diff options
| -rw-r--r-- | README.md | 77 |
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 + |