Oracle Cloud Infrastructure Documentation

Oracle Linux KVM Image

KVM provides a set of modules that enable you to use the Oracle Linux kernel as a hypervisor to run virtual machines. KVM is built into the Unbreakable Enterprise Kernel (UEK) by default.

The Oracle KVM image includes:

  • the base environment and tools to configure an Oracle Cloud instance as a KVM host for deploying and managing virtual machines
  • utilities to manage the host, guests, storage, and networking configurations required for the environment
Important

Currently, the Oracle image is not intended for use with other virtual management solutions, such as Oracle Linux Virtualization Manager.

If you are new to Oracle Cloud Infrastructure, review the Getting Started section in the Oracle Cloud Infrastructure documentation. You should also have familiarity with managing virtual machine guests using libvirt, in particular virsh and virt-install.

For more information on using KVM with Oracle Linux, see:

Release Information

Learn about the latest features and updates made to the KVM image.

Oracle updates the KVM image regularly with the latest security errata and updates. Oracle updates this document only when new features are added or existing features are modified.

Note

Release 2.0

Release 2.0 introduces the following updates:

  • The base operating system is updated to Oracle Linux 7 Update 9 and Unbreakable Enterprise Kernel Release 6 (UEKR6).
  • The oci-utils package is updated to v0.11.6-9.
  • The Oracle Cloud Marketplace now offers two versions of the Oracle Linux KVM image:

    • Oracle Linux KVM image (Autonomous Linux): This image is configured to run Oracle Autonomous Linux using the standard Oracle Linux repositories. Oracle Autonomous Linux provides autonomous capabilities such as automated Ksplice patching with zero downtime, and known exploit detection, to help keep the instance highly secure and reliable. The Autonomous Linux version of the image is listed in the Oracle Cloud Marketplace as Oracle Linux KVM image (Autonomous Linux).

      For more information about Oracle Autonomous Linux, see Getting Started: Deploying and Configuring Oracle Autonomous Linux on Oracle Cloud Infrastructure and Oracle Autonomous Linux for Oracle Cloud Infrastructure (Oracle Linux Learning Library).

    • Oracle Linux KVM image: The Oracle Linux version of the image is listed in the Oracle Cloud Marketplace as Oracle Linux KVM image. Important

      Future releases of the Oracle Linux KVM image for Oracle Cloud Infrastructure will be configured as Autonomous Linux using the standard Oracle Linux repositories.

Release 1.6

  • The base operating system is updated to Oracle Linux 7 Update 8.
  • The oci-utils packages are updated to v0.11.3-6.
  • OCI utilities have been enhanced to provide multi-VNIC support. For more information, see Using the OCI-KVM Utilities.
  • The Python3 implementation of OCI utilities includes security enhancements for Instance Metadata Service v2.
  • The python36-oci-sdk package installed in the image to provide added functionality for OCI utilities.
  • The Oracle Linux 7 KVM Utilities channel is enabled to provide updates for the qemu-kvm and libvirt packages.

Release 1.5

  • The base operating system is updated to Oracle Linux 7 Update 7.
  • Support for compute shapes have been enhanced to support:
    • Oracle Cloud Infrastructure AMD bare metal (BM) shape.
    • Nested virtualization for Oracle Cloud Infrastructure Intel-based virtual machine (VM) shapes.

    For more information, see Creating a Virtual Machine.

  • New OCI-KVM utilities for Oracle Cloud Infrastructure are included in this release:
    • oci-kvm create-network

      Creates a VNIC virtual network for a KVM guest. Creates a bridged libvirt network on top of a VNIC, allowing a single VNIC to be shared among multiple guests.

    • oci-kvm delete-network

      Deletes a VNIC virtual network for a KVM guest.

    • oci-kvm create-storage-pool

      Creates, mounts, and configures a file system on a block storage device or storage allocated on the Oracle Cloud File Storage Service on Oracle Cloud Infrastructure. Enables the use of a single block disk to host several guest disks.

Release 1.4

  • The base operation system is based on Oracle Linux 7 Update 5.
  • The oci-utils package is updated to version 0.6.
  • The oci-utils package is enhanced to provide the following capabilities:
    • VNIC creation using the oci-network-config --create-vnic command.
    • Block device creation using the oci-iscsi-config --create-volume command.
  • Virtual Function network interfaces are now fully configured using the native Oracle Linux systemd LSB networking (ifcfg network configuration files).

Creating and Connecting to an Instance

See Creating an Instance and Accessing an Instance.

Note

  • You can create Oracle KVM instances using any of the compute shapes. However, AMD processor-based virtual machines do not support nested virtualization. For more information, see Compute Shapes.
  • You can't attach a KVM guest to VLAN 0 on shapes with an active physical NIC 1. However, you can attach KVM guests to the other VLANs on either physical NIC.

Allocating Block Storage and VNICs

Before creating a virtual machine on your KVM instance, you must allocate block storage and VNICs.

Each guest requires a dedicated Oracle Cloud Infrastructure block storage device and VNIC.

Creating and Attaching Block Storage

Using the Console

Use the Oracle Cloud Infrastructure Console to create and attach block storage.

For more information, see Creating a Volume.

  1. Open the navigation menu and click Storage. Under Block Storage, click Block Volumes.
  2. Select Create Block Volume.
  3. Enter a name for your new block volume and click Create Block Volume.
  4. Open the navigation menu and click Compute. Under Compute, click Instances.
  5. In the Instances list, select your KVM instance.
  6. From Instance Details, under Resources click Attached Block Volumes.
  7. In the Attached Block Volumes section, click Attach Block Volume.
  8. From the block volume list, select the block volume you created and click Attach.

    The block volume is created and attached and displays in Attached Block Volumes on the Instance Details page.

Using the CLI

Alternatively, you can use the oci-iscsi-config command to create and attach a block volume.

For more information, see the oci-iscsi-config man page.

  1. Connect to your KVM instance using SSH, for example: 
    ssh –i PRIVATE_KEY_PATH opc@PUBLIC_IP_ADDRESS
  2. Create and attach the volume:
    sudo oci-iscsi-config create --attach-volume --volume-name VOLUME_NAME --size SIZE

    For example, to create and attach volume_001 with a size of 128 GB:

    # oci-iscsi-config create --attach-volume --volume-name volume_001 --size 128
Creating a new 128 GB volume pool_volume_001
Volume [pool_volume_001] created
Attaching the volume to this instance
Attaching iSCSI device.
Volume [pool_volume_001] is attached.

    To verify the configuration:

    # oci-iscsi-config show --details
Currently attached iSCSI devices:
             Target             | Volume name |          Volume OCID           | Persistent portal  |  Current portal  | Session State | Attached device | Size |
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
iqn.2015-12.com.oracleiaas:id...| volume_001  |ocid1.volume.oc1.uk-london-1....|  169.254.2.2:3260  | 169.254.2.2:3260 |   LOGGED_IN   |       sdb       | 128G |
    Note

    If the command fails with: Volume creation has failed: Failed to create volume

    Ensure you have configured API Keys. See Generating an API Signing Key or run oci setup config on the instance.

  3. Optionally, create a storage pool:
    sudo oci-kvm create-pool --disk DEVICE_PATH --name POOL_NAME

    For example, to create a storage pool with the name vm_pool_001 and associating the block volume device sdb:

    # oci-kvm create-pool --disk /dev/sdb --name vm_pool_001
Pool vm_pool_001 successfully created.
    To verify the configuration:
    # oci-kvm list-pool
VM pool Information:
     Name    |        UUID       | Autostart | Active | Persistent | Volumes |  State  |  Capacity  |   Allocation   | Available  |
-----------------------------------------------------------------------------------------------------------------------------------
 vm_pool_001 | [exampleuniqueID] |    yes    |  yes   |    yes     |    0    | running | 127.94 GiB |      32.25 MiB | 127.90 GiB |
    Note

    If the oci-kvm list-pool command is not available, run yum update oci-utils-kvm to update the package to 0.12.6 or later.

Creating and Attaching VNICs

Note

You can create and attach multiple VNICs on an instance. Repeat the following steps as needed to allocate multiple VNICs for your instance.

Using the Console

Use the Oracle Cloud Infrastructure Console to create and attach VNICs.

For more information, see Virtual Network Interface Cards.

  1. Open the navigation menu and click Compute. Under Compute, click Instances.
  2. In the Instances list, select your KVM instance.
  3. From Instance Details, under Resources click Attached VNICs.
  4. In the Attached VNICs section, click Create VNIC.
  5. Enter a name for the VNIC and select a virtual cloud network from the list.
  6. Select a subnet and click Save Changes.

    The VNIC is created and attached and displays in Attached VNICs on the Instance Details page.

  7. To complete the configuration, you may need to connect to the instance and run the script found here: Linux: Configuring the OS for Secondary VNICs.

Using the CLI

Alternatively, you can use the oci-network-config command to create and attach VNICs.

For more information, see the oci-network-config man page.

  1. Connect to your KVM instance using SSH, for example: 
    ssh –i PRIVATE_KEY_PATH opc@PUBLIC_IP_ADDRESS
  2. Create and attach the VNIC:
    sudo oci-network-config attach-vnic --vnic-name VNIC_NAME

    For example, create and attach a VNIC named vnic_kvm_001:

    # oci-network-config attach-vnic --name vnic_kvm_001
Creating VNIC: 10.0.7.45

    To verify the configuration:

    # oci-network-config show --details
Network configuration:
State |    Link    |Status| IP address |     VNIC     |       MAC       |     Hostname     |            Subnet           |  Router IP |Namespace |Index|VLAN tag|    VLAN   |
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  -   |    ens3    |  UP  |  10.0.7.81 |  kvm_demo    |00:00:00:00:00:01|     kvm-demo     |10.0.7.0/25 (All-Regional-...|  10.0.7.1  |    -     |  2  |  3280  |     -     |
  -   |    ens5    |  UP  |  10.0.7.45 | vnic_kvm_001 |00:00:00:00:00:02| kvm-demo-vnic... |10.0.7.0/25 (All-Regional-...|  10.0.7.1  |    -     |  5  |  3316  |     -     |
  -   | virbr0-nic | DOWN |       -    |      -       |00:00:00:00:00:03|        -         |              -              |     -      |    -     |  4  |   -    |     -     |
Operating System level network configuration:
CONFIG      ADDR    SUBNET     BITS VIRTROUTER    NS     IND      IFACE     VLTAG     VLAN    STATE        MAC                          VNIC ID                                         
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
  -     10.0.7.81   10.0.7.0    25   10.0.7.1      -      2        ens3      3280      -        UP  00:00:00:00:00:01 ocid1.vnic.oc1.uk-london-1.[exampleuniqueID] 
  -     10.0.7.45   10.0.7.0    25   10.0.7.1      -      5        ens5      3316      -        UP  00:00:00:00:00:02 ocid1.vnic.oc1.uk-london-1.[exampleuniqueID] 
  -        -           -        -       -          -      4     virbr0-nic    -        -       DOWN 00:00:00:00:00:03
    Note

    If the command fails with: Cannot create the VNIC: Failed to create VNIC: Failed to attach new VNIC:...

    Ensure you have configured API Keys. See Generating an API Signing Key or run oci setup config on the instance.

Working with Virtual Machines

Use the oci-kvm utilities to create and remove virtual machines on your KVM instance.

Creating a Virtual Machine

Use the oci-kvm create command to create a virtual machine.

  1. Before creating a virtual machine, ensure you have allocated block storage and VNICs.
  2. Connect to your KVM instance using SSH, for example: 
    ssh –i PRIVATE_KEY_PATH opc@PUBLIC_IP_ADDRESS

    For more information, see Accessing an Instance.

  3. Select a block storage device for your virtual machine:
    1. Run sudo oci-iscsi-config show --details to show details for all storage attached to your instance.
    2. Choose a device and note the Attached device name (such as sdb).

      When running the create command, you'll use this name when specifying --disk. Add /dev to the path, for example /dev/sdb.

  4. Choose a specific VNIC for your virtual machine:
    1. Run sudo oci-network-config show --details

    2. Choose an appropriate VNIC and note the Link name (such as ens5).

      When running the create command, you'll use this name when specifying the --net option.

      Note

      • Multiple guests cannot not use the same VNIC or block storage device.
      • You can assign a single guest multiple VNICs.
      • You can attach a single host to multiple virtual networks.
  5. Use the oci-kvm create command with any of the available options to create the virtual machine. For more information, see oci-kvm create.

    For example:

    oci-kvm create [-D | --domain VM_NAME] [-d | --diskDEVICE_PATH] 
            [-p | --pool POOL_NAME] [-s | --disk-size DISK_SIZE] 
            [-n | --net VNIC] [-v |--virtual-network VIRTUAL_NETWORK_NAME] 
            [-V | --virt OPT_ARGS]
    Note

    Placing the .iso file within /home/opc can cause permissions issues. Ensure the .iso file is in an accessible location (such as /tmp).

Example using block storage

This example creates a guest using a specific block storage device and a serial console for console output. You can also use other options, such as VNC for console output. If a graphical option is used, you must appropriately configure the Oracle Cloud Infrastructure security list for the subnet this image is attached to.

oci-kvm create -D MY_VM_NAME -d /dev/sdb -V --vcpus 4 --memory 8192 --boot cdrom,hd \
--location /tmp/OracleLinux.iso --nographics --console pty,target_type=serial \
--console pty,target_type=virtio --noautoconsole --os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

Example using a storage pool and VNIC

This example creates a guest using a storage pool and a serial console for console output.

sudo oci-kvm create --domain kvm_vm_001 --pool vm_pool_001 --disk-size 24 --net ens5 \
--virt --vcpus 2 --memory 8192 --boot cdrom,hd --location /isos/OracleLinux.iso --nographics \
--console pty,target_type=serial --console pty,target_type=virtio --noautoconsole \
--os-variant=rhel8.0 --extra-args="console=ttyS0,115200n8"

Example performing a kickstart installation

This example creates a guest using a kickstart file /root/kvm_vm_002_ks.cfg and a serial console for console output.

oci-kvm create --domain kvm_vm_002 --pool vm_pool_001 --disk-size=24 --net ens5 \
--virt --vcpus 2 --memory 8192 --boot cdrom,hd --location /isos/OracleLinux.iso --nographics \
--console pty,target_type=serial --console pty,target_type=virtio --noautoconsole --os-variant=ol7.9 \
--initrd-inject /root/kvm_vm_002_ks.cfg --extra-args="ks=file:kvm_vm_002_ks.cfg console=ttyS0,115200n8"

Example using a storage pool and virtual networks

This example creates a guest using a storage pool, a virtual network, and a serial console for console output. 

oci-kvm create -D MY_VM -p MY_POOL -s 35 -v MYNET0 -V --vcpus 4 --memory 8192 \
--boot cdrom,hd --location /mnt/OracleLinux.iso --nographics --console pty,target_type=serial \
--console pty,target_type=virtio --noautoconsole --os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

Example using storage pool and multiple VNICs

This example creates a guest that is 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.iso --nographics \
--console pty,target_type=serial --console pty,target_type=virtio --noautoconsole \
--os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

Example using storage pool and multiple virtual networks

This example creates a guest using a storage pool, multiple libvirt networks, and a serial console for console output. 

oci-kvm create -D MY_VM -p MY_POOL -s 35 -v MYNET0 -v MYNET1 -V --vcpus 4 \
--memory 8192 --boot cdrom,hd --location /tmp/OracleLinux.iso --nographics \
--console pty,target_type=serial --console pty,target_type=virtio  --noautoconsole \
--os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

Removing a Virtual Machine

Use the oci-kvm destroy command to remove and deconfigure all system resources assigned to the guest virtual machine and make them available for reuse.

  1. Connect to your KVM instance using SSH, for example: 
    ssh –i PRIVATE_KEY_PATH opc@PUBLIC_IP_ADDRESS

    For more information, see Accessing an Instance.

  2. Before you can remove a virtual machine, you must stop it

    virsh destroy VM_NAME

  3. After the virtual machine stops, you can permanently destroy it:

    oci-kvm destroy -D VM_NAME
    For example, to destroy kvm_vm_001:
    $ oci-kvm destroy -D kvm_vm_001
Domain kvm_vm_001 has been undefined

The oci-kvm destroy command undefines the virtual machine in libvirt and cleans up any host resources that were created for it. The Oracle Cloud Infrastructure resources that were allocated to the virtual machine become available for reuse by new virtual machines.

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]

Options

-h | --help
Displays options for the command.
-D | --domain vm_name
Name of the virtual machine.
--destroy-disks
Deletes storage pool-based disks.

Examples

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

oci-kvm destroy -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]

Options

-h | --help
Displays options for the command.
-N | --network-name network_name
The name of the virtual network.

Examples

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

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