Using Junos PyEZ to Commit the Configuration
Junos PyEZ enables you to make structured and unstructured configuration changes on devices running Junos OS. After connecting to the device and modifying the configuration, you must commit the configuration to make it active. This topic discusses how to commit the configuration and which commit options are supported in Junos PyEZ applications.
Committing the Candidate Configuration
When you use the Junos PyEZ jnpr.junos.utils.config.Config utility to make
unstructured configuration changes on a device, you commit the candidate
configuration by calling the Config instance commit() method. For example:
from jnpr.junos import Device
from jnpr.junos.utils.config import Config
from jnpr.junos.exception import ConfigLoadError, CommitError
dev = Device(host='router1.example.com')
dev.open()
with Config(dev, mode='exclusive') as cu:
try:
cu.load(path="configs/mx_config.conf", merge=True)
cu.commit()
except (ConfigLoadError, CommitError) as err:
print (err)
dev.close()
To verify the syntax of the configuration without committing
it, call the commit_check() method in place of the commit() method.
cu.commit_check()
When you use Junos PyEZ configuration Tables and Views to make
structured configuration changes on a device, you commit the candidate
configuration by calling either the set() method, which automatically calls the lock(), load(), commit() and unlock() methods,
or by calling the various methods individually. For example:
from jnpr.junos import Device
from myTables.UserConfigTable import UserConfigTable
dev = Device(host='router1.example.com')
dev.open()
userconfig = UserConfigTable(dev)
# ...set the values for the configuration data...
userconfig.append()
userconfig.set(merge=True)
dev.close()
Similarly, you can call the individual methods, as in the following example:
from jnpr.junos import Device
from myTables.UserConfigTable import UserConfigTable
dev = Device(host='router1.example.com')
dev.open()
userconfig = UserConfigTable(dev)
# ...set the values for the configuration data...
userconfig.append()
userconfig.lock()
userconfig.load(merge=True)
userconfig.commit()
userconfig.unlock()
dev.close()
If you use a context manager to create the Config or Table object and set the mode argument to private, exclusive, dynamic, batch, or ephemeral, you only call the load() and commit() methods
to configure the device. The context manager handles opening and locking
and closing and unlocking the database, so calls to the lock(), unlock(), or set() methods in one of these modes results in a LockError
exception.
Specifying Commit Options
The Junos OS command-line interface (CLI) provides options for
the commit operation, such as adding a commit comment or synchronizing
the configuration on multiple Routing Engines. Junos PyEZ supports
many of these same commit options and some additional options, which
you can use in your Junos PyEZ application by including the appropriate
arguments in the commit() or set() method argument list. Table 1 outlines the supported
commit options, provides the corresponding CLI command, and specifies
the Junos PyEZ Release in which support for the option was first introduced.
Table 1: Junos PyEZ Supported Commit Options
Commit Option Argument | Description | CLI command | Junos PyEZ Release |
|---|---|---|---|
| Log a comment for that commit operation in the system log file and in the device’s commit history. | commit comment "comment" | 1.0.0 |
| Require that a commit operation be confirmed within a specified amount of time after the initial commit. Otherwise, roll back to the previously committed configuration. Set the argument to | commit confirmed <minutes> | 1.0.0 |
| Return an XML object with detailed information about the commit process. | commit | display detail | display xml | 1.2.0 |
| Synchronize and commit the configuration on both Routing Engines, even if there are open configuration sessions or uncommitted configuration changes on the other Routing Engine. | commit synchronize force | 1.2.0 |
| Ignore warnings that are raised during the commit operation. Set the argument to | – | 2.1.1 |
| Synchronize and commit the configuration on both Routing Engines. | commit synchronize | 1.2.0 |
| Wait for completion of the operation using the specified value as the timeout. | – | 1.1.0 |
Commit Comment
When you commit the configuration, you can include a
brief comment to describe the purpose of the committed changes. To
log a comment describing the changes, include the comment parameter and a message string in the commit() or set() method argument list, as appropriate.
For example:
cu.commit(comment='Configuring ge-0/0/0 interface')
Including the comment argument is
equivalent to issuing the commit comment configuration
mode command in the Junos OS CLI. The comment is logged to the system
log file and included in the device’s commit history, which
you can view by issuing the show system commit command
in the CLI.
Commit Confirm
To require that a commit operation be confirmed within
a specified amount of time after the initial commit, include the confirm=minutes argument in the commit() or set() method
argument list, as appropriate.
cu.commit(confirm=15)
If the commit is not confirmed within the given time limit,
the configuration automatically rolls back to the previously committed
configuration and a broadcast message is sent to all logged-in users.
The allowed range is 1 through 65,535 minutes. You can also specify confirm=True to use the default rollback time of 10
minutes. To confirm the commit operation, call either the commit() or commit_check() method.
The confirmed commit operation is useful for verifying that
a configuration change works correctly and does not prevent management
access to the device. If the change prevents access or causes other
errors, the automatic rollback to the previous configuration enables
access to the device after the rollback deadline passes. If you lose
connectivity to the device, you must issue the Junos PyEZ open() method to restore connectivity.
Commit Detail
You can review the details of the entire commit operation
by including the detail=True argument in
the commit() or set() method argument list. When you include this argument, the method
returns an XML object with detailed information about the commit process.
The return value is equivalent to the contents enclosed by the <commit-results> element in the output of the commit | display detail | display xml command in the CLI.
from lxml import etree
...
commit_detail = cu.commit(detail=True)
print (etree.tostring(commit_detail, encoding='unicode'))
Commit Synchronize
If the device has dual Routing Engines, you can synchronize
and commit the configuration on both Routing Engines by including
the sync=True argument in the commit() or set() method
argument list.
cu.commit(sync=True)
When you include the sync=True argument,
the device copies the candidate configuration stored on the local
Routing Engine to the other Routing Engine, verifies the candidate’s
syntactic correctness, and commits it on both Routing Engines. To
force the commit synchronize operation to succeed even
if there are open configuration sessions or uncommitted configuration
changes on the other Routing Engine, use the force_sync=True argument, which causes the device to terminate any configuration
sessions on the other Routing Engine before synchronizing and committing
the configuration.
cu.commit(force_sync=True)
Commit Timeout
The default time for an RPC to time out is 30 seconds.
Large configuration changes might exceed this value causing the operation
to time out before the configuration can be uploaded and committed.
To accommodate configuration changes that might require a commit time
that is longer than the default timeout interval, include the timeout=seconds argument in the commit() or set() method
argument list, and set the timeout interval to an appropriate value.
For example:
cu.commit(timeout=360)
Ignore Warnings
Junos PyEZ raises an RpcError exception when the RPC reply contains <rpc-error> elements with a severity of warning or higher. In cases where it
is necessary or desirable to suppress the RpcError exceptions that are raised in response to warnings, you can include
the commit() method’s ignore_warning parameter. For example:
cu.commit(ignore_warning=True)
For more information about using the ignore_warning parameter, see Suppressing RpcError Exceptions Raised for Warnings in Junos PyEZ Applications.