README (7693B)
1 Linux namespace utilities 2 ========================= 3 4 The missing primitives for creating reliable and secure sandboxes. 5 6 Building and installing 7 ----------------------- 8 9 TBW 10 11 The provided programs 12 --------------------- 13 14 lns-pidns 15 ~~~~~~~~~ 16 17 Run program in new PID namespace (as PID2) while providing intelligent PID1 which reaps 18 orphan processes and terminates if it's parent exits. 19 You can use this for non-supervised tasks in place of the pidns support in s6. 20 21 Usage: 22 > lns-pidns prog... 23 24 25 lns-mounts-to-env 26 ~~~~~~~~~~~~~~~~~ 27 28 Record all currently mounted filesystems into environment variables in the order they 29 would need to be unmounted as `NS_MTP_1=<mountpoint>` up to `NS_MTP_COUNT`. 30 This can be subsequently used by `lns-lockdown` to remove access to original filesystem 31 while preserving all mounts done from this point onwards. 32 33 > lns-mounts-to-env prog... 34 35 lns-envuidgid 36 ~~~~~~~~~~~~~ 37 38 lns-envuidgid potentially sets the UID, GID and GIDLIST environment variables 39 according to the options and arguments it is given; then it executes into 40 another program. 41 This is clone of `s6-envuidgid` to avoid package dependency. 42 43 Usage: 44 > lns-envuidgid [ -i | -D uid:gid:gidlist ] [ -u | -g | -B ] [ -n ] account prog... 45 46 lns-envuidgid looks account up by name in the account database. 47 It sets the UID environment variable to account's uid, and the GID 48 environment variable to account's gid. 49 It also sets the GIDLIST environment variable to a comma-separated list of 50 supplementary group ids account is a member of according to the group 51 database. (If account doesn't belong to any other group than its primary 52 group, GIDLIST is still set, but empty.) 53 Then it executes into prog.... 54 55 Options: 56 -u : user. account will be interpreted as a user name; the UID environment 57 variable will be set to its numerical value, and the GID and GIDLIST 58 variables will not be touched. 59 -g : group. account will be interpreted as a group name instead of a user 60 name; the GID environment variable will be set to its numerical value, and 61 the UID and GIDLIST variables will not be touched. 62 -B : both user and group. account will be interpreted as user:group. The 63 GIDLIST variable will not be touched. If user does not exist, the UID 64 variable will be set to 0 unless a better default is provided with the -D 65 option. If group does not exist, the GID variable will be set to 0 unless a 66 better default is provided with the -D option. 67 -n : numerical fallback. If account cannot be found in the user or group 68 database, try to interpret the given values literally. For instance, 69 lns-envuidgid -B root:42 will fail if there's no group named 42 in the group 70 database, but lns-envuidgid -nB root:42 will set UID to 0 and GID to 42. 71 -i : insist. If account is unknown, exit 1 with an error message. This is 72 the default. 73 -D uid:gid:gidlist : if account is unknown, use uid, gid and gidlist as the 74 values for UID, GID and GIDLIST. 75 76 77 lns-applyuidgid 78 ~~~~~~~~~~~~~~~ 79 Drop privileges for current process by setting user/group information, optionally 80 retaining some Linux capabilites and setting securebits so the process and it's children 81 can't gain any more capabilities (disabling suid, sgid and filecaps). 82 This is extension of the `s6-applyuidgid` program. 83 84 Usage: 85 > lns-applyuidgid [ -z ] [ -u uid ] [ -g gid ] [ -G gidlist ] [ -U ] iab_caps prog... 86 87 -z : unexport. The UID, GID and GIDLIST variables will be removed from the 88 process environment. 89 -u uid : set the process' user ID to uid 90 -g gid : set the process' group ID to gid 91 -G gidlist : set the process' supplementary group list to gidlist, which 92 must be given as a comma-separated list of numeric GIDs, without spaces. 93 -U : set the process' user ID, group ID and supplementary group list to the 94 values of the UID, GID and GIDLIST environment variables. If a -u, -g or -G 95 option is given after -U, the command line value overrides the environment 96 variable. 97 <iab_caps> : retain some Linux capabilities by customizing the Inherited, Ambient and 98 Bound capability vectors. You can use comma-delimited list of capability names 99 prefixed by caret, e.g. `^CAP_NET_ADMIN,^CAP_NET_RAW` to set them in the Inherited 100 and Ambient vectors which will make them be retained across exec() and fork(). 101 Empty string will result in no capabilities being retained. 102 See cap_text_formats(7) for details of the syntax. 103 104 105 lns-lockdown 106 ~~~~~~~~~~~~ 107 108 Switch root directory of current process (pivot_root), umount directories which should 109 not be accessible, then drop privileges as `lns-applyuidgid -U` does. 110 111 Usage: 112 > lns-lockdown [ -U iab_caps ] [ -S seccomp_bpf_fd ] [ -C newcwd ] new_root put_old prog... 113 114 Options: 115 -U <iab_caps> 116 Set UID, GID and GIDLIST (supplementary groups) from environment while also 117 setting Linux capabilities from <iab_caps> string. See cap_text_formats(7) for syntax. 118 Empty string will result in no capabilities being retained. 119 120 -S <seccomp_bpf_fd> 121 Read program from given filedescriptor and set it as current syscall filter. 122 123 -C <newcwd> 124 Set current directory to <directory> after pivot_root/chroot but before 125 executing the program given as argument. 126 127 * First <newroot> is set as new filesystem root and the previous root is placed in 128 <put_old> inside <newroot>. 129 * Then environment variables `NS_MTP_#` where # is number from 1 to value of 130 `NS_MTP_COUNT` are prefixed by <put_old> and the resulting path is unmounted. 131 * Next if -U was specified then preserved Linux capabilities are set according to 132 <iab_caps>, environment variables UID, GID and GIDLIST are set as process user id, 133 group id, and supplementary group ids, finally securebits are set so the process and 134 it's children can't gain any more capabilities (disabling suid, sgid and filecaps). 135 * Next if -S was specified the given filedescriptor is read and then set as a BPF 136 program to filter allowed syscalls via seccompp. 137 * Next if -C was specified the current directory changed to <newcwd>, otherwise it's 138 left in the root directory. 139 * Finally it executes into <prog>. 140 141 142 lns-prepare-chroot 143 ~~~~~~~~~~~~~~~~~~ 144 Populate necessary directories and device nodes in new root. 145 146 > lns-prepare-chroot chroot_dir 147 148 * mounts proc filesystem 149 * mounts tmpfs at $LNS_ROOT/dev, devpts on dev/pts and mqueue on dev/mqueue 150 * creates device nodes for null, full, random, urandom, zero, tty and ptmx 151 * creates `/proc/self/fd` symlinks for stdin, stdout and stderr 152 153 154 lns-bind-chroot 155 ~~~~~~~~~~~~~~~ 156 157 Execline script to prepare new root by mounting existing directory as a base. 158 Usually to be run in freshly created mount namespace. 159 160 Usage: 161 > lns-bind-chroot image_root { prog1... } prog2... 162 163 `lns-bind-chroot` performs these steps in sequence: 164 * runs `lns-mount-to-env` to record existing mountpoints to be unmounted by `lns-lockdown` 165 * bind-mounts <image_root> onto $LNS_ROOT (defaults to /mnt/chroot) 166 * runs `lns-prepare-chroot` on $LNS_ROOT 167 * runs <prog1> which can do further modifications to $LNS_ROOT/dev 168 * remounts $LNS_ROOT/dev read-only 169 * executes into <prog2> 170 171 172 lns-tmpfs-chroot 173 ~~~~~~~~~~~~~~~~ 174 175 Execline script to prepare new root by mounting empty tmpfs. 176 Usually to be run in freshly created mount namespace. 177 178 Usage: 179 > lns-tmpfs-chroot chroot_dir { prog1... } prog2... 180 181 `lns-tmpfs-chroot` performs these steps in sequence: 182 * runs `lns-mount-to-env` to record existing mountpoints to be unmounted by `lns-lockdown` 183 * mounts empty tmpfs on top of <chroot_dir> 184 * runs `lns-prepare-chroot` on <chroot_dir> 185 * runs <prog1> which can do further modifications to <chroot_dir>/dev 186 * remounts <chroot_dir>/dev read-only 187 * executes into <prog2> 188 189