7 VM_MAKER Command Reference

The vm_maker utility is used to create, destroy, and otherwise manipulate Oracle Linux KVM guests.

7.1 About the vm_maker Utility

You can use the vm_maker command-line utility to administer an Oracle Linux KVM guest.

The vm_maker command-line utility is located on each Oracle Linux KVM host at /opt/exadata_ovm/vm_maker/vm_maker.

Syntax

The general syntax for the vm_maker command is shown here. The following topics describe the individual commands.

vm_maker --command --option [--option ...]

Some commands or options take arguments, such as the guest name. Only enough characters to uniquely identify the guest name are required.

Note:

Oracle Exadata Deployment Assistant (OEDA) contains the OEDA Command Line Interface (OEDACLI), which provides an alternative command-line utility to administer Oracle Linux KVM guests. A primary difference is that OEDACLI can orchestrate operations across multiple guests, while vm_maker is limited to operating on the Oracle Linux KVM host where it resides. Consider your requirements before deciding which utility to use.

7.2 attach Command

Use the --attach command to attach a disk image to a guest.

Syntax

vm_maker --attach --disk-image image_name --domain guest_name

Options

  • --disk-image: The name of the disk image you want to attach.
  • --domain: The name of the guest.

Usage Notes

  • The disk image should exist in /EXAVMIMAGES.
  • A KVM guest can have a maximum of 112 disks attached.

7.3 add-bonded-bridge Command

Use the --add-bonded-bridge command to add a bridge over a bonded Ethernet interface.

Syntax

vm_maker --add-bonded-bridge bridge_name --first-slave slave --second-slave slave 
[ --vlan vlanid ]

Options

  • bridge_name: The name to use for the new bridge. The bridge name must begin with 'vm' followed by an interface name, for example, vmeth1.
  • --first-slave: The first part of the interface pair that comprises the bonded bridge.
  • --second-slave: The second part of the interface pair that comprises the bonded bridge.
  • --vlan: Optionally, specifies the VLAN ID to use for the bonded bridge.

7.4 add-single-bridge Command

Use the --add-single-bridge command to add a bridge over a single Ethernet interface.

Syntax

vm_maker --add-single-bridge bridge_name [ --vlan vlanid ]

Options

  • bridge_name: The name to use for the new bridge. The bridge name must begin with 'vm' followed by an interface name, for example, vmeth1.
  • --vlan: Optionally, specifies the VLAN ID to use for the bridge.

7.5 autostart Command

Use the --autostart command to manage automatic starting of guests.

Syntax

vm_maker --autostart guest_name { --enable | --disable }

Options

  • guest_name: The name of the guest to configure.
  • --enable: Configure the guest to start automatically when the KVM host is started.
  • --disable: Configure the guest so that it does not start automatically when the KVM host is started.

7.6 check Command

Use the --check command to check and display the system configuration status

Syntax

vm_maker --check

7.7 cleanup-ip Command

Use the --cleanup-ip command to remove and clean up a network interface plumbed by the --setup-ip command.

Syntax

vm_maker --cleanup-ip network_interface [ --vlan vlanid ]

Options

  • network_interface: Specifies the name of the network interface to clean up.
  • --vlan: Optionally, specifies the VLAN ID used with the specified network interface.

Example 7-1 Cleaning Up a Network Interface

The following shows an example of using the --cleanup-ip command to remove and clean up a network interface plumbed by the --setup-ip command.

# ping 192.0.2.1
PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data.
From 10.32.106.12 icmp_seq=1 Destination Host Unreachable
^C
--- 192.0.2.1 ping statistics ---
2 packets transmitted, 0 received, +1 errors, 100% packet loss, time 999ms
# /opt/exadata_ovm/vm_maker --setup-ip 192.0.2.6 --interface eth3 --netmask 255.255.255.128 --gateway 192.0.2.1 --vlan 144
[INFO] Interface eth3 currently down
[INFO] Bringing up interface eth3
[INFO] Interface eth3.144 is plumbed.
# ping 192.0.2.1 
PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data.
64 bytes from 192.0.2.1: icmp_seq=2 ttl=255 time=0.317 ms
64 bytes from 192.0.2.1: icmp_seq=3 ttl=255 time=0.302 ms
64 bytes from 192.0.2.1: icmp_seq=4 ttl=255 time=0.307 ms
^C
--- 192.0.2.1 ping statistics ---
4 packets transmitted, 3 received, 25% packet loss, time 3077ms
rtt min/avg/max/mdev = 0.302/0.308/0.317/0.021 ms
# ip rule 
0: from all lookup local 
32757: from 192.0.2.6 to 192.0.2.1 iif eth3.144 lookup main 
32758: from all to 10.32.96.5 lookup 220 
32759: from 10.32.96.5 lookup 220 
32760: from all to 10.32.106.0/23 lookup 210 
32761: from 10.32.106.0/23 lookup 210 
32762: from all to 192.168.0.4 lookup 181 
32763: from 192.168.0.4 lookup 181 
32764: from all to 192.168.0.3 lookup 180 
32765: from 192.168.0.3 lookup 180 
32766: from all lookup main 
32767: from all lookup default 
# ip a s | grep eth3
5: eth3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
67: eth3.144@eth3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
 inet 192.0.2.6/25 scope global eth3.144
# /opt/exadata_ovm/vm_maker --cleanup-ip eth3 --vlan 144
[INFO] Deleting routing rules.
[INFO] Flushing ip-address from interface.
# ip a s | grep eth3
5: eth3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000

7.8 configure-system Command

Use the --configure-system command to configure the system.

Syntax

vm_maker --configure-system [ --no-build-base-image ]

Usage Notes

This command creates /EXAVMIMAGES and creates the virtual functions. If you include the --no-build-base-image option, then vm_maker does not check for the existence of the base image.

7.9 create Command

Use the --create command to create a disk image.

Syntax

vm_maker --create --disk-image image_name [ --size size ] [ --filesystem filesystem_type ] 
  [ --from-zip zipfile ] [ --attach --domain guest_name ]

Options

  • --disk-image: Create a disk image using the name specified.
  • --size: Optionally specifies the size of the image. If not specified, the default size is 50 GB.
  • --filesystem: Specifies the filesystem type to use for the disk image. Allowed filesystem types are: ext3, ext4, and xfs.
  • --from-zip: Indicates the disk image should be created from the specified ZIP file.
  • --attach: Use this option to directly attach the disk image to a guest after creation. If you specify this option, then you must also specify the --domain option.
  • --domain: Use this option to specify which guest to attach the disk image to after creation.

Usage Notes

  • Disk image files are created in /EXAVMIMAGES on the KVM host with a size of 50GB unless another size or unit is provided.
  • A KVM guest can have a maximum of 112 disks attached.

7.10 detach Command

Use the --detach command to detach a disk image from a guest.

Syntax

vm_maker --detach --disk-image image_name --domain guest_name [ --delete ]

Options

  • --disk image: The name of the disk image you want to detach.
  • --domain: The name of the guest from which you want to detach the disk image.
  • --delete: If the disk image is not being used by any other guest, you can include the --delete option to remove the disk image from /EXAVMIMAGES.

7.11 dumpxml Command

Use the --dumpxml command to send the XML definition of the specified guest to standard output.

Syntax

vm_maker --dumpxml guest_name

Usage Notes

You can save the data by piping the output to a file, for example:
# vm_maker --dumpxml guest1.example.com > guest.xml

7.12 list Command

Use the --list command to display information about guests.

Syntax

To view information about disk images:

vm_maker --list --disk-image [ --domain guest_name ]

To view information about guests:

vm_maker --list --domain [ guest_name [ --detail ]] 

To view information about virtual CPU configuration for guests:

vm_maker --list --vcpu [ --domain guest_name ]

To view information about memory configuration for guests:

vm_maker --list --memory [ --domain guest_name ]

Options

  • --disk-image: List all shared disk images in /EXAVMIMAGES.
  • –-domain: List all guests and their status. If you include the guest name, then the information displayed is limited to that guest.
  • --vcpu: List the virtual CPU usage for the entire system.
  • --memory: List the memory usage for the entire system.

Optional Arguments

  • --domain guest_name: Limits the information displayed to a single guest.
  • --detail: Enables detailed output.

7.13 list-domains Command

Use the --list-domains command to list all guests.

Syntax

vm_maker --list-domains

7.14 network-discovery Command

Use the --network-discovery command to identify the network for the Oracle RAC single client access name (SCAN) and other interfaces.

Syntax

vm_maker --network-discovery XML-config-file

Usage Notes

For this command you supply an XML configuration file for the engineered system, such as es.xml.

7.15 reboot Command

Use the --reboot command to restart a specific guest.

Syntax

vm_maker --reboot guest_name

7.16 remove-bridge Command

Use the --remove-bridge command to remove a network bridge.

Syntax

vm_maker --remove-bridge bridge_name [ --vlan vlanid ] [ --force ]

Options

  • bridge_name: The name of the bridge to remove. The bridge name starts with 'vm' and is followed by an interface name, for example, vmeth1.
  • --vlan: Optionally, specifies the VLAN ID for the bridge.
  • --force: Use this option to forcefully remove the bridge.

Usage Notes

A network bridge can be removed only if the bridge is not being used by the KVM host or other guests.

7.17 remove-domain Command

Use the --remove-domain command to stop and remove a specific guest or all guests.

Syntax

vm_maker --remove-domain { guest_name | --all [ --reset-kvmhost ]}

Options

  • guest_name: The name of a specific guest to shutdown and then delete. You can use --all instead of a single guest name if you want to remove all guests.
  • --reset-kvmhost: Resets the system to the state when the KVM host had no guests. This option can only be used when you specify --all for the guest name.

Usage Notes

When you use the --remove-domain command vm_maker forces a shutdown of the guest and deletes it. If -- all is specified for the guest name, then the command shutdowns and deletes all guests and intermediate image files. Underlying network bridges are removed if they are not being used anymore.

If you include the option --reset-kvmhost, then the system is reset to the state it was in before the guests were created.

7.18 set Command

Use the --set command to configure vCPUs or memory for a guest.

Syntax

To configure the number of virtual CPUs for a guest:

vm_maker --set --vcpu vcpu [ --domain guest_name [ --config ] [ --force ]]

To configure the memory for a guest:

vm_maker --set --memory size --domain guest_name [ --restart-domain ] [ --force ]

To configure the MAC for specified Ethernet interface:

vm_maker --set --mac mac_address --interface interface_name [ --restart-domain ]

Options

  • --vcpu: Specifies the number of virtual CPUs for a guest.
  • --memory: Sets the memory size for the specified guest. Memory can be specified using K, M, or G, for example, 40G or 25000M.
  • --mac: Sets the media access control (MAC) address for the specified network interface.
  • –-domain: When used with --vcpu or --memory, this argument indicates that the setting applies to a single guest. Otherwise the setting applies to all guests. You must use --domain when changing the memory size.

  • --config: Indicates that the number of virtual CPUs should not be changed until you restart the guest. This option can only be used when modifying a single guest.
  • --interface: The Ethernet network interface to configure.
  • --restart-domain: Use this option to automatically restart the guest after vm_maker changes the configuration.
  • --force: Forces the new setting to be implemented. This option can only be used when modifying a single guest.

Usage Notes

  • Changing the number of virtual CPUs for a guest happens immediately by default, without restarting the guest.
  • When changing the memory, you must restart the guest before the settings take effect.

7.19 setup-ip Command

Use the --setup-ip command to plumb a network interface on a KVM host.

Syntax

vm_maker --setup-ip ip_address --interface network_interface
  --netmask netmask --gateway gateway_address [ --vlan vlanid ]
vm_maker --setup-ip ip_address --netmask netmask 
  --discover --gateway gateway_address [ --vlan vlanid ]

Options

  • ip_address: Specifies the IP address to use for the network interface.
  • --interface: Specifies the name of the network interface to use.
  • --netmask: Specifies the IP netmask to use for the interface.
  • --gateway: Specifies the IP network gateway address to use for the interface.
  • --vlan: Optionally, specifies the VLAN ID to use for the interface.

Usage Notes

Use the --setup-ip command to plumb a network interface on a KVM host, which you can use for testing and troubleshooting purposes. Use the --cleanup-ip command to remove and clean up the network interface.

Example 7-2 Setting Up a Network Interface

The following shows an example of using the --setup-ip command plumb a network interface and use it to access the network gateway.

# ping 192.0.2.1
PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data.
From 10.32.106.12 icmp_seq=1 Destination Host Unreachable
^C
--- 192.0.2.1 ping statistics ---
2 packets transmitted, 0 received, +1 errors, 100% packet loss, time 999ms
# /opt/exadata_ovm/vm_maker --setup-ip 192.0.2.6 --interface eth3 --netmask 255.255.255.128 --gateway 192.0.2.1 --vlan 144
[INFO] Interface eth3 currently down
[INFO] Bringing up interface eth3
[INFO] Interface eth3.144 is plumbed.
# ping 192.0.2.1 
PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data.
64 bytes from 192.0.2.1: icmp_seq=2 ttl=255 time=0.317 ms
64 bytes from 192.0.2.1: icmp_seq=3 ttl=255 time=0.302 ms
64 bytes from 192.0.2.1: icmp_seq=4 ttl=255 time=0.307 ms
^C
--- 192.0.2.1 ping statistics ---
4 packets transmitted, 3 received, 25% packet loss, time 3077ms
rtt min/avg/max/mdev = 0.302/0.308/0.317/0.021 ms
# ip rule 
0: from all lookup local 
32757: from 192.0.2.6 to 192.0.2.1 iif eth3.144 lookup main 
32758: from all to 10.32.96.5 lookup 220 
32759: from 10.32.96.5 lookup 220 
32760: from all to 10.32.106.0/23 lookup 210 
32761: from 10.32.106.0/23 lookup 210 
32762: from all to 192.168.0.4 lookup 181 
32763: from 192.168.0.4 lookup 181 
32764: from all to 192.168.0.3 lookup 180 
32765: from 192.168.0.3 lookup 180 
32766: from all lookup main 
32767: from all lookup default 
# ip a s | grep eth3
5: eth3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
67: eth3.144@eth3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
 inet 192.0.2.6/25 scope global eth3.144
# /opt/exadata_ovm/vm_maker --cleanup-ip eth3 --vlan 144
[INFO] Deleting routing rules.
[INFO] Flushing ip-address from interface.
# ip a s | grep eth3
5: eth3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000

7.20 start-domain Command

Use the --start-domain command to create and start an Oracle Linux KVM guest.

Syntax

vm_maker --start-domain { guest_name | XML-config-file | --all } [ --no-discovery ]
  [ --keep ] [ --locked ] [ --ssh-key ] [ --console ]

Options

  • guest_name: The name of an existing guest to start.
  • XML-config-file: The full file name of the XML configuration file if creating a new guest.
  • --all: Instead of specifying a single guest or XML configuration file, you can use --all to start all existing domains.
  • --no-discovery: Based on the XML input, when creating the guest, a discovery operation is performed and, if needed, bridges created. If this option is specified, then the discovery operation is skipped.
  • --keep: Indicates that the guest should not be removed even if the first boot fails.
  • --locked: Forces users to choose a new password when they log in for the first time.
  • --ssh-key: If this option is included, then, when the guests are created, the log in for the root user is enabled for the SSH key in the specified file.
  • --console: If this option is included, then vm_maker displays console messages when starting existing guests. If the --locked option is also specified, then root SSH access for the guest is limited to the supplied SSH key.

7.21 stop-domain Command

Use the --stop-domain command to stop the specified Oracle Linux KVM guest.

Syntax

vm_maker --stop-domain { guest_name | --all }

Options

  • guest_name: The name of the guest to stop.
  • --all: Use this option to stop all guests instead of a specific one.

7.22 validate-ip Command

Use the --validate-ip command to validate specified network details for an Oracle Linux KVM guest.

Syntax

vm_maker --validate-ip ip_address --netmask netmask 
  --interface network_interface --gateway gateway_address [ --vlan vlanid ]
vm_maker --validate-ip ip_address --netmask netmask 
  --discover --gateway gateway_address [ --vlan vlanid ]

Options

  • ip_address: Specifies the IP address to use in the validation.
  • --netmask: Specifies the IP netmask to use in the validation.
  • --gateway: Specifies the IP network gateway address to use in the validation.
  • --vlan: Optionally, specifies the VLAN ID to use in the validation.
  • --interface: Instructs vm_maker to perform interface validation and specifies the network interface to use in the validation.
  • --discover: Instructs vm_maker to perform discovery validation.

Usage Notes

Use the --validate-ip command to verify if the provided network details are valid to use for a KVM guest. It can be used for troubleshooting purposes during deployment of KVM guests.

Two types of validation are available:

  • When you use the --interface option, vm_maker validates the specified interface by temporarily plumbing the specified network with the provided details and checking that it can reach the specified gateway.

  • When you use the --discover option, vm_maker temporarily plumbs the specified network with the provided details and discovers the interfaces that are able to reach the specified gateway.

Example 7-3 Interface Validation

The following shows an example of interface validation using the --interface option.

# /opt/exadata_ovm/vm_maker --validate-ip 192.0.2.34 --netmask 255.255.240.0 --interface eth1 --gateway 192.0.2.1
[INFO] Interface eth1 is part of bondeth0. Validating bondeth0.
[INFO] Validating network settings, this can take up to a minute.
[INFO] Interface bondeth0 with ip address 192.0.2.34 and netmask 255.255.240.0 can ping gateway 192.0.2.1

Example 7-4 Discovery Validation

The following shows an example of discovery validation using the --discover option.

# /opt/exadata_ovm/vm_maker --validate-ip 192.0.2.34 --netmask 255.255.240.0 --discover --gateway 192.0.2.1
[INFO] Potential interfaces for discovery: eth0 eth1 eth2 eth3 eth4
[INFO] Discovering interface eth0
[INFO] Discovering interface eth1
[INFO] Discovering interface eth2
[INFO] Discovering interface eth3
[INFO] Discovering interface eth4
[INFO] Interfaces found: eth1 eth2

7.23 vhostmd Command

Use the --vhostmd command to enable, disable, or show the status of the vhostmd service.

Syntax

vm_maker --vhostmd { enable | disable | status }