# Copyright (C) 2014, 2015 Codethink Limited
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 2 of the License.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, see <http://www.gnu.org/licenses/>.

help: |

    Deploy a Baserock system as a *new* KVM/LibVirt virtual machine.

    Use the `ssh-rsync` write extension to deploy upgrades to an *existing* VM

    Parameters:

    * location: a custom URL scheme of the form `kvm+ssh://HOST/GUEST/PATH`,
      where:
        * HOST is the name of the host on which KVM/LibVirt is running
        * GUEST is the name of the guest VM on that host
        * PATH is the path to the disk image that should be created,
          on that host. For example,
          `kvm+ssh://alice@192.168.122.1/testsys/home/alice/testys.img` where
            * `alice@192.168.122.1` is the target host as given to ssh,
              **from within the development host** (which may be
              different from the target host's normal address);
            * `testsys` is the name of the new guest VM';
            * `/home/alice/testys.img` is the pathname of the disk image files
              on the target host.

    * HOSTNAME=name: the hostname of the **guest** VM within the network into
      which it is being deployed

    * DISK_SIZE=X: the size of the VM's primary virtual hard disk. `X` should
      use a suffix of `K`, `M`, or `G` (in upper or lower case) to indicate
      kilo-, mega-, or gigabytes. For example, `DISK_SIZE=100G` would create a
      100 gigabyte disk image. **This parameter is mandatory**.

    * RAM_SIZE=X: The amount of RAM that the virtual machine should allocate
      for itself from the host. `X` is interpreted in the same was as for
      DISK_SIZE`, and defaults to `1G`

    * VCPUS=n: the number of virtual CPUs for the VM. Allowed values 1-32. Do
      not use more CPU cores than you have available physically (real cores, no
      hyperthreads)

    * INITRAMFS_PATH=path: the location of an initramfs for the bootloader to
      tell Linux to use, rather than booting the rootfs directly.

    * AUTOSTART=<VALUE>` - boolean. If it is set, the VM will be started when
      it has been deployed.

    * DTB_PATH=path: **(MANDATORY)** for systems that require a device tree
      binary - Give the full path (without a leading /) to the location of the
      DTB in the built system image . The deployment will fail if `path` does
      not exist.

    * BOOTLOADER_INSTALL=value: the bootloader to be installed
      **(MANDATORY)** for non-x86 systems

        allowed values =
        - 'extlinux' (default) - the extlinux bootloader will
           be installed
        - 'none' - no bootloader will be installed by `morph deploy`. A
           bootloader must be installed manually. This value must be used when
           deploying non-x86 systems such as ARM.

    * BOOTLOADER_CONFIG_FORMAT=value: the bootloader format to be used.
      If not specified for x86-32 and x86-64 systems, 'extlinux' will be used

        allowed values =
        - 'extlinux'

    * KERNEL_ARGS=args: optional additional kernel command-line parameters to
      be appended to the default set. The default set is:

        'rw init=/sbin/init rootfstype=btrfs \
          rootflags=subvol=systems/default/run \
          root=[name or UUID of root filesystem]'

        (See https://www.kernel.org/doc/Documentation/kernel-parameters.txt)

    (See `morph help deploy` for details of how to pass parameters to write
    extensions)