Skip to content

How-to Guides

Scope

Task recipes for OpenNebula 7.x (commands checked against the 7.2/7.4 docs): install and evaluate, add hosts, manage VMs, templates, networks, storage and services, enable gRPC and OneDRS, secure the cloud, upgrade, and troubleshoot. Background is in Explanation; ports, drivers and config keys are in Reference.

Run the CLI as the oneadmin system user on the front-end unless a step says otherwise.

Deployment

Evaluate Quickly with miniONE

miniONE builds a single-machine evaluation cloud (front-end, optionally plus one KVM node). Use a fresh server with 4 GiB RAM, 20 GiB disk, root access and openssh-server; ports 22, 80 and 2616 open.

wget 'https://github.com/OpenNebula/minione/releases/latest/download/minione'
sudo bash minione              # front-end + one KVM node
# or: sudo bash minione --frontend   # front-end only

On a VM without hardware virtualization miniONE falls back to QEMU emulation. Do not use it for production.

Deploy Production with OneDeploy (Ansible)

OneDeploy (OpenNebula/one-deploy) is the supported Ansible playbook set for full clouds: local, shared (NFS) or Ceph storage, front-end HA, federation, and front-end-in-a-VM. Follow the reference architectures in the one-deploy wiki; OneForm reuses the same roles when it provisions clusters.

Install a Front-end from Packages (Community Edition)

  1. Add the CE repository (Debian 13 example; replace 7.4 with the target release):

    apt-get update && apt-get -y install gnupg wget apt-transport-https
mkdir -p /etc/apt/keyrings
wget -q -O- https://downloads.opennebula.io/repo/repo2.key \
  | gpg --dearmor --yes --output /etc/apt/keyrings/opennebula.gpg
echo "deb [signed-by=/etc/apt/keyrings/opennebula.gpg] https://downloads.opennebula.io/repo/7.4/Debian/13 stable opennebula" \
  > /etc/apt/sources.list.d/opennebula.list
apt-get update

    On RHEL/AlmaLinux run crb enable, then create /etc/yum.repos.d/opennebula.repo pointing at https://downloads.opennebula.io/repo/7.4/AlmaLinux/$releasever/$basearch (or RedHat/...) with gpgkey=https://downloads.opennebula.io/repo/repo2.key.

  2. Install the front-end packages:

    apt-get -y install opennebula opennebula-fireedge opennebula-gate opennebula-flow
# RHEL/AlmaLinux: yum -y install opennebula opennebula-fireedge opennebula-gate opennebula-flow

  3. Optional: set your own oneadmin password before the first start (otherwise a random one is generated):

    sudo -u oneadmin sh -c "echo 'oneadmin:<choose-a-password>' > /var/lib/one/.one/one_auth"

  4. Set ONEGATE_ENDPOINT in /etc/one/oned.conf to an address your VMs can reach (for example http://<frontend-ip>:5030).

  5. Start and enable the services:

    systemctl enable --now opennebula opennebula-fireedge opennebula-gate opennebula-flow

  6. Verify: oneuser show as oneadmin must print user 0. Sunstone is at http://<frontend>:2616/fireedge/sunstone. If the CLI reports Failed to open TCP connection to localhost:2633, check /var/log/one/oned.log for [E] lines.

Old instructions

Guides that install opennebula-sunstone or start an opennebula-scheduler service are for 6.x. Ruby Sunstone was removed in 7.0 (use opennebula-fireedge), and the scheduler is no longer a separate service in 7.x.

Add a KVM Host

On the host (with the same repository configured):

apt-get -y install opennebula-node-kvm      # or: yum -y install opennebula-node-kvm
systemctl restart libvirtd

Make sure the front-end oneadmin can SSH to the host without a password (the opennebula-ssh-agent service holds the key on the front-end). Then, on the front-end:

onehost create kvm-host-01 -i kvm -v kvm     # long form: --im kvm --vm kvm
onehost list                                  # wait for STAT "on"

For LXC hosts install opennebula-node-lxc and use -i lxc -v lxc.

Commands and Recipes

VM Lifecycle

# Instantiate a VM from a template
onetemplate instantiate "ubuntu-24" --name web-01

# List and inspect
onevm list
onevm show web-01

# Power and state operations
onevm poweroff web-01          # guest off, disks stay on host
onevm resume web-01            # from POWEROFF, SUSPENDED or UNDEPLOYED
onevm suspend web-01           # save memory state on the host (KVM only)
onevm undeploy web-01          # power off and free the host
onevm terminate web-01         # shut down and delete (add --hard to force)

# Live migration (KVM; not available for LXC)
onevm migrate --live web-01 kvm-host-02

# Disk snapshot of disk 0
onevm disk-snapshot-create web-01 0 snap-01

# Hold / release before scheduling
onevm hold web-01
onevm release web-01

onevm shutdown no longer exists

onevm shutdown and onevm delete were replaced by onevm terminate and onevm recover --delete in OpenNebula 5.0.

Template Management

Write the template to a file, then register it:

cat > ubuntu-24.tmpl <<'EOF'
NAME   = "ubuntu-24"
CPU    = 2
VCPU   = 2
MEMORY = 4096
DISK   = [ IMAGE = "Ubuntu 24.04", SIZE = 20480 ]
NIC    = [ NETWORK = "Private" ]
CONTEXT = [ NETWORK = "YES", SSH_PUBLIC_KEY = "$USER[SSH_PUBLIC_KEY]" ]
SCHED_REQUIREMENTS = "HYPERVISOR = kvm"
EOF
onetemplate create ubuntu-24.tmpl
onetemplate list

Host Management

onehost list
onehost show kvm-host-01
onehost top                        # live-refreshing host list
onehost disable kvm-host-01        # stop scheduling new VMs (maintenance)
onehost enable kvm-host-01
onehost sync --force               # push updated driver scripts to hosts

Networking

cat > private.net <<'EOF'
NAME   = "Private"
VN_MAD = "bridge"
BRIDGE = "br0"
AR     = [ TYPE = "IP4", IP = "10.0.0.100", SIZE = "100" ]
EOF
onevnet create private.net
onevnet list

# Add another address range to an existing network
onevnet addar Private --ip 10.0.0.200 --size 10

For VLAN isolation use VN_MAD = "802.1Q" with PHYDEV and VLAN_ID; for overlays use VN_MAD = "vxlan".

Storage

# Ceph image datastore (Ceph Reef 18.2.x or Squid 19.2.x are certified)
cat > ceph-ds.conf <<'EOF'
NAME        = "ceph-ds"
DS_MAD      = "ceph"
TM_MAD      = "ceph"
DISK_TYPE   = "RBD"
POOL_NAME   = "one"
CEPH_HOST   = "ceph-mon1 ceph-mon2 ceph-mon3"
CEPH_USER   = "libvirt"
CEPH_SECRET = "<libvirt-secret-uuid>"
BRIDGE_LIST = "kvm-host-01 kvm-host-02"
EOF
onedatastore create ceph-ds.conf
onedatastore list

# Register a qcow2 image
oneimage create --name "Ubuntu 24.04" \
  --path /var/tmp/ubuntu-24.04.qcow2 \
  --format qcow2 --datastore default
oneimage list

OneFlow Services

oneflow-template create service.json          # service definition (roles, cardinality)
oneflow-template instantiate <template-id>    # creates a running service
oneflow list
oneflow scale <service-id> web 5              # set role "web" cardinality to 5

In 7.x service JSON, roles reference templates with template_id (was vm_template) and inputs with user_inputs (was custom_attrs).

Use the gRPC API (7.2+)

The gRPC server is enabled by default on port 2634 (GRPC_PORT and GRPC_LISTEN_ADDRESS in /etc/one/oned.conf).

onevm list --grpc                    # one-off
export ONEAPI_PROTOCOL=grpc          # make gRPC the CLI default
export ONE_GRPC="10.0.0.10:2634"     # remote endpoint

In HA or federated setups set ENDPOINT_GRPC on every HA server or zone, or gRPC clients fail to route. To point OneFlow at gRPC set :one_xmlrpc: 127.0.0.1:2634 in /etc/one/oneflow-server.conf.

Enable OneDRS on a Cluster

In Sunstone: Infrastructure > Clusters > (cluster) > OneDRS > Enable OneDRS. From the CLI, add an ONE_DRS vector to the cluster template (onecluster update <cluster>):

ONE_DRS = [
  AUTOMATION = "manual",
  POLICY     = "balance",
  CPU_USAGE_WEIGHT = "0.5",
  DISK_WEIGHT      = "0.5" ]

Start with manual, review the recommendations, then move to partial or full. Exclude a VM with ONEDRS_BLOCKED = "YES" in its user template (7.4).

Security Tasks

Create and Apply a Security Group

cat > web-sg.tmpl <<'EOF'
NAME = "web"
RULE = [ PROTOCOL = "TCP", RULE_TYPE = "inbound", RANGE = "80:443" ]
RULE = [ PROTOCOL = "TCP", RULE_TYPE = "inbound", RANGE = "22" ]
RULE = [ PROTOCOL = "ICMP", RULE_TYPE = "inbound" ]
RULE = [ PROTOCOL = "ALL", RULE_TYPE = "outbound" ]
EOF
onesecgroup create web-sg.tmpl

Reference the group from a NIC (NIC = [ NETWORK = "Private", SECURITY_GROUPS = "<id>" ]) or from the virtual network's SECURITY_GROUPS attribute. Rules can also match IP/SIZE or a NETWORK_ID.

Delegate Access with ACLs

oneacl list
# Let group 105 use and manage VMs and networks owned by group 100
oneacl create "@105 VM+NET/@100 USE+MANAGE"
oneacl delete <rule-id>

Harden Sunstone Access

  • Put FireEdge behind a TLS reverse proxy (nginx or Apache) and expose only 443; keep 2616 bound to the proxy.
  • Enforce two-factor authentication globally (7.2+, see the Sunstone authentication docs).
  • Configure LDAP or SAML (7.0.1+; SAML must be enabled in oned.conf) for human users.

The full list is in Reference: Hardening Checklist.

Upgrade

The upgrade tools (onedb, onecfg) ship in the opennebula-migration package, which is part of the Community Edition since 7.0.

  1. Read the Compatibility Guide of every version you skip (for 7.2 to 7.4: Sunstone redesign, round-robin address leases, Veeam architecture, logrotate changes).

  2. Stop the services and back up the database and configuration:

    systemctl stop opennebula opennebula-fireedge opennebula-gate opennebula-flow
onedb backup /var/lib/one/backups/one-$(date +%Y%m%d).sql
cp -a /etc/one /etc/one.bak-$(date +%Y%m%d)

  3. Point the repository at the new version and upgrade the packages on front-ends and hosts.

  4. Upgrade configuration and database, then check consistency:

    onecfg upgrade
onedb upgrade -v
onedb fsck

  5. Start the services and run onehost sync --force so hosts get the new drivers.

7.4 known issue

A package upgrade overwrites a customized /var/lib/one/remotes/hooks/ft/fence_host.sh. Restore it from /var/lib/one/backups/config/<timestamp>-v<previous version>/ after upgrading if you use host fencing.

Monitoring and Logs

systemctl status opennebula opennebula-fireedge
tail -f /var/log/one/oned.log            # core daemon, look for [E]
tail -f /var/log/one/<vm-id>.log         # per-VM log (also visible in Sunstone since 7.2)
onevm top                                # live VM list
onedb fsck                               # DB check: stop oned first, or use the 6.10+ dry-run flag (onedb fsck --help)

For metrics, install opennebula-prometheus (front-end) and opennebula-prometheus-kvm (hosts) to get the bundled Prometheus and Grafana dashboards.

Troubleshooting

Symptom Check Fix
VM stays PENDING onevm show <id> (scheduler message), onehost list capacity Loosen SCHED_REQUIREMENTS; check cluster/datastore compatibility ("Incompatible cluster IDs"); add capacity
Host in err state onehost show <id>, SSH from front-end as oneadmin Fix SSH/libvirt on the host, then onehost sync --force
VM FAILURE in PROLOG /var/log/one/<id>.log transfer errors Datastore reachable from host? Space available? BRIDGE_LIST correct?
Live migration fails Host-to-host SSH, CPU model compatibility Use EVC / a common CPU model for mixed CPU generations (7.2 feature)
Live storage migration fails for UEFI VMs 7.4.0 known issue with NVRAM Upgrade to 7.4.1
Sunstone login fails /var/log/one/fireedge.log Check oneadmin credentials, then systemctl restart opennebula-fireedge
Datastore full onedatastore list Delete unused images and snapshots, or add a datastore
gRPC client errors in HA onezone show 0 Set ENDPOINT_GRPC on each HA server

Sources