1 .\" Copyright (c) 1983, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgment:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" From: @(#)ifconfig.8 8.3 (Berkeley) 1/5/94
33 .\" $FreeBSD: src/sbin/ifconfig/ifconfig.8,v 1.27.2.14 2001/08/23 06:35:38 yar Exp $
40 .Nd configure network interface parameters
49 .Ar address Ns Op Cm / Ns Ar prefixlength
94 is used to assign an address
95 to a network interface and/or configure
96 network interface parameters.
98 must be used at boot time to define the network address
99 of each interface present on a machine; it may also be used at
100 a later time to redefine an interface's address
101 or other operating parameters.
103 The following options are available:
104 .Bl -tag -width indent
107 .Tn DARPA Ns -Internet
109 the address is either a host name present in the host name data
114 Internet address expressed in the Internet standard
117 It is also possible to use the CIDR notation (also known as the
118 slash notation) to include the netmask.
119 That is, one can specify an address like
121 .\" For the Xerox Network Systems(tm) family,
123 .\" .Ar net:a.b.c.d.e.f ,
126 .\" is the assigned network number (in decimal),
127 .\" and each of the six bytes of the host number,
131 .\" are specified in hexadecimal.
132 .\" The host number may be omitted on IEEE 802 protocol
133 .\" (Ethernet, FDDI, and Token Ring) interfaces,
134 .\" which use the hardware physical address,
135 .\" and on interfaces other than the first.
138 .\" family, addresses are specified as a long hexadecimal string,
139 .\" as in the Xerox family.
140 .\" However, two consecutive dots imply a zero
141 .\" byte, and the dots are optional, if the user wishes to (carefully)
142 .\" count out long strings of digits in network byte order.
143 .It Ar address_family
146 which affects interpretation of the remaining parameters.
147 Since an interface can receive transmissions in differing protocols
148 with different naming schemes, specifying the address family is recommended.
149 The address or protocol families currently
156 Specify the address of the correspondent on the other end
157 of a point to point link.
160 parameter is a string of the form
165 This parameter has the same encoding as the
170 The following parameters may be set with
172 .Bl -tag -width indent
177 Introduced for compatibility
181 Establish an additional network address for this interface.
182 This is sometimes useful when changing network numbers, and
183 one wishes to accept packets addressed to the old interface.
184 If the address is on the same subnet as the first network address
185 for this interface, a netmask of
189 Remove the network address specified.
190 This would be used if you incorrectly specified an alias, or it
191 was no longer needed.
192 If you have incorrectly set an NS address having the side effect
193 of specifying the host portion, removing all NS addresses will
194 allow you to respecify the host portion.
197 Specify that the address configured is an anycast address.
198 Based on the current specification,
199 only routers may configure anycast addresses.
200 Anycast address will not be used as source address of any of outgoing
203 Enable the use of the Address Resolution Protocol
206 between network level addresses and link level addresses (default).
207 This is currently implemented for mapping between
212 802 48-bit MAC addresses (Ethernet, FDDI, and Token Ring addresses).
214 Disable the use of the Address Resolution Protocol
216 .It Cm bonddev Ar iface
217 If the interface is a bond pseudo device, associate physical interface
219 with it. The bond pseudo device conforms
220 to the IEEE 802.3ad Link Aggregation specification.
222 If this is the first physical interface to be associated with the bond
223 interface, the bond interface inherits the ethernet address from the
224 physical interface. Physical interfaces that are added to the bond have
225 their ethernet address re-programmed so that all members of the bond have
226 the same ethernet address. If the physical interface is subsequently
227 removed from the bond using
229 a new ethernet address is chosen from the remaining interfaces, and all
230 interfaces are re-programmed again with the new ethernet address. If no
231 remaining interfaces exist, the bond interface's ethernet address is cleared.
233 If the specified physical interface
235 is not capable of having its ethernet address re-programmed, the
239 Once the physical interface
241 is successfully associated with the bond interface, all received packets
242 are diverted to the bond interface. The physical interface is no longer
243 useable on its own, and remains that way until it is removed from the bond using
246 It is possible that the specified interface
248 is not capable of aggregating, and may remain unused until the operating
251 The link status of the bond interface depends on the state of link aggregation.
252 If no active partner is detected, the link status will remain inactive.
254 To monitor the 802.3ad Link Aggregation state, use the
258 A physical interface that is associated with a vlan pseudo device cannot
259 at the same time be associated with a bond pseudo device. A physical interface
260 cannot be associated with more than one bond pseudo device at the same time.
262 It is not possible to associate a bond with pseudo interfaces such as vlan.
263 Only physical ethernet interfaces may be associated with a bond.
264 .It Fl bonddev Ar iface
265 If the interface is a bond pseudo device, disassociate the physical interface
267 from it. Before the interface is removed from the bond, the bond device
268 announces to the link partner that the interface is now individual and
269 no longer aggregatable.
272 is the last interface in the bond, the bond interface clears its link address.
275 Specify the address to use to represent broadcasts to the
277 The default broadcast address is the address with a host part of all 1's.
279 Enable driver dependent debugging code; usually, this turns on
280 extra console error logging.
282 Disable driver dependent debugging code.
290 When an interface is marked
292 the system will not attempt to
293 transmit messages through that interface.
294 If possible, the interface will be reset to disable reception as well.
295 This action does not automatically disable routes using the interface.
301 .\" This is used to specify an Internet host who is willing to receive
302 .\" ip packets encapsulating NS packets bound for a remote network.
303 .\" An apparent point to point link is constructed, and
304 .\" the address specified will be taken as the NS address and network
305 .\" of the destination.
306 .\" IP encapsulation of
308 .\" packets is done differently.
309 .It Cm lladdr Ar addr
310 Set the link-level address on an interface.
312 e.g. set a new MAC address on an ethernet interface, though the
313 mechanism used is not ethernet-specific.
316 is specified as a series of colon-separated hex digits.
317 If the interface is already
318 up when this option is used, it will be briefly brought down and
319 then brought back up again in order to ensure that the receive
320 filter in the underlying ethernet hardware is properly reprogrammed.
322 If the driver supports the media selection system, set the media type
325 Some interfaces support the mutually exclusive use of one of several
326 different physical media connectors.
327 For example, a 10Mb/s Ethernet
328 interface might support the use of either
330 or twisted pair connectors.
331 Setting the media type to
333 would change the currently active connector to the AUI port.
336 would activate twisted pair.
337 Refer to the interfaces' driver
338 specific documentation or man page for a complete list of the
340 .It Cm mediaopt Ar opts
341 If the driver supports the media selection system, set the specified
342 media options on the interface.
346 is a comma delimited list of options to apply to the interface.
347 Refer to the interfaces' driver specific man page for a complete
348 list of available options.
349 .It Fl mediaopt Ar opts
350 If the driver supports the media selection system, disable the
351 specified media options on the interface.
352 .It Cm tunnel Ar src_addr dest_addr
353 (IP tunnel devices only.)
354 Configure the physical source and destination address for IP tunnel
361 are interpreted as the outer source/destination for the encapsulating
364 Unconfigure the physical source and destination address for IP tunnel
365 interfaces previously configured with
368 Create the specified network pseudo-device.
369 If the interface is given without a unit number, try to create a new
370 device with an arbitrary unit number.
371 If creation of an arbitrary device is successful, the new device name is
372 printed to standard output.
374 Destroy the specified network pseudo-device.
390 Set the routing metric of the interface to
393 The routing metric is used by the routing protocol
395 Higher metrics have the effect of making a route
396 less favorable; metrics are counted as addition hops
397 to the destination network or host.
399 Set the maximum transmission unit of the interface to
401 default is interface specific.
402 The MTU is used to limit the size of packets that are transmitted on an
404 Not all interfaces support setting the MTU, and some interfaces have
406 .It Cm netmask Ar mask
409 Specify how much of the address to reserve for subdividing
410 networks into sub-networks.
411 The mask includes the network part of the local address
412 and the subnet part, which is taken from the host field of the address.
413 The mask can be specified as a single hexadecimal number
416 with a dot-notation Internet address,
417 or with a pseudo-network name listed in the network table
419 The mask contains 1's for the bit positions in the 32-bit address
420 which are to be used for the network and subnet parts,
421 and 0's for the host part.
422 The mask should contain at least the standard network portion,
423 and the subnet field should be contiguous with the network
426 The netmask can also be specified in CIDR notation after the address.
429 option above for more information.
430 .It Cm prefixlen Ar len
434 bits are reserved for subdividing networks into sub-networks.
437 must be integer, and for syntactical reason it must be between 0 to 128.
438 It is almost always 64 under the current IPv6 assignment rule.
439 If the parameter is omitted, 64 is used.
442 .\" .It Cm nsellength Ar n
445 .\" This specifies a trailing number of bytes for a received
447 .\" used for local identification, the remaining leading part of which is
450 .\" (Network Entity Title).
451 .\" The default value is 1, which is conformant to US
453 .\" When an ISO address is set in an ifconfig command,
456 .\" which is being specified.
459 .\" 20 hex digits should be
462 .\" to be assigned to the interface.
463 .\" There is some evidence that a number different from 1 may be useful
466 .\" 37 type addresses.
471 Introduced for compatibility
475 .It Cm link Op Cm 0 No - Cm 2
477 Enable special processing of the link level of the interface.
478 These three options are interface specific in actual effect, however,
479 they are in general used to select special modes of operation.
481 of this is to enable SLIP compression, or to select the connector type
482 for some Ethernet cards.
483 Refer to the man page for the specific driver
484 for more information.
486 .It Fl link Op Cm 0 No - Cm 2
488 Disable special processing at the link level with the specified interface.
492 This may be used to enable an interface after an
494 It happens automatically when setting the first address on an interface.
495 If the interface was reset when previously marked down,
496 the hardware will be re-initialized.
497 .It Cm vlan Ar vlan_tag Cm vlandev Ar iface
498 If the interface is a vlan pseudo interface, set its vlan tag value
501 and associate it with the physical interface
506 value is a 16-bit number that is used to create an 802.1Q
507 vlan header for packets sent from the vlan interface.
509 A packet that is transmitted through the vlan interface is sent
510 using the specified physical interface
512 with 802.1Q vlan encapsulation with the specified
514 A packet with 802.1Q encapsulation received by the physical interface
515 is directed to the associated vlan interface with the matching
517 If there is no matching vlan interface, the packet is dropped.
519 The vlan interface is assigned a
520 copy of the parent interface's flags and the parent's ethernet address.
521 If the vlan interface already has
522 a physical interface associated with it, this command will fail.
524 change the association to another physical interface, the existing
525 association must be cleared first using
528 If the physical interface supports 802.1Q VLAN tagging in hardware,
529 the vlan pseudo interface does not itself insert or remove the 802.1Q
530 encapsulation header. Instead, the
532 is passed out of band from the packet data.
534 A physical interface that is associated with a bond pseudo device cannot
535 at the same time be associated with a vlan interface. However, a physical
536 interface can be associated with multiple vlan interfaces at the same time,
537 as long as each of the
540 .It Fl vlandev Ar iface
541 If the driver is a vlan pseudo device, disassociate the physical interface
544 This breaks the link between the vlan interface and its parent,
545 clears its vlan tag, flags and its link address.
549 displays the current configuration for a network interface
550 when no optional parameters are supplied.
551 If a protocol family is specified,
553 will report only the details specific to that protocol family.
555 If the driver supports the media selection system, the supported
556 media list will be included in the output, regardless of whether the
558 flag is passed or not.
562 option passed before the interface name will print the link aggregation
563 state for bond pseudo devices.
567 flag is supplied, address lifetime is displayed for IPv6 addresses,
568 as time offset string.
572 flag may be used instead of an interface name.
575 to display information about all interfaces in the system.
578 flag limits this to interfaces that are down, and
580 limits this to interfaces that are up.
581 When no arguments are given,
587 flag may be used to list all available interfaces on the system, with
588 no other additional information.
589 Use of this flag is mutually exclusive
590 with all other flags and commands, except for
592 (only list interfaces that are down)
595 (only list interfaces that are up).
597 Only the super-user may modify the configuration of a network interface.
599 The media selection system is relatively new and only some drivers support
600 it (or have need for it).
602 Messages indicating the specified interface does not exist, the
603 requested address is unknown, or the user is not privileged and
604 tried to alter an interface's configuration.
606 IPv6 link-local addresses are required for several basic communication
608 If they are deleted by
610 manually, the kernel might show very strange behavior.
611 So, such manual deletions are strongly discouraged.
projects / apple / network_cmds.git / blob