# Welcome

ncclient is a Python library for NETCONF clients. It aims to offer an intuitive API that sensibly maps the XML-encoded nature of NETCONF to Python constructs and idioms, and make writing network-management scripts easier. Other key features are:

- Supports all operations and capabilities defined in RFC 6241.

- Request pipelining.

- Asynchronous RPC requests.

- Keeping XML out of the way unless really needed.

- Extensible. New transport mappings and capabilities/operations can be easily added.

The best way to introduce is through a simple code example:

    from ncclient import manager

    # use unencrypted keys from ssh-agent or ~/.ssh keys, and rely on known_hosts
    with manager.connect_ssh("host", username="user") as m:
        assert(":url" in m.server_capabilities)
        with m.locked("running"):
            m.copy_config(source="running", target="file:///new_checkpoint.conf")
            m.copy_config(source="file:///old_checkpoint.conf", target="running")

As of version 0.4 there has been an integration of Juniper’s and Cisco’s forks. Thus, lots of new concepts have been introduced that ease management of Juniper and Cisco devices respectively. The biggest change is the introduction of device handlers in connection params. For example to invoke Juniper’s functions and params one has to re-write the above with device_params={‘name’:’junos’}:

    from ncclient import manager

    with manager.connect(host=host, port=830, username=user, hostkey_verify=False, device_params={'name':'junos'}) as m:
        c = m.get_config(source='running').data_xml
        with open("%s.xml" % host, 'w') as f:
            f.write(c)

Respectively, for Cisco Nexus, the name is nexus. Device handlers are easy to implement and prove to be futureproof.

The latest pull request merge includes support for Huawei devices with name huawei in device_params.

## Supported device handlers

- Alcatel Lucent: device_params={‘name’:’alu’}

- Ciena: device_params={‘name’:’ciena’}

- Cisco:

    - CSR: device_params={‘name’:’csr’}

    - Nexus: device_params={‘name’:’nexus’}

    - IOS XR: device_params={‘name’:’iosxr’}

    - IOS XE: device_params={‘name’:’iosxe’}

- H3C: device_params={‘name’:’h3c’}

- HP Comware: device_params={‘name’:’hpcomware’}

- Huawei:

    - device_params={‘name’:’huawei’}

    - device_params={‘name’:’huaweiyang’}

- Juniper: device_params={‘name’:’junos’}

- Server or anything not in above: device_params={‘name’:’default’}

Contents:

- `manager` – High-level API
  - Customizing
    - `OPERATIONS`
  - Factory functions
    - `connect_ssh()`
    - `connect`
  - Manager
    - `Manager`
      - `Manager.HUGE_TREE_DEFAULT`
      - `Manager.get_config()`
      - `Manager.get_schema()`
      - `Manager.edit_config()`
      - `Manager.copy_config()`
      - `Manager.delete_config()`
      - `Manager.dispatch()`
      - `Manager.lock()`
      - `Manager.unlock()`
      - `Manager.get()`
      - `Manager.close_session()`
      - `Manager.kill_session()`
      - `Manager.commit()`
      - `Manager.cancel_commit()`
      - `Manager.discard_changes()`
      - `Manager.validate()`
      - `Manager.create_subscription()`
      - `Manager.reboot_machine()`
      - `Manager.poweroff_machine()`
      - `Manager.locked()`
      - `Manager.take_notification()`
      - `Manager.async_mode`
      - `Manager.timeout`
      - `Manager.raise_mode`
      - `Manager.client_capabilities`
      - `Manager.server_capabilities`
      - `Manager.session_id`
      - `Manager.connected`
      - `Manager.huge_tree`
  - Special kinds of parameters
    - Source and target parameters
    - Filter parameters
- Complete API documentation
  - `capabilities` – NETCONF Capabilities
    - `schemes()`
    - `Capabilities`
  - `xml_` – XML handling
    - `XMLError`
    - Namespaces
      - `BASE_NS_1_0`
      - `TAILF_AAA_1_1`
      - `TAILF_EXECD_1_1`
      - `CISCO_CPI_1_0`
      - `JUNIPER_1_1`
      - `FLOWMON_1_0`
      - `register_namespace()`
      - `qualify()`
    - Conversion
      - `to_xml()`
      - `to_ele()`
      - `parse_root()`
      - `validated_element()`
  - `transport` – Transport / Session layer
    - Base types
      - `Session`
        - `Session.add_listener()`
        - `Session.client_capabilities`
        - `Session.connected`
        - `Session.get_listener_instance()`
        - `Session.id`
        - `Session.remove_listener()`
        - `Session.server_capabilities`
      - `SessionListener`
        - `SessionListener.callback()`
        - `SessionListener.errback()`
    - SSH session implementation
      - `ssh.default_unknown_host_cb()`
      - `SSHSession`
        - `SSHSession.connect()`
        - `SSHSession.load_known_hosts()`
        - `SSHSession.transport`
    - Errors
      - `TransportError`
      - `SessionCloseError`
      - `SSHError`
      - `AuthenticationError`
      - `SSHUnknownHostError`
  - `operations` – Everything RPC
    - `RaiseMode`
      - `RaiseMode.ALL`
      - `RaiseMode.ERRORS`
      - `RaiseMode.NONE`
    - Base classes
      - `RPC`
        - `RPC.DEPENDS`
        - `RPC.REPLY_CLS`
        - `RPC._assert()`
        - `RPC._request()`
        - `RPC.error`
        - `RPC.event`
        - `RPC.huge_tree`
        - `RPC.is_async`
        - `RPC.raise_mode`
        - `RPC.reply`
        - `RPC.request()`
        - `RPC.timeout`
      - `RPCReply`
        - `RPCReply._parsing_hook()`
        - `RPCReply.error`
        - `RPCReply.errors`
        - `RPCReply.ok`
        - `RPCReply.xml`
      - `RPCError`
        - `RPCError.info`
        - `RPCError.message`
        - `RPCError.path`
        - `RPCError.severity`
        - `RPCError.tag`
        - `RPCError.type`
    - Operations
      - Retrieval
        - `Get`
          - `Get.REPLY_CLS`
          - `Get.request()`
        - `GetConfig`
          - `GetConfig.REPLY_CLS`
          - `GetConfig.request()`
        - `GetReply`
          - `GetReply.data`
          - `GetReply.data_ele`
          - `GetReply.data_xml`
        - `Dispatch`
          - `Dispatch.REPLY_CLS`
          - `Dispatch.request()`
        - `GetSchema`
          - `GetSchema.REPLY_CLS`
          - `GetSchema.request()`
      - Editing
        - `EditConfig`
          - `EditConfig.request()`
        - `DeleteConfig`
          - `DeleteConfig.request()`
        - `CopyConfig`
          - `CopyConfig.request()`
        - `Validate`
          - `Validate.request()`
        - `Commit`
          - `Commit.request()`
        - `DiscardChanges`
          - `DiscardChanges.request()`
        - `CancelCommit`
          - `CancelCommit.request()`
      - Flowmon
        - `PoweroffMachine`
          - `PoweroffMachine.request()`
        - `RebootMachine`
          - `RebootMachine.request()`
      - Locking
        - `Lock`
          - `Lock.request()`
        - `Unlock`
          - `Unlock.request()`
      - Session
        - `CloseSession`
          - `CloseSession.request()`
        - `KillSession`
          - `KillSession.request()`
      - Subscribing
        - `CreateSubscription`
          - `CreateSubscription.request()`
    - Exceptions
      - `OperationError`
      - `MissingCapabilityError`
      - `TimeoutExpiredError`

## Indices and tables

- Index

- Module Index

- Search Page