0
# NCClient
1

2
A Python library for NETCONF (Network Configuration Protocol) clients. NCClient provides a comprehensive interface for managing network devices through the standardized NETCONF protocol, supporting multiple transport methods (SSH, TLS, Unix sockets) and device-specific optimizations for major network equipment vendors.
3

4
## Package Information
5

6
- **Package Name**: ncclient
7
- **Language**: Python
8
- **Installation**: `pip install ncclient`
9

10
## Core Imports
11

12
```python
13
import ncclient
14
from ncclient import manager
15
```
16

17
For device-specific operations:
18

19
```python
20
from ncclient import operations
21
from ncclient import transport
22
from ncclient import capabilities
23
```
24

25
## Basic Usage
26

27
```python
28
from ncclient import manager
29

30
# Connect to a NETCONF device
31
with manager.connect(
32
    host='192.168.1.1',
33
    username='admin',
34
    password='admin',
35
    hostkey_verify=False
36
) as m:
37
    # Get server capabilities
38
    for capability in m.server_capabilities:
39
        print(capability)
40
    
41
    # Get configuration
42
    config = m.get_config(source='running')
43
    print(config)
44
    
45
    # Edit configuration
46
    config_xml = '''
47
    <config>
48
        <interface xmlns="urn:example:interface">
49
            <name>eth0</name>
50
            <description>Management Interface</description>
51
        </interface>
52
    </config>
53
    '''
54
    m.edit_config(target='candidate', config=config_xml)
55
    m.commit()
56
```
57

58
## Architecture
59

60
NCClient's architecture provides layered abstraction for NETCONF client operations:
61

62
- **Manager**: High-level interface that orchestrates NETCONF sessions and operations
63
- **Operations**: NETCONF RPC operations (get-config, edit-config, lock, etc.)
64
- **Transport**: Communication layers (SSH, TLS, Unix sockets) with device-specific handlers
65
- **Device Handlers**: Vendor-specific customizations for Cisco, Juniper, Huawei, etc.
66
- **XML Utilities**: XML parsing and manipulation tools for NETCONF payloads
67

68
This design enables device-agnostic NETCONF operations while supporting vendor-specific optimizations and features.
69

70
## Capabilities
71

72
### Connection Management
73

74
Functions for establishing and managing NETCONF sessions over various transport protocols, with support for device-specific parameters and authentication methods.
75

76
```python { .api }
77
def connect(host=None, port=830, username=None, password=None, **kwargs): ...
78
def connect_ssh(host, port=830, username=None, password=None, **kwargs): ...
79
def connect_tls(host, port=6513, **kwargs): ...
80
def connect_uds(path, **kwargs): ...
81
```
82

83
[Connection Management](./connection-management.md)
84

85
### NETCONF Operations
86

87
Complete implementation of NETCONF standard operations for configuration management, datastore operations, and session control with vendor-specific extensions.
88

89
```python { .api }
90
def get_config(source, filter=None, **kwargs): ...
91
def edit_config(target, config, **kwargs): ...
92
def get(filter=None, **kwargs): ...
93
def commit(**kwargs): ...
94
def lock(target): ...
95
def unlock(target): ...
96
```
97

98
[NETCONF Operations](./netconf-operations.md)
99

100
### Transport Layer
101

102
Low-level transport implementations supporting SSH, TLS, and Unix domain sockets with connection multiplexing and session management.
103

104
```python { .api }
105
class SSHSession: ...
106
class TLSSession: ...
107
class UnixSocketSession: ...
108
class LibSSHSession: ...
109
```
110

111
[Transport Layer](./transport-layer.md)
112

113
### Device Support
114

115
Device-specific handlers providing optimizations and vendor-specific functionality for major network equipment manufacturers.
116

117
```python { .api }
118
def make_device_handler(device_params, ignore_errors=None): ...
119
class JunosDeviceHandler: ...
120
class NexusDeviceHandler: ...
121
class IosxrDeviceHandler: ...
122
```
123

124
[Device Support](./device-support.md)
125

126
### XML Utilities
127

128
Tools for creating, parsing, and manipulating XML documents and NETCONF payloads with namespace support.
129

130
```python { .api }
131
def new_ele(tag, attrs=None, **extra): ...
132
def sub_ele(parent, tag, attrs=None, **extra): ...
133
def parse_root(raw): ...
134
def to_xml(ele, encoding="UTF-8"): ...
135
```
136

137
[XML Utilities](./xml-utilities.md)
138

139
## Common Types
140

141
```python { .api }
142
class NCClientError(Exception):
143
    """Base exception class for all NCClient errors."""
144

145
class RPCError(NCClientError):
146
    """NETCONF RPC error response."""
147

148
class OperationError(NCClientError):
149
    """Operation execution error."""
150

151
class TransportError(NCClientError):
152
    """Transport layer error."""
153

154
class Capabilities:
155
    """Represents the set of capabilities available to a NETCONF client or server."""
156
    
157
    def add(self, uri): ...
158
    def remove(self, uri): ...
159
    def __contains__(self, key): ...
160
    def __iter__(self): ...
161

162
class Capability:
163
    """Represents a single NETCONF capability."""
164
    
165
    def __init__(self, namespace_uri, parameters=None): ...
166
    @classmethod
167
    def from_uri(cls, uri): ...
168
```