jammy (3) vde_stackcmd.3.gz

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.