mirror of https://github.com/BlackLight/vmctl.git
104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# vmctl
|
|
|
|
`vmctl` is a script that automates the installation, provisioning and
|
|
management of Arch Linux virtual machines.
|
|
|
|
## Dependencies
|
|
|
|
- `qemu`
|
|
- `curl`
|
|
- `expect`
|
|
|
|
## Installation
|
|
|
|
Just copy the `vmctl` script anywhere in your `PATH`, or clone the repository
|
|
and create a symbolic link to `vmctl` in your `PATH`.
|
|
|
|
## Usage
|
|
|
|
### Install an Arch Linux virtual machine
|
|
|
|
The `vmctl install` command can be used to create an Arch Linux virtual machine
|
|
on the fly, wherever you are. It does the following:
|
|
|
|
- It downloads the latest Arch Linux installer ISO image if none was downloaded
|
|
or a new one is available.
|
|
- It creates a `qemu` disk file.
|
|
- It boots a new KVM that uses the ISO file as as CDROM and automates the
|
|
installation of Arch Linux in the virtual machine (no user prompt required).
|
|
- It can install extra packages and run custom post-installation provisioning scripts.
|
|
|
|
```text
|
|
Usage: vmctl install [-o <output-disk-image>] [-a <architecture>] [-s <disk-size>]
|
|
[-m <memory>] [-h <hostname>] [-P <root-password>] [-u <non-root-username>]
|
|
[-p <non-root-user-password>] [-z <timezone>] [-l <locale>] [-M <arch-mirror-url>]
|
|
[-K] [extra qemu arguments]
|
|
|
|
-o <output-disk-image> Path of the output disk image (default: ./arch.img)
|
|
-a <architecture> Target architecture (default: x86_64)
|
|
-s <disk-size> Disk size (default: 8G)
|
|
-m <memory> RAM size in KB (default: 2048)
|
|
-h <hostname> VM hostname (default: qemu)
|
|
-P <root-password> Root password. If not specified it will be prompted
|
|
-u <non-root-username> Username for the main non-root user
|
|
-p <non-root-user-password> Password for the non-root user. If not specified it will be prompted
|
|
-z <timezone> System timezone (default: UTC)
|
|
-l <locale> System locale (default: en_US.UTF-8)
|
|
-M <arch-mirror-url> Arch Linux download mirror URL (default: http://mirror.cj2.nl/archlinux/iso/latest/)
|
|
Consult https://archlinux.org/download/ for a full list of the available download mirrors.
|
|
-K Disable pacman keyring checks during installation. It's potentially unsafe,
|
|
but it can be an option if downloading the keys takes too long.
|
|
```
|
|
|
|
If a required option is not specified on the command line then it will be
|
|
interactively prompted to the user (defaults are available for most of the
|
|
options).
|
|
|
|
Non-interactive example:
|
|
|
|
```bash
|
|
vmctl install \
|
|
-h my_vm \
|
|
-a x86_64 \
|
|
-s 16G \
|
|
-m 2048 \
|
|
-P root \
|
|
-u myuser \
|
|
-p password \
|
|
-z Europe/Amsterdam \
|
|
-o arch-base.img
|
|
```
|
|
|
|
If you want to install an extra list of packages besides the default ones, then
|
|
specify them in a file named `PKGLIST` in the same directory as the disk image file.
|
|
|
|
If you want to run a custom post-installation script after the core system has been
|
|
installed, then create a custom script named `post-install.sh` in the same directory
|
|
as the disk image file.
|
|
|
|
#### Notes
|
|
|
|
The keyring population process may currently (as of March 2022) take a long time.
|
|
This is a [known issue](https://www.reddit.com/r/archlinux/comments/rbjbcr/pacman_keyring_update_taking_too_long/).
|
|
|
|
### Resize an existing image
|
|
|
|
```bash
|
|
qemu-img resize "$imgfile" +10G
|
|
```
|
|
|
|
### Create a COW (Copy-On-Write) image on top of a disk image
|
|
|
|
```bash
|
|
qemu-img create -o backing_file="$imgfile",backing_fmt=raw -f qcow2 img1.cow
|
|
```
|
|
|
|
This is particularly useful if you want to have a "base" image and several customized
|
|
images built on it.
|
|
|
|
### Convert a raw qemu image to a VirtualBox
|
|
|
|
```bash
|
|
qemu-img convert -O vdi disk.img disk.vdi
|
|
```
|