NAME

       vde_addstack, vde_delstack, vde_stackcmd, vde_msocket - vde network namespace as a user library

SYNOPSIS

       #include <vdestack.h>

       struct vdestack *vde_addstack(char *vdenet, char *ifname);

       void vde_delstack(struct vdestack *stack);

       int vde_stackcmd(struct vdestack *stack, char *stackcmd);

       int vde_msocket(struct vdestack *stack,int domain, int type, int protocol);

       void vde_default_stack(struct vdestack *stack);

DESCRIPTION

       Libvdestack  implements  the  idea  of  Internet of Threads through network namespaces.  By libvdestack a
       program can use one (or even several) private  networking  protocol  stack(s),  thus  a  program  can  be
       assigned its own IP address(es), routing etc.

       vde_addstack
              create  a  private  network  namespace:  vdenet  is the URL-like specification of a vde network as
              described in :vde_plug(1).  ifname is the name of the interface in the  network  namespace.   When
              ifname is NULL, the default interface :name is vde0.

       vde_delstack
              destroy a vdestack when it is no longer needed.

       vde_stackcmd
              run  a  command  or  a comma separated sequence of commands in the private network namespace.  The
              purpose of this function is to configure the networking parameters and options  (e.g. IP  address,
              routing).  For security reasons, commands must be specified using full pathnames.  Do not use this
              function  to  start long lasting or non terminating programs, the caller waits for the termination
              of the command sequence.

       vde_msocket
              it has the same semantics of socket(2) except that the socket is  defined  in  the  scope  of  the
              network  namespace  whose  descriptor  is  the  first argument.  The remaining arguments are those
              defined in socket(2).

       vde_default_stack
              define the default stack: any successive socket(2) call will use the stack passed as parameter  to
              vde_default_stack.  Use NULL to undefine the default stack.

RETURN VALUE

       vde_addstack  returns  a  struct  vdestack  pointer  which  is used as a descriptor and thus passed as an
       argument to the other functions of this library.  NULL is returned in case of error.

       vde_stackcmd returns the exit status of the command.  If the  stackcmd  argument  is  a  comma  separated
       sequence  of commands, the execution terminates upon the first command whose exit status is not zero, and
       the exit status of that command is  returned.   Therefore  when  vde_stackcmd  returns  zero  the  entire
       sequence was successfully executed.

       On  success,  vde_msocket  returns  a  valid  file  descriptor.  -1 is returned elseways and errno is set
       appropriately as described in socket(2).

NOTES

       Libvdestack fails if user namespaces have not been configured in  the  running  kernel  and  enabled  for
       users.  In Debian the sysctl knob kernel.unprivileged_userns_clone must be set to 1.

EXAMPLE

       The following excerpt of C code shows the use of libvdestack:

              ...
              int fd;
              int exit_status;
              struct vdestack *stack = vde_addstack("vde://", NULL);
              if (stack == NULL)
                  ... error management
              exit_status = vde_stackcmd(stack,
                        "/bin/ip link set vde0 up;"
                        "/bin/ip addr add 10.0.0.1/24 dev vde0;"
                        "/bin/ip route add default via 10.0.0.254");
              if (exit_status != 0)
                 ... error management
              fd = vde_msocket(stack, AF_INET, SOCK_STREAM, 0);
                 ... fd can be used in any context in which a file descriptor returned by socket(2) can.
              e.g. bind, accept, connect, read/write, send/recv ...
              vde_delstack(stack);

SEE ALSO

       socket(2), vde_plug(1)

BUGS

       Bug reports should be addressed to info@virtualsquare.org

AUTHOR

       VirtualSquare.  Project leader: Renzo Davoli.

VirtualSquare                                      August 2024                                    LIBVDESTACK(3)