evectl is a command-line virtualization management tool designed to work with the cloud-hypervisor VMM, providing essential VM lifecycle management capabilities. When used in conjunction with evemds (eve Metadata Server), it offers a streamlined way to deploy fully configured Linux virtual machines within minutes.
Please note that this project is currently under active development and should be considered a Work In Progress (WIP). As such:
- Features may be incomplete or subject to change
- Stability is not guaranteed
- Some functionality might not work as expected
Some default configurations are currently not optimized for security and should be reviewed before using in a production environment. For example:
- evemds defaults to listening on
0.0.0.0:9001using HTTP - Cloud-init data is transmitted without encryption
- Other security features may need hardening
It is recommended to evaluate and adjust these settings according to your security requirements before deploying in a production environment.
evectl aims to streamline the Cloud-Hypervisor workflow, making it accessible to both developers and system administrators. By abstracting away the complexities of low-level VM management, evectl allows users to focus on their workloads rather than the underlying infrastructure. The integration with evemds further simplifies the process by providing dynamic metadata to newly created VMs, enabling automated configuration and initialization using cloud-init.
Key features:
- Simplified VM Management: Create, start, stop, delete, and list VMs with simple commands.
- Cloud-Init Integration: Seamless integration with evemds for automated VM configuration.
- Fast Deployment: Launch fully initialized Linux VMs in under a minute.
- CLI-centric: Designed for efficient command-line interaction and scripting.
evectl relies on several key components to provide its functionality:
- evectl (CLI): The core command-line tool that provides the user interface for interacting with Cloud-Hypervisor. It handles parsing commands, communicating with the Cloud-Hypervisor API, and displaying output to the user.
- Cloud-Hypervisor: The underlying virtualization technology that provides the hypervisor and virtual machine execution environment. evectl interacts directly with the Cloud-Hypervisor API to manage VMs.
- evemds (Metadata Server): A minimal metadata server that provides instance-specific data to VMs during boot. This data is used by cloud-init to automate tasks such as setting hostnames, configuring networking, and installing software. evemds serves metadata in the standard cloud-init format.
- Cloud-Init: A widely used industry standard multi-distribution package that handles early initialization of a cloud instance. It reads metadata provided by evemds and performs the necessary configuration steps.
- VM Images: Disk images containing the operating system and necessary software for the virtual machines. These images are used as the basis for creating new VMs. Typically, these are cloud images that are pre-configured for cloud-init.
The interaction between these components is as follows:
- The user uses
evectl createto create a new VM, specifying parameters such as the image, memory, and vCPUs. - evectl instructs Cloud-Hypervisor to create the VM instance.
- The newly booted VM requests metadata from the configured metadata server (evemds).
- evemds provides the metadata, including network configuration, SSH keys, and user data.
- cloud-init within the VM processes the metadata, configuring the system accordingly.
- The VM is now fully initialized and ready for use.
- python3-venv
- python3-pip
- bridge-utils
- qemu-utils (for qemu-img)
- A DHCP server somewhere in your network
The automated installation script handles all essential components:
- UEFI Firmware (compatible version)
- Cloud-hypervisor
- Ubuntu Server LTS (latest version)
Run this command to start the installation:
curl -s https://raw.githubusercontent.com/syncopsta/evectl/refs/heads/main/install.sh | bash- Configure the network bridge:
- Create a new bridge interface
- Either bridge it with your physical network interface
- Or set up Host-to-VM connectivity with a dedicated IP address
Example for Host-to-VM connectivity:
brctl addbr vmbr0
ip link set up dev vmbr0
ip addr add 192.168.27.254/24 dev vmbr0Edit the configuration file at /opt/evectl/etc/evectl.yaml:
directories:
bin: /opt/evectl/bin/
data: /var/lib/evectl/
config: /opt/evectl/etc/
socket: /var/run/evectl/
vm_config: /etc/evectl/vmcfg/
network:
metadata_server: http://192.168.27.254:9001/ # Modify as needed
default_bridge: vmbr0 # Change if using different bridgeKey configuration points:
- The metadata server (
evemds) defaults to 0.0.0.0:9001 - Adjust the metadata_server address according to your setup
- Modify default_bridge if using a different bridge interface name
- /etc/evectl/hosts_config.yaml
- metadata service evemds configuration file
- The
fallback.evectlkey is a default key that gets deployed if the needed hostname is not present in the configuration.
hosts:
dbserver.example.com:
ssh_keys:
- "ssh-rsa AAAAB3NzaC1yc2E... [email protected]"
- "ssh-rsa AAAAB3N5aD1eaFE... [email protected]"
fallback.evectl:
ssh_keys:
- "ssh-rsa AAAAB3NzaC1yc2E... [email protected]"- /opt/evectl/etc/cloud_images.yaml (Image database)
- after the image conversion move the .raw file to
/var/lib/evectl/cloud_images/
- after the image conversion move the .raw file to
images:
ubuntu:
"2404": "/var/lib/evectl/cloud_images/ubuntu-24.04.raw"
"2204": "/var/lib/evectl/cloud_images/ubuntu-22.04.raw"
debian:
"12": "/var/lib/evectl/cloud_images/debian12.raw"
"13": "/var/lib/evectl/cloud_images/debian13.raw"To view the image database, use the following command:
evectl listimagesImages need to be converted using qemu-img convert from qcow2 into raw. For example:
qemu-img convert noble-server-cloudimg-amd64.img noble-server-cloudimg-amd64.rawAll Generic Cloud Images with cloud-init preinstalled should be working.
Currently only tested with Ubuntu images.
| Linux Distribution | Download | Version | Tested |
|---|---|---|---|
| Ubuntu | Download | 24.04 | Yes |
| Alpine Linux | Download | Cloud / UEFI | Yes |
| AlmaLinux | Download | / | No |
| Arch Linux | Download | / | No |
| CentOS | Download | / | No |
| Debian | Download | / | No |
| Fedora | Download | / | No |
| Kali Linux | Download | / | No |
| openSUSE | Download | / | No |
| RHEL | Download | / | No |
| Rocky Linux | Download | / | No |
| SLES | Download | / | No |
The metadata server is required for cloud-init, specifically for automatic SSH key provisioning on boot of virtual machines.
The metadata server listens on http://0.0.0.0:9001 by default. The IP/port configuration can be modified in the systemd service file located at /etc/systemd/system/evemds.service.
-
Edit Configuration:
sudo nano /etc/evectl/hosts_config.yaml
-
Restart Service:
sudo systemctl restart evemds
Please see the file called LICENSE.