wireless_tools/iftab.5

   1 .\" Jean II - HPL - 2004-2007
   2 .\" iftab.5
   3 .\"
   4 .TH IFTAB 5 "26 February 2007" "wireless-tools" "Linux Programmer's Manual"
   5 .\"
   6 .\" NAME part
   7 .\"
   8 .SH NAME
   9 iftab \- static information about the network interfaces
  10 .\"
  11 .\" DESCRIPTION part
  12 .\"
  13 .SH DESCRIPTION
  14 The file
  15 .B /etc/iftab
  16 contains descriptive information about the various network interfaces.
  17 .B iftab
  18 is only used by the program
  19 .IR ifrename (8)
  20 to assign a consistent network interface name to each network interface.
  21 .PP
  22 .B /etc/iftab
  23 defines a set of
  24 .IR mappings .
  25 Each mapping contains an interface name and a set of selectors. The
  26 selectors allow
  27 .B ifrename
  28 to identify each network interface on the system. If a network
  29 interface matches all descriptors of a mapping,
  30 .B ifrename
  31 attempt to change the name of the interface to the interface name
  32 given by the mapping.
  33 .\"
  34 .\" MAPPINGS part
  35 .\"
  36 .SH MAPPINGS
  37 Each mapping is described on a separate line, it starts with an
  38 .IR "interface name" ,
  39 and contains a set of
  40 .IR descriptors ,
  41 separated by space or tabs.
  42 .PP
  43 The relationship between descriptors of a mapping is a
  44 .IR "logical and" .
  45 A mapping matches a network interface only is all the descriptors
  46 match. If a network interface doesn't support a specific descriptor,
  47 it won't match any mappings using this descriptor.
  48 .PP
  49 If you want to use alternate descriptors for an interface name
  50 (logical or), specify two different mappings with the same interface
  51 name (one on each line).
  52 .B Ifrename
  53 always use the first matching mapping starting from the
  54 .I end
  55 of
  56 .BR iftab ,
  57 therefore more restrictive mapping should be specified last.
  58 .\"
  59 .\" INTERFACE NAME part
  60 .\"
  61 .SH INTERFACE NAME
  62 The first part of each mapping is an interface name. If a network
  63 interface matches all descriptors of a mapping,
  64 .B ifrename
  65 attempt to change the name of the interface to the interface name
  66 given by the mapping.
  67 .PP
  68 The interface name of a mapping is either a plain interface name (such as
  69 .IR eth2 " or " wlan1 )
  70 or a interface name pattern containing a single wildcard (such as
  71 .IR eth* " or " wlan* ).
  72 In case of wildcard, the kernel replace the '*' with the lowest
  73 available integer making this interface name unique. Note that
  74 wildcard is only supported for kernel 2.6.1 and 2.4.30 and later.
  75 .PP
  76 It is discouraged to try to map interfaces to default interfaces names
  77 such as
  78 .IR eth0 ", " wlan0 " or " ppp0 .
  79 The kernel use those as the default name for any new interface,
  80 therefore most likely an interface will already use this name and
  81 prevent ifrename to use it. Even if you use takeover, the interface
  82 may already be up in some cases. Not using those name will allow you
  83 to immediately spot unconfigured or new interfaces.
  84 .br
  85 Good names are either totally unique and meaningfull,
  86 such as
  87 .IR mydsl " or " privatehub ,
  88 or use larger integer, such as
  89 .IR eth5 " or " wlan5 .
  90 The second type is usually easier to integrate in various network utilities.
  91 .\"
  92 .\" DESCRIPTORS part
  93 .\"
  94 .SH DESCRIPTORS
  95 Each descriptor is composed of a descriptor name and descriptor
  96 value. Descriptors specify a static attribute of a network interface,
  97 the goal is to uniquely identify each piece of hardware.
  98 .PP
  99 Most users will only use the
 100 .B mac
 101 selector despite its potential problems, other selectors are for more
 102 specialised setup. Most selectors accept a '*' in the selector value
 103 for wilcard matching, and most selectors are case insensitive.
 104 .TP
 105 .BI mac " mac address"
 106 Matches the MAC Address of the interface with the specified MAC
 107 address. The MAC address of the interface can be shown using
 108 .IR ifconfig (8)
 109 or
 110 .IR ip (8).
 111 .br
 112 This is the most common selector, as most interfaces have a unique MAC
 113 address allowing to identify network interfaces without ambiguity.
 114 However, some interfaces don't have a valid MAC address until they are
 115 brought up, in such case using this selector is tricky or impossible.
 116 .TP
 117 .BI arp " arp type"
 118 Matches the ARP Type (also called Link Type) of the interface with the
 119 specified ARP type as a number. The ARP Type of the interface can be
 120 shown using
 121 .IR ifconfig (8)
 122 or
 123 .IR ip (8),
 124 the
 125 .B link/ether
 126 type correspond to
 127 .B 1
 128 and the
 129 .B link/ieee802.11
 130 type correspond to
 131 .BR 801 .
 132 .br
 133 This selector is useful when a driver create multiple network
 134 interfaces for a single network card.
 135 .TP
 136 .BI driver " driver name"
 137 Matches the Driver Name of the interface with the specified driver
 138 name. The Driver Name of the interface can be shown using
 139 .IR "ethtool -i" (8).
 140 .TP
 141 .BI businfo " bus information"
 142 Matches the Bus Information of the interface with the specified bus
 143 information. The Bus Information of the interface can be shown using
 144 .IR "ethtool -i" (8).
 145 .TP
 146 .BI firmware " firmware revision"
 147 Matches the Firmware Revision of the interface with the firmware
 148 revision information. The Firmware Revision of the interface can be
 149 shown using
 150 .IR "ethtool -i" (8).
 151 .TP
 152 .BI baseaddress " base address"
 153 Matches the Base Address of the interface with the specified base
 154 address. The Base Address of the interface can be shown using
 155 .IR ifconfig (8).
 156 .br
 157 Because most cards use dynamic allocation of the Base Address, this
 158 selector is only useful for ISA and EISA cards.
 159 .TP
 160 .BI irq " irq line"
 161 Matches the IRQ Line (interrupt) of the interface with the specified
 162 IRQ line. The IRQ Line of the interface can be shown using
 163 .IR ifconfig (8).
 164 .br
 165 Because there are IRQ Lines may be shared, this selector is usually
 166 not sufficient to uniquely identify an interface.
 167 .TP
 168 .BI iwproto " wireless protocol"
 169 Matches the Wireless Protocol of the interface with the specified
 170 wireless protocol. The Wireless Protocol of the interface can be shown
 171 using
 172 .IR iwconfig (8)
 173 or
 174 .IR iwgetid (8).
 175 .br
 176 This selector is only supported on wireless interfaces and is not
 177 sufficient to uniquely identify an interface.
 178 .TP
 179 .BI pcmciaslot " pcmcia slot"
 180 Matches the Pcmcia Socket number of the interface with the specified
 181 slot number. Pcmcia Socket number of the interface can be shown
 182 using
 183 .IR "cardctl ident" (8).
 184 .br
 185 This selector is usually only supported on 16 bits cards, for 32 bits
 186 cards it is advised to use the selector
 187 .BR businfo .
 188 .TP
 189 .BI prevname " previous interface name"
 190 Matches the name of the interface prior to renaming with the specified
 191 oldname.
 192 .br
 193 This selector should be avoided as the previous interface name may
 194 vary depending on various condition. A system/kernel/driver update may
 195 change the original name. Then, ifrename or another tool may rename it
 196 prior to the execution of this selector.
 197 .TP
 198 .BI SYSFS{ filename } " value"
 199 Matches the content the sysfs attribute given by filename to the
 200 specified value. For symlinks and parents directories, match the
 201 actual directory name of the sysfs attribute given by filename to the
 202 specified value.
 203 .br
 204 A list of the most useful sysfs attributes is given in the next
 205 section.
 206 .\"
 207 .\" SYSFS DESCRIPTORS part
 208 .\"
 209 .SH SYSFS DESCRIPTORS
 210 Sysfs attributes for a specific interface are located on most systems
 211 in the directory named after that interface at
 212 .IR /sys/class/net/ .
 213 Most sysfs attribute are files, and their values can be read using
 214 .IR cat "(1) or " more (1).
 215 It is also possible to match attributes in subdirectories.
 216 .PP
 217 Some sysfs attributes are symlinks, pointing to another directory in
 218 sysfs. If the attribute filename is a symlink the sysfs attribute
 219 resolves to the name of the directory pointed by the symlink using
 220 .IR readlink (1).
 221 The location is a directory in the sysfs tree is also important. If
 222 the attribute filename ends with
 223 .IR /.. ,
 224 the sysfs attribute resolves to the real name of the parent directory
 225 using
 226 .IR pwd (1).
 227 .PP
 228 The sysfs filesystem is only supported with 2.6.X kernel and need to
 229 be mounted (usually in
 230 .IR /sys ).
 231 sysfs selectors are not as efficient as other selectors, therefore
 232 they should be avoided for maximum performance.
 233 .PP
 234 These are common sysfs attributes and their corresponding ifrename
 235 descriptors.
 236 .TP
 237 .BI SYSFS{address} " value"
 238 Same as the
 239 .B mac
 240 descriptor.
 241 .TP
 242 .BI SYSFS{type} " value"
 243 Same as the
 244 .B arp
 245 descriptor.
 246 .TP
 247 .BI SYSFS{device} " value"
 248 Valid only up to kernel 2.6.20. Same as the
 249 .B businfo
 250 descriptor.
 251 .TP
 252 .BI SYSFS{..} " value"
 253 Valid only from kernel 2.6.21. Same as the
 254 .B businfo
 255 descriptor.
 256 .TP
 257 .BI SYSFS{device/driver} " value"
 258 Valid only up to kernel 2.6.20. Same as the
 259 .B driver
 260 descriptor.
 261 .TP
 262 .BI SYSFS{../driver} " value"
 263 Valid only from kernel 2.6.21. Same as the
 264 .B driver
 265 descriptor.
 266 .TP
 267 .BI SYSFS{device/irq} " value"
 268 Valid only up to kernel 2.6.20. Same as the
 269 .B irq
 270 descriptor.
 271 .TP
 272 .BI SYSFS{../irq} " value"
 273 Valid only from kernel 2.6.21. Same as the
 274 .B irq
 275 descriptor.
 276 .\"
 277 .\" EXAMPLES part
 278 .\"
 279 .SH EXAMPLES
 280 # This is a comment
 281 .br
 282 eth2            mac 08:00:09:DE:82:0E
 283 .br
 284 eth3            driver wavelan interrupt 15 baseaddress 0x390
 285 .br
 286 eth4            driver pcnet32 businfo 0000:02:05.0
 287 .br
 288 air*            mac 00:07:0E:* arp 1
 289 .br
 290 myvpn   SYSFS{address} 00:10:83:* SYSFS{type} 1
 291 .br
 292 bcm*            SYSFS{device} 0000:03:00.0 SYSFS{device/driver} bcm43xx
 293 .br
 294 bcm*            SYSFS{..} 0000:03:00.0 SYSFS{../driver} bcm43xx
 295 .\"
 296 .\" AUTHOR part
 297 .\"
 298 .SH AUTHOR
 299 Jean Tourrilhes \- jt@hpl.hp.com
 300 .\"
 301 .\" FILES part
 302 .\"
 303 .SH FILES
 304 .I /etc/iftab
 305 .\"
 306 .\" SEE ALSO part
 307 .\"
 308 .SH SEE ALSO
 309 .BR ifrename (8),
 310 .BR ifconfig (8),
 311 .BR ip (8),
 312 .BR ethtool (8),
 313 .BR iwconfig (8).