1.\" $NetBSD: rump_allserver.1,v 1.21 2014/01/16 00:32:48 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 January 15, 2014 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 kernel 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 kernel 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 kernel 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. 160By default, lazy resolution is used, and may result in a runtime 161error due to missing components. 162To test a configuration, run 163.Nm 164with 165.Ev LD_BIND_NOW=1 166(see examples). 167.It Fl m Ar module 168Load and link a kernel module after the rump kernel is initialized. 169For this to work, the rump kernel must include the vfs faction, 170since the module is loaded using kernel vfs code (see 171.Sx EXAMPLES ) . 172.It Fl r Ar total_ram 173Sets the limit of kernel memory allocatable by the server to 174.Ar total_ram 175as opposed to the default which allows the server to allocate as much 176memory as the host will give it. 177This parameter is especially useful for VFS servers, since by 178default the virtual file system will attempt to consume as much 179memory as it can, and accessing large files can cause an excessive 180amount of memory to be used as file system cache. 181.It Fl s 182Do not detach from the terminal. 183By default, 184.Nm 185detaches from the terminal once the service is running on 186.Ar url . 187.It Fl v 188Set bootverbose. 189.El 190.Pp 191After use, 192.Nm 193can be made to exit using 194.Xr rump.halt 1 . 195.Sh EXAMPLES 196Start a server and load the tmpfs file system module, and halt the 197server immediately afterwards: 198.Bd -literal -offset indent 199$ rump_server -lrumpvfs -m /modules/tmpfs.kmod unix://sock 200$ env RUMP_SERVER=unix://sock rump.halt 201.Ed 202.Pp 203Start a server with the one gigabyte host file 204.Pa dk.img 205mapped as the block device 206.Pa /dev/dk 207in the rump kernel. 208.Bd -literal -offset indent 209$ rump_allserver -d key=/dev/dk,hostpath=dk.img,size=1g unix://sock 210.Ed 211.Pp 212Start a server which listens on INADDR_ANY port 3755 213.Bd -literal -offset indent 214$ rump_server tcp://0:3755/ 215.Ed 216.Pp 217Test that a configuration contains all of the necessary components: 218.Bd -literal -offset indent 219$ env LD_BIND_NOW=1 rump_server -lrumpvfs -lrumpfs_ffs unix://tsock 220.Ed 221.Pp 222Start a FFS server with a 16MB kernel memory limit. 223.Bd -literal -offset indent 224$ rump_server -lrumpfs_ffs [...] -r 16m unix://ffs 225.Ed 226.Sh SEE ALSO 227.Xr rump.halt 1 , 228.Xr dlopen 3 , 229.Xr rump 3 , 230.Xr rump_sp 7 231