wireless_tools/ifrename.8

   1 .\" Jean II - HPL - 2004-2007
   2 .\" ifrename.8
   3 .\"
   4 .TH IFRENAME 8 "26 February 2007" "wireless-tools" "Linux Programmer's Manual"
   5 .\"
   6 .\" NAME part
   7 .\"
   8 .SH NAME
   9 ifrename \- rename network interfaces based on various static criteria
  10 .\"
  11 .\" SYNOPSIS part
  12 .\"
  13 .SH SYNOPSIS
  14 .B "ifrename [-c configfile] [-p] [-d] [-u] [-v] [-V] [-D] [-C]"
  15 .br
  16 .B "ifrename [-c configfile] [-i interface] [-n newname]"
  17 .\"
  18 .\" DESCRIPTION part
  19 .\"
  20 .SH DESCRIPTION
  21 .B Ifrename
  22 is a tool allowing you to assign a consistent name to each of your
  23 network interface.
  24 .PP
  25 By default, interface names are dynamic, and each network interface is
  26 assigned the first available name
  27 .RI ( eth0 ", " eth1 "...)."
  28 The order network interfaces are created may vary. For built-in
  29 interfaces, the kernel boot time enumeration may vary. For removable
  30 interface, the user may plug them in any order.
  31 .PP
  32 .B Ifrename
  33 allow the user to decide what name a network interface will have.
  34 .B Ifrename
  35 can use a variety of
  36 .I selectors
  37 to specify how interface names match the network interfaces on the
  38 system, the most common selector is the interface
  39 .IR "MAC address" .
  40 .PP
  41 .B Ifrename
  42 must be run before interfaces are brought up, which is why it's mostly
  43 useful in various scripts (init, hotplug) but is seldom used directly
  44 by the user. By default,
  45 .B ifrename
  46 renames all present system interfaces using mappings defined in
  47 .IR /etc/iftab .
  48 .\"
  49 .\" PARAMETER part
  50 .\"
  51 .SH PARAMETERS
  52 .TP
  53 .BI "-c " configfile
  54 Set the configuration file to be used (by default
  55 .IR /etc/iftab ).
  56 The configuration file define the mapping between selectors and
  57 interface names, and is described in
  58 .IR iftab (5).
  59 .br
  60 If
  61 .I configfile
  62 is "-", the configuration is read from stdin.
  63 .TP
  64 .B -p
  65 Probe (load) kernel modules before renaming interfaces. By default
  66 .B ifrename
  67 only check interfaces already loaded, and doesn't auto-load the
  68 required kernel modules. This option enables smooth integration with
  69 system not loading modules before calling
  70 .BR ifrename .
  71 .TP
  72 .B -d
  73 Enable various
  74 .B Debian
  75 specific hacks. Combined with
  76 .BR -p ,
  77 only modules for interfaces specified in
  78 .I /etc/network/interface
  79 are loaded.
  80 .TP
  81 .BI "-i " interface
  82 Only rename the specified
  83 .I interface
  84 as opposed to all interfaces on the system. The new interface name is
  85 printed.
  86 .TP
  87 .BI "-n " newname
  88 When used with
  89 .IR -i ,
  90 specify the new name of the interface. The list of mappings from the
  91 configuration file is bypassed, the interface specified with
  92 .I -i
  93 is renamed directly to
  94 .IR newname .
  95 The new name may be a wildcard containing a single '*'.
  96 .br
  97 When used without
  98 .IR -i ,
  99 rename interfaces by using only mappings that would rename them to
 100 .IR newname .
 101 The new name may not be a wildcard. This use of ifrename is
 102 discouraged, because inefficient
 103 .RI ( -n " without " -i ).
 104 All the interfaces of the system need to be processed at each
 105 invocation, therefore in most case it is not faster than just letting
 106 ifrename renaming all of them (without both
 107 .IR -n " and " -i ).
 108 .TP
 109 .B -t
 110 Enable name takeover support. This allow interface name swapping
 111 between two or more interfaces.
 112 .br
 113 Takeover enable an interface to 'steal' the name of another
 114 interface. This works only with kernel 2.6.X and if the other
 115 interface is down. Consequently, this is not compatible with
 116 Hotplug. The other interface is assigned a random name, but may be
 117 renamed later with 'ifrename'.
 118 .br
 119 The number of takeovers is limited to avoid circular loops, and
 120 therefore some complex multi-way name swapping situations may not be
 121 fully processed.
 122 .br
 123 In any case, name swapping and the use of this feature is discouraged,
 124 and you are invited to choose unique and unambiguous names for your
 125 interfaces...
 126 .TP
 127 .B -u
 128 Enable
 129 .I udev
 130 output mode. This enables proper integration of
 131 .B ifrename
 132 in the
 133 .I udev
 134 framework,
 135 .BR udevd (8)
 136 will use
 137 .B ifrename
 138 to assign interface names present in
 139 .IR /etc/iftab .
 140 In this mode the output of ifrename can be parsed
 141 directly by
 142 .BR udevd (8)
 143 as an IMPORT action. This requires
 144 .I udev
 145 version 107 or later.
 146 .TP
 147 .B -D
 148 Dry-run mode. Ifrename won't change any interface, it will only print
 149 new interface name, if applicable, and return.
 150 .br
 151 In dry-run mode, interface name wildcards are not resolved. New
 152 interface name is printed, even if it is the same as the old name.
 153 .br
 154 Be also aware that some selectors can only be read by root, for
 155 example those based on
 156 .BR ethtool ),
 157 and will fail silently if run by a normal user. In other words,
 158 dry-run mode under a standard user may not give the expected result.
 159 .TP
 160 .B -V
 161 Verbose mode. Ifrename will display internal results of parsing its
 162 configuration file and querying the interfaces selectors. Combined
 163 with the
 164 .I dry-run
 165 option, this is a good way to debug complex configurations or trivial
 166 problems.
 167 .TP
 168 .B -C
 169 Count matching interfaces. Display the number of interface matched,
 170 and return it as the exit status of ifrename.
 171 .br
 172 The number of interfaces matched is the number of interface on the
 173 system for which a mapping was found in the config file (which is
 174 different from the number of interface renamed).
 175 .\"
 176 .\" AUTHOR part
 177 .\"
 178 .SH AUTHOR
 179 Jean Tourrilhes \- jt@hpl.hp.com
 180 .\"
 181 .\" FILES part
 182 .\"
 183 .SH FILES
 184 .I /etc/iftab
 185 .\"
 186 .\" SEE ALSO part
 187 .\"
 188 .SH SEE ALSO
 189 .BR ifconfig (8),
 190 .BR ip (8),
 191 .BR iftab (5).