API: guest

Guest operations through the guest agent (GuestOperationsManager)

POST `/v1/vms/{id}/guest/credentials/acquire`

POST /v1/vms/{id}/guest/credentials/acquire: SOAP AcquireCredentialsInGuest.

CLI: kyvernon vm guest acquire <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestAuthRequest

Name	Type	Description
`interactiveSession`	`boolean` or `null`	Interactive session flag (SOAP parity; ignored).
`password`	`string` or `null`	Guest password (accepted and discarded).
`username`	`string` or `null`	Guest account name (echoed; not verified).

Responses

Status	Description	Schema
200	OK	`GuestAuthView`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/credentials/release`

POST /v1/vms/{id}/guest/credentials/release: SOAP ReleaseCredentialsInGuest.

CLI: kyvernon vm guest release <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestAuthRequest

Name	Type	Description
`interactiveSession`	`boolean` or `null`	Interactive session flag (SOAP parity; ignored).
`password`	`string` or `null`	Guest password (accepted and discarded).
`username`	`string` or `null`	Guest account name (echoed; not verified).

Responses

Status	Description	Schema
204	Released
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/credentials/validate`

POST /v1/vms/{id}/guest/credentials/validate: SOAP ValidateCredentialsInGuest.

CLI: kyvernon vm guest validate <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestAuthRequest

Name	Type	Description
`interactiveSession`	`boolean` or `null`	Interactive session flag (SOAP parity; ignored).
`password`	`string` or `null`	Guest password (accepted and discarded).
`username`	`string` or `null`	Guest account name (echoed; not verified).

Responses

Status	Description	Schema
204	Guest operations are available
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

GET `/v1/vms/{id}/guest/environment`

GET /v1/vms/{id}/guest/environment: SOAP ReadEnvironmentVariableInGuest.

CLI: kyvernon vm guest env <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)
`name`	query	array of `string`		Variable names; empty means the whole environment.

Responses

Status	Description	Schema
200	OK	`GuestEnvView`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/attrs`

POST /v1/vms/{id}/guest/files/attrs: SOAP ChangeFileAttributesInGuest (posix).

CLI: kyvernon vm guest change-attrs <id> --path <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestChangeAttributesRequest

Name	Type	Required	Description
`accessTimeUnix`	`integer` (int64) or `null`		Access time, Unix seconds; omit to leave unchanged.
`groupId`	`integer` (int32) or `null`		Group gid; omit to leave unchanged.
`modificationTimeUnix`	`integer` (int64) or `null`		Modification time, Unix seconds; omit to leave unchanged.
`ownerId`	`integer` (int32) or `null`		Owner uid; omit to leave unchanged.
`path`	`string`	yes	Path in the guest.
`permissions`	`integer` (int64) or `null`		Mode bits as VMware `permissions` (e.g. `420` = `0644`); omit to leave unchanged.

Responses

Status	Description	Schema
204	Done; no body
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/delete`

POST /v1/vms/{id}/guest/files/delete: SOAP DeleteFileInGuest.

CLI: kyvernon vm guest delete-file <id> --path <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestDeleteFileRequest

Name	Type	Required	Description
`path`	`string`	yes	File path in the guest (not a directory).

Responses

Status	Description	Schema
204	Done; no body
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/list`

POST /v1/vms/{id}/guest/files/list: SOAP ListFilesInGuest.

CLI: kyvernon vm guest list-files <id> --path <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestFileListRequest

Name	Type	Required	Description
`index`	`integer` (int32) or `null`		Zero-based start index (default 0).
`matchPattern`	`string` or `null`		Basename regex (`grep -E`); empty / `.*` matches all.
`maxResults`	`integer` (int32) or `null`		Cap on returned entries.
`path`	`string`	yes	Directory or file path in the guest.

Responses

Status	Description	Schema
200	OK	`GuestFileListView`
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/mkdir`

POST /v1/vms/{id}/guest/files/mkdir: SOAP MakeDirectoryInGuest.

CLI: kyvernon vm guest mkdir <id> --path <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestMkdirRequest

Name	Type	Required	Description
`createParents`	`boolean` or `null`		Create missing parents (default false).
`path`	`string`	yes	Directory path in the guest.

Responses

Status	Description	Schema
204	Done; no body
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
409	Conflict: the object exists, or `expectedVersion` is stale	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/move`

POST /v1/vms/{id}/guest/files/move: SOAP MoveFileInGuest.

CLI: kyvernon vm guest move-file <id> --src <path> --dst <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestMoveFileRequest

Name	Type	Required	Description
`dst`	`string`	yes	Destination path in the guest.
`overwrite`	`boolean` or `null`		Replace an existing destination file (default false).
`src`	`string`	yes	Source path in the guest.

Responses

Status	Description	Schema
204	Done; no body
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
409	Conflict: the object exists, or `expectedVersion` is stale	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/move-dir`

POST /v1/vms/{id}/guest/files/move-dir: SOAP MoveDirectoryInGuest.

CLI: kyvernon vm guest move-dir <id> --src <path> --dst <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestMoveDirectoryRequest

Name	Type	Required	Description
`dst`	`string`	yes	Destination directory path in the guest.
`src`	`string`	yes	Source directory path in the guest.

Responses

Status	Description	Schema
204	Done; no body
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
409	Conflict: the object exists, or `expectedVersion` is stale	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/read`

POST /v1/vms/{id}/guest/files/read: SOAP InitiateFileTransferFromGuest (inline bytes).

CLI: kyvernon vm guest read-file <id> --path <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestFileReadRequest

Name	Type	Required	Description
`path`	`string`	yes	Absolute path in the guest.

Responses

Status	Description	Schema
200	OK	`GuestFileReadView`
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/rmdir`

POST /v1/vms/{id}/guest/files/rmdir: SOAP DeleteDirectoryInGuest.

CLI: kyvernon vm guest rmdir <id> --path <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestRmdirRequest

Name	Type	Required	Description
`path`	`string`	yes	Directory path in the guest.
`recursive`	`boolean` or `null`		Remove contents too (default false).

Responses

Status	Description	Schema
204	Done; no body
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/temp-dir`

POST /v1/vms/{id}/guest/files/temp-dir: SOAP CreateTemporaryDirectoryInGuest.

CLI: kyvernon vm guest temp-dir <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestCreateTemporaryRequest

Name	Type	Description
`directoryPath`	`string` or `null`	Parent directory; omit for guest `/tmp`.
`prefix`	`string`	Name prefix (no path separators); may be empty.
`suffix`	`string`	Name suffix (no path separators); may be empty.

Responses

Status	Description	Schema
200	OK	`GuestCreateTemporaryView`
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/temp-file`

POST /v1/vms/{id}/guest/files/temp-file: SOAP CreateTemporaryFileInGuest.

CLI: kyvernon vm guest temp-file <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestCreateTemporaryRequest

Name	Type	Description
`directoryPath`	`string` or `null`	Parent directory; omit for guest `/tmp`.
`prefix`	`string`	Name prefix (no path separators); may be empty.
`suffix`	`string`	Name suffix (no path separators); may be empty.

Responses

Status	Description	Schema
200	OK	`GuestCreateTemporaryView`
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/files/write`

POST /v1/vms/{id}/guest/files/write: SOAP InitiateFileTransferToGuest (inline bytes).

CLI: kyvernon vm guest write-file <id> --path <path> --from <file>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestFileWriteRequest

Name	Type	Required	Description
`dataBase64`	`string`	yes	File content, standard Base64.
`overwrite`	`boolean` or `null`		Replace an existing file (default true).
`path`	`string`	yes	Absolute path in the guest.

Responses

Status	Description	Schema
200	OK	`GuestFileWriteView`
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
409	Conflict: the object exists, or `expectedVersion` is stale	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

GET `/v1/vms/{id}/guest/processes`

GET /v1/vms/{id}/guest/processes: SOAP ListProcessesInGuest.

CLI: kyvernon vm guest list <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)
`pid`	query	array of `integer` (int64)		Process ids to include (repeat or comma-separated); empty means all remembered.

Responses

Status	Description	Schema
200	OK	`GuestProcessListView`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/vms/{id}/guest/processes`

POST /v1/vms/{id}/guest/processes: SOAP StartProgramInGuest.

CLI: kyvernon vm guest start <id> --program <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)

Request body

application/json: GuestStartProgramRequest

Name	Type	Required	Description
`arguments`	`string` or `null`		Arguments as one string (SOAP `GuestProgramSpec.arguments`).
`auth`	`GuestAuthRequest`		Authentication (accepted, not checked).
`envVariables`	array of `string` or `null`		Environment variables (`NAME=value`).
`programPath`	`string`	yes	Absolute path of the program in the guest.
`workingDirectory`	`string` or `null`		Working directory.

Responses

Status	Description	Schema
201	Created	`GuestStartProgramView`
400	Invalid argument; the error body names the field	`ErrorBody`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

DELETE `/v1/vms/{id}/guest/processes/{pid}`

DELETE /v1/vms/{id}/guest/processes/{pid}: SOAP TerminateProcessInGuest.

CLI: kyvernon vm guest terminate <id> <pid>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the virtual machine (`vm-N`)
`pid`	path	`integer` (int64)	yes	Process id in the guest

Responses

Status	Description	Schema
204	Terminated
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`