Getting Started with NETCONFc 
====================================

In this tutorial you will learn how to connect to a NETCONF server
and perform some frequently used actions.

.. _new_connection:

Connect over SSH or SSH Call Home
--------------------------------------------
    Start NETCONFc
   
    .. image:: images/connect_toolbar_button.*     
     
    Click the ``Connect`` button, select ``NETCONF over SSH`` to bring up 
    the session creation dialog.
    
    .. image:: images/session_creation.*         

.. _new_connection_parameter:
    
    |
    |
    **New session parameters**::
    
    Enter server's host name or IP address, port number, user name and 
    password. If using Call-home to connect, specify the call-home port. 
     
    ``timeout`` is the time NETCONFc will abort connecting if no 
    response has been received after that period of time.
    
    ``keep-alive`` is the interval a heart-bear message will be 
    sent to the server to keep the connection  open if no action 
    after that period of time.    
  
    Alternatively you can use a private key file (PEM format) to 
    do SSH public key authentication, rather than SSH password 
    based authentication. 
    
    If you use a privkey file, then the 'password' is the password
    of the privkey, if there is one.
       
    Then click the button "Connect" on the session creation 
    dialog. If using call-home, click the button 
    "Start listening for call-home".
    
    You should be connected to the server. 
        
    If error occurs, check if the server is running on the specified 
    address and port. Also make sure the correct user name and password 
    are used.


Connect over TLS  or TLS Call Home
--------------------------------------------------
    Start NETCONFc
   
    .. image:: images/connect_toolbar_button.*     
     
    Click the ``Connect`` button, select ``NETCONF over TLS`` to bring up 
    the session creation dialog.    

    .. image:: images/session_creation_tls.*   

.. _new_connection_parameter:
    
    
    |
    |
    **New session parameters**
    
    Enter server's host name or IP address, port number, 
    'client certificate' file with full path, \n    
    'client private key' file with full path (this field can be left blank 
    if the client certificate file already contains client's private key), 
    and the 'trusted CA certificate' file with full path, which is needed 
    to validate the server's certificate and can be a chained certificate file.

    ``timeout`` is the time NETCONFc will abort connecting if no response 
    has been received after that period of time
    
    ``keep-alive`` is the interval a heart-bear message will be sent to the 
    server to keep the connection  open if no action after that period of time.    
    
    Then click the button "Connect" on the session creation 
    dialog. If using call-home, click the button 
    "Start listening for call-home".
    
    You should be connected to the server. 
    
    If error occurs, check if the server is running on the specified 
    address and port. Also make sure the correct certificates and keys
    are used.
    
    ll YANG modules supported 
    and advertised by the connected remote server.

YANG Models advertised by the server 
----------------------------------------------------

    After a successful connection, the YANG models loaded into 
    NETCONFC that are also advertised by the server hello or 
    listed in the server's ietf-yang-library model will have 
    a green check mark displayed.
    
    .. image:: images/shown_modules_indir.*

    
Download YANG models
----------------------------------------------------
    For modules that are not found in the local YANG module path, 
    you can try downloading them directly from server. 
     
    Select the menu "Models | Download Models", a listbox will 
    come up with all available YANG model documents on the server,
    select the desired models and click "Download" button.

    .. image:: images/download_module.*
        
    .. note::     
           This requires the server supports ``get-schema`` operation.        


View server capabilities
----------------------------------------------------
    If the connection was successful, click the "Browse" button to
    browse YANG models.
    
    .. image:: images/netconf_session.*
    

    Click the server capabilities advertised icon 
    to view capabilities advertised by the remote server.

         
Choose a target datastore for retrieving and editing
------------------------------------------------------
    
    Before we send any queries to server, we need to decide which 
    datastore we would like to work on.
    
    The selected datastore will be used as the default target 
    datastore when you browse the connected server to issue get, 
    get-config or edit-config commands.
    
    .. image:: images/select_datastore.*
        
    
Browse YANG schema tree and lookup node properties
------------------------------------------------------------------

    If a module is found in the local YANG module path, you can browse it.
    
    Expand the module tree in the left side window pane to browse its data nodes.
    
    Right click on a node, select "Lookup YANG Info" to view its type, enumerations, size, range etc.
    
    Nodes are given different icons or indicators so you can easily tell what are they and
    determine what operations can be performed on that node. For example, for a read-only
    state node, it makes no sense to send a <get-config> or an <edit-config> command against it.
    
    |
    .. image:: images/node-category.*
        

.. _basic_get:
        
Send <get> requests
----------------------------------------------------

    You can select one or more nodes in the module tree and send a <get> 
    to retrieve current data (state and config) underneath.
           
    In the notebook in the window on the right side , you will also see a notebool tab XML page that 
    shows the XML encoding of the last RPC request and reply.
  
    There is also a notebook tab page that is either labeled as ``Get instance datatree``
    or ``<Get-config instance data tree``. It shows a tree view for the retrieved instance 
    data. 
    
    Click the context 'menu' icon or right click to bring up context menu:
    
    .. image:: images/send-get.*
    
    You can use <Shift + click> or <Ctrl + click> to select multiple nodes for retrieving data
    
    .. image:: images/select_multiple.*
    
    .. note::     
        When you <get> on a leaf node in a list, if the server does not send back the value for 
        the list key nodes at the same time, then you will not make much sense out of the 
        data you received. NETCONFc by default will include all key nodes when querying data. 
        To turn this feature off see :ref:`retrieval_with_key`
    
.. _basic_get_config:
         
Send <get-config> requests
---------------------------
    
    For module tree config nodes (node in navy color), you can send a <get-config> to retrieve current settings underneath it.
    
    Select any node, right click and select 'get-config' to retrieve the config data under this node.
    If you select the ``module`` node, then all config data in that module will be retrieved.
    
    .. image:: images/send-get-config.*

    .. note::     
        When you <get> against a leaf node in a list, if the server does not send back the value for 
        the list key nodes at the same time, then you will not make much sense out of the 
        data you received. NETCONFc by default will include all key nodes when querying data. 
        To turn this feature off see :ref:`retrieval_with_key`
     
.. _basic_edit_yang_tree:    
 
Send <edit-config> command from *schema tree* 
--------------------------------------------------------

    We call the YANG module tree on the left side ``schema tree``
    
    To create a node in the remote server config, just select the node in the module tree,
    right-click and select ``Enter Value to include in RPC`` or use shortcut key ``Ctrl + W``. For types such as Enumeration and indentityref
    a drop-down box will be available for you to select one from a list of values. 
        
	.. image:: images/enter_value_dropdown.*
        
    You can also click the ``Value`` cell to enter or modify the value you want to set.
    
    After you finish entering the value,  right-click and select ``edit-config`` to send it.

    To set an indentityref value that is defined in another
    module, enter the value in the form of modulename:indentify. For example, you can set /ietf-interfaces:interfaces/interface/type
    to "iana-if-type:ethernetCsmacd", assuming module 'iana-if-type' is found in the current module path.
    
    In the following example, we set /ietf-system/system/contact to "Tom":
    
    |
    .. image:: images/set_syscontact.*

    
.. _basic_edit_instance_tree:    


Send <edit-config> command from *data tree* 
----------------------------------------------------------

    We call the instance tree on the right side ``data tree``
    
    You can modify or delete instance nodes from the data tree on the right side window.
    
    It is much easier to modify a list entry here since you don't need to explicitly enter values for all list key nodes.
    NETCONFc will automatically add list key nodes in the <edit-config> when you edit a list node. 
    If you want to the same thing in the module tree at the left side you would have to manually enter all values for list key nodes.
    It is even harder when you work with nested lists.
    
    In some cases, it might be also easier to create a new instance based on an existing instance. 
   
    After you send a ``get-config`` request, you
    will see a ``Get-config reply (Read-Write)`` notebook page on the right side of the 
    screen. It shows an ``data tree``, a tree view for the retrieved instance data. 
    
    Here you can also create or modify instance nodes by sending ``edit-config``.
    
    
	Right-click and select ``Enter Value to include in RPC`` or use shortcut key ``Ctrl + W``. 
	For types such as Enumeration and indentityref
    a drop-down box will be available for you to select one from a list of values. 
        
    You can also click the ``Value`` cell to enter or modify the value you want to set.
    
    After you finish entering the value,  right-click and select ``edit-config`` to send it.
    
    Select a node in the data tree, click the ``Value`` cell and enter the 
    value you want to set, then right click and select ``edit-config`` to send it!  
    
    |
    .. image:: images/edit_config_instance_tree.*
        
    If you changed your mind and do not want to set the value, you can right click and select
    ``unstage`` to remove it from list of nodes to be set. Of course you can also just do
    another ``get-config``.
    
.. note::        
    After editing configuration, you may need to  :ref:`commit_changes` 
    or  :ref:`copy_startup`.
    
Close connection and reconnect 
-------------------------------
    Normally if you set the ``keep_alive`` parameter to a non-zero value, the connection should be kept open.

    However if the connection you are currently working is terminated for any reason, you can click ``Reconnect`` button to 
    have the connection reestablished by creating a new session.

    .. image:: images/reconnect_session.*    

    You can also close the current session window and click the ``Connect`` toolbar button on the main 
    ``YANG module explorer`` window to create a new session.

    To close the established connection session by issuing a ``close-session`` command, simply click the [x] cross button on the top right corner of the session window. 

Logging 
----------------
    You can log RPCs sent and received by using NETCONFc's "Log" feature.
    To bring up the Log window click the "Log" toolbar button in the top YANG Module Explorer window.
    
Sending Raw XML RPC
-------------------------
    You can send RPC with a well formed XML message directly in the "Send Request and Show Replies" tab window.
    Using this feature you can modify a RPC message and resend it quickly.
    
    For example, you can send a <get-config> request. Then in the "Send Request and Show Reply)"
    window, you should see the last request and reply XML message.
    You may want to change some fields (e.g. the message-id) and then simply click 
    "Send RPC with the above XML" to resend the <get-config> request.
    
    .. image:: images/send_raw_xml.*    
    
    This can be a handy way to test your server and see how it responds to various requests. 

    