dive - connect to dived (1) and start program remotely

NAME  SYNOPSIS  DESCRIPTION  OPTIONS  ENVIRONMENT  EXIT STATUS  EXAMPLES  CAVEATS  AUTHOR  AVAILABILITY 

---

NAME

dive - connect to dived(1) and start program remotely

SYNOPSIS

dive socket_path [program arguments]

dive @abstract_address [program arguments]

DESCRIPTION

This program connects to AF_UNIX socket created by dived(1) and requests it to start program.

By default file descriptors, command-line arguments, envrironment variables, umask, current directory and controlling terminal are transferred to the remote program, mimicing the behaviour as if the program were just launched with execve(2) .

Primary use case of the program is to launch programs inside unshare(1) / lxc(1) containers from outside easily and without network connection.

OPTIONS

The first argument must be the socket path or abstract socket name, prepended with ’@’.

All the rest command line arguments are sent to server. Unless the server forces the beginning of command line, the first of these arguments is the name of the program to execute.

ENVIRONMENT

Note that all DIVE_* envrironment variables are discarded by the server.
DIVE_CURDIR

Open and send the descriptor of specified directory to be current directory for the program we are starting remotely.

DIVE_ROOTDIR

Open and send the descriptor of specified directory to be root directory. Setting the root directory is not enabled by default.

DIVE_TERMINAL

Open the given file (or use the given file descritor, if prepended with ’@’) and send it to server to be controlling terminal for the program we are starting. By default stdin is used. You can specify @-1 or empty value if you don’t want dived to touch your controlling terminal.

DIVE_WAITMODE

If set to 0 (normal waiting), dive tries explicitly wait for the remote program’s exit code and preserve it when exiting. If set to 1 (no waiting), dive starts the program and does not wait for anything, just exits. If set to 2 (workaround waiting), dive opens one additional file descitor and waits for all programs that holds it go away, then exits.

By default it is 0. If the server refuses to do normal waiting for use, dive automatically switches to workaround waiting.

DIVE_SIGFWMODE

By default (when dived has no -n/--signals/--signals-pgid option) dive gets the pid of executed process and forwards most signals to it. When DIVE_SIGFWMODE is set to 0, signal processing on dive side is disabled. When set to 2, it negates the pid to before sending the signal to make it get to the entire process group. In any case additional information like SIGCHLD’s pid or SIGIO’s fd is not forwarded. When set to 2, but there is --signals or --signals-pgid option on dived side, dive just sends signal number to dived, which processes it further.

EXIT STATUS

By default the exit status should be the same as remote program’s exit status.

	0		Successfull operation.
	1		Can’t create socket or if remote program exited with 1.
	2		Can’t connect socket or if remote program exited with 2.
	3		Incompatible dive and dived versions or if remote program exited with 3.
	127		Server dropped connection, specified command not found or the remote program exited with 127.

EXAMPLES

dive /var/run/dive.socket /bin/bash -i

Open remote shell.

HOME=/home/user USER=user dive /var/run/user.dive /bin/bash -i

Open remote shell expecting that we will get user ´s shell.

DIVE_TERMINAL= DIVE_WAITMODE=1 dive @userdive xterm

Start xterm remotely in background (using abstract socket address "@userdive" to send the request)

dive /var/run/pinger.dive -c 1 8.8.8.8

Supply arguments for remote ping.

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

CAVEATS

Obviously the parent process of the remotely started program will not be the same as if we started the program directly.

Another issue is a controlling terminal. Either dived "steals" controlling terminal from your current shell in favour of the new one (default if dived started as root) or the new (remotely started) shell does not control the terminal ("bash: no job control in this shell").

Dealing with "stolen" controlling terminal. This way everything appears to be fine unless we exit from the remotely started shell. We find that now we can’t use Ctrl+C (because of we have taken away controlling terminal from your bash and gave it to remotely started bash that is now gone). You can restore normal shell behaviour by 1. Just "exec bash", 2. Closing this virtual terminal and forgetting about the issue (or using "exec dive ..." to avoid triggering it), 3. Not letting away our terminal (using DIVE_TERMINAL) and using methods from the next paragraph. 4. Create temporary virtual terminal and let it be used for dive:
reptyr -L dive /var/run/user.dive /bin/bash -i

Dealing with "missing" controlling terminal. This happens when remote dived is not privileged enough or not configured to manage controlling terminals around. Easiest way have convenient shell access with job control is to use fresh new pty instead of reusing current terminal. This can be obtained by wrapping you program with reptry or socat.
dive /var/run/user.dive reptyr -Lbash -i

Open remote shell wrapped in reptyr(1) version not less than 0.4.

dive /var/run/user.dive socat -,raw,echo=0 exec:bash,pty,setsid,stderr

Use socat for the same purpose (I have issues with terminal width this way).

AUTHOR

Vitaly "_Vi" Shukela

AVAILABILITY

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

---