pyntc.devices.ios_device

Module for using a Cisco IOS device over SSH.

pyntc.devices.ios_device.HideUrlCredentials

Hide a copy URL password from pyntc and netmiko log records.

FTP, HTTP and HTTPS carry the password in the copy command itself, so it reaches netmiko's channel logging, netmiko's session log, and the device output this module logs. Netmiko's SecretsFilter rewrites the message of each record logged through the logger it is attached to, so one filter goes on the pyntc logger, and the token joins the mapping the connection's own filter and session log share.

__enter__()

Add a SecretsFilter to the pyntc logger and the secrets to netmiko's mapping.

The pyntc filter covers the messages logged here. The netmiko mapping is the one its own SecretsFilter and its SessionLog read from, so writing the secrets there covers the copy command as netmiko sends it.

Returns:

Type	Description
HideUrlCredentials	This instance.

__exit__(exc_type, exc_value, traceback)

Unregister the secrets.

Returns:

Type	Description
bool	False, so an exception is never suppressed.

__init__(native, secrets)

Capture the registries the secrets are added to and removed from.

Parameters:

Name	Type	Description	Default
native	BaseConnection	The netmiko connection whose no_log mapping the secrets join.	required
secrets	dict	Values to hide, keyed by the name each takes in netmiko's no_log mapping. An empty mapping is a no-op.	required

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, read_timeout=900)

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
read_timeout	int	Maximum time in seconds to wait for the checksum command to complete. Hashing large files can take several minutes (default: 900).	900

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, read_timeout=900)

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
read_timeout	int	Maximum time in seconds to wait for the checksum command to complete. Hashing large files can take several minutes (default: 900).	900

Returns:

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

pyntc.devices.ios_device.RebootSignal

Bases: NTCError

RebootSignal.