blob: e463475a340cf746f02aa40fcd22631493503d7c [file] [log] [blame]
// Copyright 2018 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 for tremplin, the container springboard service.
package vm_tools.tremplin;
option go_package = "chromiumos/vm_tools/tremplin_proto";
// This needs to be duplicated because the gyp rule for building
// go code makes it difficult to have imports.
message EmptyMessage {}
message StartLxdRequest {
bool reset_lxd_db = 1;
}
message StartLxdResponse {
enum Status {
// The status of creating the container is unknown.
UNKNOWN = 0;
// LXD is starting.
STARTING = 1;
// LXD is already running.
ALREADY_RUNNING = 2;
// Could not launch LXD.
FAILED = 3;
}
// LXD launch status
Status status = 1;
// The failure_reason if LXD could not be started.
string failure_reason = 2;
}
// Sent by tremplin to update the host on the start progress of starting LXD.
message StartLxdProgress {
enum Status {
// The status of creating the container is unknown.
UNKNOWN = 0;
// LXD is starting.
STARTING = 1;
// Something went wrong, Tremplin is trying to recover LXD.
// This is still an in-progress status.
RECOVERING = 2;
// LXD is now running.
STARTED = 3;
// Could not launch LXD.
FAILED = 4;
}
// LXD launch status
Status status = 1;
// The failure_reason if LXD could not be started.
string failure_reason = 2;
}
message CreateContainerRequest {
// Name of the container to start within the VM.
string container_name = 1;
// LXD image server URL. Only simplestreams is supported for now.
string image_server = 2;
// LXD image alias.
string image_alias = 3;
// rootfs path to create the container from.
string rootfs_path = 4;
// metadata path to create the container from.
string metadata_path = 5;
}
message CreateContainerResponse {
enum Status {
// The status of creating the container is unknown.
UNKNOWN = 0;
// The container is now being created. Tremplin will update the caller
// on the result via the UpdateCreateStatus RPC.
CREATING = 1;
// A container with this name already exists.
EXISTS = 2;
// The container could not be created.
FAILED = 3;
}
// Container creation status.
Status status = 1;
// The failure_reason if the container could not be created.
string failure_reason = 2;
}
message DeleteContainerRequest {
// Name of the container to delete.
string container_name = 1;
}
message DeleteContainerResponse {
enum Status {
// The status of deleting the container is unknown
UNKNOWN = 0;
// The container is being deleted.
DELETING = 1;
// The named container doesn't exist.
DOES_NOT_EXIST = 2;
// The container could not be deleted.
FAILED = 3;
}
// Container deletion status.
Status status = 1;
// The failure reason if the container could not be deleted.
string failure_reason = 2;
}
message StartContainerRequest {
// Name of the container to start within the VM.
string container_name = 1;
// SSH public key.
string host_public_key = 2;
// SSH private key.
string container_private_key = 3;
// Container token.
string token = 4;
// Deprecated. All calls are async.
bool async = 5 [deprecated = true];
// Represents the privilege level with which a container should be started. If
// the container is already running this should take effect on the next boot.
enum PrivilegeLevel {
// Don't change the privilege level of the container.
UNCHANGED = 0;
// Make the container unprivileged.
UNPRIVILEGED = 1;
// Make the container privileged.
PRIVILEGED = 2;
}
PrivilegeLevel privilege_level = 6;
}
// OsRelease encapsulates a subset of the os-release info as documented
// at https://www.freedesktop.org/software/systemd/man/os-release.html.
message OsRelease {
// A pretty operating system name in a format suitable for presentation to the
// user. May or may not contain a release code name or OS version of some
// kind, as suitable. (e.g. "Debian GNU/Linux 10 (buster)").
string pretty_name = 1;
// A string identifying the operating system, without a version component,
// and suitable for presentation to the user (e.g. "Debian GNU/Linux").
string name = 2;
// String identifying OS version possibly including release codename.
// (e.g. "10 (buster)").
string version = 3;
// Lower case string (mostly numeric) identifying OS version (e.g. "10").
string version_id = 4;
// Lower case string identifying the operating system (e.g. "debian").
string id = 5;
}
message StartContainerResponse {
enum Status {
// The status of starting the container is unknown.
UNKNOWN = 0;
// The container has started.
STARTED = 1;
// The container was already running.
RUNNING = 2;
// The container could not be started.
FAILED = 3;
// The container is starting. Further updates will be delivered via
// UpdateStartStatus.
STARTING = 4;
// The container is remapping its rootfs uids/gids and will take longer than
// usual to start up. Further updates will be delivered via
// UpdateStartStatus.
REMAPPING = 5;
}
// Container startup status.
Status status = 1;
// The failure_reason if the container could not be started.
string failure_reason = 2;
// OS strings found in the container's /etc/os-release, e.g. "stretch".
OsRelease os_release = 3;
}
message StopContainerRequest {
// Name of the container to stop within the VM.
string container_name = 1;
}
message StopContainerResponse {
enum Status {
// The status of stopping the container is unknown
UNKNOWN = 0;
// The container is already stopped.
STOPPED = 1;
// The container is being stopped.
STOPPING = 2;
// The named container doesn't exist.
DOES_NOT_EXIST = 3;
// The container could not be stopped.
FAILED = 4;
}
// Container stopping status.
Status status = 1;
// The failure reason if the container could not be stopped.
string failure_reason = 2;
}
message GetContainerUsernameRequest {
// Name of the container to get the primary username from.
string container_name = 1;
}
message GetContainerUsernameResponse {
enum Status {
// The result is unknown.
UNKNOWN = 0;
// The primary username is stored in the username field.
SUCCESS = 1;
// A container with the specified name doesn't exist.
CONTAINER_NOT_FOUND = 2;
// The container is not running, so the username could not be found.
CONTAINER_NOT_RUNNING = 3;
// The primary user doesn't exist.
USER_NOT_FOUND = 4;
// Some part of the operation failed.
FAILED = 5;
}
// Status of getting the container's username.
Status status = 1;
// The primary username of the container, if successful.
string username = 2;
// The failure_reason if the username could not be retrieved.
string failure_reason = 3;
// The primary homedir of the container, if successful.
string homedir = 4;
}
message SetUpUserRequest {
// Name of the container to set up.
string container_name = 1;
// Username for the first user in the container.
string container_username = 2;
}
message SetUpUserResponse {
enum Status {
// The status of setting up the user is unknown.
UNKNOWN = 0;
// The user has been set up sucessfully.
SUCCESS = 1;
// The user already exists.
EXISTS = 2;
// Setting up the user failed.
FAILED = 3;
}
// Status of setting up the user.
Status status = 1;
// The failure_reason if the user was not set up successfully.
string failure_reason = 2;
// The primary username of the container, if successful or if user already
// exists. This may be different from container_username in SetUpUserRequest
// if the container already exists, and uid 1000 user has changed username.
string username = 3;
}
message TremplinStartupInfo {}
// Sent by tremplin to update the host on the create progress of a container.
message ContainerCreationProgress {
enum Status {
// Creation status is unknown.
UNKNOWN = 0;
// The container is downloading.
DOWNLOADING = 1;
// The container has been created.
CREATED = 2;
// The container download timed out.
DOWNLOAD_TIMED_OUT = 3;
// The container creation was cancelled.
CANCELLED = 4;
// One or more steps failed and the container could not be created.
FAILED = 5;
}
// The current status of the container.
Status status = 1;
// Name of the container to create within the VM.
string container_name = 2;
// The download progress, if status is DOWNLOADING.
int32 download_progress = 3;
// The failure_reason if the container could not be created.
string failure_reason = 4;
}
// Sent by tremplin to update the host on the deletion of a container.
message ContainerDeletionProgress {
enum Status {
// Deletion status is unknown.
UNKNOWN = 0;
// The container has been deleted.
DELETED = 1;
// The container deletion was cancelled.
CANCELLED = 2;
// One or more steps failed and the container could not be deleted.
FAILED = 3;
}
// The current status of the container.
Status status = 1;
// Name of the container to delete.
string container_name = 2;
// The failure_reason if the container could not be deleted.
string failure_reason = 3;
}
// Sent by tremplin to update the host on the start progress of a container.
message ContainerStartProgress {
enum Status {
// Start status is unknown.
UNKNOWN = 0;
// The container has started.
STARTED = 1;
// The container start was cancelled.
CANCELLED = 2;
// One or more steps failed and the container could not be started.
FAILED = 3;
// Still starting, this is sent as a heartbeat on an interval.
STARTING = 4;
}
// The current status of the container.
Status status = 1;
// Name of the container to start.
string container_name = 2;
// The failure_reason if the container could not be started.
string failure_reason = 3;
}
// Sent by tremplin to update the host on the stopping of a container.
message ContainerStopProgress {
enum Status {
// Stopping status is unknown.
UNKNOWN = 0;
// The container has been stopped.
STOPPED = 1;
// The container is stopping.
STOPPING = 2;
// The container stop was cancelled.
CANCELLED = 3;
// One or more steps failed and the container could not be stopped.
FAILED = 4;
}
// The current status of the container.
Status status = 1;
// Name of the container to stop.
string container_name = 2;
// The failure_reason if the container could not be stopped.
string failure_reason = 3;
}
message GetContainerInfoRequest {
// Name of the container to get information for.
string container_name = 1;
}
message GetContainerInfoResponse {
enum Status {
// The result is unknown.
UNKNOWN = 0;
// The container is currently running.
RUNNING = 1;
// The container is not running.
STOPPED = 2;
// The container with that name doesn't exist.
NOT_FOUND = 3;
// Some part of the operation failed.
FAILED = 4;
}
// Current container status.
Status status = 1;
// The failure_reason if container info could not be returned.
string failure_reason = 2;
// The IPv4 address of the container. This field is only valid if the
// container is running.
fixed32 ipv4_address = 3;
}
message SetTimezoneRequest {
// Timezone name as per values from the timezone-data package in
// /usr/share/zoneinfo.
string timezone_name = 1;
// Timezone properties in POSIX compatible TZ environment variable format
// (see 'man timezone'). Used if the guest VM does not support timezone-data
// timezone names.
//
// brillo/timezone/tzif_parser.h can extract these strings from TZif files.
string posix_tz_string = 2;
// Containers for which we want to set the timezone.
repeated string container_names = 3;
}
message SetTimezoneResponse {
// The number of LXD containers for which the timezone was successfully set.
int32 successes = 1;
// The failure_reason if the request was unsuccessful.
repeated string failure_reasons = 2;
}
message ExportContainerRequest {
// Name of the container to export.
string container_name = 1;
// Path to write the exported container. This path, or a parent
// must have already been shared using seneschal. It is the path relative
// to the VM root mount point (/mnt/shared) as returned in seneschal
// SharePathResponse.path. E.g.: "MyFiles/export". If path is a directory,
// it must already exist, and the export will be named <fingerprint>.tar.gz
// otherwise this path must already exist as a file, or its parent directory
// must exist.
string export_path = 2;
}
message ExportContainerResponse {
enum Status {
// The result is unknown.
UNKNOWN = 0;
// The container has started exporting.
EXPORTING = 1;
// One or more steps failed and the container could not be exported.
FAILED = 2;
}
// Current container status.
Status status = 1;
// Details relating to the failure state.
string failure_reason = 2;
}
message CancelExportContainerRequest {
// Name of the container currently being exported.
string in_progress_container_name = 1;
}
message CancelExportContainerResponse {
enum Status {
// The result is unknown.
UNKNOWN = 0;
// The cancel for the in-progress request has been queued.
// The in-progress request may yet complete before the cancel is processed.
CANCEL_QUEUED = 1;
// No in-progress request was found with that container name.
OPERATION_NOT_FOUND = 2;
}
// The status of the cancellation.
Status status = 1;
}
// Sent by tremplin to update the host on the export progress of a container.
message ContainerExportProgress {
// Name of the container to export.
string container_name = 1;
enum Status {
// The result is unknown.
UNKNOWN = 0;
// Export is completed.
DONE = 1;
// One or more steps failed and the container could not be exported.
FAILED = 2;
// Deprecated. The container is exporting into a tar file.
EXPORTING_TAR = 3 [deprecated = true];
// Deprecated. The container tar file is being compressed into an image
// file.
EXPORTING_COMPRESS = 4 [deprecated = true];
// Deprecated. The exported image file is being downloaded.
EXPORTING_DOWNLOAD = 5 [deprecated = true];
// Deprecated. The exported image file is being packed. This is equivalent
// to tar/compress.
EXPORTING_PACK = 6 [deprecated = true];
// EXPORTING_PACK and EXPORTING_DOWNLOAD have been combined into
// EXPORTING_STREAMING. The exported image file is being tar'd, compressed'd
// and download'd out of the container.
EXPORTING_STREAMING = 7;
// The export has been cancelled.
CANCELLED = 8;
}
// Container status.
Status status = 2;
// Deprecated. Percentage progress for the current stage given in status.
uint32 progress_percent = 3 [deprecated = true];
// Deprecated. Speed (bytes per second) for the current stage given in status.
uint64 progress_speed = 4 [deprecated = true];
// Details relating to the failure state.
string failure_reason = 5;
// Total number of files in the input container.
uint32 total_input_files = 6;
// Total size of the files in the input container.
uint64 total_input_bytes = 7;
// Number of files in the input container that have been downloaded.
uint32 input_files_streamed = 8;
// Size of the files in the input container that have been downloaded.
uint64 input_bytes_streamed = 9;
// Number of compressed bytes that have been exported.
uint64 bytes_exported = 10;
}
message ImportContainerRequest {
// Name of the container to import.
string container_name = 1;
// Path to read the container unified tarball. This is a file which
// must have already been shared using seneschal. It is the path relative
// to the VM root mount point (/mnt/shared) as returned in seneschal
// SharePathResponse.path. E.g.: "MyFiles/export/backup.tar.gz".
string import_path = 2;
// The amount of bytes that this operation can use. Zero means unlimited.
uint64 available_disk_space = 3;
}
message ImportContainerResponse {
enum Status {
// The result is unknown.
UNKNOWN = 0;
// The container is importing. Further updates will be delievered via
// UpdateImportStatus.
IMPORTING = 1;
// One or more steps failed and the container could not be imported.
FAILED = 2;
}
// Current container status.
Status status = 1;
// Details relating to the failure state.
string failure_reason = 2;
}
message CancelImportContainerRequest {
// Name of the container currently being imported.
string in_progress_container_name = 1;
}
message CancelImportContainerResponse {
enum Status {
// The result is unknown.
UNKNOWN = 0;
// The cancel for the in-progress request has been queued.
// The in-progress request may yet complete before the cancel is processed.
CANCEL_QUEUED = 1;
// No in-progress request was found with that container name.
OPERATION_NOT_FOUND = 2;
}
// The status of the cancellation.
Status status = 1;
}
// Sent by tremplin to update the host on the import progress of a container.
message ContainerImportProgress {
// Name of the container to import.
string container_name = 1;
enum Status {
// The result is unknown.
UNKNOWN = 0;
// Import is completed.
DONE = 1;
// One or more steps failed and the container could not be imported.
FAILED = 2;
// The image is being uploaded.
IMPORTING_UPLOAD = 3;
// The image is being unpacked to create a container.
IMPORTING_UNPACK = 4;
// The container could not be imported due to mismatched architecture.
FAILED_ARCHITECTURE = 5;
// The container could not be imported due to insufficient space.
FAILED_SPACE = 6;
// The import has been cancelled.
CANCELLED = 7;
}
// Container status.
Status status = 2;
// Percentage progress for the current stage given in status.
uint32 progress_percent = 3;
// Speed (bytes per second) for the current stage given in status.
uint64 progress_speed = 4;
// Details relating to the failure state.
string failure_reason = 5;
// Architecture of device. Set when status is FAILED_ARCHITECTURE.
string architecture_device = 6;
// Architecture of container which failed to import.
// Set when status is FAILED_ARCHITECTURE.
string architecture_container = 7;
// Disk space available. Set when status is FAILED_SPACE.
uint64 disk_space_available_bytes = 8;
// Disk space required. Set when status is FAILED_SPACE.
uint64 disk_space_required_bytes = 9;
}
// Sent by tremplin to update the host that a container has shutdown.
message ContainerShutdownInfo {
// Name of the container.
string container_name = 1;
}
// Sent by tremplin to update the host on listening ports in containers.
message ListeningPortInfo {
message ContainerPortInfo {
// All IPv4 TCP ports that are currently listening on the loopback
// interface.
repeated uint32 listening_tcp4_ports = 1;
}
// Map of container names to ContainerPortInfo, which contains information
// about listening ports.
map<string, ContainerPortInfo> container_ports = 1;
}
// Sent to Tremplin to start it upgrading a container.
message UpgradeContainerRequest {
enum Version {
// Unknown version.
UNKNOWN = 0;
// Debian 9 AKA Stretch.
DEBIAN_STRETCH = 1;
// Debian 10 AKA Buster.
DEBIAN_BUSTER = 2;
// Debian 11 AKA Bullseye.
DEBIAN_BULLSEYE = 3;
}
// Name of the container e.g. penguin.
string container_name = 1;
// Source version to upgrade from.
// Ignored, since tremplin is in a better place to determine this
// then the caller.
Version source_version = 2 [deprecated = true];
// Version to upgrade to.
Version target_version = 3;
}
// Sent by Tremplin to report the status of an in-progress container upgrade.
message UpgradeContainerResponse {
enum Status {
// The result is unknown.
UNKNOWN = 0;
// Upgrade successfully started.
STARTED = 1;
// An upgrade is already running.
ALREADY_RUNNING = 2;
// Upgrade path not supported e.g. buster->stretch.
NOT_SUPPORTED = 3;
// The container is already at the target version
ALREADY_UPGRADED = 4;
// Failed to start the upgrade for some other reason.
FAILED = 5;
}
// The status.
Status status = 1;
// Human-readable message.
string failure_reason = 2;
}
// Periodically sent by Tremplin to report the status of an active upgrade,
// including being sent once upon completion.
message UpgradeContainerProgress {
enum Status {
// The current status is unknown.
UNKNOWN = 0;
// Still in progress.
IN_PROGRESS = 1;
// Completed successfully.
SUCCEEDED = 2;
// Failed to complete.
FAILED = 3;
}
// Name of the container this progress refers to.
string container_name = 1;
// The current status.
Status status = 2;
// Human-readable messages detailing progress.
repeated string progress_messages = 3;
// Human-readable failure reason if upgrade failed.
string failure_reason = 4;
}
// Request to cancel an in-progress upgrade.
message CancelUpgradeContainerRequest {
// Name of the container to cancel the upgrade on.
string container_name = 1;
}
// The response to trying to cancel an upgrade.
message CancelUpgradeContainerResponse {
enum Status {
// The status is unknown.
UNKNOWN = 0;
// Upgrade was not in progress, nothing to do.
NOT_RUNNING = 1;
// Upgrade cancelled.
CANCELLED = 2;
// Failed to cancel.
FAILED = 3;
}
// The status.
Status status = 1;
// Human-readable failure reason if cancellation failed.
string failure_reason = 2;
}
// Request to inform tremplin that the host network has changed, invalidating
// any connected sockets that were using it.
message HostNetworkChangedRequest {}
// The response to the host network changing.
message HostNetworkChangedResponse {}
// Request for Tremplin to collect and report debug info e.g. additional error
// logs which aren't in syslog, current state.
message GetDebugInfoRequest {}
// The response containing a bunch of debug info.
message GetDebugInfoResponse {
// Debug information in arbitrary format.
string debug_information = 1;
}
// Request Tremplin to attach a USB device on a given port to a container.
message AttachUsbToContainerRequest {
// Attach USB devices on this port.
int32 port_num = 1;
// Name of the container to attach to.
string container_name = 2;
}
message AttachUsbToContainerResponse {
enum Status {
// The status is unknown.
UNKNOWN = 0;
// The USB port will be attached.
OK = 1;
// The container doesn't exist.
NO_SUCH_CONTAINER = 2;
// Failed to attach.
FAILED = 3;
}
// The status.
Status status = 1;
// Human-readable failure reason.
string failure_reason = 2;
}
// Request Tremplin to detach a USB device on a given port from its container.
message DetachUsbFromContainerRequest {
// Detach USB devices on this port.
int32 port_num = 1;
}
message DetachUsbFromContainerResponse {
enum Status {
// The status is unknown.
UNKNOWN = 0;
// The USB port will be detached.
OK = 1;
// Failed to detach.
FAILED = 2;
}
// The status.
Status status = 1;
// Human-readable failure reason.
string failure_reason = 2;
}
// Tremplin service methods.
service Tremplin {
rpc StartLxd(StartLxdRequest) returns (StartLxdResponse);
rpc CreateContainer(CreateContainerRequest) returns (CreateContainerResponse);
rpc DeleteContainer(DeleteContainerRequest) returns (DeleteContainerResponse);
rpc StartContainer(StartContainerRequest) returns (StartContainerResponse);
rpc StopContainer(StopContainerRequest) returns (StopContainerResponse);
rpc GetContainerUsername(GetContainerUsernameRequest)
returns (GetContainerUsernameResponse);
rpc SetUpUser(SetUpUserRequest) returns (SetUpUserResponse);
rpc GetContainerInfo(GetContainerInfoRequest)
returns (GetContainerInfoResponse);
rpc SetTimezone(SetTimezoneRequest) returns (SetTimezoneResponse);
rpc ExportContainer(ExportContainerRequest) returns (ExportContainerResponse);
rpc CancelExportContainer(CancelExportContainerRequest)
returns (CancelExportContainerResponse);
rpc ImportContainer(ImportContainerRequest) returns (ImportContainerResponse);
rpc CancelImportContainer(CancelImportContainerRequest)
returns (CancelImportContainerResponse);
rpc UpgradeContainer(UpgradeContainerRequest)
returns (UpgradeContainerResponse);
rpc CancelUpgradeContainer(CancelUpgradeContainerRequest)
returns (CancelUpgradeContainerResponse);
rpc HostNetworkChanged(HostNetworkChangedRequest)
returns (HostNetworkChangedResponse);
rpc GetDebugInfo(GetDebugInfoRequest) returns (GetDebugInfoResponse);
rpc AttachUsbToContainer(AttachUsbToContainerRequest)
returns (AttachUsbToContainerResponse);
rpc DetachUsbFromContainer(DetachUsbFromContainerRequest)
returns (DetachUsbFromContainerResponse);
// If adding more rpc's, please update ContainerListenerFuzzerSingleAction as
// well.
}
// Service that is notified of events from tremplin.
service TremplinListener {
rpc TremplinReady(TremplinStartupInfo) returns (EmptyMessage);
rpc UpdateStartLxdStatus(StartLxdProgress) returns (EmptyMessage);
rpc UpdateCreateStatus(ContainerCreationProgress) returns (EmptyMessage);
rpc UpdateDeletionStatus(ContainerDeletionProgress) returns (EmptyMessage);
rpc UpdateStartStatus(ContainerStartProgress) returns (EmptyMessage);
rpc UpdateStopStatus(ContainerStopProgress) returns (EmptyMessage);
rpc UpdateExportStatus(ContainerExportProgress) returns (EmptyMessage);
rpc UpdateImportStatus(ContainerImportProgress) returns (EmptyMessage);
rpc ContainerShutdown(ContainerShutdownInfo) returns (EmptyMessage);
rpc UpdateListeningPorts(ListeningPortInfo) returns (EmptyMessage);
rpc UpgradeContainerStatus(UpgradeContainerProgress) returns (EmptyMessage);
// If adding more rpc's, please update ContainerListenerFuzzerSingleAction as
// well.
}