• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Command line options and configuration files
2
3It is possible to configure a VM through command-line options and/or a JSON configuration file.
4
5The names and format of configurations options are consistent between both ways of specifying,
6however the command-line includes options that are deprecated or unstable, whereas the configuration
7file only allows stable options. This section reviews how to use both.
8
9## Command-line options
10
11Command-line options generally take a set of key-value pairs separated by the comma (`,`) character.
12The acceptable key-values for each option can be obtained by passing the `--help` option to a crosvm
13command:
14
15```sh
16crosvm run --help
17...
18  -b, --block       parameters for setting up a block device.
19                    Valid keys:
20                        path=PATH - Path to the disk image. Can be specified
21                            without the key as the first argument.
22                        ro=BOOL - Whether the block should be read-only.
23                            (default: false)
24                        root=BOOL - Whether the block device should be mounted
25                            as the root filesystem. This will add the required
26                            parameters to the kernel command-line. Can only be
27                            specified once. (default: false)
28                        sparse=BOOL - Indicates whether the disk should support
29                            the discard operation. (default: true)
30                        block-size=BYTES - Set the reported block size of the
31                            disk. (default: 512)
32                        id=STRING - Set the block device identifier to an ASCII
33                            string, up to 20 characters. (default: no ID)
34                        direct=BOOL - Use O_DIRECT mode to bypass page cache.
35                            (default: false)
36...
37```
38
39From this help message, we see that the `--block` or `-b` option accepts the `path`, `ro`, `root`,
40`sparse`, `block-size`, `id`, and `direct` keys. Keys which default value is mentioned are optional,
41which means only the `path` key must always be specified.
42
43One example invocation of the `--block` option could be:
44
45```sh
46--block path=/path/to/bzImage,root=true,block-size=4096
47```
48
49Keys taking a boolean parameters can be enabled by specifying their name witout any value, so the
50previous option can also be written as
51
52```sh
53--block path=/path/to/bzImage,root,block-size=4096
54```
55
56Also, the name of the first key can be entirely omitted, which further simplifies our option as:
57
58```sh
59--block /path/to/bzImage,root,block-size=4096
60```
61
62## Configuration files
63
64Configuration files are specified using the `--cfg` argument. Here is an example configuration file
65specifying a basic VM with a few devices:
66
67```json
68{
69    "kernel": "/path/to/bzImage",
70    "cpus": {
71        "num-cores": 8
72    },
73    "mem": {
74        "size": 2048
75    },
76    "block": [
77        {
78            "path": "/path/to/root.img",
79            "root": true
80        }
81    ],
82    "serial": [
83        {
84            "type": "stdout",
85            "hardware": "virtio-console",
86            "console": true,
87            "stdin": true
88        }
89    ],
90    "net": [
91        {
92            "tap-name": "crosvm_tap"
93        }
94    ]
95}
96```
97
98The equivalent command-line options corresponding to this configuration file would be:
99
100```sh
101--kernel path/to/bzImage \
102--cpus num-cores=8 --mem size=2048 \
103--block path=/path/to/root.img,root \
104--serial type=stdout,hardware=virtio-console,console,stdin \
105--net tap-name=crosvm_tap
106```
107
108Or, if we apply the simplification rules discussed in the previous section:
109
110```sh
111--kernel /path/to/bzImage \
112--cpus 8 --mem 2048 \
113--block /path/to/root.img,root \
114--serial stdout,hardware=virtio-console,console,stdin \
115--net tap-name=crosvm_tap
116```
117
118## Combining configuration files and command-line options
119
120One useful use of configuration files is to specify a base configuration that can be augmented or
121modified.
122
123Configuration files and other command-line options can be specified together. When this happens, the
124command-line parameters will be merged into the initial configuration created by the configuration
125file, regardless of their position relative to the `--cfg` argument and even if they come before it.
126
127The effect of command-line arguments redefining items of the configuration file depends on the
128nature of said items. If an item can be specified several times (like a block device), then the
129command-line arguments will augment the configuration file. For instance, considering this
130configuration file `vm.json`:
131
132```json
133{
134    "kernel": "/path/to/bzImage",
135    "block": [
136        {
137            "path": "/path/to/root.img",
138            "root": true
139        }
140    ]
141}
142```
143
144And the following crosvm invocation:
145
146```sh
147crosvm run --cfg vm.json --block /path/to/home.img
148```
149
150Then the created VM will have two block devices, the first one pointing to `root.img` and the second
151one to `home.img`.
152
153For options that can be specified only once, like `--kernel`, the one specified on the command-line
154will take precedence over the one in the configuration file. For instance, with the same `vm.json`
155file and the following command-line:
156
157```sh
158crosvm run --cfg vm.json --kernel /path/to/another/bzImage
159```
160
161Then the loaded kernel will be `/path/to/another/bzImage`, and the `kernel` option in the
162configuration file will become a no-op.
163