244 lines
6.6 KiB
Groff
244 lines
6.6 KiB
Groff
.\" $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
|