0
# Software Management
1

2
Software installation and management utilities for updating Junos software, managing software packages, performing system operations like reboots, and handling software validation and rollback operations.
3

4
## Capabilities
5

6
### Software Utility Class
7

8
The SW utility provides comprehensive software management capabilities including package installation, validation, system reboot operations, and software rollback functionality.
9

10
```python { .api }
11
class SW:
12
    def __init__(self, dev):
13
        """
14
        Initialize SW utility bound to a device.
15
        
16
        Parameters:
17
        - dev (Device): Device object to bind to
18
        """
19

20
    def install(
21
        self,
22
        package=None,
23
        remote_path='/var/tmp',
24
        progress=None,
25
        validate=False,
26
        no_copy=False,
27
        timeout=1800,
28
        cleanfs=True,
29
        no_cleanfs_check=False
30
    ):
31
        """
32
        Install software package on the device.
33
        
34
        Parameters:
35
        - package (str): Local path to software package file
36
        - remote_path (str): Remote directory for package upload
37
        - progress (callable): Progress callback function
38
        - validate (bool): Validate package before installation
39
        - no_copy (bool): Skip copying package (package already on device)
40
        - timeout (int): Installation timeout in seconds
41
        - cleanfs (bool): Clean filesystem before installation
42
        - no_cleanfs_check (bool): Skip filesystem space check
43
        
44
        Returns:
45
        - bool: True if installation successful
46
        
47
        Raises:
48
        - SwRollbackError: Installation failed and rollback occurred
49
        - RpcTimeoutError: Installation timed out
50
        - RpcError: Installation RPC error
51
        """
52

53
    def reboot(self, in_min=0, at=None):
54
        """
55
        Reboot the device.
56
        
57
        Parameters:
58
        - in_min (int): Delay before reboot in minutes
59
        - at (str): Specific time for reboot (HH:MM format)
60
        
61
        Returns:
62
        - bool: True if reboot command accepted
63
        
64
        Raises:
65
        - RpcError: Reboot command failed
66
        """
67

68
    def poweroff(self, in_min=0, at=None):
69
        """
70
        Power off the device.
71
        
72
        Parameters:
73
        - in_min (int): Delay before poweroff in minutes  
74
        - at (str): Specific time for poweroff (HH:MM format)
75
        
76
        Returns:
77
        - bool: True if poweroff command accepted
78
        
79
        Raises:
80
        - RpcError: Poweroff command failed
81
        """
82
```
83

84
### Software Package Operations
85

86
Operations for uploading, validating, and managing software packages on Junos devices.
87

88
```python { .api }
89
def put(self, local_file, remote_path='/var/tmp', progress=None):
90
    """
91
    Upload file to device using SCP.
92
    
93
    Parameters:
94
    - local_file (str): Local file path to upload
95
    - remote_path (str): Remote directory path
96
    - progress (callable): Progress callback function
97
    
98
    Returns:
99
    - bool: True if upload successful
100
    
101
    Raises:
102
    - ScpError: SCP transfer failed
103
    """
104

105
def pkgadd(self, local_file, remote_path='/var/tmp', progress=None):
106
    """
107
    Add software package to device.
108
    
109
    Parameters:
110
    - local_file (str): Local package file path
111
    - remote_path (str): Remote directory for package
112
    - progress (callable): Progress callback function
113
    
114
    Returns:
115
    - bool: True if package add successful
116
    
117
    Raises:
118
    - RpcError: Package add operation failed
119
    """
120

121
def validate(self, remote_package, timeout=300):
122
    """
123
    Validate software package on device.
124
    
125
    Parameters:
126
    - remote_package (str): Remote package file path
127
    - timeout (int): Validation timeout in seconds
128
    
129
    Returns:
130
    - bool: True if package is valid
131
    
132
    Raises:
133
    - RpcError: Package validation failed
134
    - RpcTimeoutError: Validation timed out
135
    """
136

137
def rollback(self, timeout=1800):
138
    """
139
    Rollback software installation to previous version.
140
    
141
    Parameters:
142
    - timeout (int): Rollback timeout in seconds
143
    
144
    Returns:
145
    - bool: True if rollback successful
146
    
147
    Raises:
148
    - SwRollbackError: Rollback operation failed
149
    - RpcTimeoutError: Rollback timed out
150
    """
151
```
152

153
### Software Binding
154

155
Bind the SW utility to a Device instance to enable software management operations.
156

157
```python { .api }
158
# Binding SW utility to device
159
dev.bind(sw=SW)  # 'sw' is conventional name for SW utility
160

161
# Access bound utility
162
dev.sw.install('/path/to/package.tgz')
163
dev.sw.reboot()
164
```
165

166
## Usage Examples
167

168
### Basic Software Installation
169

170
```python
171
from jnpr.junos import Device
172
from jnpr.junos.utils.sw import SW
173

174
dev = Device(host='router1.example.com', user='admin', passwd='secret')
175
dev.open()
176

177
# Bind SW utility
178
dev.bind(sw=SW)
179

180
# Install software package
181
package_path = '/home/user/junos-install-ex-4300-21.4R3.15.tgz'
182

183
try:
184
    print("Starting software installation...")
185
    result = dev.sw.install(
186
        package=package_path,
187
        validate=True,  # Validate package before installation
188
        timeout=3600    # 1 hour timeout
189
    )
190
    
191
    if result:
192
        print("Software installation completed successfully")
193
        
194
        # Reboot device to activate new software
195
        print("Rebooting device to activate new software...")
196
        dev.sw.reboot()
197
    else:
198
        print("Software installation failed")
199
        
200
except Exception as e:
201
    print(f"Installation error: {e}")
202

203
dev.close()
204
```
205

206
### Software Installation with Progress Tracking
207

208
```python
209
from jnpr.junos import Device
210
from jnpr.junos.utils.sw import SW
211

212
def progress_callback(dev, report):
213
    """Progress callback function for installation tracking."""
214
    print(f"Progress: {report}")
215

216
dev = Device(host='router1.example.com', user='admin', passwd='secret')
217
dev.open()
218
dev.bind(sw=SW)
219

220
# Install with progress tracking
221
package_path = '/home/user/junos-install-package.tgz'
222

223
dev.sw.install(
224
    package=package_path,
225
    progress=progress_callback,
226
    validate=True,
227
    cleanfs=True  # Clean filesystem before installation
228
)
229

230
dev.close()
231
```
232

233
### Package Validation
234

235
```python
236
from jnpr.junos import Device
237
from jnpr.junos.utils.sw import SW
238

239
dev = Device(host='router1.example.com', user='admin', passwd='secret')
240
dev.open()
241
dev.bind(sw=SW)
242

243
# Upload package first
244
local_package = '/home/user/software-package.tgz'
245
remote_package = '/var/tmp/software-package.tgz'
246

247
# Upload package
248
dev.sw.put(local_package, '/var/tmp/')
249

250
# Validate package before installation
251
try:
252
    is_valid = dev.sw.validate(remote_package)
253
    if is_valid:
254
        print("Package validation successful")
255
        
256
        # Install using no_copy since package is already on device
257
        dev.sw.install(
258
            package=remote_package,
259
            no_copy=True,
260
            timeout=2400  # 40 minutes
261
        )
262
    else:
263
        print("Package validation failed")
264
        
265
except Exception as e:
266
    print(f"Validation error: {e}")
267

268
dev.close()
269
```
270

271
### Scheduled Reboot
272

273
```python
274
from jnpr.junos import Device
275
from jnpr.junos.utils.sw import SW
276

277
dev = Device(host='router1.example.com', user='admin', passwd='secret')
278
dev.open()
279
dev.bind(sw=SW)
280

281
# Schedule reboot in 10 minutes
282
dev.sw.reboot(in_min=10)
283
print("Device scheduled to reboot in 10 minutes")
284

285
# Or schedule reboot at specific time
286
dev.sw.reboot(at='02:00')  # Reboot at 2:00 AM
287
print("Device scheduled to reboot at 2:00 AM")
288

289
dev.close()
290
```
291

292
### Software Rollback
293

294
```python
295
from jnpr.junos import Device
296
from jnpr.junos.utils.sw import SW
297
from jnpr.junos.exception import SwRollbackError
298

299
dev = Device(host='router1.example.com', user='admin', passwd='secret')
300
dev.open()
301
dev.bind(sw=SW)
302

303
# Check current software version
304
print(f"Current version: {dev.facts['version']}")
305

306
try:
307
    # Perform software rollback
308
    print("Starting software rollback...")
309
    result = dev.sw.rollback(timeout=3600)
310
    
311
    if result:
312
        print("Software rollback completed successfully")
313
        
314
        # Reboot to activate previous software version
315
        dev.sw.reboot()
316
    else:
317
        print("Software rollback failed")
318
        
319
except SwRollbackError as e:
320
    print(f"Rollback error: {e}")
321

322
dev.close()
323
```
324

325
### Error Handling
326

327
```python
328
from jnpr.junos import Device
329
from jnpr.junos.utils.sw import SW
330
from jnpr.junos.exception import SwRollbackError, RpcTimeoutError, RpcError
331

332
dev = Device(host='router1.example.com', user='admin', passwd='secret')
333
dev.open()
334
dev.bind(sw=SW)
335

336
package_path = '/home/user/software-package.tgz'
337

338
try:
339
    # Attempt software installation
340
    dev.sw.install(
341
        package=package_path,
342
        validate=True,
343
        timeout=3600
344
    )
345
    print("Installation successful")
346
    
347
except SwRollbackError as e:
348
    print(f"Installation failed and rollback occurred: {e}")
349
    
350
except RpcTimeoutError:
351
    print("Installation timed out")
352
    
353
except RpcError as e:
354
    print(f"Installation RPC error: {e}")
355
    
356
except FileNotFoundError:
357
    print(f"Package file not found: {package_path}")
358
    
359
except Exception as e:
360
    print(f"Unexpected error: {e}")
361

362
dev.close()
363
```
364

365
### Multiple Device Software Update
366

367
```python
368
from jnpr.junos import Device
369
from jnpr.junos.utils.sw import SW
370
import concurrent.futures
371

372
def update_device(hostname, package_path):
373
    """Update software on a single device."""
374
    try:
375
        dev = Device(host=hostname, user='admin', passwd='secret')
376
        dev.open()
377
        dev.bind(sw=SW)
378
        
379
        print(f"Updating {hostname}...")
380
        
381
        # Install software
382
        result = dev.sw.install(
383
            package=package_path,
384
            validate=True,
385
            timeout=3600
386
        )
387
        
388
        if result:
389
            print(f"{hostname}: Installation successful")
390
            dev.sw.reboot(in_min=2)  # Reboot in 2 minutes
391
            return f"{hostname}: Success"
392
        else:
393
            return f"{hostname}: Installation failed"
394
            
395
    except Exception as e:
396
        return f"{hostname}: Error - {e}"
397
    finally:
398
        if 'dev' in locals():
399
            dev.close()
400

401
# List of devices to update
402
devices = ['router1.example.com', 'router2.example.com', 'router3.example.com']
403
package_path = '/home/user/junos-software.tgz'
404

405
# Update devices in parallel
406
with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
407
    futures = [executor.submit(update_device, hostname, package_path) 
408
               for hostname in devices]
409
    
410
    for future in concurrent.futures.as_completed(futures):
411
        result = future.result()
412
        print(result)
413
```
414

415
## Types
416

417
```python { .api }
418
# Software package types
419
PackagePath = str  # Local or remote path to software package
420
RemotePath = str   # Remote directory path on device
421

422
# Progress callback type
423
ProgressCallback = callable  # Function(device, report) for progress updates
424

425
# Installation options
426
InstallOptions = dict[str, any]  # Dictionary of installation parameters
427

428
# Time format for scheduled operations
429
TimeFormat = str  # HH:MM format for scheduled operations
430

431
# Installation result
432
InstallResult = bool  # True if installation successful
433

434
# Software validation result
435
ValidationResult = bool  # True if package is valid
436
```