illumos: manual page: vndadm.8

VNDADM(8) Maintenance Commands and Procedures VNDADM(8)

NAME

vndadm - administer vnd devices

SYNOPSIS

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...

DESCRIPTION

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(8)) 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.

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.

OPTIONS

All vndadm subcommands have the following common option:

-z zonename

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.

When -z is used and multiple devices are specified, then the use of
-z applies to all of the devices.

SUBCOMMANDS

vndadm create [-z zonename] [-l datalink] device

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.

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.

-l datalink

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.

-z zonename

See OPTIONS above.

vndadm destroy [-z zonename] device...

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.

-z zonename

See OPTIONS above.

vndadm list [-p] [-d delim] [-o field,...] [-z zonename] [device]...

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.

-o field[,...]

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:

NAME

The name of the vnd device.

DATALINK

The name of the data link the vnd device was created over.

ZONENAME

The name of the zone that the vnd device exists in.

-p

Display the output in a stable machine parseable format. The -o
option is required with the -p option. See "Parseable Output
Format" below.

-d delim

Change the delimiter used in conjunction with generating
parseable output. This option may only be specified when -p is
also specified.

-z zonename

See OPTIONS above.

vndadm get [-p] [-d delim] [-z zonename] device [prop]...

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:

LINK

The name of the device

PROPERTY

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.

PERM

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.

VALUE

The value of the property.

-p

Display the output in a stable machine parseable format. See
"Parseable Output Format" below.

-d delim

Change the delimiter used in conjunction with generating
parseable output. This option may only be specified when -p is
also specified.

-z zonename

See OPTIONS above.

vndadm set [-z zonename] device prop=val...

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.

-z zonename

See OPTIONS above.

Parseable Output Format

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.

Properties

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.

rxbuf

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.

txbuf

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.

maxsize

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.

mintu

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.

maxtu

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.

EXAMPLES

Example 1 Creating a vnd device

To create a vnd device over the VNIC named net0, enter the following
command:

# vndadm create net0

Example 2 Creating a vnd device in another zone

To create a vnd device over the VNIC named net1 in the zone
1b7155a4-aef9-e7f0-d33c-9705e4b8b525, enter the following command:

# vndadm create -z 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 net1

Example 3 Destroying a vnd device

To destroy the vnd device named net0, enter the following command:

# vndadm destroy net0

Example 4 Destroying a vnd device in another zone

To destroy the vnd device named net1 in the zone
1b7155a4-aef9-e7f0-d33c-9705e4b8b525, enter the following command:

# vndadm destroy -z 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 net1

Example 5 List all vnd devices

To list all devices, run the following command:

# vndadm list
NAME DATALINK ZONENAME
net0 net0 global
net0 net0 1b7155a4-aef9-e7f0-d33c-9705e4b8b525

Example 6 Listing devices in a specific zone

To list devices in a specific zone, run the following command:

# vndadm list -z 1b7155a4-aef9-e7f0-d33c-9705e4b8b525

NAME DATALINK ZONENAME
net0 net0 1b7155a4-aef9-e7f0-d33c-9705e4b8b525

Example 7 List all devices in a parseable format

To list all devices in a parseable format with the delimiter of ':', run
the following command:

# vndadm list -p -d: -o name,datalink,zone
net0:net0:global
net0:net0:1b7155a4-aef9-e7f0-d33c-9705e4b8b525

Example 8 Retrieving all properties for a device

To retrieve all of the properties for the vnd device foo0, run the
following command:

# 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

Example 9 Retrieving specific properties for a device

To retrieve just the rxbuf and txbuf properties for the vnd device foo0,
run the following command:

# vndadm get foo0 rxbuf txbuf
LINK PROPERTY PERM VALUE
foo0 rxbuf rw 65536
foo0 txbuf rw 65536

Example 10 Retrieving properties for a device in a parseable format

To retrieve all properties for the vnd device foo0 in a parseable format,
run the following command:

# 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

Example 11 Setting a property on a device

To set the receive buffer size to one megabyte on the device foo0, run
the following command:

# vndadm set foo0 rxbuf=1M

Example 12 Setting multiple properties on a device

To set the transmit buffer to 300 Kb and the receive buffer to 1 Mb, run
the following command:

# vndadm set foo0 rxbuf=300K txbuf=1M