1 files changed, 65 insertions, 1 deletions

diff --git a/README.md b/README.md
index 9408291..5525589 100644
--- a/README.md
+++ b/README.md
@@ -58,9 +58,13 @@ following fields:
 * `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
+* `default_generate_host_certificate` – should SSH host
+  certificates be generated by default?
 * `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
+* `ca_key` – path name to default CA *private* key
+
 
 ## Specification fields
 
@@ -73,5 +77,65 @@ all of which override some default from the configuration.
 * `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
+* `image` – overrides default image file name; must include
+  path name, is not put into the image directory by default
+* `generate_host_certificate` – override host certification
+  setting
+* `ca_key` – overrides default CA key
+* `rsa_host_key` – RSA host key to install on host
+* `rsa_host_cert` – RSA host certificate to install on host
+* `dsa_host_key` – DSA host key to install on host
+* `dsa_host_cert` – DSA host certificate to install on host
+* `ecdsa_host_key` – ECDSA host key to install on host
+* `ecdsa_host_cert` – ECDSA host certificate to install on host
+* `ed25519_host_key` – Ed25519 host key to install on host
+* `ed25519_host_cert` – Ed25519 host certificate to install on host
+
+The various `host_key` and `host_cert` fields specify *private* host
+keys and certificates to be installed in the new VM. The public key is
+computed from the private key, so there's no need to specify it
+explicitly. The fields should contain the text of the key or
+certificate, not its filename.
+
+If *any* host key is specified, no host certificate is generated: the
+`generate_host_certificate` setting is ignored. If no host keys is
+specified, an Ed25519 key is generated and signed with the specified
+CA certificate. The generated key and certificate are installed in the
+new VM.
+
+In other words, if you specify any host keys, you get to do everything
+by hand. If you want to keep things easy, don't specify any host keys
+and let vmadm generate a host key and host certificate for a VM.
+
+# Using host certificates
+
+Host certificates allow you to access a newly created VM without
+having to accept its host key. This is especially useful the VM gets
+recreated and the host key changes. You need to configure your SSH
+client to trust certificates made with a given SSH CA key, but that is
+a one-time operation.
+
+You need to create an SSH key used as a CA key for host certification.
+Run this command:
+
+~~~sh
+$ mkdir -m 0700 ~/.ssh/ca
+$ ssh-keygen -f ~/.ssh/ca/vmadm_ca -t ed25519 -N ''
+~~~
+
+This creates a key **without a passphrase**, because vmadm does not
+currently support CA keys with passphrases.
+
+Keep the CA key secure. Don't use it for anything else.
+
+Add the following to the `known_hosts` file your SSH client uses, all
+on one one:
+
+~~~
+@cert-authority * XXXX
+~~~
 
+where `XXX` is the public key part of the CA key, as stored in
+`~/.ssh/ca/vmadm_ca.pub` in the example above. This tells your client
+that the CA key on the line should be accepted for all hosts (`*`).
+You can restrict it to only some hosts if you prefer.