Configuration management

Default configuration

At startup, the SR Linux loads a JSON configuration file, located at /etc/opt/srlinux/config.json. If this startup configuration does not exist, the system is started using a factory default configuration.

The factory default configuration brings device into management, enables DHCP/v6 on the management interface, adds it to the management network-instance, enables an SSH server, and creates various system logs and applies a default set of CPM filters.

You can optionally create a rescue configuration, which is loaded if the startup configuration fails to load (see Rescue configuration). If the startup configuration fails to load, and no rescue configuration exists, the system is started using the factory default configuration.

Configuration datastores

Configuration and state information reside in datastores on the SR Linux device. The following datastores are available:

Running – contains the currently active configuration.
State – contains the running configuration, plus dynamically added data such as operational state of interfaces or BGP peers added via auto-discovery, as well as session states and routing tables.
Candidate – contains a user-configurable version of the running datastore. After it has been committed, the candidate datastore becomes the running datastore.
Tools – contains executable commands that allow you to perform operations such as restarting the device and clearing interface statistics.

Within the CLI, you can use the info command to display information from a datastore. For example, entering the info from state command (or entering the info command in state mode) displays configuration and statistics from the state datastore for the current context, and entering the info from running command (or the info command in running mode) displays configuration from the running datastore for the current context.

Configuration modes

The candidate datastore corresponds to a configuration mode within the SR Linux CLI. In candidate mode, you can modify SR Linux configuration settings.

By default, candidate mode operates in shared mode, which allows multiple users to modify the candidate configuration concurrently. When the configuration is committed in shared mode, all of the users’ changes are applied.

You can optionally use candidate mode in exclusive mode, which locks out all other users from making changes to the candidate configuration.

Configuration candidates

When a user enters candidate mode, the system creates two copies of the running datastore: one is modifiable by the user, and the other serves as a baseline. The modifiable datastore and the baseline datastore are collectively known as a configuration candidate.

A configuration candidate can be either shared or private.

Shared – is the default configuration candidate for CLI sessions. Multiple users can modify the shared candidate concurrently. When the configuration is committed, the changes from all of the users are applied.
Private – is the default configuration candidate when using JSON-RPC or gNMI clients, and can optionally be used in the CLI. With a private candidate, each user modifies their own separate instance of the configuration candidate. When a user commits their changes, only the changes from that user are committed.

By default, there is a single unnamed global configuration candidate. You can optionally configure one or more named configuration candidates, which function identically to the global configuration candidate. Both shared and private configuration candidates support named versions.

Setting the configuration mode

After logging in to the CLI, you are initially placed in running mode. From running mode, you can change to a configuration mode. Commands to change configuration mode describes the commands to change between modes.

Table 1. Commands to change configuration mode
To enter this mode:	Type this command:
Candidate shared	enter candidate
Candidate mode for named shared candidate	enter candidate name <name>
Candidate private	enter candidate private
Candidate mode for named private candidate	enter candidate private name <name>
Candidate exclusive	enter candidate exclusive
Exclusive mode for named candidate	enter candidate exclusive name <name>
Running	enter running
State	enter state
Show	enter show

Change from running to candidate mode

--{ running }--[  ]--
# enter candidate
--{ * candidate shared default }--[  ]--

The asterisk (*) next to the mode name indicates that the candidate configuration has changes that have not yet been committed.

Enter candidate mode for a named configuration candidate

--{ running }--[  ]--
# enter candidate name cand1
--{ candidate shared cand1}--[  ]--

Committing a configuration in candidate mode

Changes made during a configuration modification session do not take effect until a commit command is issued. Use the commit command in candidate mode only.

Enter candidate mode:
```
# enter candidate
```
Enter configuration commands.
Enter the commit command:
- To apply the changes and remain in candidate mode, enter commit stay.
- To apply the changes, exit candidate mode, and enter running mode, enter commit now.
- To apply the changes, remain in candidate mode, and save the changes to the startup configuration, enter commit stay save.
- To apply a comment to a commit stay or save operation, use the comment keyword and specify a comment.
```
# enter candidate
--{ candidate shared default }--[  ]--
# interface ethernet-1/1 subinterface 1
--{ * candidate shared default }--[ interface ethernet-1/1 subinterface 1 ]--
# commit stay
All changes have been committed. Starting new transaction.
--{ + candidate shared default }--[ interface ethernet-1/1 subinterface 1 ]--
# save startup
/system:
    Saved current running configuration as initial (startup) configuration '/etc/
opt/srlinux/config.json'
--{ candidate shared default }--[ interface ethernet-1/1 subinterface 1 ]--
#
```
In this example, a user enters candidate mode and creates a subinterface for interface ethernet-1/1. The asterisk (*) next to candidate shared default in the prompt indicates that the candidate configuration has changes that have not yet been committed. After committing the changes with the commit stay command, the new subinterface becomes part of the running configuration.

The plus sign (+) in the prompt indicates that the currently running configuration differs from the startup configuration. The save startup command saves the running configuration to the startup configuration.

Confirming a commit operation

You can optionally configure the SR Linux to require explicit confirmation via a tools command for the configuration changes from a commit operation to become permanent. If the new configuration is not confirmed after a timeout period, the running datastore reverts to the previous version.

Commit the configuration and start the confirmation timer

After entering configuration commands in candidate mode, use the following command to commit the configuration and start the confirmation timer:

--{ candidate shared default }--[  ]--
# commit confirmed

The commit confirmed command applies the changes to the running datastore and activates them. If the configuration is committed successfully, the confirmation timer is started (default 10 minutes). If you do not confirm the commit operation before the timer expires, the configuration reverts to the previous version.

Confirm the commit operation and make the configuration changes permanent

To confirm the commit operation and make the configuration changes permanent, enter the following command before the confirmation timer expires:

--{ candidate shared default }--[  ]--
# tools system configuration confirmed-accept

Revert to the previous configuration

To revert to the previous configuration without waiting for the confirmation timer to expire, enter the following command:

--{ candidate shared default }--[  ]--
# tools system configuration confirmed-reject

Validating a commit operation

You can optionally validate the configuration changes made during a commit operation before they are applied to the running datastore. The SR Linux management server checks the syntax of the changes in the candidate configuration and displays messages if validation errors are found.

Use the following command to perform a validation check for configuration changes. Note that this command only validates the changes; it does not apply them to the running datastore.

--{ candidate shared default }--[  ]--
# commit validate

If syntax errors are found in the configuration changes, SR Linux displays error messages; if validation is successful, no output is displayed.

Updating the baseline datastore

A configuration candidate consists of a modifiable candidate datastore and a baseline datastore, both of which are snapshots of the then-current running datastore when a user enters candidate mode.

During the lifetime of the configuration candidate, the running datastore can be modified via commits initiated from other configuration sessions. At that point, the baseline in the configuration candidate is out-of-date.

Updating the baseline datastore takes a new snapshot of the running configuration, applies the changes in the candidate datastore, and checks for configuration conflicts in the updated baseline datastore. If conflicts are found, the user is informed with a warning or error for each conflict.

A baseline datastore update is done automatically when the user commits the changes to the configuration, or can be done manually with the baseline update command.

In the following example, the baseline datastore in a configuration candidate is out of date, as indicated by the ! in the prompt. This indicates that another user has committed changes to the running datastore.

Entering the baseline update command copies the current running datastore to the baseline datastore, applies the changes in the candidate datastore, then displays any conflicts in the updated baseline datastore. If there are no conflicts, no output is returned by the command.

--{!* candidate shared default }--[  ]--
# baseline update
--{* candidate shared default }--[  ]--
#

Deleting a configuration

Use the delete command to delete configurations while in candidate mode.

The following example displays the system banner configuration, deletes the configured banner, then displays the resulting system banner configuration:

--{ candidate shared default }--[  ]--
# info system banner
    system {
        banner {
            login-banner "Welcome to SRLinux!"
        }
    }
--{ candidate shared default }--[  ]--
# delete system banner
--{ candidate shared default }--[  ]--
# info system banner
    system {
        banner {
        }
    }

Annotating the configuration

To aid in reading a configuration, you can add comments or descriptive annotations. The annotations are indicated by !!! in displayed output.

You can enter a comment either directly from the command line or by navigating to a CLI context and entering the comment in annotate mode.

Add a comment to a configuration

The following example adds a comment to an ACL configuration. If there is already a comment in the configuration, the new comment is appended to the existing comment.

--{ candidate shared default }--[  ]--
# acl ipv4-filter ip_tcp !! "Filter TCP traffic"

Replace an existing comment

To replace the existing comment, use !!! instead of !! in the command.

The following example adds the same comment to the ACL by navigating to the context for the ACL and entering the comment in annotate mode:

--{ * candidate shared default }--[  ]--
# acl ipv4-filter ip_tcp
--{ * candidate shared default }--[ acl ipv4-filter ip_tcp ]--
# annotate
Press [Meta+enter] or [Esc] followed by [Enter] to finish
-> Filter TCP traffic

You can enter multiple lines in annotate mode. To exit annotate mode, press Esc, then the Enter key.

Display a comment in context

In CLI output, the comment is displayed in the context it was entered. For example:

--{ running }--[  ]--
# info acl
    acl {
        ipv4-filter ip_tcp {
            !!! Filter TCP traffic
            entry 100 {
                action {
                    drop {
                        log true
                    }
                }
            }
            entry 110 {
                action {
                    accept {
                        log true
                    }
                }
            }
        }
    }

To remove a comment, enter annotate mode for the context and press Esc then Enter without entering any text.

Discarding a configuration in candidate mode

You can discard previously applied configurations with the discard command. Use the discard command in candidate mode only.

To discard the changes and remain in candidate mode with a new candidate session, enter discard stay.
To discard the changes, exit candidate mode, and enter running mode, enter discard now.

All changes have been committed. Starting new transaction.

--{ candidate shared default }--[ interface ethernet-1/1 subinterface 1 ]--
# discard stay
--{ candidate shared default }--[ interface ethernet-1/1 subinterface 1 ]--

Displaying configuration details

The info command displays configuration and state information. Entering the info command from the root context displays the entire configuration, or the configuration for a specified context. Entering the command from within a context limits the display to the configuration under that context. Use this command in candidate or running mode.

Display the entire configuration

To display the entire configuration, enter info from the root context:

--{ candidate shared default }--[  ]--
# info
<all the configuration is displayed>
--{ candidate }--[  ]--

Display the configuration for a specific context

To display the configuration for a specific context, enter info and specify the context:

--{ candidate shared default }--[  ]--
# info system lldp
    system {
        lldp {
            admin-state enable
            hello-timer 600
            management-address mgmt0.0 {
                type [
                    IPv4
                ]
            }
            interface mgmt0 {
                admin-state disable
            }
        }
    }
--{ candidate }--[  ]--

Display the configuration within a context

From a context, use the info command to display the configuration under that context:

--{ candidate shared default }--[  ]--
# system lldp
--{ candidate }--[ system lldp ]--
# info
    admin-state enable
    hello-timer 600
    management-address mgmt0.0 {
        type [
            IPv4
        ]
    }
    interface mgmt0 {
        admin-state disable
    }
--{ candidate }--[ system lldp ]--

Display the configuration as JSON-formatted output

Use the as json option to display JSON-formatted output:

--{ candidate }--[ system lldp ]--
# info | as json
{
  "admin-state": "enable",
  "hello-timer": "600",
  "management-address": [
    {
      "subinterface": "mgmt0.0",
      "type": [
        "IPv4"
      ]
    }
  ],
  "interface": [
    {
      "name": "mgmt0",
      "admin-state": "disable"
    }
  ]
}

Display values of all parameters in the configuration

Use the detail option to display values for all parameters, including those not specifically configured:

--{ candidate }--[ system lldp ]--
# info detail
    admin-state enable
    hello-timer 600
    hold-multiplier 4
    management-address mgmt0.0 {
        type [
            IPv4
        ]
    }
    interface mgmt0 {
        admin-state disable
    }

Display the configuration as set statements

Use the flat option to display the output as a series of set statements, omitting indentation for any sub-contexts:

--{ candidate }--[ system lldp ]--
# info flat
set / system lldp admin-state enable
set / system lldp hello-timer 600
set / system lldp management-address mgmt0.0
set / system lldp management-address mgmt0.0 type [ IPv4 ]
set / system lldp interface mgmt0
set / system lldp interface mgmt0 admin-state disable

Display a specified number of sub-context levels

Use the depth option to display parameters with a specified number of sub-context levels:

--{ candidate }--[ system lldp ]--
# info depth 0
    admin-state enable
    hello-timer 600

--{ candidate }--[ system lldp ]--
# info depth 1
    admin-state enable
    hello-timer 600
    management-address mgmt0.0 {
        type [
            IPv4
        ]
    }
    interface mgmt0 {
        admin-state disable
    }

Displaying the configuration state

To display information from the state datastore, enter the info from state command in candidate or running mode, or the info command in state mode.

Display state information for a specified context from candidate or running mode

--{ candidate shared default }--[  ]--
# info from state routing-policy policy bgp-export-policy
    routing-policy {
        policy bgp-export-policy {
            statement 999 {
                action {
                    accept {
                    }
                }
            }
        }
    }

Display state information for a specified context from state mode

--{ candidate shared default }--[  ]--
# enter state
--{ state }--[  ]--
# info routing-policy policy bgp-export-policy
    routing-policy {
        policy bgp-export-policy {
            statement 999 {
                action {
                    accept {
                    }
                }
            }
        }
    }
--{ state }--[  ]--

Change to a different mode while remaining in the previous context

You can change to a different mode (for example, from state mode to candidate mode), and remain in the previous context. For example:

--{ candidate shared default }--[  ]--
# enter state
--{ state }--[  ]--
# routing-policy policy bgp-export-policy
--{ state }--[ routing-policy policy bgp-export-policy ]--
# info
    statement 999 {
        action {
            accept {
            }
        }
    }
--{ state }--[ routing-policy policy bgp-export-policy ]--
# enter candidate
--{ candidate shared default }--[ routing-policy policy bgp-export-policy ]--

Saving a configuration to a file

Save the existing configuration to a file using the save command. Use this command in candidate or running mode.

Save the running configuration to a file

--{ running }--[  ]--
# save file running-config.txt text from running
/ running configuration has been stored in 'running-config.txt'
--{ running }--[  ]--

Save the running configuration to a JSON-formatted file

--{ running }--[  ]--
# save file running-config.json from running
/ running configuration has been stored in 'running-config.json'
--{ running }--[  ]--

Save the running configuration to the initial (startup) configuration

--{ + running }--[  ]--
# save startup
/ running configuration has been stored in '/etc/opt/srlinux/config.json'
--{ running }--[  ]--

The plus sign (+) in the prompt indicates that the running configuration differs from the startup configuration. After you enter the save startup command, the running configuration is synchronized with the startup configuration, and the plus sign is removed from the prompt.

Loading a configuration

Use the load command to load a configuration. The configuration can be from a checkpoint (see Configuration checkpoints), a JSON-formatted configuration file, the startup configuration, the factory default configuration, a rescue configuration (see Rescue configuration), or from manually entered or pasted JSON-formatted input.

Load a configuration from a checkpoint

--{ * candidate shared default }--[  ]--
# load checkpoint id 0
/system/configuration/checkpoint[id=0]:
    Loaded checkpoint '/etc/opt/srlinux/checkpoint/checkpoint-0.json'

Load a configuration from a file

--{ * candidate shared default }--[  ]--
# load file home/config.txt
Loading configuration from 'home/config.txt'

Load a rescue JSON configuration from a checkpoint

--{ * candidate shared default }--[  ]--
# load rescue auto-commit
/system/configuration/checkpoint[id=__rescue__]:
    Reverting to rescue configuration

Load a configuration from manually entered JSON-formatted input

--{ * candidate shared default }--[  ]--
# system banner
--{ * candidate shared default }--[ system banner ]--
# load json
Press [Meta+enter] or [Esc] followed by [Enter] to finish
<< {
<<   "login-banner": "Welcome to SRLinux!"
<< }

You can enter or paste multiple lines at the << prompt in JSON-input mode. To exit JSON-input mode, press Esc, then the Enter key.

Executing configuration statements from a file

You can execute configuration statements from a source file consisting of set statements such as those generated by the info flat command (see Displaying configuration details). SR Linux reads the file and executes each configuration statement line-by-line. You can optionally commit the configuration automatically after the file is read.

The following example executes a configuration from a specified file:

--{ running }--[  ]--
# source config.cfg
Sourcing commands from 'config.cfg'
Executed 20 lines in 1.6541 seconds from file config.cfg

Use the auto-commit option to commit the configuration after the commands in the source file are executed.

Configuration checkpoints

You can roll back the configuration to a previous state, known as a checkpoint. You can load a saved checkpoint into the candidate configuration, and revert the running configuration to a previously saved checkpoint.

A checkpoint is saved as a JSON-formatted file containing the complete configuration for the system. If a checkpoint file is larger than 1 Mb, it is compressed and saved in GZIP format. Checkpoint files are saved in the /etc/opt/srlinux/checkpoint directory. They are named checkpoint-<number>.json (for example, checkpoint-0.json), or checkpoint-<number>.json.gz, with the lowest number being the most recently saved checkpoint.

By default, the 10 most recent checkpoints are saved; you can configure the maximum number of checkpoint files that are kept by the system.

Generating a checkpoint

You can generate a checkpoint with a tools command or with the save checkpoint command. You can optionally configure the system to generate a checkpoint automatically when a configuration is committed.

Generate a checkpoint from the current configuration

--{ !* candidate shared default }--[  ]--
# tools system configuration generate-checkpoint
/system:
    Generated checkpoint '/etc/opt/srlinux/checkpoint/checkpoint-
0.json' with name 'checkpoint-2020-10-20T23:14:12.703Z' and comment ''

You can optionally configure a name or comment for a checkpoint; for example:

--{ !* candidate shared default }--[  ]--
# save checkpoint comment My-checkpoint
/system:
    Generated checkpoint '/etc/opt/srlinux/checkpoint/checkpoint-
0.json' with name 'checkpoint-2020-10-20T23:23:25.891Z' and comment 'My-checkpoint'

Generate a checkpoint automatically

The following example configures the system to generate a checkpoint automatically whenever a configuration is committed:

--{ !* candidate shared default }--[  ]--
# info system configuration
    system {
        configuration {
            auto-checkpoint true
            }
        }
    }

For automatically generated checkpoints, the comment is set to automatic checkpoint after commit <n>, where <n> is the ID of the commit that triggered the checkpoint.

Loading a checkpoint

To load a checkpoint, enter candidate mode and specify the checkpoint to load.

The following example loads a checkpoint into the candidate configuration. Note that you must be in candidate mode to load a checkpoint.

--{ * running }--[  ]--
# enter candidate
--{ * candidate shared default }--[  ]--
# tools system configuration checkpoint 0 load
/system/configuration/checkpoint[id=0]:
    Loaded checkpoint '/etc/opt/srlinux/checkpoint/checkpoint-0.json'

Reverting to a previous checkpoint

You can revert the running configuration to a previous checkpoint. When used within a candidate session, the revert operation loads the checkpoint, removing any present changes, then commits them and establishes a new candidate session.

The following example reverts the running configuration to a previously saved checkpoint:

--{ * running }--[  ]--
# enter candidate
--{ * candidate shared default }--[  ]--
# tools system configuration checkpoint 0 revert
/system/configuration/checkpoint[id=0]:
    Reverting to checkpoint 0 (name 'checkpoint-2019-10-14T18:47:30.282Z' 
comment 'Daily_checkpoint')
/:
    Successfully reverted configuration

Clearing a checkpoint

You can clear checkpoints from the system manually with a tools command.

In addition, checkpoints can be cleared automatically when the number of saved checkpoints exceeds the configured maximum. When the number of saved checkpoints exceeds the configured maximum, the oldest checkpoint is removed, and the number of each remaining checkpoint is incremented by 1. If you clear a checkpoint manually, the other checkpoints are not renumbered.

The following example clears a previously saved checkpoint.

--{ * candidate shared default }--[  ]--
# tools system configuration checkpoint 2 clear
/system/configuration/checkpoint[id=2]:
    Cleared checkpoint '/etc/opt/srlinux/checkpoint/checkpoint-2.json'

Configuring maximum number of checkpoints

By default, the 10 most recent checkpoints are saved; you can configure the maximum number of checkpoint files that are kept by the system.

The following example configures the system to keep a maximum of 15 checkpoint files.

--{ * candidate shared default }--[  ]--
# info system configuration
 system {
     configuration {
         max-checkpoints 15
         }
     }
 }

In this example, if 15 checkpoint files are being kept, adding a subsequent checkpoint file causes the oldest checkpoint file to be deleted and the index for the remaining checkpoint files to be incremented by 1.

Displaying checkpoint information

Use the info from state command to display information about existing checkpoints.

# info from state system configuration checkpoint 0
    system {
        configuration {
            checkpoint 0 {
                name checkpoint-2020-10-20T23:23:25.891Z
                comment cp002
                created 2020-10-20T23:23:25.894Z
                version v20.6.0
                username srlinux
                size 28494
            }
        }
    }

Rescue configuration

You can save a secondary rescue configuration to load in place of the default JSON configuration file. The rescue configuration is a checkpoint file that is loaded automatically by the management server if the default config.json fails when the system starts.

If both the default configuration and rescue configuration files are missing or fail, a config.json is regenerated and committed from the factory config.json that is compiled in the management server.

Saving a rescue configuration

You can save a rescue configuration to be loaded automatically if the default config.json fails when the system starts. Save the rescue configuration to a file with a tools command or using the save rescue command. Use these commands in running mode. The system generates a rescue-config.json file and saves it to the /etc/opt/srlinux/checkpoint directory.

Save a rescue configuration

The following tools command saves a rescue configuration:

--{ running }--[ ]--
# tools system configuration rescue-save
/system:
    Saved current running configuration as rescue configuration '/etc/opt/srlinux/
checkpoint/rescue-config.json'

The following example also saves a rescue configuration:

--{ running }--[ ]--
# save rescue
/system:
  Saved current running configuration as rescue configuration '/etc/opt/srlinux/
checkpoint/rescue-config.json'

List contents of the checkpoint directory

You can confirm the rescue configuration is saved by viewing the checkpoint directory. The following example lists the checkpoint directory:

--{ running }--[ ]--
# file ls /etc/opt/srlinux/checkpoint
checkpoint-0.json
rescue-config.json

Clearing a rescue configuration

To remove an existing rescue configuration, use the rescue-clear command to clear the configuration from the /etc/opt/srlinux/checkpoint directory. Use this command in running mode. You can then save a new rescue configuration to replace the cleared configuration.

The following tools command clears a previously saved rescue configuration:

--{ running }--[ ]--
# tools system configuration rescue-clear
/system:
    Cleared rescue configuration '/etc/opt/srlinux/checkpoint/rescue-config.json'

You can confirm the rescue configuration is cleared by viewing the checkpoint directory; for example:

--{ running }--[ ]--
# file ls /etc/opt/srlinux/checkpoint
checkpoint-0.json

Configuration upgrades

When the SR Linux is started following a software image upgrade, it reads the configuration in the startup config.json file, makes any necessary changes to ensure compatibility with the new software image, and places the upgraded configuration into the running configuration. This upgraded configuration is not saved automatically; to save the contents of the running configuration, use the following commands:

save startup – Saves the running configuration to the startup configuration file, located at /etc/opt/srlinux/config.json (or config.gz).
save rescue – Saves the running configuration to the rescue configuration file, located at /etc/opt/srlinux/checkpoint/rescue-config.json (or rescue-config.gz).
save checkpoint – Saves the running configuration to a configuration checkpoint; for example, /etc/opt/srlinux/checkpoint/checkpoint-0.json (or checkpoint-0.gz).
save file <name> from running – Saves the running configuration to the specified file in JSON format.

Upgrading configuration files

In addition to saving the upgraded running configuration to startup, rescue, and checkpoint configurations, you can use tools commands to upgrade existing configuration files so they are compatible with the current software version.

Upgrade the startup configuration file

--{ running }--[ ]--
# tools system configuration upgrade startup

Upgrade the rescue configuration file

--{ running }--[ ]--
# tools system configuration upgrade rescue

Upgrade a configuration checkpoint file

--{ running }--[ ]--
# tools system configuration upgrade checkpoint 0

Upgrade a specified JSON-formatted configuration file

--{ running }--[ ]--
# tools system configuration upgrade file /etc/opt/srlinux/configs/myconfig.json