1// Copyright 2019 The Chromium OS Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4 5syntax = "proto3"; 6 7package chromiumos.config.api.test.tls; 8 9option go_package = "go.chromium.org/chromiumos/config/go/api/test/tls"; 10 11// Common lab services implemented on top of the wiring APIs. 12// 13// The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 14// NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 15// "OPTIONAL" in this document are to be interpreted as described in 16// RFC 2119. 17// 18// All clients SHOULD pass the gRPC metadata key request_trace_id with one 19// value. The value is a unique string that is associated with the method call 20// in metrics. Clients that do not pass request_trace_id MAY be rejected so that 21// they can be fixed. 22service Common { 23 // ExecDutCommand runs a command on a DUT. 24 // 25 // The working directory is /. 26 // A tty is not spawned for the command. 27 // The user and group is root. 28 // All signals have their default dispositions and are not masked. 29 // The umask is set to 0. 30 // 31 // The environment contains: 32 // 33 // TERM=dumb 34 // PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/bin 35 // LANG=en_US.UTF-8 36 // USER=root 37 // HOME=/root 38 // 39 // The environment MAY also contain SSH client variables. 40 // The environment SHALL NOT contain variables not mentioned above. 41 // 42 // If the stream is interrupted, the implementation MAY attempt to 43 // stop the command by sending SIGINT, SIGHUP, SIGTERM, or SIGKILL. 44 rpc ExecDutCommand(ExecDutCommandRequest) 45 returns (stream ExecDutCommandResponse); 46} 47 48message ExecDutCommandRequest { 49 // name is the resource name for the DUT. 50 // The DUT name is passed to the RTD when the RTD is started. 51 // It is not specified whether the name is the DUT hostname. 52 string name = 1; 53 // command is the command to run. 54 // If this contains no slashes, it is resolved using PATH. 55 // If this starts with /, it is used as an absolute path to the 56 // program to run. 57 // Otherwise, this is treated as a path relative to the working 58 // directory. 59 string command = 2; 60 // args are the arguments to pass to the command. 61 repeated string args = 3; 62 // stdin is passed to the command as the program's stdin. 63 // The stream does not support seeking. 64 // An empty bytes is not treated specially; if the command reads 65 // from stdin, it will receive zero bytes. 66 bytes stdin = 4; 67 // stdout indicates how to handle the command's stdout. 68 Output stdout = 5; 69 // stderr indicates how to handle the command's stderr. 70 Output stderr = 6; 71} 72message ExecDutCommandResponse { 73 message ExitInfo { 74 // status provides information about how the command process 75 // terminated. 76 // 77 // If the command failed to start, status is set to an arbitrary 78 // non-zero value. 79 // 80 // If signaled is set, status is set to the signal that caused 81 // the command to terminate. 82 // 83 // Otherwise, status is set to the exit status of the process. 84 // Exit statuses outside of 0 to 255 inclusive are not supported; 85 // they will be mapped to an arbitrary non-zero value. 86 // 87 // status is zero if and only if the process was successfully 88 // started and exited with a zero status. 89 int32 status = 1; 90 // signaled indicates whether the command exited due to a signal. 91 // If set, status contains the signal. 92 bool signaled = 2; 93 // started indicates whether the command was started. 94 bool started = 3; 95 // error_message provides a human readable explanation for some errors. 96 // This MUST NOT be inspected by programs. 97 string error_message = 4; 98 } 99 // exit_info contains exit information. 100 // This is set when the command has exited or failed to start. 101 // This is set on the last message in the response stream. 102 ExitInfo exit_info = 1; 103 // stdout contains the shell command's stdout output since the last 104 // response in the stream. 105 // The implementation MAY batch or delay output to later 106 // responses in the stream. 107 bytes stdout = 2; 108 // stderr contains the shell command's stderr output since the last 109 // response in the stream. 110 // The implementation MAY batch or delay output to later 111 // responses in the stream. 112 bytes stderr = 3; 113} 114 115// Output enumeration for ExecDutCommandRequest. 116enum Output { 117 // OUTPUT_PIPE means to collect output and return it. 118 OUTPUT_PIPE = 0; 119 // OUTPUT_STDOUT is a special value for stderr which means to merge stderr 120 // into stdout. 121 OUTPUT_STDOUT = 1; 122} 123