pyntc.devices.iosxr_device

Module for using a Cisco IOS-XR (eXR / 64-bit) device over SSH.

This driver targets 64-bit IOS-XR (eXR) platforms (initial target: NCS5000 / NCS-5011) and implements the asynchronous OS upgrade workflow:

install add -> poll for completion -> install activate -> reload -> install commit -> verify

The driver upgrades from a single golden ISO image. A golden ISO bundles the base XR image together with the matching-version feature RPMs (IS-IS, OSPF, MPLS, multicast, etc.) into one file, so it can be added and activated on its own — eXR will not abort the activation demanding separate feature RPMs. Build a golden ISO with Cisco's gisobuild tool (https://github.com/ios-xr/gisobuild). Installing a bare base ISO plus separate feature RPMs is not supported by this driver.

pyntc.devices.iosxr_device.IOSXRDevice

Bases: BaseDevice

Cisco IOS-XR (eXR / 64-bit) Device Implementation.

boot_options property

Get the current boot image and version from show install active.

Returns:

Type	Description
dict	{"sys": <active boot package>, "version": <version>}; both values are None when the output cannot be parsed.

connected property writable

Get the connection status of the device.

Returns:

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

hostname property

Get the hostname of the device.

Returns:

Type	Description
str	The device hostname derived from the CLI prompt.

install_mode property

Indicate whether the device is operating in install mode.

eXR is always install-mode (there is no legacy boot-from-image state), so this always returns True. Provided for BaseDevice parity.

Returns:

Type	Description
bool	Always True.

os_version property

Get the running OS version from show version.

Returns:

Type	Description
str	The version string (e.g. 7.11.2), or None if unparsable.

uptime property

Get uptime from the device.

Returns:

Type	Description
int	Uptime in seconds.

uptime_string property

Get uptime in dd:hh:mm:ss format.

Returns:

Type	Description
str	Uptime of the device.

__init__(host, username, password, secret='', port=None, read_timeout_override=None, ssh_connect_attempts=DEFAULT_SSH_CONNECT_ATTEMPTS, ssh_connect_retry_delay=DEFAULT_SSH_CONNECT_RETRY_DELAY, **kwargs)

PyNTC Device implementation for Cisco IOS-XR (eXR).

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
read_timeout_override	int	If supplied, overrides all timeouts for netmiko send_command calls.	None
ssh_connect_attempts	int	Number of times to try to connect to the device before giving up. Defaults to 5.	DEFAULT_SSH_CONNECT_ATTEMPTS
ssh_connect_retry_delay	int	Number of seconds to wait between retries when ssh_connect_attempts is >1. Defaults to 15.	DEFAULT_SSH_CONNECT_RETRY_DELAY
kwargs	dict	Additional arguments to pass to the Netmiko ConnectHandler.	{}

check_file_exists(filename, file_system=None)

Check whether a file exists on the device filesystem.

Parameters:

Name	Type	Description	Default
filename	str	The filename to look for.	required
file_system	str	Filesystem to inspect. Automatically retrieves the default filesystem if not provided.	None

Returns:

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

close()

Disconnect from the device.

config(command, **netmiko_args)

Not implemented for IOS-XR.

Configuration management is out of scope for this OS-upgrade driver in the current release; only the upgrade workflow is supported.

Raises:

Type	Description
NotImplementedError	Always.

enable()

No-op for IOS-XR.

IOS-XR EXEC mode is already privileged, so there is no enable step analogous to IOS. Provided for API compatibility.

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", "sha1", "sha256" and "sha512" (default: "md5").	'md5'
file_system	str	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, **vendor_specifics)

Install a golden IOS-XR ISO and verify the device boots into it.

Orchestrates the eXR install workflow over the native primitives: install add (golden ISO) -> poll for completion -> install activate -> poll the activation operation -> wait for reboot -> install commit -> verify.

image_name must be a golden ISO that already bundles the base XR image and the matching-version feature RPMs (IS-IS, OSPF, MPLS, multicast, etc.). A bare base ISO cannot be activated on its own when feature packages are active — eXR aborts the activation demanding the matching RPMs — so build a golden ISO with Cisco's gisobuild tool (https://github.com/ios-xr/gisobuild) and stage that single file. Installing a base ISO plus separate feature RPMs is not supported.

Parameters:

Name	Type	Description	Default
image_name	str	The golden ISO filename already staged on the device.	required
reboot	bool	Must be True; activation reloads the device automatically.	True
vendor_specifics	dict	Supports timeout (default 3600) for the install-operation and reboot waits.	{}

Returns:

Type	Description
bool	True if the install ran and succeeded, False if the device was already running image_name.

Raises:

Type	Description
ValueError	When reboot is False (eXR always reloads during activation).
OSInstallError	When activation aborts or the device does not boot into image_name after install.

open(retry=True)

Open a connection to the network device.

Parameters:

Name	Type	Description	Default
retry	bool	Retry transient SSH failures (rate-limit / banner) with backoff. Defaults to True. Callers that run their own polling loop (e.g. _wait_for_device_reboot) pass False so each probe fails fast.	True

reboot(wait_for_reload=False, **kwargs)

Reboot the device.

Parameters:

Name	Type	Description	Default
wait_for_reload	bool	Whether to also run _wait_for_device_reboot. Defaults to False.	False
kwargs	dict	Additional arguments to pass to Netmiko.	{}

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

Copy a file from a remote URL onto the device filesystem.

Pulls the file specified by src from a remote server (FTP/TFTP/SCP/HTTP/HTTPS) using the IOS-XR copy command and saves it to file_system. The transfer is verified by confirming the file exists and matches the checksum after copy.

Parameters:

Name	Type	Description	Default
src	FileCopyModel	The source specification (URL, credentials, timeout).	required
dest	str	Destination filename. Defaults to src.file_name.	None
file_system	str	Target filesystem. Automatically retrieves the default filesystem if not provided.	None
kwargs	dict	Additional keyword arguments (unused).	{}

Raises:

Type	Description
TypeError	When src is not a FileCopyModel.
FileTransferError	When the transfer fails or the file does not match the checksum afterward.

save(filename=None)

Not supported on IOS-XR.

eXR software state is committed atomically by install_os (via install commit); there is no standalone save step.

Raises:

Type	Description
NotImplementedError	Always.

set_boot_options(image_name, **vendor_specifics)

Not supported on IOS-XR.

eXR has no separate set-boot step: boot selection is performed atomically by install_os via install activate + install commit.

Raises:

Type	Description
NotImplementedError	Always.

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

Run a command on the device.

IOS-XR EXEC mode is already privileged, so no enable step is performed.

Parameters:

Name	Type	Description	Default
command	str | list	Command(s) to run.	required
expect_string	str	Expected prompt string. Defaults to None.	None
netmiko_args	dict	Additional arguments passed to Netmiko's send_command.	{}

Returns:

Type	Description
str | list	Command output; a list when command is a list.

Raises:

Type	Description
CommandListError	When command is a list and one of the commands fails.

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

Verify a file on the remote device exists and its checksum matches.

Parameters:

Name	Type	Description	Default
checksum	str	The expected 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	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.