Deploy Router Using Bootz

With the Bootz process, you can securely and seamlessly provision network devices accurately within minutes and without any manual intervention.

Table 1. Feature History Table

Feature

Release Information

Feature Description
Provisioning Using Bootz Process

Release 7.11.1

This feature allows devices in the network to establish a secure connection with the remote Bootz server and authenticate information using a three-step validation process. This process involves validating the network device, the Bootz server, and the onboarding information thereby mitigating security risks and preventing malicious actions during remote provisioning.

Unlike the Secure ZTP process, which relies on vendor-specific definitions for bootstrapping a device, the Bootz process offers a specification that outlines data elements in a vendor-agnostic manner. It also details the necessary operations at turn-up time, integrating them into the boot process.

Also, the bootstrap request in the Bootz process includes the unique identifier or serial number for each node as opposed to the Secure ZTP process where the bootstrap request does not include serial numbers. The Bootz server returns the signed onboarding information with ownership voucher and owner certificate for the requested serial number of the device.

Supported Bootz Versions

This table provides the Bootz versions supported in each release. The Bootz Bootstrap server must be compatible with the respective Bootz version.

Table 2. Bootz Versions

Release

Version with File Path
Release 24.4.1

openconfig/bootz v0.3.1
Release 24.2.1

openconfig/bootz v0.1.1-0.20231106050618-8d6e2559f803
Release 24.1.1

openconfig/bootz v0.0.0-20230809153947-e6bc0be82dd8
Release 7.11.1

openconfig/bootz v0.1.0

Components used in the Bootz Process

These components are part of the Bootz process.

  • Onboarding Device (Router): A router is a Cisco device that you want to provision and connect to your network. Bootz is supported only on platforms that have Hardware TAM1 support.

  • DHCP Server: The DHCP server provides the URL where the Bootz process can access the bootstrapping information.

  • MASA Server: You can generate and store the ownership voucher in the MASA server. The MASA server sends the ownership voucher to the Bootz server so that the Bootz process validates the device and establishes device ownership.

  • Bootz Bootstrap Server: A Bootz Bootstrap server is any gRPC server used as a Bootz bootstrapping data source. For example, Google Proto. The Bootz Bootstrap server is complaint with Openconfig Bootz standards.


    Note

    Bootz only supports a single name-server. As a result, when the DHCP server has more than one server address configured, Bootz fails to apply the server configuration.

    The Bootz server contains these artifacts:

    • Cisco IOS XR software images: You can download Cisco images, SMU, and patches from the Cisco Support & Downloads page.

    • Bootstrapping Data: It is a collection of data that you have created and uploaded to the Bootz server. The router obtains this data from the Bootz server during the provisioning process.

      Starting with IOS XR Release 24.4.1, the bootstrap configuration remains immutable throughout the device's operation. For more information, refer the topic Immutable bootstrap configuration.

Onboard Devices Using Bootz Workflow

The Cisco IOS XR software supports Bootz provisioning capabilities. The Bootz process uses the Google Remote Procedure Call (gRPC) protocol for fetching information from a remote server.

The Bootz workflow performs these validations to onboard the remote devices securely.

  1. Router Validation: The Bootz server authenticates the router before providing the bootstrapping data.

  2. Server Validation: The router in turn validates the Bootz server and ensures that the onboarding is performed for the correct network. Once it is validated, the Bootz server sends the bootstrapping data (for example, a YANG data model) or artifact to the router.

  3. Artifact Validation: The router validates the bootstrapping data or artifacts received from the Bootz server.

This figure provides the Bootz workflow and the processes involved in the workflow. The sections that follow describe these processes in detail.

Figure 1. Bootz Workflow

Obtain Ownership Voucher

The ownership voucher is used to identify the owner of the device by verifying the owner certificate stored in the device.

How to obtain Ownership Voucher

These steps help you obtain the ownership voucher from Cisco:

  1. Contact Cisco Support.

  2. Provide these information in your request to Cisco.

    • Pinned Domain certificate (PDC): PDC is an X.509 v3 certificate structure that uses Distinguished Encoding Rules (DER). The router uses this certificate to trust a public key infrastructure for verifying a domain certificate supplied to the router separately in the bootstrapping data. This certificate could be an end-entity certificate, including a self signed entity.

    • Purchase order details with the serial numbers of the routers.

    Sample Request:

    
    { ​​
       "expires-on": "2016-10-21T19:31:42Z", ​​
       "assertion": "verified", ​​
       "serial-number": "JADA123456789", ​​
       "idevid-issuer": "base64encodedvalue==", ​​
       "pinned-domain-cert": "base64endvalue==", ​​
       "last-renewal-date": "2017-10-07T19:31:42Z" ​​
    } ​​

  3. Cisco generates the ownership voucher in .vcj format (Example: DCA213140YX.vcj) and sends the voucher in response to your request.

Build bootstrapping data

Bootstrapping data is the configuration data that

  • the router retrieves from the Bootz server using gRPC protocols

  • configures and sets up the router during its initial boot sequence

  • comprises of parameters such as gRPC services to be run and the management connectivity setup, and

  • is immutable after the initial router boot up, from IOS XR Release 24.4.1 onwards. For more information, see Immutable bootstrap configurations.

Steps to build the bootstrapping data:

  1. Create and upload the bootstrapping data to the gRPC server or Bootz bootstrap server.

  2. The router sends a bootstrap request with these artifacts to the Bootz server.

    • Serial number of the control card or line card

    • Software image to download and install

    • Bootloader Password for the device

    • Certificate used to validate the bootstrap server

    • Bootstrap server configuration information such as server credentials, path information, authentication information, and certificates

    For the request message format, see the Bootstrap Request Message.

  3. The Bootz server returns the listed bootstrapping data in its response to the router. The router receives these data during the provisioning process.

    • Signed Bootstrap Response: Each bootstrap response contains the onboarding information for:

      For the response message format, see the Bootstrap Response Message for a single card.

    • Owner Certificate: The owner certificate is installed on the router with your organization's public key. The router uses this public key in the owner certificate to verify the signature in the signed bootstrap response artifact.

    • Ownership Voucher: The ownership voucher is used to identify the device owner by verifying the owner certificate stored in the device. Cisco generates and supplies the ownership voucher in response to your request containing the PDC and device serial numbers. For more information, see How to obtain Ownership Voucher.

  4. When the router obtains the onboarding information from the Bootz server, the router reports the bootstrapping progress to the Bootz server using the API calls.

Provision Bootz Using DHCP Server

When you boot the device, the Bootz process initiates automatically on a device without prior configuration. During the process, the router receives the details of the configuration file from the DHCP server.

This figure illustrates the end-to-end sequence of the Bootz process:

Figure 2. End-to-end sequence of the Bootz process

Before you begin

As part of the initial setup for secure ZTP, the network administrator:

  • Ensures to enable secure ZTP on the router using the ztp secure-mode enable command and reload the router.

  • Contacts Cisco Support and follows the steps in How to obtain Ownership Voucher to obtain a voucher from Cisco.

Procedure

Step 1

Upload the listed bootstrapping data to the Bootz server. Refer to your vendor documentation as the upload procedure may vary from server to server.

  • Cisco IOS XR software images

    Note

     

    Download Cisco images, SMU, and patches from the Cisco Support & Downloads page.

  • Serial numbers of the routers to be onboarded

  • Owner certificates

  • Pinned Domain Certificate (PDC)

  • Ownership vouchers

Step 2

Set up the DHCP server to provide the redirect URL to the router:

Before triggering the secure ZTP process, configure the DHCP server so that it provides the location of the IOS-XR image to the router. For information about how to configure the DHCP server, see your DHCP server documentation.

Configure these parameters in the DHCP server:

  • option-code: Use one of these DHCP SZTP redirect option parameters in the option-code setting.

    • OPTION_V4_SZTP_REDIRECT (143): DHCP v4 code for IPv4.

    • OPTION_V6_SZTP_REDIRECT (136): DHCP v6 code for IPv6.

  • option-length: Provide the option length in octets.

  • bootstrap-servers: A list of servers. The onboarding device contact these servers for the bootstrapping data. 

    "bootz://<ip-address-or-hostname>[:<port>]<endpoint>"

Example: option dhcp6.bootstrap-servers code 136 = text;

Step 3

Power on the router.

This procedure provides the high-level workflow of the Bootz process:

  1. When you boot the device with an IOS-XR image, the secure ZTP process verifies if the secure ZTP mode (secure-ztp mode) is enabled. If not enabled, the device boots normally.

    Note

     

    When secure-ztp mode is enabled, the ZTP process accepts only the secure-redirect-URL and ignores the presence of the boot file name option from the DHCP response.

  2. DHCP discovery:

    1. The router initiates a DHCP request to the DHCP server.

    2. The DHCP server responds with a DHCPv4 143 address option (for IPv4 addressing) or a DHCPv6 136 option (for IPv6 addressing).

    Note

     

    URLs to access bootstrap servers for further configuration are listed in options 136 and 143.
    Figure 3. DHCP discovery
    Router and DHCP server discovery with associated message options

  3. Router and Bootz server validation:

    1. After receiving the URL from the DHCP server, the router initiates a gRPC connection to the Bootz server. The Bootz server IP address is obtained from the DHCP response.

    2. The Bootz server authenticates the router before it provides the bootstrapping data.

    3. After the Bootz server authenticates the router or the onboarding device, the router validates the Bootz server to ensure that the onboarding is performed for the correct network.

      After validating the Bootz server, the router sends the serial number for each control card or line card and other artifacts in its bootstrap request.

    4. After its validation, the Bootz server sends the required artifacts along with the bootstrap response data to the router or the onboarding device.

  4. Ownership Voucher verification:

    The router receives the bootstrap response data that contains owner certificate, ownership voucher for each serial number, and the details of the image upgrade, if any.

    Bootstrap response data includes the following:

    • Image path

    • Image version

    • Trust anchor

    • Boot configuration

    • GNSI artifacts

    These artifacts come from the Bootz server as a bootstrap response gRPC message. The router verifies the ownership voucher by validating its signature to one of its preconfigured trust anchors and downloads the image. When the router obtains the onboarding information, it reports the bootstrapping progress to the Bootz server.

  5. Artifact Validation:

    The router validates the artifacts received from the Bootz server as follows:

    1. The device extracts the pinned-domain-cert node, an X.509 certificate from the ownership voucher to verify the owner certificate.

    2. The device authenticates the owner certificate by performing the X.509 certificate path verification process on the trusted certificate.

    3. Finally, the device verifies whether the artifact is signed by the validated owner certificate.

  6. Provision the device:

    1. The device first processes the boot image information.

    2. Executes the script and then onboards the artifacts received from the Bootz server.

  7. After the onboarding process is completed, the network device is operational.

Immutable bootstrap configuration

Immutable bootstrap configuration is the tamper-proof boot configuration of the router that

  • remains static, and

  • is not affected by subsequent dynamic configuration changes by gRPC Network Management Interface (gNMI).

Table 3. Feature History Table

Feature

Release Information

Feature Description
Immutable bootstrap configuration Release 24.4.1

Introduced in this release on: NCS 5500 fixed port routers; NCS 5700 fixed port routers; NCS 5500 modular routers (NCS 5500 line cards; NCS 5700 line cards [Mode: Compatibility; Native]

You can now ensure your router always boots up in a known good state. This feature prevents unauthorized changes to the router's boot configuration, ensuring that it remains static and tamper-proof. This maintains the integrity and security of the router from the initial boot stage and throughout its entire operation.

Benefits of immutable bootstrap configuration

The benefits of an immutable bootstrap configuration are quite significant in the context of network device operation and management.

  • Security and stability: Since the immutable bootstrap configuration remains unchanged after the initial setup, it ensures that the device's foundational settings are secure and stable. This reduces the risk of unauthorized changes or accidental misconfigurations.

  • Consistent boot up: By maintaining a static configuration, the device can consistently boot into a known good state. This consistency is crucial for reliable network operations and troubleshooting.

Key features of immutable bootstrap configuration

These are the key features of immutable bootstrap configurations.

  • Upon successful Bootz completion, the boot configuration file is stored as backup in the router. The router preserves this backup file across reloads. The boot configuration commit appears in the router's commit history as the user local in the output of the show configuration commit list command.

  • The router does not allow gNMI to override the boot configurations.

  • The router does not allow configuration changes for security credentials managed by gRPC Network Security Interface (gNSI) to be overwritten by gNMI or boot configuration. This means that gNSI owns the configurations for security credentials, and you must invoke gNSI to mutate this store.

  • The router allows configuration changes through Command Line Interface (CLI) to take effect on the boot configuration. However if you perform a Route Processor Fail Over (RPFO), gNMI Set operation, or restart the Extensible Manageability Services Daemon (EMSD) process using the process restart emsd command, the boot configuration is restored. The EMSD process is the process that initializes and manages the gRPC server and services on the router.

  • The gNOI.Bootz service manages boot configuration store completely. If you need to modify the boot configuration you must call the Set RPC through the gNOI bootconfig service.

Limitations of immutable bootstrap configuration

These are the limitations of immutable boostrap configuration:

  • When you modify any of the parameters of the boot configuration using CLI, the router applies the changes. To revert the boot configuration to the original state, perform any one of the these operations:

    • RPFO

    • gNMI Set operation, or

    • restart of the EMSD process using the process restart emsd command.

  • Due to the absence of a vendor-neutral boot configuration data set, the immutable bootstrap configuration may differ depending on the vendor of the network device.

  • Boot configurations cannot be altered via gNMI set operations. This restriction is vital for safeguarding critical settings like hardware-module configurations and user credentials from accidental removal.

Verify immutable bootstrap configuration on the router

Use this procedure to view and verify the immutable bootstrap configuration.

Before you begin

Ensure the router is booted up and provisioned with the Bootz process.

Procedure

Step 1

Enter the show configuration commit list command to view the list of configurations commited.

Example:

Router# sh configuration commit list 3
SNo. Label/ID              User      Line                Client      Time Stamp
~~~~ ~~~~~~~~              ~~~~      ~~~~                ~~~~~~      ~~~~~~~~~~
1    1000000011            local     ems                 YANG Frame  Thu Nov 14 12:26:26 2024
2    1000000010            cisco     con0_RP0_CPU0       CLI         Thu Nov 14 12:23:14 2024
3    1000000009            local     ems                 YANG Frame  Thu Nov 14 05:55:50 2024

The router commits the bootstrap configuration as User local .

From the output of show configuration commit list , note the specific Label/ID listed for the User local .

Step 2

Enter the show configuration commit changes command with the Label/ID noted in the previous step, to view the list of bootstrap configurations.

Example:

Router# sh configuration commit changes 1000000011
!! Building configuration...
!! IOS XR Configuration 24.4.1
hostname cisco
username cisco
 group root-lr
 group cisco-support
 secret 10 $6$8J3HfJlo8Ah0f...$gG5juuKsunhYwcH1rRRdq2UHPk/VUxVGjVHRLAhrUFlyOoiBRjQFVdDhgYlfuOJDRmAfLv1H4AaOZX8xHrBp20
!
grpc
 no-tls
!
interface MgmtEth0/RP0/CPU0/0
 ipv4 address dhcp
!
router static
 address-family ipv4 unicast
 0.0.0.0/0 MgmtEth0/RP0/CPU0/0 192.168.122.1
 !
!
ssh server v2
end
1 A secure storage device that stores the customer certificates and Cisco's internal secure data like trust anchors, SUDI certificates, secure flags, and other security information.