github.com/vmware/govmomi@v0.43.0/toolbox/README.md (about)

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