1# Rumprun unikernel configuration 2 3This document specifies the format used for configuring a rumprun unikernel and 4the platform-dependent methods for passing configuration to a rumprun unikernel. 5 6The intent of this specification is to define the _minimal_ "lowest common 7denominator" for configuring a rumprun unikernel. It is expected that special 8case configuration will be performed by the programs baked into the unikernel on 9a case-by-case basis rather than specified here. 10 11*This is a work in progress, the described format and interfaces are not yet 12stable! The document may not reflect the current implementation. Users are 13advised to continue using the `rumprun` tool to launch rumprun unikernels until 14further notice.* 15 16Configuration interfaces and/or behaviours not documented here are considered 17unofficial and experimental, and may be removed without warning. 18 19A rumprun unikernel does not _require_ any configuration to be passed for it to 20boot. However, if the `rc` key is not specified, only the first multibaked 21program in the unikernel will be invoked. 22 23# Configuration format 24 25The configuration format is defined using JSON: 26 27 { <JSON expression> } 28 29When configuration is passed directly on the kernel command line (see 30platform-specific methods below), everything up to the first `{` character is 31not considered to be part of the configuration. 32 33## cmdline, rc: Program invocation 34 35The `cmdline` key specifies the command line for unikernels containing a single 36program: 37 38 "cmdline": <string> 39 40* _cmdline_: Whitespace-delimited string of arguments passed to the program as 41 `argv[]`, including `argv[0]`. 42 43_TODO_: Is `cmdline` deprecated entirely in favour of `rc`? 44 45Unikernels which contain more than one program (using multibake) MUST use 46the `rc` key to specify command lines for each baked-in program: 47 48 "rc": [ 49 { 50 "bin" : <string>, 51 "argv" : [ <string>, ... ], 52 "runmode" : "& OR |" (optional) 53 }, 54 ... 55 ] 56 57Each element of `rc` describes a single program, in the order in which they 58are baked into the unikernel image. 59 60* _bin_: Passed to the corresponding program as `argv[0]`. 61* _argv[]_: Passed to the corresponding program as `argv[1..N]`. 62* _runmode_: Defines how the corresponding program will be invoked. _Optional_ 63 * `&`: run program in background. 64 * `|`: pipe output of program to next defined program. 65 * _default_: run program in foreground and wait for it to exit successfully 66 before running any further programs. 67 68## env: Environment variables 69 70 "env": <string> 71 ... 72 73* _env_: A string formatted as `NAME=VALUE`. Sets the environment variable 74 `NAME` to `VALUE`. 75 76_FIXME_: Relies on specifying multiple `env` keys, which is not valid JSON. 77Proposed specification as an array follows: 78 79 "env": [ 80 <string>, 81 ... 82 ] 83 84* _env[]_: Each element is a string formatted as `NAME=VALUE`. Sets the 85 environment variable `NAME` to `VALUE`. 86 87## hostname: Kernel hostname 88 89 "hostname": <string> 90 91* _hostname_: Sets the hostname returned by the `gethostname()` call. 92 93## net: Network interfaces 94 95Each `net` key defines a network interface to configure: 96 97 "net": { 98 "if": <string>, 99 "cloner": <boolean>, 100 "type": <string>, 101 <type-specific keys> 102 } 103 ... 104 105* _if_: The name of the network interface, as seen by the rump kernel. (eg. 106 `vioif0`, `xenif0`) 107* _cloner_: If true, the rump kernel interface is created at boot time. Required 108 for Xen netback interfaces. 109* _type_: Network interface type. Supported values are `inet` or `inet6`. 110 111_FIXME_: Relies on specifying multiple `net` keys, which is not valid JSON. 112Should be change to use an array instead. 113 114### inet: IPv4 configuration 115 116A `type` of `inet` indicates that this key defines an interface to be configured 117using IPv4. The `method` key must be set to one of the following: 118 119* `dhcp`: Configure the interface using DHCPv4. 120* `static`: Configure the interface statically. The following additional keys 121 must be present: 122 * `addr`: IPv4 interface address. 123 * `mask`: IPv4 interface netmask in CIDR format. 124 * `gw`: IPv4 address of default gateway. _Optional._ 125 126### inet6: IPv6 configuration 127 128A `type` of `inet6` indicates that this key defines an interface to be 129configured using IPv6. The `method` key must be set to one of the following: 130 131* `auto`: Configure the interface using IPv6 stateless autoconfiguration. 132* `static`: Configure the interface statically. The following additional keys 133 must be present: 134 * `addr`: IPv6 interface address. 135 * `mask`: IPv6 interface netmask in CIDR format. 136 * `gw`: IPv6 address of default gateway. _Optional._ 137 138## blk: Block devices and filesystems 139 140Each `blk` key defines a block device and filesystem to mount: 141 142 "blk": { 143 "source": <string>, 144 <source-specific keys> 145 "path": "/dev/ld0a", 146 "fstype": "blk", 147 "mountpoint": "/etc", 148 } 149 ... 150 151* _source_: One of `dev`, `vnd` or `etfs`. 152 153_FIXME_: Relies on specifying multiple `blk` keys, which is not valid JSON. 154Should be change to use an array instead. 155 156_FIXME_: Unclear from the code when a `blk` key can be used to configure, but 157not mount, a block device. 158 159### dev: Mount filesystem backed by block device 160 161A `source` of `dev` indicates that this key defines a filesystem backed by a 162rump kernel block device. Block devices are usually used by the rumprun 163unikernel to access directly-attached storage on bare metal, or `virtio` devices 164on QEMU/KVM. 165 166The following additional keys are required: 167 168* _mountpoint_: The mountpoint for the filesystem. 169* _fstype_: If set to `kern`, a `kernfs` will be mounted on `mountpoint` and all 170 other keys will be ignored. If set to `blk`, rumprun will attempt to mount a 171 filesystem of type `ffs`, `ext2fs` or `cd9660` from the local block device 172 specified by `path`. 173* _path_: The pathname of the block device to mount, as seen by the rump kernel. 174 175_TODO_: Specify example _paths_ for block devices (`/dev/ld0X`, `/dev/sd0X`). 176 177### etfs: Mount filesystem backed by rump_etfs "host" device 178 179A `source` of `etfs` indicates that this key defines a filesystem backed by a 180`rump_etfs(3)` device. ETFS devices are usually used by the rumprun unikernel to 181access storage on the Xen platform. 182 183The following additional keys are required: 184 185* _mountpoint_: The mountpoint for the filesystem. 186* _fstype_: Must be set to `blk`. Rumprun will attempt to mount a 187 filesystem of type `ffs`, `ext2fs` or `cd9660` from the etfs device specified 188 by `path`. 189* _path_: The platform-specific `key` passed to `rump_pub_etfs_register()`. 190 191_TODO_: Specify example _paths_ for block devices used on Xen. 192 193### vnd: Mount filesystem backed by a vnode disk device 194 195_TODO_: Complete this section. 196 197# Passing configuration to the unikernel 198 199## hw platform on x86 200 201On x86 bare metal (this includes QEMU, KVM or other hypervisors using HVM) 202rumprun uses the multiboot protocol. 203 204Configuration may be passed either directly on the kernel command line, or 205loaded as a multiboot module. If a multiboot module containing configuration is 206found, it is used in preference to the kernel command line. 207 208_TODO_: Provide examples. Also, can the `ROOTFSCFG=` hack go away now that we 209can load configuration using multiboot. 210 211_TODO_: Make it explicit what a "multiboot module containing configuration" 212means. Ignore modules which we don't understand (e.g. does not start with `{`). 213 214## xen platform on x86 215 216On x86 paravirtualized Xen, the rumprun configuration must be written to the 217domain-specific Xenstore key `rumprun/cfg` before the domU is started. 218 219_TODO_: Examples. Do we officially want to support passing config on Xen via 220cmdline (I think not). 221 222_TODO_: Explain what "domain-specific Xenstore key" means. 223 224## hw platform on ARM 225 226TBD. 227