1liblldp_clif(3)                      Linux                     liblldp_clif(3)
2
3
4

NAME

6       clif_vsi,clif_vsievt,clif_vsiwait  - Manipulate VDP IEEE 802.1 Ratified
7       Standard Assocications
8

SYNOPSIS

10       #include "include/clif.h"
11
12       int clif_vsi(struct clif *connp, char *ifname, unsigned int tlvid, char
13       *cmd, char *reply, size_t *reply_len);
14
15       int clif_vsievt(struct clif *connp, char *reply, size_t *reply_len, int
16       wait);
17
18       int clif_vsiwait(struct clif *connp, char *ifname, unsigned int  tlvid,
19       char *cmd, char *reply, size_t *reply_len, int wait);
20
21

DESCRIPTION

23       The  Virtual station interface Discovery Protocol is a protocol to man‐
24       age the association and deassociation of virtual machine network inter‐
25       faces  (VSIs) between the station and an adjacent switch.  VDP is typi‐
26       cally used with the local switch in VEPA mode and the  adjacent  switch
27       port  in  reflective relay (also called haripin) mode.  This allows all
28       traffic to be sent to the switch for processing.  Reflective relay mode
29       is negotiated via EVB TLVs (see lldptool-evb).
30
31       This  man  pages  describes  the IEEE 802.1 Qbg ratified standard dated
32       from July 5th, 2012. This differs from the draft 0.2  which  is  imple‐
33       mented  as  well,  see  lldptool-vdp(8).  For clarification in this man
34       page the version complying to the ratified standard is called VDP22 and
35       the version complying to the draft 0.2 is called VDP.
36
37   VSI Parameter
38       Each VDP22 TLVs contains a command mode, manager identifier, type iden‐
39       tifier, type identifier version, VSI  instance  identifier,  migiration
40       hints and filter information.  The fields are explained next:
41
42       Command Mode:
43              The  command  mode determines the type of the VSI association to
44              be established.  It is an ascii string can be one of:
45
46              assoc: Create an VSI association.
47
48              preassoc:
49                     Create an VSI preassociation.  The  association  is  only
50                     announced to the switch.
51
52              preassoc-rr:
53                     Create  an  VSI  preassociation.  The association is only
54                     announced to the switch and the switch should reserve the
55                     resources.
56
57              deassoc:
58                     Delete an VSI association.
59       Other strings are not recognized and return an error.
60
61       Manager identifier:
62              The  manager  identifier  is  a  string of up to 16 alphanumeric
63              characters.  It can also be an UUID according to RFC  4122  with
64              optional dashes in between.
65
66       Type Identifier:
67              The type identifier is a number in the range of 0 to 2^24 - 1.
68
69       Type Identifier Version:
70              The type identifer version is a number in the range of 0 to 255.
71
72       VSI Instance Identifier:
73              The  VSI  instance  identifier  is an UUID according to RFC 4122
74              with optional dashes in between.
75
76       Migration Hints:
77              The migiration hints is a string aiding in migration of  virtual
78              machines:
79
80              none:  No hints available.
81
82              from:  The virtual machine is migriting away.
83
84              to:    The virtual machine is migriting to.
85
86       Filter Information Data:
87              The  filter  information  data can be supplied in four different
88              formats:
89
90              vlan (1)
91                     A vlan number only, also known as filter information for‐
92                     mat 1.  The vlan identifier is a number in the range of 1
93                     to 2^16 - 1.  The high order 4 bits are used  as  quality
94                     of service bits.  The vlan identifier can be zero, a vlan
95                     identifier is then selected by the switch. Refer to  IEEE
96                     802.1 Qbg ratified standard for details.
97
98              vlan-mac (2)
99                     A vlan number and MAC address delimited by a slash ('-'),
100                     also known as  filter  information  format  2.   The  MAC
101                     address  is  specified  in  the format xx:xx:xx:xx:xx:xx.
102                     The colons are mandatory.  For vlan details see (1).
103
104              vlan-mac-group (4)
105                     A vlan number, MAC address  and  group  identifier,  each
106                     delimited by a slash ('-'), also known as filter informa‐
107                     tion format 4.  The group identifier is a 32 bit  number.
108                     For vlan and MAC address details see (1) and (2).
109
110              vlan--group (3)
111                     A  vlan  number  and  group  identifier, delimited by two
112                     slashes ('--'), also known as filter  information  format
113                     3.  For vlan and group details see (1) and (4).
114       Several filter information fields can be supplied.  The have to be sep‐
115       arated by comma (',') and must be of the same format.
116
117   clif_vsi
118       This function sends a VSI command to lldpad(8).  Parameter connp  is  a
119       pointer to the connection information.  This information is obtained by
120       calling clif_open and clif_attach.  Parameter ifname is  the  interface
121       name  lldpad  (8)  uses  to send the VSI data.  Paramenter tlvid is the
122       number of the VSI request.  Valid numbers are 1 (for Preassociation), 2
123       (for Preassociation with resource reservation) and 3 (for association),
124       4 (for Deassociation).  Parameter cmd points to a character string con‐
125       taining  the  VSI  command.   The  layout  of  the VSI command has been
126       explained above.  All VSI fields are concatenated  together  and  sepa‐
127       rated  to by commas (',') to form one large string.  Parameter reply is
128       a pointer to a character array to receive  the  reply  from  lldpad(8).
129       Parameter reply_len holds the maximum number of characters available in
130       the array pointed to by reply.   On  successful  return  of  the  call,
131       reply_len  contains the number of characters stored by lldpad(8) as the
132       response of the command.
133
134       The functions returns zero on  success  and  the  reply  and  reply_len
135       parameters are set.  Reply_len contains the number of bytes in the mem‐
136       ory area pointed to by reply.  Reply contains the same information  and
137       format as the cmd parameter with several exceptions:
138
139              Command Mode:
140                     This  field should be the same as in cmd parameter. If it
141                     contains deassoc then the command failed  and  the  field
142                     ,igration hints contains an error numner.
143
144              Migration Hints:
145                     This  field  contains the error number on why the command
146                     was not accepted by lldpad(8).  This  command  failed  to
147                     pass  the lldpad(8) sanity checks.  Note that the command
148                     was not even sent to the switch for  processing.   If  no
149                     error occured, this field contains a dash ('-').
150
151              Filter Information Data:
152                     If parameter cmd contained the a vlan identifier of value
153                     zero or a group  identifier  the  switch  is  allowed  to
154                     assign  a  different  vlan identifier, which is saved and
155                     returned in the reply buffer.
156       All the other fields should be returned unchanged.
157
158       The function returns zero when the command was accepted  by  lldpad(8).
159       Otherwise  it  returns  a  positive  number  on why the command was not
160       accepted.
161
162   clif_vsievt
163       After a successful return of clif_vsi, lldpad(8) has sent  the  command
164       to the switch and waits for a response from the switch.  The switch can
165       still deny the request.  Function clif_vsievt waits for parameter  wait
166       seconds  for a reply from lldpad(8).  Parameter reply_len specifies the
167       maximum buffer size pointed to by parameter reply.  If a  response  was
168       received  in wait seconds, the function returns zero and sets reply_len
169       to the number of bytes received and reply contains the  response.   The
170       format is the same as in clif_vsi.
171
172       Since  the  switch  can disassociate an established VSI association any
173       time, it is recommended to call clif_vsievt periodically to  check  for
174       disassociate event messages from lldpad(8).
175
176       If the functions fails it returns
177
178       -EINVAL
179              No attachment to lldpad(8) or wait is negative.
180
181       -EAGAIN
182              No message was received during the wait.
183
184       -EIO   Message was received but could not be read.
185
186       -EBADF Message was received but was not an event message.
187
188   clif_vsiwait
189       This function combines clif_vsi and clif_vsievt into one function call.
190

EXAMPLE & USAGE

192       Code sample to create an VSI association on eth0:
193
194       char ok[MAX_CLIF_MSGBUF];
195       int rc;
196       size_t ok_len = sizeof(ok);
197       char *cmd ="assoc,blabla,12345,1,00000000-1111-2222-3333-aabbccddeeff"
198                 ",none,10-aa:bb:00:00:00:10,11-aa:bb:00:00:00:11";
199       struct clif *tool_conn = clif_open();
200
201       if (!tool_conn) {
202             fprintf(stderr, "%s can not open connection to LLDPAD0,
203                  progname);
204             exit(5);
205       }
206
207       /* Attach to the vdp22 module */
208       if (clif_attach(tool_conn, "80c4")) {
209            fprintf(stderr, "%s can not attach to LLDPAD0, progname);
210            clif_close(tool_conn);
211            tool_conn = NULL;
212            exit(5);
213       }
214
215       rc = clif_vsiwait(tool_conn, "eth0", 1, cmd, ok, &ok_len, 5);
216       if (!rc) {
217            /* Parse the response in ok */
218            ....
219       }
220       clif_detach(tool_conn));
221       clif_close(tool_conn);
222

SEE ALSO

224       lldptool-vdp(8),  lldptool-evb(8), lldptool-evb22(8), lldptool(8), lld‐
225       pad(8)
226       IEEE 802.1Qbg (http://www.ieee802.org/1/pages/802.1bg.html)
227

AUTHOR

229       Thomas Richter
230
231
232
233open-lldp                        February 2014                 liblldp_clif(3)
Impressum