ZTP Guide


ZTP Guide

  TCP-AO Configuration Guide   
Download PDF

1. Introduction to TCP-AO

BGP, which connects routers with a TCP session, does not benefit directly from packet-level authentication. Authentication in BGP is a critical concern because BGP carries routing information all over the global public internet, creating a tempting target for route-status hackers, and, at the same time, making the authenticity of inter- and intra-AS routing information absolutely essential.

An initial attempt at TCP authentication in RFC 2385 added an MD5 signature to the TCP segment header. The TCP option Kind field value of 19 (decimal) indicated the presence of the MD5 signature in the TCP segment header. It did not take long before the restrictive nature of the length and type of the protection became apparent. Simply put, this method quickly became outdated.

RFC 5925 replaced the older method with a more flexible and improved authentication technique, using TCP header option Kind 29 (decimal) to indicate use of the TCP authentication option (TCP-AO).

According to RFC 5925, TCP-AO added:

  • Stronger Message Authentication Codes (MACs)

  • Better protection against replays for the long-lived TCP sessions common between routers

  • A framework for the relationship between TCP authentication and security in general

The scope of the newer TCP-OA is indicated in the length of the RFCs: the 6 pages of RFC 2385 became 48 pages in RFC 5925. TCP-AO is compatible with the use of a Master Key Tuple (MKT), either static or with an out-of-band management technique. Both methods protect connections using the same MKT in repeated connection instances, as well as coordinating MKT changes between endpoints.

TCP-AO is compatible with the use of TCP MD5, but only with Kind = 29. However, if both Kind = 19 and Kind = 29 options appear in the same TCP header, or the header contains multiple Kind = 29 options, then the segment must be silently discarded.

The implications of TCP-AO use are considerable, such as the effects on TCP header size. For more information, see RFC 5925.

2. Implementation of TCP-AO

The RtBrick Full Stack (RBFS) supports three different MACs as described in RFC 5925:

  • MD5 (RFC 2385 compatible)

  • HMAC-SHA-1-96

  • HMAC-SHA-256-128

Sections in this chapter include:

  • TCP-AO Parameters

  • TCP-AO Key Rollover

2.1. TCP-AO Parameters

TCP-AO for RBFS uses a set of parameters. The parameters are all mandatory and configured under an authentication_identifier that provides a convenient way to package the TCP-AO options.

The individual parameters gathered under an authentication_identifier are:

local_ipv4_prefix—A valid IPv4 prefix from which the connection is created. local_ipv6_prefix—A valid IPv6 prefix from which the connection is created. remote_ipv4_prefix—A valid IPv4 prefix to connect to. remote_ipv6_prefix—A valid IPv6 prefix to connect to. local_port—The local port that the connection uses. remote_port—The remote port that the connection uses. authentication_type—The authentication method used, either MD5, HMAC-SHA-1-96, or HMAC-SHA-256-128. send_key—The secret key used by the sending side of the connection. send_key_id—An identifier for the send key. receive_key1—The primary key value expected from the other side of the connection. receive_key1_id—An identifier for the primary expected key value. receive_key2—The secondary key value expected from the other side of the connection. receive_key2_id—An identifier for the secondary expected key value.

As noted above, all parameters are mandatory. Wild card support is provided by configuring a particular authentication_identifier on port 0. This configuration applies the same configuration to all ports in the system. The parameters are applied as local or remote depending on connection initiation.

The IPv4 and IPv6 prefix parameters provide an opportunity to control the range of prefixes onto which authentication is applied.

The key identifiers are used as defined in RFC 5925, although not supported in MD5. MD5 support is maintained for consistency, but the key identifiers are ignored if the authentication type is MD5. This allows the user to easily change the authentication type from MD5 to others on the fly, as needed.

The secret key string is stored in an AES encrypted format within the system. When entering this field, the user must prepend the plain text format with a 0 so that the system understands the input is in plain text. The string 0rtbrick is an example of this usage. In this case, the actual password is rtbrick and the prepended 0 indicates the plain text style is used.

The password string is stored in the system as 11e4946e31b406de98b3077aef03ed5a7302930293293923209302932930293029 after encryption. This can be used as an input secret string for the remote system as well.

The command show tcp authentication summary instance displays the encrypted information for the given instance.

2.2. TCP-AO Key Rollover

Normally, a rollover to a new key value disrupts the TCP session. For seamless key rollover, two receive keys and identifiers need to be configured.

TCP-AO Receive Side Authentication
Figure 1. TCP-AO Receive Side Authentication

Figure 1 shows how an incoming TCP message is processed at the receiver. First, the message digest from the TCP packet needs to be located and extracted. Then, the message digest is computed and validated against the first receive key.

If this initial step results in an Auth-FAIL1 event, then the message digest based on the second receive key is computed and validated. If there is another failure (an Auth-FAIL2 event), then the TCP-message is discarded and the TCP-failed-Auth counter is incremented.

3. TCP-AO Configuration Example

This section of the document details the configuration and use of the TCP-AO feature for the RBFS.

Sections in this chapter include:

  • TCP-AO Topology

  • TCP-AO Configuration

3.1. TCP-AO Topology

The leaf/spine topology used in this example is shown in Figure 2.

The TCP-AO Example Topology
Figure 2. The TCP-AO Example Topology

In this topology:

  • Leaf-1 and Leaf-2 are routers sitting close to the servers. These routers can be the equivalent of ToR (Top of Rack) boxes in the case of data center implementation, or Provider Edge (PE) routers in a typical ISP environment.

  • Spine-1 and Spine-2 are the routers serving as route-reflectors, which distribute the routes across the leaf routers. They are connected to Core-1 and Core-2 routers (not included in this TCP-AO example). A BGP session runs between the Spine and Core routers.

  • Customer Edge (CE-1 and CE-2) or related aggregation devices are routers that connect to the leaf devices. Typically, a BGP VRF session runs between a Leaf and CE device.

Only the leaf and spine devices are used for this example. All the configurations and outputs are shown for the same devices. All leaf and spine system are running the RBFS software.

3.2. TCP-AO Configuration

The code box below shows the example configuration to configure TCP session authentication for a BGP setup.

Note CLI commands are not available for non-default instances. Bug 1918 tracks this issue.
{    "objects": [        {            "attribute": {                "authentication_identifier": "client",                "receive_key2_id": 2,                "receive_key2": "0rtbrick2", "receive_key1_id": 1,                "local_ipv4_prefix": "192.168.10.1/16",                "remote_ipv4_prefix": "192.168.10.2/16",                "local_port": 0,                "remote_port": 179,                "authentication_type": "MD5",                "send_key": "0rtbrick",                "send_key_id": 1,                "receive_key1": "11e4946e31b406de98b3077aef03ed5a7"                }          },            {             "attribute": {                   "authentication_identifier": "server",                   "receive_key2_id": 2,                   "receive_key2": "0rtbrick2",                   "receive_key1_id": 1,                   "local_ipv4_prefix": "192.168.10.1/16",                   "remote_ipv4_prefix": "192.168.10.2/16",                   "local_port": 179,                   "remote_port": 0,                   "authentication_type": "MD5",                   "send_key": "0rtbrick",                   "send_key_id": 1,                   "receive_key1": "11e4946e31b406de98b3077aef03ed5a7"                   },                    }                   ],                   "table": {                       "table_name": "vrf_6.tcp.auth.config"             }    }
Note The code box above shows two JSON objects embedded in a single configuration file, one for the server and one for the client. The server BGP session uses local port number 179 and the remote destination port can be any valid number, including 0. The port numbers for the client are the opposite: the local port is any valid number, including 0, and the remote port is 179. Both are required to match in this way for the session to activate.

Configurations can use the authentication types HMAC-SHA-1-96 or HMAC-SHA-256-128 as well.

The table name here is vrf_6.tcp.auth.config, indicating that this configuration applies to vrf_6.

In general, the table format to push the configuration to .tcp.auth.config. Please be sure to format the table name accordingly, because other forms are not supported.

4. TCP-AO Example Test Case

This section of the document shows how to bring up the authenticated BGP sessions and make sure that they are working properly.

Sections in this chapter include:

  • Baseline BGP Session Without Authentication

  • Configure TCP-AO Authentication

  • Verify TCP-AO Configuration

  • Verify Authenticated BGP Session Status

  • Verify Authenticated TCP Connection Status

4.1. Baseline BGP Sessions Without Authentication

Initially, the example topology has established BGP sessions, but without authentication. The command show bgp peer shows the status of the BGP sessions (in this case, between a leaf and the spine routers).

show bgp peer

For more information on configuring BGP on the RBFS software, see the BGP Configuration Guide.

4.2. Configure TCP-AO Authentication

The TCP-AO configuration for all device under test (DUT) boxes is shown below.

DUT: All boxes    Source IPv6 Address: fe80::/16    Remote IPv6 Address: fe80::/16    Source port : 0    Destination Port : 179    Configuration parameters.        Authentication Type : MD5        Send Key : 0rtbrick        Receive Key1 : 11e4946e31b406de98b3077aef03ed5a7302930293293923209302932930293029        Receive Key2 : 0rtbrick_alternate     Source IPv6 Address: fe80::/16    Remote IPv6 Address: fe80::/16    Soucre port : 179    Destination Port : 0    Configuration parameters.        Authentication Type : MD5        Send Key : 0rtbrick        Receive Key1 : 11e4946e31b406de98b3077aef03ed5a7302930293293923209302932930293029        Receive Key2 : 0rtbrick_alternate

4.3. Verify TCP-AO Configuration

The TCP-AO configuration is displayed with the show tcp authentication summary command.

Here is the result for leaf1:

show tcp auth summary leaf1

Here is the result for spine1:

show tcp auth summary spine1

Verify that all parameters are correct.

4.4. Verify Authenticated BGP Session Status

After TCP-AO configuration and application, the BGP sessions should still be up and established. BGP session status is displayed with the show bgp peer command.

show bgp peer verify

The same status should be displayed for the other leaf and spine devices.

4.5. Verify Authenticated TCP Status

After TCP-AO configuration and application, the TCP connections should display authentication flags and options. TCP connection and session status is displayed with the show tcp status detail command.

show tcp status detail

The same status should be displayed for the other leaf and spine devices.

5. Stressing the TCP-AO Example

This section of the document shows how configuration changes can force TCP-AO to take certain actions.

Sections in this chapter include:

  • Force Use of Receive Key2

  • Force Key Mismatch

  • Change Authentication Type

5.1. Force Use of Receive Key2

Up to this point, the example topology has established BGP sessions using TCP-AO. The command show bgp peer shows the status of the BGP sessions. If the configuration send key changes, but still matches the second receive key, the connection re-establishes itself, and does not flap.

To demonstrate this, change the configuration on Spine1 to use 0rtbrick_alternate as the send key. This change is shown in bold.

DUT: Spine1    Source IPv6 Address: fe80::/16    Remote IPv6 Address: fe80::/16    Source port : 0    Destination Port : 179    Configuration parameters.        Authentication Type : MD5        Send Key : 0rtbrick_alternate        Receive Key1 : 11e4946e31b406de98b3077aef03ed5a7302930293293923209302932930293029        Receive Key2 : 0rtbrick_alternate

This new configuration forces the connection to re-establish with the alternate key, which is shown using the show tcp authentication summary command on Spine1.

show tcp auth summary force

The authentication-secret-mismatch counter should be zero. This can be shown by dumping the contents of the global.tcp.auth.statistics, as shown below.

show datastore table dump

5.2. Force Key Mismatch

If the configuration send key changes to a key that the receiver does not recognize at all, the connection will flap and not re-establish itself.

To demonstrate this, change the secret key on a system such as Spine1 to send a key not configured on another system. Spine1 should log authentication-secret-mismatches, so the counter should be greater than 0.

To revert to the established session state, change the send key configuration back to one of the two valid send keys. The authentication-secret-mismatches counter should stabilize and stop incrementing.

5.3. Change Authentication Type

If the configuration Authentication Type changes from MD5 to SHA-1 or SHA-2, the sessions do not log authentication-secret-mismatches, but log authentication-algo-mismatches.

In other words:

  • The authentication-secret-mismatches counter remains stable or 0

  • The authentication-algo-mismatches counter increments

Changing the configuration back to matching authentication algorithms re-establishes the session and stabilizes the counters.

6. Deleting TCP-AO

This section of the document shows what happens when TCP-AO is deleted.

If TCP-AO is removed, the session should flap and not be re-established until both end systems of the connection match configurations again.

Check the session uptime to make sure the session has failed.

The assumption for lossless behavior is that the TCP stack silently discards (ignores) the following:

  • Unauthenticated segments

  • Authenticated segments when no authentication is configured

Both sides will retransmit until both ends of the session are configured with matching authentication configurations.

7. Troubleshooting TCP-AO

This section of the document shows how to address TCP-AO issues. There are a couple of things to check if TCP-AO results are not what is expected.

  • Most TCP-AO configuration-related issues can be caught through logging. To enable the logging, use the following command:

    set tcp log-level 5
  • Log levels can be from 1 to 5, which have increasing order of verbosity. You can display the log messages stored in /var/log/upstart/.log

  • Make sure that TCP-AO configurations are applied on the sessions of interest. Check that by displaying the TCP sessions and making sure that all options are set. Display the TCP status detail with the show tcp status detail command.

Make sure to apply the configurations for both server and client end for protocol sessions such as BGP.

Let us know if you find any other useful tips!


©Copyright 2019 RtBrick, Inc. All rights reserved. The information contained herein is subject to change without notice. The trademarks, logos and service marks ("Marks") displayed in this documentation are the property of RtBrick in the United States and other countries. Use of the Marks are subject to RtBrick’s Term of Use Policy, available at https://www.rtbrick.com/privacy. Use of marks belonging to other parties is for informational purposes only.

test

  Zero-Touch Provisioning (ZTP) Guide   
Download PDF

1. Introduction to ZTP

A major goal in any network is a high level of automation. This includes the automatic provisioning of switches newly installed in the network, a process known as Zero-Touch Provisioning (ZTP).

A new switch comes preinstalled with the Open Network Installation Environment (ONIE). The ONIE is an open source installation environment that acts as an enhanced boot loader utilizing facilities in a Linux/BusyBox environment. This small Linux operating system allows end-users and channel partners to install the target network OS as part of provisioning.

Because ONIE needs the ability to obtain configuration and image binaries through the management interface, a management LAN is required.

ONIE has access only to the management interface. ONIE starts a DHCP-based discovery process to obtain basic configuration information, such as the management IP address and the URL of the image to install on the switch. ONIE pulls the image and boots it, all without manual intervention.

However, even after the ONIE boots the image, the switch is not yet configured. For configuration, the RtBrick images come with some preinstalled daemons. One, the preinstalled Control Daemon (CtrlD), is responsible for the management of the switch, and another preinstalled daemon, the ZTP Daemon (ZTPD), is the daemon which takes over after the image is activated. The ZTP daemon is responsible for configuring the switch properly.

To do this, hardware box needs to connect to a DHCP server and a management server through the management LAN. The management server is responsible for providing the image binaries and the configuration of each device.

In summary, there are three basic steps to ZTP operation:

  1. Discover the IP address through DHCP.

  2. Get the image with HTTP.

  3. Activate the image configuration and boot it, also with HTTP.

2. ZTP in a Nutshell

This document provides a brief overview of Zero-Touch Provisioning (ZTP) and discusses the managed ZTP process as a ZTP application in the RtBrick Management System (RBMS). The focus is on the REST APIs of the RBMS ZTP application itself, and the management server hosting the actual ZTP service.

Some of these sections discuss how to provision the management server. By the end of this document, we show how ONIE fetches the images.

2.1. The ZTP Process

ZTP is a DHCP-based process driven by ONIE. ONIE is preinstalled on a white box switch. Figure 1 shows the overall ZTP process.

The Overall ZTP Process
Figure 1. The Overall ZTP Process

The management server runs a DHCP service and a local image repository accessible through HTTP. The complete ZTP process takes place in three distinct steps.

  1. ONIE uses DHCP to discover the IP address along with basic device configuration.

  2. ONIE determines the image download URL based on the provided DHCP options. For download, ONIE allows different ways to pull an image from the repository. In this ZTP process, HTTP is used to pull the image because ONIE conveys the serial number as the HTTP header. This serial number allows the image repository to identify the switch and select the appropriate image

  3. The final step is to activate the image and the RBFS container. The container in turn fetches the application configuration from the image repository.

3. The ZTP Management Server

The management server is responsible for bootstrapping a hardware device, such as a white-box switch.

3.1. Management Server Architecture

Two services are provided by the management server, as required by ONIE:

  • The DHCP service assigns an IP address to the switch.

  • The HTTP service delivers the NOS image and startup configuration.

This architecture leverages standard software to implement both services, and to configure them to satisfy the ONIE requirements. Figure 2 illustrates the management server components as well as the interactions with RBFS, RBMS, and image repository.

 
The ZTP Management Server Architecture
Figure 2. The ZTP Management Server Architecture

3.2. DHCP Service for ZTP

Because of its low set of requirements, the default DHCP server shipped with ubuntu, isc-dhcp, is used to run the DHCP service.

3.3. HTTP Service for ZTP

The HTTP service is implemented as a transparent proxy. The proxy tries to pull images and configuration from the image repository and the RBMS respectively. If the image repository or RBMS are not reachable, then the proxy uses a local fallback.

The HTTP service is implemented using nginx, an open-source HTTP Server. The nginx is configured to read the ONIE_SERIAL_NUMBER HTTP header and maps the serial number to the NOS installer image download path. The mapping configuration is generated by the management server provisioning scripts.

Nginx supports modularized configuration. This means that the mapping configuration can be generated and isolated from the general nginx configuration, but included when needed. This helps configuration management because only the mapping configuration needs to be generated.

4. The ZTP Daemon (ZTPD)

The ZTPD is a post-ZTP daemon, which means that it runs after the image is activated. This daemon is responsible for configuring the switch properly.

4.1. Running ZTPD

In a production environment, the ztpd binary starts with default parameters. The service is called rtbrick-ztpd. Key parameters for ZTPD are shown below.

$ ztpd -h Usage of ztpd:  -addr string        HTTP network address (default "localhost:19092")  -dhcp        Runs dhcp logic  -onl string        onl base folder (default "/lib/platform-config/current/onl")  -serial        Runs serial logic  -syslog string        syslog file (default "/var/log/syslog")  -run      Runs the whole ztp logic  -e string      Element Name only needed if run is active  -c string      Container Name, only needed if run is active  -version        Returns the software version

To get the installed version, use the ztpd -version command.

4.2. ZTPD-CTRLD-RBFS Inter-Process Communication

Figure 3 shows the inter-process communication between ZTPD and the service that ZTPD relies on., CTRLD and RBFS.

ZTPD Inter-Process Communication with CTRLD and RBFS
Figure 3. ZTPD Inter-Process Communication with CTRLD and RBFS

ZTPD subscribes to CTRLD for the event “ContainerOperationalStateChangedToUp.” This means that ZTPD is informed when an RtBrick container has an operational state of up.

When the container is up, ZTPD tries to configure the container.

The management server stores the configurations and provides the IP address of the DHCP server. Because all configurations are bound to the serial number, the device serial number is also needed to get the right configuration for the box.

The configurations are downloaded from the management server and the configuring is performed by CtrlD.

It is important to note that the subscription from ZTP to CtrlD is periodic. That is, communication takes place every 60 seconds. This repetition is needed because the subscription is stateless, meaning CtrlD stores the subscription information only in memory. After a restart of CtrlD this information is gone, and a new subscription must be done.

This is a well-known pattern in the microservices domain, and helps promote better resilience of the ecosystem.

The following configurations are stored at the management server:


  1. Startup Configuration


  2. Cmd Configuration


  3. Element Configuration


  4. CTRLD Configuration


4.2.1. Startup Configuration

The startup configuration is the running-configuration of the RBFS switch.

This configuration must be reachable at /ztp/config/startup

4.2.2. Cmd Configuration

ZTPD can load a text or plain file from the /ztp/config/ctrld location.

This file contains commands that are executed in the RBFS bash.

Here is an example file:

ls -la | grep var rtb confd show running-configuration

Each line is executed against the RBFS.

4.2.3. Element Configuration

The element config must be reachable at /ztp/config/element.

This configuration sets the element name and the PoD name in the container. The element name is used to identify the container to the RBMS.

Here is an example file:

{    "element_name": "element_name",    "pod_name": "pod2" }

4.2.4. CTRLD Configuration

Th e CtrlD must be reachable at /ztp/config/ctrld.

A detailed description of this configuration can be found in the CtrlD documentation.

4.3. Log Files

The relevant log files can be found here:


  • /var/log/rtbrick-ztpd.log



©Copyright 2019 RtBrick, Inc. All rights reserved. The information contained herein is subject to change without notice. The trademarks, logos and service marks ("Marks") displayed in this documentation are the property of RtBrick in the United States and other countries. Use of the Marks are subject to RtBrick’s Term of Use Policy, available at https://www.rtbrick.com/privacy. Use of marks belonging to other parties is for informational purposes only.