| // 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 = "tremplin_proto"; |
| |
| // This needs to be duplicated because the gyp rule for building |
| // go code makes it difficult to have imports. |
| message EmptyMessage {} |
| |
| 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]; |
| } |
| |
| // 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 delievered 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 delievered 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 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; |
| } |
| |
| // 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; |
| } |
| |
| 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. |
| // |
| // cicerone/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; |
| } |
| |
| // Name of the container e.g. penguin. |
| string container_name = 1; |
| |
| // Source version to upgrade from. |
| Version source_version = 2; |
| |
| // 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 {} |
| |
| // Tremplin service methods. |
| service Tremplin { |
| rpc CreateContainer(CreateContainerRequest) returns (CreateContainerResponse); |
| rpc DeleteContainer(DeleteContainerRequest) returns (DeleteContainerResponse); |
| rpc StartContainer(StartContainerRequest) returns (StartContainerResponse); |
| 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); |
| |
| // 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 UpdateCreateStatus(ContainerCreationProgress) returns (EmptyMessage); |
| rpc UpdateDeletionStatus(ContainerDeletionProgress) returns (EmptyMessage); |
| rpc UpdateStartStatus(ContainerStartProgress) 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. |
| } |