commit d43d0f46a13c4d581ce4682dd480f5184dad3d66
parent 1d657b51941acc808cdca704e7a50fcf15c69c24
Author: Jan Pobrislo <ccx@te2000.cz>
Date: Wed, 19 Nov 2025 08:52:38 +0000
Add README file
Diffstat:
| A | README | | | 161 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 161 insertions(+), 0 deletions(-)
diff --git a/README b/README
@@ -0,0 +1,161 @@
+Linux namespace utilities
+=========================
+
+The missing primitives for creating reliable and secure sandboxes.
+
+Building and installing
+-----------------------
+
+TBW
+
+The provided programs
+---------------------
+
+lns-pidns
+~~~~~~~~~
+
+Run program in new PID namespace (as PID2) while providing intelligent PID1 which reaps
+orphan processes and terminates if it's parent exits.
+You can use this for non-supervised tasks in place of the pidns support in s6.
+
+Usage:
+> lns-pidns prog...
+
+
+lns-mounts-to-env
+~~~~~~~~~~~~~~~~~
+
+Record all currently mounted filesystems into environment variables in the order they
+would need to be unmounted as `NS_MTP_1=<mountpoint>` up to `NS_MTP_COUNT`.
+This can be subsequently used by `lns-lockdown` to remove access to original filesystem
+while preserving all mounts done from this point onwards.
+
+> lns-mounts-to-env prog...
+
+lns-envuidgid
+~~~~~~~~~~~~~
+
+lns-envuidgid potentially sets the UID, GID and GIDLIST environment variables
+according to the options and arguments it is given; then it executes into
+another program.
+This is clone of `s6-envuidgid` to avoid package dependency.
+
+Usage:
+> lns-envuidgid [ -i | -D uid:gid:gidlist ] [ -u | -g | -B ] [ -n ] account prog...
+
+ lns-envuidgid looks account up by name in the account database.
+ It sets the UID environment variable to account's uid, and the GID
+ environment variable to account's gid.
+ It also sets the GIDLIST environment variable to a comma-separated list of
+ supplementary group ids account is a member of according to the group
+ database. (If account doesn't belong to any other group than its primary
+ group, GIDLIST is still set, but empty.)
+ Then it executes into prog....
+
+Options:
+ -u : user. account will be interpreted as a user name; the UID environment
+ variable will be set to its numerical value, and the GID and GIDLIST
+ variables will not be touched.
+ -g : group. account will be interpreted as a group name instead of a user
+ name; the GID environment variable will be set to its numerical value, and
+ the UID and GIDLIST variables will not be touched.
+ -B : both user and group. account will be interpreted as user:group. The
+ GIDLIST variable will not be touched. If user does not exist, the UID
+ variable will be set to 0 unless a better default is provided with the -D
+ option. If group does not exist, the GID variable will be set to 0 unless a
+ better default is provided with the -D option.
+ -n : numerical fallback. If account cannot be found in the user or group
+ database, try to interpret the given values literally. For instance,
+ lns-envuidgid -B root:42 will fail if there's no group named 42 in the group
+ database, but lns-envuidgid -nB root:42 will set UID to 0 and GID to 42.
+ -i : insist. If account is unknown, exit 1 with an error message. This is
+ the default.
+ -D uid:gid:gidlist : if account is unknown, use uid, gid and gidlist as the
+ values for UID, GID and GIDLIST.
+
+
+lns-applyuidgid
+~~~~~~~~~~~~~~~
+Drop privileges for current process by setting user/group information, optionally
+retaining some Linux capabilites and setting securebits so the process and it's children
+can't gain any more capabilities (disabling suid, sgid and filecaps).
+This is extension of the `s6-applyuidgid` program.
+
+Usage:
+> lns-applyuidgid [ -z ] [ -u uid ] [ -g gid ] [ -G gidlist ] [ -U ] iab_caps prog...
+
+ -z : unexport. The UID, GID and GIDLIST variables will be removed from the
+ process environment.
+ -u uid : set the process' user ID to uid
+ -g gid : set the process' group ID to gid
+ -G gidlist : set the process' supplementary group list to gidlist, which
+ must be given as a comma-separated list of numeric GIDs, without spaces.
+ -U : set the process' user ID, group ID and supplementary group list to the
+ values of the UID, GID and GIDLIST environment variables. If a -u, -g or -G
+ option is given after -U, the command line value overrides the environment
+ variable.
+ <iab_caps> : retain some Linux capabilities by customizing the Inherited, Ambient and
+ Bound capability vectors. You can use comma-delimited list of capability names
+ prefixed by caret, e.g. `^CAP_NET_ADMIN,^CAP_NET_RAW` to set them in the Inherited
+ and Ambient vectors which will make them be retained across exec() and fork().
+ Empty string will result in no capabilities being retained.
+ See cap_text_formats(7) for details of the syntax.
+
+
+lns-lockdown
+~~~~~~~~~~~~
+
+Switch root directory of current process (pivot_root), umount directories which should
+not be accessible, then drop privileges as `lns-applyuidgid -U` does.
+
+Usage:
+> lns-lockdown [ -U iab_caps ] [ -S seccomp_bpf_fd ] [ -C newcwd ] new_root put_old prog...
+
+Options:
+ -U <iab_caps>
+ Set UID, GID and GIDLIST (supplementary groups) from environment while also
+ setting Linux capabilities from <iab_caps> string. See cap_text_formats(7) for syntax.
+ Empty string will result in no capabilities being retained.
+
+ -S <seccomp_bpf_fd>
+ Read program from given filedescriptor and set it as current syscall filter.
+
+ -C <newcwd>
+ Set current directory to <directory> after pivot_root/chroot but before
+ executing the program given as argument.
+
+* First <newroot> is set as new filesystem root and the previous root is placed in
+ <put_old> inside <newroot>.
+* Then environment variables `NS_MTP_#` where # is number from 1 to value of
+ `NS_MTP_COUNT` are prefixed by <put_old> and the resulting path is unmounted.
+* Next if -U was specified then preserved Linux capabilities are set according to
+ <iab_caps>, environment variables UID, GID and GIDLIST are set as process user id,
+ group id, and supplementary group ids, finally securebits are set so the process and
+ it's children can't gain any more capabilities (disabling suid, sgid and filecaps).
+* Next if -S was specified the given filedescriptor is read and then set as a BPF
+ program to filter allowed syscalls via seccompp.
+* Next if -C was specified the current directory changed to <newcwd>, otherwise it's
+ left in the root directory.
+* Finally it executes into <prog>.
+
+lns-mount-chroot
+~~~~~~~~~~~~~~~~
+
+Execline script to prepare new root, usually to be run in freshly created mount
+namespace.
+
+Usage:
+> lns-mount-chroot chroot_dir { prog1... } prog2...
+
+`lns-mount-chroot` performs these steps in sequence:
+* runs `lns-mount-to-env` to record existing mountpoints to be unmounted by `lns-lockdown`
+* bind-mounts <image_root> onto $LNS_ROOT (defaults to /mnt/chroot)
+* mounts proc filesystem
+* mounts tmpfs at $LNS_ROOT/dev, devpts on dev/pts and mqueue on dev/mqueue
+* creates device nodes for null, full, random, urandom, zero, tty and ptmx
+* creates `/proc/self/fd` symlinks for stdin, stdout and stderr
+* runs <prog1> which can do further modifications to $LNS_ROOT/dev
+* remounts $LNS_ROOT/dev read-only
+* executes into <prog2>
+
+
