Specifying the Source and Output Format of Configuration Information

By including optional attributes when requesting configuration information, a client application can specify the source and formatting of the output returned by the Junos XML protocol server, as described in the following sections:

Requesting Information from the Committed or Candidate Configuration

To request information from the candidate configuration, the application either includes the database="candidate" attribute or omits the attribute completely (information from the candidate configuration is the default):

<rpc>
    <get-configuration/>
    
<!-- OR -->
    
    <get-configuration>
        <!-- tag elements for the configuration elements to return -->
    </get-configuration> 
</rpc>

To request information from the active configuration—the one most recently committed on the device—a client application includes the database="committed" attribute in the <get-configuration/> tag or opening <get-configuration> tag:

<rpc>
    <get-configuration database="committed"/> 
    
<!-- OR -->
    
    <get-configuration database="committed"> 
        <!-- tag elements for the configuration elements to return -->
    </get-configuration>
</rpc>

For information about the tag elements to enclose in the <get-configuration> tag element, see Specifying the Scope of Configuration Information to Return.

The Junos XML protocol server encloses its response in the <rpc-reply> tag element and either the <configuration> tag element (for Junos XML-tagged output) or <configuration-text> tag element (for formatted ASCII output).

When returning information from the candidate configuration as Junos XML tag elements, the Junos XML protocol server includes attributes in the opening <configuration> tag that indicate when the configuration last changed (they appear on multiple lines here only for legibility):

<rpc-reply xmlns:junos="URL"><configuration junos:changed-seconds="seconds" \junos:changed-localtime="YYYY-MM-DD hh:mm:ss TZ"></configuration></rpc-reply>

junos:changed-localtime represents the time of the last change as the date and time in the device’s local time zone.

junos:changed-seconds represents the time of the last change as the number of seconds since midnight on 1 January 1970.

When returning information from the active configuration as Junos XML tag elements, the Junos XML protocol server includes attributes in the opening <configuration> tag that indicate when the configuration was committed (they appear on multiple lines here only for legibility):

<rpc-reply xmlns:junos="URL"><configuration junos:commit-seconds="seconds" \junos:commit-localtime="YYYY-MM-DD hh:mm:ss TZ" \junos:commit-user="username"></configuration></rpc-reply>

junos:commit-localtime represents the commit time as the date and time in the device’s local time zone.

junos:commit-seconds represents the commit time as the number of seconds since midnight on 1 January 1970.

junos:commit-user specifies the Junos OS username of the user who requested the commit operation.

The database attribute in the application’s request can be combined with one or more of the following attributes in the <get-configuration/> tag or opening <get-configuration> tag:

changed, which is described in Requesting a Change Indicator for Configuration Elements
format, which is described in Requesting Output as Formatted ASCII Text or Junos XML Tag Elements
inherit and optionally groups, which are described in Specifying the Output Format for Configuration Groups

The application can also include the database attribute after requesting an indicator for identifiers (as described in Requesting an Indicator for Identifiers).

The following example shows how to request the entire committed configuration. 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 Output as Formatted ASCII Text or Junos XML Tag Elements

To request that the Junos XML protocol server return configuration information in Junos XML-tagged output, the client application either includes the format="xml" attribute in the <get-configuration/> tag or opening <get-configuration> tag or omits the attribute completely. The Junos XML protocol server returns Junos XML-tagged output by default.

<rpc>
        <get-configuration/> 
    
    <!-- OR -->
    
        <get-configuration> 
            <!-- tag elements for the configuration elements to return -->
        </get-configuration> 
</rpc>

To request that the Junos XML protocol server return configuration information as formatted ASCII text instead of tagging it with Junos XML tag elements, the client application includes the format="text" attribute in the <get-configuration/> tag or opening <get-configuration> tag. It encloses the request in an <rpc> tag element:

<rpc>
        <get-configuration format="text"/>
    
    <!-- OR -->
    
        <get-configuration format="text">
            <!-- tag elements for the configuration elements to return -->
        </get-configuration>
</rpc>

For information about the tag elements to enclose in the <get-configuration> tag element, see Specifying the Scope of Configuration Information to Return.

Note: Regardless of which output format they request, client applications use Junos XML tag elements to represent the configuration element to display. The format attribute controls the format of the Junos XML protocol server’s output only.

When the application requests Junos XML tag elements, the Junos XML protocol server encloses its output in <rpc-reply> and <configuration> 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 representing configuration elements -->
    </configuration>
</rpc-reply>

When the application requests formatted ASCII output, the Junos XML protocol server formats its response in the same way that the CLI show configuration command displays configuration data—it uses the newline character, tabs, braces, and square brackets to indicate the hierarchical relationships between configuration statements. The server encloses formatted ASCII configuration statements in <rpc-reply> and <configuration-text> tag elements:

<rpc-reply xmlns:junos="URL"><configuration-text></configuration-text></rpc-reply>

The format attribute can be combined with one or more of the following other attributes in the <get-configuration/> tag or opening <get-configuration> tag:

database, which is described in Requesting Information from the Committed or Candidate Configuration
inherit and optionally groups, which are described in Specifying the Output Format for Configuration Groups

It does not make sense to combine the format="text" attribute with the changed attribute (described in Requesting a Change Indicator for Configuration Elements) or to include it after requesting an indicator for identifiers (described in Requesting an Indicator for Identifiers). The change and identifier indicators appear only in Junos XML-tagged output, which is the default output format.

An application can request Junos-XML tagged output or formatted ASCII text for the entire configuration or any portion of it. For instructions on specifying the amount of data to return, see Specifying the Scope of Configuration Information to Return.

The following example shows how to request formatted ASCII output from the [edit policy-options] hierarchy level in the candidate configuration.

Requesting a Change Indicator for Configuration Elements

To request that the Junos XML protocol server indicate which configuration elements have changed since the last commit, a client application includes the changed="changed" attribute in the <get-configuration/> tag or opening <get-configuration> tag. It encloses the request in an <rpc> tag element:

<rpc>
        <get-configuration changed="changed"/>
    
    <!-- OR -->
    
        <get-configuration changed="changed">
            <!-- tag elements for the configuration elements to return -->
        </get-configuration>
</rpc>

For information about the tag elements to enclose in the <get-configuration> tag element, see Specifying the Scope of Configuration Information to Return.

The Junos XML protocol server indicates which elements have changed by including the junos:changed="changed" attribute in the opening tag of every parent tag element in the path to the changed configuration element. If the changed configuration element is represented by a single (empty) tag, the junos:changed="changed" attribute appears in the tag. If the changed element is represented by a container tag element, the junos:changed="changed" attribute appears in the opening container tag and also in the opening tag for each child tag element enclosed in the container tag element.

The Junos XML protocol server encloses its response in <rpc-reply> and <configuration> tag elements. For information about the standard attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration.

<rpc-reply xmlns:junos="URL">
        <configuration standard-attributes junos:changed="changed">
            <!-- opening-tag-for-each-parent-level junos:changed="changed" -->
    
    <!-- For each changed element, EITHER -->
        <element junos:changed="changed"/>
    
    <!-- OR -->
    
        <element junos:changed="changed">
            <first-child-of-element junos:changed="changed">
            <second-child-of-element junos:changed="changed">
            <!-- additional children of element -->
        </element>
    
        <!-- closing-tag-for-each-parent-level -->
    </configuration>
</rpc-reply>

Note: When a commit operation succeeds, the Junos XML protocol server removes the junos:changed="changed" attribute from all tag elements. However, if warnings are generated during the commit, the attribute is not removed. In this case, the junos:changed="changed" attribute appears on tag elements that changed before the commit as well as those that changed after the commit.

An example of a commit-time warning is the message explaining that a configuration element will not actually apply until the device is rebooted. The warning appears in the tag string that the Junos XML protocol server returns to confirm the success of the commit, enclosed in an <xnm:warning> tag element.

To remove the junos:changed="changed" attribute from elements that changed before the commit, the client application must take any action necessary to eliminate the cause of the warning, and commit the configuration again.

The changed attribute can be combined with one or more of the following other attributes in the <get-configuration/> tag or opening <get-configuration> tag:

database, which is described in Requesting Information from the Committed or Candidate Configuration. Request change indicators in either the candidate or active configuration:
- When the database="candidate" attribute is included or the database attribute is omitted, the output is from the candidate configuration. Elements added to the candidate configuration after the last commit operation are marked with the junos:changed="changed" attribute.
- When the database="committed" attribute is included, the output is from the active configuration. Elements added to the active configuration by the most recent commit are marked with the junos:changed="changed" attribute.
inherit and optionally groups, which are described in Specifying the Output Format for Configuration Groups.

It does not make sense to combine the changed attribute with the format="text" attribute. The junos:changed="changed" attribute appears only in Junos XML-tagged output, which is the default output format.

The application can also include the changed attribute after requesting an indicator for identifiers (as described in Requesting an Indicator for Identifiers).

The following example shows how to request change indicators for configuration elements at the [edit system syslog] hierarchy level in the candidate configuration. The output indicates that a log file called interactive-commands has been configured since the last commit.

Requesting an Indicator for Identifiers

To request that the Junos XML protocol server indicate whether a child configuration element is an identifier for its parent element, a client application includes the junos:key="key" attribute in the opening <junoscript> tag for the Junos XML protocol session, which appears here on two lines for legibility only:

<junoscript version="version" hostname="hostname" junos:key="key" 
                        release="release-code">

For more information about the <junoscript> tag, see Emitting the Opening <junoscript> Tag.

When the identifier indicator is requested, the Junos XML protocol server includes the junos:key="key" attribute in the opening tag for each identifier. As always, the Junos XML protocol server encloses its response in <rpc-reply> and <configuration> tag elements. For information about the attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration. In the following, the identifier tag element is called <name>:

<rpc-reply xmlns:junos="URL">
        <configuration attributes>
            <!-- opening tag for each parent of the object -->
    
    <!-- For each configuration object with an identifier -->
            <object>
                <name junos:key="key">identifier</name>
                <!-- additional children of object -->
                </object>
            <!-- closing tag for each parent of the object -->
    
    </configuration>
</rpc-reply>

The client application can include one or more of the following other attributes in the <get-configuration/> tag or opening <get-configuration> tag when the junos:key attribute is included in the opening <junoscript> tag:

changed, which is described in Requesting a Change Indicator for Configuration Elements
database, which is described in Requesting Information from the Committed or Candidate Configuration
inherit and optionally groups, which are described in Specifying the Output Format for Configuration Groups

When requesting an indicator for identifiers, it does not make sense to include the format="text" attribute in the <get-configuration> tag element (as described in Requesting Output as Formatted ASCII Text or Junos XML Tag Elements). The junos:key="key" attribute appears only in Junos XML-tagged output, which is the default output format.

The following example shows how indicators for identifiers appear on configuration elements at the [edit interfaces] hierarchy level in the candidate configuration when the junos:key="key" attribute is included in the opening <junoscript> tag emitted by the client application for the session. The two opening <junoscript> tags appear on multiple lines for legibility only. Neither client applications nor the Junos XML protocol server insert newline characters within tags. Also, for brevity the output includes just one interface, the loopback interface lo0.

Specifying the Output Format for Configuration Groups

The <groups> tag element corresponds to the [edit groups] configuration hierarchy. It encloses tag elements representing configuration groups, each of which contains a set of configuration statements that are appropriate at multiple locations in the hierarchy. Use the apply-groups configuration statement or <apply-groups> tag element to insert a configuration group at the appropriate location, achieving the same effect as directly inserting the statements defined in the group. The section of configuration hierarchy to which a configuration group is applied is said to inherit the group’s statements.

In addition to the groups defined at the [edit groups] hierarchy level, the Junos OS predefines a group called junos-defaults. This group includes configuration statements judged appropriate for basic operations on any routing, switching, or security platform. By default, the statements in this group do not appear in the output of CLI commands that display the configuration, nor in the output returned by the Junos XML protocol server for the <get-configuration> tag element. For more information about user-defined configuration groups and the junos-defaults group, see the Junos CLI User Guide.

The following sections explain how to specify the output format for configuration elements that are defined in configuration groups:

Specifying Whether Configuration Groups Are Displayed Separately

By default, the Junos XML protocol server displays the tag element for each user-defined configuration group as a child of the <groups> tag element, instead of displaying them as children of the elements to which they are applied. This display mode parallels the default behavior of the CLI configuration mode show command, which displays the [edit groups] hierarchy as a separate hierarchy in the configuration.

To request that the Junos XML protocol server not display the <groups> or <apply-groups> tag elements separately, but instead enclose tag elements inherited from user-defined groups within the inheriting tag elements, a client application includes the inherit="inherit" attribute in the <get-configuration/> tag or opening <get-configuration> tag. It encloses the request in an <rpc> tag element:

To request that the Junos XML protocol server include tag elements that are inherited from the junos-defaults group as well as user-defined configuration groups, the client application includes the inherit="defaults" attribute in the <get-configuration/> tag or opening <get-configuration> tag:

For information about the tag elements to enclose in the <get-configuration> tag element, see Specifying the Scope of Configuration Information to Return.

When the client includes the inherit="inherit" attribute, the output includes the same information as the output from the following CLI configuration mode command, and does not include configuration elements inherited from the junos-defaults group:

user@host# show | display inheritance | except ##

When the client includes the inherit="defaults" attribute, the output includes the same information as the output from the following CLI configuration mode command:

user@host# show | display inheritance defaults | except ##

In both cases, the Junos XML protocol server encloses its output in the <rpc-reply> tag element and either the <configuration> tag element (for Junos XML-tagged output) or <configuration-text> tag element (for formatted ASCII output). For information about the attributes in the opening <configuration> tag, see Requesting Information from the Committed or Candidate Configuration.

<rpc-reply xmlns:junos="URL">
    <!-- EITHER -->
        <configuration attributes>
            <!-- Junos XML tag elements representing configuration elements -->
        </configuration>
    
    <!-- OR -->
    
        <configuration-text>
            <!-- formatted ASCII configuration statements -->
        </configuration-text>
</rpc-reply>

The inherit attribute can be combined with one or more of the following attributes in the <get-configuration/> tag or opening <get-configuration> tag:

changed, which is described in Requesting a Change Indicator for Configuration Elements
database, which is described in Requesting Information from the Committed or Candidate Configuration
format, which is described in Requesting Output as Formatted ASCII Text or Junos XML Tag Elements
groups, which is described in Displaying the Source Group for Inherited Configuration Elements

The application can also include the inherit attribute after requesting an indicator for identifiers (as described in Requesting an Indicator for Identifiers).

Displaying the Source Group for Inherited Configuration Elements

To request that the Junos XML protocol server indicate the configuration group from which configuration elements are inherited, a client application combines the groups="groups" attribute with the inherit attribute in the <get-configuration/> tag or opening <get-configuration> tag. It encloses the request in an <rpc> tag element:

<rpc>
        <get-configuration inherit="(defaults | inherit)" groups="groups"/>
    
    <!-- OR -->
    
        <get-configuration inherit="(defaults | inherit)" groups="groups">
            <!-- tag elements for the configuration elements to return -->
        </get-configuration>
</rpc>

For information about the tag elements to enclose in the <get-configuration> tag element, see Specifying the Scope of Configuration Information to Return.

When the groups="groups" attribute is combined with the inherit="inherit" attribute, the output includes the same information as the output from the following CLI configuration mode command, and does not include configuration elements inherited from the junos-defaults group:

user@host# show | display inheritance

When the groups="groups" attribute is combined with the inherit="defaults" attribute, the output includes the same information as the output from the following CLI configuration mode command:

user@host# show | display inheritance defaults

The inherit and groups attributes can be combined with one or more of the following other attributes in the <get-configuration/> tag or opening <get-configuration> tag:

changed, which is described in Requesting a Change Indicator for Configuration Elements.
database, which is described in Requesting Information from the Committed or Candidate Configuration.

format, which is described in Requesting Output as Formatted ASCII Text or Junos XML Tag Elements. The application can request either Junos XML-tagged or formatted ASCII output:

If the output is tagged with Junos XML tag elements (the format="xml" attribute is included or the format attribute is omitted), the Junos XML protocol server includes the junos:group="source-group" attribute in the opening tags of configuration elements that are inherited from configuration groups and encloses its response 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>
    <!-- For each inherited element -->
        <!-- opening-tags-for-parents-of-the-element -->
            <inherited-element junos:group="source-group">
                <inherited-child-of-inherited-element junos:group="source-group">
                    <!-- inherited-children-of-child junos:group="source-group" -->
                </inherited-child-of-inherited-element>
            </inherited-element>
        <!-- closing-tags-for-parents-of-the-element -->
    </configuration>
</rpc-reply>

If the output is formatted ASCII text (the format="text" attribute is included), the Junos XML protocol server encloses its response in <configuration-text> and <rpc-reply> tag elements, and inserts three commented lines immediately above each inherited element, as in the following:

<rpc-reply xmlns:junos="URL">
    <configuration-text>
*/ For each inherited element */
        /* parent levels for the element */
            ##
            ## 'inherited-element' was inherited from group 'source-group'
            ##
            inherited-element {
                ##
                ## 'inherited-child' was inherited from group 'source-group'
                ##
                inherited-child {
                    ... child statements of inherited-child ...
                }
            }
        /* closing braces for parent levels for the element */
    </configuration-text>
</rpc-reply>

The application can also include the inherit and groups attributes after requesting an indicator for identifiers (as described in Requesting an Indicator for Identifiers).

Examples: Specifying Output Format for Configuration Groups

The following sample configuration hierarchy defines a configuration group called interface-group. The apply-groups statement applies the statements in the group at the [edit interfaces] hierarchy level:

[edit]groups {interface-group {interfaces {so-1/1/1 {encapsulation ppp;}}}}apply-groups interface-group;interfaces {fxp0 {unit 0 {family inet {address 192.168.4.207/24;}}}}

When the inherit attribute is not included in the <get-configuration/> tag, the output includes the <groups> and <apply-groups> tag elements as separate items. The <groups> tag element encloses the tag elements defined in the interface-group configuration group. The placement of the <apply-groups> tag element directly above the <interfaces> tag element indicates that the [edit interfaces] hierarchy inherits the statements defined in the interface-group configuration group.

When the inherit attribute is included in the <get-configuration/> tag, the <interfaces> tag element encloses the tag elements defined in the interface-group configuration group. The <groups> and <apply-groups> tag elements are not displayed.

When the groups="groups" attribute is combined with the inherit attribute in the <get-configuration/> tag, the <interfaces> tag element encloses the tag elements defined in the interface-group configuration group, which are marked with the junos:group="interface-group" attribute.