README

   1 netifaces 0.4
   2 =============
   3
   4 1. What is this?
   5 ----------------
   6
   7 It's been annoying me for some time that there's no easy way to get the
   8 address(es) of the machine's network interfaces from Python.  There is
   9 a good reason for this difficulty, which is that it is virtually impossible
  10 to do so in a portable manner.  However, it seems to me that there should
  11 be a package you can easy_install that will take care of working out the
  12 details of doing so on the machine you're using, then you can get on with
  13 writing Python code without concerning yourself with the nitty gritty of
  14 system-dependent low-level networking APIs.
  15
  16 This package attempts to solve that problem.
  17
  18 2. How do I use it?
  19 -------------------
  20
  21 First you need to install it, which you can do by typing
  22
  23   tar xvzf netifaces-0.4.tar.gz
  24   cd netifaces-0.4
  25   python setup.py install
  26
  27 Once that's done, you'll need to start Python and do something like the
  28 following:
  29
  30   >>> import netifaces
  31
  32 Then if you enter
  33
  34   >>> netifaces.interfaces()
  35   ['lo0', 'gif0', 'stf0', 'en0', 'en1', 'fw0']
  36
  37 you'll see the list of interface identifiers for your machine.
  38
  39 You can ask for the addresses of a particular interface by doing
  40
  41   >>> netifaces.ifaddresses('lo0')
  42   {18: [{'addr': ''}], 2: [{'peer': '127.0.0.1', 'netmask': '255.0.0.0', 'addr': '127.0.0.1'}], 30: [{'peer': '::1', 'netmask': 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff', 'addr': '::1'}, {'peer': '', 'netmask': 'ffff:ffff:ffff:ffff::', 'addr': 'fe80::1%lo0'}]}
  43
  44 Hmmmm.  That result looks a bit cryptic; let's break it apart and explain
  45 what each piece means.  It returned a dictionary, so let's look there first:
  46
  47   { 18: [...], 2: [...], 30: [...] }
  48
  49 Each of the numbers refers to a particular address family.  In this case, we
  50 have three address families listed; on my system, 18 is AF_LINK (which means
  51 the link layer interface, e.g. Ethernet), 2 is AF_INET (normal Internet
  52 addresses), and 30 is AF_INET6 (IPv6).
  53
  54 But wait!  Don't use these numbers in your code.  The numeric values here are
  55 system dependent; fortunately, I thought of that when writing netifaces, so
  56 the module declares a range of values that you might need.  e.g.
  57
  58   >>> netifaces.AF_LINK
  59   18
  60
  61 Again, on your system, the number may be different.
  62
  63 So, what we've established is that the dictionary that's returned has one
  64 entry for each address family for which this interface has an address.  Let's
  65 take a look at the AF_INET addresses now:
  66
  67   >>> addrs = netifaces.ifaddresses('lo0')
  68   >>> addrs[netifaces.AF_INET]
  69   [{'peer': '127.0.0.1', 'netmask': '255.0.0.0', 'addr': '127.0.0.1'}]
  70
  71 You might be wondering why this value is a list.  The reason is that it's
  72 possible for an interface to have more than one address, even within the
  73 same family.  I'll say that again: *you can have more than one address of
  74 the same type associated with each interface*.
  75
  76 *Asking for "the" address of a particular interface doesn't make sense.*
  77
  78 Right, so, we can see that this particular interface only has one address,
  79 and, because it's a loopback interface, it's point-to-point and therefore
  80 has a *peer* address rather than a broadcast address.
  81
  82 Let's look at a more interesting interface.
  83
  84   >>> addrs = netifaces.ifaddresses('en0')
  85   >>> addrs[netifaces.AF_INET]
  86   [{'broadcast': '10.15.255.255', 'netmask': '255.240.0.0', 'addr': '10.0.1.4'}, {'broadcast': '192.168.0.255', 'addr': '192.168.0.47'}]
  87
  88 This interface has two addresses (see, I told you...)  Both of them are
  89 regular IPv4 addresses, although in one case the netmask has been changed
  90 from its default.  The netmask *may not* appear on your system if it's set
  91 to the default for the address range.
  92
  93 Because this interface isn't point-to-point, it also has broadcast addresses.
  94
  95 Now, say we want, instead of the IP addresses, to get the MAC address; that
  96 is, the hardware address of the Ethernet adapter running this interface.  We
  97 can do
  98
  99   >>> addrs[netifaces.AF_LINK]
 100   [{'addr': '00:12:34:56:78:9a'}]
 101
 102 Note that this may not be available on platforms without getifaddrs(), unless
 103 they happen to implement SIOCGIFHWADDR.  Note also that you just get the
 104 address; it's unlikely that you'll see anything else with an AF_LINK address.
 105 Oh, and don't assume that all AF_LINK addresses are Ethernet; you might, for
 106 instance, be on a Mac, in which case:
 107
 108   >>> addrs = netifaces.ifaddresses('fw0')
 109   >>> addrs[netifaces.AF_LINK]
 110   [{'addr': '00:12:34:56:78:9a:bc:de'}]
 111
 112 No, that isn't an exceptionally long Ethernet MAC address---it's a FireWire
 113 address.
 114
 115 3. This is great!  What platforms does it work on?
 116 --------------------------------------------------
 117
 118 Well, see, here's the thing.  It's been tested on Mac OS X, and it seems to
 119 work.  (OS X helpfully has some of the SIOCGIFxxx ioctl()s, which means that
 120 most of those have been tested too, the only glaring exception being the
 121 SIOCGIFHWADDR ioctl(), which OS X just doesn't have.)
 122
 123 It should probably work on most of the other UNIX-like systems with relatively
 124 minor changes.  If you do have to change something, send it to me at
 125 <alastair AT alastairs-place.net> and I'll see if I can merge it in.
 126
 127 It also works just fine on Windows, using the GetAdaptersInfo() function.
 128 Note, though, that on Windows it isn't possible (yet) to retrieve IPv6
 129 addresses.  I don't use Windows at the moment, so this isn't a priority for
 130 me.  If you know how to fix it, drop me a line and I'll consider adding any
 131 necessary code.
 132
 133 4. What license is this under?
 134 ------------------------------
 135
 136 It's an MIT-style license.  Here goes:
 137
 138 Copyright (c) 2007, 2008 Alastair Houghton
 139
 140 Permission is hereby granted, free of charge, to any person obtaining a copy
 141 of this software and associated documentation files (the "Software"), to deal
 142 in the Software without restriction, including without limitation the rights
 143 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 144 copies of the Software, and to permit persons to whom the Software is
 145 furnished to do so, subject to the following conditions:
 146
 147 The above copyright notice and this permission notice shall be included in all
 148 copies or substantial portions of the Software.
 149
 150 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 151 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 152 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 153 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 154 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 155 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 156 SOFTWARE.