Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

How Commit Scripts Work

 

Commit scripts contain instructions that enforce custom configuration rules and are invoked during the commit process before the standard Junos OS validity checks are performed. You enable commit scripts by listing 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.

When you perform a commit operation, Junos OS executes each script in turn, passing the information in the post-inheritance candidate configuration to the scripts. 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 have been executed, Junos OS then processes all of the scripts’ instructions. If the commit process is not halted by a commit script, then Junos OS applies all the commit script changes and performs its final inspection of the checkout configuration.

Note

When committing a configuration that is inspected by one or more commit scripts, you might need to increase the amount of memory allocated to the commit scripts to accommodate the processing of large configurations. By default, the maximum amount of memory allocated for the data segment portion of an executed script is half of the total available memory of the system, up to a maximum value of 128 MB. 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 errors are generated, 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.

To display all configuration groups data, including script-generated changes to the groups, issue the show groups | display commit-scripts command.

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.

Table 1: Commit Scripts Actions and Output

Commit Script Output

SLAX / XSLT

Python

Generate a warning message to the committing user.

<xnm:warning>

jcs.emit_warning()

Generate an error message and cause the commit operation to fail.

<xnm:error>

jcs.emit_error()

Generate a system log message.

jcs:syslog()

<syslog><message>

jcs.syslog()

Generate a persistent change to the configuration.

<change>

emit_change(content, 'change', format)

Generate a transient change to the configuration.

<transient-change>

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.

To display a detailed trace of commit script processing, issue the commit check | display detail command.

Note

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.

Figure 1: Standard Commit Model
Standard Commit Model

In the standard commit model, the software performs the following steps:

  1. When the candidate configuration is committed, it is copied to become the checkout configuration.

  2. The mgd process validates the checkout configuration.

  3. 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.

Figure 2: Commit Model with Commit Scripts Added
Commit Model with Commit
Scripts Added

In the commit script model, Junos OS performs the following steps:

  1. When the candidate configuration is committed, the mgd process sends the XML-formatted candidate configuration to the script driver.

  2. 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.

  3. 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.

  4. If the action file includes any persistent changes, the mgd process loads the requested changes into the candidate configuration.

  5. The candidate configuration is copied to become the checkout configuration.

  6. If the action file includes any transient changes, the mgd process loads the requested changes into the checkout configuration.

  7. The mgd process validates the checkout configuration.

  8. If there are no validation errors, the checkout configuration is copied to become the current active configuration.

Note

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 Controlling 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.