Merge branch 'master' into little_fixes_4

Author: dianpopa

CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## Unreleased
+## [Unreleased]
+
+### Added
+
+- 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

@@ -196,3 +196,9 @@ Possible mitigations are:
   kernel so as to use `vmalloc` instead of `kmalloc` for them.
 - Reduce memory pressure on the host.
 
+### How can I configure and start a microVM without sending API calls?
+
+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

@@ -242,6 +242,29 @@ 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 `--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 --config-file 
+<path_to_the_configuration_file>
+```    
+
+`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.
+
 ## Building From Source
 
 The quickest way to build and test Firecracker is by using our development

docs/jailer.md

@@ -14,6 +14,7 @@ jailer --id <id> \
        [--netns <netns>]
        [--daemonize]
        [--seccomp-level <level>]
+       [--...extra arguments for Firecracker]
 ```
 
 - `id` is the unique VM identification string, which may contain alphanumeric
@@ -38,6 +39,14 @@ jailer --id <id> \
     Firecracker.
   - 2 (default): advanced filtering. This adds further checks on some of the
     parameters of the allowed syscalls.
+- 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
 
@@ -79,8 +88,9 @@ 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>`.
-  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

jailer/src/env.rs

@@ -52,6 +52,7 @@ pub struct Env {
     seccomp_level: u32,
     start_time_us: u64,
     start_time_cpu_us: u64,
+    extra_args: Vec<String>,
 }
 
 impl Env {
@@ -112,6 +113,13 @@ impl Env {
             .parse::<u32>()
             .map_err(Error::SeccompLevel)?;
 
+        let extra_args = args
+            .values_of("extra-args")
+            .into_iter()
+            .flatten()
+            .map(String::from)
+            .collect();
+
         Ok(Env {
             id: id.to_string(),
             numa_node,
@@ -124,6 +132,7 @@ impl Env {
             seccomp_level,
             start_time_us,
             start_time_cpu_us,
+            extra_args,
         })
     }
 
@@ -302,6 +311,7 @@ impl Env {
                 .stderr(Stdio::inherit())
                 .uid(self.uid())
                 .gid(self.gid())
+                .args(self.extra_args)
                 .exec(),
         ))
     }
@@ -323,6 +333,7 @@ mod tests {
         chroot_base: &str,
         netns: Option<&str>,
         daemonize: bool,
+        extra_args: Vec<&str>,
     ) -> ArgMatches<'a> {
         let app = clap_app();
 
@@ -351,6 +362,11 @@ mod tests {
             arg_vec.push("--daemonize");
         }
 
+        arg_vec.push("--");
+        for extra_arg in extra_args {
+            arg_vec.push(extra_arg);
+        }
+
         app.get_matches_from_safe(arg_vec).unwrap()
     }
 
@@ -363,6 +379,7 @@ mod tests {
         let gid = "1002";
         let chroot_base = "/";
         let netns = "zzzns";
+        let extra_args = vec!["--config-file", "config_file_path"];
 
         // This should be fine.
         let good_env = Env::new(
@@ -375,6 +392,7 @@ mod tests {
                 chroot_base,
                 Some(netns),
                 true,
+                extra_args,
             ),
             0,
             0,
@@ -389,11 +407,26 @@ 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.extra_args,
+            vec!["--config-file".to_string(), "config_file_path".to_string()]
+        );
 
         let another_good_env = Env::new(
-            make_args(node, id, exec_file, uid, gid, chroot_base, None, false),
+            make_args(
+                node,
+                id,
+                exec_file,
+                uid,
+                gid,
+                chroot_base,
+                None,
+                false,
+                vec![],
+            ),
             0,
             0,
         )
@@ -402,7 +435,17 @@ mod tests {
 
         // Not fine - invalid node.
         assert!(Env::new(
-            make_args("zzz", id, exec_file, uid, gid, chroot_base, None, true),
+            make_args(
+                "zzz",
+                id,
+                exec_file,
+                uid,
+                gid,
+                chroot_base,
+                None,
+                true,
+                vec![],
+            ),
             0,
             0,
         )
@@ -418,7 +461,8 @@ mod tests {
                 gid,
                 chroot_base,
                 None,
-                true
+                true,
+                vec![],
             ),
             0,
             0
@@ -435,7 +479,8 @@ mod tests {
                 gid,
                 chroot_base,
                 None,
-                true
+                true,
+                vec![],
             ),
             0,
             0
@@ -444,15 +489,35 @@ mod tests {
 
         // Not fine - invalid uid.
         assert!(Env::new(
-            make_args(node, id, exec_file, "zzz", gid, chroot_base, None, true),
+            make_args(
+                node,
+                id,
+                exec_file,
+                "zzz",
+                gid,
+                chroot_base,
+                None,
+                true,
+                vec![],
+            ),
             0,
             0
         )
         .is_err());
 
         // Not fine - invalid gid.
         assert!(Env::new(
-            make_args(node, id, exec_file, uid, "zzz", chroot_base, None, true),
+            make_args(
+                node,
+                id,
+                exec_file,
+                uid,
+                "zzz",
+                chroot_base,
+                None,
+                true,
+                vec![],
+            ),
             0,
             0
         )

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")
@@ -298,6 +299,13 @@ pub fn clap_app<'a, 'b>() -> App<'a, 'b> {
                 .default_value("2")
                 .possible_values(&["0", "1", "2"]),
         )
+        .arg(
+            Arg::with_name("extra-args")
+                .help("Arguments that will be passed verbatim to the exec file.")
+                .required(false)
+                .takes_value(true)
+                .multiple(true),
+        )
 }
 
 fn sanitize_process() {

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;
@@ -108,6 +109,13 @@ fn main() {
                 .takes_value(true)
                 .hidden(true),
         )
+        .arg(
+            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),
+        )
         .get_matches();
 
     let bind_path = cmd_arguments
@@ -142,6 +150,11 @@ fn main() {
             .expect("'start-time-cpu_us' parameter expected to be of 'u64' type.")
     });
 
+    let vmm_config_json = cmd_arguments
+        .value_of("config-file")
+        .map(fs::read_to_string)
+        .map(|x| x.expect("Unable to open or read from the configuration file"));
+
     let shared_info = Arc::new(RwLock::new(InstanceInfo {
         state: InstanceState::Uninitialized,
         id: instance_id,
@@ -156,8 +169,13 @@ fn main() {
         .get_event_fd_clone()
         .expect("Cannot clone API eventFD.");
 
-    let _vmm_thread_handle =
-        vmm::start_vmm_thread(shared_info, api_event_fd, from_api, seccomp_level);
+    let _vmm_thread_handle = vmm::start_vmm_thread(
+        shared_info,
+        api_event_fd,
+        from_api,
+        seccomp_level,
+        vmm_config_json,
+    );
 
     match server.bind_and_run(bind_path, start_time_us, start_time_cpu_us, seccomp_level) {
         Ok(_) => (),

tests/framework/jailer.py

@@ -62,7 +62,7 @@ def __del__(self):
         """Cleanup this jailer context."""
         self.cleanup()
 
-    def construct_param_list(self):
+    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,6 +94,9 @@ def construct_param_list(self):
             jailer_param_list.extend(
                 ['--seccomp-level', str(self.seccomp_level)]
             )
+        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):
@@ -113,16 +116,17 @@ def chroot_path(self):
         """Return the MicroVM chroot path."""
         return os.path.join(self.chroot_base_with_id(), 'root')
 
-    def jailed_path(self, file_path, create=False):
+    def jailed_path(self, file_path, create=False, create_jail=False):
         """Create a hard link owned by uid:gid.
 
         Create a hard link to the specified file, changes the owner to
         uid:gid, and returns a path to the link which is valid within the jail.
         """
         file_name = os.path.basename(file_path)
         global_p = os.path.join(self.chroot_path(), file_name)
+        if create_jail:
+            os.makedirs(self.chroot_path(), exist_ok=True)
         jailed_p = os.path.join("/", file_name)
-
         if create:
             cmd = 'ln -f {} {}'.format(file_path, global_p)
             run(cmd, shell=True, check=True)