# 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 .
help: |
Deploy a Baserock system as a *new* VirtualBox virtual machine.
(Use the `ssh-rsync` write extension to deploy upgrades to an *existing*
VM)
Connects to HOST via ssh to run VirtualBox's command line management tools.
Parameters:
* location: a custom URL scheme of the form `vbox+ssh://HOST/GUEST/PATH`,
where:
* HOST is the name of the host on which VirtualBox 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,
`vbox+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: **(MANDATORY)** 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 virtual hard disk.
* RAM_SIZE=X: The amount of RAM that the virtual machine should allocate
for itself from the host. `X` is interpreted in the same 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.
* 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)
* AUTOSTART= - boolean. If it is set, the VM will be started when
it has been deployed.
* VAGRANT= - boolean. If it is set, then networking is configured
so that the VM will work with Vagrant. Otherwise networking is
configured to run directly in VirtualBox.
* HOST_IPADDR= - the IP address of the VM host.
* NETMASK= - the netmask of the VM host.
* NETWORK_CONFIG= - `net_config` is used to set up the VM's
network interfaces. It is a string containing semi-colon separated
'stanzas' where each stanza provides information about a network
interface. Each stanza is of the form name:type[,arg=value] e.g.
lo:loopback
eth0:dhcp
eth1:static,address=10.0.0.1,netmask=255.255.0.0
An example of the NETWORK_CONFIG parameter (It should be in one line)
`"lo:loopback;eth0:static,address=192.168.100.2,netmask=255.255.255.0;
eth1:dhcp,hostname=$(hostname)"`
It is useful to configure one interface to use NAT to give the VM access
to the outside world and another interface to use the Virtual Box host
adapter to allow you to access the Trove from the host machine.
The NAT interface eth1 is set up to use dhcp, the host-only adapter
interface is configured statically.
Note: you must give the host-only adapter interface an address that lies
**on the same network** as the host adapter. So if the host adapter has
an IP of 192.168.100.1 eth0 should have an address such as
192.168.100.42.
The settings of the host adapter, including its IP can be changed either
in the VirtualBox manager UI
(https://www.virtualbox.org/manual/ch03.html#settings-network)
or via the VBoxManage command line
(https://www.virtualbox.org/manual/ch08.html#idp57572192)
See Chapter 6 of the VirtualBox User Manual for more information about
virtual networking (https://www.virtualbox.org/manual/ch06.html)
(See `morph help deploy` for details of how to pass parameters to write
extensions)