NAME

rumphijack — System call hijack library

LIBRARY

used by ld.so(1)

DESCRIPTION

The ld.so(1) runtime linker can be instructed to load rumphijack between the main object and other libraries. This enables rumphijack to capture and redirect system call requests to a rump kernel instead of the host kernel.

The behaviour of hijacked applications is affected by the following environment variables:

RUMPHIJACK

If present, this variable specifies which system calls should be hijacked. The string is parsed as a comma-separated list of “name=value” tuples. The possible lefthandside names are:

“path”

Pathname-based system calls are hijacked if the path the system call is directed to resides under value. In case of an absolute pathname argument, a literal prefix comparison is made. In case of a relative pathname, the current working direct is examined. This also implies that neither “..” nor symbolic links will cause the namespace to be switched.

“blanket”

A colon-separated list of rump path prefixes. This acts almost like “path” with the difference that the prefix does not get removed when passing the path to the rump kernel. For example, if “path” is /rump, accessing /rump/dev/bpf will cause /dev/bpf to be accessed in the rump kernel. In contrast, if “blanket” contains /dev/bpf, accessing /dev/bpf will cause an access to /dev/bpf in the rump kernel.

In case the current working directory is changed to a blanketed directory, the current working directory will still be reported with the rump prefix, if available. Note, though, that some shells cache the directory and may report something else. In case no rump path prefix has been configured, the raw rump directory is reported.

It is recommended to supply blanketed pathnames as specific as possible, i.e. use /dev/bpf instead of /dev unless necessary to do otherwise. Also, note that the blanket prefix does not follow directory borders. In other words, setting the blanket for /dev/bpf means it is set for all pathnames with the given prefix, not just ones in /dev.

“socket”

The specifier value contains a colon-separated list of which protocol families should be hijacked. The special value “all” can be specified as the first element. It indicates that all protocol families should be hijacked. Some can then be disabled by prepending “no” to the name of the protocol family.

For example, “inet:inet6” specifies that only PF_INET and PF_INET6 sockets should be hijacked, while “all:noinet” specifies that all protocol families except PF_INET should be hijacked.

“vfs”

The specifier value contains a colon-separated list of which vfs-related system calls should be hijacked. These differ from the pathname-based file system syscalls in that there is no pathname to make the selection based on. Current possible values are “nfssvc”, “getvfsstat”, and “fhcalls”. They indicate hijacking nfssvc(), getvfsstat(), and all file handle calls, respectively. The file handle calls include fhopen(), fhstat(), and fhstatvfs1().

It is also possible to use “all” and “no” in the same fashion as with the socket hijack specifier.

“sysctl”

Direct the __sysctl() backend of the sysctl(3) facility to the rump kernel. Acceptable values are “yes” and “no”, meaning to call the rump or the host kernel, respectively.

“fdoff”

Adjust the library's fd offset to the specified value. All rump kernel descriptors have the offset added to them before they are returned to the application. This should be changed only if the application defines a low non-default FD_SETSIZE for select() or if it opens a very large number of file descriptors. The default value is 128.

If the environment variable is unset, the default value “path=/rump,socket=all:nolocal” is used. The rationale for this is to have networked X clients work out-of-the-box: X clients use local sockets to communicate with the server, so local sockets must be used as a host service.

An empty string as a value means no calls are hijacked.

RUMPHIJACK_RETRYCONNECT

Change how rumpclient(3) attempts to reconnect to the server in case the connection is lost. Acceptable values are:

“inftime”

retry indefinitely

“once”

retry once, when that connection fails, give up

“die”

call exit(3) if connection failure is detected

n

Attempt reconnect for n seconds. The value 0 means reconnection is not attempted. The value n must be a positive integer.

See rumpclient(3) for more discussion.

EXAMPLES

Use an alternate TCP/IP stack for firefox with a persistent server connection:

$ setenv RUMP_SERVER unix:///tmp/tcpip 
$ setenv LD_PRELOAD /usr/lib/librumphijack.so 
$ setenv RUMPHIJACK_RETRYCONNECT inftime 
$ firefox

SEE ALSO

ld.so(1), rump_server(1), rump(3), rumpclient(3), rump_sp(7)