NAME

       userbindmount,  userbindmount_unshare, userbindmount_set_cap_sysadm, userbindmount_string,
       userbindmount_data, userbindmount_fd - bind-mount in user-namespaces

SYNOPSIS

       #include <userbindmount.h>
       int userbindmount(const char *source, const char *target);
       int userbindmount_unshare(void);
       int userbindmount_set_cap_sysadm(void);
       int userbindmount_string(const char *string, const char *target, mode_t mode);
       int userbindmount_data(const void *data, size_t count, const char *target, mode_t mode);
       int userbindmount_fd(int fd, const char *target, mode_t mode);

       These functions are provided by libuserbindmount. Link with -luserbindmount.

DESCRIPTION

       Libuserbindmount is a library providing support for bind mount in user userspaces.

       userbindmount bind mounts source on destination.  If it is not permitted  in  the  current
       namespace it creates (unshare) a new user-namespace.

       userbindmount_unshare creates a new user-namespace where bind mount is allowed.

       userbindmount_set_cap_sysadm  add  the  CAP_SYS_ADMIN  ambient  capability  to the current
       namespace so that the ability of bind mount files and directories can be exported  to  new
       programs (ambient capabilities survive to execve(2)).

       userbindmount_string  bind-mounts on destination a temporary file whose (text) contents is
       provided by string. The temporary file is automatically  deleted  when  the  namespace  is
       closed or the file/directory unmounted.

       userbindmount_data  bind-mounts on destination a temporary file whose (binary) contents is
       provided by data and has the size of count bytes.  The  temporary  file  is  automatically
       deleted when the namespace is closed or the file/directory unmounted.

       userbindmount_fd  bind-mounts  on destination a temporary file whose contents is read from
       the by the file descriptor fd (up to the end of file). The temporary file is automatically
       deleted when the namespace is closed or the file/directory unmounted.

RETURN VALUE

       All  the  functions  provided  by  libuserbindmount  return  0  in case of success.  -1 is
       returned elseways and errno is set appropriately.

NOTES

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

EXAMPLES

       The following excerpts of C code shows the use of libuserbindmount: the inclusion  of  the
       header file for this library is required:
              #include <usrbindmount.h>

       Bind-mount /tmp/resolv.conf on /etc/resolv.conf:
              userbindmount("/tmp/resolv.conf", "/etc/resolv.conf");

       Bind-mount a string on /etc/resolv.conf:
              userbindmount_string("nameserver 9.9.9.90, "/etc/resolv.conf", 0600);

       Bind-mount a binary data on /proc/self/cmdline:
              static char fakeargv[] = {'c','m','d',0,
                   'a','r','g','1',0,
                   'a','r','g','2',0,
                   0};
              userbindmount_data(fakeargv, sizeof(fakeargv), "/proc/self/cmdline", 0600);

       Bind-mount the data read from a file descriptor on /etc/resolv.conf:
              userbindmount_fd(STDIN_FILENO, "/etc/resolv.conf", 0600);

       Bind-mount several files or directories:
              userbindmount("/tmp/resolv.conf", "/etc/resolv.conf");
              userbindmount("/tmp/passwd", "/etc/passwd");
              userbindmount("/tmp/hosts", "/etc/hosts");
       Only the first userbindmount creates a new namespace if needed.

       The  following program creates a namespace and runs a program in it.  In the new namespace
       bind-mount is allowed.
              #include <stdio.h>
              #include <unistd.h>
              #include <userbindmount.h>

              int main(int argc, char *argv[]) {
                   userbindmount_unshare();
                   userbindmount_set_cap_sysadm();
                   execvp(argv[1], argv+1);
              }

       It can be compiled and tested in the following way:
              $ gcc -o unshare_sysadm unshare_sysadm.c -luserbindmount
              $ unshare_sysadm bash
              $ cat /etc/resolv.conf
              nameserver 127.0.0.1
              $ echo "nameserver 9.9.9.9" > /tmp/resolv.conf
              $ busybox mount --bind /tmp/resolv.conf /etc/resolv.conf
              $ cat /etc/resolv.conf
              nameserver 9.9.9.9
              $ exit
              $
       please note that in the example the mount command by busybox has been used instead of  the
       standard  mount  by util-linux. In fact the standard mount command has not been updated to
       support the capabilities, and forbids the access to the mount system call if the effective
       user is not root, denying in this way a legal operation.

SEE ALSO

       mount(2), mount(8), user_namespaces(7)

BUGS

       Bug reports should be addressed to <info@virtualsquare.org>

AUTHORS

       Renzo Davoli <renzo@cs.unibo.it>