# vmadm – Manage SmartOS virtual machines and zones

- Synopsis
- Requirements
- Parameters
- Examples
- Return Values
- Status

## Synopsis

- Manage SmartOS virtual machines through vmadm(1M).

## Requirements

The below requirements are needed on the host that executes this module.

- python >= 2.6

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
archive_on_delete - |  | When enabled, the zone dataset will be mounted on `/zones/archive` upon removal.
autoboot - |  | Whether or not a VM is booted when the system is rebooted.
boot - |  | Set the boot order for KVM VMs.

brand
- / required

Choices:
- joyent ←
- joyent-minimal
- kvm
- lx

Type of virtual machine.

cpu_cap - |  | Sets a limit on the amount of CPU time that can be used by a VM. Use `0` for no cap.
cpu_shares - |  | Sets a limit on the number of fair share scheduler (FSS) CPU shares for a VM. This limit is relative to all other VMs on the system.

cpu_type
-

Choices:
- qemu64 ←
- host

Control the type of virtual CPU exposed to KVM VMs.

customer_metadata - |  | Metadata to be set and associated with this VM, this contain customer modifiable keys.
delegate_dataset - |  | Whether to delegate a ZFS dataset to an OS VM.
disk_driver - |  | Default value for a virtual disk model for KVM guests.
disks - |  | A list of disks to add, valid properties are documented in vmadm(1M).
dns_domain - |  | Domain value for `/etc/hosts`.
docker - added in 2.5 |  | Docker images need this flag enabled along with the brand set to `lx`.
filesystems - |  | Mount additional filesystems into an OS VM.
firewall_enabled - |  | Enables the firewall, allowing fwadm(1M) rules to be applied.
force - |  | Force a particular action (i.e. stop or delete a VM).
fs_allowed - |  | Comma separated list of filesystem types this zone is allowed to mount.
hostname - |  | Zone/VM hostname.
image_uuid - |  | Image UUID.
indestructible_delegated - |  | Adds an `@indestructible` snapshot to delegated datasets.
indestructible_zoneroot - |  | Adds an `@indestructible` snapshot to zoneroot.
internal_metadata - |  | Metadata to be set and associated with this VM, this contains operator generated keys.
internal_metadata_namespace - |  | List of namespaces to be set as internal_metadata-only; these namespaces will come from internal_metadata rather than customer_metadata.
kernel_version - |  | Kernel version to emulate for LX VMs.
limit_priv - |  | Set (comma separated) list of privileges the zone is allowed to use.
maintain_resolvers - |  | Resolvers in `/etc/resolv.conf` will be updated when updating the resolvers property.
max_locked_memory - |  | Total amount of memory (in MiBs) on the host that can be locked by this VM.
max_lwps - |  | Maximum number of lightweight processes this VM is allowed to have running.
max_physical_memory - |  | Maximum amount of memory (in MiBs) on the host that the VM is allowed to use.
max_swap - |  | Maximum amount of virtual memory (in MiBs) the VM is allowed to use.
mdata_exec_timeout - |  | Timeout in seconds (or 0 to disable) for the `svc:/smartdc/mdata:execute` service that runs user-scripts in the zone.
name - |  | Name of the VM. vmadm(1M) uses this as an optional name. aliases: alias
nic_driver - |  | Default value for a virtual NIC model for KVM guests.
nics - |  | A list of nics to add, valid properties are documented in vmadm(1M).
nowait - |  | Consider the provisioning complete when the VM first starts, rather than when the VM has rebooted.
qemu_extra_opts - |  | Additional qemu cmdline arguments for KVM guests.
qemu_opts - |  | Additional qemu arguments for KVM guests. This overwrites the default arguments provided by vmadm(1M) and should only be used for debugging.
quota - |  | Quota on zone filesystems (in MiBs).
ram - |  | Amount of virtual RAM for a KVM guest (in MiBs).
resolvers - |  | List of resolvers to be put into `/etc/resolv.conf`.
routes - |  | Dictionary that maps destinations to gateways, these will be set as static routes in the VM.
spice_opts - |  | Addition options for SPICE-enabled KVM VMs.
spice_password - |  | Password required to connect to SPICE. By default no password is set. Please note this can be read from the Global Zone.

state
- / required

Choices:
- present
- absent
- stopped
- restarted

States for the VM to be in. Please note that `present`, `stopped` and `restarted` operate on a VM that is currently provisioned. `present` means that the VM will be created if it was absent, and that it will be in a running state. `absent` will shutdown the zone before removing it. `stopped` means the zone will be created if it doesn't exist already, before shutting it down.

tmpfs - |  | Amount of memory (in MiBs) that will be available in the VM for the `/tmp` filesystem.
uuid - |  | UUID of the VM. Can either be a full UUID or `*` for all VMs.
vcpus - |  | Number of virtual CPUs for a KVM guest.
vga - |  | Specify VGA emulation used by KVM VMs.
virtio_txburst - |  | Number of packets that can be sent in a single flush of the tx queue of virtio NICs.
virtio_txtimer - |  | Timeout (in nanoseconds) for the TX timer of virtio NICs.
vnc_password - |  | Password required to connect to VNC. By default no password is set. Please note this can be read from the Global Zone.
vnc_port - |  | TCP port to listen of the VNC server. Or set `0` for random, or `-1` to disable.
zfs_data_compression - |  | Specifies compression algorithm used for this VMs data dataset. This option only has effect on delegated datasets.
zfs_data_recsize - |  | Suggested block size (power of 2) for files in the delegated dataset's filesystem.
zfs_filesystem_limit - |  | Maximum number of filesystems the VM can have.
zfs_io_priority - |  | IO throttle priority value relative to other VMs.
zfs_root_compression - |  | Specifies compression algorithm used for this VMs root dataset. This option only has effect on the zoneroot dataset.
zfs_root_recsize - |  | Suggested block size (power of 2) for files in the zoneroot dataset's filesystem.
zfs_snapshot_limit - |  | Number of snapshots the VM can have.
zpool - |  | ZFS pool the VM's zone dataset will be created in.

## Examples

    - name: create SmartOS zone
      vmadm:
        brand: joyent
        state: present
        alias: fw_zone
        image_uuid: 95f265b8-96b2-11e6-9597-972f3af4b6d5
        firewall_enabled: yes
        indestructible_zoneroot: yes
        nics:
          - nic_tag: admin
            ip: dhcp
            primary: true
        internal_metadata:
          root_pw: 'secret'
        quota: 1

    - name: Delete a zone
      vmadm:
        alias: test_zone
        state: deleted

    - name: Stop all zones
      vmadm:
        uuid: '*'
        state: stopped

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
alias string | When addressing a VM by alias. | Alias of the managed VM. Sample: dns-zone
state string | success | State of the target, after execution. Sample: running
uuid string | always | UUID of the managed VM. Sample: b217ab0b-cf57-efd8-cd85-958d0b80be33

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Jasper Lievisse Adriaanse (@jasperla)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.