Provided by: lldpad-dev_1.0.1+git20150824.036e314-2_amd64 
NAME
clif_vsi,clif_vsievt,clif_vsiwait - Manipulate VDP IEEE 802.1 Ratified Standard
Assocications
SYNOPSIS
#include "include/clif.h"
int clif_vsi(struct clif *connp, char *ifname, unsigned int tlvid, char *cmd, char *reply,
size_t *reply_len);
int clif_vsievt(struct clif *connp, char *reply, size_t *reply_len, int wait);
int clif_vsiwait(struct clif *connp, char *ifname, unsigned int tlvid, char *cmd, char
*reply, size_t *reply_len, int wait);
DESCRIPTION
The Virtual station interface Discovery Protocol is a protocol to manage the association
and deassociation of virtual machine network interfaces (VSIs) between the station and an
adjacent switch. VDP is typically used with the local switch in VEPA mode and the
adjacent switch port in reflective relay (also called haripin) mode. This allows all
traffic to be sent to the switch for processing. Reflective relay mode is negotiated via
EVB TLVs (see lldptool-evb).
This man pages describes the IEEE 802.1 Qbg ratified standard dated from July 5th, 2012.
This differs from the draft 0.2 which is implemented as well, see lldptool-vdp(8). For
clarification in this man page the version complying to the ratified standard is called
VDP22 and the version complying to the draft 0.2 is called VDP.
VSI Parameter
Each VDP22 TLVs contains a command mode, manager identifier, type identifier, type
identifier version, VSI instance identifier, migiration hints and filter information. The
fields are explained next:
Command Mode:
The command mode determines the type of the VSI association to be established. It
is an ascii string can be one of:
assoc: Create an VSI association.
preassoc:
Create an VSI preassociation. The association is only announced to the
switch.
preassoc-rr:
Create an VSI preassociation. The association is only announced to the
switch and the switch should reserve the resources.
deassoc:
Delete an VSI association.
Other strings are not recognized and return an error.
Manager identifier:
The manager identifier is a string of up to 16 alphanumeric characters. It can
also be an UUID according to RFC 4122 with optional dashes in between.
Type Identifier:
The type identifier is a number in the range of 0 to 2^24 - 1.
Type Identifier Version:
The type identifier version is a number in the range of 0 to 255.
VSI Instance Identifier:
The VSI instance identifier is an UUID according to RFC 4122 with optional dashes
in between.
Migration Hints:
The migiration hints is a string aiding in migration of virtual machines:
none: No hints available.
from: The virtual machine is migriting away.
to: The virtual machine is migriting to.
Filter Information Data:
The filter information data can be supplied in four different formats:
vlan (1)
A vlan number only, also known as filter information format 1. The vlan
identifier is a number in the range of 1 to 2^16 - 1. The high order 4 bits
are used as quality of service bits. The vlan identifier can be zero, a
vlan identifier is then selected by the switch. Refer to IEEE 802.1 Qbg
ratified standard for details.
vlan-mac (2)
A vlan number and MAC address delimited by a slash ('-'), also known as
filter information format 2. The MAC address is specified in the format
xx:xx:xx:xx:xx:xx. The colons are mandatory. For vlan details see (1).
vlan-mac-group (4)
A vlan number, MAC address and group identifier, each delimited by a slash
('-'), also known as filter information format 4. The group identifier is a
32 bit number. For vlan and MAC address details see (1) and (2).
vlan--group (3)
A vlan number and group identifier, delimited by two slashes ('--'), also
known as filter information format 3. For vlan and group details see (1)
and (4).
Several filter information fields can be supplied. The have to be separated by comma
(',') and must be of the same format.
clif_vsi
This function sends a VSI command to lldpad(8). Parameter connp is a pointer to the
connection information. This information is obtained by calling clif_open and
clif_attach. Parameter ifname is the interface name lldpad (8) uses to send the VSI data.
Paramenter tlvid is the number of the VSI request. Valid numbers are 1 (for
Preassociation), 2 (for Preassociation with resource reservation) and 3 (for association),
4 (for Deassociation). Parameter cmd points to a character string containing the VSI
command. The layout of the VSI command has been explained above. All VSI fields are
concatenated together and separated to by commas (',') to form one large string.
Parameter reply is a pointer to a character array to receive the reply from lldpad(8).
Parameter reply_len holds the maximum number of characters available in the array pointed
to by reply. On successful return of the call, reply_len contains the number of
characters stored by lldpad(8) as the response of the command.
The functions returns zero on success and the reply and reply_len parameters are set.
Reply_len contains the number of bytes in the memory area pointed to by reply. Reply
contains the same information and format as the cmd parameter with several exceptions:
Command Mode:
This field should be the same as in cmd parameter. If it contains deassoc
then the command failed and the field ,igration hints contains an error
number.
Migration Hints:
This field contains the error number on why the command was not accepted by
lldpad(8). This command failed to pass the lldpad(8) sanity checks. Note
that the command was not even sent to the switch for processing. If no
error occurred, this field contains a dash ('-').
Filter Information Data:
If parameter cmd contained the a vlan identifier of value zero or a group
identifier the switch is allowed to assign a different vlan identifier,
which is saved and returned in the reply buffer.
All the other fields should be returned unchanged.
The function returns zero when the command was accepted by lldpad(8). Otherwise it
returns a positive number on why the command was not accepted.
clif_vsievt
After a successful return of clif_vsi, lldpad(8) has sent the command to the switch and
waits for a response from the switch. The switch can still deny the request. Function
clif_vsievt waits for parameter wait seconds for a reply from lldpad(8). Parameter
reply_len specifies the maximum buffer size pointed to by parameter reply. If a response
was received in wait seconds, the function returns zero and sets reply_len to the number
of bytes received and reply contains the response. The format is the same as in clif_vsi.
Since the switch can disassociate an established VSI association any time, it is
recommended to call clif_vsievt periodically to check for disassociate event messages from
lldpad(8).
If the functions fails it returns
-EINVAL
No attachment to lldpad(8) or wait is negative.
-EAGAIN
No message was received during the wait.
-EIO Message was received but could not be read.
-EBADF Message was received but was not an event message.
clif_vsiwait
This function combines clif_vsi and clif_vsievt into one function call.
EXAMPLE & USAGE
Code sample to create an VSI association on eth0:
char ok[MAX_CLIF_MSGBUF];
int rc;
size_t ok_len = sizeof(ok);
char *cmd ="assoc,blabla,12345,1,00000000-1111-2222-3333-aabbccddeeff"
",none,10-aa:bb:00:00:00:10,11-aa:bb:00:00:00:11";
struct clif *tool_conn = clif_open();
if (!tool_conn) {
fprintf(stderr, "%s can not open connection to LLDPAD0,
progname);
exit(5);
}
/* Attach to the vdp22 module */
if (clif_attach(tool_conn, "80c4")) {
fprintf(stderr, "%s can not attach to LLDPAD0, progname);
clif_close(tool_conn);
tool_conn = NULL;
exit(5);
}
rc = clif_vsiwait(tool_conn, "eth0", 1, cmd, ok, &ok_len, 5);
if (!rc) {
/* Parse the response in ok */
....
}
clif_detach(tool_conn));
clif_close(tool_conn);
SEE ALSO
lldptool-vdp(8), lldptool-evb(8), lldptool-evb22(8), lldptool(8), lldpad(8)
IEEE 802.1Qbg (http://www.ieee802.org/1/pages/802.1bg.html)
AUTHOR
Thomas Richter