From e6207bf11056ad0e576da32c31b2da43eded86b4 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Tue, 1 Dec 2015 16:18:37 +0100 Subject: [PATCH] config.md: Continuing work on configuration spec Now mostly documents the current implementation --- doc/config.md | 188 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 135 insertions(+), 53 deletions(-) diff --git a/doc/config.md b/doc/config.md index 30f06fd..083940f 100644 --- a/doc/config.md +++ b/doc/config.md @@ -1,8 +1,12 @@ # Rumprun unikernel configuration -This document specifies the JSON format used for configuring a rumprun unikernel -and the platform-dependent methods for passing configuration to a rumprun -unikernel. +This document specifies the format used for configuring a rumprun unikernel and +the platform-dependent methods for passing configuration to a rumprun unikernel. + +The intent of this specification is to define the _minimal_ "lowest common +denominator" for configuring a rumprun unikernel. It is expected that special +case configuration will be performed by the programs baked into the unikernel on +a case-by-case basis rather than specified here. *This is a work in progress, the described format and interfaces are not yet stable! The document may not reflect the current implementation. Users are @@ -12,30 +16,39 @@ further notice.* Configuration interfaces and/or behaviours not documented here are considered unofficial and experimental, and may be removed without warning. -## Configuration format +A rumprun unikernel does not _require_ any configuration to be passed for it to +boot. However, if the `rc` key is not specified, only the first multibaked +program in the unikernel will be invoked. + +# Configuration format -The configuration format is a valid JSON expression: +The configuration format is defined using JSON: { } -Unless otherwise stated, all keys are optional. +When configuration is passed directly on the kernel command line (see +platform-specific methods below), everything up to the first `{` character is +not considered to be part of the configuration. -### cmdline, rc: Program command line(s) +## cmdline, rc: Program invocation The `cmdline` key specifies the command line for unikernels containing a single program: - "cmdline": "arg0 arg1 arg2 ... argN" + "cmdline": + +* _cmdline_: Whitespace-delimited string of arguments passed to the program as + `argv[]`, including `argv[0]`. -_argN_: Corresponds to the `argv[N]` passed to the program. +_TODO_: Is `cmdline` deprecated entirely in favour of `rc`? Unikernels which contain more than one program (using multibake) MUST use the `rc` key to specify command lines for each baked-in program: "rc": [ { - "bin" : "arg0", - "argv" : [ "arg1", "arg2", ..., "argN" ], + "bin" : , + "argv" : [ , ... ], "runmode" : "& OR |" (optional) }, ... @@ -44,80 +57,146 @@ the `rc` key to specify command lines for each baked-in program: Each element of `rc` describes a single program, in the order in which they are baked into the unikernel image. -_argN_: Corresponds to the `argv[N]` passed to the program. -_runmode_: - * `&`: run this program in background - * `|`: pipe output of current program to next defined program - * (default): run this program in foreground and wait for it to successfully - exit before running further programs +* _bin_: Passed to the corresponding program as `argv[0]`. +* _argv[]_: Passed to the corresponding program as `argv[1..N]`. +* _runmode_: Defines how the corresponding program will be invoked. _Optional_ + * `&`: run program in background. + * `|`: pipe output of program to next defined program. + * _default_: run program in foreground and wait for it to exit successfully + before running any further programs. -### env: Environment variables +## env: Environment variables - "env": "NAME=VALUE" + "env": ... -Sets the environment variable `NAME` to `VALUE`. +* _env_: A string formatted as `NAME=VALUE`. Sets the environment variable + `NAME` to `VALUE`. _FIXME_: Relies on specifying multiple `env` keys, which is not valid JSON. Proposed specification as an array follows: "env": [ - "NAME=VALUE", + , ... ] -Sets the environment variable `NAME` to `VALUE`. +* _env[]_: Each element is a string formatted as `NAME=VALUE`. Sets the + environment variable `NAME` to `VALUE`. -### hostname: Kernel hostname setting +## hostname: Kernel hostname - "hostname": "hostname" + "hostname": -_hostname_: The kernel hostname. +* _hostname_: Sets the hostname returned by the `gethostname()` call. -### net: Network interfaces +## net: Network interfaces + +Each `net` key defines a network interface to configure: "net": { - "if": "if", - "cloner": "cloner", - "type": "type", - "method": "method", - ... + "if": , + "cloner": , + "type": , + } ... -* _if_: The kernel name of the network interface. (eg. `vioif0`, `xenif0`) -* _cloner_: Create the interface? (boolean, Xen only) -* _type_, _method_: Network interface type and configuration method. - -_TODO_: Document methods. +* _if_: The name of the network interface, as seen by the rump kernel. (eg. + `vioif0`, `xenif0`) +* _cloner_: If true, the rump kernel interface is created at boot time. Required + for Xen netback interfaces. +* _type_: Network interface type. Supported values are `inet` or `inet6`. _FIXME_: Relies on specifying multiple `net` keys, which is not valid JSON. Should be change to use an array instead. -### blk: Block devices and file systems +### inet: IPv4 configuration + +A `type` of `inet` indicates that this key defines an interface to be configured +using IPv4. The `method` key must be set to one of the following: + +* `dhcp`: Configure the interface using DHCPv4. +* `static`: Configure the interface statically. The following additional keys + must be present: + * `addr`: IPv4 interface address. + * `mask`: IPv4 interface netmask in CIDR format. + * `gw`: IPv4 address of default gateway. _Optional._ + +### inet6: IPv6 configuration + +A `type` of `inet6` indicates that this key defines an interface to be +configured using IPv6. The `method` key must be set to one of the following: + +* `auto`: Configure the interface using IPv6 stateless autoconfiguration. +* `static`: Configure the interface statically. The following additional keys + must be present: + * `addr`: IPv6 interface address. + * `mask`: IPv6 interface netmask in CIDR format. + * `gw`: IPv6 address of default gateway. _Optional._ + +## blk: Block devices and filesystems + +Each `blk` key defines a block device and filesystem to mount: "blk": { - "source": "dev", + "source": , + "path": "/dev/ld0a", "fstype": "blk", "mountpoint": "/etc", } ... -* _source_: `dev`, `vnd` or `etfs` -* _path_: The path to the block device/etfs key. -* _fstype_: `blk` or `kernfs` -* _mountpoint_: The filesystem mount point. - -_TODO_: Incomplete. Document semantics of various sources, and differences -between Xen and hw. +* _source_: One of `dev`, `vnd` or `etfs`. _FIXME_: Relies on specifying multiple `blk` keys, which is not valid JSON. Should be change to use an array instead. -## Passing configuration to the unikernel +_FIXME_: Unclear from the code when a `blk` key can be used to configure, but +not mount, a block device. + +### dev: Mount filesystem backed by block device + +A `source` of `dev` indicates that this key defines a filesystem backed by a +rump kernel block device. Block devices are usually used by the rumprun +unikernel to access directly-attached storage on bare metal, or `virtio` devices +on QEMU/KVM. + +The following additional keys are required: -### hw platform on x86 +* _mountpoint_: The mountpoint for the filesystem. +* _fstype_: If set to `kern`, a `kernfs` will be mounted on `mountpoint` and all + other keys will be ignored. If set to `blk`, rumprun will attempt to mount a + filesystem of type `ffs`, `ext2fs` or `cd9660` from the local block device + specified by `path`. +* _path_: The pathname of the block device to mount, as seen by the rump kernel. + +_TODO_: Specify example _paths_ for block devices (`/dev/ld0X`, `/dev/sd0X`). + +### etfs: Mount filesystem backed by rump_etfs "host" device + +A `source` of `etfs` indicates that this key defines a filesystem backed by a +`rump_etfs(3)` device. ETFS devices are usually used by the rumprun unikernel to +access storage on the Xen platform. + +The following additional keys are required: + +* _mountpoint_: The mountpoint for the filesystem. +* _fstype_: Must be set to `blk`. Rumprun will attempt to mount a + filesystem of type `ffs`, `ext2fs` or `cd9660` from the etfs device specified + by `path`. +* _path_: The platform-specific `key` passed to `rump_pub_etfs_register()`. + +_TODO_: Specify example _paths_ for block devices used on Xen. + +### vnd: Mount filesystem backed by a vnode disk device + +_TODO_: Complete this section. + +# Passing configuration to the unikernel + +## hw platform on x86 On x86 bare metal (this includes QEMU, KVM or other hypervisors using HVM) rumprun uses the multiboot protocol. @@ -126,19 +205,22 @@ Configuration may be passed either directly on the kernel command line, or loaded as a multiboot module. If a multiboot module containing configuration is found, it is used in preference to the kernel command line. -_TODO_: Provide examples. Also, can the `ROOTFSCFG=` hack go away now? +_TODO_: Provide examples. Also, can the `ROOTFSCFG=` hack go away now that we +can load configuration using multiboot. _TODO_: Make it explicit what a "multiboot module containing configuration" means. Ignore modules which we don't understand (e.g. does not start with `{`). -### hw platform on ARM - -TBD. - -### xen platform on x86 +## xen platform on x86 On x86 paravirtualized Xen, the rumprun configuration must be written to the domain-specific Xenstore key `rumprun/cfg` before the domU is started. _TODO_: Examples. Do we officially want to support passing config on Xen via cmdline (I think not). + +_TODO_: Explain what "domain-specific Xenstore key" means. + +## hw platform on ARM + +TBD. -- 2.39.5