NAME
rumpclient —
rump client library
LIBRARY
library “rumpclient”
SYNOPSIS
#include <rump/rumpclient.h>
#include <rump/rump_syscalls.h>
int
rumpclient_init();
pid_t
rumpclient_fork();
pid_t
rumpclient_vfork();
struct rumpclient_fork *
rumpclient_prefork();
int
rumpclient_fork_init(
struct
rumpclient_fork *rfp);
void
rumpclient_fork_cancel(
struct
rumpclient_fork *rfp);
int
rumpclient_exec(
const
char *path,
char *const
argv[],
char *const
envp[]);
int
rumpclient_daemon(
int
nochdir,
int
noclose);
void
rumpclient_setconnretry(
time_t
retrytime);
int
rumpclient_syscall(
int num,
const void *sysarg,
size_t
argsize,
register_t *retval);
DESCRIPTION
rumpclient is the clientside implementation of the
rump_sp(7) facility. It can be
used to connect to a rump kernel server and make system call style requests.
Every connection to a rump kernel server creates a new process context in the
rump kernel. By default a process is inherited from init, but through existing
connections and the forking facility offered by
rumpclient
it is possible to form process trees.
-
-
- rumpclient_init()
- Initialize rumpclient. The server address
is determined from the environment variable
RUMP_SERVER
according to syntax described in
rump_sp(7). The new process
is registered to the rump kernel with the command name from
getprogname(3).
-
-
- rumpclient_fork()
- Fork a rump client process. This also causes a host process
fork via fork(2). The child
will have a copy of the parent's rump kernel file descriptors.
-
-
- rumpclient_vfork()
- Like above, but the host uses
vfork(2).
-
-
- rumpclient_prefork()
- Low-level routine which instructs the rump kernel that the
current process is planning to fork. The routine returns a
non-
NULL
cookie if successful.
-
-
- rumpclient_fork_init(rfp)
- Low-level routine which works like
rumpclient_init(), with the exception that it uses the
rfp context created by a call to
rumpclient_prefork(). This is typically called from the
child of a fork(2) call.
-
-
- rumpclient_fork_cancel(rfp)
- Cancel previously initiated prefork context. This is useful
for error handling in case a full fork could not be carried through.
-
-
- rumpclient_exec(path,
argv, envp)
- This call is a rumpclient wrapper around
execve(2). The wrapper makes
sure that the rump kernel process context stays the same in the newly
executed program. This means that the rump kernel PID remains the same and
the same rump file descriptors are available (apart from ones which were
marked with
FD_CLOEXEC
).
It should be noted that the newly executed program must call
rumpclient_init() before any other rump kernel
communication can take place. The wrapper cannot do it because it no
longer has program control. However, since all rump clients call the init
routine, this should not be a problem.
-
-
- rumpclient_daemon(noclose,
nochdir)
- This function performs the equivalent of
daemon(3), but also ensures
that the internal call to
fork(2) is handled properly.
This routine is provided for convenience.
-
-
- rumpclient_setconnretry(retrytime)
- Set the timeout for how long the client attempts to
reconnect to the server in case of a broken connection. After the timeout
expires the client will return a failure for that particular request. It
is critical to note that after a restablished connection the rump kernel
context will be that of a newly connected client. This means all previous
kernel state such as file descriptors will be lost. It is largely up to a
particular application if this has impact or not. For example, web
browsers tend to recover fairly smoothly from a kernel server reconnect,
while sshd(8) gets confused if
its sockets go missing.
If retrytime is a positive integer, it means the
number of seconds for which reconnection will be attempted. The value 0
means that reconnection will not be attempted, and all subsequent
operations will return the errno
ENOTCONN
.
Additionally, the following special values are accepted:
-
-
RUMPCLIENT_RETRYCONN_INFTIME
- Attempt reconnection indefinitely.
-
-
RUMPCLIENT_RETRYCONN_ONCE
- Attempt reconnect exactly once. What this precisely
means depends on the situation: e.g. getting
EHOSTUNREACH
immediately or the TCP connection
request timeouting are considered to be one retry.
-
-
RUMPCLIENT_RETRYCONN_DIE
- In case of a broken connection is detected at runtime,
call exit(3). This is
useful for example in testing. It ensures that clients are killed
immediately when they attempt to communicate with a halted
server.
-
-
- rumpclient_syscall(num,
sysarg, argsize,
retval)
- Execute an "indirect" system call. In the normal
case system calls are executed through the interfaces in
<rump/rump_syscalls.h> (for
example rump_sys_read(fd,
buf, nbytes)). This interface
allows calling the server with pre-marshalled arguments.
Additionally, all of the supported rump system calls are available through this
library. See
<rump/rump_syscalls.h>
for a list.
RETURN VALUES
rumpclient routines return -1 in case of error and set errno.
In case of success a non-negative integer is returned, where applicable.
SEE ALSO
rump_server(1),
rump(3),
rump_sp(7)
CAVEATS
Interfaces for a cryptographically authenticated client-server handshake do not
currently exist. This can be worked around with e.g. host access control and
an ssh tunnel.