path: root/usr/src/man/man8/vndadm.8

'\" 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 8 "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(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.

.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

fcntl(2), fcntl.h(3HEAD), libvnd(3LIB), vnd(7D), dladm(8), ipadm(8), vndstat(8)