How to Configure NETCONF or Shell Sessions over Outbound HTTPS

Understanding NETCONF and Shell Sessions over Outbound HTTPS

• Benefits of NETCONF and Shell Sessions over Outbound HTTPS

• NETCONF and Shell Sessions over Outbound HTTPS Overview

• Connection Workflow for Sessions over 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 devices running Junos OS 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.

The Junos OS with upgraded FreeBSD 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 HTTPS

In this scenario, the gRPC server acts as the NETCONF or shell client, and the JET application is the gRPC client and NETCONF or 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 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 devices running Junos OS, the gRPC server must have a valid X.509 certificate.

Table 1 outlines the features supported for sessions over outbound HTTPS for a given Junos OS release. Devices running Junos OS Release 20.3 and later support multiple outbound HTTPS client connections; configuring one or more backup gRPC servers for a client; and establishing multiple, concurrent NETCONF and shell sessions between the outbound HTTPS client and device running Junos OS.

Connection Workflow for Sessions over Outbound HTTPS

In a NETCONF or shell session over outbound HTTPS, the gRPC server running on the network management system acts as the NETCONF or shell client, and the JET application on the device running Junos OS is the gRPC client and NETCONF or shell server. Starting in Junos OS Release 20.3, 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. You can establish multiple, concurrent NETCONF and shell sessions with that gRPC server in releases that support multiple sessions.

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. On devices running Junos OS Release 20.3R1 or later, the gRPC client sends the device ID and shared secret configured for that outbound HTTPS client to the gRPC server.

7. The NETCONF or shell session is established as follows:

   • For connections to devices running Junos OS Release 20.2, a single NETCONF session is automatically established.

   • For connections to devices running Junos OS Release 20.3R1 or later, the outbound HTTPS client requests a NETCONF or shell session, and the gRPC server uses the device ID and shared secret to authenticate the device running Junos OS. 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.

If the device is running Junos OS Release 20.3R1 or later, 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 device running Junos OS.

How to Establish NETCONF and Shell Sessions over Outbound HTTPS

You can use the JET application that is included as part of the Junos OS with upgraded FreeBSD software image to establish NETCONF and shell sessions over outbound HTTPS between network management systems (NMS) and supported devices running Junos OS. 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 or shell client, and the JET application is the gRPC client and NETCONF or shell server.

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

• Network management system running Python 3.5 or later

• Device running Junos OS with upgraded FreeBSD Release 20.2 or later that also supports running Juniper Extension Toolkit (JET) applications

  Note

  If you are unsure if your device supports upgraded FreeBSD, see Feature Explorer: Junos kernel upgrade to FreeBSD 10+.

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

Figure 2: NETCONF 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:

1. Obtain an X.509 Certificate for the gRPC Server

2. Set Up the gRPC Server

3. Configure the User Account for the NETCONF or Shell User

4. Configure the Outbound HTTPS Client (Junos OS Release 20.2)

5. Configure the Outbound HTTPS Clients (Junos OS Release 20.3R1 and later)

6. Configure the Extension Service for Outbound HTTPS on Devices Running Junos OS

7. Start the NETCONF or Shell Session

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.

• To connect to devices running Junos OS Release 20.2, the certificate must be self-signed.

  To connect to devices running Junos OS Release 20.3 or later, 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 device running Junos OS must use the same value to establish the connection to the server. If the SubjectAltName IP Address field is defined, the Common Name field is ignored 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.
   user@nms:~$ openssl genrsa -out server.key 4096
   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.
   user@nms:~$ cat openssl.cnf
3. Generate a certificate signing request (CSR), which contains the client’s public key and information about their identity.
   user@nms:~$ openssl req -new -key server.key -out server.csr
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.

     user@nms:~$ openssl x509 -req -in server.csr -CA RootCA.crt -CAkey RootCA.key -set_serial 0101 -out server.crt -days 365 -sha256 -extfile openssl.cnf

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

     user@nms:~$ openssl x509 -req -in server.csr -signkey server.key -out server.crt -days 365 -sha256 -extfile openssl.cnf
5. Verify that the Common Name (CN) field and extensions, if provided, are correct.
   user@nms:~$ openssl x509 -text -noout -in server.crt
6. (Optional) To manage devices running Junos OS Release 20.2, 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.
   user@nms:~$ scp server.crt <device-hostname-or-ip>:/var/db/scripts/jet
   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 device running Junos OS.

Set Up the gRPC Server

The network management system and the JET application on the device running Junos OS 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.

The network management system requires the following software:

• Python 3.5 or later

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.

1. Install pip for Python 3.
   user@nms:~$ sudo apt install python3-pip
2. Install the grpcio package.
   user@nms:~$ sudo pip3 install grpcio==1.29.0
3. Install the grpcio-tools package.
   user@nms:~$ sudo pip3 install grpcio-tools==1.18.0
4. Go to the Juniper GitHub repository at https://github.com/Juniper/netconf-https-outbound, and select the directory corresponding to the Junos OS release running on the managed devices.

   • For Junos OS Release 20.2, select the 20.2 directory.

   • For Junos OS Release 20.3 and later, select the 20.3 directory.

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.

   user@nms:~$ ls
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.
   user@nms:~$ python3 -m grpc_tools.protoc -I./ --python_out=. --grpc_python_out=. filename.proto

   For example, to compile the files to use with devices running Junos OS Release 20.3 or later, issue the following commands:

   user@nms:~$ python3 -m grpc_tools.protoc -I./ --python_out=. --grpc_python_out=. jnx_common_base_types.proto

   user@nms:~$ python3 -m grpc_tools.protoc -I./ --python_out=. --grpc_python_out=. jnx_netconf_service.proto

   user@nms:~$ ls jnx*.py
7. Start the gRPC server, and specify the port for the connection, if it’s different from the default port 443.
   user@nms:~$ python3 nc_grpc_server.py -p 50051
   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 device running Junos OS 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 first create a user account locally on the device running Junos OS. 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.

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 device running Junos OS where the client needs to establish NETCONF or shell sessions over outbound HTTPS.

Configure the Outbound HTTPS Client (Junos OS Release 20.2)

In Junos OS Release 20.2, the JET application can only connect to a single outbound HTTPS client, and you configure the connection and authentication information for the client as command-line arguments to the JET script. Table 2 outlines the arguments.

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

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 Clients (Junos OS Release 20.3R1 and later)

Starting in Junos OS Release 20.3R1, you can configure multiple outbound HTTPS clients at the [edit system services outbound-https] hierarchy level, and you can 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.

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

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 device running Junos OS during session establishment.
3. Define a shared secret string, which is a user-defined string that the gRPC server uses to authenticate the device running Junos OS during session establishment.
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 device running Junos OS.
9. Commit the configuration.

Configure the Extension Service for Outbound HTTPS on Devices Running Junos OS

On devices running Junos OS with upgraded FreeBSD that also support the Juniper Extension Toolkit (JET), the software image includes files that support NETCONF or shell sessions over outbound HTTPS. Table 3 outlines the files, which are located in the /var/db/scripts/jet directory on supported devices.

1. Verify that the JET application and related files are present on the device.
   user@R0> file list /var/db/scripts/jet/nc*
2. Enter configuration mode.
3. Enable the device to run unsigned Python 3 applications.
4. On devices running Junos OS Release 20.3R1 or later, configure extension service notifications for the loopback address.
5. Navigate to the hierarchy of the extension service application, and ensure that the filename, as defined in Table 3, is correct for your release.
6. Configure the application to run as a daemonized process in the background.
7. Configure the application to respawn on normal exit.
8. Configure the usename under whose privileges the application will execute and the NETCONF operations and shell commands will be 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.
    user@R0> show extension-service status nc_grpc_app.pyc

Start the NETCONF or Shell Session

The gRPC server running on the network management system acts as the NETCONF or shell client, and the JET application on the device running Junos OS acts as the gRPC client and NETCONF or 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, the establishment of the NETCONF or shell session depends on the Junos OS release.

• When managing devices running Junos OS Release 20.2, the NETCONF session starts automatically.

• When managing devices running Junos OS Release 20.3R1 or later, you must request the session and specify the device ID, shared secret, and session type.

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

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 script output varies for different releases.
   user@nms:~$ python3 nc_grpc_server.py -p 50051

   When managing devices running Junos OS Release 20.2, the NETCONF session starts automatically.

2. To establish one or more sessions with a device running Junos OS Release 20.3R1 or later, execute the request_session.py script, and specify the session type as well as the device ID and shared secret that you configured for that outbound HTTPS client on the device running Junos OS. For example:

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

     user@nms:~$ python3 request_session.py -d router1 -sk my-shared-secret

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

     user@nms:~$ python3 request_session.py -d router1 -sk my-shared-secret -s netconf

   If the authentication of the device running Junos OS is successful, the requested session starts.

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

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

   • Shell sessions should display the csh session is started output, for example:
4. Perform NETCONF or shell operations as necessary.
   <rpc><get-configuration/></rpc>
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 device running Junos OS by deleting or deactivating the relevant hierarchy in the configuration and then committing the change.