Specifying the Scope of Configuration Information to Return

By including the appropriate optional child tag elements in the <get-configuration> tag element, a client application can request the entire configuration or specific portions of the configuration, as described in the following sections:

Requesting the Complete Configuration

To request the entire configuration, a client application encloses the <get-configuration/> tag in an <rpc> tag element:

When the application requests Junos XML-tagged output (the default), the Junos XML protocol server returns the requested configuration in <configuration> and <rpc-reply> tag elements. For information about the attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration.

<rpc-reply xmlns:junos="URL">
    <configuration attributes>
        <!-- Junos XML tag elements for all configuration elements -->
    </configuration>
</rpc-reply>

To specify the source of the output (candidate or active configuration) and request special formatting of the output (for example, formatted ASCII text or an indicator for identifiers), the application can include attributes in the <get-configuration/> tag, its opening <junoscript> tag, or both. For more information, see Specifying the Source and Output Format of Configuration Information.

The following example shows how to request the complete candidate configuration tagged with Junos XML tag elements (the default). In actual output, the JUNOS-version variable is replaced by a value such as 10.3R1 for the initial version of Junos OS Release 10.3.

Requesting a Hierarchy Level or Container Object Without an Identifier

To request complete information about all child configuration elements at a hierarchy level or in a container object that does not have an identifier, a client application emits a <get-configuration> tag element that encloses the tag elements representing all levels in the configuration hierarchy from the root (represented by the <configuration> tag element) down to the level’s immediate parent level. An empty tag represents the requested level. The entire request is enclosed in an <rpc> tag element.

<rpc>
    <get-configuration>
        <configuration>
            <!-- opening tags for each parent of the level -->
                <requested-level/> 
            <!-- closing tags for each parent of the level -->
        </configuration>
    </get-configuration>
</rpc>

When the application requests Junos XML-tagged output (the default), the Junos XML protocol server returns the requested section of the configuration in <configuration> and <rpc-reply> tag elements. For information about the attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration.

<rpc-reply xmlns:junos="URL">
    <configuration attributes>
        <!-- opening tags for each parent of the level -->
            <hierarchy-level>
                <!-- child tag elements of the level -->
            </hierarchy-level>
        <!-- closing tags for each parent of the level -->
    </configuration>
</rpc-reply>

To specify the source of the output (candidate or active configuration) and request special formatting of the output (for example, formatted ASCII text or an indicator for identifiers), the application can include attributes in the opening <get-configuration> tag, its opening <junoscript> tag, or both. For more information, see Specifying the Source and Output Format of Configuration Information.

The application can also request additional configuration elements of the same or other types by including the appropriate tag elements in the same <get-configuration> tag element. For more information, see Requesting Multiple Configuration Elements Simultaneously.

The following example shows how to request the contents of the [edit system login] hierarchy level in the candidate configuration. The output is tagged with Junos XML tag elements (the default).

Requesting All Configuration Objects of a Specified Type

To request complete information about all configuration objects of a specified type in a hierarchy level, a client application emits a <get-configuration> tag element that encloses the tag elements representing all levels of the configuration hierarchy from the root (represented by the <configuration> tag element) down to the immediate parent level for the object type. An empty tag represents the requested object type. The entire request is enclosed in an <rpc> tag element.

This type of request is useful when the object’s parent hierarchy level has child objects of multiple types and the application is requesting just one of the types. If the requested object is the only possible child type, then this type of request yields the same output as a request for the complete parent hierarchy (described in Requesting a Hierarchy Level or Container Object Without an Identifier).

<rpc>
    <get-configuration>
        <configuration>
            <!-- opening tags for each parent of the object type -->
                <object-type/> 
            <!-- closing tags for each parent of the object type -->
        </configuration>
    </get-configuration>
</rpc>

When the application requests Junos XML-tagged output (the default), the Junos XML protocol server returns the requested objects in <configuration> and <rpc-reply> tag elements. For information about the attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration.

<rpc-reply xmlns:junos="URL">
    <configuration attributes>
        <!-- opening tags for each parent of the object type -->
            <first-object>
                <!-- child tag elements for the first object -->
            </first-object>
            <second-object>
                <!-- child tag elements for the second object -->
            </second-object>
            <!-- additional instances of the object -->
        <!-- closing tags for each parent of the object type -->
    </configuration>
</rpc-reply>

To specify the source of the output (candidate or active configuration) and request special formatting of the output (for example, formatted ASCII text or an indicator for identifiers), the application can include attributes in the opening <get-configuration> tag, its opening <junoscript> tag, or both. For more information, see Specifying the Source and Output Format of Configuration Information.

Requesting a Specified Number of Configuration Objects

To request information about a specific number of configuration objects of a specific type, a client application emits the <get-configuration> tag element and encloses the tag elements that represent all levels of the configuration hierarchy from the root (represented by the <configuration> tag element) down to the immediate parent level for the object type. An empty tag represents the requested object type, and the following attributes are included in it:

count, to specify the number of objects to return
start, to specify the index number of the first object to return (1 for the first object, 2 for the second, and so on)

(If the application is requesting only the first object in the hierarchy, it includes the count="1" attribute and omits the start attribute.) The application encloses the entire request in an <rpc> tag element:

<rpc>
    <get-configuration>
        <configuration>
            <!-- opening tags for each parent of the object -->
                <object-type  count="count" start="index"/> 
            <!-- closing tags for each parent of the object -->
        </configuration>
    </get-configuration>
</rpc>

When the application requests Junos XML-tagged output (the default), the Junos XML protocol server returns the requested objects in <configuration> and <rpc-reply> tag elements, starting with the object specified by the start attribute and running consecutively. In the opening container tag for each object, it includes two attributes:

junos:position, to specify the object’s numerical index
junos:total, to report the total number of such objects that exist in the hierarchy

In the following, the identifier tag element is called <name>. (For information about the attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration.)

<rpc-reply xmlns:junos="URL">
    <configuration attributes>
        <!-- opening tags for each parent of the object type -->
            <first-object junos:position="index1" junos:total="total">
                <name>identifier-for-first-object</name>
                <!-- other child tag elements of the first object -->
            </first-object>
            <second-object junos:position="index2" junos:total="total">
                <name>identifier-for-second-object</name>
                <!-- other child tag elements of the second object -->
            </second-object>
            <!-- additional objects -->
        <!-- closing tags for each parent of the object type -->
    </configuration>
</rpc-reply>

The junos:position and junos:total attributes do not appear if the client requests formatted ASCII output by including the format="text" attribute in the <get-configuration> tag element (as described in Requesting Output as Formatted ASCII Text or Junos XML Tag Elements).

To specify the source of the output (candidate or active configuration) and request special formatting of the output (for example, formatted ASCII text or an indicator for identifiers), the application can include attributes in the opening <get-configuration> tag, its opening <junoscript> tag, or both. For more information, see Specifying the Source and Output Format of Configuration Information.

The following example shows how to request the third and fourth Junos user accounts at the [edit system login] hierarchy level. The output is from the candidate configuration and is tagged with Junos XML tag elements (the default).

Requesting Identifiers Only

To request just the identifier tag element for configuration objects of a specified type in a hierarchy, a client application emits a <get-configuration> tag element that encloses the tag elements representing all levels of the configuration hierarchy from the root (represented by the <configuration> tag element) down to the immediate parent level for the object type. An empty tag represents the requested object type, and the recurse="false" attribute is included. The entire request is enclosed in an <rpc> tag element.

To request the identifier for all objects of a specified type, the client application includes only the recurse="false" attribute:

<rpc>
    <get-configuration>
        <configuration>
            <!-- opening tags for each parent of the object type -->
                <object-type  recurse="false"/> 
            <!-- closing tags for each parent of the object type -->
        </configuration>
    </get-configuration>
</rpc>

To request the identifier for a specified number of objects, the client application combines the recurse="false" attribute with the count and start attributes discussed in Requesting a Specified Number of Configuration Objects:

<rpc>
    <get-configuration>
        <configuration>
            <!-- opening tags for each parent of the object type -->
                <object-type  recurse="false" count="count" start="index"/> 
            <!-- closing tags for each parent of the object type -->
        </configuration>
    </get-configuration>
</rpc>

When the application requests Junos XML-tagged output (the default), the Junos XML protocol server returns the requested objects in <configuration> and <rpc-reply> tag elements. If the application has requested a specified number of objects, the junos:position and junos:total attributes are included in the opening tag for each object, as described in Requesting a Specified Number of Configuration Objects. In the following, the identifier tag element is called <name>. (For information about the attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration.)

<rpc-reply xmlns:junos="URL">
    <configuration attributes>
        <!-- opening tags for each parent of the object type -->
            <first-object [junos:position="index1" junos:total="total"]>
                <name>identifier-for-first-object</name>
            </first-object>
            <second-object [junos:position="index2" junos:total="total"]>
                <name>identifier-for-second-object</name>
            </second-object>
            <!-- additional instances of the object -->
        <!-- closing tags for each parent of the object type -->
    </configuration>
</rpc-reply>

To specify the source of the output (candidate or active configuration) and request special formatting of the output (for example, formatted ASCII text or an indicator for identifiers), the application can include attributes in the opening <get-configuration> tag, its opening <junoscript> tag, or both. For more information, see Specifying the Source and Output Format of Configuration Information.

The following example shows how to request the identifier for each interface configured at the [edit interfaces] hierarchy level. The output is from the candidate configuration and is tagged with Junos XML tag elements (the default).

Requesting One Configuration Object

To request information about a single configuration object, a client application emits the <get-configuration> tag element and encloses the tag elements that represent the entire statement path down to the object, starting with the <configuration> tag element. To represent the requested object, the application emits only the container tag element and identifier tag elements (each complete with the identifier value) for the object. It does not emit tag elements that represent other object characteristics. It encloses the entire request in an <rpc> tag element. In the following, the identifier tag element is called name:

<rpc>
    <get-configuration>
        <configuration>
            <!-- opening tags for each parent of the object -->
                <object>
                    <name>identifier</name> 
                </object>
            <!-- closing tags for each parent of the object -->
        </configuration>
    </get-configuration>
</rpc>

When the client application requests Junos XML-tagged output (the default), the Junos XML protocol server returns the requested object in <configuration> and <rpc-reply> tag elements. For information about the attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration.

<rpc-reply xmlns:junos="URL">
    <configuration attributes>
        <!-- opening tags for each parent of the object -->
            <object>
                <!-- child tag elements of the object -->
            </object>
        <!-- closing tags for each parent of the object -->
    </configuration>
</rpc-reply>

To specify the source of the output (candidate or active configuration) and request special formatting of the output (for example, formatted ASCII text or an indicator for identifiers), the application can include attributes in the opening <get-configuration> tag, its opening <junoscript> tag, or both. For more information, see Specifying the Source and Output Format of Configuration Information.

The following example shows how to request the contents of one multicasting scope called local, which is at the [edit routing-options multicast] hierarchy level. To specify the desired object, the client application emits the <name>local</name> identifier tag element as the innermost tag element. The output is from the candidate configuration and is tagged with Junos XML tag elements (the default).

Requesting a Subset of Objects by Using Regular Expressions

To request information about only those instances of a configuration object type that have a specified set of characters in their identifier names, a client application includes the matching attribute with a regular expression that matches the identifier name. For example, the application can request information about just the SONET/SDH interfaces at the [edit interfaces] hierarchy level by specifying the characters so- at the start of the regular expression.

Using the matching attribute enables the application to represent the objects to return in a form similar to the XML Path Language (XPath) representation, which is described in XML Path Language (XPath) Version 1.0, available from the World Wide Web Consortium (W3C) at http://www.w3.org/TR/xpath . In an XPath representation, an object and its parent levels are an ordered series of tag element names separated by forward slashes. The angle brackets around tag element names are omitted, and the opening tag is used to represent the entire tag element. For example, the following XPath:

configuration/system/radius-server/name

is equivalent to the following tagged representation:

<configuration>
    <system>
        <radius-server>
            <name/>
        </radius-server>
    </system>
</configuration>

The application includes the matching attribute in the empty tag that represents a parent level for the object type. As with all requests for configuration information, the client emits a <get-configuration> tag element that encloses the tag elements representing all levels of the configuration hierarchy from the root (represented by the <configuration> tag element) down to the level at which the matching attribute is included. The entire request is enclosed in an <rpc> tag element:

<rpc>
    <get-configuration>
        <configuration>
            <!-- opening tags for each parent of the level -->
                <level  matching="matching-expression"/> 
            <!-- closing tags for each parent of the level -->
        </configuration>
    </get-configuration>
</rpc>

In the value for the matching attribute, each level in the XPath-like representation can be either a full level name or a regular expression that matches the identifier name of one or more instances of an object type:

object-type[name='regular-expression']"

The regular expression uses the notation defined in POSIX Standard 1003.2 for extended (modern) UNIX regular expressions. Explaining regular expression syntax is beyond the scope of this document, but Table 7 specifies which character or characters are matched by some of the regular expression operators that can be used in the expression. In the descriptions, the term term refers to either a single alphanumeric character or a set of characters enclosed in square brackets, parentheses, or braces.

Note: The matching attribute is not case-sensitive.

Table 7: Regular Expression Operators for the matching Attribute

Operator	Matches
. (period)	One instance of any character except the space.
* (asterisk)	Zero or more instances of the immediately preceding term.
+ (plus sign)	One or more instances of the immediately preceding term.
? (question mark)	Zero or one instance of the immediately preceding term.
\| (pipe)	One of the terms that appear on either side of the pipe operator.
^ (caret)	The start of a line, when the caret appears outside square brackets. One instance of any character that does not follow it within square brackets, when the caret is the first character inside square brackets.
$ (dollar sign)	The end of a line.
[ ] (paired square brackets)	One instance of one of the enclosed alphanumeric characters. To indicate a range of characters, use a hyphen ( - ) to separate the beginning and ending characters of the range. For example, [a-z0-9] matches any letter or number.
( ) (paired parentheses)	One instance of the evaluated value of the enclosed term. Parentheses are used to indicate the order of evaluation in the regular expression.

When the application requests Junos XML-tagged output (the default), the Junos XML protocol server returns the requested object in <configuration> and <rpc-reply> tag elements. For information about the attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration.

<rpc-reply xmlns:junos="URL">
    <configuration attributes>
        <!-- opening tags for each parent of the parent level -->
            <parent-level>
                <first-matching-object>
                    <!-- child tag elements for the first object -->
                </first-matching-object>
                <second-matching-object>
                    <!-- child tag elements for the second object -->
                </second-matching-object>
                <!-- additional instances of the object -->
            </parent-level>
        <!-- closing tags for each parent of the object type -->
    </configuration>
</rpc-reply>

The application can combine one or more of the count, start, and recurse attributes along with the matching attribute, to limit the set of possible matches to a specific range of objects, to request only identifiers, or both. For more information about those attributes, see Requesting a Specified Number of Configuration Objects and Requesting Identifiers Only.

To specify the source of the output (candidate or active configuration) and request special formatting of the output (for example, formatted ASCII text or an indicator for identifiers), the application can include attributes in the opening <get-configuration> tag, its opening <junoscript> tag, or both. For more information, see Specifying the Source and Output Format of Configuration Information.

The application can request additional configuration elements of the same or other types in the same <get-configuration> tag element by including the appropriate tag elements. For more information, see Requesting Multiple Configuration Elements Simultaneously.

The following example shows how to request just the identifier for the first two SONET/SDH interfaces configured at the [edit interfaces] hierarchy level.

Requesting Multiple Configuration Elements Simultaneously

Within a <get-configuration> tag element, a client application can request multiple configuration elements of the same type or different types. The request includes only one <configuration> tag element (the Junos XML protocol server returns an error if there is more than one).

If two requested objects have the same parent hierarchy level, the client can either include both requests within one parent tag element, or repeat the parent tag element for each request. As an example, at the [edit system] hierarchy level the client can request the list of configured services and the identifier tag element for RADIUS servers in either of the following two ways:

<!-- both requests in one parent tag element -->
<rpc>
    <get-configuration>
        <configuration>
            <system>
                <services/>
                <radius-server>
                    <name/>
                </radius-server>
            </system>
        </configuration>
    </get-configuration>
</rpc>
    
<!-- separate parent tag element for each request -->
<rpc>
    <get-configuration>
        <configuration>
            <system>
                <services/>
            </system>
            <system>
                <radius-server>
                    <name/>
                </radius-server>
            </system>
        </configuration>
    </get-configuration>
</rpc>

The client can combine requests for any of the types of information discussed in the following sections: