dived.1

.TH DIVED 1 2013-03-12 v1.2

.SH NAME

dived - listen AF_UNIX socket for requests to start programs (by
.BR dive (1)
) and more.

.SH SYNOPSIS

.BI "dived " "socket_path [options] [ " "-- " "command line ]"

.BI "dived @" "abstract_address [options] [ " "-- " "command line ]"

.BI "dived -i " "[options] [ " "-- " "command line ]"

.BI "dived -J " "[options]" " -- " "command line"

.BI "dived -j " "[options]" " -- " "command line"


.SH 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 
.BR 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
.BR 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
.BR sudo (8)
(including with password authentication)

* Act like 
.BR chroot (8)
(also securely allowing users to use chroot)

* Act like 
.BR unshare (1)
(including for "pid" namespace)

* Act like 
.BR capsh (8)
(manage capabilities and lockbits)





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



.TP
.B -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


.TP
.B -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'

    
.TP
.B -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


.TP
.B -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
    
.TP
.B -C, --chmod
chmod the socket to this mode (like '0777')


.TP
.B -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

  
.TP
.B -d, --detach
Detach from console after opening the socket


.TP
.B -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.

.TP
.B -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.

  
.TP
.B -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.


.TP
.B -F, --no-fork
Accept once, serve only one client. Useful for debugging or for starting the
requested process with pid=1 in PID namespace.

.TP
.B  -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

.TP
.B -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.

.TP
.B -H, --no-chdir         
Don't let client set current directory


.TP
.B -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.

.TP
.B -j, --just-execute2
Alias of -J -S -T -P


.TP
.B -J, --just-execute
Don't use the socket at all (don't receive file descriptors, argv, environment),
just start (execve) the program right away.



.TP
.B -l, --rlimit           
Set resource limits using
.BR 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


.TP
.B  -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).

.TP
.B -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

.TP
.B -M, --no-umask        
Don't let client set umask

 
.TP
.B -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.

.TP
.B --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.

.TP
.B -N, --setns           
Open this file and 
.BR 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.


.TP
.B -O, --no-fds          
Don't let client set file descriptors


.TP
.B -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.


.TP
.B -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.


.TP
.B -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.


.TP
.B -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.

.TP
.B -s, --unshare          
Unshare the specified namespaces.
Known namespaces: ipc,net,fs,pid,uts,user,cgroup

.TP
.B -S, --no-setsid
no setsid

Don't do:

setpgid(0, getppid());

setsid();

.TP
.B -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

.TP
.B -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

.TP
.B -T, --no-csctty        
Don't do: 

ioctl (terminal_fd_received_from_client, TIOCSCTTY, 1);


.TP
.B -U, --chown            
chown the socket to this user:group

Both user and group must be specified. They can be numeric.

.TP
.B  -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).

.TP
.B  -V, --pivot-root
pivot_root to specified directory, putting old root to the directory specified as second argument

Example:

TODO


.TP
.B -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.


.TP
.B -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.


.TP
.B -X, --no-new-privs     
set PR_SET_NO_NEW_PRIVS

Deny elevating privileges using setuid-bit or filesystem capabilities.

Requires new enough Linux kernel.


.SH ENVIRONMENT
dived does not use any environment variables for configuration.
But for programs it is starting it sets the following environment variables:

.TP
.B DIVE_UID
Is set to the user id of the client

.TP
.B DIVE_GID
Is set to the group id of the client

.TP
.B DIVE_PID
Is set of the PID of the program that connected to us.

.TP
.B DIVE_USER
Is set of the username of connected client 
(if it can be resolved from uid).

.TP
Note that any client's DIVE_* environment variables are discarded.


.SH EXAMPLES

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

.B dived /var/run/socket.dive -U 0:chrooters -r -X
.br
.B 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)


.B dived @without_network -C 777 --unshare net

Allow anybody run their programs without network access 
(i.e. in a separate unconfigured network namespace).


.B 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)


.B dived  /var/run/container_admin.dive -T --unshare pid,fs,net,uts,ipc -d
.br
.B dive /var/run/container_admin.dive /bin/mount -t proc proc /mnt/container/proc
.br
.B dive /var/run/container_admin.dive /sbin/ifconfig  lo up
.br
.B dive /var/run/container_admin.dive dived /var/run/container_user.dive -d -T -W 
.br
    -B CAP_CHOWN,CAP_DAC_OVERRIDE,CAP_DAC_READ_SEARCH,CAP_FOWNER,CAP_FSETID,CAP_IPC_OWNER,
.br
    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.


.B 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).


.TP
See additional examples at http://vi.github.com/dive/


.SH 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 
.BR 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).

.SH AUTHOR
Vitaly "_Vi" Shukela

.SH AVAILABILITY
The program is intended to be used with Linux primarily.

Source code is available at https://github.com/vi/dive