README
¶
Guest Agent Command Monitor
Overview
The Guest Agent command monitor is a system used for executing commands in the guest agent on behalf of components in the guest os.
The events layer is formed of a Monitor, a Server and a Handler where the Monitor handles command registration for guest agent components, the Server is the component which listens for events from the gueest os, and the Handler is the function executed by the agent.
Each Handler is identified by a string ID, provided when sending commands to the server. Requests and response to and from the server are structured in JSON format. A request must contain the name field, specifying the handler to be executed. A request may contain arbitrary other fields to be passed to the handler. An example request is below:
{"Name":"agent.ExampleCommand","ArbitraryArgument":123}
A response will be valid JSON and has two required fields: Status and StatusMessage. Status is an int which follows unix status code conventions (ie zero is success, status codes are arbitrary and meaning is defined by the function called) and StatusMessage is an explanatory string accompanying the Status. Two example responses are below.
{"Status":0,"StatusMessage":""}
{"Status":7,"StatusMessage":"Failure message"}
By default, the Server listens on a unix socket or a named pipe, depending on platform. Permissions for the pipe and the pipe path can be set in the guest-agent configuration. The default pipe path for windows and linux systems are \\.\pipe\google-guest-agent-commands non-windows and /run/google-guest-agent/commands.sock respectively.
Implementing a command handler
Registering a command handler will expose the handler function to be called by anyone with write permission to the underlying socket. To do so, call command.Get().RegisterHandler(name, handerFunc) to get the current command monitor and register the handlerFunc with it. Note that if the command system is disabled by user configuration, handler registration will succeed but the server will not be available for callers to send commands to.
Documentation
¶
Overview ¶
Package command facilitates calling commands within the guest-agent.
Index ¶
Constants ¶
const DefaultPipePath = "/run/google-guest-agent/commands.sock"
DefaultPipePath is the default unix socket path for linux.
Variables ¶
var ( // CmdNotFoundError is return when there is no handler for the request command CmdNotFoundError = Response{ Status: 101, StatusMessage: "Could not find a handler for the requested command", } // BadRequestError is returned for invalid or unparseable JSON BadRequestError = Response{ Status: 102, StatusMessage: "Could not parse valid JSON from request", } // ConnError is returned for errors from the underlying communication protocol ConnError = Response{ Status: 103, StatusMessage: "Connection error", } // TimeoutError is returned when the timeout period elapses before valid JSON is receieved TimeoutError = Response{ Status: 104, StatusMessage: "Connection timeout before reading valid request", } // HandlerError is returned when the handler function returns an non-nil error. The status message will be replaced with the returnd error string. HandlerError = Response{ Status: 105, StatusMessage: "The command handler encountered an error processing your request", } // InternalErrorCode is the error code for internal command server errors. Returned when failing to marshal a response. InternalErrorCode = 106 )
Functions ¶
func Close ¶
func Close() error
Close will close the internally managed command server, if it was initialized.
func Init ¶
Init starts an internally managed command server. The agent configuration will decide the server options. Returns a reference to the internally managed command monitor which the caller can Close() when appropriate.
func SendCmdPipe ¶
SendCmdPipe sends a command request over a specific pipe. Most callers should use SendCommand() instead.
Types ¶
type Handler ¶
Handler functions are the business logic of commands. They must process json encoded as a byte slice which contains a Command field and optional arbitrary data, and return json which contains a Status, StatusMessage, and optional arbitrary data (again encoded as a byte slice). Returned errors will be passed onto the command requester.
type Monitor ¶
type Monitor struct {
// contains filtered or unexported fields
}
Monitor is the structure which handles command registration and deregistration.
func Get ¶
func Get() *Monitor
Get returns the current command monitor which can be used to register command handlers.
func (*Monitor) RegisterHandler ¶
RegisterHandler registers f as the handler for cmd. If a command.Server has been initialized, it will be signalled to start listening for commands.
func (*Monitor) UnregisterHandler ¶
UnregisterHandler clears the handlers for cmd. If a command.Server has been intialized and there are no more handlers registered, the server will be signalled to stop listening for commands.
type Request ¶
type Request struct {
Command string
}
Request is the basic request structure. Command determines which handler the request is routed to. Callers may set additional arbitrary fields.
type Response ¶
type Response struct {
// Status code for the request. Meaning is defined by the caller, but
// conventially zero is success.
Status int
// StatusMessage is an optional message defined by the caller. Should generally
// help a human understand what happened.
StatusMessage string
}
Response is the basic response structure. Handlers may set additional arbitrary fields.
Source Files