1.\" $NetBSD: rump_allserver.1,v 1.24 2023/04/24 00:07:04 uwe 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 April 24, 2023 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 Fl 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.Sm off 79.Ar name\^ Li = Ar value 80.Sm on 81format and must contain the following tokens: 82. 83.Bl -tag -width Ic -offset indent 84. 85.It Ic key 86Block device path in rump kernel namespace. 87This must be specified according to the rules for a key in 88.Xr rump_etfs 3 . 89. 90.It Ic hostpath 91Host file used for storage. 92If the file does not exist, it will be created. 93.El 94. 95.Pp 96The type of file that 97.Ic key 98is exposed as within the rump kernel is specified with: 99. 100.Bl -tag -width Ic -offset indent 101.It Ic type 102Possible values are 103.Ql blk , 104.Ql chr , 105and 106.Ql reg 107for block device, character device and regular file, respectively. 108The default is a block device 109.Pq Ql blk . 110.Pp 111.Sy Note : 112the contents of block devices are cached in the rump kernel's 113buffer cache. 114To avoid cache incoherency, it is advisable not to access a file 115through the host namespace while it is mapped as a block device in 116a rump kernel. 117.El 118. 119.Pp 120For block and character devices the 121.Bq Va offset Ns \&,\~ Ns Va offset Ns + Ns Va size 122region of the file must be specified with: 123. 124.Bl -tag -width Ic -offset indent 125. 126.It Ic disklabel 127Use a disklabel partition letter to specify the offset and size 128of the mapping. 129.Ic hostpath 130must contain a valid disklabel within the first 64k. 131. 132.It Ic offset 133Offset of the mapping. 134The default is 0. 135. 136.It Ic size 137Size of the mapping. 138Similar to 139.Xr dd 1 , 140this argument accepts a suffix as the multiplier for the number. 141The special value 142.Ql host 143indicates that the current size of 144.Ic hostpath 145will be used. 146In this case it is assumed that 147.Ic hostpath 148exists and is a regular file. 149.El 150. 151.Pp 152In case 153.Ic hostpath 154does not exist, it will be created as a regular file with mode 1550644 (plus any restrictions placed by umask). 156In case 157.Ic hostpath 158is a regular file and is not large enough to accommodate the 159specified size, it will be extended to the specified size. 160.It Fl l Ar library 161Call 162.Xr dlopen 3 163on library before initializing the rump kernel. 164In case 165.Ar library 166provides a kernel module, it will appear as a builtin module in the 167rump kernel. 168Any rump kernel component present in 169.Ar library 170will also be initialized. 171.Pp 172The argument 173.Ar library 174can contain a full path or a filename, in which case the standard 175dynamic library search path will be used. 176By default, lazy resolution is used, and may result in a runtime 177error due to missing components. 178To test a configuration, run 179.Nm 180with 181.Ev LD_BIND_NOW Ns Li \&=1 182.Pq see Sx EXAMPLES . 183.It Fl m Ar module 184Load and link a kernel module after the rump kernel is initialized. 185For this to work, the rump kernel must include the vfs faction, 186since the module is loaded using kernel vfs code 187.Pq see Sx EXAMPLES . 188.It Fl r Ar total_ram 189Sets the limit of kernel memory allocatable by the server to 190.Ar total_ram 191as opposed to the default which allows the server to allocate as much 192memory as the host will give it. 193This parameter is especially useful for VFS servers, since by 194default the virtual file system will attempt to consume as much 195memory as it can, and accessing large files can cause an excessive 196amount of memory to be used as file system cache. 197.It Fl s 198Do not detach from the terminal. 199By default, 200.Nm 201detaches from the terminal once the service is running on 202.Ar url . 203.It Fl v 204Set 205.Dv AB_VERBOSE 206in rump kernel's 207.Xr boothowto 9 . 208.El 209.Pp 210After use, 211.Nm 212can be made to exit using 213.Xr rump.halt 1 . 214.Sh EXAMPLES 215Start a server and load the tmpfs file system module, and halt the 216server immediately afterwards: 217.Bd -literal -offset indent 218$ rump_server -lrumpvfs -m /modules/tmpfs.kmod unix://sock 219$ env RUMP_SERVER=unix://sock rump.halt 220.Ed 221.Pp 222Start a server with the one gigabyte host file 223.Pa dk.img 224mapped as the block device 225.Pa /dev/dk 226in the rump kernel. 227.Pp 228.Dl $ rump_allserver -d key=/dev/dk,hostpath=dk.img,size=1g unix://sock 229.Pp 230Start a server which listens on INADDR_ANY port 3755 231.Pp 232.Dl $ rump_server tcp://0:3755/ 233.Pp 234Test that a configuration contains all of the necessary components: 235.Pp 236.Dl $ env LD_BIND_NOW=1 rump_server -lrumpvfs -lrumpfs_ffs unix://tsock 237.Pp 238Start a FFS server with a 16MB kernel memory limit. 239.Pp 240.Dl $ rump_server -lrumpfs_ffs [...] -r 16m unix://ffs 241.Sh SEE ALSO 242.Xr rump.halt 1 , 243.Xr dlopen 3 , 244.Xr rump 3 , 245.Xr rump_etfs 3 , 246.Xr rump_sp 7 247