Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

NETCONF Sessions over Outbound HTTPS

Client applications can establish Network Configuration Protocol (NETCONF) sessions using outbound HTTPS on supported devices running Junos OS Release 20.2.

This topic discusses how to establish NETCONF sessions using outbound HTTPS on devices running Junos OS Release 20.2. For information about establishing NETCONF and shell sessions using enhanced outbound HTTPS, see NETCONF and Shell Sessions over Enhanced Outbound HTTPS.

Understanding NETCONF Sessions over Outbound HTTPS

Benefits of NETCONF Sessions over Outbound HTTPS

  • Enable NETCONF client applications to manage devices that are not accessible through other protocols.

  • Enable remote management of devices using certificate-based authentication for the outbound HTTPS client.

NETCONF Sessions over Outbound HTTPS Overview

You can establish NETCONF sessions over outbound HTTPS between supported Junos devices and a network management system. A NETCONF session over outbound HTTPS enables you to remotely manage devices that might not be accessible through other protocols such as SSH. This might happen, for example, if the device is behind a firewall, and the firewall or another security tool blocks those protocols. HTTPS, on the other hand, uses a standard port, which is typically allowed outbound in most environments.

On supported devices, Junos OS includes a Juniper Extension Toolkit (JET) application that supports establishing a NETCONF session using outbound HTTPS. The JET application uses the gRPC framework to connect to the outbound HTTPS client, which consists of a gRPC server running on the network management system. gRPC is a language-agnostic, open-source remote procedure call (RPC) framework. Figure 1 illustrates the outbound HTTPS setup in its simplest form.

Figure 1: NETCONF Sessions over Outbound HTTPSNETCONF Sessions over Outbound HTTPS

In this scenario, the gRPC server acts as the NETCONF client, and the JET application is the gRPC client and NETCONF server. The gRPC server listens for connection requests on the specified port, which defaults to port 443. You configure the JET application as an extension service. The relevant connection and authentication information is passed to the script. While the script runs, it automatically attempts to connect to the gRPC server on the configured host and port.

The JET application and gRPC server establish a persistent HTTPS connection over a TLS-encrypted gRPC session. The JET application authenticates the gRPC server using an X.509 digital certificate, and if the authentication is successful, the requested NETCONF session is established over this connection. The NETCONF operations execute under the account privileges of the user configured for the extension service application.

The outbound HTTPS connection uses an X.509 digital certificate to authenticate the gRPC server. A digital certificate is an electronic means for verifying your identity through a trusted third party, known as a certificate authority or certification authority (CA). A certificate authority issues digital certificates, which can be used to establish a secure connection between two endpoints through certificate validation. The X.509 standard defines the format for the certificate. To establish a NETCONF session over outbound HTTPS on supported Junos devices, the gRPC server must have a valid X.509 certificate.

The basic outbound HTTPS feature provides support for connecting to a single outbound HTTPS client and configuring one gRPC server for that client. Server authentication must use a self-signed X.509 certificate. You can establish a single NETCONF session over the connection.

Connection Workflow for Sessions over Outbound HTTPS

In a NETCONF session over outbound HTTPS, the gRPC server running on the network management system acts as the NETCONF client, and the JET application on the Junos device is the gRPC client and NETCONF server.

The gRPC client and server perform the following actions to establish a NETCONF session over outbound HTTPS:

  1. The gRPC server listens for incoming connections on the specified port, or if no port is specified, on the default port 443.

  2. The gRPC client initiates a TCP/IP connection with the configured gRPC server and port.

  3. The gRPC client sends a TLS ClientHello message to initiate the TLS handshake.

  4. The gRPC server sends a ServerHello message and its certificate.

  5. The gRPC client verifies the identity of the gRPC server.

  6. The NETCONF session is established.

  7. The server and client exchange NETCONF <hello> messages.

  8. The NETCONF client application performs operations as needed.

How to Establish a NETCONF Session over Outbound HTTPS

You can use the JET application that is included as part of the Junos software image to establish a NETCONF session over outbound HTTPS between a network management system (NMS) and supported Junos devices. The JET application, configured as an extension service, initiates a connection to a gRPC server running on an NMS and establishes a persistent HTTPS connection over a TLS-encrypted gRPC session. The NETCONF session runs over this HTTPS connection. In this scenario, the gRPC server is the NETCONF client, and the JET application is the gRPC client and NETCONF server.

The following hardware and software are required for establishing a NETCONF session over outbound HTTPS:

  • Network management system running Python 3.5 or later

  • Device running Junos OS with upgraded FreeBSD Release 20.2 that also supports running JET applications

    Note:

    For supported devices, see Feature Explorer NETCONF sessions over outbound HTTPS.

Figure 2 illustrates the setup referenced in the tasks that follow.

Figure 2: NETCONF over Outbound HTTPS TopologyNETCONF over Outbound HTTPS Topology

Before the client and server can establish a NETCONF session over outbound HTTPS, you must satisfy the requirements discussed in the following sections:

Obtain an X.509 Certificate for the gRPC Server

The outbound HTTPS connection uses an X.509 public key certificate to authenticate the identity of the gRPC server running on the network management system. The gRPC stack supports the X.509 v3 certificate format.

The requirements for the gRPC server’s certificate are:

  • The certificate must be self-signed.

  • The certificate must define either the gRPC server’s hostname in the Common Name (CN) field, or it must define the gRPC server’s IP address in the SubjectAltName (SAN) IP Address field. The Junos device must use the same value to establish the connection to the server. If the certificate defines the SubjectAltName IP Address field, the device ignores the Common Name field during authentication.

  • The certificate must be PEM-encoded and use a .crt extension.

  • The certificate and its key must be named server.crt and server.key, respectively.

To use OpenSSL to obtain a certificate:

  1. Generate a private key, and specify the key length in bits.
    Note:

    We recommend using 3072 bits or greater for the size of the private key.
  2. If you are connecting to the gRPC server’s IP address, update your openssl.cnf or equivalent configuration file to define the subjectAltName=IP extension with the gRPC server’s address.
  3. Generate a certificate signing request (CSR), which contains the client’s public key and information about their identity.
  4. Generate the certificate.

    Sign the CSR with the server key to generate a self-signed client certificate, and include the -extfile option if you need to reference your configuration file and extensions.

  5. Verify that the Common Name (CN) field and extensions, if provided, are correct.
  6. (Optional) Copy the server.crt file to the /var/db/scripts/jet directory on the device running Junos OS to use the certificate file for authentication.
    Note:

    You can omit this step if the key size is less than or equal to 4096 bits and you instead configure the certificate’s contents in the JET application’s trusted_certs argument on the Junos device.

Set Up the gRPC Server

The network management system requires the following software:

  • Python 3.5 or later

The network management system and the JET application on the Junos device use the gRPC framework to establish a persistent HTTPS connection over a TLS-encrypted gRPC session. The network management system must have the gRPC stack installed and run a gRPC server that listens on the specified port for the connection request. Juniper Networks provides the necessary proto definition files and sample gRPC server application files in the Juniper Networks netconf-https-outbound repository on GitHub.

This section sets up the gRPC server on a network management system running Ubuntu 18.04. If you are running a different operating system, use the commands appropriate for your OS.

To set up the gRPC server on a network management system running Ubuntu 18.04:

  1. Install pip for Python 3.
  2. Install the grpcio package.
  3. Install the grpcio-tools package.
  4. Go to the Juniper GitHub repository at https://github.com/Juniper/netconf-https-outbound, and select the directory corresponding to the release running on the Junos device.
  5. Download the application and proto files in the GitHub directory to the directory on the network management system where the gRPC server’s certificate resides.

    1. Select each file, click the Raw button, and copy the URL for the file.

    2. Download the file by using the URL with the download tool of your choice, for example, wget or curl.

  6. Use the protocol buffer compiler, protoc, to compile each proto definition file and generate Python code, which produces two output files for each proto file.

    For example:

  7. Start the gRPC server, and specify the port for the connection, if it’s different from the default port 443.
    Note:

    You might need to execute the script with root permissions to listen on port 443.

The gRPC server listens indefinitely on the specified port for incoming connections. After you configure the Junos device to connect to the gRPC server and a connection and session are established, you can perform NETCONF operations as appropriate.

Configure the User Account for the NETCONF User

To establish a NETCONF session over outbound HTTPS, you must create a user account locally on the Junos device. You use this account to perform the NETCONF operations on the device for that session. The JET application runs using the permissions configured for this account.

To create a user account on a Junos device:

  1. Configure the user statement with a unique username, and include the class statement to specify a login class that has the permissions required for all actions to be performed by the user. For example:
  2. (Optional) Configure the uid and full-name statements to specify a unique user ID and the user’s name.
  3. Commit the configuration to activate the user account on the device.
  4. Repeat the preceding steps on each Junos device where the client needs to establish NETCONF sessions over outbound HTTPS.

Configure the Outbound HTTPS Client

The JET application can connect to only one outbound HTTPS client. You configure the connection and authentication information for the client as command-line arguments to the JET script. Table 1 outlines the arguments.

Table 1: nc_grpc_app.py Arguments

Argument

Value

--device or -d

The hostname or IPv4 address of the gRPC server to which the JET application connects. The argument value must match the hostname in the Common Name (CN) field or the IP address in the SubjectAltName IP address field in the gRPC server's certificate.

--port or -p

(Optional) Port on which the JET application attempts to connect to the gRPC server. Omit this argument to use the default port 443.

--trusted_certs or -ts

(Optional) The gRPC server's certificate contents between the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, omitting any newlines.

You can omit this argument if you instead copy the certificate to the /var/db/scripts/jet directory on the device. You must copy the certificate to the device for key sizes greater than 4096 bits.

Before you begin, you will need the values for the script arguments, including:

  • The port on which the gRPC server is listening for connections.

  • The contents of the SubjectAltName IP Address field, or if there is no such field, the contents of the Common Name (CN) field in the gRPC server's certificate.

  • The contents of the gRPC server's certificate between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, omitting any newlines. This information is only required when you configure the certificate contents as a script argument instead of copying the certificate to the device running Junos OS.

To configure the outbound HTTPS client:

  1. Navigate to the hierarchy of the nc_grpc_app.py extension service application.
  2. Configure the arguments that are passed to the application when it starts.
  3. Commit the configuration.

Configure the Outbound HTTPS Extension Service on Junos Devices

Junos releases that support NETCONF sessions over outbound HTTPS include a JET application and supporting files in the software image. Table 2 outlines the files, which are located in the /var/db/scripts/jet directory on the device.

Table 2: JET Files for Sessions over Outbound HTTPS

Files

Description

nc_grpc_app.py

JET application that uses the gRPC framework to establish a persistent HTTPS connection with a gRPC server running on the network management system.

nc_grpc_pb2.py

nc_grpc_pb2_grpc.py

Required libraries

To configure the Junos device for sessions over outbound HTTPS:

  1. Verify that the JET application and related files are present on the device.
  2. Enter configuration mode.
  3. Enable the device to run unsigned Python 3 applications.
  4. Navigate to the hierarchy of the extension service application.
  5. Configure the application to run in the background as a daemonized process.
  6. Configure the application to respawn on normal exit.
  7. Configure the usename under whose privileges the application executes and the NETCONF operations are performed.
  8. Commit the configuration.

    When you commit the configuration, the daemonize option causes the application to start automatically.

  9. Verify that the application is running.

After the application successfully starts, it logs messages to the outbound_https.log file.

Note:

If the application does not automatically start after you commit the configuration, review the log messages related to this application to troubleshoot the issue. In Junos OS, issue the show log jet.log command.

Start the NETCONF Session

The gRPC server running on the network management system acts as the NETCONF client, and the JET application on the Junos device acts as the gRPC client and NETCONF server. After you start the gRPC server and JET application, the JET application attempts to connect to the gRPC server on the specified port. If the connection is successful, the gRPC client authenticates the gRPC server. If the server authentication is successful, the NETCONF session starts automatically.

To establish a NETCONF session over outbound HTTPS:

  1. On the network management system, if you did not already start the gPRC server, start the server, and specify the port for the connection.

    The NETCONF session starts automatically.

  2. Verify that the session is successfully established by reviewing the output.

    NETCONF sessions should display the NETCONF capabilities as shown here:

  3. Perform NETCONF operations as necessary.
  4. When you are finished with the session, type Ctrl+C.
  5. When you are finished using the outbound HTTPS connection, you can stop the extension service application on the Junos device by deleting or deactivating the relevant hierarchy in the configuration and then committing the change.