NetBSD/lib/librumphijack/rumphijack.3

.\"     $NetBSD: rumphijack.3,v 1.13 2018/12/16 14:03:37 hannken Exp $
.\"
.\" Copyright (c) 2011 Antti Kantee.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd December 16, 2018
.Dt RUMPHIJACK 3
.Os
.Sh NAME
.Nm rumphijack
.Nd System call hijack library
.Sh LIBRARY
used by
.Xr ld.so 1
.Sh DESCRIPTION
The
.Xr ld.so 1
runtime linker can be instructed to load
.Nm
between the main object and other libraries.
This enables
.Nm
to capture and redirect system call requests to a rump kernel instead
of the host kernel.
.Pp
The behaviour of hijacked applications is affected by the following
environment variables:
.Bl -tag -width 12345
.It Ev RUMPHIJACK
If present, this variable specifies which system calls should be
hijacked.
The string is parsed as a comma-separated list of
.Dq name=value
tuples.
The possible lefthandside names are:
.Bl -tag -width xxblanketxx
.It Dq path
Pathname-based system calls are hijacked if the path the system
call is directed to resides under
.Ar 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
.Dq ..
nor symbolic links will cause the namespace to be switched.
.It Dq blanket
A colon-separated list of rump path prefixes.
This acts almost like
.Dq path
with the difference that the prefix does not get removed when
passing the path to the rump kernel.
For example, if
.Dq path
is
.Pa /rump ,
accessing
.Pa /rump/dev/bpf
will cause
.Pa /dev/bpf
to be accessed in the rump kernel.
In contrast, if
.Dq blanket
contains
.Pa /dev/bpf ,
accessing
.Pa /dev/bpf
will cause an access to
.Pa /dev/bpf
in the rump kernel.
.Pp
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.
.Pp
It is recommended to supply blanketed pathnames as specific as
possible, i.e. use
.Pa /dev/bpf
instead of
.Pa /dev
unless necessary to do otherwise.
Also, note that the blanket prefix does not follow directory borders.
In other words, setting the blanket for
.Pa /dev/bpf
means it is set for
.Em all
pathnames with the given prefix, not just ones in
.Pa /dev .
.It Dq socket
The specifier
.Ar value
contains a colon-separated list of which protocol families should
be hijacked.
The special value
.Dq all
can be specified as the first element.
It indicates that all protocol families should be hijacked.
Some can then be disabled by prepending
.Dq no
to the name of the protocol family.
.Pp
For example,
.Dq inet:inet6
specifies that only
.Dv PF_INET
and
.Dv PF_INET6
sockets should be hijacked,
while
.Dq all:noinet
specifies that all protocol families except
.Dv PF_INET
should be hijacked.
.It Dq vfs
The specifier
.Ar 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
.Dq nfssvc ,
.Dq getvfsstat ,
and
.Dq fhcalls .
They indicate hijacking
.Fn nfssvc ,
.Fn getvfsstat ,
and all file handle calls, respectively.
The file handle calls include
.Fn fhopen ,
.Fn fhstat ,
and
.Fn fhstatvfs1 .
.Pp
It is also possible to use
.Dq all
and
.Dq no
in the same fashion as with the socket hijack specifier.
.It Dq sysctl
Direct the
.Fn __sysctl
backend of the
.Xr sysctl 3
facility to the rump kernel.
Acceptable values are
.Dq yes
and
.Dq no ,
meaning to call the rump or the host kernel, respectively.
.It Dq modctl
Direct the
.Fn modctl
call to the rump kernel.
Acceptable values are
.Dq yes
and
.Dq no ,
meaning to call the rump or the host kernel, respectively.
.It Dq 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
.Dv FD_SETSIZE
for
.Fn select
or if it opens a very large number of file descriptors.
The default value is 128.
.El
.Pp
If the environment variable is unset, the default value
.Qq 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.
.Pp
An empty string as a value means no calls are hijacked.
.It Ev RUMPHIJACK_RETRYCONNECT
Change how
.Xr rumpclient 3
attempts to reconnect to the server in case the connection is lost.
Acceptable values are:
.Bl -tag -width xxinftimexx
.It Dq inftime
retry indefinitely
.It Dq once
retry once, when that connection fails, give up
.It Dq die
call
.Xr exit 3
if connection failure is detected
.It n
Attempt reconnect for n seconds.
The value 0 means reconnection is not attempted.
The value n must be a positive integer.
.El
.Pp
See
.Xr rumpclient 3
for more discussion.
.El
.Sh EXAMPLES
Use an alternate TCP/IP stack for firefox with a persistent server
connection:
.Bd -literal -offset indent
$ setenv RUMP_SERVER unix:///tmp/tcpip
$ setenv LD_PRELOAD /usr/lib/librumphijack.so
$ setenv RUMPHIJACK_RETRYCONNECT inftime
$ firefox
.Ed
.Sh SEE ALSO
.Xr ld.so 1 ,
.Xr rump_server 1 ,
.Xr rump 3 ,
.Xr rumpclient 3 ,
.Xr rump_sp 7