community.general.virtualbox inventory – virtualbox inventory source

Note

This inventory plugin is part of the community.general collection (version 9.4.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.virtualbox.

Synopsis

  • Get inventory hosts from the local virtualbox installation.

  • Uses a YAML configuration file that ends with virtualbox.(yml|yaml) or vbox.(yml|yaml).

  • The inventory_hostname is always the ‘Name’ of the virtualbox instance.

  • Groups can be assigned to the VMs using VBoxManage. Multiple groups can be assigned by using / as a delimeter.

  • A separate parameter, enable_advanced_group_parsing is exposed to change grouping behaviour. See the parameter documentation for details.

Parameters

Parameter

Comments

cache

boolean

Toggle to enable/disable the caching of the inventory’s source data, requires a cache plugin setup to work.

Choices:

  • false ← (default)

  • true

Configuration:

cache_connection

string

Cache connection data or path, read cache plugin documentation for specifics.

Configuration:

cache_plugin

string

Cache plugin to use for the inventory’s source data.

Default: "memory"

Configuration:

cache_prefix

string

Prefix to use for cache plugin files/tables.

Default: "ansible_inventory_"

Configuration:

cache_timeout

integer

Cache duration in seconds.

Default: 3600

Configuration:

compose

dictionary

Create vars from jinja2 expressions.

Default: {}

enable_advanced_group_parsing

boolean

added in community.general 9.2.0

The default group parsing rule (when this setting is set to false) is to split the VirtualBox VM’s group based on the / character and assign the resulting list elements as an Ansible Group.

Setting enable_advanced_group_parsing=true changes this behaviour to match VirtualBox’s interpretation of groups according to https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups. Groups are now split using the , character, and the / character indicates nested groups.

When enabled, a VM that’s been configured using VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2,/TestGroup3" will result in the group TestGroup2 being a child group of TestGroup; and the VM being a part of TestGroup2 and TestGroup3.

Choices:

  • false ← (default)

  • true

groups

dictionary

Add hosts to group based on Jinja2 conditionals.

Default: {}

keyed_groups

list / elements=dictionary

Add hosts to group based on the values of a variable.

Default: []

default_value

string

added in ansible-core 2.12

The default value when the host variable’s value is an empty string.

This option is mutually exclusive with keyed_groups[].trailing_separator.

key

string

The key from input dictionary used to generate groups.

parent_group

string

parent group for keyed group.

prefix

string

A keyed group name will start with this prefix.

Default: ""

separator

string

separator used to build the keyed group name.

Default: "_"

trailing_separator

boolean

added in ansible-core 2.12

Set this option to false to omit the keyed_groups[].separator after the host variable when the value is an empty string.

This option is mutually exclusive with keyed_groups[].default_value.

Choices:

  • false

  • true ← (default)

leading_separator

boolean

added in ansible-core 2.11

Use in conjunction with keyed_groups.

By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.

This is because the default prefix is "" and the default separator is "_".

Set this option to false to omit the leading underscore (or other separator) if no prefix is given.

If the group name is derived from a mapping the separator is still used to concatenate the items.

To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.

Choices:

  • false

  • true ← (default)

network_info_path

string

property path to query for network information (ansible_host)

Default: "/VirtualBox/GuestInfo/Net/0/V4/IP"

plugin

string / required

token that ensures this is a source file for the ‘virtualbox’ plugin

Choices:

  • "virtualbox"

  • "community.general.virtualbox"

query

dictionary

create vars from virtualbox properties

Default: {}

running_only

boolean

toggles showing all vms vs only those currently running

Choices:

  • false ← (default)

  • true

settings_password_file

string

provide a file containing the settings password (equivalent to –settingspwfile)

strict

boolean

If yes make invalid entries a fatal error, otherwise skip and continue.

Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.

Choices:

  • false ← (default)

  • true

use_extra_vars

boolean

added in ansible-core 2.11

Merge extra vars into the available variables for composition (highest precedence).

Choices:

  • false ← (default)

  • true

Configuration:

Examples

# file must be named vbox.yaml or vbox.yml
simple_config_file:
    plugin: community.general.virtualbox
    settings_password_file: /etc/virtulbox/secrets
    query:
      logged_in_users: /VirtualBox/GuestInfo/OS/LoggedInUsersList
    compose:
      ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh')

# add hosts (all match with minishift vm) to the group container if any of the vms are in ansible_inventory'
plugin: community.general.virtualbox
groups:
  container: "'minis' in (inventory_hostname)"

Authors

  • Unknown

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.