blob: 721e358dc2b31c4e5ed99dbd55ec0ca14d5f8a7c [file] [log] [blame]
// 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 = "";
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.
// No action is taken in this state.
// Prepare applications for impending critical disk space state.
// Critical disk space state.
// 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.
// Balloon failed to be inflated.
// 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 {
// ¯\_(ツ)_/¯
// The process exited normally.
// The process was killed by a signal.
// Successfully launched but may or may not have exited yet.
// One or more setup steps failed and the process did not launch.
// 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
START_LXD = 2 [deprecated = true];
RESET_LXD_ON_LAUNCH = 3 [deprecated = true];
LXD_4_LTS = 4 [deprecated = true];
LXD_5_LTS = 5 [deprecated = true];
// 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 ""
// 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.
// The disk mount succeeded completely.
// 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.
// The disk is unmountable.
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 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.
// Another resize request is already in progress; this request will not be
// carried out.
// Resize is started and can be monitored via GetResizeStatus.
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);