RUMPCLIENT(3)

RUMPCLIENT(3) | Library Functions Manual | RUMPCLIENT(3)

# 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.

February 16, 2011 | NetBSD 9.3