summaryrefslogtreecommitdiff
path: root/extensions/virtualbox-ssh.write.help
blob: 2dbf988c5f6da505a45c4df3a01d033193ac00e5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
# 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* 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=<VALUE> - boolean. If it is set, the VM will be started when
      it has been deployed.

    * VAGRANT=<VALUE> - 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=<ip_address> - the IP address of the VM host.

    * NETMASK=<netmask> - the netmask of the VM host.

    * NETWORK_CONFIG=<net_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)