Junos Snapshot Administrator Configuration File
Understanding the Junos Snapshot Administrator Configuration File
The Junos Snapshot Administrator configuration file defines
the scope of a snapshot and the evaluation criteria for either a single
snapshot or a comparison of two snapshots. You provide the location
of the Junos Snapshot Administrator configuration file as an argument
to the jsnap command.
In the Junos Snapshot Administrator configuration file, curly braces delimit code blocks, and semicolons signal the end of a statement or command. You can insert comments into the configuration file by using either a hash (#) or a semicolon (;) at the start of a line.
The Junos Snapshot Administrator configuration file consists
of a required do code block placed at the
beginning of the configuration file followed by any number of user-defined
test sections. Details of the individual configuration file components
are described in the following sections:
do Section
The do code block lists the name
of each test section that will be used in the snapshot. This section
is mandatory and must be placed at the start of the configuration
file. You can define as many test sections as desired, but you must
include the test section name in the do code block in order to execute that test. The syntax of the do code block is:
do {
test-section-name1;
test-section-name2;
test-section-name3;
}For example, the following do code
block lists five test sections. When Junos Snapshot Administrator
references the configuration file, although the configuration file
might define more than five test sections, the tool only executes
the five test sections listed in the do code block.
do {
re0-master;
ospf-checks;
l2vpn-list;
vpls-list;
bgp-checks;
}
Test Sections
Within the configuration file, you define one or more test sections.
The test sections, which are placed in any order after the do code block, define the scope of a snapshot and the
evaluation criteria for a single snapshot or a comparison of two snapshots.
Each test section consists of a unique configuration stanza, which contains:
The section name—Unique, user-defined string that should describe the check being performed.
One
commandstatement—Specifies the Junos OS operational mode command that is executed to collect the data.One or more
itemoriteratecontent section declarations—Defines the test cases used to evaluate the data.
The general syntax of the test section code block is:
test-section-name {
command command-syntax;
(item | iterate) xpath-expression {
[id xpath-expression;]
# test cases
}
}For example:
re0-master {
command show chassis routing-engine;
item route-engine[slot = '0'] {
is-equal mastership-state, "master" {
info re0 is always master;
err " re0 is not master, rather %s", mastership-state;
err " Correct so that re0 is the master!";
}
}
}
The test section components are described in detail in the following sections:
Test Section Name
Test section names are unique, user-defined strings that should
describe the check being performed. You add the names of the test
sections that you want to execute to the do code block at the start of the configuration file. When Junos Snapshot
Administrator references the configuration file, the tool executes
any test sections that are listed in the do code block.
Ideally, you should create descriptive test section names so
that you or anyone else working with the configuration file can quickly
discern the scope and purpose of each test section long after the
configuration file is created. For example, you might use active-chassis-alarm-check for a test section that
checks whether there are any active chassis alarms, as shown here:
active-chassis-alarm-check {
command show chassis alarms;
item alarm-summary {
exists no-active-alarm {
info No chassis alarms;
err "There are %s chassis alarms", active-alarm-count;
}
}
}
Test Section Command Statement
Each test section consists of a single command identifier followed by the Junos OS operational mode command that
is executed to collect the desired data for that check. For example,
if you want to collect and evaluate data about the OSPF neighbors
for an interface, you would include the command identifier followed by the show ospf neighbor operational
mode command, as shown here:
ospf-neighbor-check {
command show ospf neighbor;
iterate ospf-neighbor {
id interface-name;
#
# test cases
#
}
}
Provided the ospf-neighbor-check section
name is included in the do code block,
the resulting snapshot will include the XML data from the show
ospf neighbor command output. For more information about Junos
OS operational mode commands, see the Junos XML API Operational
Reference. A sample of the show ospf neighbor output is shown here:
<ospf-neighbor-information>
<ospf-neighbor>
<neighbor-address>10.1.12.2</neighbor-address>
<interface-name>ae18.0</interface-name>
<ospf-neighbor-state>Full</ospf-neighbor-state>
<neighbor-id>10.0.0.2</neighbor-id>
<neighbor-priority>128</neighbor-priority>
<activity-timer>3</activity-timer>
</ospf-neighbor>
<ospf-neighbor>
<neighbor-address>10.1.15.2</neighbor-address>
<interface-name>ae19.0</interface-name>
<ospf-neighbor-state>Full</ospf-neighbor-state>
<neighbor-id>10.0.0.5</neighbor-id>
<neighbor-priority>128</neighbor-priority>
<activity-timer>3</activity-timer>
</ospf-neighbor>
</ospf-neighbor-information>
You can evaluate specific elements in the snapshot output or compare elements across multiple snapshots by defining test cases.
Test Section Evaluation Criteria
The test section command statement
can be followed by either an item or iterate content section declaration, within which you
define one or more test cases for evaluating the captured snapshot
data. You use the item statement to uniquely
identify a specific element, and the iterate statement to iterate over multiple elements.
The general syntax for the content section declaration is:
(item | iterate) xpath-expression {
test-operator operator-params {
#specify an ID for test operators that compare two collections
[id xpath-expression;]
info string;
err "string";
}
}Each test case is defined by a test operator followed by any
required parameters. For more information about available test operators
see Understanding Junos Snapshot Administrator Test Operators and Junos Snapshot Administrator Test Operators Summary. Within the test-case
code block you define an info statement
to provide information about the test case and expected operating
conditions. You also define one or more err statements, which are generated when the content fails the specific
test case.
The following example has a test case that checks the XML output
of the show chassis routing-engine command to determine
if the Routing Engine in slot 0 is the primary Routing Engine. If
the mastership-state of the Routing Engine
in slot 0 is not equal to "master", the code generates two err statements.
re0-master {
command show chassis routing-engine;
item route-engine[slot = '0'] {
is-equal mastership-state, "master" {
info RE-0 is always master;
err " RE-0 is not master, rather %s", mastership-state;
err " Correct error so that RE-0 is the master";
}
}
}
When using certain test operators to compare element values
across two snapshots, in order to map the first snapshot data item
to a second snapshot data item, you must select elements of the data
that create a unique ID. To create a unique ID for a test case, you
include the id statement followed by an
XPath expression that references the unique element. To create a unique
ID based on multiple element values, you define multiple id statements. You can also construct ID values relative
to the content value. For detailed information about creating ID values,
see Understanding Junos Snapshot Administrator Test Operators.
Example: Creating the Junos Snapshot Administrator Configuration File
This example creates a basic sample Junos Snapshot Administrator configuration file.
Requirements
Junos Snapshot Administrator Release 1.0 is installed on the server.
Overview
This example creates a Junos Snapshot Administrator configuration
file with one test section named re0-master. The re0-master test section retrieves
and parses the XML output from the Junos OS operational mode command show chassis routing-engine. A sample of the XML output
from a dual Routing Engine device is shown here:
<route-engine-information xmlns="http://xml.juniper.net/junos/11.4R1/junos-chassis">
<route-engine>
<slot>0</slot>
<mastership-state>master</mastership-state>
<mastership-priority>master (default)</mastership-priority>
<status>OK</status>
<temperature junos:celsius="30">30 degrees C / 86 degrees F</temperature>
<cpu-temperature junos:celsius="27">
27 degrees C / 80 degrees F
</cpu-temperature>
<memory-dram-size>768</memory-dram-size>
<memory-buffer-utilization>48</memory-buffer-utilization>
<cpu-user>1</cpu-user>
<cpu-background>0</cpu-background>
<cpu-system>5</cpu-system>
<cpu-interrupt>1</cpu-interrupt>
<cpu-idle>94</cpu-idle>
<model>RE-5.0</model>
<serial-number>19995858810</serial-number>
<start-time junos:seconds="1337708989">
2012-05-22 10:49:49 PDT
</start-time>
<up-time junos:seconds="8735869">
101 days, 2 hours, 37 minutes, 49 seconds
</up-time>
<last-reboot-reason>
Router rebooted after a normal shutdown.
</last-reboot-reason>
<load-average-one>0.00</load-average-one>
<load-average-five>0.00</load-average-five>
<load-average-fifteen>0.00</load-average-fifteen>
</route-engine>
</route-engine-information>
For a dual Routing Engine device, the test case checks the XML
output to determine if the Routing Engine in slot 0 is the primary
Routing Engine. The test section uses the item route-engine[slot = '0'] expression to select the route-engine element that has the child element slot value of "0". The test case uses the is-equal test operator to compare the value of the mastership-state child element with the string value "master". If the test case returns
true, the Routing Engine in slot 0 is the primary Routing Engine.
If the test case returns false, the code reports two error statements.
The mandatory do section includes
the names of all test sections that should be executed when Junos
Snapshot Administrator references this configuration file. For this
example, the do section contains only re0-master.
Configuration
The Junos Snapshot Administrator configuration
consists of a mandatory do section and
one or more test sections.
How to Configure the Test Sections
Step-by-Step Procedure
The Junos Snapshot Administrator configuration consists of test sections that define the commands and evaluation criteria that are used in a snapshot or snapshot comparison. To configure a test section:
Name the test section using a unique and descriptive string.
re0-master { ... }Add the
commandstatement, and specify the Junos OS operational mode command that the code executes to retrieve the desired XML data.re0-master { command show chassis routing-engine; }Add the
iterateoritemstatement followed by the XPath expression that selects the desired elements.re0-master { command show chassis routing-engine; item route-engine[slot = '0'] { } }If the test section compares elements from two snapshots, add the
idstatement specifying a unique ID to map the first snapshot data item to the second snapshot data element.This example does not require an
idstatement.Create the test case condition used during the check.
re0-master { command show chassis routing-engine; item route-engine[slot = '0'] { is-equal mastership-state, "master" { } } }Within the test case code block, add the
infostatement describing the test case or normal operating conditions.re0-master { command show chassis routing-engine; item route-engine[slot = '0'] { is-equal mastership-state, "master" { info re0 is always master; } } }Within the test case code block, add one or more
errstatements, which are executed if the test case fails.re0-master { command show chassis routing-engine; item route-engine[slot = '0'] { is-equal mastership-state, "master" { info re0 is always master; err " re0 is not master, rather %s", mastership-state; err " Correct so that re0 is the master!"; } } }
How to Configure the "do" Section
Step-by-Step Procedure
The Junos Snapshot Administrator configuration file must
begin with a do code block that defines
the test sections to be used in the snapshot.
At the beginning of the configuration file, add the
docode block.do { }Add the name of each test section that will be used in the snapshot.
do { re0-master; }
Results
do {
re0-master;
}
re0-master {
command show chassis routing-engine;
item route-engine[slot = '0'] {
is-equal mastership-state, "master" {
info re0 is always master;
err " re0 is not master, rather %s", mastership-state;
err " Correct so that re0 is the master!";
}
}
}