Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Using the Requests Library for Python on Devices Running Junos OS

 

The Requests library for Python is available on certain devices running Junos OS that support the Python extensions package. You can use the requests module in Python scripts to send HTTP/1.1 requests. On devices running Junos OS with Enhanced Automation, you can also use the requests module in Python interactive mode. The Requests library provides additional methods for supporting initial deployments as well as for performing routine monitoring and configuration changes on devices running Junos OS. For information about the requests module and its functions, see the Requests documentation at http://docs.python-requests.org/.

Issuing Requests

You can use the requests module in onbox Python scripts to send HTTP/1.1 requests. To make a request, import the module in your script, and call the function corresponding to the desired request. The module supports HTTP GET and POST requests as well as HEAD, DELETE, and PUT requests. The request returns a Response object containing the server’s response. By default, requests are made using the default routing instance.

The Requests library can be used to execute RPCs on devices running Junos OS that support the REST API service. The target device must be configured with the appropriate statements at the [edit system services rest] hierarchy level to enable Junos OS commands over HTTP or HTTPS using REST.

For example, the following op script performs a GET request that executes the get-software-information RPC on a remote device running Junos OS that has the REST API service over HTTP configured on the default port (3000). The script prints the response status code, and if the status code indicates success, it prints the response content.

user@host> op show-version.py

To retrieve just the headers, you can send a simple HEAD request.

user@host> op request-headers.py

If a GET request requires additional parameters, you can either include the params argument and supply a dictionary or a list of tuples or bytes to send in the query string, or you can pass in key/value pairs as part of the URL. Similarly, you can supply custom headers by including the headers argument and a dictionary of HTTP headers.

The following request executes the get-interface-information RPC with the terse option for the given interface and returns the response in text format:

The following example supplies the arguments as key/value pairs in the URL:

To execute multiple RPCs in the same request, initiate an HTTP POST request, and set the data parameter to reference the RPCs to execute. See sections Executing Operational RPCs and Managing the Configuration for examples that execute multiple RPCs.

Executing Operational RPCs

You can use the requests module to execute RPCs from the Junos XML API on a remote device running Junos OS that has the REST API service enabled.

The following op script uses the requests module to execute the RPC equivalent of the show interfaces ge-2/0/1 terse operational mode command on the target device:

The following op script sends a POST request that executes multiple RPCs on the target device. The data parameter references the RPCs to execute, which are defined in a multiline string for readability.

You can also create a generic op script for which the user supplies the necessary variables and the script constructs and executes the request. Consider the following op script configuration, which configures the host, rpc, and rpc_args command line arguments for the requests-rpc.py op script

The following sample op script connects to a remote device running Junos OS, which has been configured with the appropriate statements at the [edit system services rest] hierarchy level to enable Junos OS commands over HTTP using REST. The script prompts for the connection password and connects to the host and port provided through the host argument. The script then uses the requests module to send a GET request executing the RPC that was provided through the command-line arguments.

When you execute the script, it executes the RPC with the specified options on the remote device and prints the response to standard output.

Managing the Configuration

You can use the requests module to retrieve or change the configuration on a device running Junos OS that has the REST API service enabled.

The following op script retrieves the [edit system] hierarchy from the candidate configuration using a POST request:

HTTP POST requests also enable you to execute multiple RPCs in a single request, for example, to lock, load, commit, and unlock a configuration.

The following sample op script connects to the remote device and configures an address on the given interface. The lock, load, commit, and unlock operations are defined separately for readability, but the RPCs are concatenated in the request.

When you execute the op script, it returns the RPC results for the lock, load, commit, and unlock operations. On some devices, the response output separates the individual RPC replies with boundary lines that include -- followed by a boundary string and a Content-Type header. Other devices might include just the Content-Type header.

user@host> op requests-set-interface.py

Using Certificates in HTTPS Requests

The HTTP basic authentication mechanism sends user credentials as a Base64-encoded clear-text string. To protect the authentication credentials from eavesdropping, we recommend enabling the RESTful API service over HTTPS, which encrypts the communication using Transport Layer Security (TLS) or Secure Sockets Layer (SSL). For information about configuring this service, see the Junos OS REST API Guide.

By default, the Requests library verifies SSL certificates for HTTPS requests. You can include the verify and cert arguments in the request to control the SSL verification options. For detailed information about these options, see the Requests documentation.

Note

When you use Python 2.7 to execute a script that uses the requests module to execute HTTPS requests, the script generates InsecurePlatformWarning and SubjectAltNameWarning warnings.

The following op script sends a GET request over HTTPS, and sets the verify argument to the file path of a CA bundle or a directory containing trusted CA certificates. The specified CA certificates are used to verify the server’s certificate.

To specify a local client-side certificate, set the cert argument equal to the path of a single file containing the client’s private key and certificate or to a tuple containing the paths of the individual client certificate and private key files.

Specifying the Routing Instance

By default, requests are executed using the default routing instance. You can also execute requests using the mgmt_junos management instance or another non-default routing instance. When you execute scripts through the Junos OS infrastructure, you can specify the routing instance by calling the set_routing_instance() function in the script. Certain devices also support specifying the routing instance and executing a script in the Unix-level shell.

Note

On devices running Junos OS Evolved, the set_routing_instance() function only supports using the management routing instance.

In a Python script, to execute a request using a non-default routing instance, including the mgmt_junos instance:

  1. Import the jcs module.
  2. Call the set_routing_instance() function, and specify the instance to use for the connection.
  3. Establish the connection with the target device.

The following op script uses the mgmt_junos management instance to connect to the target device and execute requests.

For information about using the set_routing_instance() function in Python scripts, see set_routing_instance().

In addition to specifying the routing instance in the script, certain devices support specifying the routing instance and executing a script from the Unix-level shell. On devices running Junos OS with Enhanced Automation (FreeBSD Release 7.1 or later), you can use the setfib command to execute requests with the given routing instance, including the management instance and other non-default routing instances.

The following Python script simply executes the get-software-information RPC on a remote device and prints the response:

To use setfib to execute the script using a non-default routing instance on a device running Junos OS with Enhanced Automation:

  1. Find the software index associated with the routing table for that instance.

    In the following example, the device is configured to use the non-default dedicated management instance mgmt_junos. The routing table index is referenced in the command output.

    user@host> show route forwarding-table extensive table mgmt_junos
  2. Enter the Unix-level shell.
    user@host> start shell
  3. Use the setfib command to execute the script, and reference the index.
    % setfib -F36738 python /var/db/scripts/op/request-software-info.py

In the following example, the device is configured with a non-default routing instance, vr1, and the vr1.inet routing table index is 8:

user@host> show route forwarding-table extensive table vr1

The following command executes the script using the vr1 routing instance:

% setfib -F8 python /var/db/scripts/op/request-software-info.py

Performing ZTP Operations

Zero touch provisioning (ZTP) enables you to provision new Juniper Networks devices in your network automatically, with minimal manual intervention. To use ZTP, you configure a DHCP server to provide the required information, which can include a Junos OS image and a configuration file. The configuration file can be a Junos OS configuration to load or a script to execute.

When you physically connect a device to the network and boot it with a factory-default configuration, the device retrieves the information from the designated server, downloads the image and configuration file, and upgrades the software as appropriate. The device then examines the configuration file. If the first line of the file contains the characters #! followed by an interpreter path, Junos OS treats the file as a script and executes it with the specified interpreter. You can use the Requests library in executed scripts to streamline the ZTP process.

For example, consider the following sample Python script, which the new device downloads and executes during the ZTP process. When the script executes, it first downloads the CA certificate from the ca_cert_remote location on the specified server and stores it locally in the ca_cert_local location. The script then connects to the configuration server on port 8000 and issues a GET request to retrieve the new device configuration. The request includes the path to the CA certificate, which is used to verify the server’s certificate during the exchange. The script then uses the Junos PyEZ library to load the configuration on the device and commit it.