Committing a Configuration

 

To commit a configuration, the commit configuration mode command enables you to save the Junos OS configuration changes to the configuration database and to activate the configuration on the router. For more information, see the following topics:

Junos OS Commit Model for Configurations

The device configuration is saved using a commit model—a candidate configuration is modified as desired and then committed to the system. When a configuration is committed, the device checks the configuration for syntax errors, and if no errors are found, the configuration is saved as juniper.conf.gz and activated. The formerly active configuration file is saved as the first rollback configuration file (juniper.conf.1.gz), and any other rollback configuration files are incremented by 1. For example, juniper.conf.1.gz is incremented to juniper.conf.2.gz, making it the second rollback configuration file. The device can have a maximum of 49 rollback configurations (numbered 1 through 49) saved on the system.

On the device, the active configuration file and the first three rollback files (juniper.conf.gz.1, juniper.conf.gz.2, juniper.conf.gz.3) are located in the /config directory. If the file rescue.conf.gz is saved on the system, this file should also be saved in the /config directory. The factory default files are located in the /etc/config directory.

There are two mechanisms used to propagate the configurations between Routing Engines within a device:

  • Synchronization—Propagates a configuration from one Routing Engine to a second Routing Engine within the same device chassis.

    Note

    The QFX3500 switch has only one Routing Engine.

    To synchronize configurations, use the commit synchronize CLI command. If one of the Routing Engines is locked, the synchronization fails. If synchronization fails because of a locked configuration file, you can use the commit synchronize force command. This command overrides the lock and synchronizes the configuration files.

  • Distribution—Propagates a configuration across the routing plane on a multichassis device. Distribution occurs automatically. There is no user command available to control the distribution process. If a configuration is locked during a distribution of a configuration, the locked configuration does not receive the distributed configuration file, so the synchronization fails. You need to clear the lock before the configuration and resynchronize the routing planes.

    Note

    When you use the commit synchronize force CLI command on a multichassis platform, the forced synchronization of the configuration files does not affect the distribution of the configuration file across the routing plane. If a configuration file is locked on a device remote from the device where the command was issued, the synchronization fails on the remote device. You need to clear the lock and reissue the synchronization command.

Committing a Junos OS Configuration and Exiting Configuration Mode

To save Junos OS configuration changes, activate the configuration on the device and exit configuration mode, using the commit and-quit configuration mode command. This command succeeds only if the configuration contains no errors.

Note

We do not recommend performing a commit operation on the backup Routing Engine when graceful Routing Engine switchover is enabled on the router.

Committing a Junos OS Configuration

To save Junos OS configuration changes to the configuration database and to activate the configuration on the router, use the commit configuration mode command. You can issue the commit command from any hierarchy level:

When you enter the commit command, the configuration is first checked for syntax errors (commit check). Then, if the syntax is correct, the configuration is activated and becomes the current, operational router configuration.

You can issue the commit command from any hierarchy level.

A configuration commit can fail for any of the following reasons:

  • The configuration includes incorrect syntax, which causes the commit check to fail.

  • The candidate configuration that you are trying to commit is larger than 700 MB.

  • The configuration is locked by a user who entered the configure exclusive command.

If the configuration contains syntax errors, a message indicates the location of the error, and the configuration is not activated. The error message has the following format:

For example:

You must correct the error before recommitting the configuration. To return quickly to the hierarchy level where the error is located, copy the path from the first line of the error and paste it at the configuration mode prompt at the [edit] hierarchy level.

The uncommitted, candidate configuration file is /var/rundb/juniper.db. It is limited to 700 MB. If the commit fails with a message configuration database size limit exceeded, view the file size from configuration mode by entering the command run file list /var/rundb detail. You can simplify the configuration and reduce the file size by creating configuration groups with wildcards or defining less specific match policies in your firewall filters.

Note

CLI commit-time warnings displayed for configuration changes at the [edit interfaces] hierarchy level are removed and are logged as system log messages.

This is also applicable to VRRP configuration at the following hierarchy levels:

  • [edit interfaces interface-name unit logical-unit-number family (inet | inet6) address address]

  • [edit logical-systems logical-system-name interfaces interface-name unit logical-unit-number family (inet | inet6) address address]

When you commit a configuration, you commit the entire configuration in its current form. If more than one user is modifying the configuration, committing it saves and activates the changes of all the users.

  • If you are using Junos OS in a Common Criteria environment, system log messages are created whenever a secret attribute is changed (for example, password changes or changes to the RADIUS shared secret). These changes are logged during the following configuration load operations:

    For more information, see the Secure Configuration Guide for Common Criteria and Junos-FIPS.

    To save Junos OS configuration changes, activate the configuration on the device and exit configuration mode, using the commit and-quit configuration mode command. This command succeeds only if the configuration contains no errors.

  • We do not recommend performing a commit operation on the backup Routing Engine when graceful Routing Engine switchover is enabled on the router.

  • Note

    If you configure the same IP address for a management interface or internal interface such as fxp0 and an external physical interface such as ge-0/0/1, when graceful Routing Engine switchover (GRES) is enabled, the CLI displays an appropriate commit error message that identical addresses have been found on the private and public interfaces. In such cases, you must assign unique IP addresses for the two interfaces that have duplicate addresses.

    The management Ethernet interface used for the TX Matrix Plus router, T1600 or T4000 routers in a routing matrix, and PTX Series Packet Transport Routers, is em0. Junos OS automatically creates the router’s management Ethernet interface, em0.

Commit Operation When Multiple Users Configure the Software

Up to 32 users can be in configuration mode simultaneously, and they all can be making changes to the configuration. All changes made by all users are visible to everyone editing the configuration—the changes become visible as soon as the user presses the Enter key at the end of a command that changes the configuration, such as set, edit, or delete.

When any of the users editing the configuration issues a commit command, all changes made by all users are checked and activated.

If you enter configuration mode with the configure private command, each user has a private candidate configuration to edit somewhat independently of other users. When you commit the configuration, only your own changes get committed. To synchronize your copy of the configuration after other users have committed changes, you can run the update command in configuration mode. A commit operation also updates all of the private candidate configurations. For example, suppose user X and user Y are both in configure private mode, and user X commits a configuration change. When user Y performs a subsequent commit operation and then views the new configuration, the new configuration seen by user Y includes the changes made by user X.

If you enter configuration mode with the configure exclusive command, you lock the candidate configuration for as long as you remain in configuration mode, allowing you to make changes without interference from other users. Other users can enter and exit configuration mode, but they cannot commit the configuration. This is true even if the other users entered configuration mode before you enter the configure exclusive command. For example, suppose user X is already in the configure private or configure mode. Then suppose user Y enters the configure exclusive mode. User X cannot commit any changes to the configuration, even if those changes were entered before user Y logged in. If user Y exits configure exclusive mode, user X can then commit the changes made in configure private or configure mode.

Commit Preparation and Activation Overview

To save Junos configuration changes to the configuration database and to activate the configuration on the router, the configuration mode command commit is used.

Starting in Junos OS Release 17.3R1, you can complete the commit process in two steps. This feature enables you to configure a number of devices and simultaneously activate the configurations. Prior to Junos OS Release 17.3R1, the commit process was completed in a single step. The purpose of decoupling these stages of commit is to provide a definitive time window for the commit to be effective on the system. You are allowed to enter into commit mode after the commit is prepared, but you receive a message informing that the commit is pending activation.

In the first step, known as the preparation stage, the commit is validated and a new database with the necessary files is generated. If the configuration contains syntax errors, an appropriate error message is displayed, and the configuration is not prepared. In the event of failure during the preparation stage, the error message commit check-out failed is displayed.

In the second step, referred to as the activation stage, the previously prepared configuration is activated. Next, if you need to clear the prepared configuration, you can do so by using clear system commit prepared command. A log message is generated upon successful clearing of the pending commit.

Note

Commit operations cannot be performed in between preparation and activation stages.

The two-step commit process is superior to the single-step process for time-critical commits. In the single-step process, the preparation time can vary depending on the existing configuration on the device. In the two-step process, the complex preparation work is more efficiently handled.

Configuration commands are provided that allow you to prepare the configuration cache and activate the configuration. You can prepare the devices with new configurations and activate them at the exact times you want.

The commit prepare command validates the configurations, and the commit activate command activates the configurations. The commands have the following configuration options:

  • and-quit

  • no-synchronize

  • peers-synchronize

  • synchronize

The commit prepare and commit activate commands are available for private, exclusive and shared commits only. The commands are not applicable for dynamic and ephemeral modes. This feature is applicable for multichassis devices, but it is not applicable for batch commits.

To support this functionality using Network Configuration Protocol (NETCONF), the following new remote procedure calls (RPCs) are provided:

  • <commit-configuration>< prepare/></commit-configuration>

  • <commit-configuration><activate/></commit-configuration>

  • <clear-system-commit><prepared/></clear-system-commit>

Note
  • In an MX Series Virtual Chassis setup the following applies: When commit prepare is issued on one Routing Engine followed by switchover, the Routing Engine where the switchover command is issued reboots. Therefore, the prepared cache gets cleared in that Routing Engine.

  • In an MX Series Virtual Chassis setup, it is advisable to execute clear system commit prepared command only on VC master.

Committing Junos OS Configurations in Two Steps: Preparation and Activation

To save Junos OS configuration changes to the configuration database and to activate the configuration on the router, the configuration mode command commit is used.

Starting in Junos OS Release 17.3, you can complete the commit process in two steps. This enables you to configure a number of devices, and the configurations can be activated simultaneously. In the first step, known as the preparation stage, the commit is validated and a new database along with necessary files is generated. If the configuration contains syntax errors, an appropriate error message is displayed, and the configuration is not prepared. In the second step, referred to as the activation stage, the previously prepared configuration is activated and becomes the current, operational router configuration.

To prepare the configuration:

  1. At the [edit] hierarchy level in configuration mode, make the necessary changes to the configuration.

    For example, to configure the scripts of the system, issue the following command:

    For example:

  2. Issue the commit prepare command.

    The message commit prepare successful is displayed.

  3. To verify the output of the show system commit command after commit prepare is issued, issue the following command:

    In the event of failure during the preparation stage, the error message commit check-out failed is displayed.

To activate the prepared configuration:

  1. Issue the commit activate command

    The message commit complete is displayed.

  2. To verify the activated system configuration, issue the following command:

To verify the output of the show system commit and show system commit revision detail commands after commit activate is issued, issue the following commands.

Activating a Junos OS Configuration but Requiring Confirmation

When you commit the current candidate configuration, you can require an explicit confirmation for the commit to become permanent. This is useful if you want to verify that a configuration change works correctly and does not prevent access to the router. If the change prevents access or causes other errors, the router automatically returns to the previous configuration and restores access after the rollback confirmation timeout passes. This feature is called automatic rollback.

To commit the current candidate configuration but require an explicit confirmation for the commit to become permanent, use the commit confirmed configuration mode command:

Once you have verified that the change works correctly, you can keep the new configuration active by entering a commit or commit check command within 10 minutes of the commit confirmed command. For example:

If the commit is not confirmed within a certain time (10 minutes by default), Junos OS automatically rolls back to the previous configuration and a broadcast message is sent to all logged-in users.

To show when a rollback is scheduled after a commit confirmed command, enter the show system commit command. For example:

Like the commit command, the commit confirmed command verifies the configuration syntax and reports any errors. If there are no errors, the configuration is activated temporarily (10 minutes by default), and begins running on the router.

Figure 1 illustrates how the commit confirmed command works.

Figure 1: Confirm a Configuration
Confirm a Configuration

To change the amount of time before you have to confirm the new configuration, specify the number of minutes when you issue the command:

In Junos OS Release 11.4 and later, you can also use the commit confirmed command in the [edit private] configuration mode.

Scheduling a Junos OS Commit Operation

You can schedule when you want your candidate configuration to become active. To save Junos OS configuration changes and activate the configuration on the router at a future time or upon reboot, use the commit at configuration mode command, specifying reboot or a future time at the [edit] hierarchy level:

Where string is reboot or the future time to activate the configuration changes. You can specify time in two formats:

  • A time value in the form hh:mm[:ss] hours, minutes, and optionally seconds)—Commit the configuration at the specified time, which must be in the future but before 11:59:59 PM on the day the commit at configuration mode command is issued. Use 24-hour time for the hh value; for example, 04:30:00 is 4:30:00 AM, and 20:00 is 8:00 PM. The time is interpreted with respect to the clock and time zone settings on the router.

  • A date and time value in the form yyyy-mm-dd hh:mm[:ss] (year, month, date, hours, minutes, and, optionally, seconds)—Commit the configuration at the specified day and time, which must be after the commit at command is issued. Use 24-hour time for the hh value. For example, 2003-08-21 12:30:00 is 12:30 PM on August 21, 2003. The time is interpreted with respect to the clock and time zone settings on the router.

Enclose the string value in quotation marks (" "). For example, commit at "18:00:00". For date and time, include both values in the same set of quotation marks. For example, commit at "2005-03-10 14:00:00".

A commit check is performed immediately when you issue the commit at configuration mode command. If the result of the check is successful, then the current user is logged out of configuration mode, and the configuration data is left in a read-only state. No other commit can be performed until the scheduled commit is completed.

Note

If Junos OS fails before the configuration changes become active, all configuration changes are lost.

You cannot enter the commit at configuration command after you issue the request system reboot command.

You cannot enter the request system reboot command once you schedule a commit operation for a specific time in the future.

You cannot commit a configuration when a scheduled commit is pending. For information about how to cancel a scheduled configuration by means of the clear command, see the CLI Explorer.

Note

We do not recommend performing a commit operation on the backup Routing Engine when graceful Routing Engine switchover is enabled on the router.

Monitoring the Junos OS Commit Process

To monitor the Junos commit process, use the display detail command after the pipe with the commit command:

For example:

Adding a Comment to Describe the Committed Configuration

You can include a comment that describes changes to the committed configuration. To do so, include the commit comment statement. The comment can be as long as 512 bytes and you must type it on a single line.

comment-string is the text of the comment.

Note

You cannot include a comment with the commit check command.

To add a comment to the commit command, include the comment statement after the commit command:

To add a comment to the commit confirmed command, include the comment statement after the commit confirmed command:

To view these commit comments, issue the show system commit operational mode command.

In Junos OS Release 11.4 and later, you can also use the commit confirmed command in the [edit private] configuration mode.

Junos OS Batch Commits Overview

Junos OS provides a batch commit feature that aggregates or merges multiple configuration edits from different CLI sessions or users and adds them to a batch commit queue. A batch commit server running on the device takes one or more jobs from the batch commit queue, applies the configuration changes to the shared configuration database, and then commits the configuration changes in a single commit operation.

Batches are prioritized by the commit server based on priority of the batch specified by the user or the time when the batch job is added. When one batch commit is complete, the next set of configuration changes are aggregated and loaded into the batch queue for the next session of the batch commit operation. Batches are created until there are no commit entries left in the queue directory.

When compared to the regular commit operation where all commits are independently committed sequentially, batch commits save time and system resources by committing multiple small configuration edits in a single commit operation.

Batch commits are performed from the [edit batch] configuration mode. The commit server properties can be configured at the [edit system commit server] hierarchy level.

Aggregation and Error Handling

When there is a load-time error in one of the aggregated jobs, the commit job that encounters the error is discarded and the remaining jobs are aggregated and committed.

For example, if there are five commit jobs (commit-1, commit-2, commit-3, commit-4, and commit-5) being aggregated, and commit-3 encounters an error while loading, commit-3 is discarded and commit-1, commit-2, commit-4, and commit-5 are aggregated and committed.

If there is an error during the commit operation when two or more jobs are aggregated and committed, the aggregation is discarded and each of those jobs is committed individually like a regular commit operation.

For example, if there are five commit jobs (commit-1, commit-2, commit-3, commit-4, and commit-5) that are aggregated and if there is a commit error caused because of commit-3, the aggregation is discarded, commit-1, commit-2, commit-3, commit-4, and commit-5 are committed individually, and the CLI reports a commit error for commit-3.

Example: Configuring Batch Commit Server Properties

This example shows how to configure batch commit server properties to manage batch commit operations.

Requirements

This example uses the following hardware and software components:

  • MX Series 5G Universal Routing Platform

  • Junos OS Release 12.1 or later running on the device

Overview

You can control how the batch commit queue is handled by the commit server by configuring the server properties at the [edit system commit server] hierarchy level. This enables you to control how many commit jobs are aggregated or merged into a single batch commit, the maximum number of jobs that can be added to the queue, days to keep batch commit error logs, interval between two batch commits, and tracing operations for batch commit operations.

Configuration

CLI Quick Configuration

To quickly configure this section of the example, copy the following commands, paste them into a text file, remove any line breaks, change any details necessary to match your network configuration, and then copy and paste the commands into the CLI at the [edit] hierarchy level. You can configure the commit server properties from either the regular [edit] mode or the [edit batch] mode.

Device R0

Configuring the Commit Server Properties

Step-by-Step Procedure

  1. (Optional) Configure the number of commit transactions to aggregate or merge in a single commit operation.

    The default value for maximum-aggregate-pool is 5.

    Note

    Setting maximum-aggregate-pool to 1 commits each of the jobs individually.

    In this example, the number of commit transactions is set to 4 indicating that four different commit jobs are aggregated into a single commit before the commit operation is initiated.

  2. (Optional) Configure the maximum number of jobs allowed in a batch.

    This limits the number of commits jobs that are added to the queue.

    Note

    If you set maximum-entries to 1, the commit server cannot add more than one job to the queue, and the CLI displays an appropriate message when you try to commit more than one job.

  3. (Optional) Configure the time (in seconds) to wait before starting the next batch commit operation.
  4. (Optional) Configure the number of days to keep error logs.

    The default value is 30 days.

  5. (Optional) Configure tracing operations to log batch commit events.

    In this example, the filename for logging batch commit events is commitd_nov, and all traceoption flags are set.

Results

From configuration mode, confirm your configuration by entering the show system commit server command. If the output does not display the intended configuration, repeat the instructions in this example to correct the configuration.

Committing the Configuration from Batch Configuration Mode

Step-by-Step Procedure

To commit the configuration from the [edit batch] mode, do one of the following:

  • Log in to the device and enter commit.

  • To assign a higher priority to a batch commit job, issue the commit command with the priority option.
  • To commit a configuration without aggregating the configuration changes with other commit jobs in the queue, issue the commit command with the atomic option.
  • To commit a configuration without aggregating the configuration changes with other commit jobs in the queue, and issuing a higher priority to the commit job, issue the commit command with the atomic priority option.

Verification

Confirm that the configuration is working properly.

Checking the Batch Commit Server Status

Purpose

Check the status of the batch commit server.

Action

user@R0> show system commit server

By default, the status of the commit server is Not running. The commit server starts running only when a batch commit job is added to the queue.

When a batch commit job is added to the queue, the status of the commit server changes to Running.

user@R0> show system commit server

Meaning

The Jobs in process field lists the commit IDs of jobs that are in process.

Checking the Batch Commit Status

Purpose

Check the commit server queue for the status of the batch commits.

Action

user@R0> show system commit server queue

Meaning

Pending commits displays commit jobs that are added to the commit queue but are not committed yet. Completed commits displays the list of commit jobs that are successful. Error commits are commits that failed because of an error.

Viewing the Patch Files in a Batch Commit Job

Purpose

View the timestamps, patch files, and the status of each of the commit jobs. Patch files show the configuration changes that occur in each commit operation that is added to the batch commit queue.

Action

  1. Issue the show system commit server queue patch command to view the patches for all commit operations.
    user@R0> show system commit server queue patch

    The output shows the changes in configuration for each commit job ID.

  2. To view the patch for a specific commit job ID, issue the show system commit server queue patch id <id-number> command.
    user@R0> show system commit server queue patch id 1000

Meaning

The output shows the patch created for a commit job. The + or - sign indicates the changes in the configuration for a specific commit job.

Viewing the Trace Files for Batch Commit Operations

Purpose

View the trace files for batch commit operations. You can use the trace files for troubleshooting purposes.

Action

  • Issue the file show /var/log/<filename> command to view all entries in the log file.
    user@R0> file show/var/log/commitd_nov

    The output shows commit server event logs and other logs for batch commits.

  • To view log entries only for successful batch commit operations, issue the file show /var/log/<filename> command with the | match committed pipe option.
    user@R0> file show/var/log/commitd_nov | match committed

    The output shows batch commit job IDs for successful commit operations.

  • To view log entries only for failed batch commit operations, issue the file show /var/log/<filename> command with the | match “Error while” pipe option.
    user@R0> file show/var/log/commitd_nov | match “Error while”

    The output shows commit job IDs for failed commit operations.

  • To view log entries only for commit server events, issue the file show /var/log/<filename> command with the | match “commit server” pipe option.
    user@R0> file show/var/log/commitd_nov | match “commit server”

    The output shows commit server event logs.

Backing Up the Committed Configuration on the Alternate Boot Drive

After you commit the configuration and are satisfied that it is running successfully, you should issue the request system snapshot command to back up the new software onto the /altconfig file system. If you do not issue the request system snapshot command, the configuration on the alternate boot drive will be out of sync with the configuration on the primary boot drive.

The request system snapshot command backs up the root file system to /altroot, and /config to /altconfig. The root and /config file systems are on the router’s flash drive, and the /altroot and /altconfig file systems are on the router’s hard disk (if available).

Note

For more information about backing up the file system on an ACX Series Universal Metro Router, see Understanding System Snapshot on an ACX Series Router.

After you issue the request system snapshot command, you cannot return to the previous version of the software because the running and backup copies of the software are identical.

Release History Table
Release
Description
Starting in Junos OS Release 17.3R1, you can complete the commit process in two steps. This feature enables you to configure a number of devices and simultaneously activate the configurations