From cd34ddcff75481b0b5a2ee0895e0bb7400801307 Mon Sep 17 00:00:00 2001 From: Alexandre Courbot Date: Mon, 21 Nov 2022 14:40:16 +0900 Subject: [PATCH] docs: book: document how to specify command-line options and configuration files Document the format and rules for specifying command-line options, and add a section on how configuration files can also be used. BUG=b:218223240 TEST=mdbook build Change-Id: Ieec40315b7ae8212c6a5b60280440abc9a5e92e6 Reviewed-on: https://chromium-review.googlesource.com/c/crosvm/crosvm/+/4040820 Reviewed-by: Keiichi Watanabe Commit-Queue: Alexandre Courbot Reviewed-by: Daniel Verkamp --- docs/book/src/SUMMARY.md | 1 + docs/book/src/running_crosvm/index.md | 2 + docs/book/src/running_crosvm/options.md | 162 ++++++++++++++++++++++++ 3 files changed, 165 insertions(+) create mode 100644 docs/book/src/running_crosvm/options.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 17c1f0a62e..c281970e4d 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -7,6 +7,7 @@ - [Example Usage](./running_crosvm/example_usage.md) - [Advanced Usage](./running_crosvm/advanced_usage.md) - [Custom Kernel / Rootfs](./running_crosvm/custom_kernel_rootfs.md) + - [Options and Configuration Files](./running_crosvm/options.md) - [System Requirements](./running_crosvm/requirements.md) - [Features](./running_crosvm/features.md) - [Programmatic Interaction](./running_crosvm/programmatic_interaction.md) diff --git a/docs/book/src/running_crosvm/index.md b/docs/book/src/running_crosvm/index.md index d3022e4361..db662d650e 100644 --- a/docs/book/src/running_crosvm/index.md +++ b/docs/book/src/running_crosvm/index.md @@ -7,5 +7,7 @@ This chapter includes instructions on how to run crosvm. of crosvm. - [Custom Kernel / Rootfs](./custom_kernel_rootfs.md): Instructions on how to build a kernel and rootfs for crosvm. +- [Options and Configuration Files](./options.md): How to specify command-line options and use + configuration files - [System Requirements](./requirements.md): Host and guest requirements for running crosvm - [Features](./features.md): Feature flags available when building crosvm diff --git a/docs/book/src/running_crosvm/options.md b/docs/book/src/running_crosvm/options.md new file mode 100644 index 0000000000..de95907d4c --- /dev/null +++ b/docs/book/src/running_crosvm/options.md @@ -0,0 +1,162 @@ +# Command line options and configuration files + +It is possible to configure a VM through command-line options and/or a JSON configuration file. + +The names and format of configurations options are consistent between both ways of specifying, +however the command-line includes options that are deprecated or unstable, whereas the configuration +file only allows stable options. This section reviews how to use both. + +## Command-line options + +Command-line options generally take a set of key-value pairs separated by the comma (`,`) character. +The acceptable key-values for each option can be obtained by passing the `--help` option to a crosvm +command: + +```sh +crosvm run --help +... + -b, --block parameters for setting up a block device. + Valid keys: + path=PATH - Path to the disk image. Can be specified + without the key as the first argument. + ro=BOOL - Whether the block should be read-only. + (default: false) + root=BOOL - Whether the block device should be mounted + as the root filesystem. This will add the required + parameters to the kernel command-line. Can only be + specified once. (default: false) + sparse=BOOL - Indicates whether the disk should support + the discard operation. (default: true) + block-size=BYTES - Set the reported block size of the + disk. (default: 512) + id=STRING - Set the block device identifier to an ASCII + string, up to 20 characters. (default: no ID) + direct=BOOL - Use O_DIRECT mode to bypass page cache. + (default: false) +... +``` + +From this help message, we see that the `--block` or `-b` option accepts the `path`, `ro`, `root`, +`sparse`, `block-size`, `id`, and `direct` keys. Keys which default value is mentioned are optional, +which means only the `path` key must always be specified. + +One example invocation of the `--block` option could be: + +```sh +--block path=/path/to/vmlinux,root=true,block-size=4096 +``` + +Keys taking a boolean parameters can be enabled by specifying their name witout any value, so the +previous option can also be written as + +```sh +--block path=/path/to/vmlinux,root,block-size=4096 +``` + +Also, the name of the first key can be entirely omitted, which further simplifies our option as: + +```sh +--block /path/to/vmlinux,root,block-size=4096 +``` + +## Configuration files + +Configuration files are specified using the `--cfg` argument. Here is an example configuration file +specifying a basic VM with a few devices: + +```json +{ + "kernel": "/path/to/vmlinux", + "cpus": { + "num-cores": 8 + }, + "mem": { + "size": 2048 + }, + "block": [ + { + "path": "/path/to/root.img", + "root": true + } + ], + "serial": [ + { + "type": "stdout", + "hardware": "virtio-console", + "console": true, + "stdin": true + } + ], + "net": [ + { + "tap-name": "crosvm_tap" + } + ] +} +``` + +The equivalent command-line options corresponding to this configuration file would be: + +```sh +--kernel path/to/vmlinux \ +--cpus num-cores=8 --mem size=2048 \ +--block path=/path/to/root.img,root \ +--serial type=stdout,hardware=virtio-console,console,stdin \ +--net tap-name=crosvm_tap +``` + +Or, if we apply the simplification rules discussed in the previous section: + +```sh +--kernel /path/to/vmlinux \ +--cpus 8 --mem 2048 \ +--block /path/to/root.img,root \ +--serial stdout,hardware=virtio-console,console,stdin \ +--net tap-name=crosvm_tap +``` + +## Combining configuration files and command-line options + +One useful use of configuration files is to specify a base configuration that can be augmented or +modified. + +Configuration files and other command-line options can be specified together. When this happens, the +command-line parameters will be merged into the initial configuration created by the configuration +file, regardless of their position relative to the `--cfg` argument and even if they come before it. + +The effect of command-line arguments redefining items of the configuration file depends on the +nature of said items. If an item can be specified several times (like a block device), then the +command-line arguments will augment the configuration file. For instance, considering this +configuration file `vm.json`: + +```json +{ + "kernel": "/path/to/vmlinux", + "block": [ + { + "path": "/path/to/root.img", + "root": true + } + ] +} +``` + +And the following crosvm invocation: + +```sh +crosvm run --cfg vm.json --block /path/to/home.img +``` + +Then the created VM will have two block devices, the first one pointing to `root.img` and the second +one to `home.img`. + +For options that can be specified only once, like `--kernel`, the one specified on the command-line +will take precedence over the one in the configuration file. For instance, with the same `vm.json` +file and the following command-line: + +```sh +crosvm run --cfg vm.json --kernel /path/to/another/vmlinux +``` + +Then the loaded kernel will be `/path/to/another/vmlinux`, and the `kernel` option in the +configuration file will become a no-op.