# 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)