| // Copyright 2017 The Chromium OS Authors. All rights reserved. |
| // 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; |
| |
| 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; |
| } |
| |
| // Parameters needed to spawn a container guest. |
| message ConfigureContainerGuestRequest { |
| // Token which cicerone will check to verify that the guest spawned. |
| string container_token = 1; |
| } |
| |
| // 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 { |
| UNKNOWN = 0; |
| USED_BY_TESTS = 1; |
| START_LXD = 2; |
| RESET_LXD_ON_LAUNCH = 3; |
| } |
| // 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; |
| } |
| |
| 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; |
| } |
| |
| // 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; |
| } |
| |
| // 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); |
| |
| // 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); |
| |
| // Prepares to suspend the VM. |
| rpc PrepareToSuspend(EmptyMessage) returns (EmptyMessage); |
| } |