Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Connecting to Devices Running Junos OS Using Ansible

SUMMARY Juniper Networks’ Ansible modules enable you to connect to devices running Junos OS using SSH, telnet, or serial console connections.

Juniper Networks provides Ansible modules that you can use to manage devices running Junos OS. The Juniper Networks modules are distributed through the juniper.device collection and the Juniper.junos role, which are hosted on Ansible Galaxy. The modules can connect to devices running Junos OS using different protocols and Ansible connections, which are described in this document.

Connection Methods Overview

The Juniper Networks Ansible modules enable you to connect to a device running Junos OS using SSH, telnet, or a serial console connection. You must use a serial console connection when your terminal or laptop is physically connected to the CONSOLE port on a device running Junos OS. You can use SSH or telnet to connect to the device’s management interface or to a console server that is directly connected to the device’s CONSOLE port.

New or zeroized devices that have factory-default configurations require access through a console connection. Thus, you can use Ansible 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 directly connected to the device.

By default, the Juniper Networks modules use SSH to connect to a device. To use telnet or a serial console connection, set the module’s mode parameter to the appropriate value. To telnet to a device, set the mode argument equal to "telnet". To use a serial console connection, set the mode argument equal to "serial". Table 1 summarizes the connection modes, their default values for certain parameters, any required Junos OS configuration, and the Juniper.junos release in which support for that connection mode was first introduced. The juniper.device modules support all connection modes as of their initial release.

Table 1: Connection Modes for the Juniper Networks Ansible Modules

Connection Mode

Value of mode Argument

Default Port

Required Junos OS Configuration

First Supported Release (Juniper.junos)

NETCONF over SSH (default)

830

[edit system services]
netconf {
    ssh;
}

1.0.0

Serial console connection

serial

/dev/ttyUSB0

2.0.0

SSH through a console server

22

2.2.0

Telnet to device running Junos OS

telnet

23

[edit system services]
telnet;

1.4.0

Default port added in 2.0.0

Telnet through a console server

telnet

23

1.4.0

Note:

Before you can access the management interface using telnet or NETCONF over SSH, you must first enable the appropriate service at the [edit system services] hierarchy level. Because telnet uses clear-text passwords (therefore creating a potential security vulnerability), we recommend that you use SSH.

When you execute the Juniper Networks modules to manage a device running Junos OS, the remote device must be able to authenticate the Ansible user using credentials appropriate for the given protocol. For more information, see Authenticating Users Executing Ansible Modules on Devices Running Junos OS.

The Juniper Networks modules support different Ansible connections when connecting to devices running Junos OS, including local (per-task) connections and persistent (per-play) connections. The Ansible connection determines whether Ansible establishes a separate connection to the host for each task in the play or whether it establishes a single connection to a host that persists over all tasks in the play. For information about specifying the Ansible connection, see Understanding Local and Persistent Ansible Connections.

Understanding Local and Persistent Ansible Connections

The Juniper Networks modules do not require Python on devices running Junos OS because they use Junos PyEZ and the Junos XML API over NETCONF to interface with the device. Therefore, to perform operations on devices running Junos OS, you must run modules locally on the Ansible control node, where Python is installed. You can run the modules locally by including connection: local in the playbook play. When you use connection: local, Ansible establishes a separate connection to the host for each task in the play that performs operations on the host.

The juniper.device collection modules also support connection: juniper.device.pyez for establishing a persistent connection to a host. When you use a persistent connection, Ansible still executes the modules locally on the control node, but it only establishes and maintains a single connection to each host, which persists over the execution of all tasks in the play. Establishing a persistent connection to a host can be more efficient for executing multiple tasks than establishing a separate connection to the host for every task in the play.

Table 2 summarizes the Ansible connections and the content sets that support them.

Table 2: Ansible Connections Supported By Juniper Networks Modules

Ansible connection

Description

Content Set Support

connection: local

Execute the modules locally on the Ansible control node but establish a separate connection to a host for each task in the play that performs operations on the host.

juniper.device collection

Juniper.junos role

connection: juniper.device.pyez

Execute the modules locally on the Ansible control node but establish a persistent connection to a host that persists over the execution of all tasks in the play.

juniper.device collection

Note:

Ansible has deprecated connection: local. Therefore, when you use the juniper.device collection modules, we recommend that you use connection: juniper.device.pyez in your playbook to avoid issues in the event that Ansible removes support for local connections in a later release.

When you use connection: local, Ansible establishes a separate connection to a host for each module, which means you can define module-specific connection and authentication parameters in the module’s argument list. By contrast, when you use connection: juniper.device.pyez, the connection persists across all tasks in the play, and thus you must define the connection and authentication parameters globally for all modules. You can define the parameters in the vars: section of a play, in addition to providing them through other means, for example, in an SSH configuration file or in the Ansible inventory file. For additional details, see Authenticating Users Executing Ansible Modules on Devices Running Junos OS.

The following playbook establishes a persistent connection to each host that is used for all tasks in the play. The user’s credentials, which are stored in an Ansible vault file, are defined in the play’s vars: section.

Connecting to a Device Using SSH

The Juniper Networks Ansible modules support using SSH to connect to a device running Junos OS. You can establish a NETCONF session over SSH on 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 Users Executing Ansible Modules on Devices Running Junos OS. To establish a NETCONF session over SSH, you must also satisfy the requirements outlined in Setting up Ansible for Junos OS Managed Nodes.

The Juniper Networks modules automatically query the default SSH configuration file at ~/.ssh/config, if one exists, unless the ssh_config parameter specifies a different configuration file. When using SSH to connect to a device running Junos OS or to a console server connected to the device, the modules first attempt SSH public key-based authentication and then try password-based authentication. When password-based authentication is used, the supplied password is used as the device password. When SSH keys are in use, the supplied password is used as the passphrase for unlocking the private key. If the SSH private key has an empty passphrase, then a password is not required. However, SSH private keys with empty passphrases are not recommended.

The following playbook establishes a NETCONF session over SSH with a device running Junos OS and retrieves the device facts. The playbook uses SSH keys in the default location.

The Juniper Networks Ansible modules also enable you 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 both the device running Junos OS and the console server. Use the user and passwd parameters to specify the Junos OS login credentials, and use the cs_user and cs_passwd parameters to specify the console server credentials. When SSH keys are in use, cs_passwd is the passphrase for the private key.

The following playbook prompts for the user’s credentials for the console server and the device running Junos OS. The module authenticates with the console server and then the device running Junos OS. If authentication is successful, the playbook then retrieves the device facts from the managed node and prints the Junos OS version.

The Juniper Networks modules automatically query the default SSH client configuration file at ~/.ssh/config, if it exists. You can use a different SSH configuration file by including the ssh_config parameter and specifying the location of the configuration file. For example:

Connecting to a Device Using Telnet

The Juniper Networks modules enable you to connect 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. 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 telnet to the management interface, you must configure the Telnet service at the [edit system services] hierarchy level on all devices that require access to the interface.

To telnet to the remote device, set the mode parameter to "telnet" and optionally include the port parameter to specify a port. When you set mode to "telnet" but omit the port parameter, the value for port defaults to 23. For persistent connections, define mode and port under the vars: section. For local connections, you can define the parameters either under the vars: section or as module arguments.

The following playbook telnets to a device running Junos OS using port 7016, retrieves the device facts, and saves them to a file. The module uses the default user and prompts for the login password.

Connecting to a Device Using a Serial Console Connection

The Juniper Networks modules enable 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, your terminal or laptop must be physically connected to the device running Junos OS through the CONSOLE port. For detailed instructions about connecting to the CONSOLE port on a device running Junos OS, see the hardware documentation for your specific device.

To connect to a device running Junos OS through a serial console connection, set the module’s mode parameter to "serial", and optionally include the port parameter to specify a port. When you set mode to "serial" but omit the port parameter, the value for port defaults to /dev/ttyUSB0. For persistent connections, define mode and port under the vars: section. For local connections, you can define the parameters either under the vars: section or as module arguments.

The following playbook connects to a device running Junos OS through the CONSOLE port and then loads and commits an initial configuration. The module uses the default user and prompts for the login password.