System Administration Commands dladm(1M) NAME dladm - administer data links SYNOPSIS dladm show-link [-P] [-s [-i interval]] [[-p] -o field[,...]] [link] dladm rename-link [-R root-dir] link new-link] dladm delete-phys phys-link dladm show-phys [-P] [-m] [[-p] -o field[,...]] [phys-link] dladm create-aggr [-t] [-R root-dir] [-P policy] [-L mode] [-T time] [-u address] -l ether-link1 [-l ether-link2...] aggr-link dladm modify-aggr [-t] [-R root-dir] [-P policy] [-L mode] [-T time] [-u address] aggr-link dladm delete-aggr [-t] [-R root-dir] aggr-link dladm add-aggr [-t] [-R root-dir] -l ether-link1 [-l ether-link2...] aggr-link dladm remove-aggr [-t] [-R root-dir] -l ether-link1 [-l ether-link2...] aggr-link dladm show-aggr [-PLx] [-s [-i interval]] [[-p] -o field[,...]] [aggr-link] dladm create-vlan [-ft] [-R root-dir] -l ether-link -v vid [vlan-link] dladm delete-vlan [-t] [-R root-dir] vlan-link dladm show-vlan [-P] [[-p] -o field[,...]] [vlan-link] dladm scan-wifi [[-p] -o field[,...]] [wifi-link] dladm connect-wifi [-e essid] [-i bssid] [-k key,...] [-s none | wep | wpa ] [-a open | shared] [-b bss | ibss] [-c] [-m a | b | g] [-T time] [wifi-link] dladm disconnect-wifi [-a] [wifi-link] dladm show-wifi [[-p] -o field[,...]] [wifi-link] dladm show-ether [-x] [[-p] -o field[,...]] [ether-link] dladm set-linkprop [-t] [-R root-dir] -p prop=value[,...] link dladm reset-linkprop [-t] [-R root-dir] [-p prop[,...]] link dladm show-linkprop [-P] [[-c] -o field[,...]] [-p prop[,...]] [link] dladm create-secobj [-t] [-R root-dir] [-f file] -c class secobj dladm delete-secobj [-t] [-R root-dir] secobj[,...] dladm show-secobj [-P] [[-p] -o field[,...]] [secobj,...] SunOS 5.11 Last change: 16 Jan 2009 1 System Administration Commands dladm(1M) dladm create-vnic [-t] [-R root-dir] [-l link] [-m value | auto | {factory -n slot-identifier]} | {random [-r prefix]}] [-v vlan-id] [-p prop=value[,...]] vnic-link dladm delete-vnic [-t] [-R root-dir] vnic-link dladm show-vnic [-pP] [-s [-i interval]] [-o field[,...]] [-l link] [vnic-link] dladm create-etherstub [-t] [-R root-dir] etherstub dladm delete-etherstub [-t] [-R root-dir] etherstub dladm show-etherstub [etherstub] dladm show-usage -a -f filename [-d | -F format] [-s time] [-e time] [link] DESCRIPTION The dladm command is used to administer data-links. A data- link is represented in the system as a STREAMS DLPI (v2) interface which can be plumbed under protocol stacks such as TCP/IP. Each data-link relies on either a single network device or an aggregation of devices to send packets to or receive packets from a network. Each dladm subcommand operates on one of the following objects: link A datalink, identified by a name. In general, the name can use any alphanumeric characters (or the underscore, _), but must start with an alphabetic character and end with a number. A datalink name can be at most 32 charac- ters, and the ending number can be at most 16 charac- ters. Datalink names between 3 and 8 characters are recommended. Some subcommands operate only on certain types or classes of datalinks. For those cases, the following object names are used: phys-link A physical datalink. vlan-link A VLAN datalink. SunOS 5.11 Last change: 16 Jan 2009 2 System Administration Commands dladm(1M) aggr-link An aggregation datalink (or a key; see NOTES). ether-link A physical Ethernet datalink. wifi-link A WiFi datalink. vnic-link A virtual network interface. dev A network device, identified by concatenation of a driver name and an instance number. etherstub An Ethernet stub can be used instead of a physical NIC to create VNICs. VNICs created on an etherstub will appear to be connected through a virtual switch, allow- ing complete virtual networks to be built without physi- cal hardware. secobj A secure object, identified by an administratively- chosen name. The name can use any alphanumeric charac- ters, as well as underscore (_), period (.), and hyphen (-). A secure object name can be at most 32 characters. vnic A VNIC is a virtual-link created on a link or an ether- stub. It is a pseudo device that can be treated as if it were an network interface card on a machine. SunOS 5.11 Last change: 16 Jan 2009 3 System Administration Commands dladm(1M) SUBCOMMANDS The following subcommands are supported: dladm show-link [-P] [-s [-i interval]] [[-p] -o field[,...]][link] Show link configuration information either for all datalinks or for the specified link. By default, the system is configured with one datalink for each known network device. The option to print link statistics is moved to dlstat(1M) show-link. -o field[,...], --output=field[,...] A case-insensitive, comma-separated list of output fields to display. When not modified by the -s option (described below), the field name must be one of the fields listed below, or the special value all to display all fields. By default (without -o), show-link displays all fields. LINK The name of the datalink. CLASS The class of the datalink. dladm distinguishes between the following classes: phys A physical datalink. The show-phys subcom- mand displays more detail for this class of datalink. aggr An IEEE 802.3ad link aggregation. The show- aggr subcommand displays more detail for this class of datalink. vlan A VLAN datalink. The show-vlan subcommand displays more detail for this class of datalink. SunOS 5.11 Last change: 16 Jan 2009 4 System Administration Commands dladm(1M) vnic A virtual network interface. The show-vnic subcommand displays more detail for this class of datalink. MTU The maximum transmission unit size for the datalink being displayed. STATE The link state of the datalink. The state can be up, down, or unknown. OVER The physical datalink(s) over which the datalink is operating. This applies to aggr and vlan classes of datalinks. A VLAN is created over a single physical datalink, and an aggregation is comprised of one or more physical datalinks. When the -o option is used in conjunction with the -s option, used to display link statistics, the field name must be one of the fields listed below, or the special value all to display all fields LINK The name of the datalink. IPACKETS Number of packets received on this link. RBYTES Number of bytes received on this link. IERRORS Number of input errors. SunOS 5.11 Last change: 16 Jan 2009 5 System Administration Commands dladm(1M) OPACKETS Number of packets sent on this link. OBYTES Number of bytes received on this link. OERRORS Number of output errors. -p, --parseable Display using a stable machine-parseable format. The -o option is required with -p. See "Parseable Output Format", below. -P, --persistent Display the persistent link configuration. -s, --statistics Display link statistics. This option is made Obsolete by dlstat(1M). -i interval, --interval=interval Used with the -s option to specify an interval, in seconds, at which statistics should be displayed. If this option is not specified, statistics will be displayed only once. This option is made Obsolete by dlstat(1M). dladm rename-link [-R root-dir] link new-link] Rename link to new-link. This is used to give a link a meaningful name, or to associate existing link confi- guration such as link properties of a removed device with a new device. See the EXAMPLES section for specific examples of how this subcommand is used. -R root-dir, --root-dir=root-dir SunOS 5.11 Last change: 16 Jan 2009 6 System Administration Commands dladm(1M) Specifies an alternate root directory where the link rename operation should apply. dladm delete-phys phys-link This command is used to delete the persistent configura- tion of a link associated with physical hardware which has been removed from the system. See the EXAMPLES sec- tion. dladm show-phys [-P] [[-p] -o field[,...]] [phys-link] Show the physical device and attributes of all physical links, or of the named physical link. Without -P, only physical links that are available on the running system are displayed. -o field, --output=field A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below, or the special value all, to display all fields. For each link, the following fields can be displayed: LINK The name of the datalink. MEDIA The media type provided by the physical datalink. STATE The state of the link. This can be up, down, or unknown. SPEED The current speed of the link, in megabits per second. SunOS 5.11 Last change: 16 Jan 2009 7 System Administration Commands dladm(1M) DUPLEX For Ethernet links, the full/half duplex status of the link is displayed if the link state is up. The duplex is displayed as unknown in all other cases. DEVICE The name of the physical device under this link. -p, --parseable Display using a stable machine-parseable format. The -o option is required with -p. See "Parseable Output Format", below. -P, --persistent This option displays persistent configuration for all links, including those that have been removed from the system. The output provides a FLAGS column in which the r flag indicates that the physical dev- ice associated with a physical link has been removed. For such links, delete-phys can be used to purge the link's configuration from the system. dladm create-aggr [-t] [-R root-dir] [-P policy] [-L mode] [-T time] [-u address] -l ether-link1 [-l ether-link2...] aggr-link Combine a set of links into a single IEEE 802.3ad link aggregation named aggr-link. The use of an integer key to generate a link name for the aggregation is also sup- ported for backward compatibility. Many of the *-aggr subcommands below also support the use of a key to refer to a given aggregation, but use of the aggregation link name is preferred. See the NOTES section for more infor- mation on keys. -l ether-link, --link=ether-link Each Ethernet link (or port) in the aggregation is specified using an -l option followed by the name of the link to be included in the aggregation. Multiple links are included in the aggregation by specifying SunOS 5.11 Last change: 16 Jan 2009 8 System Administration Commands dladm(1M) multiple -l options. For backward compatibility with previous versions of Solaris, the dladm command also supports the using the -d option (or --dev) with a device name to specify links by their underlying device name. The other *-aggr subcommands that take -loptions also accept -d. -t, --temporary Specifies that the aggregation is temporary. Tem- porary aggregations last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent creation. -P policy, --policy=policy Specifies the port selection policy to use for load spreading of outbound traffic. The policy specifies which dev object is used to send packets. A policy is a list of one or more layers specifiers separated by commas. A layer specifier is one of the follow- ing: L2 Select outbound device according to source and destination MAC addresses of the packet. L3 Select outbound device according to source and destination IP addresses of the packet. L4 Select outbound device according to the upper layer protocol information contained in the packet. For TCP and UDP, this includes source and destination ports. For IPsec,, this includes the SPI (Security Parameters Index.) For example, to use upper layer protocol informa- tion, the following policy can be used: SunOS 5.11 Last change: 16 Jan 2009 9 System Administration Commands dladm(1M) -P L4 To use the source and destination MAC addresses as well as the source and destination IP addresses, the following policy can be used: -P L2,L3 -L mode, --lacp-mode=mode Specifies whether LACP should be used and, if used, the mode in which it should operate. Supported values are off, active or passive. -T time, --lacp-timer=time Specifies the LACP timer value. The supported values are short or long. -u address, --unicast=address Specifies a fixed unicast hardware address to be used for the aggregation. If this option is not specified, then an address is automatically chosen from the set of addresses of the component devices. dladm modify-aggr [-t] [-R root-dir] [-P policy] [-L mode] [-T time] [-u address] aggr-link Modify the parameters of the specified aggregation. -t, --temporary Specifies that the modification is temporary. Tem- porary aggregations last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent modifications. SunOS 5.11 Last change: 16 Jan 2009 10 System Administration Commands dladm(1M) -P policy, --policy=policy Specifies the port selection policy to use for load spreading of outbound traffic. See dladm create-aggr for a description of valid policy values. -L mode, --lacp-mode=mode Specifies whether LACP should be used and, if used, the mode in which it should operate. Supported values are off, active, or passive. -T time, --lacp-timer=time Specifies the LACP timer value. The supported values are short or long. -u address, --unicast=address Specifies a fixed unicast hardware address to be used for the aggregation. If this option is not specified, then an address is automatically chosen from the set of addresses of the component devices. dladm delete-aggr [-t] [-R root-dir] aggr-link Deletes the specified aggregation. -t, --temporary Specifies that the deletion is temporary. Temporary deletions last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent deletions. dladm add-aggr [-t] [-R root-dir] -l ether-link1 [-- link=ether-link2...] aggr-link Adds links to the specified aggregation. SunOS 5.11 Last change: 16 Jan 2009 11 System Administration Commands dladm(1M) -l ether-link, --link=ether-link Specifies an Ethernet link to add to the aggrega- tion. Multiple links can be added by supplying mul- tiple -l options. -t, --temporary Specifies that the additions are temporary. Tem- porary additions last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent additions. dladm remove-aggr [-t] [-R root-dir] -l ether-link1 [-- link=ether-link2...] aggr-link Removes links from the specified aggregation. -l ether-link, --link=ether-link Specifies an Ethernet link to remove from the aggre- gation. Multiple links can be added by supplying multiple -l options. -t, --temporary Specifies that the removals are temporary. Temporary removal last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent removals. dladm show-aggr [-PLx] [-s [-i interval]] [[-p] -o field[,...]] [aggr-link] Show aggregation configuration (the default) or LACP information either for all aggregations or for the specified aggregation. SunOS 5.11 Last change: 16 Jan 2009 12 System Administration Commands dladm(1M) By default (with no options), the following fields can be displayed: LINK The name of the aggregation link. POLICY The LACP policy of the aggregation. See the create- aggr -P option for a description of the possible values. ADDRPOLICY Either auto, if the aggregation is configured to automatically configure its unicast MAC address (the default if the -u option was not used to create or modify the aggregation), or fixed, if -u was used to set a fixed MAC address. LACPACTIVITY The LACP mode of the aggregation. Possible values are off, active, or passive, as set by the -l option to create-aggr or modify-aggr. LACPTIMER The LACP timer value of the aggregation as set by the -T option of create-aggr or modify-aggr. FLAGS A set of state flags associated with the aggrega- tion. The only possible flag is f, which is displayed if the administrator forced the creation the aggregation using the -f option to create-aggr. Other flags might be defined in the future. The show-aggr command accepts the following options: -L, --lacp Displays detailed LACP information for the aggrega- tion link and each underlying port. Most of the state information displayed by this option is SunOS 5.11 Last change: 16 Jan 2009 13 System Administration Commands dladm(1M) defined by IEEE 802.3. With this option, the follow- ing fields can be displayed: LINK The name of the aggregation link. PORT The name of one of the underlying aggregation ports. AGGREGATABLE Whether the port can be added to the aggrega- tion. SYNC If yes, the system considers the port to be syn- chronized and part of the aggregation. COLL If yes, collection of incoming frames is enabled on the associated port. DIST If yes, distribution of outgoing frames is enabled on the associated port. DEFAULTED If yes, the port is using defaulted partner information (that is, has not received LACP data from the LACP partner). EXPIRED If yes, the receive state of the port is in the EXPIRED state. SunOS 5.11 Last change: 16 Jan 2009 14 System Administration Commands dladm(1M) -x, --extended Display additional aggregation information including detailed information on each underlying port. With -x, the following fields can be displayed: LINK The name of the aggregation link. PORT The name of one of the underlying aggregation ports. SPEED The speed of the link or port in megabits per second. DUPLEX The full/half duplex status of the link or port is displayed if the link state is up. The duplex status is displayed as unknown in all other cases. STATE The link state. This can be up, down, or unknown. ADDRESS The MAC address of the link or port. PORTSTATE This indicates whether the individual aggrega- tion port is in the standby or attached state. -o field[,...], --output=field[,...] A case-insensitive, comma-separated list of output SunOS 5.11 Last change: 16 Jan 2009 15 System Administration Commands dladm(1M) fields to display. The field name must be one of the fields listed above, or the special value all, to display all fields. The fields applicable to the -o option are limited to those listed under each output mode. For example, if using -L, only the fields listed under -L, above, can be used with -o. -p, --parseable Display using a stable machine-parseable format. The -o option is required with -p. See "Parseable Output Format", below. -P, --persistent Display the persistent aggregation configuration rather than the state of the running system. -s, --statistics Display aggregation statistics. This option is made Obsolete by dlstat(1M). -i interval, --interval=interval Used with the -s option to specify an interval, in seconds, at which statistics should be displayed. If this option is not specified, statistics will be displayed only once. This option is made Obsolete by dlstat(1M). dladm create-vlan [-ft] [-R root-dir] -l ether-link -v vid [vlan-link] Create a tagged VLAN link with an ID of vid over Ether- net link ether-link. The name of the VLAN link can be specified as vlan-link. If the name is not specified, a name will be automatically generated (assuming that ether-link is namePPA) as: <1000 * vlan-tag + PPA> For example, if ether-link is bge1 and vid is 2, the name generated is bge2001. -f, --force SunOS 5.11 Last change: 16 Jan 2009 16 System Administration Commands dladm(1M) Force the creation of the VLAN link. Some devices do not allow frame sizes large enough to include a VLAN header. When creating a VLAN link over such a dev- ice, the -f option is needed, and the MTU of the IP interfaces on the resulting VLAN must be set to 1496 instead of 1500. -t, --temporary Specifies that the VLAN link is temporary. Temporary VLAN links last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should create the VLAN link. dladm delete-vlan [-t] [-R root-dir] vlan-link Delete the VLAN link specified. The delete-vlan subcommand accepts the following options: -t, --temporary Specifies that the deletion is temporary. Temporary deletions last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent deletions. dladm show-vlan [-P] [[-p] -o field[,...]] [vlan-link] Display VLAN configuration for all VLAN links or for the specified VLAN link. The show-vlan subcommand accepts the following options: -o field[,...], --output=field[,...] A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below, or the special value all, to SunOS 5.11 Last change: 16 Jan 2009 17 System Administration Commands dladm(1M) display all fields. For each VLAN link, the follow- ing fields can be displayed: LINK The name of the VLAN link. VID The ID associated with the VLAN. OVER The name of the physical link over which this VLAN is configured. FLAGS A set of flags associated with the VLAN link. Possible flags are: f The VLAN was created using the -f option to create-vlan. i The VLAN was implicitly created when the DLPI link was opened. These VLAN links are automatically deleted on last close of the DLPI link (for example, when the IP inter- face associated with the VLAN link is unplumbed). Additional flags might be defined in the future. -p, --parseable Display using a stable machine-parseable format. The -o option is required with -p. See "Parseable Output Format", below. -P, --persistent SunOS 5.11 Last change: 16 Jan 2009 18 System Administration Commands dladm(1M) Display the persistent VLAN configuration rather than the state of the running system. dladm scan-wifi [[-p] -o field[,...]] [wifi-link] Scans for WiFi networks, either on all WiFi links, or just on the specified wifi-link. By default, currently all fields but BSSTYPE are displayed. -o field[,...], --output=field[,...] A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below, or the special value all to display all fields. For each WiFi network found, the following fields can be displayed: LINK The name of the link the WiFi network is on. ESSID The ESSID (name) of the WiFi network. BSSID Either the hardware address of the WiFi network's Access Point (for BSS networks), or the WiFi network's randomly generated unique token (for IBSS networks). SEC Either none for a WiFi network that uses no security, wep for a WiFi network that requires WEP (Wired Equivalent Privacy), or wpa for a WiFi network that requires WPA (Wi-Fi Protected Access). MODE The supported connection modes: one or more of a, b, or g. SunOS 5.11 Last change: 16 Jan 2009 19 System Administration Commands dladm(1M) STRENGTH The strength of the signal: one of excellent, very good, good, weak, or very weak. SPEED The maximum speed of the WiFi network, in mega- bits per second. BSSTYPE Either bss for BSS (infrastructure) networks, or ibss for IBSS (ad-hoc) networks. -p, --parseable Display using a stable machine-parseable format. The -o option is required with -p. See "Parseable Output Format", below. dladm connect-wifi [-e essid] [-i bssid] [-k key,...] [-s none | wep | wpa] [-a open|shared] [-b bss|ibss] [-c] [-m a|b|g] [-T time] [wifi-link] Connects to a WiFi network. This consists of four steps: discovery, filtration, prioritization, and association. However, to enable connections to non-broadcast WiFi networks and to improve performance, if a BSSID or ESSID is specified using the -e or -i options, then the first three steps are skipped and connect-wifi immediately attempts to associate with a BSSID or ESSID that matches the rest of the provided parameters. If this association fails, but there is a possibility that other networks matching the specified criteria exist, then the tradi- tional discovery process begins as specified below. The discovery step finds all available WiFi networks on the specified WiFi link, which must not yet be con- nected. For administrative convenience, if there is only one WiFi link on the system, wifi-link can be omitted. Once discovery is complete, the list of networks is fil- tered according to the value of the following options: SunOS 5.11 Last change: 16 Jan 2009 20 System Administration Commands dladm(1M) -e essid, --essid=essid Networks that do not have the same essid are fil- tered out. -b bss|ibss, --bsstype=bss|ibss Networks that do not have the same bsstype are fil- tered out. -m a|b|g, --mode=a|b|g Networks not appropriate for the specified 802.11 mode are filtered out. -k key,..., --key=key, ... Use the specified secobj named by the key to connect to the network. Networks not appropriate for the specified keys are filtered out. -s none|wep|wpa, --sec=none|wep|wpa Networks not appropriate for the specified security mode are filtered out. Next, the remaining networks are prioritized, first by signal strength, and then by maximum speed. Finally, an attempt is made to associate with each network in the list, in order, until one succeeds or no networks remain. In addition to the options described above, the follow- ing options also control the behavior of connect-wifi: -a open|shared, --auth=open|shared Connect using the specified authentication mode. By default, open and shared are tried in order. -c, --create-ibss Used with -b ibss to create a new ad-hoc network if one matching the specified ESSID cannot be found. If no ESSID is specified, then -c -b ibss always triggers the creation of a new ad-hoc network. SunOS 5.11 Last change: 16 Jan 2009 21 System Administration Commands dladm(1M) -T time, --timeout=time Specifies the number of seconds to wait for associa- tion to succeed. If time is forever, then the asso- ciate will wait indefinitely. The current default is ten seconds, but this might change in the future. Timeouts shorter than the default might not succeed reliably. -k key,..., --key=key,... In addition to the filtering previously described, the specified keys will be used to secure the asso- ciation. The security mode to use will be based on the key class; if a security mode was explicitly specified, it must be compatible with the key class. All keys must be of the same class. For security modes that support multiple key slots, the slot to place the key will be specified by a colon followed by an index. Therefore, -k mykey:3 places mykey in slot 3. By default, slot 1 is assumed. For security modes that support multiple keys, a comma-separated list can be specified, with the first key being the active key. dladm disconnect-wifi [-a] [wifi-link] Disconnect from one or more WiFi networks. If wifi-link specifies a connected WiFi link, then it is discon- nected. For administrative convenience, if only one WiFi link is connected, wifi-link can be omitted. -a, --all-links Disconnects from all connected links. This is pri- marily intended for use by scripts. dladm show-wifi [[-p] -o field,...] [wifi-link] Shows WiFi configuration information either for all WiFi links or for the specified link wifi-link. -o field,..., --output=field A case-insensitive, comma-separated list of output fields to display. The field name must be one of the SunOS 5.11 Last change: 16 Jan 2009 22 System Administration Commands dladm(1M) fields listed below, or the special value all, to display all fields. For each WiFi link, the follow- ing fields can be displayed: LINK The name of the link being displayed. STATUS Either connected if the link is connected, or disconnected if it is not connected. If the link is disconnected, all remaining fields have the value --. ESSID The ESSID (name) of the connected WiFi network. BSSID Either the hardware address of the WiFi network's Access Point (for BSS networks), or the WiFi network's randomly generated unique token (for IBSS networks). SEC Either none for a WiFi network that uses no security, wep for a WiFi network that requires WEP, or wpa for a WiFi network that requires WPA. MODE The supported connection modes: one or more of a, b, or g. STRENGTH The connection strength: one of excellent, very good, good, weak, or very weak. SPEED SunOS 5.11 Last change: 16 Jan 2009 23 System Administration Commands dladm(1M) The connection speed, in megabits per second. AUTH Either open or shared (see connect-wifi). BSSTYPE Either bss for BSS (infrastructure) networks, or ibss for IBSS (ad-hoc) networks. By default, currently all fields but AUTH, BSSID, BSSTYPE are displayed. -p, --parseable Displays using a stable machine-parseable format. The -o option is required with -p. See "Parseable Output Format", below. dladm show-ether [-x] [[-p] -o field,...] [ether-link] Shows state information either for all physical Ethernet links or for a specified physical Ethernet link. The show-ether subcommand accepts the following options: -o field,..., --output=field A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below, or the special value all to display all fields. For each link, the following fields can be displayed: LINK The name of the link being displayed. PTYPE Parameter type, where current indicates the negotiated state of the link, capable indicates capabilities supported by the device, adv indi- cates the advertised capabilities, and peeradv indicates the capabilities advertised by the SunOS 5.11 Last change: 16 Jan 2009 24 System Administration Commands dladm(1M) link-partner. STATE The state of the link. AUTO A yes/no value indicating whether auto- negotiation is advertised. SPEED-DUPLEX Combinations of speed and duplex values avail- able. The units of speed are encoded with a trailing suffix of G (Gigabits/s) or M (Mb/s). Duplex values are encoded as f (full-duplex) or h (half-duplex). PAUSE Flow control information. Can be no, indicating no flow control is available; tx, indicating that the end-point can transmit pause frames, but ignores any received pause frames; rx, indi- cating that the end-point receives and acts upon received pause frames; or bi, indicating bi- directional flow-control. REM_FAULT Fault detection information. Valid values are none or fault. By default, all fields except REM_FAULT are displayed for the "current" PTYPE. -p, --parseable Displays using a stable machine-parseable format. The -o option is required with -p. See "Parseable Output Format", below. -x, --extended SunOS 5.11 Last change: 16 Jan 2009 25 System Administration Commands dladm(1M) Extended output is displayed for PTYPE values of current, capable, adv and peeradv. dladm set-linkprop [-t] [-R root-dir] -p prop=value[,...] link Sets the values of one or more properties on the link specified. The list of properties and their possible values depend on the link type, the network device driver, and networking hardware. These properties can be retrieved using show-linkprop. -t, --temporary Specifies that the changes are temporary. Temporary changes last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent creation. -p prop=value[,...], --prop prop=value[,...] A comma-separated list of properties to set to the specified values. Note that when the persistent value is set, the tem- porary value changes to the same value. dladm reset-linkprop [-t] [-R root-dir] -p prop,... link Resets one or more properties to their values on the link specified. Properties are reset to the values they had at startup. If no properties are specified, all pro- perties are reset. See show-linkprop for a description of properties. -t, --temporary Specifies that the resets are temporary. Values are reset to default values. Temporary resets last until the next reboot. SunOS 5.11 Last change: 16 Jan 2009 26 System Administration Commands dladm(1M) -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent creation. -p prop, ..., --prop=prop, ... A comma-separated list of properties to reset. Note that when the persistent value is reset, the tem- porary value changes to the same value. dladm show-linkprop [-P] [[-c] -o field[,...]][-p prop[,...]] [link] Show the current or persistent values of one or more properties, either for all datalinks or for the speci- fied link. By default, current values are shown. If no properties are specified, all available link properties are displayed. For each property, the following fields are displayed: -o field[,...], --output=field A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below, or the special value all to display all fields. For each link, the following fields can be displayed: LINK The name of the datalink. PROPERTY The name of the property. PERM The read/write permissions of the property. The value shown is one of ro or rw. VALUE The current (or persistent) property value. If the value is not set, it is shown as --. If it SunOS 5.11 Last change: 16 Jan 2009 27 System Administration Commands dladm(1M) is unknown, the value is shown as ?. Persistent values that are not set or have been reset will be shown as -- and will use the system DEFAULT value (if any). DEFAULT The default value of the property. If the pro- perty has no default value, -- is shown. POSSIBLE A comma-separated list of the values the pro- perty can have. If the values span a numeric range, min - max might be shown as shorthand. If the possible values are unknown or unbounded, -- is shown. The list of properties depends on the link type and network device driver, and the available values for a given property further depends on the underlying network hardware and its state. General link proper- ties are documented in the LINK PROPERTIES section. However, link properties that begin with "_" (under- bar) are specific to a given link or its underlying network device and subject to change or removal. See the appropriate network device driver man page for details. -c, --parseable Display using a stable machine-parseable format. The -o option is required with this option. See "Parse- able Output Format", below. -P, --persistent Display persistent link property information -p prop, ..., --prop=prop, ... A comma-separated list of properties to show. See the sections on link properties following subcommand descriptions. SunOS 5.11 Last change: 16 Jan 2009 28 System Administration Commands dladm(1M) dladm create-secobj [-t] [-R root-dir] [-f file] -c class secobj Create a secure object named secobj in the specified class to be later used as a WEP or WPA key in connecting to an encrypted network. The value of the secure object can either be provided interactively or read from a file. The sequence of interactive prompts and the file format depends on the class of the secure object. Currently, the classes wep and wpa are supported. The WEP (Wired Equivalent Privacy) key can be either 5 or 13 bytes long. It can be provided either as an ASCII or hexadecimal string -- thus, 12345" and "0x3132333435 are equivalent 5-byte keys (the 0x prefix can be omitted). A file containing a WEP key must consist of a single line using either WEP key format. The WPA (Wi-Fi Protected Access) key must be provided as an ASCII string with a length between 8 and 63 bytes. This subcommand is only usable by users or roles that belong to the "Network Link Security" RBAC profile. -c class, --class=class class can be wep or wpa. See preceding discussion. -t, --temporary Specifies that the creation is temporary. Temporary creation last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent creation. -f file, --file=file Specifies a file that should be used to obtain the secure object's value. The format of this file depends on the secure object class. See the EXAMPLES section for an example of using this option to set a WEP key. dladm delete-secobj [-t] [-R root-dir] secobj[,...] SunOS 5.11 Last change: 16 Jan 2009 29 System Administration Commands dladm(1M) Delete one or more specified secure objects. This sub- command is only usable by users or roles that belong to the "Network Link Security" RBAC profile. -t, --temporary Specifies that the deletions are temporary. Tem- porary deletions last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent deletions dladm show-secobj [-P] [[-p] -o field[,...]] [secobj,...] Show current or persistent secure object information. If one or more secure objects are specified, then informa- tion for each is displayed. Otherwise, all current or persistent secure objects are displayed. By default, current secure objects are displayed, which are all secure objects that have either been per- sistently created and not temporarily deleted, or tem- porarily created. For security reasons, it is not possible to show the value of a secure object. -o field[,...] , --output=field[,...] A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below. For displayed secure object, the following fields can be shown: OBJECT The name of the secure object. CLASS The class of the secure object. -p, --parseable SunOS 5.11 Last change: 16 Jan 2009 30 System Administration Commands dladm(1M) Display using a stable machine-parseable format. The -o option is required with -p. See "Parseable Output Format", below. -P, --persistent Display persistent secure object information dladm create-vnic [-t] [-R root-dir] [-l link] [-m value | auto | {factory [-n slot-identifier]} | {random [-r pre- fix]}] [-v vlan-id] [-p prop=value[,...]] vnic-link Create a VNIC with name vnic-link over the specified link. -t, --temporary Specifies that the VNIC is temporary. Temporary VNICs last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent creation. -l link, --link=link link can be a physical link or an etherstub. -m value | keyword, --mac-address=value | keyword Sets the VNIC's MAC address based on the specified value or keyword. If value is not a keyword, it is interpreted as a unicast MAC address, which must be valid for the underlying NIC. The following special keywords can be used: factory [-n slot-identifier], factory [--slot=slot-identifier] Assign a factory MAC address to the VNIC. When a factory MAC address is requested, -m can be com- bined with the -n option to specify a MAC address slot to be used. If -n is not specified, the system will choose the next available fac- tory MAC address. The -m option of the show-phys SunOS 5.11 Last change: 16 Jan 2009 31 System Administration Commands dladm(1M) subcommand can be used to display the list of factory MAC addresses, their slot identifiers, and their availability. random [-r prefix], random [--mac-prefix=prefix] Assign a random MAC address to the VNIC. A default prefix consisting of a valid IEEE OUI with the local bit set will be used. That prefix can be overridden with the -r option. auto Try and use a factory MAC address first. If none is available, assign a random MAC address. auto is the default action if the -m option is not specified. -v vlan-id Enable VLAN tagging for this VNIC. The VLAN tag will have id vlan-id. -p prop=value,..., --prop prop=value,... A comma-separated list of properties to set to the specified values. dladm delete-vnic [-t] [-R root-dir] vnic-link Deletes the specified VNIC. -t, --temporary Specifies that the deletion is temporary. Temporary deletions last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent creation. SunOS 5.11 Last change: 16 Jan 2009 32 System Administration Commands dladm(1M) dladm show-vnic [-pP] [-s [-i interval]] [-l link] [vnic- link] Show VNIC configuration information for all VNICs, all all VNICs on a link, or only the specified vnic-link. -o field[,...] , --output=field[,...] A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below. The field name must be one of the fields listed below, or the special value all to display all fields. By default (without -o), show- vnic displays all fields. LINK The name of the VNIC. OVER The name of the physical link over which this VNIC is configured. SPEED The maximum speed of the VNIC, in megabits per second. MACADDRESS MAC address of the VNIC. MACADDRTYPE MAC address type of the VNIC. dladm distin- guishes among the following MAC address types: random A random address assigned to the VNIC. factory A factory MAC address used by the VNIC. SunOS 5.11 Last change: 16 Jan 2009 33 System Administration Commands dladm(1M) -p, --parseable Display using a stable machine-parseable format. The -o option is required with -p. See "Parseable Output Format", below. -P, --persistent Display the persistent VNIC configuration. -s, --statistics Display VNIC statistics. This option is made Obsolete by dlstat(1M). -i interval, --interval=interval Used with the -s option to specify an interval, in seconds, at which statistics should be displayed. If this option is not specified, statistics will be displayed only once. This option is made Obsolete by dlstat(1M). -l link, --link=link Display information for all VNICs on the named link. dladm create-etherstub [-t] [-R root-dir] etherstub Create an etherstub with the specified name. -t, --temporary Specifies that the etherstub is temporary. Temporary etherstubs do not persist across reboots. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent creation. VNICs can be created on top of etherstubs instead of physical NICs. As with physical NICs, such a creation causes the stack to implicitly create a virtual switch between the VNICs created on top of the same etherstub. SunOS 5.11 Last change: 16 Jan 2009 34 System Administration Commands dladm(1M) dladm delete-etherstub [-t] [-R root-dir] etherstub Delete the specified etherstub. -t, --temporary Specifies that the deletion is temporary. Temporary deletions last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent deletions. dladm show-etherstub [etherstub] Show all configured etherstubs by default, or the speci- fied etherstub if etherstub is specified. dladm show-usage -a -f filename [-d | -F format] [-s time] [-e time] [link] Show the network usage from a stored extended accounting file. Configuration and enabling of network accounting through acctadm(1M) is required. The default output will be the summary of network usage of the existing links for their entire period of time in which extended accounting was enabled. -a Display all historical network usage for the specified period of time while extended accounting is enabled. This includes the usage information for the links that have already been deleted. -d Display the dates for which there is logging infor- mation. The date is in the format DD/MM/YYYY. -f filename, --file=filename Read extended accounting records of network usage from filename. -F format, --format=format Specifies the output format of the network usage information. As of this release, gnuplot is the only supported format. -s time, --start=time -e time, --stop=time Start and stop times for data display. Time is in the format MM/DD/YYYY,hh:mm:ss. link If specified, display the network usage only for the named link. Otherwise, display network usage for all links. This subcommand is made Obsolete by dlstat(1M) show-link -h subcommand. SunOS 5.11 Last change: 16 Jan 2009 35 System Administration Commands dladm(1M) Parseable Output Format Many dladm subcommands have an option that displays output in a machine-parseable format. The output format is one or more lines of colon (:) delimited fields. The fields displayed are specific to the subcommand used and are listed under the entry for the -o option for a given subcommand. Output includes only those fields requested by means of the -o option, in the order requested. When you request multiple fields, any literal colon charac- ters are escaped by a backslash (\) before being output. Similarly, literal backslash characters will also be escaped (\\). This escape format is parseable by using shell read(1) functions with the environment variable IFS=: (see EXAMPLES, below). Note that escaping is not done when you request only a single field. General Link Properties The following general link properties are supported: autopush Specifies the set of STREAMS modules to push on the stream associated with a link when its DLPI device is opened. It is a space-delimited list of modules. The optional special character sequence [anchor] indi- cates that a STREAMS anchor should be placed on the stream at the module previously specified in the list. It is an error to specify more than one anchor or to have an anchor first in the list. The autopush property is preferred over the more general autopush(1M) command. SunOS 5.11 Last change: 16 Jan 2009 36 System Administration Commands dladm(1M) cpus Bind the processing of packets for a given data link to a processor or a set of processors. The value can be a comma-separated list of one or more processor ids. If the list consists of more than one processor, the pro- cessing will spread out to all the processors. Connec- tion to processor affinity and packet ordering for any individual connection will be maintained. The processor or set of processors are not exclusively reserved for the link. Only the kernel threads and interrupts associated with processing of the link are bound to the processor or the set of processors speci- fied. In case it is desired that processors be dedicated to the link, psrset(1M) can be used to create a proces- sor set and then specifying the processors from the pro- cessor set to bind the link to. If the link was already bound to processor or set of processors due to a previous operation, the binding will be removed and the new set of processors will be used instead. The default is no CPU binding, which is to say that the processing of packets is not bound to any specific pro- cessor or processor set. maxbw Sets the full duplex bandwidth for the link. The bandwidth is specified as an integer with one of the scale suffixes (K, M, or G for Kbps, Mbps, and Gbps). If no units are specified, the input value will be read as Mbps. The default is no bandwidth limit. priority Sets the relative priority for the link. The value can be given as one of the tokens high, medium, or low. The default is high. zone Specifies the zone to which the link belongs. This pro- perty can be modified only temporarily through dladm, and thus the -t option must be specified. To modify the zone assignment such that it persists across reboots, please use zonecfg(1M). Possible values consist of any SunOS 5.11 Last change: 16 Jan 2009 37 System Administration Commands dladm(1M) exclusive-IP zone currently running on the system. By default, the zone binding is as per zonecfg(1M). Wifi Link Properties The following WiFi link properties are supported. Note that the ability to set a given property to a given value depends on the driver and hardware. channel Specifies the channel to use. This property can be modi- fied only by certain WiFi links when in IBSS mode. The default value and allowed range of values varies by regulatory domain. powermode Specifies the power management mode of the WiFi link. Possible values are off (disable power management), max (maximum power savings), and fast (performance-sensitive power management). Default is off. radio Specifies the radio mode of the WiFi link. Possible values are on or off. Default is on. speed Specifies a fixed speed for the WiFi link, in megabits per second. The set of possible values depends on the driver and hardware (but is shown by show-linkprop); common speeds include 1, 2, 11, and 54. By default, there is no fixed speed. Ethernet Link Properties The following MII Properties, as documented in ieee802.3(5), are supported in read-only mode: o duplex o state o adv_autoneg_cap o adv_1000fdx_cap SunOS 5.11 Last change: 16 Jan 2009 38 System Administration Commands dladm(1M) o adv_1000hdx_cap o adv_100fdx_cap o adv_100hdx_cap o adv_10fdx_cap o adv_10hdx_cap Each adv_ property (for example, adv_autoneg_cap) also has a read/write counterpart enable_ property (for example, enable_autoneg_cap) controlling parameters used at auto- negotiation. In addition, the following Ethernet properties are reported: speed (read-only) The operating speed of the device, in Mbps. mtu The maximum client SDU (Send Data Unit) supported by the device. Valid range is 68-65536. flowctrl Establishes flow-control modes that will be advertised by the device. Valid input is one of: no No flow control enabled. rx Receive, and act upon incoming pause frames. tx Transmit pause frames to the peer when congestion occurs, but ignore received pause frames. SunOS 5.11 Last change: 16 Jan 2009 39 System Administration Commands dladm(1M) bi Bidirectional flow control. Note that the actual settings for this value are con- strained by the capabilities allowed by the device and the link partner. EXAMPLES Example 1 Configuring an Aggregation To configure a data-link over an aggregation of devices bge0 and bge1 with key 1, enter the following command: # dladm create-aggr -d bge0 -d bge1 1 Example 2 Connecting to a WiFi Link To connect to the most optimal available unsecured network on a system with a single WiFi link (as per the prioritiza- tion rules specified for connect-wifi), enter the following command: # dladm connect-wifi Example 3 Creating a WiFi Key To interactively create the WEP key mykey, enter the follow- ing command: # dladm create-secobj -c wep mykey Alternatively, to non-interactively create the WEP key mykey using the contents of a file: # umask 077 # cat >/tmp/mykey.$$ <<-EOF SunOS 5.11 Last change: 16 Jan 2009 40 System Administration Commands dladm(1M) 12345 EOF # dladm create-secobj -c wep -f /tmp/mykey.$$ mykey # rm /tmp/mykey.$$ Example 4 Connecting to a Specified Encrypted WiFi Link To use key mykey to connect to ESSID wlan on link ath0, enter the following command: # dladm connect-wifi -k mykey -e wlan ath0 Example 5 Changing a Link Property To set powermode to the value fast on link pcwl0, enter the following command: # dladm set-linkprop -p powermode=fast pcwl0 Example 6 Connecting to a WPA-Protected WiFi Link Create a WPA key psk and enter the following command: # dladm create-secobj -c wpa psk To then use key psk to connect to ESSID wlan on link ath0, enter the following command: # dladm connect-wifi -k psk -e wlan ath0 Example 7 Renaming a Link SunOS 5.11 Last change: 16 Jan 2009 41 System Administration Commands dladm(1M) To rename the bge0 link to mgmt0, enter the following com- mand: # dladm rename-link bge0 mgmt0 Example 8 Replacing a Network Card Consider that the bge0 device, whose link was named mgmt0 as shown in the previous example, needs to be replaced with a ce0 device because of a hardware failure. The bge0 NIC is physically removed, and replaced with a new ce0 NIC. To associate the newly added ce0 device with the mgmt0 confi- guration previously associated with bge0, enter the follow- ing command: # dladm rename-link ce0 mgmt0 Example 9 Removing a Network Card Suppose that in the previous example, the intent is not to replace the bge0 NIC with another NIC, but rather to remove and not replace the hardware. In that case, the mgmt0 datalink configuration is not slated to be associated with a different physical device as shown in the previous example, but needs to be deleted. Enter the following command to delete the datalink configuration associated with the mgmt0 datalink, whose physical hardware (bge0 in this case) has been removed: # dladm delete-phys mgmt0 Example 10 Using Parseable Output to Capture a Single Field The following assignment saves the MTU of link net0 to a variable named mtu. # mtu=`dladm show-link -p -o mtu net0` SunOS 5.11 Last change: 16 Jan 2009 42 System Administration Commands dladm(1M) Example 11 Using Parseable Output to Iterate over Links The following script displays the state of each link on the system. # dladm show-link -p -o link,state | while IFS=: read link state; do print "Link $link is in state $state" done Example 12 Configuring VNICs Create two VNICs with names hello0 and test1 over a single physical link bge0: # dladm create-vnic -l bge0 hello0 # dladm create-vnic -l bge0 test1 Example 13 Configuring VNICs and Allocating Bandwidth and Priority Create two VNICs with names hello0 and test1 over a single physical link bge0 and make hello0 a high priority VNIC with a factory-assigned MAC address with a maximum bandwidth of 50 Mbps. Make test1 a low priority VNIC with a random MAC address and a maximum bandwidth of 100Mbps. # dladm create-vnic -l bge0 -m factory -p maxbw=50,priority=high hello0 # dladm create-vnic -l bge0 -m random -p maxbw=100M,priority=low test1 Example 14 Configuring a VNIC with a Factory MAC Address First, list the available factory MAC addresses and choose one of them: # dladm show-phys -m bge0 LINK SLOT ADDRESS INUSE CLIENT bge0 primary 0:e0:81:27:d4:47 yes bge0 bge0 1 8:0:20:fe:4e:a5 no SunOS 5.11 Last change: 16 Jan 2009 43 System Administration Commands dladm(1M) bge0 2 8:0:20:fe:4e:a6 no bge0 3 8:0:20:fe:4e:a7 no Create a VNIC named hello0 and use slot 1's address: # dladm create-vnic -l bge0 -m factory -n 1 hello0 # dladm show-phys -m bge0 LINK SLOT ADDRESS INUSE CLIENT bge0 primary 0:e0:81:27:d4:47 yes bge0 bge0 1 8:0:20:fe:4e:a5 yes hello0 bge0 2 8:0:20:fe:4e:a6 no bge0 3 8:0:20:fe:4e:a7 no Example 15 Creating a VNIC with User-Specified MAC Address, Binding it to Set of Processors Create a VNIC with name hello0, with a user specified MAC address, and a processor binding 0, 1, 2, 3. # dladm create-vnic -l bge0 -m 8:0:20:fe:4e:b8 -p cpus=0,1,2,3 hello0 Example 16 Creating a Virtual Network Without a Physical NIC First, create an etherstub with name stub1: # dladm create-etherstub stub1 Create two VNICs with names hello0 and test1 on the ether- stub. This operation implicitly creates a virtual switch connecting hello0 and test1. # dladm create-vnic -l stub1 hello0 # dladm create-vnic -l stub1 test1 SunOS 5.11 Last change: 16 Jan 2009 44 System Administration Commands dladm(1M) ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: /usr/sbin ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsu | |_____________________________|_____________________________| | Interface Stability | Committed* | |_____________________________|_____________________________| /sbin SunOS 5.11 Last change: 16 Jan 2009 45 System Administration Commands dladm(1M) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsr | |_____________________________|_____________________________| | Interface Stability | Committed* | |_____________________________|_____________________________| * dladm show-link, dladm show-vnic and dladm show-aggr's -s and -i are committed obselete. SEE ALSO acctadm(1M), autopush(1M), dlstat(1M), ifconfig(1M), ndd(1M), psrset(1M), wpad(1M), zonecfg(1M), attributes(5), ieee802.3(5), dlpi(7P) NOTES The preferred method of referring to an aggregation in the aggregation subcommands is by its link name. Referring to an aggregation by its integer key is supported for backward compatibility, but is not necessary. When creating an aggre- gation, if a key is specified instead of a link name, the aggregation's link name will be automatically generated by dladm as aggrkey. SunOS 5.11 Last change: 16 Jan 2009 46