1.\" $NetBSD: rumphijack.3,v 1.13 2018/12/16 14:03:37 hannken 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 December 16, 2018 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 modctl 177Direct the 178.Fn modctl 179call to the rump kernel. 180Acceptable values are 181.Dq yes 182and 183.Dq no , 184meaning to call the rump or the host kernel, respectively. 185.It Dq fdoff 186Adjust the library's fd offset to the specified value. 187All rump kernel descriptors have the offset added to them 188before they are returned to the application. 189This should be changed only if the application defines a low non-default 190.Dv FD_SETSIZE 191for 192.Fn select 193or if it opens a very large number of file descriptors. 194The default value is 128. 195.El 196.Pp 197If the environment variable is unset, the default value 198.Qq path=/rump,socket=all:nolocal 199is used. 200The rationale for this is to have networked X clients work 201out-of-the-box: X clients use local sockets to communicate with 202the server, so local sockets must be used as a host service. 203.Pp 204An empty string as a value means no calls are hijacked. 205.It Ev RUMPHIJACK_RETRYCONNECT 206Change how 207.Xr rumpclient 3 208attempts to reconnect to the server in case the connection is lost. 209Acceptable values are: 210.Bl -tag -width xxinftimexx 211.It Dq inftime 212retry indefinitely 213.It Dq once 214retry once, when that connection fails, give up 215.It Dq die 216call 217.Xr exit 3 218if connection failure is detected 219.It n 220Attempt reconnect for n seconds. 221The value 0 means reconnection is not attempted. 222The value n must be a positive integer. 223.El 224.Pp 225See 226.Xr rumpclient 3 227for more discussion. 228.El 229.Sh EXAMPLES 230Use an alternate TCP/IP stack for firefox with a persistent server 231connection: 232.Bd -literal -offset indent 233$ setenv RUMP_SERVER unix:///tmp/tcpip 234$ setenv LD_PRELOAD /usr/lib/librumphijack.so 235$ setenv RUMPHIJACK_RETRYCONNECT inftime 236$ firefox 237.Ed 238.Sh SEE ALSO 239.Xr ld.so 1 , 240.Xr rump_server 1 , 241.Xr rump 3 , 242.Xr rumpclient 3 , 243.Xr rump_sp 7 244