.. _edit_config_rpc:
 
Editing Configuration (NETCONF)
===============================
Using NETCONFc, editing data from the connected server is also very convenient.

Lock datastore for editing
---------------------------

    It is recommended you lock the running and candidate datastore before editing anything.
    You can easily lock the involved datastore by clicking the correspondent lock button
    for each config datastore.

    .. image:: images/lock_datastore.*

Partial-lock data nodes for editing
-------------------------------------

    To allow other managers to edit server's configuration store simultaneously you can use <partial-lock> to lock only the subtrees you want to edit.
    To issue ``partially-lock`` , first use <get-config> to retrieve some data, then in the data tree on the right panel, select one or more rows, 
    right click and select ``Partial lock``

    .. image:: images/partial_lock.*

    .. note::     
        Partial-lock is only effective when the target datastore is ``running``.

    .. note::     
        After a successful ``partial-lock``, you can right-click to issue ``partial-unlock`` to unlock the locked subtrees.
    
Basic <edit-config> operations
-------------------------------

    Either from ``schema tree`` on the left side or ``data tree`` on the right,
    you can send <edit-config>. See :ref:`basic_edit_yang_tree` and 
    :ref:`basic_edit_instance_tree` for more information.

    From ``data tree`` on the right, you can edit nodes in different list entries or different list.


    Use shortcut key ``<Ctrl + S>`` to send <edit-config>.


.. _edit_config_rpc_multiple_list_leaflist:

Create multiple list or leaf-list instance entries in a single request
----------------------------------------------------------------------------
    You can create or edit multiple list instance entries from YANG data schema tree. 
    
    The following is an example that shows how to create two list instance entries in a single RPC.
    
    First, enter value 'rule1' and 'group1' as shown, then right click and select 
    ``Add to build <edit-config> data``.
    
    .. image:: images/edit_multiple_list_entry1.*

    You should see an edit-config RPC was generated in the ``Send Request and Show Reply`` window
    at the right side of the screen.
	
    Then, enter value 'rule2' and 'group2' as shown, then right click and again and select 
    ``Add to build <edit-config> data``.
    
    .. image:: images/edit_multiple_list_entry2.*
    
    You should see new value entries are added to the previous edit-config RPC generated. 
    If you want to make any changes you can edit it here.
    
    Finally click the button ``Click to Send RPC with above XML`` at the bottom of
    ``Send Request and Show Reply`` window pane to send the edit-config message 
    to the remote server.
    
    To clear <edit-config> you have built, select "Reset all values" context menu or hit <Ctrl + Q>.
    
Deal with list key nodes
--------------------------

    When issuing <edit-config> on a list, list keys must be included and placed before all other non-key nodes.
    NETCONFc handles this ciritical step for you automatically.

    When sending <edit-config>  from ``schema tree``,  all key nodes must be given an appropriate value. 

    .. note::     
        If a list is a nested list, the parent list's key nodes must also be specified.

    When sending <edit-config>  from ``data tree``,  all key nodes will use their current respective value, 
    unless otherwise changed.
        


How to create a presence container node
------------------------------------------------------------

    If a presence container contains any child node that is part of the ``edit-config`` then the server should create
    it automatically. Otherwise a presence container need to be created explicitly.

    For example, in toaster yang module (http://www.netconfcentral.org/modulereport/toaster), the node /toaster/toaster is a presence container
    that has no child nodes. If this is the case, you should see a special ``Create this presence container`` menu in the right-click context 
    menu. Just select it an <edit-config> will be sent to create this node.

    .. image:: images/create_presence_container.*

    Alternatively you can also right click to select ``Assign empty value`` to include in RPC, and then select 
    ``Send edit-config`` to send the command. 


Delete a node from *data tree*
--------------------------------------
    
    It is really easy to ``Delete`` a node from the data tree. Just select it,
    right-click and choose ``Delete``.

    .. image:: images/delete_instance_node.*
   
    
Reorder ordered-by-user list of leaf-lists
---------------------------------------------
    
    In the ``schema tree`` and ``data tree`` you can also rearrange the order of list and leaf-list that
    are defined as ``ordered-by-user``. 
    
    Select a list of leaf-list that is ordered by user, right click to select ``set <edit-config> options | Reorder options | ...``
    
    .. image:: images/reorder_node.*
     
    If you select ``insert before`` or ``insert after`` reorder options, a dialog will pop up and asks you to select a target
    entry before or after which you want to move the selected node to.
   
    .. image:: images/reorder_target_selection.*
    
    You will then notice the node name is tagged with options you selected. Now you simply right lick and select ``edit-config`` 
    to send it!

    .. image:: images/edit_config_instance_tree.*
    

Edit-config operation attributes
----------------------------------

    For any config node, you can assign an ``operation`` attribute. If it is not assigned explicitly, it will use the setting in
    its parent nodes. If no parent node has this attribute set, then the setting in ``default-operation`` option  will be used.

    If you select any ``operation``, then the selected node will be tagged with your selection. 

    If you select any ``default operation``, the selected node will not be tagged with the selection since it a general setting.

    If you want to remove a selected option, select ``do not user/clear``.

    .. image:: images/edit_config_option.*


    The ``operation`` attribute has one of the following values:

         ``merge``:  The configuration data identified by the element containing this attribute is merged with the configuration at the corresponding level in the
         configuration datastore identified by the <target> parameter.  This is the default behavior.

         ``replace``:  The configuration data identified by the element containing this attribute replaces any related configuration in the configuration datastore 
         identified by the <target> parameter.  If no such configuration data exists in the configuration datastore, it is created.  Unlike a <copy-config> 
         operation, which replaces the entire target configuration, only the configuration actually present in the <config> parameter is affected.

         ``create``:  The configuration data identified by the element containing this attribute is added to the configuration if and only if the configuration data
         does not already exist in the configuration datastore.  If the configuration data exists, an <rpc-error> element is returned.

         ``delete``:  The configuration data identified by the element containing this attribute is deleted from the configuration if and only if the configuration 
         data currently exists in the configuration datastore.  If the configuration data does not exist, an <rpc-error> element is returned.

         ``remove``:  The configuration data identified by the element containing this attribute is deleted from the configuration if the configuration data currently
         exists in the configuration datastore.  If the configuration data does not exist, the "remove" operation is silently ignored by the server.        

         
    The ``default-operation`` option parameter has one of the following values:
        
        ``merge``:  The configuration data is merged with the configuration at the corresponding level in the target datastore.  This is the default behavior.

        ``replace``:  The configuration data completely replaces the configuration in the target datastore.  This is useful for loading previously saved configuration data.

        ``none``:  The target datastore is unaffected by the configuration data, unless and until the incoming configuration data uses the "operation" attribute to
        request a different operation.  If the configuration data contains data for which there is not a corresponding level in the target datastore, an <rpc-error>
        is returned. Using "none" allows operations like "delete" to avoid unintentionally creating the parent hierarchy of the element to be deleted.
    
 
Edit-config with XML config data or URL 
------------------------------------------------------------

    Sometimes you may want to edit a datastore with manually built XML data, 
    or a resource pointed at by an URL, NETCONFc also allows you to do that.

    First select a ``config datastore`` by enabling the corresponding radio button,
    click the dropdown arrow button and select ``edit-config with inline data or URL``.

    .. image:: images/edit_with_xml_url.*

    The data to edit can be specfied either in a file given by its url or inline config data. 
            
    When using a config file, simply select "use a config file (url)" and specify an url value 
    in the "Config url" field.

    When using inline config data, select "use inline config data" and specify config data
    in the "Config Data" filed. 

    In either case, the config data must be a well formed XML <config> string. For example:
    ::
    <config>
    <top xmlns="http://example.com/schema/1.2/config">
    <interface>
    <name>Ethernet0/0</name>
    <mtu>1500</mtu>
    </interface>
    </top>
    </config>
      


Additional edit-config  options
--------------------------------

    You can assign the following additional options to <edit-config> by right-clicking and select "edit-config options | test-option or error-option".

    The <test-option> element is available only if the device advertises the :validate:1.1 capability.
    The <test-option> element has one of the following values:

         ``test-then-set``:  Perform a validation test before attempting to
         set.  If validation errors occur, do not perform the
         <edit-config> operation.  This is the default test-option.

         ``set``:  Perform a set without a validation test first.

         ``test-only``:  Perform only the validation test, without attempting to set.
                
    The <error-option> has one of the following values:

        ``stop (stop-on-error)``:  Abort the <edit-config> operation on first
        error.  This is the default error-option.

        ``continue (continue-on-error)``:  Continue to process configuration data on
        error; error is recorded, and negative response is generated
        if any errors occur.

        ``rollback (rollback-on-error)``:  If an error condition occurs such that an
        error severity <rpc-error> element is generated, the server
        will stop processing the <edit-config> operation and restore
        the specified configuration to its complete state at the
        start of this <edit-config> operation.  This option requires
        the server to support the :rollback-on-error capability.
            

Edit-config  With-defaults attribute
-------------------------------------

    An ``edit-config`` RPC can have a 'default' attribute.

    If the server supports the 'report-all-tagged' mode, then the 'default' attribute defined in RFC6243 section 6 also impacts the <edit-config> operation.
    If the 'default' attribute is present and set to 'true', then the server MUST treat the new data node as a request to return that node to its default 
    value (i.e., remove it from the configuration datastore).  The data node within the NETCONF message MUST contain a value in this case, which MUST be 
    equal to the schema default value. 

    If the 'default' attribute is present, then the effective operation for the target data node MUST be 'create', 'merge', or 'replace'. 

    If you want to enable this attribute, use ``edit-config options | default-attribute`` as shown below:

    .. image:: images/xml_default_attribute.*

    Here is the corresponding XML snippet::
        
    <cfgnetopeer:enabled xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0" wd:default="true">false</cfgnetopeer:enabled>
        
    .. _commit_changes:  
    
Commit changes into running datastore
------------------------------------------------------------------------------

    After making changes to ``candidate`` datastore, we must commit the changes into ``running`` datastore, otherwise the
    changes will not make effect to the device.

    If the selected target datastore is ``running`` then you are editing it directly so nothing needs to be committed!

    If the selected target datastore is ``candidate`` then you need to commit the changes you made to the candidate 
    config datastore to the running config datastore.
     
    * To commit the changes made to candidate datastore into the running datastore, click the down-arrow button
      to the right of the ``candidate`` radio button, and select ``commit``.
        
      .. image:: images/commit.*

    * To discard changes made to the candidate datastore and set it to the same as the current running,
      click the down-arrow button to the right of the ``candidate`` radio button, and select 
      ``discard-changes and revert to the current running``.        
        
      .. image:: images/discard.*

          
    Alternatively you can use ``<confirmed-commit>``  if the server supports it.     

    A confirmed-commit needs two separate commits. The second commit must be 
    received by the server within the specified timeout period. Otherwise the
    commit process will be abandoned and the config will be reverted to the state
    before the first commit was issued.
                                             

.. _copy_startup:  
                                       
                                       
Copy changes to startup datastore to keep it across reboot
-----------------------------------------------------------------

    If the server supports ``startup`` datastore, then after you make any changes, 
    the current running config must be copied to ``startup`` so the changes can
    retain across reboot. Otherwise the changes won't go back to the state before
    your editing.
                                          
    If the server does not support ``startup`` datastore then the changes made 
    to ``running`` datastore will be automatically retained and kept across reboot.
                                          
    Normally we don't edit the ``startup`` datastore directly, even if the remote server 
    advertises the support for it. 

    There are two important operations we must know for ``startup`` datastore.

    *If we find we are satisfied with the current ``running`` config store configuration, the we must copy 
    the current running config to ``startup`` config datasrtore so it can
    be retained across reboot. To do that, click the down-arrow button to the right of the ``startup`` radio 
    button, and select ``Save running as startup`` config.  

    .. image:: images/save_startup.*

    *In case we messed up totally we want to revert to factory setting on next reboot, you can  click the 
    down-arrow button to the right of the ``startup`` radio 
    button, and select ``Reset to factory settings (delete-config)``.

    .. image:: images/reset_factory.*


