1*******************
2Netlink Core Module
3*******************
4
5.. py:module:: netlink.core
6
7Examples::
8
9	import netlink.core as netlink
10
11===============
12Object
13===============
14
15.. py:class:: Object
16
17   Base class for all classes representing a cacheable object
18
19   Example::
20	obj = netlink.Object("route/link", "link")
21
22   .. py:method:: clone
23
24      Clone the object and return a duplicate (used for COW)
25
26   .. py:method:: dump([params=None])
27
28      Call the libnl internal dump mechanism to dump the object
29      according to the parameters specified.
30
31   .. py:method:: apply(attr, val)
32
33      Applies a attribute=value pair and modifies the object accordingly.
34      Example::
35	obj.apply("mtu", 1200)      # Sets attribute mtu to 1200 (link obj)
36
37      :raises: KeyError if attribute is unknown
38      :raises: ImmutableError if attribute is not mutable
39
40   .. py:attribute:: mark
41
42      True if the object is marked, otherwise False.
43
44   .. py:attribute:: shared
45
46      True if the object is used by multiple parties, otherwise False.
47
48   .. py:attribute:: refcnt
49
50      Number of users sharing a reference to the object
51      :rtype: int
52
53   .. py:attribute:: attrs
54
55      List of attributes
56
57      :rtype: list of strings
58
59===============
60Cache
61===============
62
63.. py:class:: Cache
64
65   Base class for all cache implementations.
66
67   A cache is a collection of cacheable objects which is typically used
68   by netlink protocols which handle any kind of object, e.g. network
69   links, network addresses, neighbours, ...
70
71   .. py:method:: subset(filter)
72
73      Returns a new cache containing the subset which matches the
74      provided filter.
75
76      :raises: ValueError if no filter is specified
77      :rtype: :py:class:`Cache`
78
79   .. py:method:: dump([params=None, filter=None])
80
81      Calls the libnl internal dump mechanism to dump the cache according
82      to the parameters and filter specified.
83
84   .. py:method:: clear()
85
86      Remove and possibly destroy all objects in the cache
87
88   .. py:method:: refill([socket=None]) -> :py:class:`Cache`
89
90      Clears and refills the cache with the content which is provided by
91      the kernel, e.g. for a link cache this would mean refilling the
92      cache with all configured network links.
93
94   .. py:method:: provide()
95
96      Caches which have been "provided" are made available to other users
97      (of the same application context) which "require" it. F.e. a link
98      cache is generally provided to allow others to translate interface
99      indexes to link names
100
101
102   .. py:method:: unprovide()
103
104      No longer make the cache available to others. If the cache has been
105      handed out already, that reference will still be valid.
106
107===============
108AbstractAddress
109===============
110
111.. py:class:: AbstractAddress
112
113   Abstract representation of an address. This class is not to be mistaken
114   with :py:class:`route.Address` which represents a configured network
115   address. This class represents the actual address in a family independent
116   way::
117
118	addr = netlink.AbstractAddress('127.0.0.1/8')
119	print addr               # => '127.0.0.1/8'
120	print addr.prefixlen     # => '8'
121	print addr.family        # => 'inet'
122	print len(addr)          # => '4' (32bit ipv4 address)
123
124	a = netlink.AbstractAddress('10.0.0.1/24')
125	b = netlink.AbstractAddress('10.0.0.2/24')
126	print a == b             # => False
127
128   .. py:attribute:: prefixlen
129
130      Length of prefix in number of bits.
131
132      :rtype: int
133
134   .. py:attribute:: family
135
136      The family type of the address. Setting the address family can be
137      done with a string or a :py:class:`AddressFamily` object.
138
139      :rtype: :py:class:`AddressFamily`
140
141   .. py:attribute:: shared
142
143      True if address is in use by multiple callers, otherwise False
144
145      :rtype: bool
146
147===============
148AddressFamily
149===============
150
151.. py:class:: AddressFamily
152
153   Address family representation::
154
155	af = netlink.AddressFamily('inet6')
156	# raises:
157	#   - ValueError if family name is not known
158	#   - TypeError if invalid type is specified for family
159
160	print af        # => 'inet6' (string representation)
161	print int(af)   # => 10 (numeric representation)
162	print repr(af)  # => AddressFamily('inet6')
163
164===============
165Exceptions
166===============
167
168.. py:exception:: NetlinkError
169
170   Generic exception raised by netlink modules.
171
172.. py:exception:: KernelError
173
174   Raised if an error occured while communicating with the kernel. Contains
175   the error code returning which is automatically included in the error
176   message.
177
178.. py:exception:: ImmutableError
179
180   Raised if an attribute is modified which is marked immutable.
181
182===============
183Socket
184===============
185
186.. py:class:: Socket
187
188   Netlink socket.
189
190   Note: It is not required to manually create and connect netlink sockets
191   when using caches. The caches will automatically lookup or create a
192   socket as needed.
193
194   .. py:attribute:: local_port
195
196      Local port (address) of netlink socket
197
198   .. py:attribute:: peer_port
199
200      Peer port (remote address) of netlink socket. If set, all messages
201      will be sent to that peer.
202
203   .. py:method:: connect(proto)
204
205      Connect the netlink socket using the specified netlink protocol::
206	sock.connect(netlink.NETLINK_ROUTE)
207
208   .. py:method:: disconnect()
209
210      Disconnect the socket
211
212   .. py:method:: set_bufsize(rx, tx)
213
214      Sets the size of the socket buffer
215
216