Permalink
Browse files

config.md: Continuing work on configuration spec

Now mostly documents the current implementation
  • Loading branch information...
mato committed Dec 1, 2015
1 parent 8365eb9 commit e6207bf11056ad0e576da32c31b2da43eded86b4
Showing with 135 additions and 53 deletions.
  1. +135 −53 doc/config.md
View
@@ -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:
{ <JSON expression> }
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": <string>
* _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" : <string>,
"argv" : [ <string>, ... ],
"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": <string>
...
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",
<string>,
...
]
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": <string>
_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": <string>,
"cloner": <boolean>,
"type": <string>,
<type-specific keys>
}
...
* _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": <string>,
<source-specific keys>
"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.

0 comments on commit e6207bf

Please sign in to comment.