doc/uid_wrapper.1.txt

   1 uid_wrapper(1)
   2 ==============
   3 :revdate: 2015-11-03
   4
   5 NAME
   6 ----
   7
   8 uid_wrapper - A wrapper to fake privilege separation
   9
  10 SYNOPSIS
  11 --------
  12
  13 LD_PRELOAD=libuid_wrapper.so UID_WRAPPER=1 UID_WRAPPER_ROOT=1 *./myapplication*
  14
  15 DESCRIPTION
  16 -----------
  17
  18 - Allows uid switching as a normal user.
  19 - Start any application making it believe it is running as root.
  20 - Support for user/group changing in the local thread using the syscalls (like glibc).
  21 - More precisely this library intercepts seteuid and related calls, and simulates
  22   them in a manner similar to the nss_wrapper and socket_wrapper libraries.
  23
  24 Some projects like a file server need privilege separation to be able to switch
  25 to the connection user and do file operations. uid_wrapper convincingly lies to
  26 the application letting it believe it is operating as root and even switching
  27 between UIDs and GIDs as needed.
  28
  29 ENVIRONMENT VARIABLES
  30 ---------------------
  31
  32 *UID_WRAPPER*::
  33
  34 If you load the uid_wrapper and enable it with setting UID_WRAPPER=1 all setuid
  35 and setgid will work, even as a normal user.
  36
  37 *UID_WRAPPER_ROOT*::
  38
  39 It is possible to start your application as fake root with setting
  40 UID_WRAPPER_ROOT=1.
  41
  42 *UID_WRAPPER_DEBUGLEVEL*::
  43
  44 If you need to see what is going on in uid_wrapper itself or try to find a
  45 bug, you can enable logging support in uid_wrapper if you built it with
  46 debug symbols.
  47
  48 - 0 = ERROR
  49 - 1 = WARNING
  50 - 2 = DEBUG
  51 - 3 = TRACE
  52
  53 *UID_WRAPPER_MYUID*::
  54
  55 This environment variable can be used to tell uid_wrapper to let geteuid()
  56 return the real (instead of the faked) UID of the user who started the process
  57 with uid_wrapper.
  58
  59 --------------------------------------
  60 uid_t uid;
  61
  62 setenv("UID_WRAPPER_MYUID", "1", 1);
  63 uid = geteuid();
  64 unsetenv("UID_WRAPPER_MYUID");
  65 --------------------------------------
  66
  67 *UID_WRAPPER_DISABLE_DEEPBIND*::
  68
  69 This allows you to disable deep binding in uid_wrapper. This is useful for
  70 running valgrind tools or sanitizers like (address, undefined, thread).
  71
  72 EXAMPLE
  73 -------
  74
  75   $ LD_PRELOAD=libuid_wrapper.so UID_WRAPPER=1 UID_WRAPPER_ROOT=1 id
  76   uid=0(root) gid=0(root) 0(root)
  77
  78 WORKAROUNDS
  79 -----------
  80
  81 If you need to write code that behaves differently depending on whether
  82 uid_wrapper is  enabled or not, for example in cases where you have to file
  83 permissions, you can predefine the uid_wrapper_enabled() function in your
  84 project as follows:
  85
  86 --------------------------------------
  87 bool uid_wrapper_enabled(void)
  88 {
  89     return false;
  90 }
  91 --------------------------------------
  92
  93 Since uid_wrapper overloads this function if enabled, you can use it in your
  94 code to detect uid_wrapper.