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