Provided by: lldpad-dev_1.1+git20221028.aa18720-2_amd64 bug

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