Configuration

Configuration is at the root of vmupdate and as a user you can override virtually all of the utility’s functionality to suit your needs. For most purposes setting up the Credentials will be sufficient. To override the configuration (including Credentials) for specific VM’s see Machines.

You can pass a custom config file as follows:

$ vmupdate --config "/path/to/config/vmupdate.yaml"

Note

Nested keys will be merged, but values will be replaced. Thus, when modifying a list make sure to include any original list items that you wish to keep.

Specification

Credentials

The Credentials section is used for options relating to authentication and access. These options will be used for all VM’s unless specifically overridden (see Machines).

Credentials:
  Username: myuser
  Password: mypass
  Use Keyring: true
  Run As Elevated: true
Username
The username used to authenticate with the VM. Defaults to root.
Password
The password used to authenticate with the VM. Defaults to null.
Use Keyring
Whether to use the host’s keyring to access the password. See Using the Keyring for more details. Defaults to true.
Run As Elevated
Whether to use an elevated user mode when running commands against the VM. This will be required by most guest operating system configurations. Defaults to true.

Warning

Setting a password in plaintext is generally insecure. Use of the keyring is encouraged.

General

The General section is used for miscellaneous options.

General:
  Wait After Start: 30
  Wait Before Stop: 10
Wait After Start
Time in seconds to wait after starting the VM. Defaults to 30.
Wait Before Stop
Time in seconds to wait before stopping the VM. Defaults to 10.

Network

The Network section is used for options relating to SSH endpoints. These are advanced options and generally don’t need to be modified.

Network:
  SSH:
    Guest:
      Port: 22
    Host:
      Ports:
        Min: 49152
        Max: 65535

SSH

Guest Port
SSH port of the guest. Defaults to 22.
Host Ports
Range of ports to be used on the host for forwarding SSH to the guest. Defaults to 49152 - 65535.

Package Managers

The Package Managers section is used for configuring package managers on guest operating systems. These are advanced options and generally don’t need to be modified.

Package Managers:
  Ubuntu:
    apt-get:
      - update -y -u -q
      - upgrade -y -u -q

This example configures the utility to run apt-get with the update and upgrade commands on guests running Ubuntu.

Shells

The Shells section is used for configuring shells for communicating with the guest operating system. These are advanced options and generally don’t need to be modified.

Shells:
  Ubuntu: Posix

This example configures the utility to use the Posix shell to communicate with guests running Ubuntu.

Machines

The Machines section is used for overriding the configuration for specific virtual machines.

Machines:
  My Machine:
    Username: myuser
    Password: mypass
    Use Keyring: true
    Run As Elevated: true
    Shell: Posix
    Ignore: false
Username
The username used to authenticate with the VM.
Password
The password used to authenticate with the VM.
Use Keyring
Whether to use the host’s keyring to access the password. See Using the Keyring for more details.
Run As Elevated
Whether to use an elevated user mode when running commands against the VM. This will be required by most guest operating system configurations.
Shell
Which shell to use for communicating with the guest operating system.
Ignore
Whether to skip the machine for updating. Defaults to false.

My Machine is the name of the virtual machine as listed in the virtualizer.

Virtualizers

The Virtualizers section is used for configuring virtualizers that may be found on the host. These are advanced options and generally don’t need to be modified.

Virtualizers:
  Windows:
    VirtualBox:
      - $PROGRAMW6432\Oracle\VirtualBox\VBoxManage.exe
      - $PROGRAMFILES\Oracle\VirtualBox\VBoxManage.exe

This example configures the utility to search for VirtualBox on Windows hosts at the listed paths. The first path found will be used.

Note

$[ENVAR] in the paths will be expanded using environment variables on the host.

Examples

Using the Keyring

The keyring of your host is the most secure place to store the password(s) used by the utility.

Note

Keyring lookup is by label and username. Both must match to retrieve the password.

General Credentials

In your config file:

Credentials:
  Username: myuser
  Use Keyring: true

Then in your keyring provider, set the password using the label vmupdate and your chosen username. This will act as the default authentication profile for all virtual machine connections.

Machine Credentials

You may have different credentials for a specific machine.

In your config file:

Machines:
  My Machine:
    Username: myuser
    Use Keyring: true

Then in your keyring provider, set the password with the label as your machine name (My Machine in the example). This will override the authentication profile for this machine.