| 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 \- [email protected] |
| 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). |