Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 1 | .. _ipaddress-howto: |
| 2 | |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 3 | *************************************** |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 4 | An introduction to the ipaddress module |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 5 | *************************************** |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 6 | |
| 7 | :author: Peter Moody |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 8 | :author: Nick Coghlan |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 9 | |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 10 | .. topic:: Overview |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 11 | |
Nick Coghlan | ccd712a | 2012-07-07 22:53:46 +1000 | [diff] [blame] | 12 | This document aims to provide a gentle introduction to the |
| 13 | :mod:`ipaddress` module. It is aimed primarily at users that aren't |
| 14 | already familiar with IP networking terminology, but may also be useful |
| 15 | to network engineers wanting an overview of how :mod:`ipaddress` |
| 16 | represents IP network addressing concepts. |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 17 | |
| 18 | |
| 19 | Creating Address/Network/Interface objects |
| 20 | ========================================== |
| 21 | |
Eli Bendersky | dfd72bb | 2012-07-31 17:25:33 +0300 | [diff] [blame] | 22 | Since :mod:`ipaddress` is a module for inspecting and manipulating IP addresses, |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 23 | the first thing you'll want to do is create some objects. You can use |
| 24 | :mod:`ipaddress` to create objects from strings and integers. |
| 25 | |
| 26 | |
| 27 | A Note on IP Versions |
| 28 | --------------------- |
| 29 | |
| 30 | For readers that aren't particularly familiar with IP addressing, it's |
| 31 | important to know that the Internet Protocol is currently in the process |
| 32 | of moving from version 4 of the protocol to version 6. This transition is |
| 33 | occurring largely because version 4 of the protocol doesn't provide enough |
| 34 | addresses to handle the needs of the whole world, especially given the |
| 35 | increasing number of devices with direct connections to the internet. |
| 36 | |
| 37 | Explaining the details of the differences between the two versions of the |
| 38 | protocol is beyond the scope of this introduction, but readers need to at |
| 39 | least be aware that these two versions exist, and it will sometimes be |
| 40 | necessary to force the use of one version or the other. |
| 41 | |
| 42 | |
| 43 | IP Host Addresses |
| 44 | ----------------- |
| 45 | |
| 46 | Addresses, often referred to as "host addresses" are the most basic unit |
| 47 | when working with IP addressing. The simplest way to create addresses is |
Nick Coghlan | ccd712a | 2012-07-07 22:53:46 +1000 | [diff] [blame] | 48 | to use the :func:`ipaddress.ip_address` factory function, which automatically |
| 49 | determines whether to create an IPv4 or IPv6 address based on the passed in |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 50 | value: |
| 51 | |
| 52 | .. testsetup:: |
| 53 | >>> import ipaddress |
| 54 | |
| 55 | :: |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 56 | |
| 57 | >>> ipaddress.ip_address('192.0.2.1') |
| 58 | IPv4Address('192.0.2.1') |
| 59 | >>> ipaddress.ip_address('2001:DB8::1') |
| 60 | IPv6Address('2001:db8::1') |
| 61 | |
| 62 | Addresses can also be created directly from integers. Values that will |
| 63 | fit within 32 bits are assumed to be IPv4 addresses:: |
| 64 | |
| 65 | >>> ipaddress.ip_address(3221225985) |
| 66 | IPv4Address('192.0.2.1') |
| 67 | >>> ipaddress.ip_address(42540766411282592856903984951653826561) |
| 68 | IPv6Address('2001:db8::1') |
| 69 | |
| 70 | To force the use of IPv4 or IPv6 addresses, the relevant classes can be |
| 71 | invoked directly. This is particularly useful to force creation of IPv6 |
| 72 | addresses for small integers:: |
| 73 | |
| 74 | >>> ipaddress.ip_address(1) |
| 75 | IPv4Address('0.0.0.1') |
| 76 | >>> ipaddress.IPv4Address(1) |
| 77 | IPv4Address('0.0.0.1') |
| 78 | >>> ipaddress.IPv6Address(1) |
| 79 | IPv6Address('::1') |
| 80 | |
| 81 | |
| 82 | Defining Networks |
| 83 | ----------------- |
| 84 | |
| 85 | Host addresses are usually grouped together into IP networks, so |
| 86 | :mod:`ipaddress` provides a way to create, inspect and manipulate network |
| 87 | definitions. IP network objects are constructed from strings that define the |
| 88 | range of host addresses that are part of that network. The simplest form |
| 89 | for that information is a "network address/network prefix" pair, where the |
| 90 | prefix defines the number of leading bits that are compared to determine |
| 91 | whether or not an address is part of the network and the network address |
| 92 | defines the expected value of those bits. |
| 93 | |
| 94 | As for addresses, a factory function is provided that determines the correct |
| 95 | IP version automatically:: |
| 96 | |
| 97 | >>> ipaddress.ip_network('192.0.2.0/24') |
| 98 | IPv4Network('192.0.2.0/24') |
| 99 | >>> ipaddress.ip_network('2001:db8::0/96') |
| 100 | IPv6Network('2001:db8::/96') |
| 101 | |
| 102 | Network objects cannot have any host bits set. The practical effect of this |
| 103 | is that ``192.0.2.1/24`` does not describe a network. Such definitions are |
| 104 | referred to as interface objects since the ip-on-a-network notation is |
| 105 | commonly used to describe network interfaces of a computer on a given network |
| 106 | and are described further in the next section. |
| 107 | |
| 108 | By default, attempting to create a network object with host bits set will |
| 109 | result in :exc:`ValueError` being raised. To request that the |
| 110 | additional bits instead be coerced to zero, the flag ``strict=False`` can |
| 111 | be passed to the constructor:: |
| 112 | |
| 113 | >>> ipaddress.ip_network('192.0.2.1/24') |
| 114 | Traceback (most recent call last): |
| 115 | ... |
| 116 | ValueError: 192.0.2.1/24 has host bits set |
| 117 | >>> ipaddress.ip_network('192.0.2.1/24', strict=False) |
| 118 | IPv4Network('192.0.2.0/24') |
| 119 | |
| 120 | While the string form offers significantly more flexibility, networks can |
| 121 | also be defined with integers, just like host addresses. In this case, the |
| 122 | network is considered to contain only the single address identified by the |
| 123 | integer, so the network prefix includes the entire network address:: |
| 124 | |
| 125 | >>> ipaddress.ip_network(3221225984) |
| 126 | IPv4Network('192.0.2.0/32') |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 127 | >>> ipaddress.ip_network(42540766411282592856903984951653826560) |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 128 | IPv6Network('2001:db8::/128') |
| 129 | |
Nick Coghlan | ccd712a | 2012-07-07 22:53:46 +1000 | [diff] [blame] | 130 | As with addresses, creation of a particular kind of network can be forced |
| 131 | by calling the class constructor directly instead of using the factory |
| 132 | function. |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 133 | |
| 134 | |
| 135 | Host Interfaces |
| 136 | --------------- |
| 137 | |
| 138 | As mentioned just above, if you need to describe an address on a particular |
| 139 | network, neither the address nor the network classes are sufficient. |
Nick Coghlan | ccd712a | 2012-07-07 22:53:46 +1000 | [diff] [blame] | 140 | Notation like ``192.0.2.1/24`` is commonly used by network engineers and the |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 141 | people who write tools for firewalls and routers as shorthand for "the host |
| 142 | ``192.0.2.1`` on the network ``192.0.2.0/24``", Accordingly, :mod:`ipaddress` |
| 143 | provides a set of hybrid classes that associate an address with a particular |
| 144 | network. The interface for creation is identical to that for defining network |
| 145 | objects, except that the address portion isn't constrained to being a network |
| 146 | address. |
| 147 | |
| 148 | >>> ipaddress.ip_interface('192.0.2.1/24') |
| 149 | IPv4Interface('192.0.2.1/24') |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 150 | >>> ipaddress.ip_interface('2001:db8::1/96') |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 151 | IPv6Interface('2001:db8::1/96') |
| 152 | |
| 153 | Integer inputs are accepted (as with networks), and use of a particular IP |
| 154 | version can be forced by calling the relevant constructor directly. |
| 155 | |
| 156 | |
| 157 | Inspecting Address/Network/Interface Objects |
| 158 | ============================================ |
| 159 | |
| 160 | You've gone to the trouble of creating an IPv(4|6)(Address|Network|Interface) |
| 161 | object, so you probably want to get information about it. :mod:`ipaddress` |
| 162 | tries to make doing this easy and intuitive. |
| 163 | |
| 164 | Extracting the IP version:: |
| 165 | |
| 166 | >>> addr4 = ipaddress.ip_address('192.0.2.1') |
| 167 | >>> addr6 = ipaddress.ip_address('2001:db8::1') |
| 168 | >>> addr6.version |
| 169 | 6 |
| 170 | >>> addr4.version |
| 171 | 4 |
| 172 | |
| 173 | Obtaining the network from an interface:: |
| 174 | |
| 175 | >>> host4 = ipaddress.ip_interface('192.0.2.1/24') |
| 176 | >>> host4.network |
| 177 | IPv4Network('192.0.2.0/24') |
| 178 | >>> host6 = ipaddress.ip_interface('2001:db8::1/96') |
| 179 | >>> host6.network |
| 180 | IPv6Network('2001:db8::/96') |
| 181 | |
| 182 | Finding out how many individual addresses are in a network:: |
| 183 | |
| 184 | >>> net4 = ipaddress.ip_network('192.0.2.0/24') |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 185 | >>> net4.num_addresses |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 186 | 256 |
| 187 | >>> net6 = ipaddress.ip_network('2001:db8::0/96') |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 188 | >>> net6.num_addresses |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 189 | 4294967296 |
| 190 | |
Eli Bendersky | dfd72bb | 2012-07-31 17:25:33 +0300 | [diff] [blame] | 191 | Iterating through the "usable" addresses on a network:: |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 192 | |
| 193 | >>> net4 = ipaddress.ip_network('192.0.2.0/24') |
Eli Bendersky | dfd72bb | 2012-07-31 17:25:33 +0300 | [diff] [blame] | 194 | >>> for x in net4.hosts(): |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 195 | ... print(x) # doctest: +ELLIPSIS |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 196 | 192.0.2.1 |
| 197 | 192.0.2.2 |
| 198 | 192.0.2.3 |
| 199 | 192.0.2.4 |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 200 | ... |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 201 | 192.0.2.252 |
| 202 | 192.0.2.253 |
| 203 | 192.0.2.254 |
| 204 | |
| 205 | |
| 206 | Obtaining the netmask (i.e. set bits corresponding to the network prefix) or |
| 207 | the hostmask (any bits that are not part of the netmask): |
| 208 | |
| 209 | >>> net4 = ipaddress.ip_network('192.0.2.0/24') |
| 210 | >>> net4.netmask |
| 211 | IPv4Address('255.255.255.0') |
| 212 | >>> net4.hostmask |
| 213 | IPv4Address('0.0.0.255') |
| 214 | >>> net6 = ipaddress.ip_network('2001:db8::0/96') |
| 215 | >>> net6.netmask |
| 216 | IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff::') |
| 217 | >>> net6.hostmask |
| 218 | IPv6Address('::ffff:ffff') |
| 219 | |
| 220 | |
| 221 | Exploding or compressing the address:: |
| 222 | |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 223 | >>> addr6.exploded |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 224 | '2001:0db8:0000:0000:0000:0000:0000:0001' |
Nick Coghlan | ccd712a | 2012-07-07 22:53:46 +1000 | [diff] [blame] | 225 | >>> addr6.compressed |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 226 | '2001:db8::1' |
Nick Coghlan | ccd712a | 2012-07-07 22:53:46 +1000 | [diff] [blame] | 227 | >>> net6.exploded |
| 228 | '2001:0db8:0000:0000:0000:0000:0000:0000/96' |
| 229 | >>> net6.compressed |
| 230 | '2001:db8::/96' |
| 231 | |
| 232 | While IPv4 doesn't support explosion or compression, the associated objects |
| 233 | still provide the relevant properties so that version neutral code can |
| 234 | easily ensure the most concise or most verbose form is used for IPv6 |
| 235 | addresses while still correctly handling IPv4 addresses. |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 236 | |
| 237 | |
| 238 | Networks as lists of Addresses |
| 239 | ============================== |
| 240 | |
| 241 | It's sometimes useful to treat networks as lists. This means it is possible |
| 242 | to index them like this:: |
| 243 | |
| 244 | >>> net4[1] |
| 245 | IPv4Address('192.0.2.1') |
| 246 | >>> net4[-1] |
| 247 | IPv4Address('192.0.2.255') |
| 248 | >>> net6[1] |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 249 | IPv6Address('2001:db8::1') |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 250 | >>> net6[-1] |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 251 | IPv6Address('2001:db8::ffff:ffff') |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 252 | |
| 253 | |
| 254 | It also means that network objects lend themselves to using the list |
| 255 | membership test syntax like this:: |
| 256 | |
| 257 | if address in network: |
| 258 | # do something |
| 259 | |
| 260 | Containment testing is done efficiently based on the network prefix:: |
| 261 | |
| 262 | >>> addr4 = ipaddress.ip_address('192.0.2.1') |
| 263 | >>> addr4 in ipaddress.ip_network('192.0.2.0/24') |
| 264 | True |
| 265 | >>> addr4 in ipaddress.ip_network('192.0.3.0/24') |
| 266 | False |
| 267 | |
| 268 | |
| 269 | Comparisons |
| 270 | =========== |
| 271 | |
| 272 | :mod:`ipaddress` provides some simple, hopefully intuitive ways to compare |
| 273 | objects, where it makes sense:: |
| 274 | |
| 275 | >>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2') |
| 276 | True |
| 277 | |
| 278 | A :exc:`TypeError` exception is raised if you try to compare objects of |
| 279 | different versions or different types. |
| 280 | |
| 281 | |
| 282 | Using IP Addresses with other modules |
| 283 | ===================================== |
| 284 | |
| 285 | Other modules that use IP addresses (such as :mod:`socket`) usually won't |
| 286 | accept objects from this module directly. Instead, they must be coerced to |
| 287 | an integer or string that the other module will accept:: |
| 288 | |
| 289 | >>> addr4 = ipaddress.ip_address('192.0.2.1') |
| 290 | >>> str(addr4) |
| 291 | '192.0.2.1' |
| 292 | >>> int(addr4) |
| 293 | 3221225985 |
| 294 | |
| 295 | |
Nick Coghlan | b582ecc | 2012-07-07 22:15:22 +1000 | [diff] [blame] | 296 | Getting more detail when instance creation fails |
| 297 | ================================================ |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 298 | |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 299 | When creating address/network/interface objects using the version-agnostic |
Nick Coghlan | b582ecc | 2012-07-07 22:15:22 +1000 | [diff] [blame] | 300 | factory functions, any errors will be reported as :exc:`ValueError` with |
| 301 | a generic error message that simply says the passed in value was not |
Eli Bendersky | dfd72bb | 2012-07-31 17:25:33 +0300 | [diff] [blame] | 302 | recognized as an object of that type. The lack of a specific error is |
Nick Coghlan | b582ecc | 2012-07-07 22:15:22 +1000 | [diff] [blame] | 303 | because it's necessary to know whether the value is *supposed* to be IPv4 |
| 304 | or IPv6 in order to provide more detail on why it has been rejected. |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 305 | |
Nick Coghlan | b582ecc | 2012-07-07 22:15:22 +1000 | [diff] [blame] | 306 | To support use cases where it is useful to have access to this additional |
| 307 | detail, the individual class constructors actually raise the |
| 308 | :exc:`ValueError` subclasses :exc:`ipaddress.AddressValueError` and |
| 309 | :exc:`ipaddress.NetmaskValueError` to indicate exactly which part of |
| 310 | the definition failed to parse correctly. |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 311 | |
Nick Coghlan | b582ecc | 2012-07-07 22:15:22 +1000 | [diff] [blame] | 312 | The error messages are significantly more detailed when using the |
| 313 | class constructors directly. For example:: |
| 314 | |
| 315 | >>> ipaddress.ip_address("192.168.0.256") |
| 316 | Traceback (most recent call last): |
| 317 | ... |
| 318 | ValueError: '192.168.0.256' does not appear to be an IPv4 or IPv6 address |
| 319 | >>> ipaddress.IPv4Address("192.168.0.256") |
| 320 | Traceback (most recent call last): |
| 321 | ... |
| 322 | ipaddress.AddressValueError: Octet 256 (> 255) not permitted in '192.168.0.256' |
| 323 | |
| 324 | >>> ipaddress.ip_network("192.168.0.1/64") |
| 325 | Traceback (most recent call last): |
| 326 | ... |
| 327 | ValueError: '192.168.0.1/64' does not appear to be an IPv4 or IPv6 network |
| 328 | >>> ipaddress.IPv4Network("192.168.0.1/64") |
| 329 | Traceback (most recent call last): |
| 330 | ... |
| 331 | ipaddress.NetmaskValueError: '64' is not a valid netmask |
| 332 | |
| 333 | However, both of the module specific exceptions have :exc:`ValueError` as their |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 334 | parent class, so if you're not concerned with the particular type of error, |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 335 | you can still write code like the following:: |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 336 | |
| 337 | try: |
Nick Coghlan | b582ecc | 2012-07-07 22:15:22 +1000 | [diff] [blame] | 338 | network = ipaddress.IPv4Network(address) |
Nick Coghlan | 53c9200 | 2012-05-27 01:53:33 +1000 | [diff] [blame] | 339 | except ValueError: |
Nick Coghlan | b582ecc | 2012-07-07 22:15:22 +1000 | [diff] [blame] | 340 | print('address/netmask is invalid for IPv4:', address) |
| 341 | |