github.com/Cloud-Foundations/Dominator@v0.3.4/cmd/hyper-control/README.md (about) 1 # hyper-control 2 A utility to manage SmallStack Hypervisors. 3 4 The *hyper-control* utility manages [Hypervisors](../hypervisor/README.md). It 5 is typically run on a desktop or bastion machine. Please read the 6 [SmallStack design document](https://bit.ly/SmallStack) to understand the 7 architecture. 8 9 ## Usage 10 *hyper-control* supports several sub-commands. There are many command-line flags 11 which provide parameters for these sub-commands. The most commonly used 12 parameters are `-fleetManagerHostname` or `-hypervisorHostname` which specify 13 either the Fleet Manager or a specific *Hypervisor* to communicate with. At 14 startup, *hyper-control* will read parameters from the 15 `~/.config/hyper-control/flags.default` and 16 `~/.config/hyper-control/flags.extra` files. These are simple `name=value` 17 pairs. The basic usage pattern is: 18 19 ``` 20 hyper-control [flags...] command [args...] 21 ``` 22 23 Built-in help is available with the command: 24 25 ``` 26 hyper-control -h 27 ``` 28 29 Some of the sub-commands available are: 30 31 - **add-address**: manually add a MAC address and IP address pair to a specific 32 *Hypervisor*. If the IP address is not specified an external 33 DHCP server is required to provides leases to VMs. This 34 is only required if a *Fleet Manager* is not available 35 - **add-subnet**: manually add a subnet to a specific *Hypervisor*. This is only 36 required if a *Fleet Manager* is not available 37 - **change-tags**: change the tags for a specific *Hypervisor* 38 - **connect-to-vm-manager**: connect to the manager for the specified VM. This 39 is meant for low-level development 40 - **disable-hypervisor**: disable a specific *Hypervisor*, preventing VMs from 41 being created or started. Useful for draining (taking 42 out of service) a *Hypervisor* 43 - **enable-hypervisor**: enable a specific *Hypervisor*, enabling VMs to be 44 be created and started. Useful for bringing a 45 *Hypervisor* back into service 46 - **get-capacity**: get capacity for a specific *Hypervisor* directly from the 47 *Hypervisor* 48 - **get-machine-info**: get information for a specific *Hypervisor* from the 49 *Fleet Manager* 50 - **get-updates**: get and show a continuous stream of updates from a 51 *Hypervisor* or *Fleet Manager*. This is primarily for 52 debugging 53 - **hold-lock**: hold the *Hypervisor* lock for the time specified by 54 *-lock-timeout*. *-writeLock* specifies whether to hold a 55 write lock 56 - **hold-vm-lock**: hold the lock for a VM for the time specified by 57 *-lock-timeout* *-writeLock* specifies whether to hold a 58 write lock 59 - **installer-shell**: start a remote shell (via SRPC) to the installer running 60 on a machine 61 - **list-volume-directories**: list the volume directories for a specific 62 *Hypervisor* 63 - **make-installer-iso**: make a bootable installation ISO (CD-ROM) image for a 64 machine 65 - **move-ip-address**: move a (free) IP address to a specific *Hypervisor* 66 - **netboot-host**: temporarily enable PXE-based network booting and installing 67 for a machine 68 - **netboot-machine**: temporarily enable PXE-based network booting for a 69 machine 70 - **netboot-vm**: create a temporary VM and install with PXE booting. This is 71 for debugging physical machine installation 72 - **power-off**: shut down and power off the specified *Hypervisor*. All VMs 73 must be stopped beforehand 74 - **power-on**: power on the specified *Hypervisor*. This uses remote IPMI or 75 Wake On LAN, where available. 76 - **register-external-leases**: register external DHCP leases with a specific 77 *Hyervisor*. These are lost after a *Hypervisor* 78 restart 79 - **reinstall**: reinstall the local machine. This erases all data 80 - **remove-excess-addresses**: remove free addresses for a specific *Hypervisor* 81 above the specified limit 82 - **remove-ip-address**: remove a (free) IP address from a specific *Hypervisor* 83 - **remove-mac-address**: remove a (free) MAC address from a specific 84 *Hypervisor* 85 - **rollout-image**: safely roll out specified image to all *Hypervisors* in a 86 location 87 - **show-network-configuration**: show the network configuration for the 88 specified *Hypervisor* 89 - **update-network-configuration**: update the network configuration for the 90 local *Hypervisor* 91 - **watch-dhcp**: watch for DHCP messages received by the specified *Hypervisor* 92 and log and write packet data. This is primarily for debugging 93 - **write-netboot-files**: write the configuration files for installing a 94 machine. This is primarily for debugging 95 96 ## Security 97 The *Hypervisor* restricts RPC access using TLS client authentication. 98 *hyper-control* will load certificate and key files from the 99 `~/.ssl` directory. *hyper-control* will present these certificates to 100 the *Hypervisor* (or *Fleet Manager*). If one of the certificates is signed by a 101 certificate authority that the *Hypervisor* trusts, the *Hypervisor* will grant 102 access. 103 104 ## Installing Hypervisors 105 The *hyper-control* tool may be used to install *Hypervisors* (OS+Hypervisor) on 106 physical machines. This requires that information about machines and subnets is 107 recorded in the topology (usually in Git), which is obtained from the 108 [Fleet Manager](../fleet-manager/README.md). *Hypervisors* may be installed by 109 PXE booting an installer, booting from a custom ISO image or installing over a 110 running system. Please read the 111 [Machine Birthing design document](../../design-docs/MachineBirthing/README.md) 112 which describes the principles of installing physical machines. 113 114 ### Network (PXE) Installation 115 This is the most common method of installing. If there is at least one working 116 Hypervisor on the same subnet, you can PXE (network) boot. The *hyper-control* 117 tool is used to automatically select a *Hypervisor* to configure as a PXE server 118 (it creates a temporary DHCP lease and will serve configuration files via TFTP). 119 120 The following options must be provided: 121 - `fleetManagerHostname` 122 - `imageServerHostname` 123 - `installerImageStream` 124 125 You may want to increase the `-netbootTimeout` option if the machine takes a 126 long time to boot. Run the following command: 127 128 ``` 129 hyper-control netboot-host $target_host 130 ``` 131 132 Then, initiate a PXE boot for the target machine. It should boot the installer 133 image, configure and install the machine and then reboot into the new OS. In 134 principle, multiple machines can be installed in parallel, one machine for each 135 time the above command is run. 136 137 ### Installing from an ISO (CD-ROM) image 138 If there is no working *Hypervisor* on the subnet and if there is no DHCP relay 139 configured to forward DHCP requests to a *Hypervisor* on another subnet, then 140 another option is to install the machine using a custom ISO (CD-ROM) image. The 141 ISO image can be written to a CD-ROM, a USB memory drive or served by a NFS/SMB 142 server (this requires that the machine BIOS supports booting from remote media). 143 144 As above, the same required options must be provided. The following command will 145 generate a custom ISO image for the target machine. Note that the networking 146 configuration for the machine is baked into the ISO, so the ISO is only good for 147 one machine. 148 149 ``` 150 hyper-control make-installer-iso $target_host $destdir 151 ``` 152 153 This will create a custom ISO for this machine in the specified directory, with 154 both hostname and IP address file entries. 155 156 ### Self installing a Hypervisor 157 If there is a Linux OS already installed and running on a machine, you can use 158 the *hyper-control* utility to install a new OS+Hypervisor. This uses the 159 `kexec` utility to boot directly into the new kernel, skipping the BIOS. This is 160 a good way of wiping and getting a fresh install. 161 162 As above, the same required options must be provided. Run this command: 163 164 ``` 165 hyper-control reinstall 166 ``` 167 168 This method is much faster, since it skips rebooting via the BIOS the first. 169 Remember: it wipes all data on the machine! 170 171 ## Upgrading Hypervisors 172 Upgrading *Hypervisors* is done using the *hyper-control* tool. This sets the 173 `RequiredImage` tag on *Hypervisors* in the specified location. The rollout is 174 controlled, starting slow and gaining speed as *Hypervisors* complete upgrades 175 and remain healthy. The upgrade may include a new kernel, in which case the 176 machine will be rebooted as part of the upgrade, thus taking several minutes for 177 the per-machine upgrade+health check cycle to complete (compared to less than 178 one minute for most upgrades). The actual upgrades are performed by the 179 [dominator](../dominator/README.md) which reads the tags to determine the image 180 to push to the machine. Once the rollout is complete, the new tags are saved by 181 committing to the Git repository containing the topology. 182 183 The following options must be provided: 184 - `fleetManagerHostname` 185 - `imageServerHostname` 186 - `location` 187 - `topologyDir` 188 189 To rollout a new *Hypervisor* image to all the *Hypervisors* in the specified 190 location, run a command like this: 191 192 ``` 193 hyper-control rollout-image $image_name 194 ```