Creating, Modifying, or Deleting Configuration Elements

In addition to replacing the entire configuration (as described in Replacing the Entire Configuration), a client application can create, modify, or delete one or more configuration elements (hierarchy levels and configuration objects) in the candidate configuration or a private copy.

To use Junos XML tag elements to represent an element, the application includes the tag elements representing all levels in the configuration hierarchy from the root (represented by the <configuration> tag element) down to the element’s container tag element. Which attributes and child tag elements are included depends on the operation being performed on the element. The syntax applies both to the contents of a file and to a data stream. In the following, the identifier tag element is called <name>:

<configuration>
    <!-- opening tag for each parent of the element -->
        <container-tag [operation-attribute="value"]> 
            <name>identifier</name> <!-- if the element has an identifier -->
            <!-- other child tag elements --> <!-- if appropriate for the operation -->
</container-tag> 
    <!-- closing tag for each parent of the element -->
</configuration>

To use formatted ASCII text to represent an element, the application includes the complete statement path, starting with a statement that can appear directly under the [edit] hierarchy level. The attributes and child statements to include depend on the operation being performed on the element. The set of statements is enclosed in a <configuration-text> tag element when the application provides a data stream. When saving statements to a file for later loading, omit the <configuration-text> tag element.

<configuration-text>
/* statements for parent levels of the element */
    operation-to-perform: # if appropriate
    element identifier   { # if the element has an identifier
        /* child statements */  # if appropriate for the operation
    } 
/* closing braces for parent levels for the element */
</configuration-text>

When loading formatted ASCII text, the application includes the format=”text" attribute in the <load-configuration/> tag or opening <load-configuration> tag.

For more information about the source and formatting for configuration elements, see Specifying the Source and Format of New Configuration Data.

For information about the operations a client application can perform on configuration elements, see the following sections:

Merging Configuration Elements

By default, the Junos XML protocol server merges loaded configuration data into the candidate configuration according to the following rules. (The rules also apply to a private copy of the configuration, but for simplicity the following discussion refers to the candidate configuration only.)

A configuration element (hierarchy level or configuration object) that exists in the candidate but not in the loaded configuration remains unchanged.
A configuration element that exists in the loaded configuration but not in the candidate is added to the candidate.
If a configuration element exists in both configurations, the semantics are as follows:
If a child statement of the configuration element (represented by a child tag element) exists in the candidate but not in the loaded configuration, it remains unchanged.
If a child statement exists in the loaded configuration but not in the candidate, it is added to the candidate.
If a child statement exists in both configurations, the value in the loaded configuration replaces the value in the candidate.

Merge mode is the default mode for new configuration elements, so the application simply emits the <load-configuration> tag element in an <rpc> tag element:

<rpc>
    <!-- For a file -->
        <load-configuration url="file" [format="text"]/>
    
<!-- For a data stream -->
    <load-configuration [format="text"]> 
        <!-- configuration data -->
    </load-configuration>
</rpc>

For more information about the url and format attributes, see Specifying the Source and Format of New Configuration Data.

To explicitly specify merge mode, the application can include the action="merge" attribute in the <load-configuration/> tag or opening <load-configuration> tag, as shown in the examples at the end of this section.

If using Junos XML tag elements to represent the element to merge into the configuration, the application includes the basic tag elements described in Creating, Modifying, or Deleting Configuration Elements. It does not include any attributes in the element’s container tag. If adding or changing the value of a child element, the application includes the tag elements for it. If a child remains unchanged, it does not need to be included in the loaded configuration. In the following, the identifier tag element is called <name>:

<configuration>
    <!-- opening tag for each parent of the element -->
        <container-tag> 
            <name>identifier</name> <!-- if the element has an identifier -->
            <!-- tag elements for other children, if any -->
        </container-tag> 
    <!-- closing tag for each parent of the element -->
</configuration>

If using formatted ASCII text, the application includes the statement path described in Creating, Modifying, or Deleting Configuration Elements. It does not include a preceding operator, but does include the element’s identifier if it has one. If adding or changing the value of a child element, the application includes the tag elements for it. If a child remains unchanged, it does not need to be included in the loaded configuration.

<configuration-text>
/* statements for parent levels of the element */
    element identifier  {
          /* child statements if any */
    } 
/* closing braces for parent levels for the element */
</configuration-text>

The following example shows how to merge in a new interface called so-3/0/0 at the [edit interfaces] hierarchy level in the candidate configuration. The information is provided as Junos XML tag elements (the default).

The following example shows how to use formatted ASCII text to define the same new interface.
Replacing Configuration Elements
To replace individual configuration elements (hierarchy levels or configuration objects), a client application emits the <load-configuration> tag element with the action="replace" attribute in an <rpc> tag element:
<rpc>

<load-configuration action="replace" url="file" [format="text"]/>


<load-configuration action="replace" [format="text"]>

</load-configuration>
</rpc>
For more information about the url and format attributes, see Providing Configuration Data in a File.
To use Junos XML tag elements to represent the replacement, the application includes the basic tag elements described in Creating, Modifying, or Deleting Configuration Elements. Within the container tag, it includes the same child tag elements as for a new element: each of the replacement’s identifier tag elements (if it has them) and all child tag elements being defined for the replacement element. In the following, the identifier tag element is called <name>. The application also includes the replace= “replace” attribute in the opening container tag:
<configuration>

<container-tag replace="replace">
<name>identifier</name>

</container-tag>

</configuration>
To use formatted ASCII text to represent the element, the application includes the complete statement path described in Creating, Modifying, or Deleting Configuration Elements. As for a new element, it includes each of the replacement’s identifiers (if it has them) and all child statements (with values if appropriate) that it is defining for the replacement. It places the replace: statement above the element’s container statement.
<configuration-text>
/* statements for parent levels of the element */
replace:
element identifier {
/* child statements if any */
}
/* closing braces for parent levels for the element */
</configuration-text>
The following example shows how to grant new permissions for the object named operator at the [edit system login class] hierarchy level. The information is provided in Junos XML-tagged format (the default).
The following example shows how to use formatted ASCII text to make the same change.
Creating New Configuration Elements
To create new configuration elements (hierarchy levels or configuration objects), a client application includes the basic tag elements or formatted ASCII statements described in Creating, Modifying, or Deleting Configuration Elements.
New elements can be created in either merge mode or replace mode, which are described in Merging Configuration Elements and Replacing Configuration Elements. In replace mode, the application includes the action="replace" attribute in the <load-configuration/> tag or opening <load-configuration> tag.
To use Junos XML tag elements to represent the element, the application includes each of the replacement’s identifier tag elements (if it has them) and all child tag elements being defined for the element. In the following, the identifier tag element is called <name>. The application does not need to include any attributes in the opening container tag for the new element:
<configuration>

<container-tag>
<name>identifier</name>

</container-tag>

</configuration>
To use formatted ASCII text to represent the element, the application includes each of the replacement’s identifiers (if it has them) and all child statements (with values if appropriate) that it is defining for the element. It does not need to include an operator before the new element:
<configuration-text>
/* statements for parent levels of the element */
element identifier {
/* child statements if any */
}
/* closing braces for parent levels for the element */
</configuration-text>
Replacing Configuration Elements Only If They Have Changed
To replace configuration elements (hierarchy levels and configuration objects) only if they differ in the loaded configuration and the candidate configuration or private copy, the application emits the <load-configuration> tag element with the action="update" attribute in an <rpc> tag element:
<rpc>

<load-configuration action="update" url="file" [format="text"]/>


<load-configuration action="update" [format="text"]>

</load-configuration>
</rpc>
For more information about the url and format attributes, see Specifying the Source and Format of New Configuration Data.
This operation is equivalent to the Junos OS CLI load update configuration mode command. The Junos configuration management software compares the two configurations. Each configuration element that is different in the loaded configuration replaces its corresponding element in the existing configuration. Elements that are the same in both configurations, or exist only in the existing configuration, remain unchanged. When the configuration is later committed, only system processes that are affected by the changed configuration elements parse the new configuration.
To represent the replacement elements, the application uses the same syntax as for new elements, as described in Creating New Configuration Elements. In the following, the identifier tag element is called <name>:
<configuration>

<container-tag>
<name>identifier</name>

</container-tag>

</configuration>

OR

<configuration-text>
/* statements for parent levels of the element */
element identifier {
/* child statements if any */
}
/* closing braces for parent levels for the element */
</configuration-text>
The following example shows how to update the candidate configuration with the contents of the file /tmp/new.conf (which resides on the device). The file contains a complete configuration represented as Junos XML tag elements (the default), so the format attribute is omitted.
Deleting Configuration Elements
To delete configuration elements (hierarchy levels or configuration objects) from the candidate configuration or private copy, a client application emits the basic tag elements described in Creating, Modifying, or Deleting Configuration Elements. When using Junos XML tag elements to represent the elements to delete, it includes the delete="delete" attribute in the opening tag for each one. When using formatted ASCII text, it precedes each element with the delete: operator. The placement of the attribute or operator depends on the type of element being deleted, as described in the following sections:
Deleting a Hierarchy Level or Container Object
Deleting a Configuration Object That Has an Identifier
Deleting a Single-Value or Fixed-Form Option from a Configuration Object
Deleting Values from a Multivalue Option of a Configuration Object
Deleting a Hierarchy Level or Container Object
To delete a hierarchy level and all of its children (or a container object that has children but no identifier), a client application includes the basic tag elements or configuration statements for its parent levels, as described in Creating, Modifying, or Deleting Configuration Elements.
If using Junos XML tag elements, the application includes the delete="delete" attribute in the empty tag that represents the level or container object:
<configuration>

<level-or-object delete="delete"/>

</configuration>
If using formatted ASCII text, the application places the delete: statement above the level to be removed, which is followed by a semicolon (even though in the existing configuration it is followed by curly braces that enclose its child statements):
<configuration-text>
/* statements for parent levels */
delete:
object-or-level;
/* closing braces for parent levels */
</configuration-text>
The following example shows how to remove the [edit protocols ospf] hierarchy level from the candidate configuration:
Deleting a Configuration Object That Has an Identifier
To delete a configuration object that has an identifier, a client application includes the basic tag elements or configuration statements for its parent levels, as described in Creating, Modifying, or Deleting Configuration Elements.
If using Junos XML tag elements, the application includes the delete="delete" attribute in the opening tag for the object. In the container tag element for the object, it encloses only the identifier tag element, not tag elements that represent any other characteristics of the object. In the following, the identifier tag element is called <name>:
<configuration>

<object delete="delete">
<name>identifier</name>
</object>

</configuration>
Note: The delete attribute appears in the opening container tag, not in the identifier tag element. The presence of the identifier tag element results in the removal of the specified object, not in the removal of the entire hierarchy level represented by the container tag element.
If using formatted ASCII text, the application places the delete: statement above the object and its identifier:
<configuration-text>
/* statements for parent levels of the object */
delete:
object identifier;
/* closing braces for parent levels of the object */
</configuration-text>
The following example shows how to remove the user object barbara from the [edit system login user] hierarchy level in the candidate configuration.
Deleting a Single-Value or Fixed-Form Option from a Configuration Object
To delete from a configuration object either a fixed-form option or an option that takes just one value, a client application includes the basic tag elements or configuration statements for its parent levels, as described in Creating, Modifying, or Deleting Configuration Elements. (For information about deleting an option that can take multiple values, see Deleting Values from a Multivalue Option of a Configuration Object.)
If using Junos XML tag elements, the application includes the delete="delete" attribute in the empty tag for each option. It does not include tag elements for children that are to remain in the configuration. In the following, the identifier tag element for the object is called <name>:
<configuration>

<object>
<name>identifier</name> 
<option1 delete="delete"/>
<option2 delete="delete"/>

</object>

</configuration>
If using formatted ASCII text, the application places the delete: statement above each option:
<configuration-text>
/* statements for parent levels of the object */
object identifier;
delete:
option1;
delete:
option2;
/* closing braces for parent levels of the object */
</configuration-text>
The following example shows how to remove the fixed-form disable option at the [edit forwarding-options sampling] hierarchy level.
Deleting Values from a Multivalue Option of a Configuration Object
As described in Mapping for Leaf Statements with Multiple Values, some Junos configuration objects are leaf statements that have multiple values. In the formatted ASCII CLI representation, the values are enclosed in square brackets following the name of the object:
object [value1 value2 value3 ...];
The Junos XML representation does not use a parent tag for the object, but instead uses a separate instance of the object tag element for each value. In the following, the identifier tag element is called <name>:
<parent-object>
<name>identifier</name>
<object>value1</object>
<object>value2</object>
<object>value3</object>
</parent-object>
To remove one or more values for such an object, a client application includes the basic tag elements or configuration statements for its parent levels, as described in Creating, Modifying, or Deleting Configuration Elements. If using Junos XML tag elements, the application includes the delete="delete" attribute in the opening tag for each value. It does not include tag elements that represent values to be retained. In the following, the identifier tag element for the parent object is called <name>:
<configuration>

<parent-object>
<name>identifier</name>
<object delete="delete">value1</object>
<object delete="delete">value2</object>
</parent-object>

</configuration>
If using formatted ASCII text, the application repeats the parent statement for each value and places the delete: statement above each paired statement and value:
<configuration-text>
/* statements for parent levels of the parent object */
parent-object identifier;
delete:
object value1;
delete:
object value2;
/* closing braces for parent levels of the parent object */
</configuration-text>
The following example shows how to remove two of the permissions granted to the user-accounts login class.