plugins¶

module contents¶

File utils common base class

class genie.libs.filetransferutils.plugins.fileutils.FileUtils¶

Bases: genie.libs.filetransferutils.fileutils.FileUtils

Initialize an instance of FileUtils

Parameters:	os (`str`) – The operating system of the device acting as a file transfer client. testbed (`pyats.topology.Testbed`) – The testbed object that contains auth and address details for servers referenced by file transfer URLs.

copyfile(source, destination, timeout_seconds, cmd, used_server, *args, **kwargs)¶

Copy a file to/from NXOS device

Copy any file to/from a device to any location supported on the device and on the running-configuration.

Parameters:	source (`str`) – Full path to the copy ‘from’ location destination (`str`) – Full path to the copy ‘to’ location timeout_seconds (`str`) – The number of seconds to wait before aborting the operation cmd (`str`) – Command to be executed on the device used_server (`str`) – Server address/name
Returns:
Return type:	`None`
Raises:	`Exception` – When a device object is not present or device execution encountered an unexpected behavior.

Examples

# FileUtils >>> from ats.utils.fileutils import FileUtils

# Instanciate a filetransferutils instance for NXOS device >>> fu_device = FileUtils.from_device(device)

# copy file from device to server >>> fu_device.copyfile( … source=’flash:/memleak.tcl’, … destination=’ftp://10.1.0.213//auto/tftp-ssr/memleak.tcl’, … timeout_seconds=’300’, device=device)

# copy file from server to device >>> fu_device.copyfile( … source=’ftp://10.1.0.213//auto/tftp-ssr/memleak.tcl’, … destination=’flash:/new_file.tcl’, … timeout_seconds=’300’, device=device)

# copy file from server to device running configuration >>> fu_device.copyfile( … source=’ftp://10.1.0.213//auto/tftp-ssr/memleak.tcl’, … destination=’running-config’, … timeout_seconds=’300’, device=device)

parsed_dir(target, timeout_seconds, dir_output, *args, **kwargs)¶

Retrieve filenames contained in a directory.

Do not recurse into subdirectories, only list files at the top level of the given directory.

Parameters:	target (`str`) – The directory whose details are to be retrieved. timeout_seconds (`int`) – The number of seconds to wait before aborting the operation. dir_output (`obj`) – The OS corresponding `dir` parser object
Returns:	`dict`
Return type:	Dict of filename URLs and the corresponding info (ex:size)
Raises:	`AttributeError` – device object not passed in the function call `Exception` – Parser encountered an issue

Examples

# FileUtils >>> from ats.utils.fileutils import FileUtils

# Instanciate a filetransferutils instance for NXOS device >>> fu_device = FileUtils.from_device(device)

# list all files on the device directory ‘flash:’ >>> directory_output = fu_device.dir(target=’flash:’, … timeout_seconds=300, device=device)

>>> directory_output['dir']['flash:/']['files']
...     (Pdb) directory_output['dir']['flash:/']['files']['boothelper.log']
        {'index': '69699', 'permissions': '-rw-', 'size': '76',
        'last_modified_date': 'Mar 20 2018 10:25:46 +00:00'}

stat(target, timeout_seconds, dir_output, *args, **kwargs)¶

Retrieve file details such as length and permissions.

Parameters:	target (`str`) – The URL of the file whose details are to be retrieved. timeout_seconds (`int`) – The number of seconds to wait before aborting the operation. dir_output (`obj`) – The OS corresponding `dir` parser object
Returns:	`file_details` – and last modified date.
Return type:	File details including size, permissions, index
Raises:	`AttributeError` – device object not passed in the function call `Exception` – Parser encountered an issue

Examples

# FileUtils >>> from ats.utils.fileutils import FileUtils

# Instanciate a filetransferutils instance for NXOS device >>> fu_device = FileUtils.from_device(device)

# list the file details on the device ‘flash:’ directory >>> directory_output = fu_device.stat(target=’flash:memleak.tcl’, … timeout_seconds=300, device=device)

>>> directory_output['size']
...     '104260'
>>> directory_output['permissions']
...     '-rw-'

deletefile(target, timeout_seconds, *args, **kwargs)¶

Delete a file

Parameters:	target (`str`) – The URL of the file whose details are to be retrieved. timeout_seconds (`int`) – The number of seconds to wait before aborting the operation.
Returns:
Return type:	None
Raises:	`Exception` – When a device object is not present or device execution encountered an unexpected behavior.

Examples

# FileUtils >>> from ats.utils.fileutils import FileUtils

# Instanciate a filetransferutils instance for NXOS device >>> fu_device = FileUtils.from_device(device)

# delete a specific file on device directory ‘flash:’ >>> directory_output = fu_device.deletefile( … target=’flash:memleak_bckp.tcl’, … timeout_seconds=300, device=device)

renamefile(source, destination, timeout_seconds, cmd, *args, **kwargs)¶

Rename a file

Parameters:	source (`str`) – The URL of the file to be renamed. destination (`str`) – The URL of the new file name. timeout_seconds (`int`) – Maximum allowed amount of time for the operation.
Returns:
Return type:	None
Raises:	`Exception` – When a device object is not present or device execution encountered an unexpected behavior.

Examples

# FileUtils >>> from ats.utils.fileutils import FileUtils

# Instanciate a filetransferutils instance for NXOS device >>> fu_device = FileUtils.from_device(device)

# rename the file on the device ‘flash:’ directory >>> fu_device.renamefile(target=’flash:memleak.tcl’, … destination=’memleak_backup.tcl’ … timeout_seconds=300, device=device)

chmod(target, mode, timeout_seconds, *args, **kwargs)¶

Change file permissions

Parameters:	target (`str`) – The URL of the file whose permissions are to be changed. mode (`int`) – Same format as `os.chmod`. timeout_seconds (`int`) – Maximum allowed amount of time for the operation.
Returns:
Return type:	`None` if operation succeeded.

validateserver(cmd, target, timeout_seconds=300, *args, **kwargs)¶

Make sure that the given server information is valid

Function that verifies if the server information given is valid, and if the device can connect to it. It does this by saving show clock output to a particular file using transfer protocol. Then deletes the file.

Parameters:	(str) (target) – (str) – file location. timeout_seconds (`str`) – The number of seconds to wait before aborting the operation. Default is 300
Returns:
Return type:	`None`
Raises:	Exception: If the command from the device to server is unreachable – or the protocol used doesn’t support remote checks.

Examples

# FileUtils >>> from ats.utils.fileutils import FileUtils

# Instanciate a filetransferutils instance for NXOS device >>> fu_device = FileUtils.from_device(device)

# Validate server connectivity >>> fu_device.validateserver( … target=’ftp://10.1.7.250//auto/tftp-ssr/show_clock’, … timeout_seconds=300, device=device)

copyconfiguration(source, destination, cmd, used_server, timeout_seconds=300, *args, **kwargs)¶

Copy configuration to/from device

Copy configuration on the device or between locations supported on the device and on the server.

Parameters:	source (`str`) – Full path to the copy ‘from’ location destination (`str`) – Full path to the copy ‘to’ location timeout_seconds (`str`) – The number of seconds to wait before aborting the operation vrf (`str`) – Vrf to be used during copy operation
Returns:
Return type:	`None`
Raises:	`Exception` – When a device object is not present or device execution encountered an unexpected behavior.

Examples

# FileUtils >>> from ats.utils.fileutils import FileUtils

# Instantiate a filetransferutils instance for NXOS device >>> from ats.utils.fileutils import FileUtils >>> fu_device = FileUtils.from_device(device)

# copy file from server to device running configuration >>> fu_device.copyconfiguration( … source=’ftp://10.1.0.213//auto/tftp-ssr/config.py’, … destination=’running-config’, … timeout_seconds=’300’, device=device)

# copy running-configuration to device memory >>> fu_device.copyconfiguration( … from_file_url=’running-config’, … to_file_url=’bootflash:filename’, … timeout_seconds=’300’, device=device)

# copy startup-configuration running-configuration >>> fu_device.copyconfiguration( … from_file_url=’startup-config’, … to_file_url=’running-config’, … timeout_seconds=’300’, device=device)

checkfile¶

Check for file existence and (optionally) stability.

Parameters:	target (`str`) – The URL of the file whose details are to be retrieved. max_tries (`int`) – Stat is run this many times at maximum delay_seconds (`int`) – Delay this many seconds between tries. check_stability (`bool`) – If `True`, up to the max possible tries are executed and the file length is monitored. If at least two consecutive equal file lengths are seen then the file is deemed stable. timeout_seconds (`int`) – The number of seconds for each underlying stat call to wait before the stat is considered aborted. NOTE: If retries remain, an aborted stat still leads to delay/retry and does not necessarily lead to an exception being raised.
Returns:
Return type:	`None` if the file check succeeded
Raises:	`Exception` – check_stability is specified as True but the file length is not stable. `Exception` – timeout exceeded

close¶: Deallocate any resources being held.

dir¶

Retrieve filenames contained in a directory.

Do not recurse into subdirectories, only list files at the top level of the given directory.

Parameters:	target (`str`) – The URL of the directory whose contained files are to be retrieved. timeout_seconds (`int`) – The number of seconds to wait before aborting the operation.
Returns:	`list`
Return type:	List of filename URLs. Directory names are ignored.

classmethod from_device(device, *args, testbed=None, **kwargs)¶

Instantiate a fileutils object from a device object.

Parameters:

device (pyats.topology.device.Device) – The device against which file client operations are to be executed. This device must have its os member set. If device.testbed is set, this testbed object is used to authenticate file client operations, even if the testbed argument is specified.
testbed (pyats.topology.testbed.Testbed) – The testbed object used to authenticate file client operations. If device.testbed is set, this parameter, even if specified, is ignored.

get_auth¶

Get authentication details.

If credentials

Returns:	username, password Each element in this tuple is returned as `None` if not found in the testbed.
Raises:	`Exception` – if auth details not found in testbed.

get_child¶

Get a child FileUtils object under the current OS given a key.

Returns:	FileUtils object under the current OS plugin. If the object does not exist in the cache, it is created, otherwise it is returned from the cache. The object may be removed from the cache via the remove_child API.

Example

>>> from pyats.utils import FileUtils
>>> fu_linux = FileUtils(os='linux')
>>> fu_linux_ftp = fu_linux.get_child('ftp')
>>> assert(fu_linux_ftp.parent is fu_linux)

get_hostname(server_name_or_ip, device, vrf=None, cache_ip=True)¶

Get host name or address to connect to.: (inherited from pyats FileUtils with support for device connection)

Returns:

DNS name or IP address of server to connect to.
If IP address (single or list) specified in server block
Return first reachable address (plugin determines reachability).
If no address specified, or if no address reachable
Server name, if specified in server block, is next preferred.
If neither address nor server keys are present in server block,
or if the server could not be found in the testbed,
return the user-specified server name or IP address.

Raises: Exception – if server details not found in testbed.

get_protocol¶: Returns the url scheme (protocol).

get_server(source, destination=None)¶

Get the server address from the provided URLs

Parameters:	source (`str`) – URL path of the from location destination (`str`) – URL path of the to location
Returns:	used_server – String of the used server
Return type:	`str`
Raises:	`None`

Examples

# FileUtils >>> from ..fileutils import FileUtils

# Get the server

>>> output = FileUtils.get_server(source, destination)

>>> output
...   '10.1.7.250'

get_server_block¶

Return the required server block from the testbed if it exists.

Parameters:	server_name_or_ip (`str`) – The name or IP address of the server
Returns:	`dict`
Return type:	Server block if found, empty dict if not found.

is_local¶: Returns True if the url refers to a local resource.

is_remote¶: Returns True if the url refers to a remote resource.

is_valid_ip(ip, device, vrf=None, cache_ip=True)¶

is_valid_ip_cache¶

is_valid_ip_no_cache(ip, device, vrf=None)¶

parent¶: Find the os-specific parent of a protocol-specific plugin.

parse_url(url)¶

Parse the given url

Parameters:	url (`str`) – Full url to be parsed
Returns:	ParseResult class with the following keyword arguments (scheme=’’, netloc=’’, path=’’, params=’’, query=’’, fragment=’’)
Raises:	`None`

Examples

# FileUtils >>> from ..fileutils import FileUtils

# Parse the URL

>>> output = FileUtils.parse_url(file_url)
        ParseResult(scheme='flash', netloc='', path='memleak.tcl',
        params='', query='', fragment='')

>>> output.scheme
...   'flash'

>>> output.path
...   'memleak.tcl'

remove_child¶

Removes a child (protocol-specific) implementation from the cache.

This method is to be called on the parent (os-specific).

First, any resources held by the current child are deallocated.

Then, the current child is removed from the cache so the next call to get_child causes a brand new child to be allocated.

The child is then deleted.

send_cli_to_device(cli, used_server=None, invalid=None, timeout_seconds=300, **kwargs)¶

Send command to a particular device and deal with its result

Parameters:	cli (`str`) – Full command to be executed on the device invalid (`str`) – Any invalid patterns need to be caught during execution timeout_seconds (`str`) – The number of seconds to wait before aborting the operation. used_server (`str`) – Server address/name
Returns:
Return type:	`None`
Raises:	`Exception` – When a device object is not present or device execution encountered an unexpected behavior. `ValueError` – When a device execution output shows one of the invalid patterns.

Examples

# FileUtils >>> from ..fileutils import FileUtils

# copy flash:/memleak.tcl ftp://10.1.0.213//auto/tftp-ssr/memleak.tcl >>> cmd = ‘copy {f} {t}’.format(f=source, t=destination)
>>> FileUtils.send_cli_to_device(cli=cmd,
...   timeout_seconds=timeout_seconds, **kwargs)

validate_and_update_url(url, device, vrf=None, cache_ip=True)¶: Validate the url and replace the hostname/address with a reachable address from the testbed