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 creates 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 destroys 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 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 defines 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.