How Commit Scripts Work
Commit scripts contain instructions that enforce custom configuration rules. When you commit the
configuration, the system invokes the commit scripts during the commit
process before the standard Junos OS validity checks are performed. You
enable commit scripts by configuring the names of one or more commit script
files at the [edit system scripts commit] hierarchy level.
These files must be added to the appropriate commit script directory on the
device. For more information, see Store and Enable Junos Automation Scripts
When you perform a commit operation, Junos OS executes each commit script in turn, passing the information in the post-inheritance candidate configuration to the script. The script inspects the configuration, performs the necessary tests and validations, and generates a set of instructions for performing certain actions. After all commit scripts are executed, Junos OS then processes all of the scripts’ instructions. If a commit script instruction does not halt the commit process, then Junos OS applies all the commit script changes and performs its final inspection of the checkout configuration.
You might need to increase the amount of memory allocated to commit scripts to accommodate the
processing of large configurations. To increase the maximum memory
allocated for each executed commit script, configure the
max-datasize size
statement with an appropriate memory limit in bytes at the
[edit system scripts commit] hierarchy
level before committing the configuration.
Commit script actions can include generating error, warning, and system log messages. If a script generate an error, the commit operation fails and the candidate configuration remains unchanged. This is the same behavior that occurs with standard commit errors. Commit scripts can also generate changes to the system configuration. Because the changes are loaded before the standard validation checks are performed, they are validated for correct syntax, just like statements already present in the configuration before the script is applied. If the syntax is correct, the configuration is activated and becomes the active, operational device configuration.
Commit scripts cannot make configuration changes to protected statements or within protected hierarchies. If a commit script attempts to modify or delete a protected statement or hierarchy, Junos OS issues a warning that the change cannot be made. Failure to modify a protected configuration element does not halt the commit script or the commit process.
The following sections discuss several important concepts related to the commit script input and output:
Commit Script Input
The input for a commit script is the post-inheritance candidate configuration in Junos XML API format. The term post-inheritance means that all configuration group values have been inherited by their targets in the candidate configuration and that the inactive portions of the configuration have been removed. For more information about configuration groups, see the CLI User Guide.
When you issue the commit command, Junos OS automatically
generates the candidate configuration in XML format and reads it into
the management (mgd) process, at which
time the input is evaluated by any commit scripts.
To display the XML format of the post-inheritance candidate
configuration in the CLI, issue the show | display
commit-scripts view command.
[edit] user@host# show | display commit-scripts view
To display all configuration groups data, including script-generated
changes to the groups, issue the show groups | display
commit-scripts command.
[edit] user@host# show groups | display commit-scripts
Commit Script Output
During the commit process, enabled commit scripts are executed sequentially, and the commit script output, or instruction set, is provided to Junos OS. After all commit scripts have been executed, Junos OS then processes all of the scripts’ instructions.
Commit script actions can include generating warning, error,
and system log messages, and making persistent and transient changes
to the configuration. Table 1 briefly outlines
the various elements, templates, and functions that commit scripts
can use to instruct Junos OS to perform various actions during the
commit process. In some cases, there are multiple ways to perform
the same action. Because SLAX and XSLT scripts return a result tree,
output elements like <syslog><message> that are present in SLAX and XSLT scripts are added directly into
the result tree.
Commit Script Output |
SLAX / XSLT |
Python |
|---|---|---|
Generate a warning message to the committing user. |
|
jcs.emit_warning() |
Generate an error message and cause the commit operation to fail. |
|
jcs.emit_error() |
Generate a system log message. |
jcs:syslog()
|
jcs.syslog() |
Generate a persistent change to the configuration. |
|
emit_change(content, 'change', format) |
Generate a transient change to the configuration. |
|
emit_change(content, 'transient-change', format) |
Generate a persistent change relative to the current context node as defined by an XPath expression. |
XSLT <xsl:call-template name="jcs:emit-change"> <xsl:with-param name="content"> SLAX call jcs:emit-change() {
with $content = { }
}
|
– |
Generate a transient change relative to the current context node as defined by an XPath expression. |
XSLT <xsl:call-template name="jcs:emit-change"> <xsl:with-param name="tag" select="'transient-change'"/> <xsl:with-param name="content"> SLAX call jcs:emit-change() {
with $tag = "transient-change";
with $content = { }
}
|
– |
Generate a warning message in conjunction with a configuration change. You can use this set of tags to generate a notification that the configuration has been changed. |
XSLT <xsl:call-template name="jcs:emit-change"> <xsl:with-param name="message"> <xsl:text> SLAX call jcs:emit-change() {
with $message = {
expr "message";
}
}
|
jcs.emit_warning() |
Junos OS processes this output and performs the appropriate actions. Errors and warnings are passed back to the Junos OS CLI or to a Junos XML protocol client application. The presence of an error automatically causes the commit operation to fail. Persistent and transient changes are loaded into the appropriate configuration database.
To test the output of error, warning, and system log messages
from commit scripts, issue the commit check | display xml command.
[edit] user@host# commit check | display xml
To display a detailed trace of commit script processing, issue
the commit check | display detail command.
[edit] user@host# commit check | display detail
System log messages do not appear in the trace output, so you cannot use the commit check operation to test script-generated system log messages. Furthermore, system log messages are written to the system log during a commit operation, but not during a commit check operation.
Commit Scripts and the Junos OS Commit Model
Junos OS uses a commit model to update the device's configuration. This model allows you to make a series of changes to a candidate configuration without affecting the operation of the device. When the changes are complete, you can commit the configuration. The commit operation saves the candidate configuration changes into the current configuration.
When you commit a set of changes in the candidate configuration, two methods are used to forward these changes to the current configuration:
Standard commit model—Used when no commit scripts are active on the device.
Commit script model—Incorporates commit scripts into the commit model.
Standard Commit Model
In the standard commit model, the management (mgd) process validates the candidate configuration based on standard Junos OS validation rules. If the configuration file is valid, it becomes the current active configuration. Figure 1 and the accompanying discussion explain how the standard commit model works.
In the standard commit model, the software performs the following steps:
When the candidate configuration is committed, it is copied to become the checkout configuration.
The mgd process validates the checkout configuration.
If no error occurs, the checkout configuration is copied as the current active configuration.
Commit Model with Commit Scripts
When commit scripts are added to the standard commit model, the process becomes more complex. The mgd process first passes an XML-formatted checkout configuration to a script driver, which handles the verification of the checkout configuration by the commit scripts. When verification is complete, the script driver returns an action file to the mgd process. The mgd process follows the instructions in the action file to update the candidate and checkout configurations, issue messages to the CLI or client application, and write information to the system log as required. After processing the action file, the mgd process performs the standard Junos OS validation. Figure 2 and the accompanying discussion explain this process.
In the commit script model, Junos OS performs the following steps:
When the candidate configuration is committed, the mgd process sends the XML-formatted candidate configuration to the script driver.
Each enabled commit script is invoked against the candidate configuration, and each script can generate a set of actions for the mgd process to perform. The actions are collected in an action file.
The mgd process performs the following actions for commit script error, warning, and system log messages in the action file:
error—The mgd process halts the commit process (that is, the commit operation fails), returns an error message to the CLI or Junos XML protocol client, and takes no further action.
warning—The mgd process forwards the message to the CLI or the Junos XML protocol client.
system log message—The mgd process forwards the message to the system log process.
If the action file includes any persistent changes, the mgd process loads the requested changes into the candidate configuration.
The candidate configuration is copied to become the checkout configuration.
If the action file includes any transient changes, the mgd process loads the requested changes into the checkout configuration.
The mgd process validates the checkout configuration.
If there are no validation errors, the checkout configuration is copied to become the current active configuration.
Commit scripts cannot make configuration changes to protected statements or within protected hierarchies. If a commit script attempts to modify or delete a protected statement or hierarchy, Junos OS issues a warning that the change cannot be made. Failure to modify a protected configuration element does not halt the commit script or the commit process.
Changes that are made to the candidate configuration during the commit operation are not evaluated by the custom rules during that commit operation. However, persistent changes are maintained in the candidate configuration and are evaluated by the custom rules during subsequent commit operations. For more information about how commit scripts change the candidate configuration, see Avoiding Potential Conflicts When Using Multiple Commit Scripts.
Transient changes are never evaluated by the custom rules in commit scripts, because they are made to the checkout configuration only after the commit scripts have evaluated the candidate configuration and the candidate is copied to become the checkout configuration. To remove a transient change from the configuration, remove, disable, or deactivate the commit script (as discussed in Control the Execution of Commit Scripts During Commit Operations), or comment out the code that generates the transient change.
For more information about differences between persistent and transient changes, see Overview of Generating Persistent or Transient Configuration Changes Using Commit Scripts.