`pyntc.devices.ios_device` ¶

Module for using a Cisco IOS device over SSH.

`pyntc.devices.ios_device.IOSDevice` ¶

Bases: BaseDevice

Cisco IOS Device Implementation.

`boot_options` `property` ¶

Get current boot image.

Returns:

Type	Description
`dict`	Key `sys` with value being the current boot image.

`config_register` `property` ¶

Get config register of device.

Returns:

Type	Description
`str`	Config register.

`connected` `property` `writable` ¶

Get connection status of the device.

Returns:

Type	Description
`bool`	True if the device is connected, else False.

`fqdn` `property` ¶

Get fully qualified domain name.

Returns:

Type	Description
`str`	Fully qualified domain name or `N/A` if not defined.

`hostname` `property` ¶

Get hostname of device.

Returns:

Type	Description
`str`	Hostname of device.

`install_mode` `property` ¶

Return whether the device is currently booted in install mode.

Returns:

Type	Description
`bool`	True when the current boot image equals :data:`INSTALL_MODE_FILE_NAME` (i.e., `packages.conf`), False otherwise.

`interfaces` `property` ¶

Get list of interfaces on device.

Returns:

Type	Description
`list`	List of interfaces on device.

`model` `property` ¶

Get the device model.

Returns:

Type	Description
`str`	Device model.

`os_version` `property` ¶

Get os version on device.

Returns:

Type	Description
`str`	OS version on device.

`peer_redundancy_state` `property` ¶

Determine the current redundancy state of the peer processor.

Returns:

Type	Description
`str`	The redundancy state of the peer processor.
`None`	When the processor does not support redundancy.

Example

device = IOSDevice(**connection_args) device.peer_redundancy_state 'standby hot'

`redundancy_mode` `property` ¶

Get operating redundancy mode of the device.

Returns:

Type	Description
`str`	The redundancy mode the device is operating in. If the command is not supported, then "n/a" is returned.

Example

device = IOSDevice(**connection_args) device.redundancy_mode 'stateful switchover'

`redundancy_state` `property` ¶

Determine the current redundancy state of the processor.

Returns:

Type	Description
`str`	The redundancy state of the current processor.
`None`	When the processor does not support redundancy.

Example

device = IOSDevice(**connection_args) device.redundancy_state 'active'

`running_config` `property` ¶

Get running configuration.

Returns:

Type	Description
`str`	Output of `show running-config`.

`serial_number` `property` ¶

Get serial number of device.

Returns:

Type	Description
`str`	Serial number of device.

`startup_config` `property` ¶

Get startup configuration.

Returns:

Type	Description
`str`	Startup configuration from device.

`uptime` `property` ¶

Get uptime from device.

Returns:

Type	Description
`int`	Uptime in seconds.

`uptime_string` `property` ¶

Get uptime in format dd:hh:mm.

Returns:

Type	Description
`str`	Uptime of device.

`vlans` `property` ¶

Get list of VLANs on device.

Returns:

Type	Description
`list`	List of VLANs on device.

`init(host, username, password, secret='', port=None, confirm_active=True, **kwargs)` ¶

PyNTC Device implementation for Cisco IOS.

Parameters:

Name	Type	Description	Default
`host`	`str`	The address of the network device.	required
`username`	`str`	The username to authenticate with the device.	required
`password`	`str`	The password to authenticate with the device.	required
`secret`	`str`	The password to escalate privilege on the device.	`''`
`port`	`int`	The port to use to establish the connection. Defaults to 22.	`None`
`confirm_active`	`bool`	Determines if device's high availability state should be validated before leaving connection open.	`True`
`kwargs`	`dict`	Additional arguments to pass to the Netmiko ConnectHandler.	`{}`

`backup_running_config(filename)` ¶

Backup running configuration to filename specified.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename to save running configuration to.	required

`check_file_exists(filename, file_system=None)` ¶

Check if a remote file exists by filename.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The name of the file to check for on the remote device.	required
`file_system`	`str`	Supported only for IOS and NXOS. The file system for the remote file. If no file_system is provided, then the `get_file_system` method is used to determine the correct file system to use.	`None`

Returns:

Type	Description
`bool`	True if the remote file exists, False if it doesn't.

Raises:

Type	Description
`CommandError`	If there is an error in executing the command to check if the file exists.

`checkpoint(checkpoint_file)` ¶

Create checkpoint file.

Parameters:

Name	Type	Description	Default
`checkpoint_file`	`str`	Name of checkpoint file.	required

`close()` ¶

Disconnect from device.

`config(command, **netmiko_args)` ¶

Send config commands to device.

By default, entering and exiting config mode is handled automatically. To disable entering and exiting config mode, pass enter_config_mode and exit_config_mode in **netmiko_args. This supports all arguments supported by Netmiko's send_config_set method using netmiko_args. This will send each command in command until either an Error is caught or all commands have been sent.

Parameters:

Name	Type	Description	Default
`command`	`str \| list`	The command or commands to send to the device.	required
`**netmiko_args`	`dict`	Any argument supported by `netmiko.ConnectHandler.send_config_set`.	`{}`

Returns:

Type	Description
`str`	When `command` is a str, the config session input and output from sending `command`.
`list`	When `command` is a list, the config session input and output from sending `command`.

Raises:

Type	Description
`TypeError`	When sending an argument in `**netmiko_args` that is not supported.
`CommandError`	When `command` is a str and its results report an error.
`CommandListError`	When `command` is a list and one of the commands reports an error.

Example

device = IOSDevice(**connection_args) device.config("no service pad") 'configure terminal\nEnter configuration commands, one per line. End with CNTL/Z.\n' 'host(config)#no service pad\nhost(config)#end\nhost#' device.config(["interface Gig0/1", "description x-connect"]) ['host(config)#interface Gig0/1\nhost(config-if)#, 'description x-connect\nhost(config-if)#']

`confirm_is_active()` ¶

Confirm that the device is either standalone or the active device in a high availability cluster.

Returns:

Type	Description
`bool`	True when the device is considered active.

Rasies

DeviceNotActiveError: When the device is not considered the active device.

Example

device = IOSDevice(**connection_args) device.redundancy_state 'standby hot' device.confirm_is_active() raised DeviceNotActiveError: host1 is not the active device.

device state: standby hot peer state: active

device.redundancy_state 'active' device.confirm_is_active() True

`enable()` ¶

Ensure device is in enable mode.

Returns:

Type	Description
`None`	Device prompt is set to enable mode.

`file_copy(src, dest=None, file_system=None)` ¶

Copy file to device.

Parameters:

Name	Type	Description	Default
`src`	`str`	Source of file.	required
`dest`	`str`	Destination name for file. Defaults to None.	`None`
`file_system`	`str`	File system to copy file to. Defaults to None.	`None`

Raises:

Type	Description
`SocketClosedError`	Error raised if connection to device is closed.
`FileTransferError`	Error in transferring file.
`FileTransferError`	Error if unable to verify file was transferred successfully.

`file_copy_remote_exists(src, dest=None, file_system=None)` ¶

Check if file exists on remote device.

Parameters:

Name	Type	Description	Default
`src`	`str`	Source of file.	required
`dest`	`str`	Destination name for file. Defaults to None.	`None`
`file_system`	`str`	File system to copy file to. Defaults to None.	`None`

Returns:

Type	Description
`bool`	True if file copied succesfully and md5 hashes match. Otherwise, false.

`get_remote_checksum(filename, hashing_algorithm='md5', file_system=None)` ¶

Get the checksum of a remote file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The name of the file to check for on the remote device.	required
`hashing_algorithm`	`str`	The hashing algorithm to use. Valid choices are "md5" and "sha512" (default: "md5").	`'md5'`
`file_system`	`str`	Supported only for IOS and NXOS. The file system for the remote file. If no file_system is provided, then the `get_file_system` method is used to determine the correct file system to use.	`None`

Returns:

Type	Description
`str`	The checksum of the remote file.

Raises:

Type	Description
`ValueError`	If an unsupported hashing algorithm is provided.
`CommandError`	If there is an error in executing the command to get the remote checksum.

`install_os(image_name, reboot=True, install_mode=None, read_timeout=2000, **vendor_specifics)` ¶

Installs the prescribed Network OS, which must be present before issuing this command.

Parameters:

Name	Type	Description	Default
`image_name`	`str`	Name of the IOS image to boot into	required
`reboot`	`bool`	Whether to reboot the device after setting the boot options. Defaults to true.	`True`
`install_mode`	`bool`	Deprecated. Whether to use the newer install-mode upgrade procedure. When omitted (the default), the value is derived from :attr:`install_mode`, which reads the device's current boot configuration. Passing the argument explicitly still works but emits a `DeprecationWarning` and will be removed in a future release.	`None`
`read_timeout`	`int`	Netmiko timeout when waiting for device prompt. Default 2000.	`2000`
`vendor_specifics`	`dict`	Vendor specific arguments to pass to the install command.	`{}`

Raises:

Type	Description
`OSInstallError`	Unable to install OS Error type

Returns:

Type	Description
`bool`	False if no install is needed, true if the install completes successfully

`is_active()` ¶

Determine if the current processor is the active processor.

Returns:

Type	Description
`bool`	True if the processor is active or does not support HA, else False.

Example

device = IOSDevice(**connection_args) device.is_active() True

`open(confirm_active=True)` ¶

Open a connection to the network device.

This method will close the connection if confirm_active is True and the device is not active. Devices that do not have high availability are considered active.

Parameters:

Name	Type	Description	Default
`confirm_active`	`bool`	Determines if device's high availability state should be validated before leaving connection open.	`True`

Raises:

Type	Description
`DeviceNotActiveError`	When `confirm_active` is True, and the device high availability state is not active.

Example

device = IOSDevice(**connection_args) device.open() raised DeviceNotActiveError: host1 is not the active device.

device state: standby hot peer state: active

device.open(confirm_active=False) device.connected True

`reboot(wait_for_reload=False, **kwargs)` ¶

Reboot device.

Reload the controller or controller pair.

Parameters:

Name	Type	Description	Default
`wait_for_reload`	`bool`	Whether or not reboot method should also run _wait_for_device_reboot(). Defaults to False.	`False`
`kwargs`	`dict`	Additional arguments to pass to the Netmiko.	`{}`

Raises:

Type	Description
`ReloadTimeoutError`	When the device is still unreachable after the timeout period.

`remote_file_copy(src, dest=None, file_system=None, **kwargs)` ¶

Copy a file to a remote device.

Parameters:

Name	Type	Description	Default
`src`	`FileCopyModel`	The source file model.	required
`dest`	`str`	The destination file path on the remote device.	`None`
`kwargs`	`dict`	Additional keyword arguments that may be used by subclasses.	`{}`

Other Parameters:

Name	Type	Description
`file_system`	`str`	Supported only for IOS and NXOS. The file system for the remote file. If no file_system is provided, then the `get_file_system` method is used to determine the correct file system to use.

Raises:

Type	Description
`TypeError`	If src is not an instance of FileCopyModel.
`FileTransferError`	If there is an error during file transfer or if the file cannot be verified after transfer.

`rollback(rollback_to)` ¶

Rollback configuration to file on flash.

Parameters:

Name	Type	Description	Default
`rollback_to`	`sEtr`	Name of the file to rollback to.	required

Raises:

Type	Description
`RollbackError`	Error if unable to rollback to configuration.

`save(filename='startup-config')` ¶

Save running configuration.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Name of file to save running configuration. Defaults to "startup-config".	`'startup-config'`

Returns:

Type	Description
`bool`	True if save is succesfull.

`set_boot_options(image_name, **vendor_specifics)` ¶

Set specified image as boot image.

Parameters:

Name	Type	Description	Default
`image_name`	`str`	Name of image to set as boot variable.	required
`vendor_specifics`	`dict`	Vendor specific arguments to pass to the set_boot_options command.	`{}`

Raises:

Type	Description
`NTCFileNotFoundError`	Error if file is not found on device.
`CommandError`	Error if setting new image as boot variable fails.

`show(command, expect_string=None, **netmiko_args)` ¶

Run command on device.

Parameters:

Name	Type	Description	Default
`command`	`str`	Command to be ran.	required
`expect_string`	`str`	Expected string from command output. Defaults to None.	`None`
`netmiko_args`	`dict`	Additional arguments to pass to Netmiko's send_command method.	`{}`

Returns:

Type	Description
`str`	Output of command.

`verify_file(checksum, filename, hashing_algorithm='md5', file_system=None)` ¶

Verify a file on the remote device by and validate the checksums.

Parameters:

Name	Type	Description	Default
`checksum`	`str`	The checksum of the file.	required
`filename`	`str`	The name of the file to check for on the remote device.	required
`hashing_algorithm`	`str`	The hashing algorithm to use (default: "md5").	`'md5'`
`file_system`	`str`	Supported only for IOS and NXOS. The file system for the remote file. If no file_system is provided, then the `get_file_system` method is used to determine the correct file system to use.	`None`

Returns:

Type	Description
`bool`	True if the file is verified successfully, False otherwise.