liblldp_clif-vdp22

liblldp_clif(3)                      Linux                     liblldp_clif(3)



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



open-lldp                        February 2014                 liblldp_clif(3)