Merge branch 'README' into 'main'

doc: add README

See merge request larswirzenius/vmadm!10

1 files changed, 77 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9408291
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# vmadm README
+
+vmadm is a tool to create and destroy virtual machines running
+under a local libvirt. Virtual machines are described in specification
+files, using YAML:
+
+~~~yaml
+foo:
+  cpus: 4
+  memory_mib: 4096
+  image_size_gib: 100
+
+bar:
+  cpus: 1
+  memory_mib: 512
+  image_size_gib: 1
+~~~
+
+All the machines in a specification file are created or destroyed at
+once.
+
+## Usage
+
+Given a specification file `machines.yaml`, to create virtual machines
+run:
+
+~~~sh
+$ vmadm new machines.yaml
+~~~
+
+To delete them:
+
+~~~sh
+$ vmadm delete machines.yaml
+~~~
+
+Creating a VM creates a disk image of qcow2 format, based on a base
+image, also of qcow2 format. Deleting the VM deletes the image file as
+well. Image files are named after the VM and put into the configured
+image directory, unless the specification file names an image file
+explicitly.
+
+To get built-in command line help:
+
+~~~sh
+$ vmadm help
+$ vmadm --help
+~~~
+
+## Configuration
+
+The default configuration file is `vmadm/config.yaml` under the XDG
+configuration directory; by default, this is
+`~/.config/vmadm/config.yaml`. The configuration file may specify the
+following fields:
+
+* `default_base_image` – path to the base image to use by default
+* `default_image_gib` – default size of new image for a VM, in GiB
+* `default_memory_mib` – default amount of memory for a VM, in MiB
+* `default_cpus` – default number of CPUs for a VM
+* `image_directory` – directory where VM image files are put
+* `authorized_keys` – list of filenames to SSH public keys, to
+  be put into the default user's `authorized_keys` file in the VM
+
+## Specification fields
+
+The specification file is YAML and may specify the following fields,
+all of which override some default from the configuration.
+
+* `ssh_key_files` – overrides `authorized_keys`
+* `image_size_gib` – overrides `default_image_giv`
+* `memory_mib` – overrides `default_memory_mib`
+* `cpus` – overrides `default_cpus`
+* `base` – overrides `default_base_image`
+* `image` – overrides default image file name; must include
+  pathname, is not put into the image directory by default
+