Connecting to Devices Running Junos OS Using Junos PyEZ

 

Junos PyEZ is a microframework for Python that enables you to manage devices running Junos OS. Junos PyEZ models each device as an instance of the jnpr.junos.device.Device class. The Device class enables you to connect to a device running Junos OS using a serial console connection, telnet, or by establishing a NETCONF session over SSH. In addition, Junos PyEZ also supports connecting to the device through a telnet or SSH connection to a console server. A console server, also known as a terminal server, is a specialized device that provides a network connection to a device’s out-of-band management console port.

This topic provides an overview of the connection methods supported by Junos PyEZ and explains how to use the different methods to connect to a device running Junos OS. The Junos PyEZ examples use various authentication methods, but for detailed information about authenticating a user, see Authenticating Junos PyEZ Users.

Connection Methods Overview

Junos PyEZ enables you to connect to devices running Junos OS using a serial console connection, telnet, or a NETCONF session over SSH. You must use a serial console connection when you are physically connected to the CONSOLE port on a device. You can use telnet or SSH to connect to the device’s management interface or to a console server that is connected to the device’s CONSOLE port. In addition, Junos PyEZ supports outbound SSH connections, in which the device running Junos OS initiates the connection with the client management application.

New or zeroized devices that have factory default configurations require access through a console connection. Thus, you can use Junos PyEZ to initially configure a device that is not yet configured for remote access by using either a serial console connection when you are directly connected to the device or by using telnet or SSH through a console server that is connected to the device.

By default, Junos PyEZ uses SSH to connect to a device . To specify a different connection type, you must include the mode parameter in the Device argument list. To telnet to a device, include the mode='telnet' argument. To connect to a device using a serial console connection, include the mode='serial' argument. Table 1 summarizes the Junos PyEZ connection methods, their default values for certain parameters, any required Junos OS configuration, and the Junos PyEZ release in which support for that connection method was first introduced.

Table 1: Junos PyEZ Connection Modes

Connection Mode

Value of mode Argument

Default Port

Required Junos OS Configuration

First Supported Junos PyEZ Release

NETCONF over SSH (default)

830

[edit system services]
netconf {
ssh;
}

1.0.0

Serial console connection

serial

/dev/ttyUSB0

2.0.0

Telnet to device running Junos OS

telnet

23

[edit system services]
telnet;

2.0.0

Telnet through a console server

telnet

23

2.0.0

SSH through a console server

22

2.2.0

Outbound SSH

[edit system services]
outbound-ssh {
...
}

2.2.0

Note

Before you can access a device’s management interface using telnet or NETCONF over SSH, you must first enable the appropriate service at the [edit system services] hierarchy. For more information, see Setting Up Junos PyEZ Managed Nodes. Because telnet uses clear-text passwords (therefore creating a potential security vulnerability), we recommend that you use SSH.

Note

It is the user's responsibility to obtain the username and password authentication credentials in a secure manner appropriate for their environment. It is best practice to prompt for these authentication credentials during each invocation of the script, rather than storing the credentials in an unencrypted format.

Junos PyEZ supports using context managers (with ... as syntax) for all connection methods. When you use a context manager, Junos PyEZ automatically calls the open() and close() methods to connect to and disconnect from the device. If you do not use a context manager, you must explicitly call the open() and close() methods in your application. We recommend that you use a context manager for console connections, because the context manager automatically handles closing the connection, and failure to close the connection can lead to unpredictable results.

Understanding Junos PyEZ Connection Properties

When you connect to a device running Junos OS, Junos PyEZ stores information about the current connection as properties of the Device instance. Table 2 outlines the available connection properties.

Table 2: Device Properties

Property

Description

connected

Boolean specifying the current state of the connection. Returns True when connected.

hostname

String specifying the hostname of the device to which the application is connected.

master

Boolean returning True if the Routing Engine to which the application is connected is the master Routing Engine.

port

Integer or string specifying the port used for the connection.

re_name

String specifying the Routing Engine name to which the application is connected.

timeout

Integer specifying the RPC timeout value in seconds.

uptime

Integer representing the number of seconds since the current Routing Engine was booted. This property is available starting in Junos PyEZ Release 2.1.5.

user

String specifying the user accessing the device running Junos OS.

For example, after connecting to a device, you can query the connected property to return the current state of the connection. A SessionListener monitors the session and responds to transport errors by raising a TransportError exception and setting the Device.connected property to False.

The following sample code prints the value of the connected property after connecting to a device running Junos OS and again after closing the session.

When you execute the program, the connected property returns True while the application is connected to the device and returns False after the connection is closed.

user@host:~$ python connect.py

Connecting to a Device Using SSH

The Junos PyEZ Device class supports using SSH to connect to a device running Junos OS. You can establish a NETCONF session over SSH with the device’s management interface or you can establish an SSH connection with a console server that is directly connected to the device’s CONSOLE port. The SSH server must be able to authenticate the user using standard SSH authentication mechanisms, as described in Authenticating Junos PyEZ Users. To establish a NETCONF session over SSH, you must also satisfy the requirements outlined in Setting Up Junos PyEZ Managed Nodes.

Junos PyEZ automatically queries the default SSH configuration file at ~/.ssh/config, if one exists. When using SSH to connect to a device running Junos OS or to a console server connected to the device, Junos PyEZ first attempts SSH public key-based authentication and then tries password-based authentication. When SSH keys are in use, the supplied password is used as the passphrase for unlocking the private key. When password-based authentication is used, the supplied password is used as the device password. If SSH public key-based authentication is being used and the SSH private key has an empty passphrase, then a password is not required. However, SSH private keys with empty passphrases are not recommended.

To establish a NETCONF session over SSH with a device running Junos OS and print the device facts in a Junos PyEZ application using Python 3:

  1. Import the Device class and any other modules or objects required for your tasks.

  2. Create the device instance, and provide the hostname, any parameters required for authentication, and any optional parameters.

  3. Connect to the device by calling the open() method, for example:

  4. Print the device facts.

  5. After performing any necessary tasks, close the connection to the device.

The sample program in its entirety is presented here:

Alternatively, you can use a context manager when connecting to the device, which automatically calls the open() and close() methods. For example:

Junos PyEZ also enables a client to connect to a device running Junos OS through an SSH connection to a console server. In this case, you must specify the login credentials for the console server by including the cs_user and cs_passwd arguments in the Device argument list. When SSH keys are in use, set the cs_passwd argument to the variable containing the passphrase for the private key.

The console server connects to the device running Junos OS through a serial connection, which can be slow. Junos PyEZ connections through a console server have a default connection timeout value of 0.5 seconds. As a result, you might need to increase the connection timeout interval by including the Device timeout=seconds argument to allow sufficient time for the client application to establish the connection.

The following Python 3 example authenticates with the console server and then the device running Junos OS. The connection timeout is set to six seconds so that the client has sufficient time to establish the connection.

Junos PyEZ automatically queries the default SSH configuration file at ~/.ssh/config, if one exists. However, starting with Junos PyEZ Release 1.2, you can specify a different SSH configuration file when you create the device instance by including the ssh_config parameter in the Device argument list. For example:

Also, starting in Junos PyEZ Release 1.2, Junos PyEZ provides support for ProxyCommand, which enables you to access a target device through an intermediary host that supports netcat. This is useful when you can only log in to the target device through the intermediate host.

To configure ProxyCommand, add the appropriate information to the SSH configuration file. For example:

Connecting to a Device Using Outbound SSH

You can configure a device running Junos OS to initiate a TCP/IP connection with a client management application that would be blocked if the client attempted to initiate the connection (for example, if the device is behind a firewall). The outbound-ssh configuration instructs the device to create a TCP/IP connection with the client management application and to forward the identity of the device. Once the connection is established, the management application acts as the client and initiates the SSH sequence, and the device acts as the server and authenticates the client.

Note

There is no initiation command with outbound SSH. Once outbound SSH is configured and committed, the device begins to initiate an outbound SSH connection based on the committed configuration. The device repeatedly attempts to create this connection until successful. If the connection between the device and the client management application is dropped, the device again attempts to create a new outbound SSH connection until successful. This connection is maintained until the outbound SSH stanza is removed from the configuration.

To configure the device running Junos OS for outbound SSH connections, include the outbound-ssh statement at the [edit system services] hierarchy level. In the following example, the device running Junos OS attempts to initiate a connection with the host at 198.51.100.101 on port 2200:

user@router1> show configuration system services outbound-ssh

To establish a connection with the device running Junos OS using outbound SSH, the Junos PyEZ application sets the sock_fd argument in the Device constructor equal to the file descriptor of an existing socket and either omits the host argument or sets it to None.

The following Junos PyEZ example listens on the configured TCP port for incoming SSH sessions from devices running Junos OS. The application accepts an incoming connection and retrieves the socket’s file descriptor for that connection, which is used for the value of the sock_fd argument. The client application establishes the SSH connection with the device, collects and prints the device facts, disconnects from the device, and waits for more connections.

user@server:~$ python junos-pyez-outbound-ssh.py

For detailed information about configuring outbound SSH on devices running Junos OS, see Configuring Outbound SSH Service.

Connecting to a Device Using Telnet

The Junos PyEZ Device class supports connecting to a device running Junos OS using telnet, which provides unencrypted access to the network device. You can telnet to the device’s management interface or to a console server that is directly connected to the device’s CONSOLE port. You must configure the Telnet service at the [edit system services] hierarchy level on all devices that require access to the management interface. Accessing the device through a console server enables you to initially configure a new or zeroized device that is not yet configured for remote access.

To use Junos PyEZ to telnet to a device running Junos OS, you must include mode='telnet' in the Device argument list, and optionally include the port parameter to specify a port. When you include the mode='telnet' argument but omit the port parameter, the value for port defaults to 23. When the application connects through a console server, specify the port through which the console server connects to the device running Junos OS.

To use Junos PyEZ to telnet to a device running Junos OS and print the device facts in a Junos PyEZ application using Python 3:

  1. Import the Device class and any other modules or objects required for your tasks.

  2. Create the device instance with the mode='telnet' argument, specify the connection port if different from the default, and provide the hostname, any parameters required for authentication, and any optional parameters.

  3. Connect to the device by calling the open() method.

  4. Print the device facts.

  5. After performing any necessary tasks, close the connection to the device.

The sample program in its entirety is presented here:

Alternatively, you can use a context manager when connecting to the device, which handles opening and closing the connection. For example:

In some cases, when you connect to a console server that emits a banner message, you might be required to press Enter after the message to reach the login prompt. If a Junos PyEZ application opens a Telnet session with a console server that requires the user to press Enter after a banner message, the application might fail to receive the login prompt, which can cause the connection to hang.

Starting in Junos PyEZ Release 2.1.0, a Junos PyEZ application can include the console_has_banner=True argument in the Device argument list to telnet to a console server that emits a banner message.

When you include the console_has_banner=True argument and the application does not receive a login prompt upon initial connection, the application waits for 5 seconds and then emits a newline (\n) character so that the console server issues the login prompt. If you omit the argument and the connection hangs, the application instead emits the <close-session/> RPC to terminate the connection.

Connecting to a Device Using a Serial Console Connection

The Junos PyEZ Device class enables you to connect to a device running Junos OS using a serial console connection, which is useful when you must initially configure a new or zeroized device that is not yet configured for remote access. To use this connection method, you must be physically connected to the device through the CONSOLE port. For detailed instructions about connecting to the CONSOLE port on your device, see the hardware documentation for your specific device.

Note

Junos PyEZ supports using context managers for serial console connections. We recommend that you use a context manager for console connections, because the context manager automatically handles opening and closing the connection. Failure to close the connection can lead to unpredictable results.

To use Junos PyEZ to connect to a device running Junos OS through a serial console connection, you must include mode='serial' in the Device argument list, and optionally include the port parameter to specify a port. When you include the mode='serial' argument but omit the port parameter, the value for port defaults to /dev/ttyUSB0.

To connect to a device running Junos OS using a serial console connection and also load and commit a configuration on the device in a Junos PyEZ application using Python 3:

  1. Import the Device class and any other modules or objects required for your tasks.

  2. Create the device instance with the mode='serial' argument, specify the connection port if different from the default, and provide any parameters required for authentication and any optional parameters.

    Note

    All platforms running Junos OS have only the root user configured by default, without any password. For new or zeroized devices, use user='root' and omit the passwd parameter.

  3. Load and commit the configuration on the device.

  4. Include any necessary error handing.

The sample program in its entirety is presented here: