firecracker: preparing 0.9.0 release

Updated various doc files, and changed the version number to 0.9.0.

Signed-off-by: Alexandru Agache <[email protected]>

Author: alexandruag

CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.9.0]
+
+### Added
+
+- Seccomp filtering is configured via the `--seccomp-level` jailer parameter.
+- Firecracker logs the starting addresses of host memory areas provided as guest
+memory slots to KVM.
+- The metric `panic_count` gets incremented to signal that a panic has occurred.
+- Firecracker logs a backtrace when it crashes following a panic.
+- Added basic instrumentation support for measuring boot time. 
+
+### Changed
+
+- `StartInstance` is a synchronous API request (it used to be an asynchronous
+request).   
+
+### Fixed
+
+- Ensure that fault messages sent by the API have valid JSON bodies.
+- Use HTTP response code 500 for internal Firecracker errors, and 400 for user
+errors on InstanceStart.
+- Serialize the machine configuration fields to the correct data types (as specified
+in the Swagger definition). 
+- NUMA node assignment is properly enforced by the jailer.
+- The `is_root_device` and `is_read_only` properties are now marked as required
+in the Swagger definition of `Drive` object properties.
+
+### Removed
+
+- `GET` requests on the `/actions` API resource are no longer supported.
+- The metrics associated with asynchronous actions have been removed.
+- Remove the `action_id` parameter for `InstanceStart`, both from the URI and the
+JSON request body.
+
 ## [0.8.0]
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "firecracker"
-version = "0.8.0"
+version = "0.9.0"
 authors = ["Amazon firecracker team <[email protected]>"]
 
 [dependencies]

FAQ.md

@@ -12,14 +12,14 @@ Right now initrd is not supported in Firecracker. You can track the
 `Q2:`
 *Firecracker is not showing any output on the console.*  
 `A2:`
-In order to debug the issue, you will first have to check the output of the GET
-request on Instance Start. You can find examples in
+In order to debug the issue, you will first have to check the response of the
+`InstanceStart` API request. You can find examples in
 [README.md](https://github.com/aws/PRIVATE-firecracker/blob/master/README.md) in
-the "Power-On the MicroVM" section. If the result of the GET is:  
+the "Power-On the MicroVM" section. If the result is:  
 
 - **Error**: Submit a new issue with the label "Support: Failure".
-- **Success**: If the boot was successful, you should see an output like
-  `{"action_type":"InstanceStart"}`.
+- **Success**: If the boot was successful, you should get a response with 204 as
+the status code.
 
 If you have no output in the console, most likely you will have to update the
 kernel command line. By default, Firecracker starts with the serial console

README.md

@@ -33,10 +33,11 @@ The **API endpoint** can be used to:
   - Set a CPU template (the only available template is T2 for now)
   - Enable/Disable hyperthreading (by default hyperthreading is disabled).
     The host needs to be modified before starting Firecracker as this flag
-    only changes the topology inside the microvm.
-- Add one or more network interfaces to the microVM. Firecracker is mapping
-  an existing host file as a VirtIO/block device into the microVM.
+    only changes the topology inside the microVM.
+- Add one or more network interfaces to the microVM. 
 - Add one or more read/write disks (file-backed block devices) to the microVM.
+Firecracker is mapping an existing host file as a VirtIO/block device into the
+microVM.
 - Configure the logging system by:
     - Specifying two named pipes (one for human readable logs and one for the
       metrics).
@@ -86,6 +87,13 @@ The **API endpoint** can be used to:
 
 - The boot-time SLA is enforced in `tests/performance/test-boottime.py`
 
+### Measuring boot time
+
+- Writing the magic value `123` to IO port `0x03f0` triggers a timestamp entry in
+the Firecracker log, which represents the time elapsed since receiving the 
+`InstanceStart` command. This mechanism can be used to measure guest boot-time by
+writing to said IO port very early (ideally as part of init) from the guest.
+
 ## Getting Started
 
 ### Get or Build the Firecracker Binary

api_server/swagger/firecracker.yaml

@@ -4,7 +4,7 @@ info:
   description: RESTful public-facing API.
                The API is accessible through HTTP calls on specific URLs carrying JSON modeled data.
                The transport medium is a Unix Domain Socket.
-  version: 0.8.0
+  version: 0.9.0
   termsOfService: ""
   contact:
     email: "[email protected]"

docs/jailer.md

@@ -6,7 +6,7 @@ The jailer is invoked in this manner:
 
 ``` bash
 jailer --id <id> --node <numa_node> --exec-file <exec_file> --uid <uid> --gid <gid> [--chroot-base-dir <chroot_base>]
-[--netns <netns>] [--daemonize]
+[--netns <netns>] [--daemonize] [--seccomp-level <level>]
 ```
 
 - `id` is the unique VM identification string, which may contain alphanumeric
@@ -24,21 +24,16 @@ jailer --id <id> --node <numa_node> --exec-file <exec_file> --uid <uid> --gid <g
   will use this to join the associated network namespace.
 - When present, the `--daemonize` flag causes the jailer to cal **setsid()** and
   redirect all three standard I/O file descriptors to `/dev/null`.
+- Possible values for `--seccomp-level` are: 0 (disabled - the default value),
+1 (basic filtering), or 2 (advanced filtering). Basic filtering simply prohibits
+syscalls not whitelisted by Firecracker, whereas advanced filtering adds further
+checks on some of the parameters of the allowed syscalls. The filters are installed
+after the jailer execs into Firecracker, but before running any customer code.
 
 ## Jailer Operation
 
 After starting, the Jailer goes through the following operations:
 
-- If the `--secomp-level` flag is set to `1`, sets up a list of seccomp
-  filters, white listing the minimum set of system calls that Firecracker
-  requires to function.
-- If the `--seccomp-level` flag is set to `2`, sets up advanced
-  seccomp filtering. The default action for a syscall is to send `SIGSYS`,
-  unless there is an added rule white listing respective syscall with the given
-  set of arguments. The added rules are the minimum set that Firecracker
-  requires to function.
-- Otherwise if `--seccomp-level` flag is not set or is set to `0`, does not use
-  seccomp filtering.
 - Validate **all provided paths** and the VM `id`.
 - Close all open file descriptors unrelated to standard input.
 - Open `/dev/kvm` as *RW*, and bind a Unix domain socket listener to
@@ -148,8 +143,9 @@ from the controlling terminal. Then, redirect standard file descriptors to `/dev
 because it is no longer necessary.
 
 Finally, the jailer switches the **uid** to ```123```, and **gid** to ```100```, and execs
-`./firecracker --jailed`. We can now use the socket at `/srv/jailer/firecracker/551e7604-e35c-42b3-b825-416853441234/api.socket`
-to interact with the VM.
+`./firecracker --jailed --seccomp-level=<level>`. We can now use the socket at
+`/srv/jailer/firecracker/551e7604-e35c-42b3-b825-416853441234/api.socket` to
+interact with the VM.
 
 ### Observations
 
@@ -166,10 +162,6 @@ to interact with the VM.
   this involves registering handlers with the cgroup **notify_on_release**
   mechanism, while being wary about potential race conditions (the instance
   crashing before the subscription process is complete, for example).
-- Seccomp filtering is currently disabled by default and needs to be enabled by
-  setting the `USE_SECCOMP` environment variable due to a bug in the Linux
-  kernel. Enabling it might cause slowness as a result of an increased number of
-  page faults.
 - For extra resilience, the jailer expects to be spawned by the user in a new PID namespace, most likely via a
 combination of **clone()** with the **CLONE_NEWPID** flag and **exec()**. A process must be created in a new PID
 namespace in order to become a pseudo-init process, and the other option is to use a **clone()** in the jailer,

jailer/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jailer"
-version = "0.8.0"
+version = "0.9.0"
 authors = ["Amazon Firecracker team <[email protected]>"]
 
 [dependencies]