1.\" $NetBSD: rump_allserver.1,v 1.19 2011/03/04 09:13:23 pooka 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 21, 2011 27.Dt RUMP_SERVER 1 28.Os 29.Sh NAME 30.Nm rump_server , 31.Nm rump_allserver 32.Nd rump kernel server 33.Sh SYNOPSIS 34.Nm 35.Op Fl s 36.Op Fl c Ar ncpu 37.Op Fl d Ar drivespec 38.Op Fl l Ar library 39.Op Fl m Ar module 40.Ar url 41.Sh DESCRIPTION 42The 43.Nm 44utility is used to provide a rump kernel service. 45Clients can use the system calls provided by 46.Nm 47via 48.Ar url . 49.Pp 50The difference between 51.Nm 52and 53.Nm rump_allserver 54is that 55.Nm 56offers only a minimalistic set of features, 57while 58.Nm rump_allserver 59provides all rump kernel components which were available when the 60system was built. 61At execution time it is possible to load components from the command 62line as described in the options section. 63.Bl -tag -width indent 64.It Fl c Ar ncpu 65Configure 66.Ar ncpu 67virtual CPUs on SMP-capable archs. 68By default, the number of CPUs equals the number of CPUs on the 69host. 70.It Fl d Ar drivespec 71The argument 72.Ar drivespec 73maps a host file in the rump fs namespace. 74The string 75.Ar drivespec 76must be of comma-separated 77.Dq name=value 78format and must contain the following tokens: 79.Bl -tag -width hostpath1234 80.It Ar key 81Block device path in rump namespace. 82This must be specified according to the rules for a key in 83.Xr rump_etfs 3 . 84.It Ar hostpath 85Host file used for storage. 86If the file does not exist, it will be created. 87.It Ar size 88Size of the mapping. 89Similar to 90.Xr dd 1 , 91this argument accepts a suffix as the multiplier for the number. 92The special value 93.Dq host 94indicates that the current size of 95.Ar hostpath 96will be used. 97In this case it is assumed that 98.Ar hostpath 99exists and is a regular file. 100.It OR 101.It Ar disklabel 102Use a disklabel partition identifier to specify the offset and size 103of the mapping. 104.Ar hostpath 105must contain an existing and valid disklabel within the first 64k. 106.El 107.Pp 108The following are optional: 109.Bl -tag -width hostpath1234 110.It Ar offset 111Offset of the mapping. 112The window into 113.Ar hostpath 114therefore is 115.Fa [ offset , offset+size ] . 116In case this parameter is not given, the default value 0 is used. 117.It Ar type 118The type of file that 119.Ar key 120is exposed as within the rump kernel. 121The possibilities are 122.Dq blk , 123.Dq chr , 124and 125.Dq reg 126for block device, character device and regular file, respectively. 127The default is a block device. 128.Pp 129Note: the contents of block devices are cached in the rump kernel's 130buffer cache. 131To avoid cache incoherency, it is advisable not to access a file 132through the host namespace while it is mapped as a block device in 133a rump kernel. 134.El 135.Pp 136In case 137.Ar hostpath 138does not exist, it will be created as a regular file with mode 1390644 (plus any restrictions placed by umask). 140In case 141.Ar hostpath 142is a regular file and is not large enough to accommodate the 143specified size, it will be extended to the specified size. 144.It Fl l Ar library 145Call 146.Fn dlopen 147on library before initializing the rump kernel. 148In case 149.Ar library 150provides a kernel module, it will appear as a builtin module in the 151rump kernel. 152Any rump component present in 153.Ar library 154will also be initialized. 155.Pp 156The argument 157.Ar library 158can contain a full path or a filename, in which case the standard 159dynamic library search path will be used. 160Libraries are loaded in the order they are given. 161Dependencies are not autoloaded, and the order must be specified 162correctly. 163.It Fl m Ar module 164Load and link a kernel module after the rump kernel is initialized. 165For this to work, the rump kernel must include the vfs faction, 166since the module is loaded using kernel vfs code (see 167.Sx EXAMPLES ) . 168.It Fl r Ar total_ram 169Sets the limit of kernel memory allocatable by the server to 170.Ar total_ram 171as opposed to the default which allows the server to allocate as much 172memory as the host will give it. 173This parameter is especially useful for VFS servers, since by 174default the virtual file system will attempt to consume as much 175memory as it can, and accessing large files can cause an excessive 176amount of memory to be used as file system cache. 177.It Fl s 178Do not detach from the terminal. 179By default, 180.Nm 181detaches from the terminal once the service is running on 182.Ar url . 183.It Fl v 184Set bootverbose. 185.El 186.Pp 187After use, 188.Nm 189can be made to exit using 190.Xr rump.halt 1 . 191.Sh EXAMPLES 192Start a server and load the tmpfs file system module, and halt the 193server immediately afterwards: 194.Bd -literal -offset indent 195$ rump_server -lrumpvfs -m /modules/tmpfs.kmod unix://sock 196$ env RUMP_SERVER=unix://sock rump.halt 197.Ed 198.Pp 199Start a server with the one gigabyte host file 200.Pa dk.img 201mapped as the block device 202.Pa /dev/dk 203in the rump kernel. 204.Bd -literal -offset indent 205$ rump_allserver -d key=/dev/dk,hostpath=dk.img,size=1g unix://sock 206.Ed 207.Pp 208Start a server which listens on INADDR_ANY port 3755 209.Bd -literal -offset indent 210$ rump_server tcp://0:3755/ 211.Ed 212.Pp 213Start a FFS server with a 16MB kernel memory limit. 214.Bd -literal -offset indent 215$ rump_server -lrumpvfs -lrumpfs_ffs -r 16m unix:///tmp/ffs_server 216.Ed 217.Sh SEE ALSO 218.Xr rump.halt 1 , 219.Xr dlopen 3 , 220.Xr rump 3 , 221.Xr rump_sp 7 222