1# toolbox - VMware guest tools library for Go #
2
3## Overview
4
5The toolbox library is a lightweight, extensible framework for implementing VMware guest tools functionality.
6The primary focus of the library is the implementation of VM guest RPC protocols, transport and dispatch.
7These protocols are undocumented for the most part, but [open-vm-tools](https://github.com/vmware/open-vm-tools) serves
8as a reference implementation.  The toolbox provides default implementations of the supported RPCs, which can be
9overridden and/or extended by consumers.
10
11## Supported features
12
13Feature list from the perspective of vSphere public API interaction.  The properties, objects and methods listed are
14relative to
15the [VirtualMachine](http://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.wssdk.apiref.doc%2Fvim.VirtualMachine.html)
16managed object type.
17
18### guest.toolsVersionStatus property
19
20The toolbox reports version as `guestToolsUnmanaged`.
21
22See [ToolsVersionStatus](http://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.wssdk.apiref.doc%2Fvim.vm.GuestInfo.ToolsVersionStatus.html)
23
24### guest.toolsRunningStatus and guest.guestState properties
25
26The VMX determines these values based on the toolbox's response to the `ping` RPC.
27
28### guest.ipAddress property
29
30The VMX requests this value via the `Set_Option broadcastIP` RPC.
31
32The default value can be overridden by setting the `Service.PrimaryIP` function.
33
34See [vim.vm.GuestInfo](http://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.wssdk.apiref.doc%2Fvim.vm.GuestInfo.html)
35
36### guest.net property
37
38This data is pushed to the VMX using the `SendGuestInfo(INFO_IPADDRESS_V3)` RPC.
39
40See [GuestNicInfo](http://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.wssdk.apiref.doc%2Fvim.vm.GuestInfo.NicInfo.html).
41
42### ShutdownGuest and RebootGuest methods
43
44The [PowerCommandHandler](power.go) provides power hooks for customized guest shutdown and reboot.
45
46### GuestAuthManager object
47
48Not supported, but authentication can be customized.
49
50See [vim.vm.guest.AuthManager](http://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.wssdk.apiref.doc%2Fvim.vm.guest.AuthManager.html)
51
52### GuestFileManager object
53
54| Method                          | Supported | Client Examples                                                                     |
55|---------------------------------|-----------|-------------------------------------------------------------------------------------|
56| ChangeFileAttributesInGuest     | Yes       | [chmod](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/chmod.go)       |
57|                                 |           | [chown](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/chown.go)       |
58|                                 |           | [touch](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/touch.go)       |
59| CreateTemporaryDirectoryInGuest | Yes       | [mktemp](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/mktemp.go)     |
60| CreateTemporaryFileInGuest      | Yes       | [mktemp](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/mktemp.go)     |
61| DeleteDirectoryInGuest          | Yes       | [rmdir](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/rmdir.go)       |
62| DeleteFileInGuest               | Yes       | [rm](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/rm.go)             |
63| InitiateFileTransferFromGuest   | Yes       | [download](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/download.go) |
64| InitiateFileTransferToGuest     | Yes       | [upload](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/upload.go)     |
65| ListFilesInGuest                | Yes       | [ls](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/ls.go)             |
66| MakeDirectoryInGuest            | Yes       | [mkdir](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/mkdir.go)       |
67| MoveDirectoryInGuest            | Yes       | [mv](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/mv.go)             |
68| MoveFileInGuest                 | Yes       | [mv](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/mv.go)             |
69
70See [vim.vm.guest.FileManager](http://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.wssdk.apiref.doc%2Fvim.vm.guest.FileManager.html)
71
72### GuestProcessManager
73
74Currently, the `ListProcessesInGuest` and `TerminateProcessInGuest` methods only apply those processes and goroutines
75started by `StartProgramInGuest`.
76
77| Method                         | Supported | Client Examples                                                                     |
78|--------------------------------|-----------|-------------------------------------------------------------------------------------|
79| ListProcessesInGuest           | Yes       | [ps](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/ps.go)             |
80| ReadEnvironmentVariableInGuest | Yes       | [getenv](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/getenv.go)     |
81| StartProgramInGuest            | Yes       | [start](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/start.go)       |
82| TerminateProcessInGuest        | Yes       | [kill](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/kill.go)         |
83
84See [vim.vm.guest.ProcessManager](http://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.wssdk.apiref.doc%2Fvim.vm.guest.ProcessManager.html)
85
86## Extensions
87
88### Authentication
89
90Guest operations can be authenticated using the `toolbox.CommandServer.Authenticate` hook.
91
92### Go functions
93
94The toolbox [ProcessManager](process.go) can manage both OS processes and Go functions running as go routines.
95
96### File handlers
97
98The `hgfs.FileHandler` interface can be used to customize file transfer.
99
100### Process I/O
101
102The toolbox provides support for I/O redirection without the use of disk files within the guest.
103Access to *stdin*, *stdout* and *stderr* streams is implemented as an `hgfs.FileHandler` within the `ProcessManager`.
104
105See [toolbox.Client](https://github.com/vmware/govmomi/blob/master/guest/toolbox/client.go) and
106[govc guest.run](https://github.com/vmware/govmomi/blob/master/govc/vm/guest/run.go)
107
108### http.RoundTripper
109
110Building on top of the process I/O functionality, `toolbox.NewProcessRoundTrip` can be used to start a Go function to
111implement the [http.RoundTripper](https://golang.org/pkg/net/http/#RoundTripper) interface over vmx guest RPC.  This
112makes it possible to use the Go [http.Client](https://golang.org/pkg/net/http/#Client) without network access to the VM
113or to a port that is bound to the guest's loopback address.  It is intended for use with bootstrap configuration for
114example.
115
116### Directory archives
117
118The toolbox provides support for transferring directories to and from guests as gzip'd tar streams, without writing the
119tar file itself to the guest file system.  Archive supports is implemented as an `hgfs.FileHandler` within the `hgfs`
120package.  See [hgfs.NewArchiveHandler](https://github.com/vmware/govmomi/blob/master/toolbox/hgfs/archive.go)
121
122### Linux /proc file access
123
124With standard vmware-tools, the file size is reported as returned by `stat()` and hence a `Content-Length` header of
125size `0`.  The toolbox reports /proc file size as `hgfs.LargePacketMax` to enable transfer of these files.  Note that if
126the file data fits within in `hgfs.LargePacketMax`, the `Content-Length` header will be correct as it is sent after the
127first read by the vmx.  However, if the file data exceeds `hgfs.LargePacketMax`, the `Content-Length` will be
128`hgfs.LargePacketMax`, and client side will truncate to that size.
129
130## Testing
131
132The Go tests cover most of the toolbox code and can be run on any Linux or MacOSX machine, virtual or otherwise.
133
134To test the toolbox with vSphere API interaction, it must be run inside a VM managed by vSphere without the standard
135vmtoolsd running.
136
137The [toolbox-test.sh](toolbox-test.sh) can be used to run the full suite of toolbox tests with vSphere API interaction.
138Use the `-s` flag to start the standalone version of the toolbox and leave it running, to test vSphere interaction
139without running the test suite.
140
141## Consumers of the toolbox library
142
143* [Toolbox example main](https://github.com/vmware/govmomi/blob/master/toolbox/toolbox/main.go)
144
145* [VIC tether toolbox extension](https://github.com/vmware/vic/blob/master/lib/tether/toolbox.go)
146
147* [VIC container VM tether](https://github.com/vmware/vic/blob/main/cmd/tether/main_linux.go)
148
149* [VIC container host tether](https://github.com/vmware/vic/blob/master/cmd/vic-init/main_linux.go)
150
151## Supported guests
152
153The toolbox guest RPC implementations tend to be simple and portable thanks to the Go standard library, but are only
154supported on Linux currently.  Support for other guests, such as Windows, has been kept in mind but not yet tested.
155
156## Supported vSphere Versions
157
158The toolbox is supported with vSphere 6.0 and 6.5, but may function with older versions.
159