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.
274 .\" This is used to specify an Internet host who is willing to receive
275 .\" ip packets encapsulating NS packets bound for a remote network.
276 .\" An apparent point to point link is constructed, and
277 .\" the address specified will be taken as the NS address and network
278 .\" of the destination.
279 .\" IP encapsulation of
281 .\" packets is done differently.
282 .It Cm lladdr Ar addr
283 Set the link-level address on an interface.
285 e.g. set a new MAC address on an ethernet interface, though the
286 mechanism used is not ethernet-specific.
289 is specified as a series of colon-separated hex digits.
290 If the interface is already
291 up when this option is used, it will be briefly brought down and
292 then brought back up again in order to ensure that the receive
293 filter in the underlying ethernet hardware is properly reprogrammed.
295 If the driver supports the media selection system, set the media type
298 Some interfaces support the mutually exclusive use of one of several
299 different physical media connectors.
300 For example, a 10Mbit/s Ethernet
301 interface might support the use of either
303 or twisted pair connectors.
304 Setting the media type to
306 would change the currently active connector to the AUI port.
309 would activate twisted pair.
310 Refer to the interfaces' driver
311 specific documentation or man page for a complete list of the
313 .It Cm mediaopt Ar opts
314 If the driver supports the media selection system, set the specified
315 media options on the interface.
319 is a comma delimited list of options to apply to the interface.
320 Refer to the interfaces' driver specific man page for a complete
321 list of available options.
322 .It Fl mediaopt Ar opts
323 If the driver supports the media selection system, disable the
324 specified media options on the interface.
325 .It Cm rxcsum , txcsum
326 If the driver supports user-configurable checksum offloading,
327 enable receive (or transmit) checksum offloading on the interface.
328 Some drivers may not be able to enable these flags independently
329 of each other, so setting one may also set the other.
330 The driver will offload as much checksum work as it can reliably
331 support, the exact level of offloading varies between drivers.
332 .It Fl rxcsum , txcsum
333 If the driver supports user-configurable checksum offloading,
334 disable receive (or transmit) checksum offloading on the interface.
335 These settings may not always be independent of each other.
337 If the driver supports
339 segmentation offloading, enable TSO on the interface.
340 Some drivers may not be able to support TSO for
344 packets, so they may enable only one of them.
346 If the driver supports
348 segmentation offloading, disable TSO on the interface.
349 It will always disable TSO for
354 If the driver supports
356 large receive offloading, enable LRO on the interface.
358 If the driver supports
360 large receive offloading, disable LRO on the interface.
362 If supported by the driver, enable 802.1 AVB on the interface.
364 If supported by the driver, disable 802.1 AVB on the interface.
365 .It Cm vlanmtu , vlanhwtag
366 If the driver offers user-configurable VLAN support, enable
367 reception of extended frames or tag processing in hardware,
369 Note that this must be issued on a physical interface associated with
374 .It Fl vlanmtu , vlanhwtag
375 If the driver offers user-configurable VLAN support, disable
376 reception of extended frames or tag processing in hardware,
379 Create the specified network pseudo-device.
380 If the interface is given without a unit number, try to create a new
381 device with an arbitrary unit number.
382 If creation of an arbitrary device is successful, the new device name is
383 printed to standard output unless the interface is renamed or destroyed
388 Destroy the specified network pseudo-device.
404 Set the routing metric of the interface to
407 The routing metric is used by the routing protocol
409 Higher metrics have the effect of making a route
410 less favorable; metrics are counted as additional hops
411 to the destination network or host.
413 Set the maximum transmission unit of the interface to
415 default is interface specific.
416 The MTU is used to limit the size of packets that are transmitted on an
418 Not all interfaces support setting the MTU, and some interfaces have
420 .It Cm netmask Ar mask
423 Specify how much of the address to reserve for subdividing
424 networks into sub-networks.
425 The mask includes the network part of the local address
426 and the subnet part, which is taken from the host field of the address.
427 The mask can be specified as a single hexadecimal number
430 with a dot-notation Internet address,
431 or with a pseudo-network name listed in the network table
433 The mask contains 1's for the bit positions in the 32-bit address
434 which are to be used for the network and subnet parts,
435 and 0's for the host part.
436 The mask should contain at least the standard network portion,
437 and the subnet field should be contiguous with the network
440 The netmask can also be specified in CIDR notation after the address.
443 option above for more information.
444 .It Cm prefixlen Ar len
448 bits are reserved for subdividing networks into sub-networks.
451 must be integer, and for syntactical reason it must be between 0 to 128.
452 It is almost always 64 under the current IPv6 assignment rule.
453 If the parameter is omitted, 64 is used.
455 The prefix can also be specified using the slash notation after the address.
458 option above for more information.
461 .\" .It Cm nsellength Ar n
464 .\" This specifies a trailing number of bytes for a received
466 .\" used for local identification, the remaining leading part of which is
469 .\" (Network Entity Title).
470 .\" The default value is 1, which is conformant to US
472 .\" When an ISO address is set in an ifconfig command,
475 .\" which is being specified.
478 .\" 20 hex digits should be
481 .\" to be assigned to the interface.
482 .\" There is some evidence that a number different from 1 may be useful
485 .\" 37 type addresses.
490 Introduced for compatibility
494 .It Cm link Op Cm 0 No - Cm 2
496 Enable special processing of the link level of the interface.
497 These three options are interface specific in actual effect, however,
498 they are in general used to select special modes of operation.
500 of this is to enable SLIP compression, or to select the connector type
501 for some Ethernet cards.
502 Refer to the man page for the specific driver
503 for more information.
505 .It Fl link Op Cm 0 No - Cm 2
507 Disable special processing at the link level with the specified interface.
511 This may be used to enable an interface after an
513 It happens automatically when setting the first address on an interface.
514 If the interface was reset when previously marked down,
515 the hardware will be re-initialized.
518 The following parameters are specific to link aggregate interfaces:
519 .Bl -tag -width indent
520 .It Cm bonddev Ar iface
521 If the interface is a bond pseudo device, associate physical interface
523 with it. By default, the bond pseudo device is in LACP
524 (Link Aggregation Control Protocol) mode (see \fBbondmode\fR below). In
525 this mode, the device conforms to the IEEE 802.3ad Link Aggregation
528 If this is the first physical interface to be associated with the bond
529 interface, the bond interface inherits the ethernet address from the
530 physical interface. Physical interfaces that are added to the bond have
531 their ethernet address re-programmed so that all members of the bond have
532 the same ethernet address. If the physical interface is subsequently
533 removed from the bond using
535 a new ethernet address is chosen from the remaining interfaces, and all
536 interfaces are re-programmed again with the new ethernet address. If no
537 remaining interfaces exist, the bond interface's ethernet address is cleared.
539 If the specified physical interface
541 is not capable of having its ethernet address re-programmed, the
545 Once the physical interface
547 is successfully associated with the bond interface, all received packets
548 are diverted to the bond interface. The physical interface is no longer
549 useable on its own, and remains that way until it is removed from the bond using
552 It is possible that the specified interface
554 is not capable of aggregating, and may remain unused until the operating
557 The link status of the bond interface depends on the state of link aggregation.
558 If no active partner is detected, the link status will remain inactive.
560 To monitor the 802.3ad Link Aggregation state, use the
564 A physical interface that is associated with a vlan pseudo device cannot
565 at the same time be associated with a bond pseudo device. A physical interface
566 cannot be associated with more than one bond pseudo device at the same time.
568 It is not possible to associate a bond with pseudo interfaces such as vlan.
569 Only physical ethernet interfaces may be associated with a bond.
570 .It Fl bonddev Ar iface
571 If the interface is a bond pseudo device, disassociate the physical interface
573 from it. Before the interface is removed from the bond, the bond device
574 announces to the link partner that the interface is now individual and
575 no longer aggregatable.
578 is the last interface in the bond, the bond interface clears its link address.
579 .It Cm bondmode Ar lacp | static
580 If the interface is a bond pseudo device, this option will set the \fImode\fR
581 on the bond interface. The two currently supported modes are
588 To enable static mode (and turn off LACP), specify
590 In static mode, a member interface is made an active part of the
591 link aggregate as long as the link status is active.
593 To re-enable LACP mode, specify
597 The following parameters are specific to IP tunnel interfaces,
599 .Bl -tag -width indent
600 .It Cm tunnel Ar src_addr dest_addr
601 Configure the physical source and destination address for IP tunnel
607 are interpreted as the outer source/destination for the encapsulating
610 Unconfigure the physical source and destination address for IP tunnel
611 interfaces previously configured with
619 The following parameters are specific to bridge interfaces:
620 .Bl -tag -width indent
621 .It Cm addm Ar interface
622 Add the interface named by
624 as a member of the bridge.
625 The interface is put into promiscuous mode
626 so that it can receive every packet sent on the network.
627 .It Cm deletem Ar interface
628 Remove the interface named by
631 Promiscuous mode is disabled on the interface when
632 it is removed from the bridge.
633 .It Cm maxaddr Ar size
634 Set the size of the bridge address cache to
636 The default is 100 entries.
637 .It Cm timeout Ar seconds
638 Set the timeout of address cache entries to
643 is zero, then address cache entries will not be expired.
644 The default is 240 seconds.
646 Display the addresses that have been learned by the bridge.
647 .It Cm static Ar interface-name Ar address
648 Add a static entry into the address cache pointing to
650 Static entries are never aged out of the cache or re-placed, even if the
651 address is seen on a different interface.
652 .It Cm deladdr Ar address
655 from the address cache.
657 Delete all dynamically-learned addresses from the address cache.
659 Delete all addresses, including static addresses, from the address cache.
660 .It Cm discover Ar interface
661 Mark an interface as a
664 When the bridge has no address cache entry
665 (either dynamic or static)
666 for the destination address of a packet,
667 the bridge will forward the packet to all
668 member interfaces marked as
670 This is the default for all interfaces added to a bridge.
671 .It Cm -discover Ar interface
674 attribute on a member interface.
675 For packets without the
677 attribute, the only packets forwarded on the interface are broadcast
678 or multicast packets and packets for which the destination address
679 is known to be on the interface's segment.
680 .It Cm learn Ar interface
681 Mark an interface as a
684 When a packet arrives on such an interface, the source
685 address of the packet is entered into the address cache as being a
686 destination address on the interface's segment.
687 This is the default for all interfaces added to a bridge.
688 .It Cm -learn Ar interface
691 attribute on a member interface.
692 .It Cm sticky Ar interface
693 Mark an interface as a
696 Dynamically learned address entries are treated at static once entered into
698 Sticky entries are never aged out of the cache or replaced, even if the
699 address is seen on a different interface.
700 .It Cm -sticky Ar interface
703 attribute on a member interface.
704 .It Cm private Ar interface
705 Mark an interface as a
708 A private interface does not forward any traffic to any other port that is also
710 .It Cm -private Ar interface
713 attribute on a member interface.
714 .It Cm span Ar interface
715 Add the interface named by
717 as a span port on the bridge.
718 Span ports transmit a copy of every frame received by the bridge.
719 This is most useful for snooping a bridged network passively on
720 another host connected to one of the span ports of the bridge.
721 .It Cm -span Ar interface
722 Delete the interface named by
724 from the list of span ports of the bridge.
725 .It Cm stp Ar interface
726 Enable Spanning Tree protocol on
730 driver has support for the IEEE 802.1D Spanning Tree protocol (STP).
731 Spanning Tree is used to detect and remove loops in a network topology.
732 .It Cm -stp Ar interface
733 Disable Spanning Tree protocol on
735 This is the default for all interfaces added to a bridge.
736 .It Cm edge Ar interface
740 An edge port connects directly to end stations cannot create bridging
741 loops in the network, this allows it to transition straight to forwarding.
742 .It Cm -edge Ar interface
743 Disable edge status on
745 .It Cm autoedge Ar interface
748 to automatically detect edge status.
749 This is the default for all interfaces added to a bridge.
750 .It Cm -autoedge Ar interface
751 Disable automatic edge status on
753 .It Cm ptp Ar interface
756 as a point to point link.
757 This is required for straight transitions to forwarding and
758 should be enabled on a direct link to another RSTP capable switch.
759 .It Cm -ptp Ar interface
760 Disable point to point link status on
762 This should be disabled for a half duplex link and for an interface
763 connected to a shared network segment,
764 like a hub or a wireless network.
765 .It Cm autoptp Ar interface
766 Automatically detect the point to point status on
768 by checking the full duplex link status.
769 This is the default for interfaces added to the bridge.
770 .It Cm -autoptp Ar interface
771 Disable automatic point to point link detection on
773 .It Cm maxage Ar seconds
774 Set the time that a Spanning Tree protocol configuration is valid.
775 The default is 20 seconds.
776 The minimum is 6 seconds and the maximum is 40 seconds.
777 .It Cm fwddelay Ar seconds
778 Set the time that must pass before an interface begins forwarding
779 packets when Spanning Tree is enabled.
780 The default is 15 seconds.
781 The minimum is 4 seconds and the maximum is 30 seconds.
782 .It Cm hellotime Ar seconds
783 Set the time between broadcasting of Spanning Tree protocol
784 configuration messages.
785 The hello time may only be changed when operating in legacy stp mode.
786 The default is 2 seconds.
787 The minimum is 1 second and the maximum is 2 seconds.
788 .It Cm priority Ar value
789 Set the bridge priority for Spanning Tree.
790 The default is 32768.
791 The minimum is 0 and the maximum is 61440.
792 .It Cm proto Ar value
793 Set the Spanning Tree protocol.
795 The available options are stp and rstp.
796 .It Cm holdcnt Ar value
797 Set the transmit hold count for Spanning Tree.
798 This is the number of packets transmitted before being rate limited.
800 The minimum is 1 and the maximum is 10.
801 .It Cm ifpriority Ar interface Ar value
802 Set the Spanning Tree priority of
807 The minimum is 0 and the maximum is 240.
808 .It Cm ifpathcost Ar interface Ar value
809 Set the Spanning Tree path cost of
813 The default is calculated from the link speed.
814 To change a previously selected path cost back to automatic, set the
816 The minimum is 1 and the maximum is 200000000.
817 .It Cm ifmaxaddr Ar interface Ar size
818 Set the maximum number of hosts allowed from an interface, packets with unknown
819 source addresses are dropped until an existing host cache entry expires or is
824 The following parameters are specific to vlan interfaces:
825 .Bl -tag -width indent
826 .It Cm vlan Ar vlan_tag
827 Set the VLAN tag value to
829 This value is a 16-bit number which is used to create an 802.1Q
830 VLAN header for packets sent from the
837 must both be set at the same time.
838 .It Cm vlandev Ar iface
839 Associate the physical interface
844 Packets transmitted through the
847 diverted to the specified physical interface
849 with 802.1Q VLAN encapsulation.
850 Packets with 802.1Q encapsulation received
851 by the parent interface with the correct VLAN tag will be diverted to
857 interface is assigned a
858 copy of the parent interface's flags and the parent's ethernet address.
863 must both be set at the same time.
866 interface already has
867 a physical interface associated with it, this command will fail.
869 change the association to another physical interface, the existing
870 association must be cleared first.
872 Note: if the hardware tagging capability
873 is set on the parent interface, the
876 interface's behavior changes:
879 interface recognizes that the
880 parent interface supports insertion and extraction of VLAN tags on its
881 own (usually in firmware) and that it should pass packets to and from
882 the parent unaltered.
883 .It Fl vlandev Op Ar iface
886 pseudo device, disassociate the parent interface from it.
887 This breaks the link between the
889 interface and its parent,
890 clears its VLAN tag, flags and its link address and shuts the interface down.
893 argument is useless and hence deprecated.
898 utility displays the current configuration for a network interface
899 when no optional parameters are supplied.
900 If a protocol family is specified,
902 will report only the details specific to that protocol family.
906 flag is passed before an interface name,
908 will display the capability list and all
909 of the supported media for the specified interface.
913 flag is supplied, address lifetime is displayed for IPv6 addresses,
914 as time offset string.
918 flag may be used instead of an interface name.
921 to display information about all interfaces in the system.
924 flag limits this to interfaces that are down, and
926 limits this to interfaces that are up.
927 When no arguments are given,
933 flag may be used to list all available interfaces on the system, with
934 no other additional information.
935 Use of this flag is mutually exclusive
936 with all other flags and commands, except for
938 (only list interfaces that are down)
941 (only list interfaces that are up).
945 flag may be used to get more verbose status for an interface.
949 flag may be used to list all of the interface cloners available on
950 the system, with no additional information.
951 Use of this flag is mutually exclusive with all other flags and commands.
955 flag may be used to show additional information related to the count of route references on the network interface.
957 For bridge interfaces, the list of addresses learned by the bridge is not shown when displaying information about
958 all interfaces except when the
962 Only the super-user may modify the configuration of a network interface.
964 The media selection system is relatively new and only some drivers support
965 it (or have need for it).
967 Assign the IPv4 address
969 with a network mask of
973 .Dl # ifconfig en0 inet 192.0.2.10 netmask 255.255.255.0
977 with the CIDR network prefix
983 as a synonym for the canonical form of the option
985 .Dl # ifconfig en0 inet 192.0.2.45/28 add
987 Remove the IPv4 address
991 .Dl # ifconfig en0 inet 192.0.2.45 -alias
994 .Li 2001:DB8:DBDB::123/48
997 .Dl # ifconfig en0 inet6 2001:db8:bdbd::123 prefixlen 48 alias
998 Note that lower case hexadecimal IPv6 addresses are acceptable.
1000 Remove the IPv6 address added in the above example,
1003 character as shorthand for the network prefix,
1006 as a synonym for the canonical form of the option
1008 .Dl # ifconfig en0 inet6 2001:db8:bdbd::123/48 delete
1010 Configure the interface
1012 to use 100baseTX, full duplex Ethernet media options:
1013 .Dl # ifconfig en1 media 100baseTX mediaopt full-duplex
1015 Create the software network interface
1017 .Dl # ifconfig gif1 create
1019 Destroy the software network interface
1021 .Dl # ifconfig gif1 destroy
1023 Messages indicating the specified interface does not exist, the
1024 requested address is unknown, or the user is not privileged and
1025 tried to alter an interface's configuration.
1036 Basic IPv6 node operation requires a link-local address on each
1037 interface configured for IPv6.
1038 Normally, such an address is automatically configured by the
1039 kernel on each interface added to the system; this behaviour may
1040 be disabled by setting the sysctl MIB variable
1041 .Va net.inet6.ip6.auto_linklocal
1044 If you delete such an address using
1046 the kernel may act very odd.
1047 Do this at your own risk.
projects / apple / network_cmds.git / blob