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 .\" 4. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" From: @(#)ifconfig.8 8.3 (Berkeley) 1/5/94
29 .\" $FreeBSD: src/sbin/ifconfig/ifconfig.8,v 1.142.2.6.2.1 2008/11/25 02:59:29 kensmith Exp $
36 .Nd configure network interface parameters
97 utility is used to assign an address
98 to a network interface and/or configure
99 network interface parameters.
101 The following options are available:
102 .Bl -tag -width indent
105 .Tn DARPA Ns -Internet
107 the address is either a host name present in the host name data
112 Internet address expressed in the Internet standard
115 It is also possible to use the CIDR notation (also known as the
116 slash notation) to include the netmask.
117 That is, one can specify an address like
122 family, it is also possible to specify the prefix length using the slash
127 parameter below for more information.
128 .\" For the Xerox Network Systems(tm) family,
130 .\" .Ar net:a.b.c.d.e.f ,
133 .\" is the assigned network number (in decimal),
134 .\" and each of the six bytes of the host number,
138 .\" are specified in hexadecimal.
139 .\" The host number may be omitted on IEEE 802 protocol
140 .\" (Ethernet, FDDI, and Token Ring) interfaces,
141 .\" which use the hardware physical address,
142 .\" and on interfaces other than the first.
145 .\" family, addresses are specified as a long hexadecimal string,
146 .\" as in the Xerox family.
147 .\" However, two consecutive dots imply a zero
148 .\" byte, and the dots are optional, if the user wishes to (carefully)
149 .\" count out long strings of digits in network byte order.
154 is specified as a series of colon-separated hex digits.
156 e.g.\& set a new MAC address on an ethernet interface, though the
157 mechanism used is not ethernet-specific.
158 If the interface is already
159 up when this option is used, it will be briefly brought down and
160 then brought back up again in order to ensure that the receive
161 filter in the underlying ethernet hardware is properly reprogrammed.
162 .It Ar address_family
165 which affects interpretation of the remaining parameters.
166 Since an interface can receive transmissions in differing protocols
167 with different naming schemes, specifying the address family is recommended.
168 The address or protocol families currently
187 Specify the address of the correspondent on the other end
188 of a point to point link.
191 parameter is a string of the form
197 The following parameters may be set with
199 .Bl -tag -width indent
204 Introduced for compatibility
208 Establish an additional network address for this interface.
209 This is sometimes useful when changing network numbers, and
210 one wishes to accept packets addressed to the old interface.
211 If the address is on the same subnet as the first network address
212 for this interface, a non-conflicting netmask must be given.
217 Remove the network address specified.
218 This would be used if you incorrectly specified an alias, or it
219 was no longer needed.
220 If you have incorrectly set an NS address having the side effect
221 of specifying the host portion, removing all NS addresses will
222 allow you to respecify the host portion.
225 Specify that the address configured is an anycast address.
226 Based on the current specification,
227 only routers may configure anycast addresses.
228 Anycast address will not be used as source address of any of outgoing
231 Enable the use of the Address Resolution Protocol
234 between network level addresses and link level addresses (default).
235 This is currently implemented for mapping between
240 802 48-bit MAC addresses (Ethernet, FDDI, and Token Ring addresses).
242 Disable the use of the Address Resolution Protocol
246 Specify the address to use to represent broadcasts to the
248 The default broadcast address is the address with a host part of all 1's.
250 Enable driver dependent debugging code; usually, this turns on
251 extra console error logging.
253 Disable driver dependent debugging code.
261 When an interface is marked
263 the system will not attempt to
264 transmit messages through that interface.
265 If possible, the interface will be reset to disable reception as well.
266 This action does not automatically disable routes using the interface.
272 .\" This is used to specify an Internet host who is willing to receive
273 .\" ip packets encapsulating NS packets bound for a remote network.
274 .\" An apparent point to point link is constructed, and
275 .\" the address specified will be taken as the NS address and network
276 .\" of the destination.
277 .\" IP encapsulation of
279 .\" packets is done differently.
280 .It Cm lladdr Ar addr
281 Set the link-level address on an interface.
283 e.g. set a new MAC address on an ethernet interface, though the
284 mechanism used is not ethernet-specific.
287 is specified as a series of colon-separated hex digits.
288 If the interface is already
289 up when this option is used, it will be briefly brought down and
290 then brought back up again in order to ensure that the receive
291 filter in the underlying ethernet hardware is properly reprogrammed.
293 If the driver supports the media selection system, set the media type
296 Some interfaces support the mutually exclusive use of one of several
297 different physical media connectors.
298 For example, a 10Mb/s Ethernet
299 interface might support the use of either
301 or twisted pair connectors.
302 Setting the media type to
304 would change the currently active connector to the AUI port.
307 would activate twisted pair.
308 Refer to the interfaces' driver
309 specific documentation or man page for a complete list of the
311 .It Cm mediaopt Ar opts
312 If the driver supports the media selection system, set the specified
313 media options on the interface.
317 is a comma delimited list of options to apply to the interface.
318 Refer to the interfaces' driver specific man page for a complete
319 list of available options.
320 .It Fl mediaopt Ar opts
321 If the driver supports the media selection system, disable the
322 specified media options on the interface.
324 Create the specified network pseudo-device.
325 If the interface is given without a unit number, try to create a new
326 device with an arbitrary unit number.
327 If creation of an arbitrary device is successful, the new device name is
328 printed to standard output unless the interface is renamed or destroyed
333 Destroy the specified network pseudo-device.
349 Set the routing metric of the interface to
352 The routing metric is used by the routing protocol
354 Higher metrics have the effect of making a route
355 less favorable; metrics are counted as additional hops
356 to the destination network or host.
358 Set the maximum transmission unit of the interface to
360 default is interface specific.
361 The MTU is used to limit the size of packets that are transmitted on an
363 Not all interfaces support setting the MTU, and some interfaces have
365 .It Cm netmask Ar mask
368 Specify how much of the address to reserve for subdividing
369 networks into sub-networks.
370 The mask includes the network part of the local address
371 and the subnet part, which is taken from the host field of the address.
372 The mask can be specified as a single hexadecimal number
375 with a dot-notation Internet address,
376 or with a pseudo-network name listed in the network table
378 The mask contains 1's for the bit positions in the 32-bit address
379 which are to be used for the network and subnet parts,
380 and 0's for the host part.
381 The mask should contain at least the standard network portion,
382 and the subnet field should be contiguous with the network
385 The netmask can also be specified in CIDR notation after the address.
388 option above for more information.
389 .It Cm prefixlen Ar len
393 bits are reserved for subdividing networks into sub-networks.
396 must be integer, and for syntactical reason it must be between 0 to 128.
397 It is almost always 64 under the current IPv6 assignment rule.
398 If the parameter is omitted, 64 is used.
400 The prefix can also be specified using the slash notation after the address.
403 option above for more information.
406 .\" .It Cm nsellength Ar n
409 .\" This specifies a trailing number of bytes for a received
411 .\" used for local identification, the remaining leading part of which is
414 .\" (Network Entity Title).
415 .\" The default value is 1, which is conformant to US
417 .\" When an ISO address is set in an ifconfig command,
420 .\" which is being specified.
423 .\" 20 hex digits should be
426 .\" to be assigned to the interface.
427 .\" There is some evidence that a number different from 1 may be useful
430 .\" 37 type addresses.
435 Introduced for compatibility
439 .It Cm link Op Cm 0 No - Cm 2
441 Enable special processing of the link level of the interface.
442 These three options are interface specific in actual effect, however,
443 they are in general used to select special modes of operation.
445 of this is to enable SLIP compression, or to select the connector type
446 for some Ethernet cards.
447 Refer to the man page for the specific driver
448 for more information.
450 .It Fl link Op Cm 0 No - Cm 2
452 Disable special processing at the link level with the specified interface.
456 This may be used to enable an interface after an
458 It happens automatically when setting the first address on an interface.
459 If the interface was reset when previously marked down,
460 the hardware will be re-initialized.
463 The following parameters are specific to link aggregate interfaces:
464 .Bl -tag -width indent
465 .It Cm bonddev Ar iface
466 If the interface is a bond pseudo device, associate physical interface
468 with it. By default, the bond pseudo device is in LACP
469 (Link Aggregation Control Protocol) mode (see \fBbondmode\fR below). In
470 this mode, the device conforms to the IEEE 802.3ad Link Aggregation
473 If this is the first physical interface to be associated with the bond
474 interface, the bond interface inherits the ethernet address from the
475 physical interface. Physical interfaces that are added to the bond have
476 their ethernet address re-programmed so that all members of the bond have
477 the same ethernet address. If the physical interface is subsequently
478 removed from the bond using
480 a new ethernet address is chosen from the remaining interfaces, and all
481 interfaces are re-programmed again with the new ethernet address. If no
482 remaining interfaces exist, the bond interface's ethernet address is cleared.
484 If the specified physical interface
486 is not capable of having its ethernet address re-programmed, the
490 Once the physical interface
492 is successfully associated with the bond interface, all received packets
493 are diverted to the bond interface. The physical interface is no longer
494 useable on its own, and remains that way until it is removed from the bond using
497 It is possible that the specified interface
499 is not capable of aggregating, and may remain unused until the operating
502 The link status of the bond interface depends on the state of link aggregation.
503 If no active partner is detected, the link status will remain inactive.
505 To monitor the 802.3ad Link Aggregation state, use the
509 A physical interface that is associated with a vlan pseudo device cannot
510 at the same time be associated with a bond pseudo device. A physical interface
511 cannot be associated with more than one bond pseudo device at the same time.
513 It is not possible to associate a bond with pseudo interfaces such as vlan.
514 Only physical ethernet interfaces may be associated with a bond.
515 .It Fl bonddev Ar iface
516 If the interface is a bond pseudo device, disassociate the physical interface
518 from it. Before the interface is removed from the bond, the bond device
519 announces to the link partner that the interface is now individual and
520 no longer aggregatable.
523 is the last interface in the bond, the bond interface clears its link address.
524 .It Cm bondmode Ar lacp | static
525 If the interface is a bond pseudo device, this option will set the \fImode\fR
526 on the bond interface. The two currently supported modes are
533 To enable static mode (and turn off LACP), specify
535 In static mode, a member interface is made an active part of the
536 link aggregate as long as the link status is active.
538 To re-enable LACP mode, specify
542 The following parameters are specific to IP tunnel interfaces,
544 .Bl -tag -width indent
545 .It Cm tunnel Ar src_addr dest_addr
546 Configure the physical source and destination address for IP tunnel
552 are interpreted as the outer source/destination for the encapsulating
555 Unconfigure the physical source and destination address for IP tunnel
556 interfaces previously configured with
564 The following parameters are specific to bridge interfaces:
565 .Bl -tag -width indent
566 .It Cm addm Ar interface
567 Add the interface named by
569 as a member of the bridge.
570 The interface is put into promiscuous mode
571 so that it can receive every packet sent on the network.
572 .It Cm deletem Ar interface
573 Remove the interface named by
576 Promiscuous mode is disabled on the interface when
577 it is removed from the bridge.
578 .It Cm maxaddr Ar size
579 Set the size of the bridge address cache to
581 The default is 100 entries.
582 .It Cm timeout Ar seconds
583 Set the timeout of address cache entries to
588 is zero, then address cache entries will not be expired.
589 The default is 240 seconds.
591 Display the addresses that have been learned by the bridge.
592 .It Cm static Ar interface-name Ar address
593 Add a static entry into the address cache pointing to
595 Static entries are never aged out of the cache or re-placed, even if the
596 address is seen on a different interface.
597 .It Cm deladdr Ar address
600 from the address cache.
602 Delete all dynamically-learned addresses from the address cache.
604 Delete all addresses, including static addresses, from the address cache.
605 .It Cm discover Ar interface
606 Mark an interface as a
609 When the bridge has no address cache entry
610 (either dynamic or static)
611 for the destination address of a packet,
612 the bridge will forward the packet to all
613 member interfaces marked as
615 This is the default for all interfaces added to a bridge.
616 .It Cm -discover Ar interface
619 attribute on a member interface.
620 For packets without the
622 attribute, the only packets forwarded on the interface are broadcast
623 or multicast packets and packets for which the destination address
624 is known to be on the interface's segment.
625 .It Cm learn Ar interface
626 Mark an interface as a
629 When a packet arrives on such an interface, the source
630 address of the packet is entered into the address cache as being a
631 destination address on the interface's segment.
632 This is the default for all interfaces added to a bridge.
633 .It Cm -learn Ar interface
636 attribute on a member interface.
637 .It Cm sticky Ar interface
638 Mark an interface as a
641 Dynamically learned address entries are treated at static once entered into
643 Sticky entries are never aged out of the cache or replaced, even if the
644 address is seen on a different interface.
645 .It Cm -sticky Ar interface
648 attribute on a member interface.
649 .It Cm private Ar interface
650 Mark an interface as a
653 A private interface does not forward any traffic to any other port that is also
655 .It Cm -private Ar interface
658 attribute on a member interface.
659 .It Cm span Ar interface
660 Add the interface named by
662 as a span port on the bridge.
663 Span ports transmit a copy of every frame received by the bridge.
664 This is most useful for snooping a bridged network passively on
665 another host connected to one of the span ports of the bridge.
666 .It Cm -span Ar interface
667 Delete the interface named by
669 from the list of span ports of the bridge.
670 .It Cm stp Ar interface
671 Enable Spanning Tree protocol on
675 driver has support for the IEEE 802.1D Spanning Tree protocol (STP).
676 Spanning Tree is used to detect and remove loops in a network topology.
677 .It Cm -stp Ar interface
678 Disable Spanning Tree protocol on
680 This is the default for all interfaces added to a bridge.
681 .It Cm edge Ar interface
685 An edge port connects directly to end stations cannot create bridging
686 loops in the network, this allows it to transition straight to forwarding.
687 .It Cm -edge Ar interface
688 Disable edge status on
690 .It Cm autoedge Ar interface
693 to automatically detect edge status.
694 This is the default for all interfaces added to a bridge.
695 .It Cm -autoedge Ar interface
696 Disable automatic edge status on
698 .It Cm ptp Ar interface
701 as a point to point link.
702 This is required for straight transitions to forwarding and
703 should be enabled on a direct link to another RSTP capable switch.
704 .It Cm -ptp Ar interface
705 Disable point to point link status on
707 This should be disabled for a half duplex link and for an interface
708 connected to a shared network segment,
709 like a hub or a wireless network.
710 .It Cm autoptp Ar interface
711 Automatically detect the point to point status on
713 by checking the full duplex link status.
714 This is the default for interfaces added to the bridge.
715 .It Cm -autoptp Ar interface
716 Disable automatic point to point link detection on
718 .It Cm maxage Ar seconds
719 Set the time that a Spanning Tree protocol configuration is valid.
720 The default is 20 seconds.
721 The minimum is 6 seconds and the maximum is 40 seconds.
722 .It Cm fwddelay Ar seconds
723 Set the time that must pass before an interface begins forwarding
724 packets when Spanning Tree is enabled.
725 The default is 15 seconds.
726 The minimum is 4 seconds and the maximum is 30 seconds.
727 .It Cm hellotime Ar seconds
728 Set the time between broadcasting of Spanning Tree protocol
729 configuration messages.
730 The hello time may only be changed when operating in legacy stp mode.
731 The default is 2 seconds.
732 The minimum is 1 second and the maximum is 2 seconds.
733 .It Cm priority Ar value
734 Set the bridge priority for Spanning Tree.
735 The default is 32768.
736 The minimum is 0 and the maximum is 61440.
737 .It Cm proto Ar value
738 Set the Spanning Tree protocol.
740 The available options are stp and rstp.
741 .It Cm holdcnt Ar value
742 Set the transmit hold count for Spanning Tree.
743 This is the number of packets transmitted before being rate limited.
745 The minimum is 1 and the maximum is 10.
746 .It Cm ifpriority Ar interface Ar value
747 Set the Spanning Tree priority of
752 The minimum is 0 and the maximum is 240.
753 .It Cm ifpathcost Ar interface Ar value
754 Set the Spanning Tree path cost of
758 The default is calculated from the link speed.
759 To change a previously selected path cost back to automatic, set the
761 The minimum is 1 and the maximum is 200000000.
762 .It Cm ifmaxaddr Ar interface Ar size
763 Set the maximum number of hosts allowed from an interface, packets with unknown
764 source addresses are dropped until an existing host cache entry expires or is
769 The following parameters are specific to vlan interfaces:
770 .Bl -tag -width indent
771 .It Cm vlan Ar vlan_tag
772 Set the VLAN tag value to
774 This value is a 16-bit number which is used to create an 802.1Q
775 VLAN header for packets sent from the
782 must both be set at the same time.
783 .It Cm vlandev Ar iface
784 Associate the physical interface
789 Packets transmitted through the
792 diverted to the specified physical interface
794 with 802.1Q VLAN encapsulation.
795 Packets with 802.1Q encapsulation received
796 by the parent interface with the correct VLAN tag will be diverted to
802 interface is assigned a
803 copy of the parent interface's flags and the parent's ethernet address.
808 must both be set at the same time.
811 interface already has
812 a physical interface associated with it, this command will fail.
814 change the association to another physical interface, the existing
815 association must be cleared first.
817 Note: if the hardware tagging capability
818 is set on the parent interface, the
821 interface's behavior changes:
824 interface recognizes that the
825 parent interface supports insertion and extraction of VLAN tags on its
826 own (usually in firmware) and that it should pass packets to and from
827 the parent unaltered.
828 .It Fl vlandev Op Ar iface
831 pseudo device, disassociate the parent interface from it.
832 This breaks the link between the
834 interface and its parent,
835 clears its VLAN tag, flags and its link address and shuts the interface down.
838 argument is useless and hence deprecated.
843 utility displays the current configuration for a network interface
844 when no optional parameters are supplied.
845 If a protocol family is specified,
847 will report only the details specific to that protocol family.
851 flag is passed before an interface name,
853 will display the capability list and all
854 of the supported media for the specified interface.
858 flag is supplied, address lifetime is displayed for IPv6 addresses,
859 as time offset string.
863 flag may be used instead of an interface name.
866 to display information about all interfaces in the system.
869 flag limits this to interfaces that are down, and
871 limits this to interfaces that are up.
872 When no arguments are given,
878 flag may be used to list all available interfaces on the system, with
879 no other additional information.
880 Use of this flag is mutually exclusive
881 with all other flags and commands, except for
883 (only list interfaces that are down)
886 (only list interfaces that are up).
890 flag may be used to get more verbose status for an interface.
894 flag may be used to list all of the interface cloners available on
895 the system, with no additional information.
896 Use of this flag is mutually exclusive with all other flags and commands.
898 For bridge interfaces, the list of addresses learned by the bridge is not shown when displaying information about
899 all interfaces except when the
903 Only the super-user may modify the configuration of a network interface.
905 The media selection system is relatively new and only some drivers support
906 it (or have need for it).
908 Assign the IPv4 address
910 with a network mask of
914 .Dl # ifconfig en0 inet 192.0.2.10 netmask 255.255.255.0
918 with the CIDR network prefix
924 as a synonym for the canonical form of the option
926 .Dl # ifconfig en0 inet 192.0.2.45/28 add
928 Remove the IPv4 address
932 .Dl # ifconfig en0 inet 192.0.2.45 -alias
935 .Li 2001:DB8:DBDB::123/48
938 .Dl # ifconfig en0 inet6 2001:db8:bdbd::123 prefixlen 48 alias
939 Note that lower case hexadecimal IPv6 addresses are acceptable.
941 Remove the IPv6 address added in the above example,
944 character as shorthand for the network prefix,
947 as a synonym for the canonical form of the option
949 .Dl # ifconfig en0 inet6 2001:db8:bdbd::123/48 delete
951 Configure the interface
953 to use 100baseTX, full duplex Ethernet media options:
954 .Dl # ifconfig en1 media 100baseTX mediaopt full-duplex
956 Create the software network interface
958 .Dl # ifconfig gif1 create
960 Destroy the software network interface
962 .Dl # ifconfig gif1 destroy
964 Messages indicating the specified interface does not exist, the
965 requested address is unknown, or the user is not privileged and
966 tried to alter an interface's configuration.
977 Basic IPv6 node operation requires a link-local address on each
978 interface configured for IPv6.
979 Normally, such an address is automatically configured by the
980 kernel on each interface added to the system; this behaviour may
981 be disabled by setting the sysctl MIB variable
982 .Va net.inet6.ip6.auto_linklocal
985 If you delete such an address using
987 the kernel may act very odd.
988 Do this at your own risk.
projects / apple / network_cmds.git / blob