Supported Platforms
Junos Named Templates in the jcs Namespace
The templates are discussed in more detail in the following sections:
jcs:edit-path Template
XSLT Syntax
<xsl:call-template name="jcs:edit-path">
<xsl:with-param name="dot" select="expression"/>
</xsl:call-template>
SLAX Syntax
call jcs:edit-path($dot=expression);
Description
Generate an <edit-path> element suitable for inclusion in an <xnm:error> or <xnm:warning> element. This template converts a location in the configuration hierarchy into the standard text representation that you would see in the Junos OS configuration mode banner. By default, the location of the configuration error is passed into the jcs:edit-path template as the value of dot. This location defaults to “ . ”, the current position in the XML hierarchy. You can alter the default by including a valid XPath expression for the dot parameter when you call the template.
Parameters
dot | — | XPath expression specifying the hierarchy level. The default location is the position in the XML hierarchy that the script is currently evaluating. You can alter the default when you call the template by including a valid XPath expression either for the dot parameter in SLAX scripts or for the select attribute of the dot parameter in XSLT scripts. |
Usage Examples
The following example demonstrates how to call the jcs:edit-path template in a commit script and set the context to the [edit chassis] hierarchy level:
<xsl:if test="not(chassis/source-route)">
<xnm:warning>
<xsl:call-template name="jcs:edit-path">
<xsl:with-param name="dot" select="chassis"/>
</xsl:call-template>
<message>IP source-route processing is not enabled.</message>
</xnm:warning>
</xsl:if>
When you commit a configuration that does not enable IP source routing, the code generates an <xnm:warning> element, which results in the following command-line interface (CLI) output:
user@host# commit[edit chassis] # The hierarchy level is generated by the jcs:edit-path template.
warning: IP source-route processing is not enabled.
commit complete
jcs:emit-change Template
XSLT Syntax
<xsl:call-template name="jcs:emit-change">
<xsl:with-param name="content">
...
</xsl:with-param>
<xsl:with-param name="dot" select="expression"/>
<xsl:with-param name="message">
<xsl:text>message</xsl:text>
</xsl:with-param>
<xsl:with-param name="name" select="name($dot)"/>
<xsl:with-param name="tag" select="'(change | transient-change)'"/>
</xsl:call-template>
SLAX Syntax
call jcs:emit-change($dot=expression, $name = name($dot), $tag = "(change | transient-change)" {
with $content = {
...
}
with $message = {
expr "message";
}
}Description
Generate a <change> or <transient-change> element, which results in a persistent or transient change to the configuration.
Parameters
This template includes the following optional parameters:
content | — | Content of the persistent or transient change, relative to dot. |
dot | — | XPath expression specifying the hierarchy level at which the change will be made. The default location is the position in the XML hierarchy that the script is currently evaluating. You can alter the default when you call the template by including a valid XPath expression either for the dot parameter in SLAX scripts or for the select attribute of the dot parameter in XSLT scripts. |
message | — | Warning message displayed in the CLI notifying the user that the configuration has been changed. The message parameter automatically includes the edit path, which defaults to the current location in the XML hierarchy. To change the default edit path, specify a valid XPath expression either for the dot parameter in SLAX scripts or for the select attribute of the dot parameter in XSLT scripts. |
name | — | Allows you to refer to the current element or attribute. The name() XPath function returns the name of an element or attribute. The name parameter defaults to the value name($dot), which is the name of the element in dot (which in turn defaults to “ . ”, which is the current element). |
tag | — | Type of change to generate. By default, the jcs:emit-change template generates a persistent change, as designated by the 'change' expression. To specify a transient change, you must include the tag parameter and include the 'transient-change' expression. |
Usage Examples
The following example demonstrates how to call the jcs:emit-change template in a commit script:
<xsl:template match="configuration">
<xsl:for-each select="interfaces/interface/unit[family/iso]">
<xsl:if test="not(family/mpls)">
<xsl:call-template name="jcs:emit-change">
<xsl:with-param name="message">
<xsl:text>Adding 'family mpls' to ISO-enabled interface</xsl:text>
</xsl:with-param>
<xsl:with-param name="content">
<family>
<mpls/>
</family>
</xsl:with-param>
</xsl:call-template>
</xsl:if>
</xsl:for-each>
</xsl:template>
When you commit a configuration that includes one or more interfaces that have IS-IS enabled but do not have the family mpls statement included at the [edit interfaces interface-name unit logical-unit-number] hierarchy level, the jcs:emit-change template adds the family mpls statement to the configuration and generates the following CLI output:
[edit]
user@host# commit[edit interfaces interface so-1/2/3 unit 0]
warning: Adding 'family mpls' to ISO-enabled interface
[edit interfaces interface so-1/2/3 unit 0]
warning: Adding ISO-enabled interface so-1/2/3.0 to [protocols mpls]
[edit interfaces interface so-1/3/2 unit 0]
warning: Adding 'family mpls' to ISO-enabled interface
[edit interfaces interface so-1/3/2 unit 0]
warning: Adding ISO-enabled interface so-1/3/2.0 to [protocols mpls]
commit complete
The content parameter of the jcs:emit-change template provides a simpler method for specifying a change to the configuration. For example, consider the following code:
<xsl:with-param name="content">
<family>
<mpls/>
</family>
</xsl:with-param>
The jcs:emit-change template converts the content parameter into a <change> request. The <change> request inserts the provided partial configuration content into the complete hierarchy of the current context node. Thus, the jcs:emit-change template changes the hierarchy information in the content parameter into the following code:
<change>
<interfaces>
<interface>
<name><xsl:value-of select="name"/></name>
<unit>
<name><xsl:value-of select="unit/name"/></name>
<family>
<mpls/>
</family>
</unit>
</interface>
</interfaces>
</change>
If a transient change is required, the tag parameter can be passed in as 'transient-change', as shown here:
<xsl:with-param name="tag" select="'transient-change'"/>
The extra quotation marks are required to allow XSLT to distinguish between the string "transient-change" and the contents of a node named "transient-change". If the change is relative to a node other than the context node, the parameter dotcan be set to that node, as shown in the following example, where context is set to the [edit chassis] hierarchy level:
<xsl:for-each select="interfaces/interface/unit">
...
<xsl:call-template name="jcs:emit-change">
<xsl:with-param name="dot" select="chassis"/>
...
See also Example: Imposing a Minimum MTU Setting.
jcs:emit-comment Template
XSLT Syntax
<junos:comment>
<xsl:text>...</xsl:text>
</junos:comment>
Description
Emit a simple comment that indicates a change was made by a commit script. The template contains a <junos:comment> element. You never call the jcs:emit-comment template directly. Rather, you include its <junos:comment> element and the child element <xsl:text> inside a call to the jcs:emit-change template, a <change> element, or a <transient-change> element.
Usage Examples
The following example demonstrates how to call this template in a commit script:
<xsl:call-template name="jcs:emit-change">
<xsl:with-param name="content">
<term>
<name>very-last</name>
<junos:comment>
<xsl:text>This term was added by a commit script</xsl:text>
</junos:comment>
<then>
<accept/>
</then>
</term>
</xsl:with-param>
</xsl:call-template>
When you issue the show firewall configuration mode command, the following output appears:
[edit]
user@host# show firewallfamily inet {
term very-last {
/* This term was added by a commit script */
then accept;
}
}jcs:grep Template
XSLT Syntax
<xsl:call-template name="jcs:grep">
<xsl:with-param name="filename" select="filename"/>
<xsl:with-param name="pattern" select="pattern"/>
</xsl:call-template>
SLAX Syntax
call jcs:grep($filename=filename, $pattern=pattern);
Description
Search the given input file for all instances matching the specified regular expression and write the matching strings and corresponding lines to the result tree. The pattern is matched to each line of the file. The template does not support matching a pattern spanning multiple lines.
If the regular expression contains a syntax error, the template generates an error for every line of the file. For each match, the template adds a <match> element, which contains <input> and <output> child tags, to the result tree. The template writes the matching string to the <output> element and writes the corresponding matching line to the <input> element.
<match> {
<input>
<output>
}Starting with Junos OS Release 11.1, if an absolute path is
not specified for the input file, the default path is relative to
the user’s home directory for op scripts, and it is relative
to the /var/tmp/ directory for commit
scripts and for event scripts that are enabled at the [edit event-options event-script] hierarchy level. For event scripts that are enabled
at the [edit system scripts] hierarchy level, the default
path is relative to the top-level directory, /.
Parameters
filename | — | (Mandatory) Absolute or relative path and filename of the file to search. Starting with Junos OS Release 11.1, if you do not specify an
absolute path, the path is relative to the user’s home directory
for op scripts, and it is relative to the |
pattern | — | (Mandatory) Regular expression. |
Usage Examples
Example: Searching Files Using an Op Script
jcs:load-configuration Template
XSLT Syntax
<xsl:call-template name="jcs:load-configuration">
<xsl:with-param name="action" select="(merge | override | replace)"/>
<xsl:with-param name="commit-options" select="node-set"/>
<xsl:with-param name="configuration" select="configuration-data"/>
<xsl:with-param name="connection" select="connection-handle"/>
<xsl:with-param name="rollback" select="number"/>
</xsl:call-template>
SLAX Syntax
call jcs:load-configuration($action="(merge | override | replace)", $commit-options=node-set, $configuration=configuration-data, $connection=connection-handle, $rollback=number);
Description
Make structured changes to the Junos OS configuration using an op script. When called, the template locks the configuration database, loads the configuration changes, commits the configuration, and then unlocks the configuration database.
The jcs:load-configuration template makes changes to the configuration in configure exclusive mode. In this mode, Junos OS locks the candidate global configuration for as long as the script accesses the shared database and makes changes to the configuration without interference from other users.
If another user is currently editing the configuration in configure exclusive mode or if the database is already locked when the template is called, the call fails. In addition, if there are existing, uncommitted changes to the configuration when the template is called, the commit will fail. If the template call is successful but the commit fails, Junos OS discards the uncommitted changes and rolls back the configuration.
Parameters
action | — | Specifies how to load the configuration changes with respect to the candidate configuration. The following options are supported:
|
commit-options | — | Node set defining options that customize the commit command. The default value is null. Supported commit options are:
|
configuration | — | XML configuration changes. The configuration changes are incorporated into the candidate configuration as specified by the action parameter. Starting with Junos OS Release 12.2, you can also supply a NULL configuration. If the configuration data value is NULL, the template performs a simple commit of the candidate configuration. |
connection | — | Connection handle generated by a call to the jcs:open() function. |
rollback | — | Return to a previously committed configuration. Specify the rollback number of the configuration, and the configuration you specify is loaded from the associated file. The software saves the last 50 committed configurations. The rollback parameter is available starting with Junos OS Release 12.2. |
Usage Examples
The following example calls the jcs:load-configuration template to modify the configuration to disable an interface. The interface name is supplied by the user and stored in the variable interface-name. All of the values required for the jcs:load-configuration template are defined as variables, which are then passed into the template as arguments.
In this example, the configuration data that includes the changes to the configuration are stored in the variable disable. This is the value used for the configuration parameter of the jcs:load-configuration template. The load-action variable is initialized to merge, which merges the configuration changes in the disable variable with the candidate configuration. This is the equivalent of the CLI configuration mode command load merge.
The options variable uses the := operator to create a node-set, which is passed to the template as the value of the commit-options parameter. This example uses the synchronize commit option . If the commit succeeds, it will commit the configuration changes on both Routing Engines. The log tag is also included to add the description of the commit to the commit log file for future reference.
The call to the jcs:open() function opens a connection with the Junos OS management process (mgd) and returns a connection handle that is stored in the conn variable. All of the defined variables are passed as arguments to the jcs:load-configuration template at the time that it is called.
SLAX syntax:
var $disable = {
<configuration> {
<interfaces> {
<interface> {
<name> $interface-name;
<disable>;
}
}
}
}
var $load-action = "merge";
var $options := {
<commit-options> {
<synchronize>;
<log> "disabling interface on both routing engines";
}
var $conn = jcs:open();
var $disable-results := {
call jcs:load-configuration($action=$load-action, $commit-options=$options,
$configuration = $disable, $connection = $conn);
}
if ($disable-results//xnm:error) {
for-each ($disable-results//xnm:error) {
<output> message;
}
}
var $close-results = jcs:close($conn);The := operator copies the results of the jcs:load-configuration template call to a temporary variable and runs the node-set function on that variable. The := operator ensures that the disable-results variable is a node-set rather than a result tree fragment so that the script can access the contents. The if code block is included to output any error messages that may indicate a problem in committing the configuration. The jcs:close function closes the connection.
In XSLT, the code corresponding to the SLAX call to jcs:load-configuration template is:
<xsl:variable name="disable-results-temp">
<xsl:call-template name="jcs:load-configuration">
<xsl:with-param name="action" select="$load-action"/>
<xsl:with-param name="commit-options" select="$options"/>
<xsl:with-param name="configuration" select="$disable"/>
<xsl:with-param name="connection" select="$conn"/>
</xsl:call-template>
</xsl:variable>
<xsl:variable xmlns ext="http:xmlsoft.org/XSLT/namespace" \
name="disable-results" select="ext:node-set($disable-results-temp)"/>
jcs:statement Template
XSLT Syntax
<xsl:call-template name="jcs:statement">
<xsl:with-param name="dot" select="expression"/>
</xsl:call-template>
SLAX Syntax
call jcs:statement($dot=expression);
Description
Generate a <statement> element suitable for inclusion in an <xnm:error> or <xnm:warning> element. This location defaults to “ . ”, the current position in the XML hierarchy. If the error is not at the current position in the XML hierarchy, you can alter the default when you call the template by including a valid XPath expression either for the dot parameter in SLAX scripts or for the select attribute of the dot parameter in XSLT scripts.
Parameters
dot | — | XPath expression specifying the hierarchy level. The default location is the position in the XML hierarchy that the script is currently evaluating. You can alter the default when you call the template by including a valid XPath expression either for the dot parameter in SLAX scripts or for the select attribute of the dot parameter in XSLT scripts. |
Usage Examples
The following example demonstrates how to call the jcs:statement template in a commit script:
<xnm:error>
<xsl:call-template name="jcs:edit-path"/>
<xsl:call-template name="jcs:statement">
<xsl:with-param name="dot" select="mtu"/>
</xsl:call-template>
<message>
<xsl:text>SONET interfaces must have a minimum MTU of </xsl:text>
<xsl:value-of select="$min-mtu"/>
<xsl:text>.</xsl:text>
</message>
</xnm:error>
When you commit a configuration that includes a SONET/SDH interface with a maximum transmission unit (MTU) setting less than a specified minimum, the <xnm:error> element results in the following CLI output:
[edit]
user@host# commit[edit interfaces interface so-1/2/3] 'mtu 576;' # mtu statement generated by the jcs:statement template SONET interfaces must have a minimum MTU of 2048.
error: 1 error reported by commit scripts
error: commit script failure
The test of the MTU setting is not performed in the <xnm:error> element. For the full example, see Example: Imposing a Minimum MTU Setting.
