System Administration Commands dladm(1M) NAME dladm - administer data links SYNOPSIS dladm show-link [-p] [-s [-i interval]] [name] dladm show-dev [-p] [-s [-i interval]] [dev] dladm create-aggr [-t] [-R root-dir] [-P policy] [-l mode] [-T time] [-u address] -d dev... key dladm modify-aggr [-t] [-R root-dir] [-P policy] [-l mode] [-T time] [-u address] key dladm delete-aggr [-t] [-R root-dir] key dladm add-aggr [-t] [-R root-dir] -d dev ... key dladm remove-aggr [-t] [-R root-dir] -d dev ... key dladm show-aggr [-pL] [-s [-i interval]] [key] dladm scan-wifi [-p] [-o field,...] [name] dladm connect-wifi [-e essid] [-i bssid] [-k key,...] [-s wep ] [-a open|shared][-b bss|ibss] [-c] [-m a|b|g] [-T time] [name] dladm disconnect-wifi [-a] [name] dladm show-wifi [-p] [-o field,...] [name] dladm set-linkprop [-t] [-R root-dir] -p prop=value[,...] name dladm reset-linkprop [-t] [-R root-dir] [-p prop,...] name dladm show-linkprop [-cP] [-p prop,...] [name] dladm create-secobj [-t] [-R root-dir] [-f file] -c class secobj dladm delete-secobj [-t] [-R root-dir] secobj[,...] dladm show-secobj [-pP] [secobj,...] 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 may 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 Data-links, identified by a name. SunOS 5.11 Last change: 28 Nov 2006 1 System Administration Commands dladm(1M) dev Network devices, identified by concatenation of a driver name and an instance number. aggr Aggregations of network devices, identified by an administratively-chosen key between 1 and 999. secobj Secure objects, identified by an administratively- chosen alphanumeric name. Some subcommands require a specific type of link. For instance, the WiFi subcommands require a WiFi link. Further, the behavior of the linkprop subcommands depends on the type of link and underlying device. Some devices do not support configurable data-links or aggregations. The fixed data-links provided by such devices can be viewed using dladm, but can not be configured. SUBCOMMANDS The following subcommands are supported: dladm show-link [-p] [-s [-i interval]] [name] Show link configuration information (the default) or statistics, either for all data-links or for the speci- fied link name. By default, the system is configured with one data-link for each known network device. -p, --parseable Display using a stable machine-parseable format. SunOS 5.11 Last change: 28 Nov 2006 2 System Administration Commands dladm(1M) -s, --statistics Display link statistics. -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 only be displayed once. dladm show-dev [-p] [-s [-i interval]] [dev] Show device configuration information (the default) or statistics, either for all network devices or for the specified device dev. -p, --parseable Display using a stable machine-parseable format. -s, --statistics Display network device statistics. -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 only be displayed once. SunOS 5.11 Last change: 28 Nov 2006 3 System Administration Commands dladm(1M) dladm create-aggr [-t] [-R root-dir] [-P policy] [-l mode] [-T time] [-u address] -d dev ... key Create an aggregation using the given key value from as many dev objects as are specified. A data-link is created and is given a name which is the concatenation of "aggr" and the key value of the aggregation. -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. SunOS 5.11 Last change: 28 Nov 2006 4 System Administration Commands dladm(1M) 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: -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 SunOS 5.11 Last change: 28 Nov 2006 5 System Administration Commands dladm(1M) 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] key 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. -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". SunOS 5.11 Last change: 28 Nov 2006 6 System Administration Commands dladm(1M) -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] key 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] -d dev ... key Adds as many dev objects as are provided to the SunOS 5.11 Last change: 28 Nov 2006 7 System Administration Commands dladm(1M) specified aggregation. -d, --dev Specifies a device to add to the aggregation. -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] -d dev ... key Removes as many dev objects as are provided from the specified aggregation. -d, --dev Specifies a device to remove from the aggregation. -t, --temporary Specifies that the removals are temporary. Temporary removal last until the next reboot. SunOS 5.11 Last change: 28 Nov 2006 8 System Administration Commands dladm(1M) -R root-dir, --root-dir=root-dir Specifies an alternate root directory where dladm should apply persistent removals. dladm show-aggr [-pL] [-s [-i interval]] [key] Show aggregation configuration (the default), LACP information, or statistics, either for all aggregations or for the specified key. -p, --parseable Display using a stable machine-parseable format. -L, --lacp Displays detailed LACP information. -s, --statistics Displays aggregation statistics. -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 only be displayed once. SunOS 5.11 Last change: 28 Nov 2006 9 System Administration Commands dladm(1M) dladm scan-wifi [-p] [-o field,...] [name] Scans for WiFi networks, either on all WiFi links, or just on the specified name. 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 secu- rity, or "wep" for a WiFi network that requires WEP. MODE The supported connection modes: one or more of "a", "b", or "g". SunOS 5.11 Last change: 28 Nov 2006 10 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 megabits per second. BSSTYPE Either "bss" for BSS (infrastructure) networks, or "ibss" for IBSS (ad-hoc) networks. By default, currently all fields but BSSTYPE are displayed. -p, --parseable Display using a stable machine-parseable format. If this option is speci- fied, all output fields are displayed by default. -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 above, or the special value "all" to display all fields. SunOS 5.11 Last change: 28 Nov 2006 11 System Administration Commands dladm(1M) dladm connect-wifi [-e essid] [-i bssid] [-k key,...] [-s wep ] [-a open|shared] [-b bss|ibss] [-c] [-m a|b|g] [-T time] [name] 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 to 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 name, which must not yet be connected. For administrative convenience, if there is only one WiFi link on the system, name may be omitted. Once discovery is complete, the list of networks is fil- tered according to the value of the following options: -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 SunOS 5.11 Last change: 28 Nov 2006 12 System Administration Commands dladm(1M) Networks not appropriate for the specified 802.11 mode are filtered out. -k key,..., --key=key, ... Networks not appropriate for the specified keys are filtered out. -s none|wep, --sec=none|wep 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" will always trigger the creation of a new ad-hoc network. SunOS 5.11 Last change: 28 Nov 2006 13 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 associate will wait indefinitely. The current default is ten seconds, but this may change in the future. Timeouts shorter than the default may 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] [name] Disconnect from one or more WiFi networks. If name specifies a connected WiFi link, then it is discon- nected. For administrative convenience, if only one WiFi link is connected, name may be omitted. -a, --all-links Disconnects from all connected links. This is primarily intended for use by scripts. SunOS 5.11 Last change: 28 Nov 2006 14 System Administration Commands dladm(1M) dladm show-wifi [-p] [-o field,...] [name] Shows WiFi configuration information either for all WiFi links or for the specified link name. For each WiFi link, the following 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 secu- rity, or "wep" for a WiFi network that requires WEP. SunOS 5.11 Last change: 28 Nov 2006 15 System Administration Commands dladm(1M) 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 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. If this option is speci- fied, all output fields are displayed by default. SunOS 5.11 Last change: 28 Nov 2006 16 System Administration Commands dladm(1M) -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 above, or the special value "all" to display all fields. dladm set-linkprop [-t] [-R root-dir] -p prop=value[,...] name Sets the values of one or more properties on the link specified by name. The list of properties and their pos- sible values depend on the link type, the network device driver, and networking hardware, but 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. SunOS 5.11 Last change: 28 Nov 2006 17 System Administration Commands dladm(1M) dladm reset-linkprop [-t] [-R root-dir] -p prop, ... name Resets one or more properties to their values on the link specified by name. If no properties are specified, all properties are reset. -t, --temporary Specifies that the resets are temporary. Temporary resets 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, ..., --prop=prop, ... A comma-separated list of properties to reset. dladm show-linkprop [-cP] [-p prop, ...] [name] Show the current or persistent values of one or more properties, either for all data-links or for the specified link name. 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: LINK The name of the data-link. PROPERTY The name of the property. SunOS 5.11 Last change: 28 Nov 2006 18 System Administration Commands dladm(1M) VALUE The current (or persistent) property value. The value is shown as "--". if unset, and "?" if is unknown. 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 may have. If the values span a numeric range, min - max may be shown as shorthand. If the possible values are unknown or unbounded, "--" is shown. The list of properties depends on the link type and net- work device driver, and the available values for a given property further depends on the underlying network hardware and its state. General link properties are documented in theLINK PROPERTIES, section. However, link properties that begin with "link" are specific to a given link or its underlying network device and subject to change or removal; see the appropriate network device driver manpage for details. -c, --parseable Display using a stable machine-parseable for- mat. -P, --persistent Display persistent link property information -p prop, ..., --prop=prop, ... A comma-separated list of properties to show. SunOS 5.11 Last change: 28 Nov 2006 19 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. The value of the secure object can either be pro- vided interactively or read from a file. The sequence of interactive prompts and file format depends on the class of the secure object. Currently, the only defined class is "wep". The WEP 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 may be omitted). A file containing a WEP key must consist of a single line using either WEP key format. This subcommand is only usable by users or roles that belong to the "Network Link Security" RBAC profile. -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. SunOS 5.11 Last change: 28 Nov 2006 20 System Administration Commands dladm(1M) dladm delete-secobj [-t] [-R root-dir] secobj[,...] 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 [-pP] [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 each displayed secure object, the following fields are shown: OBJECT The name of the secure object. SunOS 5.11 Last change: 28 Nov 2006 21 System Administration Commands dladm(1M) CLASS The class of the secure object. For security reasons, it is not possible to show the value of a secure object. -p, --parseable Display using a stable machine- parseable format. -P, --persistent Display persistent secure object information LINK PROPERTIES The following link properties are supported. zone Specifies the zone the link belongs to. This property can only be temporarily modified 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 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 only be modified 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. Possi- ble values are "on" or "off". Default is "on". SunOS 5.11 Last change: 28 Nov 2006 22 System Administration Commands dladm(1M) 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. 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 fol- lowing command: # dladm create-secobj -c wep mykey Alternatively, to non-interactively create the WEP key "mykey" using the contents of a file: SunOS 5.11 Last change: 28 Nov 2006 23 System Administration Commands dladm(1M) # umask 077 # cat >/tmp/mykey.$$ <<-EOF 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 ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: /usr/sbin SunOS 5.11 Last change: 28 Nov 2006 24 System Administration Commands dladm(1M) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsu | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________| /sbin ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsr | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________| SEE ALSO ifconfig(1M), zonecfg(1M), attributes(5), dlpi(7P) NOTES The configuration of all objects will persist across reboot. SunOS 5.11 Last change: 28 Nov 2006 25