'\" te .\" .\" This file and its contents are supplied under the terms of the .\" Common Development and Distribution License ("CDDL"), version 1.0. .\" You may only use this file in accordance with the terms of version .\" 1.0 of the CDDL. .\" .\" A full copy of the text of the CDDL should have accompanied this .\" source. A copy of the CDDL is also available via the Internet at .\" http://www.illumos.org/license/CDDL. .\" .\" .\" Copyright (c) 2014, Joyent, Inc. All rights reserved. .\" .TH VNDADM 1M "Mar 06, 2014" .SH NAME vndadm \- administer vnd devices .SH SYNOPSIS .nf vndadm create [-z zonename] [-l datalink] device vndadm destroy [-z zonename] device... vndadm list [-p] [-d delim] [-o field,...] [-z zonename] [device]... vndadm get [-p] [-d delim] [-z zonename] device [prop]... vndadm set [-z zonename] device prop=val... .fi .SH DESCRIPTION .sp .LP The vndadm command is used to administer vnd devices. A vnd device is similar to an IP network interface, except that the vnd device operates at layer two. A vnd device is created over a data link (see dladm(1M)) and its address is that of the underlying data link. For ethernet based devices, that address would be the MAC address of the data link. vnd devices are character devices which may be used to send and receive layer two packets. When reading or writing to a vnd device, the full frame must be present. This is useful for working with virtual machines, or other environments where you need to manipulate the entire layer two frame. .sp .LP Every command takes a device as an argument. To specify a vnd device, you just use the name of the device. Devices are scoped to zones. If no zone is specified, the current zone is assumed. A device name can be any series of alphanumeric ascii characters which typically match the name of the underlying data link. A given vnd device name must be unique in a given zone, but the same name can be used across zones. .sp .SH OPTIONS .sp .LP All vndadm subcommands have the following common option: .sp .ne 2 .na -z zonename .ad .sp .6 .RS 4n Operate in the context of the specified zone. When creating a vnd device, the named device is created in the specified zone. All other operations scope the device lookup to the specified zone. If the user is not in the global zone, the use of -z will not work. .sp .LP When -z is used and multiple devices are specified, then the use of -z applies to all of the devices. .RE .SH SUBCOMMANDS .sp .ne 2 .na vndadm create [-z zonename] [-l datalink] device .ad .sp .RS 4n Creates a vnd device with the specified name device. If -l datalink is not specified, it is assumed that the data link and the device share the same name. The created device will exist for as long as the zone exists or until a call to vndadm destroy. vnd devices do not persist across system reboots. Note, if an IP interface or another libdlpi(3LIB) consumer is already using the data link, then vnd will fail. .sp The maximum length of the name of device is 31 characters. The allowed set of characters is alphanumberic characters, ':', \'-', and \'_'. The names 'zone' and 'ctl' are reserved and may not be used. .sp .ne 2 .na -l datalink .ad .sp .6 .RS 4n Specifies the name of the data link to create the device over. This allows the vnd device name to be different from the data link's name. .RE .sp .ne 2 .na -z zonename .ad .sp .6 .RS 4n See OPTIONS above. .RE .RE .sp .ne 2 .na vndadm destroy [-z zonename] device... .ad .sp .RS 4n Destroys the specified device. The destruction is analogous to unlink(2). If the device is still open and used by applications, the device will continue to exist, but it will no longer be accessible by the name device. .sp .ne 2 .na -z zonename .ad .sp .6 .RS 4n See OPTIONS above. .RE .RE .sp .ne 2 .na vndadm list [-p] [-d delim] [-o field,...] [-z zonename] [device]... .ad .sp .RS 4n Lists active vnd devices. By default, vnadm list lists all devices in every zone that the caller is allowed to see; the current zone if in the non-global zone, and all zones in the global zone. If device is specified one or more times, then output will be limited to the specified devices. .sp .ne 2 .na -o field[,...] .ad .sp .6 .RS 4n A case-insensitive, comma-separated list of output fields. When -o is not used, all of the fields listed below are shown. The field name must be one of the following fields: .sp .ne 2 .na NAME .ad .sp .6 .RS 4n The name of the vnd device. .RE .sp .ne 2 .na DATALINK .ad .sp .6 .RS 4n The name of the data link the vnd device was created over. .RE .sp .ne 2 .na ZONENAME .ad .sp .6 .RS 4n The name of the zone that the vnd device exists in. .RE .RE .sp .ne 2 .na -p .ad .sp .6 .RS 4n Display the output in a stable machine parseable format. The -o option is required with the -p option. See "Parseable Output Format" below. .RE .sp .ne 2 .na -d delim .ad .sp .6 .RS 4n Change the delimiter used in conjunction with generating parseable output. This option may only be specified when -p is also specified. .RE .sp .ne 2 .na -z zonename .ad .sp .6 .RS 4n See OPTIONS above. .RE .RE .sp .ne 2 .na vndadm get [-p] [-d delim] [-z zonename] device [prop]... .ad .sp .RS 4n Displays the properties for the specified device. By default, all properties of a given device are displayed. If prop is specified one or more times, then only the specified properties will be displayed for device. For a list of properties, see the section "Properties" below. The property output consists of the following four columns: .sp .ne 2 .na LINK .ad .sp .6 .RS 4n The name of the device .RE .sp .ne 2 .na PROPERTY .ad .sp .6 .RS 4n The name of the property. Note that some properties that are private to the implementation may be displayed. Those properties begin with a leading underscore. .RE .sp .ne 2 .na PERM .ad .sp .6 .RS 4n Describes whether the property is read-only or if it is read-write. This field does not indicate if the current user has permission, but lists permissions for a privileged user. .RE .sp .ne 2 .na VALUE .ad .sp .6 .RS 4n The value of the property. .RE .sp .ne 2 .na -p .ad .sp .6 .RS 4n Display the output in a stable machine parseable format. See "Parseable Output Format" below. .RE .sp .ne 2 .na -d delim .ad .sp .6 .RS 4n Change the delimiter used in conjunction with generating parseable output. This option may only be specified when -p is also specified. .RE .sp .ne 2 .na -z zonename .ad .sp .6 .RS 4n See OPTIONS above. .RE .RE .sp .ne 2 .na vndadm set [-z zonename] device prop=val... .ad .sp .RS 4n Sets properties on the named device. Setting a property takes effect for all operations on the device, after the program returns. Multiple properties can be set at once; however, properties are applied one at a time to the device. Property names and values must be separated with an equals sign. Additional property and value pairs should be separated by white space. For a list of properties, see the section "Properties" below. .sp .ne 2 .na -z zonename .ad .sp .6 .RS 4n See OPTIONS above. .RE .RE .SS Parseable Output Format .sp .LP The default output for parseable data is to be separated with a single ascii space character. The delimiter may be changed with the -d option. When parseable output is requested, no numbers that represent sizes will be displayed in human readable form, they will be fully expanded. eg. the number 42K will instead be 43008. .SS Properties .sp .LP The following are supported and stable properties. Note that any properties that starts with a leading underscore are not a stable property and may be removed at any time. .sp .ne 2 .na rxbuf .ad .sp .6 .RS 4n A read/write property that controls the size of the receive buffer for the device. All received data enters the receive buffer until a consumer consumes it. If adding a received frame would exceed the size of the receive buffer, then that frame will be dropped. The maximum size of the buffer is limited by the 'maxsize' property. The minimum size of the buffer is the value of the 'maxtu' property. The property's value may be anything between that maximum and minimum. When setting this property, standard size suffixes such as 'K' and 'M' may be used. .RE .sp .ne 2 .na txbuf .ad .sp .6 .RS 4n A read/write property that controls the size of the transmit buffer. All in-flight transmitted data must be able to fit into the transmit buffer to account for potential flow control events. If there is not enough space in the transmit buffer, transmit related I/O operations will either block or fail based on whether the file has been put into non-blocking mode by setting O_NONBLOCK or O_NDELAY with fcntl(2). The maximum size of the buffer is limited by the 'maxsize' property. The minimum size of the buffer is the value of the 'maxtu' property. The property's value may be anything between that maximum and minimum. When setting this property, standard size suffixes such as 'K' and 'M' may be used. .RE .sp .ne 2 .na maxsize .ad .sp .6 .RS 4n A read-only property that describes the maximum size of buffers in the system. Properties such as rxbuf and txbuf cannot be set beyond this. .RE .sp .ne 2 .na mintu .ad .sp .6 .RS 4n A read-only property that describes the minimum size of a frame transmitted to the underlying data link. Note that the minimum listed here may be less than the size of a valid layer two frame and therefore may be dropped. A frame smaller than this value will be rejected by vnd. .RE .sp .ne 2 .na maxtu .ad .sp .6 .RS 4n A read-only property that describes the maximum size of a frame transmitted to the underlying data link. A frame larger than this value will be rejected by vnd. .RE .SH EXAMPLES .LP Example 1 Creating a vnd device .sp .LP To create a vnd device over the VNIC named net0, enter the following command: .sp .in +2 .nf # vndadm create net0 .fi .in -2 .sp .LP Example 2 Creating a vnd device in another zone .sp .LP To create a vnd device over the VNIC named net1 in the zone 1b7155a4-aef9-e7f0-d33c-9705e4b8b525, enter the following command: .sp .in +2 .nf # vndadm create -z 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 net1 .fi .in -2 .sp .LP Example 3 Destroying a vnd device .sp .LP To destroy the vnd device named net0, enter the following command: .sp .in +2 .nf # vndadm destroy net0 .fi .in -2 .sp .LP Example 4 Destroying a vnd device in another zone .sp .LP To destroy the vnd device named net1 in the zone 1b7155a4-aef9-e7f0-d33c-9705e4b8b525, enter the following command: .sp .in +2 .nf # vndadm destroy -z 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 net1 .fi .in -2 .sp .LP Example 5 List all vnd devices .sp .LP To list all devices, run the following command: .sp .in +2 .nf # vndadm list NAME DATALINK ZONENAME net0 net0 global net0 net0 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 .fi .in -2 .sp .LP Example 6 Listing devices in a specific zone .sp .LP To list devices in a specific zone, run the following command: .sp .in +2 .nf # vndadm list -z 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 NAME DATALINK ZONENAME net0 net0 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 .fi .in -2 .sp .LP Example 7 List all devices in a parseable format .sp .LP To list all devices in a parseable format with the delimiter of ':', run the following command: .sp .in +2 .nf # vndadm list -p -d: -o name,datalink,zone net0:net0:global net0:net0:1b7155a4-aef9-e7f0-d33c-9705e4b8b525 .fi .in -2 .sp .LP Example 8 Retrieving all properties for a device .sp .LP To retrieve all of the properties for the vnd device foo0, run the following command: .sp .in +2 .nf # vndadm get foo0 LINK PROPERTY PERM VALUE foo0 rxbuf rw 65536 foo0 txbuf rw 65536 foo0 maxsize r- 4194304 foo0 mintu r- 0 foo0 maxtu r- 1518 foo0 _nflush rw 10 foo0 _burstsz rw 10 .fi .in -2 .sp .LP Example 9 Retrieving specific properties for a device .sp .LP To retrieve just the rxbuf and txbuf properties for the vnd device foo0, run the following command: .sp .in +2 .nf # vndadm get foo0 rxbuf txbuf LINK PROPERTY PERM VALUE foo0 rxbuf rw 65536 foo0 txbuf rw 65536 .fi .in -2 .sp .LP Example 10 Retrieving properties for a device in a parseable format .sp .LP To retrieve all properties for the vnd device foo0 in a parseable format, run the following command: .sp .in +2 .nf # vndadm get -p foo0 foo0 rxbuf rw 65536 foo0 txbuf rw 65536 foo0 maxsize r- 4194304 foo0 mintu r- 0 foo0 maxtu r- 1518 foo0 _nflush rw 10 foo0 _burstsz rw 10 .fi .in -2 .sp .LP Example 11 Setting a property on a device .sp .LP To set the receive buffer size to one megabyte on the device foo0, run the following command: .sp .in +2 .nf # vndadm set foo0 rxbuf=1M .fi .in -2 .sp .LP Example 12 Setting multiple properties on a device .sp .LP To set the transmit buffer to 300 Kb and the receive buffer to 1 Mb, run the following command: .sp .in +2 .nf # vndadm set foo0 rxbuf=300K txbuf=1M .fi .in -2 .sp .SH SEE ALSO dladm(1M), ipadm(1M), fcntl(2), fcntl.h(3HEAD), libvnd(3LIB), vndstat(1M), vnd(7D)