vm_guest.proto

// Copyright 2017 The ChromiumOS Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

option cc_enable_arenas = true;

// This file defines services that will be running in the guest VM.
package vm_tools;

option go_package = "chromiumos/vm_tools/vm_rpc";

import "common.proto";
import "google/protobuf/timestamp.proto";

// Parameters for setting up IPv4 networking inside the VM.  Each parameter
// is stored in network-byte order (for example from the output of inet_pton).
message IPv4Config {
  // IPv4 address for the VM.
  fixed32 address = 1;
  // VM subnet.
  fixed32 netmask = 2;
  // Gateway for sending packets out to the internet.
  fixed32 gateway = 3;
}

// DNS parameters for the VM. These correspond to settings in resolv.conf(5).
message ResolvConfig {
  // The nameservers to use for DNS resolution.
  repeated string nameservers = 1;

  // The search domains for hostname lookup. See resolv.conf(5).
  repeated string search_domains = 2;
}

message NetworkConfigRequest {
  // IPv4 configuration for the VM.
  IPv4Config ipv4_config = 1;

  // DNS configuration for the VM.
  ResolvConfig resolv_config = 2;
}

// Possible states for the host stateful disk to be in.
enum StatefulDiskSpaceState {
  // No value was set.
  DISK_NONE = 0;
  // No action is taken in this state.
  DISK_NORMAL = 1;
  // Prepare applications for impending critical disk space state.
  DISK_LOW = 2;
  // Critical disk space state.
  DISK_CRITICAL = 3;
}

// Request to update the storage balloon according to a stateful disk update.
message UpdateStorageBalloonRequest {
  // What overall state the disk is in.
  StatefulDiskSpaceState state = 1;

  // How many bytes remain free on the host's stateful.
  int64 free_space_bytes = 2;
}

// Possible results of a UpdateStorageBalloonRequest.
enum UpdateStorageBalloonResult {
  // Request worked as intended.
  SUCCESS = 0;
  // Balloon failed to be inflated.
  BALLOON_INFLATE_FAILED = 1;
}

// Response to UpdateStorageBalloonRequest.
message UpdateStorageBalloonResponse {
  // Result of the UpdateStorageBalloonRequest.
  UpdateStorageBalloonResult result = 1;
}

// Parameters needed to spawn a container guest.
message ConfigureContainerGuestRequest {
  // Token which cicerone will check to verify that the guest spawned.
  string container_token = 1;
  // Optional suggested username of the owner of the VM. Only used by
  // VM types that support dynamic usernames.
  string vm_username = 2;
}

// Description of a single process that should be spawned by maitre'd.
message LaunchProcessRequest {
  // Process arguments.  argv[0] must be either an absolute path or the name of
  // an executable program that can be found in the default PATH inside the VM.
  repeated string argv = 1;

  // Any additional environment variables that should be set before spawning
  // the process.  Can be empty.
  map<string, string> env = 2;

  // If |true| the process will be respawned when it exits or is killed.
  // Processes that respawn too frequently will be stopped and will need to be
  // explicitly restarted via a LaunchProcess rpc.  Cannot be true if
  // |wait_for_exit| is true.
  bool respawn = 3;

  // If |true| the process will use /dev/console for its standard I/O.
  // Otherwise all standard I/O is redirected to /dev/null.
  bool use_console = 4;

  // If |true| then maitre'd will wait for the process to exit and include its
  // exit status in the response. Cannot be true if |respawn| is true.
  bool wait_for_exit = 5;
}

// The current status of a process launched via LaunchProcess.
enum ProcessStatus {
  // ¯\_(ツ)_/¯
  UNKNOWN = 0;

  // The process exited normally.
  EXITED = 1;

  // The process was killed by a signal.
  SIGNALED = 2;

  // Successfully launched but may or may not have exited yet.
  LAUNCHED = 3;

  // One or more setup steps failed and the process did not launch.
  FAILED = 4;
}

// Response sent back after maitre'd launches a process.  Will only be filled in
// if the |wait_for_exit| field of the LaunchProcessRequest was set to true.
message LaunchProcessResponse {
  // The status of the launched process.
  ProcessStatus status = 1;

  // If |status| is EXITED then this contains the exit status of the process. If
  // |status| is SIGNALED then this contains the signal number that killed the
  // process.  Otherwise the contents of this field are undefined.
  sint32 code = 2;
}

// Request for maitred to mount a filesystem.
message MountRequest {
  string source = 1;
  string target = 2;
  string fstype = 3;
  uint64 mountflags = 4;
  string options = 5;

  // If |create_target| is true and the |target| directory doesn't exist,
  // maitred creates it. If |target| does exist, this value is ignored.
  bool create_target = 6;

  // If |permissions| is a non-zero value, maitred runs chmod with the value for
  // the mounted directory.
  uint32 permissions = 7;

  // If |mkfs_if_necessary| is true and maitred fails to mount the device,
  // maitred runs mkfs.btrfs to the device and tries to mount it again.
  bool mkfs_if_needed = 8;
}

// Request to mount a 9P filesystem via a vsock socket using the trans=fd
// option.
message Mount9PRequest {
  // The port number on the host where the server is listening for connections.
  uint32 port = 1;

  // The path where the filesystem should be mounted.
  string target = 2;
}

// Response after maitred attempts to mount a filesystem.
message MountResponse {
  sint32 error = 1;
}

// The request protobuf for a StartTermina message. StartTermina requests that
// maitred run all VM guest setup necessary to start containers.
message StartTerminaRequest {
  enum Feature {
    // This list must stay in sync with the one in concierge_service.proto
    UNKNOWN = 0;
    USED_BY_TESTS = 1;
    START_LXD = 2 [deprecated = true];
    RESET_LXD_ON_LAUNCH = 3 [deprecated = true];
    LXD_4_LTS = 4 [deprecated = true];
    LXD_5_LTS = 5;
    // This list must stay in sync with the one in concierge_service.proto
  }
  // The address for tremplin to connect to.
  uint32 tremplin_ipv4_address = 1;

  // The IPv4 address config for LXD. Expected to be in a "xxx.xxx.xxx.xxx/yy"
  // format.
  string lxd_ipv4_subnet = 2;

  // Name of the device containing the stateful partition.
  string stateful_device = 3;

  // Allow termina to support privileged containers.
  bool allow_privileged_containers = 4;

  // Which termina features to enable.
  repeated Feature feature = 5;
}

message StartTerminaResponse {
  enum MountResult {
    // The mountability of the disk is unknown, typically because the
    // call failed before trying to mount the disk.
    UNKNOWN = 0;

    // The disk mount succeeded completely.
    SUCCESS = 1;

    // The disk mount succeeded, but some data loss is
    // likely. Currently this occurrs when the initial mount fails,
    // but succeeds on a retry with -o usebackuproots.
    PARTIAL_DATA_LOSS = 2;

    // The disk is unmountable.
    FAILURE = 3;
  }

  MountResult mount_result = 1;

  // The amount of free space on the stateful partition in bytes. -1 if unable
  // to calculate the amount of free space (e.g. error mounting the partition).
  // Only valid when free_bytes_has_value is true.
  int64 free_bytes = 2;

  // Whether the free_bytes field has been filled in. If false, ignore whatever
  // value is in the field.
  bool free_bytes_has_value = 3;
}

message SetResolvConfigRequest {
  // DNS configuration for the VM.
  ResolvConfig resolv_config = 1;
}

// Protos to update time in guest.
// This RPC is necessary because Linux on ARM does not have paravirtualized
// time, so (especially on resume) there can be significant clock drift as
// compared to the host.  We work around this on ARM by triggering guest clock
// update on resume, using this RPC.
// See https://crbug.com/823406 for details.
message SetTimeRequest {
  // The current time, as seconds and nanos since UTC epoch. (Jan 1, 1970)
  google.protobuf.Timestamp time = 1;
}

message SetTimezoneRequest {
  // Timezone name as per values from the timezone-data package in
  // /usr/share/zoneinfo. Empty string is not a valid input.
  // Examples: UTC, Australia/Melbourne
  string timezone_name = 1;
  // Some applications in the VM may not support chained symlinks (ex. Steam in
  // Linux). In those instances, we need to bind-mount the zoneinfo file
  // directly to /etc/localtime.
  bool use_bind_mount = 2;
}

// Response to GetKernelVersion, containing detailed Termina kernel information
// for enterprise reporting.
message GetKernelVersionResponse {
  string kernel_release = 1;
  string kernel_version = 2;
}

// Request to resize the stateful filesystem to a new size.
// This is an asynchronous request; its state may be queried with
// the GetResizeStatus method.
message ResizeFilesystemRequest {
  // Requested size of the stateful filesystem in bytes.
  uint64 size = 1;
}

// Response to ResizeFilesystemRequest.
message ResizeFilesystemResponse {
  enum ResizeStatus {
    // Could not start the filesystem request due to an error.
    FAILED = 0;

    // Another resize request is already in progress; this request will not be
    // carried out.
    ALREADY_IN_PROGRESS = 1;

    // Resize is started and can be monitored via GetResizeStatus.
    STARTED = 2;
  }

  ResizeStatus status = 1;
}

// Response to GetResizeStatus request.
message GetResizeStatusResponse {
  // True if a resize operation started by ResizeFilesystemRequest is underway.
  bool resize_in_progress = 1;

  // Current size of the stateful partition.
  // If a resize is in progress, this is the size before the resize started.
  uint64 current_size = 2;

  // Final target size of the current resize operation, if one is in progress.
  uint64 target_size = 3;
}

// Response to GetResizeBounds request.
message GetResizeBoundsResponse {
  // Minimum size in bytes that can be passed to ResizeFilesystem.
  uint64 minimum_size = 1;
}

// Response to GetAvailableSpace request.
message GetAvailableSpaceResponse {
  // Available space, in bytes, on the disk.
  uint64 available_space = 1;
}

// Implemented by maitred inside the VM.
service Maitred {
  // Set up networking inside the VM so that it can access the internet.
  rpc ConfigureNetwork(NetworkConfigRequest) returns (EmptyMessage);

  // Set up a container guest in the VM, so that it can interface with cicerone.
  rpc ConfigureContainerGuest(ConfigureContainerGuestRequest)
      returns (EmptyMessage);

  // DEPRECATED. Use OnHostNetworkChanged instead.
  // Reset IPv6 in VM and restart SLAAC process to acquire a new configuration.
  rpc ResetIPv6(EmptyMessage) returns (EmptyMessage);

  // Informs the guest that the host network has changed. The guest should
  // perform any actions necessary, such as resetting potentially stale sockets,
  // flushing DNS caches, and renegotiating SLAAC addresses for IPv6.
  rpc OnHostNetworkChanged(EmptyMessage) returns (EmptyMessage);

  // Initiate a shut-down of the VM.
  rpc Shutdown(EmptyMessage) returns (EmptyMessage);

  // Launch one process inside the VM.
  rpc LaunchProcess(LaunchProcessRequest) returns (LaunchProcessResponse);

  // Mount a filesystem in the VM.
  rpc Mount(MountRequest) returns (MountResponse);

  // Start Termina-specific system services.
  rpc StartTermina(StartTerminaRequest) returns (StartTerminaResponse);

  // Set the VM time to a specified value.
  // If the new time is invalid (roughly 0), ignore it.
  // This RPC is to address cases where the guest loses time for some reason
  // (e.g. due to the host being suspended for a while).
  rpc SetTime(SetTimeRequest) returns (EmptyMessage);

  // Set the VM timezone to a specified value.
  rpc SetTimezone(SetTimezoneRequest) returns (EmptyMessage);

  // Mount a 9P server using a vsock socket.  This uses the trans=fd option
  // when mounting the 9P server, which requires first connecting a socket
  // to the server.  Other transports should use the normal Mount rpc instead.
  rpc Mount9P(Mount9PRequest) returns (MountResponse);

  // Sets the resolv config (nameservers, search domains, and local domain).
  rpc SetResolvConfig(SetResolvConfigRequest) returns (EmptyMessage);

  // Returns the kernel release and version for enterprise reporting.
  rpc GetKernelVersion(EmptyMessage) returns (GetKernelVersionResponse);

  // Resizes the stateful filesystem.
  rpc ResizeFilesystem(ResizeFilesystemRequest)
      returns (ResizeFilesystemResponse);

  // Queries the status of the most recent ResizeFilesystem request.
  rpc GetResizeStatus(EmptyMessage) returns (GetResizeStatusResponse);

  // Gets information about the valid range of parameters to ResizeFilesystem.
  rpc GetResizeBounds(EmptyMessage) returns (GetResizeBoundsResponse);

  // Gets information about unallocated space on a disk.
  rpc GetAvailableSpace(EmptyMessage) returns (GetAvailableSpaceResponse);

  // Prepares to suspend the VM.
  rpc PrepareToSuspend(EmptyMessage) returns (EmptyMessage);

  // Adjusts the disk state of the VM based on the given state. This generally
  // means adjusting the size of the storage balloon and/or other parameters
  // (e.g /proc/sys/dirty_ratio).
  rpc UpdateStorageBalloon(UpdateStorageBalloonRequest)
      returns (UpdateStorageBalloonResponse);
}