dived - listen AF_UNIX socket for requests to start programs (by dive (1) ) and more.
NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT EXAMPLES CAVEATS AUTHOR AVAILABILITYNAME
dived - listen AF_UNIX socket for requests to start programs (by dive(1) ) and more.
SYNOPSIS
dived socket_path [options] [ -- command line ]
dived @abstract_address [options] [ -- command line ]
dived -i [options] [ -- command line ]
dived -J [options] -- command line
dived -j [options] -- command line
DESCRIPTION
This program a helper to start another processes (by remote request or directly) allowing using of various Linux features like capabilities, namespaces, chroot, etc. It is simple, ligtweight and does not require configuration files. The goal is to be a Linux tool for starting processes in various ways like socat(1) is a tool to use various types of sockets for various ways.
In the primary mode of operation dived listens AF_UINX socket and waits for dive(1) to connect. Upon connection, it
1. Obtains the connected’s client’s uid/gid;
2. Retrieves all file descriptors from the client;
3. Changes into appropriate uid/gid, sets up grounps;
4. Retrieves umask, environment variables, command line arguments, current directory;
5. Starts the requested program;
6. Waits for program termination and reports back the exit code.
This gives the remote user impression that he just started the program itself, but in fact the program is started remotely. This alone can be is useful when you want to start programs in other Linux namespaces.
With various options some steps can be added or removed, making additional uses, like:
* Act like simple sudo(8) (including with password authentication)
* Act like chroot(8) (also securely allowing users to use chroot)
* Act like unshare(1) (including for "pid" namespace)
* Act like capsh(8) (manage capabilities and lockbits)
OPTIONS
The first command line argument must be the socket (filesystem or @abstract) path or "-i" (--inetd) or "-J" (--just-execute).or "-j".
All the rest options should each take separate element of argv (no short options combining supported). Option’s arguments are the next argv element (no "--long-option=argument" supported, use "--long-option argument").
"--" stops option parsing and starts "forced command-line arguments", which limits what can be executed with dived. That way you specify the beginning of command line, and the remote user specifies the ending.
In
"-j"/"-J" mode the "--" is
required.
-A, --no-argv
Don’t let client set [part of] command line. Should be used with "-- forced command line arguments".
Example:
dived qqq -A -- /sbin/shutdown -s now
dive qqq this is ignored
-a, --authenticate
Start this program for authentication. The program is started using "system" after file descriptors are received from client, but before everything else (root, current dir, environment) is received. Nonzero exit code => rejected client.
DIVE_* environment variables are also available for the program. The program is expected to ask password, check user id or log the event.
The program is started as dived user, before any setuids.
Example:
dived /var/run/givemeroot.dive -C 777 -P -a ’user=root /root/askpassword’
gives the connected user root access if it enters the correct password
The program can also be used to do some setup as root before dropping privileges:
dived /var/run/emptynetwithlo -C 777 -P -s net -a ’ifconfig lo up’
-B, --retain-capabilities
Remove all capabilities from bounding set except of specified ones
Example:
dived -J -B cap_net_raw -- /bin/ping 127.0.0.1
-b, --remove-capabilities
Remove the selected capabilities from bounding set
dived -J -b cap_net_raw -- /bin/ping 127.0.0.1
ping: icmp open socket: Operation not permitted
-C, --chmod
chmod the socket to this mode (like ’0777’)
-c, --set-capabilities
Use libcap to interpret the specified string as capabilities set and apply it
Example:
cp /bin/ping /root/ping
setcap cap_net_raw+ei /root/ping
dived -J -c ’cap_net_raw+i’ -u nobody -- /root/ping 127.0.0.1
-d, --detach
Detach from console after opening the socket
-D, --children-daemon
Call "daemon" in forked children. Can be useful primarily when dealing with case when dived is started from console and not detached itself, so the started processes accidently receive server’s controlling terminal instead of the client’s one, causing weird behaviour.
-e, --effective-user
Set effective user ID to this user instead of SO_PEERCRED-obtained uid.
Note that other groups can be preserved in this mode.
-E, --no-environment
Don’t let client set any environment variables. The environment of the started programs will be the same as current environment.
By default dived only rejects DIVE_* environment variables.
-F, --no-fork
Accept once, serve only one client. Useful for debugging or for starting the requested process with pid=1 in PID namespace.
-g, --groups
setgid to this group instead of the client’s SO_PEERCRED-obtained gid. Also setgroups(2) to the specified comma-separated list of groups. With both -u specified to a numeric uid and -g specified to a list of numeric gids, dived should operate independently of /etc/passwd and /etc/group files.
Example:
# dived -J -S -T -u 123213 -g man,9999,43 -- /usr/bin/id
uid=123213 gid=12(man) groups=12(man),43(utmp),9999
-h, --chdir
Set this directory as current. If both --chdir and --chroot are specified, we remember the specified directory before chroot, but chdir to it after the chroot.
Example:
dived -J -S -T -R . -h / -- /bin/bash
Swap current and root directories and execute /bin/bash
Complicated example:
/usr/bin/dived -J -S -T -R /lib -h / -- /ld-linux.so.2 --library-path /i386-linux-gnu/ ./usr/bin/dived -J -S -T -R . -h ../.. -- /bin/bash
Escape chroot jail and re-enter it, leaving "outer" root as current directory, without executing any programs from "outer" system. "i386-linux-gnu", "ld-linux.so.2" and "/usr/bin/dived" may require adjustments.
-H, --no-chdir
Don’t let client set current directory
-i, --inetd
Don’t bind the socket, just use stdin (fd = 0) as accepted client’s socket.
Example /etc/inetd.conf configuration line:
/var/run/qqq.dive stream unix nowait qqq /usr/bin/dived dived -i
This allows anybody who can access /var/run/qqq.dive to run commands as user qqq.
-j, --just-execute2
Alias of -J -S -T -P
-J, --just-execute
Don’t use the socket at all (don’t receive file descriptors, argv, environment), just start (execve) the program right away.
-l, --rlimit
Set resource limits using setrlimit(2)
Argument should be comma-separated list of resource=hard_limit:soft_limit Soft limit may be omitted.
"dived --help" should show the list of recognized resources. You can also specify numeric resources.
Limit values are typicaly in bytes or in seconds.
Example:
dived -J --rlimit cpu=3 -- /bin/cat /dev/urandom > /dev/null
-L, --lock-securebits
set and lock SECBIT_NO_SETUID_FIXUP and SECBIT_NOROOT
This makes root user (uid=0) non-special for the kernel. To be used in conjunction with capabilities (-B and -c options).
-m, --ambient-capabilities
Make specified permitted and inheritable capabilities ambient, allowing them to be preserved across execve.
Minimum Linux kernel version is 4.3
Example:
USER=vi HOME=/home/vi dived -J -S -T -c CAP_NET_BIND_SERVICE+ip -m CAP_NET_BIND_SERVICE -u vi -- bash
-M, --no-umask
Don’t let client set umask
-n, --signals
Transfer all signals from dive
By default dived tells the PID of launched process to dive and it tries to deliver signals to the started process by itself (should be OK unless we are overriding user with -u, -e or -P).
With -n option dived accepts signals from the client and helps delivering them to the started program. This way unprivileged user can be allowed to send signals to dived-started programs.
--signals-pgid
Transfer all signals from dive to process group
Like -n option, but sends signal to entire process group instead of just one PID. Useful for allowing ˆC interrupting behaviour to travel though dive/dived.
-N, --setns
Open this file and setns(2) it.
Such files can be found in /proc/<pid>/ns/<something> or /var/run/netns/.
You can specify this option up to 8 times to "dive" into multiple namespaces.
Dived opens the namespace file each time it needs to do setns. So namespace will not be active only because of it is referenced by dived.
-O, --no-fds
Don’t let client set file descriptors
-p, --pidfile
save PID to this file. Can be specified multiple times. Can also be used to add dived-spawned processes to control group (cgroup) tasks file.
-P, --no-setuid
Don’t mess with user/group/capabilities things at all, just start the program.
-a option will still work like expected although.
-R, --chroot
chroot to this directory Note that current directory stays on unchrooted filesystem; use -W option to prevent. --chroot and --chdir can be specified at the same time and should not interfere with each other. If relative directory is specified as argument, it is taken before --chdir is applied.
pidfile is saved unchrooted.
-r, --client-chroot
Allow arbitrary chroot from client
By default dive always send the intended root directory descriptor, but dived ignores it. With this options we actually chroot to where client wants.
Use -X or -B ’’ options to disable starting any setuid-bit things after such chroot.
-s, --unshare
Unshare the specified namespaces. Known namespaces: ipc,net,fs,pid,uts,user,cgroup
-S, --no-setsid
no setsid
Don’t do:
setpgid(0, getppid());
setsid();
-t, --write-content
After setting up namespaces, but before dropping privileges, write specified content to file.
May be supplied more than one time.
Example:
dived -J -S -T -P -s user -t /proc/self/uid_map "0 1000 1" -t /proc/self/setgroups deny -t /proc/self/gid_map ’0 1000 1’ -- /bin/bash
-tt, --setup-uidgidmap
Alias of -t /proc/self/uid_map "0 ‘id -u‘ 1" -t /proc/self/setgroups deny -t /proc/self/gid_map "0 ‘id -g‘ 1"
Does not require any arguments.
Example:
dived -j -s user -tt -- /bin/bash
-T, --no-csctty
Don’t do:
ioctl (terminal_fd_received_from_client, TIOCSCTTY, 1);
-U, --chown
chown the socket to this user:group
Both user and group must be specified. They can be numeric.
-u, --user
setuid to this user instead of the client’s SO_PEERCRED-obtained uid. Unless --group is also specified, initialize groups with initgroups(3).
-V, --pivot-root
pivot_root to specified directory, putting old root to the directory specified as second argument
Example:
TODO
-W, --root-to-current
Set server’s root directory as current directory (implies -H; useful with -r)
Assist inspection of container’s filesystem using host’s utilities (if it is not visible directly).
Example:
dived /var/run/some_socket_on_shared_fs -U 0:0 -C 700 -W -r
dive /mnt/container/var/run/some_socket_on_shared_fs bash
than have /mnt/container/ as current directory, but hosts’s / as root; other filesystems mounted in container visible.
-w, --no-wait
Don’t fork and wait for exit code
Only setup things and execve program, don’t fork and wait to report program completion to the client.
-X, --no-new-privs
set PR_SET_NO_NEW_PRIVS
Deny elevating privileges using setuid-bit or filesystem capabilities.
Requires new enough Linux kernel.
ENVIRONMENT
dived does not
use any environment variables for configuration. But for
programs it is starting it sets the following environment
variables:
DIVE_UID
Is set to the user id of the client
DIVE_GID
Is set to the group id of the client
DIVE_PID
Is set of the PID of the program that connected to us.
DIVE_USER
Is set of the username of connected client (if it can be resolved from uid).
Note that any client’s DIVE_* environment variables are discarded.
EXAMPLES
dived /var/run/socket.dive -C 777 -d -p /var/run/socket.pid
Run dived that will just allow users to start programs in a way the most similar to as if users are starting them directly (without dive/dived). Detach and save pidfile. chmod the /var/run/socket.dive to 777.
dived
/var/run/socket.dive -U 0:chrooters -r -X
dived /var/run/socket.dive -U 0:chrooters -r -B
’’
Allow users in group "chrooters" chroot into arbitrary directory securely (turn off any privilege elevation using suid-bit or filesystem capabilities)
dived @without_network -C 777 --unshare net
Allow anybody run their programs without network access (i.e. in a separate unconfigured network namespace).
dived -J -T -S -P -L -- /bin/bash -i
Open a shell where uid=0 does not have any special privileges (according to Linux kernel)
dived
/var/run/container_admin.dive -T --unshare
pid,fs,net,uts,ipc -d
dive /var/run/container_admin.dive /bin/mount -t proc proc
/mnt/container/proc
dive /var/run/container_admin.dive /sbin/ifconfig lo up
dive /var/run/container_admin.dive dived
/var/run/container_user.dive -d -T -W
-B
CAP_CHOWN,CAP_DAC_OVERRIDE,CAP_DAC_READ_SEARCH,CAP_FOWNER,CAP_FSETID,CAP_IPC_OWNER,
CAP_KILL,CAP_NET_BIND_SERVICE,CAP_NET_RAW,CAP_SETGID,CAP_SETUID
-R /mnt/container
Start and set up a sort of a container. Create special restriced root login for it.
dived /var/run/alice4bob -u alice -U bob:0 -a ’exit $RANDOM’
Allow user bob
to run commands as alice (but only when he’s lucky
enough).
See additional examples at http://vi.github.com/dive/
CAVEATS
Some dived features (-X, for example) require recent enough Linux kernel. Other behaviour can vary a bit between versions of Linux kernel.
When using --unshare pid, dived can tall dive that it’s pid is 1. dive (if run as root) can "kill -INT 1" accidently, causing system reboot.
Although dived sets up groups using initgroups(3) , it does not set all user PAM settings like resource usage limits.
You need to understand what is exactly happening to use dived securely (especially as root). For example,
dived @socket -P -- chroot /some/root su -l someuser
is not secure (because of user can set PATH and LD_whatever before we execute binaries).
AUTHOR
Vitaly "_Vi" Shukela
AVAILABILITY
The program is intended to be used with Linux primarily.
Source code is available at https://github.com/vi/dive