API Reference¶

yang.connector module¶

yang.connector module defines a set of classes that connect to Data Model Interfaces (DMI), in particular, an implementation of Netconf client by wrapping up ncclient package. Restconf implementation is coming next.

class yang.connector.Netconf(*args, **kwargs)[source]¶

Bases: ncclient.manager.Manager, pyats.connections.bases.BaseConnection

Implementation of NetConf connection to devices (NX-OS, IOS-XR or IOS-XE), based on pyATS BaseConnection and ncclient.

YAML Example:

devices:
    asr22:
        type: 'ASR'
        tacacs:
            login_prompt: "login:"
            password_prompt: "Password:"
            username: "admin"
        passwords:
            tacacs: admin
            enable: admin
            line: admin
        connections:
            a:
                protocol: telnet
                ip: "1.2.3.4"
                port: 2004
            vty:
                protocol : telnet
                ip : "2.3.4.5"
            netconf:
                class: yang.connector.Netconf
                ip : "2.3.4.5"
                port: 830
                username: admin
                password: admin

Code Example:

>>> from pyats.topology import loader
>>> testbed = loader.load('/users/xxx/xxx/asr22.yaml')
>>> device = testbed.devices['asr22']
>>> device.connect(alias='nc', via='netconf')
>>> device.nc.connected
True
>>> netconf_request = """
...     <rpc message-id="101"
...      xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
...     <get>
...     <filter>
...     <native xmlns="http://cisco.com/ns/yang/ned/ios">
...     <version>
...     </version>
...     </native>
...     </filter>
...     </get>
...     </rpc>
...     """
>>> reply = device.nc.request(netconf_request)
>>> print(reply)
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="101"><data>
<native xmlns="http://cisco.com/ns/yang/ned/ios">
<version>16.3</version></native></data></rpc-reply>
>>> device.nc.disconnect()
>>> device.nc.connected
False
>>>

timeout¶: int – Timeout value in seconds which is used by paramiko channel. By default this value is 30 seconds.

client_capabilities¶: object – Object ncclient.capabilities.Capabilities representing the client’s capabilities.

server_capabilities¶: object – Object ncclient.capabilities.Capabilities representing the server’s capabilities, and it has a list of data models the server supports.

async_mode¶: boolean – Specify whether operations are executed asynchronously (True) or synchronously (False). The default value is False.

__init__ instantiates a single connection instance.

configure(msg)[source]¶

High-level api: configure is a common method of console, vty and ssh sessions, however it is not supported by this Netconf class. This is just a placeholder in case someone mistakenly calls config method in a netconf session. An Exception is thrown out with explanation.

Parameters:	msg (`str`) – Any config CLI need to be sent out.
Raises:	`Exception` – configure is not a supported method of this Netconf class.

connect()[source]¶

High-level api: opens the NetConf connection and exchanges capabilities. Since topology YAML file is parsed by BaseConnection, the following parameters can be specified in your YAML file.

Parameters:

host (string) – Hostname or IP address to connect to.
port (int, optional) – By default port is 830, but some devices use the default SSH port of 22 so this may need to be specified.
timeout (int, optional) – An optional keyed argument to set timeout value in seconds. By default this value is 30 seconds.
username (string) – The username to use for SSH authentication.
password (string) – The password used if using password authentication, or the passphrase to use for unlocking keys that require it.
key_filename (string) – a filename where a the private key to be used can be found.
allow_agent (boolean) – Enables querying SSH agent (if found) for keys. The default value is True.
hostkey_verify (boolean) – Enables hostkey verification from ~/.ssh/known_hosts. The default value is False.
look_for_keys (boolean) – Enables looking in the usual locations for ssh keys (e.g. ~/.ssh/id_*). The default value is True.
ssh_config (string) – Enables parsing of an OpenSSH configuration file, if set to its path, e.g. ~/.ssh/config or to True. If the value is True, ncclient uses ~/.ssh/config. The default value is None.

Raises:

Exception – If the YAML file does not have correct connections section, or establishing transport to ip:port is failed, ssh authentication is failed, or other transport failures.

Note

There is no return from this method. If something goes wrong, an exception will be raised.

YAML Example:

devices:
    asr22:
        type: 'ASR'
        tacacs:
            login_prompt: "login:"
            password_prompt: "Password:"
            username: "admin"
        passwords:
            tacacs: admin
            enable: admin
            line: admin
        connections:
            a:
                protocol: telnet
                ip: "1.2.3.4"
                port: 2004
            vty:
                protocol : telnet
                ip : "2.3.4.5"
            netconf:
                class: yang.connector.Netconf
                ip : "2.3.4.5"
                port: 830
                username: admin
                password: admin

Code Example:

>>> from pyats.topology import loader
>>> testbed = loader.load('/users/xxx/xxx/asr22.yaml')
>>> device = testbed.devices['asr22']
>>> device.connect(alias='nc', via='netconf')
>>>

Expected Results:

>>> device.nc.connected
True
>>> for iter in device.nc.server_capabilities:
...     print(iter)
...
urn:ietf:params:xml:ns:yang:smiv2:RFC-1215?module=RFC-1215
urn:ietf:params:xml:ns:yang:smiv2:SNMPv2-TC?module=SNMPv2-TC
...
>>>

disconnect()[source]¶: High-level api: closes the NetConf connection.

execute(operation, *args, **kwargs)[source]¶: High-level api: The fact that most connection classes implement execute method lead us to add this method here as well. Supported operations are get, get_config, get_schema, dispatch, edit_config, copy_config, validate, commit, discard_changes, delete_config, lock, unlock, close_session, kill_session, poweroff_machine and reboot_machine. Refer to ncclient document for more details.

request(msg, timeout=30)[source]¶

High-level api: sends message through NetConf session and returns with a reply. Exception is thrown out either the reply is in wrong format or timout. Users can modify timeout value (in seconds) by passing parameter timeout. Users may want to set a larger timeout when making a large query.

Parameters:	msg (`str`) – Any message need to be sent out in XML format. The message can be in wrong format if it is a negative test case. Because ncclient tracks same message-id in both rpc and rpc-reply, missing message-id in your rpc may cause exception when receiving rpc-reply. Most other wrong format rpc’s can be sent without exception. timeout (`int`, optional) – An optional keyed argument to set timeout value in seconds. Its default value is 30 seconds.
Returns:	The reply from the device in string. If something goes wrong, an exception will be raised.
Return type:	str
Raises:	`Exception` – If NetConf is not connected, or there is a timeout when receiving reply.

Code Example:

>>> from pyats.topology import loader
>>> testbed = loader.load('/users/xxx/xxx/asr_20_22.yaml')
>>> device = testbed.devices['asr22']
>>> device.connect(alias='nc', via='netconf')
>>> netconf_request = """
...     <rpc message-id="101"
...      xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
...     <get>
...     <filter>
...     <native xmlns="http://cisco.com/ns/yang/ned/ios">
...     <version>
...     </version>
...     </native>
...     </filter>
...     </get>
...     </rpc>
...     """
>>> reply = device.nc.request(netconf_request)
>>>

Expected Results:

>>> print(reply)
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="101"><data>
<native xmlns="http://cisco.com/ns/yang/ned/ios">
<version>16.3</version></native></data></rpc-reply>
>>>

session¶

High-level api – return the SSH session object.

Returns:	The SSH session that was created by ncclient.transport.SSHSession.
Return type:	object

class yang.connector.RawRPC(session, device_handler, async_mode=False, timeout=30, raise_mode=0)[source]¶

Bases: ncclient.operations.rpc.RPC

A modified ncclient.operations.rpc.RPC class. This is for internal use only.

session is the Session instance

device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

async specifies whether the request is to be made asynchronously, see is_async

timeout is the timeout for a synchronous request, see timeout

raise_mode specifies the exception raising mode, see raise_mode