Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

NETCONF and Shell Sessions over Enhanced Outbound HTTPS

SUMMARY Client applications can establish Network Configuration Protocol (NETCONF) sessions and shell sessions using enhanced outbound HTTPS on supported Junos devices.

Understanding NETCONF and Shell Sessions over Enhanced Outbound HTTPS

Benefits of NETCONF and Shell Sessions over Outbound HTTPS

  • Enable NETCONF or shell 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 and Shell Sessions over Outbound HTTPS Overview

You can establish NETCONF and shell sessions over outbound HTTPS between supported Junos devices and a network management system. A NETCONF or shell 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, the Junos software image includes a Juniper Extension Toolkit (JET) application that supports establishing a NETCONF or shell 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 and Shell Sessions over Outbound HTTPSNETCONF and Shell Sessions over Outbound HTTPS

In this scenario, the gRPC server acts as the NETCONF/shell client, and the JET application is the gRPC client and NETCONF/shell 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 or shell session is established over this connection. The NETCONF operations and shell commands 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 or shell session over outbound HTTPS on supported Junos devices, the gRPC server must have a valid X.509 certificate.

Enhanced outbound HTTPS provides support for:

  • Connecting to multiple outbound HTTPS clients

  • Configuring multiple backup gRPC servers for each outbound HTTPS client

  • Establishing multiple, concurrent NETCONF and shell sessions with a given client

  • Authenticating the outbound HTTPS client using self-signed or CA-signed X.509 digital certificates

  • Authenticating the Junos device using a shared secret

Connection Workflow for Sessions over Enhanced Outbound HTTPS

In a NETCONF or shell session over outbound HTTPS, the gRPC server running on the network management system acts as the NETCONF/shell client, and the JET application on the Junos device is the gRPC client and NETCONF/shell server. You can configure multiple outbound HTTPS clients, and you can configure one or more backup gRPC servers for each client. The JET application connects to only one gRPC server in the client’s server list at any one time.

The gRPC client and server perform the following actions to establish a NETCONF or shell 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. If you configure an outbound HTTPS client with one or more backup gRPC servers, the gRPC client tries to connect to each server in the list until it establishes a connection.

  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 gRPC client sends the device ID and shared secret configured for that outbound HTTPS client to the gRPC server.

  7. The outbound HTTPS client requests a NETCONF or shell session, and the gRPC server uses the device ID and shared secret to authenticate the Junos device. If authentication is successful, the session is established.

  8. If a NETCONF session is requested, the server and client exchange NETCONF <hello> messages.

  9. The NETCONF or shell client application performs operations as needed.

The gRPC client initiates another TCP/IP connection with the same gRPC server, and the gRPC client and server repeat the process, which enables the outbound HTTPS client to establish multiple NETCONF and shell sessions with the network device.

How to Establish NETCONF and Shell Sessions over Enhanced Outbound HTTPS

You can use the JET application that is included as part of the Junos software image to establish NETCONF and shell sessions over outbound HTTPS between network management systems (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 or shell session runs over this HTTPS connection. In this scenario, the gRPC server is the NETCONF/shell client, and the JET application is the gRPC client and NETCONF/shell server.

The following hardware and software are required for establishing sessions over enhanced outbound HTTPS:

  • Network management system running Python 3.5 or later

  • Device running Junos OS Evolved or device running Junos OS with upgraded FreeBSD Release 20.3 or later that also supports running JET applications

    Note:

    For supported devices, see Feature Explorer.

Figure 2 illustrates the setup referenced in the tasks that follow. The management interface name on the Junos device varies depending on the platform and OS.

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

Before the client and server can establish a NETCONF or shell 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 can be self-signed or signed by a certificate authority (CA).

  • 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. The key length should not exceed 4096 bits.
  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 entity’s public key and information about their identity.
  4. Generate the certificate by doing one of the following:

    • Send the CSR to a certificate authority to request an X.509 certificate, and provide the configuration file to include any additional extensions.

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

    • 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.

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.
    Note:

    If you encounter installation errors for the grpcio or grpcio packages, try installing the latest version.
  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.

    Release

    Directory

    Junos OS Release 20.3R1 or later

    20.3

    Junos OS Evolved Release 22.4R1 or later

    junos-evolved/22.4
  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 or shell commands as appropriate.

Configure the User Account for the NETCONF or Shell User

To establish a NETCONF or shell session over outbound HTTPS, you must create a user account locally on the Junos device. You use this account to perform the NETCONF or shell 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 or shell sessions over outbound HTTPS.

Configure the Outbound HTTPS Clients

Enhanced outbound HTTPS enables you to configure multiple outbound HTTPS clients at the [edit system services outbound-https] hierarchy level and configure multiple backup gRPC servers for each client. The JET application connects to only one gRPC server in the client’s server list at any one time.

Before you configure the device, you will need the following information:

  • 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, if it’s self-signed, or the contents of the CA certificates, if the server certificate is authenticated using a certificate chain.

To configure an outbound HTTPS client:

  1. Navigate to the outbound HTTPS client hierarchy, and define an identifier that uniquely identifies the outbound HTTPS client.
  2. Define the device identifier, which is a user-defined string that the gRPC server uses to identify and authenticate the Junos device during session establishment.
  3. Define a shared secret string, which is a user-defined string that the gRPC server uses to authenticate the Junos device during session establishment.

    The device stores the shared secret string as an encrypted value in the configuration database.

  4. (Optional) Define the method used to reestablish a disconnected outbound HTTPS connection as sticky or in-order.
  5. (Optional) Define the time in seconds that the gRPC client waits in between attempts to connect to the outbound HTTPS client’s list of servers.
  6. Configure the hostname or IPv4 address for one or more gRPC servers and the port on which the server is listening for outbound HTTPS connection requests.

    The hostname or IP address must match the value of the Common Name (CN) field or the SubjectAltName IP Address field, respectively, in that gRPC server's certificate.

  7. For each gRPC server, configure the trusted_cert statement with the certificate information required to authenticate the server.

    • If the server’s certificate is self-signed, configure the contents of the gRPC server’s certificate, server.crt, omitting any newlines.

    • If the server’s certificate is authenticated using a certificate chain, concatenate any intermediate CA and root CA certificates in that order, remove all newlines, and configure the resulting single string.

    Note:

    To easily generate the value for the trusted_cert statement, you can concatenate the appropriate certificates in the required order and remove any newlines, for example, by using a command similar to the following:
  8. Repeat the preceding steps for each outbound HTTPS client that will manage the Junos device.
  9. Commit the configuration.
Note:

If the outbound HTTPS extension service is already running, and you add, delete, or modify an outbound HTTPS client and commit the configuration, you do not need to restart the service for the changes to take effect. They are picked up automatically.

Configure the Outbound HTTPS Extension Service on Junos Devices

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

Table 1: JET Files for Sessions over Enhanced Outbound HTTPS

File

Description

nc_grpc_app.pyc

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_app_lib.pyc

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. Configure extension service notifications for the loopback address.
  5. Navigate to the hierarchy of the extension service application.
  6. Configure the application to run in the background as a daemonized process.
  7. Configure the application to respawn on normal exit.
  8. Configure the usename under whose privileges the application executes and the NETCONF operations and shell commands are performed.
  9. Commit the configuration.

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

  10. 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. In Junos OS Evolved, issue the show trace application cscript and show log messages commands.

Start the NETCONF or Shell Session

The gRPC server running on the network management system acts as the NETCONF/shell client, and the JET application on the Junos device acts as the gRPC client and NETCONF/shell 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, you can then request one or more NETCONF or shell sessions.

Before you begin, you will need the following information:

  • The device identifier and shared secret string configured for the outbound HTTPS client

To establish a NETCONF or shell session over enhanced 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.
  2. To establish one or more sessions with a Junos device, execute the request_session.py script. Specify the session type as well as the device ID and shared secret that you configured for that outbound HTTPS client on the Junos device. For example:

    • To request a csh session, which is the default, you do not need to specify a session type.

    • To request a NETCONF session, include the -s netconf option.

    If the server successfully authenticates the Junos device, the requested session starts.

  3. Verify that the session is established by reviewing the output.

    • Shell sessions should display the csh session is started output, for example:

    • NETCONF sessions should display the NETCONF capabilities as shown here:

  4. Perform NETCONF or shell operations as necessary.
  5. When you are finished with the session, type Ctrl+C.
  6. 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.