swagger: '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
host: localhost
basePath: /
schemes:
- http
consumes:
- application/json
produces:
- application/json
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
      parameters:
      - name: body
        in: body
        description: The configuration used for creating a snapshot.
        required: true
        schema:
          $ref: '#/definitions/SnapshotCreateParams'
      responses:
        204:
          description: Snapshot created
        400:
          description: Snapshot cannot be created due to bad input
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Internal server error
          schema:
            $ref: '#/definitions/Error'
      tags:
      - Snapshot
  /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
      parameters:
      - name: body
        in: body
        description: The configuration used for loading a snapshot.
        required: true
        schema:
          $ref: '#/definitions/SnapshotLoadParams'
      responses:
        204:
          description: Snapshot loaded
        400:
          description: Snapshot cannot be loaded due to bad input
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Internal server error
          schema:
            $ref: '#/definitions/Error'
      tags:
      - Snapshot
definitions:
  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.
  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: '#/definitions/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: '#/definitions/NetworkOverride'
      vsock_override:
        $ref: '#/definitions/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.
  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
  Error:
    type: object
    properties:
      fault_message:
        type: string
        description: A description of the error condition
        readOnly: true
  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