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
100 utility is used to assign an address
101 to a network interface and/or configure
102 network interface parameters.
104 The following options are available:
105 .Bl -tag -width indent
108 .Tn DARPA Ns -Internet
110 the address is either a host name present in the host name data
115 Internet address expressed in the Internet standard
118 It is also possible to use the CIDR notation (also known as the
119 slash notation) to include the netmask.
120 That is, one can specify an address like
125 family, it is also possible to specify the prefix length using the slash
130 parameter below for more information.
131 .\" For the Xerox Network Systems(tm) family,
133 .\" .Ar net:a.b.c.d.e.f ,
136 .\" is the assigned network number (in decimal),
137 .\" and each of the six bytes of the host number,
141 .\" are specified in hexadecimal.
142 .\" The host number may be omitted on IEEE 802 protocol
143 .\" (Ethernet, FDDI, and Token Ring) interfaces,
144 .\" which use the hardware physical address,
145 .\" and on interfaces other than the first.
148 .\" family, addresses are specified as a long hexadecimal string,
149 .\" as in the Xerox family.
150 .\" However, two consecutive dots imply a zero
151 .\" byte, and the dots are optional, if the user wishes to (carefully)
152 .\" count out long strings of digits in network byte order.
157 is specified as a series of colon-separated hex digits.
159 e.g.\& set a new MAC address on an ethernet interface, though the
160 mechanism used is not ethernet-specific.
161 If the interface is already
162 up when this option is used, it will be briefly brought down and
163 then brought back up again in order to ensure that the receive
164 filter in the underlying ethernet hardware is properly reprogrammed.
165 .It Ar address_family
168 which affects interpretation of the remaining parameters.
169 Since an interface can receive transmissions in differing protocols
170 with different naming schemes, specifying the address family is recommended.
171 The address or protocol families currently
190 Specify the address of the correspondent on the other end
191 of a point to point link.
194 parameter is a string of the form
200 The following parameters may be set with
202 .Bl -tag -width indent
207 Introduced for compatibility
211 Establish an additional network address for this interface.
212 This is sometimes useful when changing network numbers, and
213 one wishes to accept packets addressed to the old interface.
214 If the address is on the same subnet as the first network address
215 for this interface, a non-conflicting netmask must be given.
220 Remove the network address specified.
221 This would be used if you incorrectly specified an alias, or it
222 was no longer needed.
223 If you have incorrectly set an NS address having the side effect
224 of specifying the host portion, removing all NS addresses will
225 allow you to respecify the host portion.
228 Specify that the address configured is an anycast address.
229 Based on the current specification,
230 only routers may configure anycast addresses.
231 Anycast address will not be used as source address of any of outgoing
234 Enable the use of the Address Resolution Protocol
237 between network level addresses and link level addresses (default).
238 This is currently implemented for mapping between
243 802 48-bit MAC addresses (Ethernet, FDDI, and Token Ring addresses).
245 Disable the use of the Address Resolution Protocol
249 Specify the address to use to represent broadcasts to the
251 The default broadcast address is the address with a host part of all 1's.
253 Enable driver dependent debugging code; usually, this turns on
254 extra console error logging.
256 Disable driver dependent debugging code.
264 When an interface is marked
266 the system will not attempt to
267 transmit messages through that interface.
268 If possible, the interface will be reset to disable reception as well.
269 This action does not automatically disable routes using the interface.
275 .\" This is used to specify an Internet host who is willing to receive
276 .\" ip packets encapsulating NS packets bound for a remote network.
277 .\" An apparent point to point link is constructed, and
278 .\" the address specified will be taken as the NS address and network
279 .\" of the destination.
280 .\" IP encapsulation of
282 .\" packets is done differently.
283 .It Cm lladdr Ar addr
284 Set the link-level address on an interface.
286 e.g. set a new MAC address on an ethernet interface, though the
287 mechanism used is not ethernet-specific.
290 is specified as a series of colon-separated hex digits.
291 If the interface is already
292 up when this option is used, it will be briefly brought down and
293 then brought back up again in order to ensure that the receive
294 filter in the underlying ethernet hardware is properly reprogrammed.
296 If the driver supports the media selection system, set the media type
299 Some interfaces support the mutually exclusive use of one of several
300 different physical media connectors.
301 For example, a 10Mb/s Ethernet
302 interface might support the use of either
304 or twisted pair connectors.
305 Setting the media type to
307 would change the currently active connector to the AUI port.
310 would activate twisted pair.
311 Refer to the interfaces' driver
312 specific documentation or man page for a complete list of the
314 .It Cm mediaopt Ar opts
315 If the driver supports the media selection system, set the specified
316 media options on the interface.
320 is a comma delimited list of options to apply to the interface.
321 Refer to the interfaces' driver specific man page for a complete
322 list of available options.
323 .It Fl mediaopt Ar opts
324 If the driver supports the media selection system, disable the
325 specified media options on the interface.
327 Create the specified network pseudo-device.
328 If the interface is given without a unit number, try to create a new
329 device with an arbitrary unit number.
330 If creation of an arbitrary device is successful, the new device name is
331 printed to standard output unless the interface is renamed or destroyed
336 Destroy the specified network pseudo-device.
352 Set the routing metric of the interface to
355 The routing metric is used by the routing protocol
357 Higher metrics have the effect of making a route
358 less favorable; metrics are counted as additional hops
359 to the destination network or host.
361 Set the maximum transmission unit of the interface to
363 default is interface specific.
364 The MTU is used to limit the size of packets that are transmitted on an
366 Not all interfaces support setting the MTU, and some interfaces have
368 .It Cm netmask Ar mask
371 Specify how much of the address to reserve for subdividing
372 networks into sub-networks.
373 The mask includes the network part of the local address
374 and the subnet part, which is taken from the host field of the address.
375 The mask can be specified as a single hexadecimal number
378 with a dot-notation Internet address,
379 or with a pseudo-network name listed in the network table
381 The mask contains 1's for the bit positions in the 32-bit address
382 which are to be used for the network and subnet parts,
383 and 0's for the host part.
384 The mask should contain at least the standard network portion,
385 and the subnet field should be contiguous with the network
388 The netmask can also be specified in CIDR notation after the address.
391 option above for more information.
392 .It Cm prefixlen Ar len
396 bits are reserved for subdividing networks into sub-networks.
399 must be integer, and for syntactical reason it must be between 0 to 128.
400 It is almost always 64 under the current IPv6 assignment rule.
401 If the parameter is omitted, 64 is used.
403 The prefix can also be specified using the slash notation after the address.
406 option above for more information.
409 .\" .It Cm nsellength Ar n
412 .\" This specifies a trailing number of bytes for a received
414 .\" used for local identification, the remaining leading part of which is
417 .\" (Network Entity Title).
418 .\" The default value is 1, which is conformant to US
420 .\" When an ISO address is set in an ifconfig command,
423 .\" which is being specified.
426 .\" 20 hex digits should be
429 .\" to be assigned to the interface.
430 .\" There is some evidence that a number different from 1 may be useful
433 .\" 37 type addresses.
438 Introduced for compatibility
442 .It Cm link Op Cm 0 No - Cm 2
444 Enable special processing of the link level of the interface.
445 These three options are interface specific in actual effect, however,
446 they are in general used to select special modes of operation.
448 of this is to enable SLIP compression, or to select the connector type
449 for some Ethernet cards.
450 Refer to the man page for the specific driver
451 for more information.
453 .It Fl link Op Cm 0 No - Cm 2
455 Disable special processing at the link level with the specified interface.
459 This may be used to enable an interface after an
461 It happens automatically when setting the first address on an interface.
462 If the interface was reset when previously marked down,
463 the hardware will be re-initialized.
466 The following parameters are specific to link aggregate interfaces:
467 .Bl -tag -width indent
468 .It Cm bonddev Ar iface
469 If the interface is a bond pseudo device, associate physical interface
471 with it. By default, the bond pseudo device is in LACP
472 (Link Aggregation Control Protocol) mode (see \fBbondmode\fR below). In
473 this mode, the device conforms to the IEEE 802.3ad Link Aggregation
476 If this is the first physical interface to be associated with the bond
477 interface, the bond interface inherits the ethernet address from the
478 physical interface. Physical interfaces that are added to the bond have
479 their ethernet address re-programmed so that all members of the bond have
480 the same ethernet address. If the physical interface is subsequently
481 removed from the bond using
483 a new ethernet address is chosen from the remaining interfaces, and all
484 interfaces are re-programmed again with the new ethernet address. If no
485 remaining interfaces exist, the bond interface's ethernet address is cleared.
487 If the specified physical interface
489 is not capable of having its ethernet address re-programmed, the
493 Once the physical interface
495 is successfully associated with the bond interface, all received packets
496 are diverted to the bond interface. The physical interface is no longer
497 useable on its own, and remains that way until it is removed from the bond using
500 It is possible that the specified interface
502 is not capable of aggregating, and may remain unused until the operating
505 The link status of the bond interface depends on the state of link aggregation.
506 If no active partner is detected, the link status will remain inactive.
508 To monitor the 802.3ad Link Aggregation state, use the
512 A physical interface that is associated with a vlan pseudo device cannot
513 at the same time be associated with a bond pseudo device. A physical interface
514 cannot be associated with more than one bond pseudo device at the same time.
516 It is not possible to associate a bond with pseudo interfaces such as vlan.
517 Only physical ethernet interfaces may be associated with a bond.
518 .It Fl bonddev Ar iface
519 If the interface is a bond pseudo device, disassociate the physical interface
521 from it. Before the interface is removed from the bond, the bond device
522 announces to the link partner that the interface is now individual and
523 no longer aggregatable.
526 is the last interface in the bond, the bond interface clears its link address.
527 .It Cm bondmode Ar lacp | static
528 If the interface is a bond pseudo device, this option will set the \fImode\fR
529 on the bond interface. The two currently supported modes are
536 To enable static mode (and turn off LACP), specify
538 In static mode, a member interface is made an active part of the
539 link aggregate as long as the link status is active.
541 To re-enable LACP mode, specify
545 The following parameters are specific to IP tunnel interfaces,
547 .Bl -tag -width indent
548 .It Cm tunnel Ar src_addr dest_addr
549 Configure the physical source and destination address for IP tunnel
555 are interpreted as the outer source/destination for the encapsulating
558 Unconfigure the physical source and destination address for IP tunnel
559 interfaces previously configured with
567 The following parameters are specific to bridge interfaces:
568 .Bl -tag -width indent
569 .It Cm addm Ar interface
570 Add the interface named by
572 as a member of the bridge.
573 The interface is put into promiscuous mode
574 so that it can receive every packet sent on the network.
575 .It Cm deletem Ar interface
576 Remove the interface named by
579 Promiscuous mode is disabled on the interface when
580 it is removed from the bridge.
581 .It Cm maxaddr Ar size
582 Set the size of the bridge address cache to
584 The default is 100 entries.
585 .It Cm timeout Ar seconds
586 Set the timeout of address cache entries to
591 is zero, then address cache entries will not be expired.
592 The default is 240 seconds.
594 Display the addresses that have been learned by the bridge.
595 .It Cm static Ar interface-name Ar address
596 Add a static entry into the address cache pointing to
598 Static entries are never aged out of the cache or re-placed, even if the
599 address is seen on a different interface.
600 .It Cm deladdr Ar address
603 from the address cache.
605 Delete all dynamically-learned addresses from the address cache.
607 Delete all addresses, including static addresses, from the address cache.
608 .It Cm discover Ar interface
609 Mark an interface as a
612 When the bridge has no address cache entry
613 (either dynamic or static)
614 for the destination address of a packet,
615 the bridge will forward the packet to all
616 member interfaces marked as
618 This is the default for all interfaces added to a bridge.
619 .It Cm -discover Ar interface
622 attribute on a member interface.
623 For packets without the
625 attribute, the only packets forwarded on the interface are broadcast
626 or multicast packets and packets for which the destination address
627 is known to be on the interface's segment.
628 .It Cm learn Ar interface
629 Mark an interface as a
632 When a packet arrives on such an interface, the source
633 address of the packet is entered into the address cache as being a
634 destination address on the interface's segment.
635 This is the default for all interfaces added to a bridge.
636 .It Cm -learn Ar interface
639 attribute on a member interface.
640 .It Cm sticky Ar interface
641 Mark an interface as a
644 Dynamically learned address entries are treated at static once entered into
646 Sticky entries are never aged out of the cache or replaced, even if the
647 address is seen on a different interface.
648 .It Cm -sticky Ar interface
651 attribute on a member interface.
652 .It Cm private Ar interface
653 Mark an interface as a
656 A private interface does not forward any traffic to any other port that is also
658 .It Cm -private Ar interface
661 attribute on a member interface.
662 .It Cm span Ar interface
663 Add the interface named by
665 as a span port on the bridge.
666 Span ports transmit a copy of every frame received by the bridge.
667 This is most useful for snooping a bridged network passively on
668 another host connected to one of the span ports of the bridge.
669 .It Cm -span Ar interface
670 Delete the interface named by
672 from the list of span ports of the bridge.
673 .It Cm stp Ar interface
674 Enable Spanning Tree protocol on
678 driver has support for the IEEE 802.1D Spanning Tree protocol (STP).
679 Spanning Tree is used to detect and remove loops in a network topology.
680 .It Cm -stp Ar interface
681 Disable Spanning Tree protocol on
683 This is the default for all interfaces added to a bridge.
684 .It Cm edge Ar interface
688 An edge port connects directly to end stations cannot create bridging
689 loops in the network, this allows it to transition straight to forwarding.
690 .It Cm -edge Ar interface
691 Disable edge status on
693 .It Cm autoedge Ar interface
696 to automatically detect edge status.
697 This is the default for all interfaces added to a bridge.
698 .It Cm -autoedge Ar interface
699 Disable automatic edge status on
701 .It Cm ptp Ar interface
704 as a point to point link.
705 This is required for straight transitions to forwarding and
706 should be enabled on a direct link to another RSTP capable switch.
707 .It Cm -ptp Ar interface
708 Disable point to point link status on
710 This should be disabled for a half duplex link and for an interface
711 connected to a shared network segment,
712 like a hub or a wireless network.
713 .It Cm autoptp Ar interface
714 Automatically detect the point to point status on
716 by checking the full duplex link status.
717 This is the default for interfaces added to the bridge.
718 .It Cm -autoptp Ar interface
719 Disable automatic point to point link detection on
721 .It Cm maxage Ar seconds
722 Set the time that a Spanning Tree protocol configuration is valid.
723 The default is 20 seconds.
724 The minimum is 6 seconds and the maximum is 40 seconds.
725 .It Cm fwddelay Ar seconds
726 Set the time that must pass before an interface begins forwarding
727 packets when Spanning Tree is enabled.
728 The default is 15 seconds.
729 The minimum is 4 seconds and the maximum is 30 seconds.
730 .It Cm hellotime Ar seconds
731 Set the time between broadcasting of Spanning Tree protocol
732 configuration messages.
733 The hello time may only be changed when operating in legacy stp mode.
734 The default is 2 seconds.
735 The minimum is 1 second and the maximum is 2 seconds.
736 .It Cm priority Ar value
737 Set the bridge priority for Spanning Tree.
738 The default is 32768.
739 The minimum is 0 and the maximum is 61440.
740 .It Cm proto Ar value
741 Set the Spanning Tree protocol.
743 The available options are stp and rstp.
744 .It Cm holdcnt Ar value
745 Set the transmit hold count for Spanning Tree.
746 This is the number of packets transmitted before being rate limited.
748 The minimum is 1 and the maximum is 10.
749 .It Cm ifpriority Ar interface Ar value
750 Set the Spanning Tree priority of
755 The minimum is 0 and the maximum is 240.
756 .It Cm ifpathcost Ar interface Ar value
757 Set the Spanning Tree path cost of
761 The default is calculated from the link speed.
762 To change a previously selected path cost back to automatic, set the
764 The minimum is 1 and the maximum is 200000000.
765 .It Cm ifmaxaddr Ar interface Ar size
766 Set the maximum number of hosts allowed from an interface, packets with unknown
767 source addresses are dropped until an existing host cache entry expires or is
772 The following parameters are specific to vlan interfaces:
773 .Bl -tag -width indent
774 .It Cm vlan Ar vlan_tag
775 Set the VLAN tag value to
777 This value is a 16-bit number which is used to create an 802.1Q
778 VLAN header for packets sent from the
785 must both be set at the same time.
786 .It Cm vlandev Ar iface
787 Associate the physical interface
792 Packets transmitted through the
795 diverted to the specified physical interface
797 with 802.1Q VLAN encapsulation.
798 Packets with 802.1Q encapsulation received
799 by the parent interface with the correct VLAN tag will be diverted to
805 interface is assigned a
806 copy of the parent interface's flags and the parent's ethernet address.
811 must both be set at the same time.
814 interface already has
815 a physical interface associated with it, this command will fail.
817 change the association to another physical interface, the existing
818 association must be cleared first.
820 Note: if the hardware tagging capability
821 is set on the parent interface, the
824 interface's behavior changes:
827 interface recognizes that the
828 parent interface supports insertion and extraction of VLAN tags on its
829 own (usually in firmware) and that it should pass packets to and from
830 the parent unaltered.
831 .It Fl vlandev Op Ar iface
834 pseudo device, disassociate the parent interface from it.
835 This breaks the link between the
837 interface and its parent,
838 clears its VLAN tag, flags and its link address and shuts the interface down.
841 argument is useless and hence deprecated.
846 utility displays the current configuration for a network interface
847 when no optional parameters are supplied.
848 If a protocol family is specified,
850 will report only the details specific to that protocol family.
854 flag is passed before an interface name,
856 will display the capability list and all
857 of the supported media for the specified interface.
861 flag is supplied, address lifetime is displayed for IPv6 addresses,
862 as time offset string.
866 flag may be used instead of an interface name.
869 to display information about all interfaces in the system.
872 flag limits this to interfaces that are down, and
874 limits this to interfaces that are up.
875 When no arguments are given,
881 flag may be used to list all available interfaces on the system, with
882 no other additional information.
883 Use of this flag is mutually exclusive
884 with all other flags and commands, except for
886 (only list interfaces that are down)
889 (only list interfaces that are up).
893 flag may be used to get more verbose status for an interface.
897 flag may be used to list all of the interface cloners available on
898 the system, with no additional information.
899 Use of this flag is mutually exclusive with all other flags and commands.
903 flag may be used to show additional information related to the count of route references on the network interface.
905 For bridge interfaces, the list of addresses learned by the bridge is not shown when displaying information about
906 all interfaces except when the
910 Only the super-user may modify the configuration of a network interface.
912 The media selection system is relatively new and only some drivers support
913 it (or have need for it).
915 Assign the IPv4 address
917 with a network mask of
921 .Dl # ifconfig en0 inet 192.0.2.10 netmask 255.255.255.0
925 with the CIDR network prefix
931 as a synonym for the canonical form of the option
933 .Dl # ifconfig en0 inet 192.0.2.45/28 add
935 Remove the IPv4 address
939 .Dl # ifconfig en0 inet 192.0.2.45 -alias
942 .Li 2001:DB8:DBDB::123/48
945 .Dl # ifconfig en0 inet6 2001:db8:bdbd::123 prefixlen 48 alias
946 Note that lower case hexadecimal IPv6 addresses are acceptable.
948 Remove the IPv6 address added in the above example,
951 character as shorthand for the network prefix,
954 as a synonym for the canonical form of the option
956 .Dl # ifconfig en0 inet6 2001:db8:bdbd::123/48 delete
958 Configure the interface
960 to use 100baseTX, full duplex Ethernet media options:
961 .Dl # ifconfig en1 media 100baseTX mediaopt full-duplex
963 Create the software network interface
965 .Dl # ifconfig gif1 create
967 Destroy the software network interface
969 .Dl # ifconfig gif1 destroy
971 Messages indicating the specified interface does not exist, the
972 requested address is unknown, or the user is not privileged and
973 tried to alter an interface's configuration.
984 Basic IPv6 node operation requires a link-local address on each
985 interface configured for IPv6.
986 Normally, such an address is automatically configured by the
987 kernel on each interface added to the system; this behaviour may
988 be disabled by setting the sysctl MIB variable
989 .Va net.inet6.ip6.auto_linklocal
992 If you delete such an address using
994 the kernel may act very odd.
995 Do this at your own risk.
projects / apple / network_cmds.git / blob