1.\" $NetBSD: rumphijack.3,v 1.12 2011/03/14 15:21:22 pooka Exp $ 2.\" 3.\" Copyright (c) 2011 Antti Kantee. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd March 14, 2011 27.Dt RUMPHIJACK 3 28.Os 29.Sh NAME 30.Nm rumphijack 31.Nd System call hijack library 32.Sh LIBRARY 33used by 34.Xr ld.so 1 35.Sh DESCRIPTION 36The 37.Xr ld.so 1 38runtime linker can be instructed to load 39.Nm 40between the main object and other libraries. 41This enables 42.Nm 43to capture and redirect system call requests to a rump kernel instead 44of the host kernel. 45.Pp 46The behaviour of hijacked applications is affected by the following 47environment variables: 48.Bl -tag -width 12345 49.It Ev RUMPHIJACK 50If present, this variable specifies which system calls should be 51hijacked. 52The string is parsed as a comma-separated list of 53.Dq name=value 54tuples. 55The possible lefthandside names are: 56.Bl -tag -width xxblanketxx 57.It Dq path 58Pathname-based system calls are hijacked if the path the system 59call is directed to resides under 60.Ar value . 61In case of an absolute pathname argument, a literal prefix comparison is made. 62In case of a relative pathname, the current working direct is 63examined. 64This also implies that neither 65.Dq .. 66nor symbolic links will cause the namespace to be switched. 67.It Dq blanket 68A colon-separated list of rump path prefixes. 69This acts almost like 70.Dq path 71with the difference that the prefix does not get removed when 72passing the path to the rump kernel. 73For example, if 74.Dq path 75is 76.Pa /rump , 77accessing 78.Pa /rump/dev/bpf 79will cause 80.Pa /dev/bpf 81to be accessed in the rump kernel. 82In contrast, if 83.Dq blanket 84contains 85.Pa /dev/bpf , 86accessing 87.Pa /dev/bpf 88will cause an access to 89.Pa /dev/bpf 90in the rump kernel. 91.Pp 92In case the current working directory is changed to a blanketed 93directory, the current working directory will still be reported 94with the rump prefix, if available. 95Note, though, that some shells cache the directory and may report 96something else. 97In case no rump path prefix has been configured, the raw rump 98directory is reported. 99.Pp 100It is recommended to supply blanketed pathnames as specific as 101possible, i.e. use 102.Pa /dev/bpf 103instead of 104.Pa /dev 105unless necessary to do otherwise. 106Also, note that the blanket prefix does not follow directory borders. 107In other words, setting the blanket for 108.Pa /dev/bpf 109means it is set for 110.Em all 111pathnames with the given prefix, not just ones in 112.Pa /dev . 113.It Dq socket 114The specifier 115.Ar value 116contains a colon-separated list of which protocol families should 117be hijacked. 118The special value 119.Dq all 120can be specified as the first element. 121It indicates that all protocol families should be hijacked. 122Some can then be disabled by prepending 123.Dq no 124to the name of the protocol family. 125.Pp 126For example, 127.Dq inet:inet6 128specifies that only 129.Dv PF_INET 130and 131.Dv PF_INET6 132sockets should be hijacked, 133while 134.Dq all:noinet 135specifies that all protocol families except 136.Dv PF_INET 137should be hijacked. 138.It Dq vfs 139The specifier 140.Ar value 141contains a colon-separated list of which vfs-related system calls 142should be hijacked. 143These differ from the pathname-based file system syscalls in that 144there is no pathname to make the selection based on. 145Current possible values are 146.Dq nfssvc , 147.Dq getvfsstat , 148and 149.Dq fhcalls . 150They indicate hijacking 151.Fn nfssvc , 152.Fn getvfsstat , 153and all file handle calls, respectively. 154The file handle calls include 155.Fn fhopen , 156.Fn fhstat , 157and 158.Fn fhstatvfs1 . 159.Pp 160It is also possible to use 161.Dq all 162and 163.Dq no 164in the same fashion as with the socket hijack specifier. 165.It Dq sysctl 166Direct the 167.Fn __sysctl 168backend of the 169.Xr sysctl 3 170facility to the rump kernel. 171Acceptable values are 172.Dq yes 173and 174.Dq no , 175meaning to call the rump or the host kernel, respectively. 176.It Dq fdoff 177Adjust the library's fd offset to the specified value. 178All rump kernel descriptors have the offset added to them 179before they are returned to the application. 180This should be changed only if the application defines a low non-default 181.Dv FD_SETSIZE 182for 183.Fn select 184or if it opens a very large number of file descriptors. 185The default value is 128. 186.El 187.Pp 188If the environment variable is unset, the default value 189.Qq path=/rump,socket=all:nolocal 190is used. 191The rationale for this is to have networked X clients work 192out-of-the-box: X clients use local sockets to communicate with 193the server, so local sockets must be used as a host service. 194.Pp 195An empty string as a value means no calls are hijacked. 196.It Ev RUMPHIJACK_RETRYCONNECT 197Change how 198.Xr rumpclient 3 199attempts to reconnect to the server in case the connection is lost. 200Acceptable values are: 201.Bl -tag -width xxinftimexx 202.It Dq inftime 203retry indefinitely 204.It Dq once 205retry once, when that connection fails, give up 206.It Dq die 207call 208.Xr exit 3 209if connection failure is detected 210.It n 211Attempt reconnect for n seconds. 212The value 0 means reconnection is not attempted. 213The value n must be a positive integer. 214.El 215.Pp 216See 217.Xr rumpclient 3 218for more discussion. 219.El 220.Sh EXAMPLES 221Use an alternate TCP/IP stack for firefox with a persistent server 222connection: 223.Bd -literal -offset indent 224$ setenv RUMP_SERVER unix:///tmp/tcpip 225$ setenv LD_PRELOAD /usr/lib/librumphijack.so 226$ setenv RUMPHIJACK_RETRYCONNECT inftime 227$ firefox 228.Ed 229.Sh SEE ALSO 230.Xr ld.so 1 , 231.Xr rump_server 1 , 232.Xr rump 3 , 233.Xr rumpclient 3 , 234.Xr rump_sp 7 235