1.\" $NetBSD: rump_sp.7,v 1.2 2017/06/04 08:53:38 abhinav Exp $ 2.\" 3.\" Copyright (c) 2010 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 7, 2011 27.Dt RUMP_SP 7 28.Os 29.Sh NAME 30.Nm rump_sp 31.Nd rump remote system call support 32.Sh DESCRIPTION 33The 34.Nm 35facility allows clients to attach to a rump kernel server over a 36socket and perform system calls. 37While making a local rump system call is faster than calling the 38host kernel, a remote system call over a socket is slower. 39This facility is therefore meant mostly for operations which are 40not performance critical, such as configuration of a rump kernel 41server. 42.Ss Clients 43The 44.Nx 45base system comes with multiple preinstalled clients which can be 46used to configure a rump kernel and request diagnostic information. 47These clients run as hybrids partially in the host system and 48partially against the rump kernel. 49For example, network-related clients will typically avoid making 50any file system related system calls against the rump kernel, since 51it is not guaranteed that a rump network server has file system 52support. 53Another example is DNS: since a rump server very rarely has a DNS 54service configured, host networking is used to do DNS lookups. 55.Pp 56Some examples of clients include 57.Nm rump.ifconfig 58which configures interfaces, 59.Nm rump.sysctl 60which is used to access the 61.Xr sysctl 7 62namespace 63and 64.Nm rump.traceroute 65which is used to display a network trace starting from the rump kernel. 66.Pp 67Also, almost any unmodified dynamically linked application 68(for example 69.Xr telnet 1 70or 71.Xr ls 1 ) 72can be used as a rump kernel client with the help of system call hijacking. 73See 74.Xr rumphijack 3 75for more information. 76.Ss Connecting to the server 77A remote rump server is specified using an URL. 78Currently two types of URLs are supported: TCP and local domain sockets. 79The TCP URL is of the format tcp://ip.address:port/ and the local 80domain URL is unix://path. 81The latter can accept relative or absolute paths. 82Note that absolute paths require three leading slashes. 83.Pp 84To preserve the standard usage of the rump clients' counterparts 85the environment variable 86.Ev RUMP_SERVER 87is used to specify the server URL. 88To keep track of which rump kernel the current shell is using, 89modifying the shell prompt is recommended -- this is analogous 90to the visual clue you have when you login from one machine to 91another. 92.Ss Client credentials and access control 93The current scheme gives all connecting clients root credentials. 94It is recommended to take precautions which prevent unauthorized 95access. 96For a unix domain socket it is enough to prevent access to the 97socket using file system permissions. 98For TCP/IP sockets the only available means is to prevent network 99access to the socket with the use of firewalls. 100More fine-grained access control based on cryptographic credentials 101may be implemented at a future date. 102.Sh EXAMPLES 103Get a list of file systems supported by a rump kernel server 104(in case that particular server does not support file systems, 105an error will be returned): 106.Bd -literal -offset indent 107$ env RUMP_SERVER=unix://sock rump.sysctl vfs.generic.fstypes 108.Ed 109.Sh SEE ALSO 110.Xr rump_server 1 , 111.Xr rump 3 , 112.Xr rumpclient 3 , 113.Xr rumphijack 3 114.Sh HISTORY 115.Nm 116first appeared in 117.Nx 6.0 . 118