Firecracker Snapshot API

openapi: 3.2.0
info:
  title: Firecracker Actions Snapshot API
  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: 1.16.0-dev
  termsOfService: ''
  contact:
    email: firecracker-maintainers@amazon.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: http://localhost/
tags:
- name: Snapshot
paths:
  /snapshot/create:
    put:
      summary: Creates a full or diff snapshot. Post-boot only.
      description: Creates a snapshot of the microVM state. The microVM should be in the `Paused` state.
      operationId: createSnapshot
      responses:
        204:
          description: Snapshot created
        400:
          description: Snapshot cannot be created due to bad input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Snapshot
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SnapshotCreateParams'
        description: The configuration used for creating a snapshot.
        required: true
  /snapshot/load:
    put:
      summary: Loads a snapshot. Pre-boot only.
      description: Loads the microVM state from a snapshot. Only accepted on a fresh Firecracker process (before configuring any resource other than the Logger and Metrics).
      operationId: loadSnapshot
      responses:
        204:
          description: Snapshot loaded
        400:
          description: Snapshot cannot be loaded due to bad input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Snapshot
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SnapshotLoadParams'
        description: The configuration used for loading a snapshot.
        required: true
components:
  schemas:
    SnapshotCreateParams:
      type: object
      required:
      - mem_file_path
      - snapshot_path
      properties:
        mem_file_path:
          type: string
          description: Path to the file that will contain the guest memory.
        snapshot_path:
          type: string
          description: Path to the file that will contain the microVM state.
        snapshot_type:
          type: string
          enum:
          - Full
          - Diff
          description: Type of snapshot to create. It is optional and by default, a full snapshot is created.
    MemoryBackend:
      type: object
      required:
      - backend_type
      - backend_path
      properties:
        backend_type:
          type: string
          enum:
          - File
          - Uffd
        backend_path:
          type: string
          description: Based on 'backend_type' it is either 1) Path to the file that contains the guest memory to be loaded 2) Path to the UDS where a process is listening for a UFFD initialization control payload and open file descriptor that it can use to serve this process's guest memory page faults
    NetworkOverride:
      type: object
      description: Allows for changing the backing TAP device of a network interface during snapshot restore.
      required:
      - iface_id
      - host_dev_name
      properties:
        iface_id:
          type: string
          description: The name of the interface to modify
        host_dev_name:
          type: string
          description: The new host device of the interface
    Error:
      type: object
      properties:
        fault_message:
          type: string
          description: A description of the error condition
          readOnly: true
    SnapshotLoadParams:
      type: object
      description: Defines the configuration used for handling snapshot resume. Exactly one of the two `mem_*` fields must be present in the body of the request.
      required:
      - snapshot_path
      properties:
        enable_diff_snapshots:
          type: boolean
          description: (Deprecated) Enable dirty page tracking to improve space efficiency of diff snapshots
        track_dirty_pages:
          type: boolean
          description: Enable dirty page tracking to improve space efficiency of diff snapshots
        mem_file_path:
          type: string
          description: Path to the file that contains the guest memory to be loaded. It is only allowed if `mem_backend` is not present. This parameter has been deprecated and it will be removed in future Firecracker release.
        mem_backend:
          $ref: '#/components/schemas/MemoryBackend'
          description: Configuration for the backend that handles memory load. If this field is specified, `mem_file_path` is forbidden. Either `mem_backend` or `mem_file_path` must be present at a time.
        snapshot_path:
          type: string
          description: Path to the file that contains the microVM state to be loaded.
        resume_vm:
          type: boolean
          description: When set to true, the vm is also resumed if the snapshot load is successful.
        network_overrides:
          type: array
          description: Network host device names to override
          items:
            $ref: '#/components/schemas/NetworkOverride'
        vsock_override:
          $ref: '#/components/schemas/VsockOverride'
          description: Overrides the vsock device's UDS path on snapshot restore. This is useful for restoring a snapshot with a different socket path than the one used when the snapshot was created. For example, when the original socket path is no longer available or when deploying to a different environment.
        clock_realtime:
          type: boolean
          description: '[x86_64 only] When set to true, passes KVM_CLOCK_REALTIME to KVM_SET_CLOCK on restore, advancing kvmclock by the wall-clock time elapsed since the snapshot was taken. When false (default), kvmclock resumes from where it was at snapshot time. This option may be extended to other clock sources and CPU architectures in the future.'
    VsockOverride:
      type: object
      description: Allows for changing the backing Unix Domain Socket of a vsock device during snapshot restore.
      required:
      - uds_path
      properties:
        uds_path:
          type: string
          description: The new path for the backing Unix Domain Socket.