netconf-console2

netconf-console2

A console application for interacting with NETCONF servers built on top of ncclient <http://https://pypi.org/project/ncclient/>__.

Note: this is a continuation (or a rename) of the project netconf-console; the old name was clashing with another product. Use netconf-console2 instead of netconf-console.

Requirements and installation

This application runs both in Python 2 and Python 3 environments. The only package required for running this application is ncclient; if this is installed, all other necessary packages are installed as dependencies. This means that if you can (successfully) run something like pip install ncclient on the target platform, all requirements should be met.

If you cannot, there still is a chance you can run it if the target platform supports at least packages six and lxml, which are commonly present; and if it contains paramiko or at least cryptography, you will be able to use SSH (without them you can only use plain and nonstandard TCP transport). The missing piece, ncclient, can be cloned <https://github.com/ncclient/ncclient>__ and compiled to a "Python Wheel" - you can do this on any computer and copy the resulting .whl file to the target platform, it should work there. Pretty much the same holds for paramiko. You may also want to create a wheel for the application itself by running python setup.py bdist_wheel.

Installing and running the application

If you can and want to install the application and all necessary
libraries, just run ``python setup.py install``. Otherwise prepare all
necessary .whl files and the script ``netconf-console2`` to the target
platform. If they are in the same directory, nothing else is needed,
otherwise you may need to add the wheel files to ``PYTHONPATH`` before
running the script.

Once installed or copied, you can just run the script with appropriate
options - see below.

Command-line mode
-----------------

The application can be run in two different modes: command-line mode and
interactive (console) mode. The command-line mode allows you to request
several RPC operations in one shell command. The command line would
contain the operation command options (``--get``, ``--lock``, etc.) in
the desired order, all common options (such as ``--host``, ``--port``
etc.) as well as command options (``--db``, ``--style``); the command
options are all used for the commands that accept them, so for example
no two commands can address different datastores.

An example of such command line:

::

    # netconf-console2 --host=example.com --db candidate --lock --edit-config=fragment1.xml \
    --rpc=commit-confirmed.xml --unlock --sleep 5 --rpc=confirm.xml

Interactive mode
----------------

The interactive mode is started by ``--interactive`` (or ``-i``). During
an interactive session the user issues commands, one per line, with
required arguments or options. The options are isolated now, so it is
possible to have two commands in one session accessing different
datastores. The interactive console provides limited support for
tab-completion of commands, options, and their arguments.

The previous example can look like this:

::

    # netconf-console2 --host=example.com -i
    netconf> lock
    netconf> edit-config fragment1.xml --db candidate
    netconf> rpc commit-confirmed.xml
    netconf> unlock
    netconf> get-config
    netconf> rpc confirm.xml
    netconf>

Note: some commands (``rpc``, ``edit-config`` and others) may accept
data from standard input in the command-line mode; this does not work in
the interactive mode.

Some capabilities of the interactive mode can be used in command-line
mode too using ``--expr`` pseudo-command: the argument is a command
(including options) as if it was added in the interactive mode, such as

::

    # netconf-console2 --expr 'get-config --db candidate' 'get-config'

Commands
--------

A command may accept an argument and a number of options. In
command-line mode, all option values are shared (see above); conversely,
in interactive mode the option needs to be provided for every command
where its desired value differs from the default. If a command does not
accept given option, it is a syntax error to provide it in interactive
mode (in command-line mode such situations are ignored).

``hello``
    Send just the initial ``hello`` message and display the reply. Does
    not accept any arguments or options.

``get``
    Send ``get`` RPC. Accepts options ``outputStyle``, ``with-defaults``,
    ``xpath``. As an alternative to ``xpath``, ``get`` accepts path as an
    argument.

``get-config``
    Send ``get-config`` RPC. Accepts the same set of options as ``get``
    plus ``db``.

``set``
    Send ``edit-config`` with single leaf assignment.  Requires the assignment
    in the form ``<path>=<value>`` as an argument, accepts ``db``, ``test``,
    and ``operation``.  The path may contain (or actually needs to contain, in
    case it descends into a list instance) simple predicates in the form
    ``node[key1=value1][key2=value2]...``.

``delete``
    Sends ``edit-config`` with a single node to be deleted.  The node is
    determined by the path provided as an argument, see ``set`` for the path
    format.  Accepts ``db``, ``test``, and ``del-operation`` options.

``create``
    Sends ``edit-config`` with a single node to be created.  The node is
    determined by the path provided as an argument, see ``set`` for the path
    format.

``kill-session``
    Send ``kill-session`` RPC. Requires session identifier as an
    argument, accepts no options.

``discard-changes``
    Send ``discard-changes`` RPC. Accepts no arguments or options.

``lock``
    Send ``lock`` RPC towards the datastore indicated by ``db`` option.

``unlock``
    Send ``unlock`` RPC, counterpart of ``lock``.

``commit``
    Send ``commit`` request. Accepts optional ``confirmed`` as an
    argument and option ``timeout``.

``validate``
    Send ``validate`` RPC. Accepts one argument, which can be either the
    literal ``candidate`` (to validate the contents of the candidate
    datastore) or a filename pointing to a file with full configuration
    to be validated; defaults to ``-``, standard input.

``copy-running-to-startup``
    Send ``copy-config`` RPC with ``running`` datastore as the source
    and ``startup`` datastore as target. Accepts no arguments or
    options.

``copy-config``
    Send ``copy-config`` RPC. Accepts a filename for the source
    configuration as a argument (defaults to ``-``), and the ``db``
    option for the target datastore.

``edit-config``
    Send ``edit-config`` RPC. Accepts the same set of arguments and
    options as ``copy-config``.

``get-schema``
    Send ``get-schema`` RPC. Requires schema identifier as an argument.

``create-subscription``
    Send ``create-subscription`` RPC. Requires notification stream
    identifier as an argument. The notifications received from the
    server are displayed on standard output while the session is active
    - i.e. makes sense either in an interactive mode or in command-line
    mode with the command ``sleep``.

``rpc``
    If none of the commands above is sufficient, a custom RPC can be
    send using this command. Accepts a filename (or ``-`` as default) as
    an argument; the file contents is sent to the server enveloped in
    the ``rpc`` element.

``sleep``
    Do nothing, just sleep for given number of seconds provided as an
    argument.

As a backward-compatibility option, it is possible to provide a filename (or
``-`` for standard input) containing all messages that are supposed to be sent
to the server, separated by the NETCONF transport v1.0 message separator.  This
option cannot be used with any other command.  Note that RPC message-id is not
preserved.


Options
-------

There are two sets of options: global options and command options.
Global options affect overall behavior of the tool and can be provided
in the shell command line (i.e. not to individual commands in the
interactive mode). Command options affect individual commands and in
interactive mode they need to be provided per command.

Global options
~~~~~~~~~~~~~~

``help``
    Display a usage message and exit.

``host``
    Hostname or IP address of the NETCONF server.

``port``
    Port number of the NETCONF server.

``user``
    Username for the authentication on the server (defaults to
    ``admin``).

``password``
    Password for the authentication on the server (defaults to
    ``admin``). If the option is provided without a value, the password
    is read from the terminal.

``privKeyFile``
    File containing the user's private key.

``raw``
    Print all received replies in the original form. The option accepts
    one argument, name of file where the text should be stored; defaults
    to standard output.

``tcp``
    Use plain TCP for the communication with the server (without this
    option SSH is used).

``dry``
    Do not actually send any RPCs, just display them to standard output.

Local options
~~~~~~~~~~~~~

As written above, local (or command) options are meaningful only for
certain command.

``outputStyle``
    Affects the format of the displayed RPC reply. By default, the reply
    is pretty-printed, but otherwise kept as is. The option accepts
    ``plain`` (do no pretty-printing) and ``noaaa`` (remove the ``aaa``
    subtree from the reply from ``get`` or ``get-config`` requests).

``db``
    Target datastore for some of the RPC operations. Defaults to
    ``running``.

``timeout``
    Timeout in seconds for confirmed commit.

``with-defaults``
    Set default values handling. Accepted values are ``explicit``,
    ``trim``, ``report-all``, ``report-all-tagged``.

``xpath``
    Set the XPath filter for get or subscribe requests.

``ns``
    Set a namespace prefix list; useful in case ``xpath`` option uses
    namespace prefixes.

``test``
    Test-option value. Accepted values are ``test-only``,
    ``test-then-set`` and ``set``.

``operation``
    Value of the attribute ``nc:operation``.  Useful with the ``set``
    operation, can be ``merge`` (the default), ``replace``, ``create``.

``del-operation``
    Value of the attribute ``nc:operation`` when used with the ``delete``
    operation, can be ``remove`` (the default) or ``delete``.