Oracle Cloud Infrastructure Documentation

Using the OCI-KVM Utilities

The OCI-KVM (oci-kvm) utilities allow you to create and configure KVM guests on Oracle Cloud Infrastructure instances.

During the automated guest creation process, the utility ensures that Oracle Cloud Infrastructure resources are not assigned to more than one KVM guest. When you no longer need a guest, the utilities can remove the guest and unconfigure all system resources assigned to the guest.

oci-kvm create

Description

  • Performs all actions required to create a KVM guest that uses Oracle Cloud Infrastructure block storage and Oracle Cloud Infrastructure VNICs for both the root disk and network interface.
  • For block storage, validates and checks device to ensure it has not been assigned to another guest. A storage pool can also be used.
  • For virtual network interfaces, creates all virtual network infrastructure, including virtual functions, VLANs, individual block storage devices, and VNICs that are required for each guest.
  • Guests cannot share either a VNIC or a block storage device.
  • Guests can have multiple VNICs assigned and be attached to more than one virtual network.

Usage

oci-kvm create [-h] [-D | --domain vm_name] [-d | --disk device_path] [-p | --pool pool_name] [-s | --disk-size disk_size] [-n | --net ip_vnic] [-v | --virtual-network virtual_network_name] [-V | --virt opt_args]

Options

-h | --help
Displays options for the command.
-D | --domain vm_name
Name of the virtual machine.
-d | --disk device_path
Path to the block device to be used as the root disk of the VM; use with -p | --pool and -s | --disk-size.
-s | --disk-size disk_size
Size of the disk, in gigabytes, to be created when using storage pool; use with -d | --disk and -p | --pool.
-p | --pool pool_name
Name of storage pool to be used for root disk. Use with -d |--disk and -s | --disk-size.
-v | --virtual-network virtual_network_name
The name of libvirt network to attach the guest to; can be repeated to attach guest to multiple networks.
-n | --net ip_vnic
IP or name of the VNIC assigned to the guest; can be repeated to assign multiple VNICs.
-V | --virt optional_arguments
Other optional arguments to provide to virt-install. These arguments are passed unmodified into virt-install, even if they are arguments that oci-kvm would otherwise understand.

Examples

This example shows how to create a guest named MY_VM with a root disk of 128 GB on storage pool named MY_POOL using the 192.168.100.1 VNIC.

oci-kvm create -D MY_VM --disk-size 128 --disk DEVICE_PATH --pool MY_POOL --net
            192.168.100.1 --virt --vcpu 1 --memory 8g --pxe

This example shows how to create an Oracle Linux 7 Update 8 guest configured to use a storage pool, multiple VNICs (two VNICs in this example using the -n option), and a serial console for console output. 

oci-kvm create -D MY_VM -p MY_POOL -s 35
                -n 10.0.0.97 -n 10.0.1.2 -V --vcpus 4 --memory 8192 --boot cdrom,hd --location
                /tmp/OracleLinux-R7-U8-Server-x86_64-dvd.iso --nographics --console
                pty,target_type=serial --console pty,target_type=virtio --noautoconsole
                --os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

oci-kvm destroy

Description

  • Permanently deletes a KVM guest.
  • Optionally deletes the associated storage pool-based disks.

Usage

oci-kvm destroy [-D | --domain vm_name][--destroy-disks] [-f | --force vm_name] [-s | --stop vm_name]

Options

-h | --help
Displays options for the command.
-D | --domain vm_name
Name of the virtual machine.
--destroy-disks
Deletes storage pool-based disks.
-f | --force vm_name
Forces the virtual machine to stop.
-s | --stop vm_name
Stops the virtual machine.

Examples

This example shows how to stop and destroy the MY_VM virtual machine, and delete its associated storage pool-based disks.

oci-kvm destroy -s -D MY_VM --destroy-disks

oci-kvm create-pool

Description

  • Creates a storage pool for hosting guest virtual disks.
  • Pools can be created on block devices or FSS file systems.

Usage

oci-kvm create-pool [-n | --name pool_name][-d | --disk device_path]

oci-kvm create-pool [-n | --name pool_name][-N | --netfshost ip_nfs][-p | --path path_netfs]

Options

-h | --help
Displays options for the command.
-n | --name pool_name
Name of the storage pool.
-d | --disk device_path
Path to the disk where the storage pool is created.
-N | --netfshost ip_nfs
Name or IP of the NFS server where the storage pool is created; use with -p | --path.
-p | --path path_netfs
Path to the NETFS resource; use with -N | --netfshost.

Examples

This example shows how to create a disk-based storage pool on disk /dev/sdb. 

oci-kvm create-pool --disk /dev/sdb

This example shows how to create a NETFS-based storage pool named MY_POOL on NFS resource FileSystem-20201212-1454 on NFS server 192.168.100.1.

oci-kvm create-pool --netfshost 192.168.100.2 --path /FileSystem-20201212-1454 --name MY_POOL

oci-kvm list-pool

Description

Lists the storage pools associated with the instance.

Usage

oci-kvm list-pool [--output-mode mode]

Options

-h | --help
Displays options for the command.
--output-mode mode
Sets the output display mode. For mode, specify either parsable, table, json, or text.

Examples

This example lists the pools in text output mode.

oci-kvm list-pool --output-mode text

oci-kvm create-network

Description

  • Creates a virtual (libvirt) network that uses an Oracle Cloud Infrastructure VNIC.
  • The created libvirt network offers an IP range that is usable by other KVM guests.

Usage

oci-kvm create-network [-n | --net ip_vnic] [-N | --network-name network_name] [-B | --ip-bridge ip_bridge] [-S | --ip-start ip_start] [-E | --ip-end ip_end] [-P | --ip-prefix ip_prefix]

Options

-h | --help
Displays options for the command.
-n | --net ip_vnic
IP of the VNIC used to build the network.
-N | --network-name network_name
Name of the virtual network.
-B | --ip-bridge ip_bridge
Bridge IP for virtual network address space.
-S | --ip-start ip_start
Guest first IP range in virtual network address space.
-E | --ip-end ip_end
Guest last IP range in virtual network address space.
-P | --ip-prefix ip_prefix
IP prefix to be used in virtual network.

Examples

This example shows how to create a virtual network named MYNET0 on a VNIC with 10.0.1.2 as the IP address, a bridge IP of 192.168.100.9, an IP range of 192.168.100.10 - 192.268.100.30, and an IP prefix of 24.

oci-kvm create-network --network-name=MYNET0 --net=10.0.1.2 --ip-bridge=192.168.100.9
            --ip-start=192.168.100.10 --ip-end=192.168.100.30 --ip-prefix=24

oci-kvm delete-network

Description

Deletes a libvirt network previously created with the oci-kvm create-network command.

Usage

oci-kvm delete-network [-N | --network-name network_name][-y | --yes]

Options

-h | --help
Displays options for the command.
-N | --network-name network_name
The name of the virtual network.
-y | --yes
Lets you confirm the deletion of the virtual network, without needing to be prompted.

Examples

This example shows how to delete a virtual network named MYNET0.

oci-kvm delete-network --network-name=MYNET0 -y