1.\" $NetBSD: rumpclient.3,v 1.3 2013/03/08 08:30:44 wiz 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 February 16, 2011 27.Dt RUMPCLIENT 3 28.Os 29.Sh NAME 30.Nm rumpclient 31.Nd rump client library 32.Sh LIBRARY 33.Lb rumpclient 34.Sh SYNOPSIS 35.In rump/rumpclient.h 36.In rump/rump_syscalls.h 37.Ft int 38.Fn rumpclient_init 39.Ft pid_t 40.Fn rumpclient_fork 41.Ft pid_t 42.Fn rumpclient_vfork 43.Ft struct rumpclient_fork * 44.Fn rumpclient_prefork 45.Ft int 46.Fn rumpclient_fork_init "struct rumpclient_fork *rfp" 47.Ft void 48.Fn rumpclient_fork_cancel "struct rumpclient_fork *rfp" 49.Ft int 50.Fn rumpclient_exec "const char *path" "char *const argv[]" "char *const envp[]" 51.Ft int 52.Fn rumpclient_daemon "int nochdir" "int noclose" 53.Ft void 54.Fn rumpclient_setconnretry "time_t retrytime" 55.Ft int 56.Fo rumpclient_syscall 57.Fa "int num" "const void *sysarg" "size_t argsize" "register_t *retval" 58.Fc 59.Sh DESCRIPTION 60.Nm 61is the clientside implementation of the 62.Xr rump_sp 7 63facility. 64It can be used to connect to a rump kernel server and make system call 65style requests. 66.Pp 67Every connection to a rump kernel server creates a new process 68context in the rump kernel. 69By default a process is inherited from init, but through existing 70connections and the forking facility offered by 71.Nm 72it is possible to form process trees. 73.Bl -tag -width xxxx 74.It Fn rumpclient_init 75Initialize 76.Nm . 77The server address is determined from the environment variable 78.Ev RUMP_SERVER 79according to syntax described in 80.Xr rump_sp 7 . 81The new process is registered to the rump kernel with the command 82name from 83.Xr getprogname 3 . 84.It Fn rumpclient_fork 85Fork a rump client process. 86This also causes a host process fork via 87.Xr fork 2 . 88The child will have a copy of the parent's rump kernel file descriptors. 89.It Fn rumpclient_vfork 90Like above, but the host uses 91.Xr vfork 2 . 92.It Fn rumpclient_prefork 93Low-level routine which instructs the rump kernel that the current 94process is planning to fork. 95The routine returns a 96.Pf non- Dv NULL 97cookie if successful. 98.It Fn rumpclient_fork_init rfp 99Low-level routine which works like 100.Fn rumpclient_init , 101with the exception that it uses the 102.Ar rfp 103context created by a call to 104.Fn rumpclient_prefork . 105This is typically called from the child of a 106.Xr fork 2 107call. 108.It Fn rumpclient_fork_cancel rfp 109Cancel previously initiated prefork context. 110This is useful for error handling in case a full fork could not 111be carried through. 112.It Fn rumpclient_exec path argv envp 113This call is a 114.Nm 115wrapper around 116.Xr execve 2 . 117The wrapper makes sure that the rump kernel process context stays 118the same in the newly executed program. 119This means that the rump kernel PID remains the same and the same 120rump file descriptors are available (apart from ones which 121were marked with 122.Dv FD_CLOEXEC ) . 123.Pp 124It should be noted that the newly executed program must call 125.Fn rumpclient_init 126before any other rump kernel communication can take place. 127The wrapper cannot do it because it no longer has program control. 128However, since all rump clients call the init routine, 129this should not be a problem. 130.It Fn rumpclient_daemon noclose nochdir 131This function performs the equivalent of 132.Xr daemon 3 , 133but also ensures that the internal call to 134.Xr fork 2 135is handled properly. 136This routine is provided for convenience. 137.It Fn rumpclient_setconnretry retrytime 138Set the timeout for how long the client attempts to reconnect to 139the server in case of a broken connection. 140After the timeout expires the client will return a failure 141for that particular request. 142It is critical to note that after a restablished connection the 143rump kernel context will be that of a newly connected client. 144This means all previous kernel state such as file descriptors 145will be lost. 146It is largely up to a particular application if this has impact 147or not. 148For example, web browsers tend to recover fairly smoothly from a 149kernel server reconnect, while 150.Xr sshd 8 151gets confused if its sockets go missing. 152.Pp 153If 154.Ar retrytime 155is a positive integer, it means the number of seconds for which 156reconnection will be attempted. 157The value 0 means that reconnection will not be attempted, and all 158subsequent operations will return the errno 159.Er ENOTCONN . 160.Pp 161Additionally, the following special values are accepted: 162.Bl -tag -width xxxx 163.It Dv RUMPCLIENT_RETRYCONN_INFTIME 164Attempt reconnection indefinitely. 165.It Dv RUMPCLIENT_RETRYCONN_ONCE 166Attempt reconnect exactly once. 167What this precisely means depends on the situation: e.g. getting 168.Er EHOSTUNREACH 169immediately or the TCP connection request timeouting are considered 170to be one retry. 171.It Dv RUMPCLIENT_RETRYCONN_DIE 172In case of a broken connection is detected at runtime, call 173.Xr exit 3 . 174This is useful for example in testing. 175It ensures that clients are killed immediately when they attempt 176to communicate with a halted server. 177.El 178.It Fn rumpclient_syscall num sysarg argsize retval 179Execute an "indirect" system call. 180In the normal case system calls are executed through the interfaces in 181.In rump/rump_syscalls.h 182(for example 183.Fn rump_sys_read fd buf nbytes ) . 184This interface allows calling the server with pre-marshalled arguments. 185.El 186.Pp 187Additionally, all of the supported rump system calls are available 188through this library. 189See 190.In rump/rump_syscalls.h 191for a list. 192.Sh RETURN VALUES 193.Nm 194routines return \-1 in case of error and set errno. 195In case of success a non-negative integer is returned, where applicable. 196.Sh SEE ALSO 197.Xr rump_server 1 , 198.Xr rump 3 , 199.Xr rump_sp 7 200.Sh CAVEATS 201Interfaces for a cryptographically authenticated client-server 202handshake do not currently exist. 203This can be worked around with e.g. host access control and an ssh 204tunnel. 205