# `manager` – High-level API

This module is a thin layer of abstraction around the library. It exposes all core functionality.

## Customizing

These attributes control what capabilties are exchanged with the NETCONF server and what operations are available through the `Manager` API.

`ncclient.manager.``OPERATIONS` = {'create_subscription': <class 'ncclient.operations.subscribe.CreateSubscription'>, 'delete_config': <class 'ncclient.operations.edit.DeleteConfig'>, 'get_schema': <class 'ncclient.operations.retrieve.GetSchema'>, 'get': <class 'ncclient.operations.retrieve.Get'>, 'lock': <class 'ncclient.operations.lock.Lock'>, 'copy_config': <class 'ncclient.operations.edit.CopyConfig'>, 'close_session': <class 'ncclient.operations.session.CloseSession'>, 'dispatch': <class 'ncclient.operations.retrieve.Dispatch'>, 'poweroff_machine': <class 'ncclient.operations.flowmon.PoweroffMachine'>, 'unlock': <class 'ncclient.operations.lock.Unlock'>, 'get_config': <class 'ncclient.operations.retrieve.GetConfig'>, 'kill_session': <class 'ncclient.operations.session.KillSession'>, 'discard_changes': <class 'ncclient.operations.edit.DiscardChanges'>, 'commit': <class 'ncclient.operations.edit.Commit'>, 'edit_config': <class 'ncclient.operations.edit.EditConfig'>, 'validate': <class 'ncclient.operations.edit.Validate'>, 'reboot_machine': <class 'ncclient.operations.flowmon.RebootMachine'>}

  Dictionary of base method names and corresponding `RPC` subclasses. It is used to lookup operations, e.g. get_config is mapped to `GetConfig`. It is thus possible to add additional operations to the `Manager` API.

## Factory functions

A `Manager` instance is created using a factory function.

`ncclient.manager.``connect_ssh`(*args, **kwds)

  Initialize a `Manager` over the SSH transport. For documentation of arguments see `ncclient.transport.SSHSession.connect()`.

  The underlying `ncclient.transport.SSHSession` is created with
    `CAPABILITIES`. It is first instructed to `load_known_hosts()` and then all the provided arguments are passed directly to its implementation of `connect()`.
  To invoke advanced vendor related operation add device_params =
    {‘name’:’<vendor_alias>’} in connection paramerers. For the time, ‘junos’ and ‘nexus’ are supported for Juniper and Cisco Nexus respectively.

`ncclient.manager.``connect` = <function connect>

## Manager

Exposes an API for RPC operations as method calls. The return type of these methods depends on whether we are in `asynchronous or synchronous mode`.

In synchronous mode replies are awaited and the corresponding `RPCReply` object is returned. Depending on the `exception raising mode`, an rpc-error in the reply may be raised as an `RPCError` exception.

However in asynchronous mode, operations return immediately with the corresponding `RPC` object. Error handling and checking for whether a reply has been received must be dealt with manually. See the `RPC` documentation for details.

Note that in case of the `get()` and `get_config()` operations, the reply is an instance of `GetReply` which exposes the additional attributes `data` (as `Element`) and `data_xml` (as a string), which are of primary interest in case of these operations.

Presence of capabilities is verified to the extent possible, and you can expect a `MissingCapabilityError` if something is amiss. In case of transport-layer errors, e.g. unexpected session close, `TransportError` will be raised.

class `ncclient.manager.``Manager`(session, device_handler, timeout=30, *args, **kwargs)
  For details on the expected behavior of the operations and their
    parameters refer to RFC 4741.

  Manager instances are also context managers so you can use it like this:

      with manager.connect("host") as m:
          # do your stuff

  ... or like this:

      m = manager.connect("host")
      try:
          # do your stuff
      finally:
          m.close_session()

  `get_config`(source, filter=None)

    Retrieve all or part of a specified configuration.

    source name of the configuration datastore being queried

    filter specifies the portion of the configuration to retrieve (by default entire configuration is retrieved)

    Seealso: | Filter parameters

  `edit_config`(target, config, default_operation=None, test_option=None, error_option=None)

    Loads all or part of the specified config to the target configuration datastore.

    target is the name of the configuration datastore being edited

    config is the configuration, which must be rooted in the config element. It can be specified either as a string or an `Element`.

    default_operation if specified must be one of { “merge”, “replace”, or “none” }

    test_option if specified must be one of { “test_then_set”, “set” }

    error_option if specified must be one of { “stop-on-error”, “continue-on-error”, “rollback-on-error” }

    The “rollback-on-error” error_option depends on the :rollback-on-error capability.

  `copy_config`(source, target)

    Create or replace an entire configuration datastore with the contents of another complete configuration datastore.

    source is the name of the configuration datastore to use as the source of the copy operation or config element containing the configuration subtree to copy

    target is the name of the configuration datastore to use as the destination of the copy operation

    Seealso: | Source and target parameters

  `delete_config`(target)

    Delete a configuration datastore.

    target specifies the name or URL of configuration datastore to delete

    Seealso: | Source and target parameters

  `dispatch`(rpc_command, source=None, filter=None)

    rpc_command specifies rpc command to be dispatched either in plain text or in xml element format (depending on command)

    source name of the configuration datastore being queried

    filter specifies the portion of the configuration to retrieve (by default entire configuration is retrieved)

    Seealso: | Filter parameters

    Examples of usage:

        dispatch('clear-arp-table')

    or dispatch element like

        xsd_fetch = new_ele('get-xnm-information')
        sub_ele(xsd_fetch, 'type').text="xml-schema"
        sub_ele(xsd_fetch, 'namespace').text="junos-configuration"
        dispatch(xsd_fetch)

  `lock`(target)

    Allows the client to lock the configuration system of a device.

    target is the name of the configuration datastore to lock

  `unlock`(target)

    Release a configuration lock, previously obtained with the lock operation.

    target is the name of the configuration datastore to unlock

  `locked`(target)

    Returns a context manager for a lock on a datastore, where target is the name of the configuration datastore to lock, e.g.:

        with m.locked("running"):
            # do your stuff

    ... instead of:

        m.lock("running")
        try:
            # do your stuff
        finally:
            m.unlock("running")

  `get`()

    Retrieve running configuration and device state information.

    filter specifies the portion of the configuration to retrieve (by default entire configuration is retrieved)

    Seealso: | Filter parameters

  `close_session`()

    Request graceful termination of the NETCONF session, and also close the transport.

  `kill_session`(session_id)

    Force the termination of a NETCONF session (not the current one!)

    session_id is the session identifier of the NETCONF session to be terminated as a string

  `commit`(confirmed=False, timeout=None, persist=None)

    Commit the candidate configuration as the device’s new current configuration. Depends on the :candidate capability.

    A confirmed commit (i.e. if confirmed is True) is reverted if there is no followup commit within the timeout interval. If no timeout is specified the confirm timeout defaults to 600 seconds (10 minutes). A confirming commit may have the confirmed parameter but this is not required. Depends on the :confirmed-commit capability.

    confirmed whether this is a confirmed commit

    timeout specifies the confirm timeout in seconds

    persist make the confirmed commit survive a session termination, and set a token on the ongoing confirmed commit

  `discard_changes`()

    Revert the candidate configuration to the currently running configuration. Any uncommitted changes are discarded.

  `validate`(source)

    Validate the contents of the specified configuration.

    source is the name of the configuration datastore being validated or config element containing the configuration subtree to be validated

    Seealso: | Source and target parameters

  `async_mode`

    Specify whether operations are executed asynchronously (True) or synchronously (False) (the default).

  `timeout`

    Specify the timeout for synchronous RPC requests.

  `raise_mode`

    Specify which errors are raised as `RPCError` exceptions. Valid values are the constants defined in `RaiseMode`. The default value is `ALL`.

  `client_capabilities`

    `Capabilities` object representing the client’s capabilities.

  `server_capabilities`

    `Capabilities` object representing the server’s capabilities.

  `session_id`

    session-id assigned by the NETCONF server.

  `connected`

    Whether currently connected to the NETCONF server.

## Special kinds of parameters

Some parameters can take on different types to keep the interface simple.

### Source and target parameters

Where an method takes a source or target argument, usually a datastore name or URL is expected. The latter depends on the :url capability and on whether the specific URL scheme is supported. Either must be specified as a string. For example, “running”, “ftp://user:pass@host/config”.

If the source may be a config element, e.g. as allowed for the validate RPC, it can also be specified as an XML string or an `Element` object.

### Filter parameters

Where a method takes a filter argument, it can take on the following types:

- A tuple of (type, criteria).

  > Here type has to be one of “xpath” or “subtree”.

  > - For “xpath” the criteria should be a string containing the XPath expression.
  > - For “subtree” the criteria should be an XML string or an `Element` object containing the criteria.

- A <filter> element as an XML string or an `Element` object.