Replace json string parameter with file

Signed-off-by: Laura Loghin <[email protected]>

Author: lauralt

CHANGELOG.md

@@ -1,12 +1,14 @@
 # Changelog
 
-## Unreleased
+## [Unreleased]
 
 ### Added
 
-- New command-line parameter for both `firecracker` and `jailer`, named 
-  `vmm-config`, which represents a JSON that can be used for configuring and 
-  starting a microVM without sending any API requests.
+- New command-line parameter for `firecracker`, named `--config-file`, which 
+  represents the path to a file that contains a JSON which can be used for 
+  configuring and starting a microVM without sending any API requests.
+- The jailer adheres to the "end of command options" convention, meaning 
+  all parameters specified after `--` are forwarded verbatim to Firecracker.
 
 ### Changed
 

FAQ.md

@@ -198,7 +198,7 @@ Possible mitigations are:
 
 ### How can I configure and start a microVM without sending API calls?
 
-Passing an optional command line parameter, `vmm-config`, to the Firecracker process 
-allows this type of configuration. This parameter must contain the entire JSON that 
-will be used for configuring all of the microVM's resources. One example of such JSON 
-can be found in `tests/framework/vm_config.json`.  
+Passing an optional command line parameter, `--config-file`, to the Firecracker 
+process allows this type of configuration. This parameter must be the path to a 
+file that contains the JSON specification that will be used to configure and start 
+the microVM. One example of such file can be found at `tests/framework/vm_config.json`. 

docs/getting-started.md

@@ -245,28 +245,23 @@ curl --unix-socket /tmp/firecracker.socket -i  \
 #### Configuring the microVM without sending API requests
 
 If you'd like to boot up a guest machine without using the API socket, you can do that 
-by passing the parameter `vmm-config` to the Firecracker process. The command for starting 
-Firecracker with this option will look like this:
+by passing the parameter `--config-file` to the Firecracker process. The command for 
+starting Firecracker with this option will look like this:
 
 ```bash
-./firecracker --api-sock /tmp/firecracker.socket --vmm-config "JSON_BODY"
+./firecracker --api-sock /tmp/firecracker.socket --config-file 
+<path_to_the_configuration_file>
 ```    
 
-"JSON_BODY" should contain the entire configuration for all of the microVM's resources. 
-You **must** provide in your JSON the configuration for the guest kernel and rootfs, as 
-these are mandatory, but all of the other resources are optional, so it's your choice if 
-you want to configure them or not. Because using this configuration method will also start 
-the microVM, you need to specify all desired pre-boot configurable resources in that JSON. 
-The names of the resources are the ones from the `firecracker.yaml` file and the names of 
-their fields are the same that are used in API requests. 
-The easiest way to send the configuration is by storing the JSON in a file and passing 
-the content of the file as command line parameter, for example: 
-
-```bash
-./firecracker --api-sock /tmp/firecracker.socket --vmm-config "$(cat /path_to_the_configuration_file)"
-``` 
-
-You can find an example of configuration file in `tests/framework/vm_config.json`.
+`path_to_the_configuration_file` should represent the path to a file that contains a 
+JSON which stores the entire configuration for all of the microVM's resources. The 
+JSON **must** contain the configuration for the guest kernel and rootfs, as these 
+are mandatory, but all of the other resources are optional, so it's your choice 
+if you want to configure them or not. Because using this configuration method will 
+also start the microVM, you need to specify all desired pre-boot configurable resources 
+in that JSON. The names of the resources are the ones from the `firecracker.yaml` file 
+and the names of their fields are the same that are used in API requests. 
+You can find an example of configuration file at `tests/framework/vm_config.json`. 
 After the machine is booted, you can still use the socket to send API requests
 for post-boot operations.
 

docs/jailer.md

@@ -14,7 +14,7 @@ jailer --id <id> \
        [--netns <netns>]
        [--daemonize]
        [--seccomp-level <level>]
-       [--vmm-config <vmm_config>]
+       [--...extra arguments for Firecracker]
 ```
 
 - `id` is the unique VM identification string, which may contain alphanumeric
@@ -39,8 +39,14 @@ jailer --id <id> \
     Firecracker.
   - 2 (default): advanced filtering. This adds further checks on some of the
     parameters of the allowed syscalls.
-- `vmm_config` represents the json that can be used for configuring and 
-  starting the microVM without using API requests.
+- The jailer adheres to the "end of command options" convention, meaning 
+  all parameters specified after `--` are forwarded to Firecracker. For 
+  example, this can be paired with the `--config-file` Firecracker argument to 
+  specify a configuration file when starting Firecracker via the jailer (the 
+  file path and the resources referenced within must be valid relative to a 
+  jailed Firecracker). Please note the jailer already passes the following 
+  parameters to the Firecracker process: `--api-sock`, `--seccomp-level` and 
+  `--id`.
 
 ## Jailer Operation
 
@@ -82,14 +88,13 @@ After starting, the Jailer goes through the following operations:
 - Drop privileges via setting the provided `uid` and `gid`.
 - Exec into `<exec_file_name> --id=<id> --api-sock=/api.socket
   --seccomp-level=<level> --start-time-us=<opaque>
-  --start-time-cpu-us=<opaque> [--vmm-config <vmm_config>]`.
-  Where:
+  --start-time-cpu-us=<opaque>` (and also forward any extra arguments provided
+  to the jailer after `--`, as mentioned in the **Jailer Usage** section),
+  where:
   - `id`: (`string`) - The `id` argument provided to jailer.
   - `level`: (`number`) - the `--seccomp-level` argument provided to jailer.
   - `opaque`: (`number`) time calculated by the jailer that it spent doing
      its work.
-  - `vmm_config`: (`string`) - optional argument that can be used for 
-     configuring and starting a microVM without sending API requests.
 
 ## Example Run and Notes
 
@@ -196,10 +201,6 @@ We can now use the socket at
 `/srv/jailer/firecracker/551e7604-e35c-42b3-b825-416853441234/root/api.socket`
 to interact with the VM.
 
-In case we want to configure the VM without using the API socket, we can also 
-pass the `vmm-config` parameter, as mentioned in the previous section 
-(`Jailer Operation`).
-
 ### Observations
 
 - The user must create hard links for (or copy) any resources which will be

jailer/src/env.rs

@@ -52,7 +52,7 @@ pub struct Env {
     seccomp_level: u32,
     start_time_us: u64,
     start_time_cpu_us: u64,
-    config_json: Option<String>,
+    extra_args: Option<Vec<String>>,
 }
 
 impl Env {
@@ -113,7 +113,10 @@ impl Env {
             .parse::<u32>()
             .map_err(Error::SeccompLevel)?;
 
-        let config_json = args.value_of("vmm-config").map(String::from);
+        let extra_args = args
+            .values_of("extra-args")
+            .map(|v| v.collect::<Vec<&str>>())
+            .map(|v| v.iter().map(|s| s.to_string()).collect());
 
         Ok(Env {
             id: id.to_string(),
@@ -127,7 +130,7 @@ impl Env {
             seccomp_level,
             start_time_us,
             start_time_cpu_us,
-            config_json,
+            extra_args,
         })
     }
 
@@ -307,8 +310,8 @@ impl Env {
             .uid(self.uid())
             .gid(self.gid());
 
-        if let Some(json) = self.config_json {
-            command.arg(format!("--vmm-config={}", json));
+        if let Some(args) = self.extra_args {
+            command.args(args);
         }
         Err(Error::Exec(command.exec()))
     }
@@ -330,7 +333,7 @@ mod tests {
         chroot_base: &str,
         netns: Option<&str>,
         daemonize: bool,
-        config_json: Option<&str>,
+        extra_args: Option<Vec<&str>>,
     ) -> ArgMatches<'a> {
         let app = clap_app();
 
@@ -359,11 +362,12 @@ mod tests {
             arg_vec.push("--daemonize");
         }
 
-        if let Some(json) = config_json {
-            arg_vec.push("--vmm-config");
-            arg_vec.push(json);
+        if let Some(args) = extra_args {
+            arg_vec.push("--");
+            for exec_arg in args {
+                arg_vec.push(exec_arg);
+            }
         }
-
         app.get_matches_from_safe(arg_vec).unwrap()
     }
 
@@ -376,25 +380,7 @@ mod tests {
         let gid = "1002";
         let chroot_base = "/";
         let netns = "zzzns";
-        let config_json = r#"{
-           "boot-source":{
-               "kernel_image_path": "vmlinux.bin",
-               "boot_args": "console=ttyS0 reboot=k panic=1 pci=off"
-           },
-           "drives": [
-               {
-                   "drive_id": "rootfs",
-                   "path_on_host": "xenial.rootfs.ext4",
-                   "is_root_device": true,
-                   "is_read_only": false
-               }
-           ],
-           "machine-config":{
-               "vcpu_count": 2,
-               "mem_size_mib": 1024,
-               "ht_enabled": false
-           }
-       }"#;
+        let extra_args = vec!["--config-file", "config_file_path"];
 
         // This should be fine.
         let good_env = Env::new(
@@ -407,7 +393,7 @@ mod tests {
                 chroot_base,
                 Some(netns),
                 true,
-                Some(config_json),
+                Some(extra_args),
             ),
             0,
             0,
@@ -422,9 +408,16 @@ mod tests {
         assert_eq!(good_env.chroot_dir(), chroot_dir);
         assert_eq!(format!("{}", good_env.gid()), gid);
         assert_eq!(format!("{}", good_env.uid()), uid);
+
         assert_eq!(good_env.netns, Some(netns.to_string()));
         assert!(good_env.daemonize);
-        assert_eq!(good_env.config_json, Some(config_json.to_string()));
+        assert_eq!(
+            good_env.extra_args,
+            Some(vec![
+                "--config-file".to_string(),
+                "config_file_path".to_string()
+            ])
+        );
 
         let another_good_env = Env::new(
             make_args(

jailer/src/lib.rs

@@ -20,7 +20,7 @@ use std::io;
 use std::path::{Path, PathBuf};
 use std::result;
 
-use clap::{App, Arg, ArgMatches};
+use clap::{App, AppSettings, Arg, ArgMatches};
 
 use env::Env;
 use fc_util::validators;
@@ -222,6 +222,7 @@ pub fn clap_app<'a, 'b>() -> App<'a, 'b> {
         .version(crate_version!())
         .author(crate_authors!())
         .about("Jail a microVM.")
+        .setting(AppSettings::TrailingVarArg)
         .arg(
             Arg::with_name("id")
                 .long("id")
@@ -299,10 +300,11 @@ pub fn clap_app<'a, 'b>() -> App<'a, 'b> {
                 .possible_values(&["0", "1", "2"]),
         )
         .arg(
-            Arg::with_name("vmm-config")
-                .long("vmm-config")
+            Arg::with_name("extra-args")
+                .help("Arguments that will be passed verbatim to the exec file.")
+                .required(false)
                 .takes_value(true)
-                .required(false),
+                .multiple(true),
         )
 }
 

src/main.rs

@@ -17,6 +17,7 @@ extern crate vmm;
 use backtrace::Backtrace;
 use clap::{App, Arg};
 
+use std::fs;
 use std::io::ErrorKind;
 use std::panic;
 use std::path::PathBuf;
@@ -109,8 +110,9 @@ fn main() {
                 .hidden(true),
         )
         .arg(
-            Arg::with_name("vmm-config")
-                .long("vmm-config")
+            Arg::with_name("config-file")
+                .long("config-file")
+                .help("Path to a file that contains the microVM configuration in JSON format.")
                 .takes_value(true)
                 .required(false),
         )
@@ -148,7 +150,11 @@ fn main() {
             .expect("'start-time-cpu_us' parameter expected to be of 'u64' type.")
     });
 
-    let vmm_config_json = cmd_arguments.value_of("vmm-config").map(String::from);
+    let vmm_config_json = if let Some(path) = cmd_arguments.value_of("config-file") {
+        Some(fs::read_to_string(path).expect("Unable to open or read from the configuration file"))
+    } else {
+        None
+    };
 
     let shared_info = Arc::new(RwLock::new(InstanceInfo {
         state: InstanceState::Uninitialized,

tests/framework/jailer.py

@@ -62,7 +62,7 @@ def __del__(self):
         """Cleanup this jailer context."""
         self.cleanup()
 
-    def construct_param_list(self, config_json):
+    def construct_param_list(self, config_file):
         """Create the list of parameters we want the jailer to start with.
 
         We want to be able to vary any parameter even the required ones as we
@@ -94,8 +94,9 @@ def construct_param_list(self, config_json):
             jailer_param_list.extend(
                 ['--seccomp-level', str(self.seccomp_level)]
             )
-        if config_json is not None:
-            jailer_param_list.extend(['--vmm-config', str(config_json)])
+        if config_file is not None:
+            jailer_param_list.extend(['--'])
+            jailer_param_list.extend(['--config-file', str(config_file)])
         return jailer_param_list
 
     def chroot_base_with_id(self):

tests/framework/microvm.py

@@ -46,7 +46,7 @@ def __init__(
         build_feature='',
         monitor_memory=True,
         bin_cloner_path=None,
-        config_json=None
+        config_file=None
     ):
         """Set up microVM attributes, paths, and data structures."""
         # Unique identifier for this machine.
@@ -96,8 +96,9 @@ def __init__(
         self.machine_cfg = None
         self.vsock = None
 
-        # Optional json for configuring microvm from command line parameter.
-        self.config_json = config_json
+        # Optional file that contains a json for configuring microvm from
+        # command line parameter.
+        self.config_file = config_file
 
         # The ssh config dictionary is populated with information about how
         # to connect to a microVM that has ssh capability. The path of the
@@ -264,7 +265,7 @@ def spawn(self):
         self.network = Network(self._api_socket, self._api_session)
         self.vsock = Vsock(self._api_socket, self._api_session)
 
-        jailer_param_list = self._jailer.construct_param_list(self.config_json)
+        jailer_param_list = self._jailer.construct_param_list(self.config_file)
 
         # When the daemonize flag is on, we want to clone-exec into the
         # jailer rather than executing it via spawning a shell. Going

tests/integration_tests/functional/test_cmd_line_start.py

@@ -10,10 +10,10 @@
 
 
 @pytest.mark.parametrize(
-    "vm_config_json",
+    "vm_config_file",
     ["framework/vm_config.json"]
 )
-def test_config_json_start(test_microvm_with_ssh, vm_config_json):
+def test_config_json_start(test_microvm_with_ssh, vm_config_file):
     """Start a microvm using configuration sent as command line parameter.
 
     Create resources needed for the configuration of the microvm, then
@@ -34,7 +34,18 @@ def test_config_json_start(test_microvm_with_ssh, vm_config_json):
     test_microvm.create_jailed_resource(log_fifo.path, create_jail=True)
     test_microvm.create_jailed_resource(metrics_fifo.path, create_jail=True)
 
-    test_microvm.config_json = open(vm_config_json).read()
+    # vm_config_file is the source file that keeps the desired vmm
+    # configuration. vm_config_path is the configuration file we
+    # create inside the jail, such that it can be accessed by
+    # firecracker after it starts.
+    vm_config_path = os.path.join(test_microvm.path,
+                                  os.path.basename(vm_config_file))
+    with open(vm_config_file) as f1:
+        with open(vm_config_path, "w") as f2:
+            for line in f1:
+                f2.write(line)
+    test_microvm.create_jailed_resource(vm_config_path, create_jail=True)
+    test_microvm.config_file = os.path.basename(vm_config_file)
     test_microvm.spawn()
 
     response = test_microvm.machine_cfg.get()