liblldp_clif
Section: Linux (3)
Updated: February 2014
Page Index
NAME
clif_vsi,clif_vsievt,clif_vsiwait - Manipulate VDP IEEE 802.1 Ratified Standard Associations
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 identifer 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 numner.
- 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 occured, 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 LLDPAD,
progname);
exit(5);
}
/* Attach to the vdp22 module */
if (clif_attach(tool_conn, "80c4")) {
fprintf(stderr, "%s can not attach to LLDPAD, 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