qemu: document boot command from struct

This commit is contained in:
Adrien Delorme 2019-06-13 16:08:15 +02:00
parent b48d22b43b
commit 3bb8c92902
7 changed files with 340 additions and 85 deletions

View File

@ -1,3 +1,5 @@
//go:generate struct-markdown
package bootcommand
import (
@ -8,18 +10,131 @@ import (
"github.com/hashicorp/packer/template/interpolate"
)
// The boot configuration is very important: `boot_command` specifies the keys
// to type when the virtual machine is first booted in order to start the OS
// installer. This command is typed after boot_wait, which gives the virtual
// machine some time to actually load.
//
// The boot_command is an array of strings. The strings are all typed in
// sequence. It is an array only to improve readability within the template.
//
// There are a set of special keys available. If these are in your boot
// command, they will be replaced by the proper key:
//
// - `<bs>` - Backspace
//
// - `<del>` - Delete
//
// - `<enter> <return>` - Simulates an actual "enter" or "return" keypress.
//
// - `<esc>` - Simulates pressing the escape key.
//
// - `<tab>` - Simulates pressing the tab key.
//
// - `<f1> - <f12>` - Simulates pressing a function key.
//
// - `<up> <down> <left> <right>` - Simulates pressing an arrow key.
//
// - `<spacebar>` - Simulates pressing the spacebar.
//
// - `<insert>` - Simulates pressing the insert key.
//
// - `<home> <end>` - Simulates pressing the home and end keys.
//
// - `<pageUp> <pageDown>` - Simulates pressing the page up and page down
// keys.
//
// - `<menu>` - Simulates pressing the Menu key.
//
// - `<leftAlt> <rightAlt>` - Simulates pressing the alt key.
//
// - `<leftCtrl> <rightCtrl>` - Simulates pressing the ctrl key.
//
// - `<leftShift> <rightShift>` - Simulates pressing the shift key.
//
// - `<leftSuper> <rightSuper>` - Simulates pressing the ⌘ or Windows key.
//
// - `<wait> <wait5> <wait10>` - Adds a 1, 5 or 10 second pause before
// sending any additional keys. This is useful if you have to generally
// wait for the UI to update before typing more.
//
// - `<waitXX>` - Add an arbitrary pause before sending any additional keys.
// The format of `XX` is a sequence of positive decimal numbers, each with
// optional fraction and a unit suffix, such as `300ms`, `1.5h` or `2h45m`.
// Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For
// example `<wait10m>` or `<wait1m20s>`.
//
// - `<XXXOn> <XXXOff>` - Any printable keyboard character, and of these
// "special" expressions, with the exception of the `<wait>` types, can
// also be toggled on or off. For example, to simulate ctrl+c, use
// `<leftCtrlOn>c<leftCtrlOff>`. Be sure to release them, otherwise they
// will be held down until the machine reboots. To hold the `c` key down,
// you would use `<cOn>`. Likewise, `<cOff>` to release.
//
// - `{{ .HTTPIP }} {{ .HTTPPort }}` - The IP and port, respectively of an
// HTTP server that is started serving the directory specified by the
// `http_directory` configuration parameter. If `http_directory` isn't
// specified, these will be blank!
//
// - `Name` - The name of the VM.
//
// Example boot command. This is actually a working boot command used to start an
// CentOS 6.4 installer:
//
// ``` json
// "boot_command": [
// "<tab><wait>",
// " ks=http://{{ .HTTPIP }}:{{ .HTTPPort }}/centos6-ks.cfg<enter>"
// ]
// ```
// For more examples of various boot commands, see the sample projects from our
// [community templates page](/community-tools.html#templates).
type BootConfig struct {
RawBootGroupInterval string `mapstructure:"boot_keygroup_interval"`
RawBootWait string `mapstructure:"boot_wait"`
BootCommand []string `mapstructure:"boot_command"`
BootGroupInterval time.Duration ``
BootWait time.Duration ``
// Time to wait after sending a group of key pressses. The value of this
// should be a duration. Examples are `5s` and `1m30s` which will cause
// Packer to wait five seconds and one minute 30 seconds, respectively. If
// this isn't specified, a sensible default value is picked depending on
// the builder type.
RawBootGroupInterval string `mapstructure:"boot_keygroup_interval"`
// The time to wait after booting the initial virtual machine before typing
// the `boot_command`. The value of this should be a duration. Examples are
// `5s` and `1m30s` which will cause Packer to wait five seconds and one
// minute 30 seconds, respectively. If this isn't specified, the default is
// `10s` or 10 seconds.
RawBootWait string `mapstructure:"boot_wait"`
// This is an array of commands to type when the virtual machine is first
// booted. The goal of these commands should be to type just enough to
// initialize the operating system installer. Special keys can be typed as
// well, and are covered in the section below on the boot command. If this
// is not specified, it is assumed the installer will start itself.
BootCommand []string `mapstructure:"boot_command"`
BootGroupInterval time.Duration ``
BootWait time.Duration ``
}
// The boot command "typed" character for character over a VNC connection to
// the machine, simulating a human actually typing the keyboard.
//
// Keystrokes are typed as separate key up/down events over VNC with a default
// 100ms delay. The delay alleviates issues with latency and CPU contention.
// You can tune this delay on a per-builder basis by specifying
// "boot_key_interval" in your Packer template, example:
//
// ``` json
// "builders": [
// {
// "type": "...",
// "boot_key_interval": "10ms"
// ...
// }
// ]
// ```
type VNCConfig struct {
BootConfig `mapstructure:",squash"`
// Whether to create a VNC connection or not. A boot_command cannot be used
// when this is true. Defaults to false.
DisableVNC bool `mapstructure:"disable_vnc"`
// time in ms to wait between each key press
// Time in ms to wait between each key press
RawBootKeyInterval string `mapstructure:"boot_key_interval"`
BootKeyInterval time.Duration ``
}

View File

@ -109,68 +109,17 @@ Linux server and have not enabled X11 forwarding (`ssh -X`).
### Optional:
<%= partial "partials/builder/qemu/Config-not-required" %>
DADA
- `boot_command` (array of strings) - This is an array of commands to type
when the virtual machine is first booted. The goal of these commands should
be to type just enough to initialize the operating system installer. Special
keys can be typed as well, and are covered in the section below on the
boot command. If this is not specified, it is assumed the installer will
start itself.
## Boot Configuration Reference
- `boot_wait` (string) - The time to wait after booting the initial virtual
machine before typing the `boot_command`. The value of this should be
a duration. Examples are `5s` and `1m30s` which will cause Packer to wait
five seconds and one minute 30 seconds, respectively. If this isn't
specified, the default is `10s` or 10 seconds.
<%= partial "partials/common/bootcommand/VNCConfig" %>
<%= partial "partials/common/bootcommand/BootConfig" %>
## Boot Command
### Optional:
<%= partial "partials/common/bootcommand/VNCConfig-not-required" %>
<%= partial "partials/common/bootcommand/BootConfig-not-required" %>
The `boot_command` configuration is very important: it specifies the keys to
type when the virtual machine is first booted in order to start the OS
installer. This command is typed after `boot_wait`, which gives the virtual
machine some time to actually load the ISO.
As documented above, the `boot_command` is an array of strings. The strings are
all typed in sequence. It is an array only to improve readability within the
template.
The boot command is "typed" character for character over a VNC connection to the
machine, simulating a human actually typing the keyboard.
-&gt; Keystrokes are typed as separate key up/down events over VNC with a
default 100ms delay. The delay alleviates issues with latency and CPU
contention. You can tune this delay on a per-builder basis by specifying
"boot_key_interval" in your Packer template, for example:
```
{
"builders": [
{
"type": "qemu",
"boot_key_interval": "10ms"
...
}
]
}
```
<%= partial "partials/builders/boot-command" %>
Example boot command. This is actually a working boot command used to start an
CentOS 6.4 installer:
``` json
{
"boot_command": [
"<tab><wait>",
" ks=http://{{ .HTTPIP }}:{{ .HTTPPort }}/centos6-ks.cfg<enter>"
]
}
```
For more examples of various boot commands, see the sample projects from our
[community templates page](/community-tools.html#templates).
### Troubleshooting

View File

@ -1,7 +1,7 @@
<!-- Code generated from the comments of the Config struct in builder/qemu/builder.go; DO NOT EDIT MANUALLY -->
- `iso_skip_cache` (bool) - Use iso from provided url. Qemu must support
curl block device. This defaults to false.
curl block device. This defaults to `false`.
- `accelerator` (string) - The accelerator type to use when running the VM.
This may be `none`, `kvm`, `tcg`, `hax`, `hvf`, `whpx`, or `xen`. The appropriate
@ -26,11 +26,17 @@
- `cpus` (int) - The number of cpus to use when building the VM.
The default is `1` CPU.
- `disk_interface` (string) - The interface to use for the disk. Allowed
values include any of ide, scsi, virtio or virtio-scsi*. Note
also that any boot commands or kickstart type scripts must have proper
adjustments for resulting device names. The Qemu builder uses virtio by
default.
- `disk_interface` (string) - The interface to use for the disk. Allowed values include any of `ide`,
`scsi`, `virtio` or `virtio-scsi`^\*. Note also that any boot commands
or kickstart type scripts must have proper adjustments for resulting
device names. The Qemu builder uses `virtio` by default.
^\* Please be aware that use of the `scsi` disk interface has been
disabled by Red Hat due to a bug described
[here](https://bugzilla.redhat.com/show_bug.cgi?id=1019220). If you are
running Qemu on RHEL or a RHEL variant such as CentOS, you *must* choose
one of the other listed interfaces. Using the `scsi` interface under
these circumstances will cause the build to fail.
- `disk_size` (uint) - The size, in megabytes, of the hard disk to create
for the VM. By default, this is 40960 (40 GB).
@ -54,12 +60,15 @@
- `disk_compression` (bool) - Apply compression to the QCOW2 disk file
using qemu-img convert. Defaults to false.
- `format` (string) - Either qcow2 or raw, this specifies the output
format of the virtual machine image. This defaults to qcow2.
- `format` (string) - Either `qcow2` or `raw`, this specifies the output format of the virtual
machine image. This defaults to `qcow2`.
- `headless` (bool) - Packer defaults to building QEMU virtual machines by
launching a GUI that shows the console of the machine being built. When this
value is set to true, the machine will start without a console.
value is set to `true`, the machine will start without a console.
You can still see the console if you make a note of the VNC display
number chosen, and then connect using `vncviewer -Shared <host>:<display>`
- `disk_image` (bool) - Packer defaults to building from an ISO file, this parameter controls
whether the ISO URL supplied is actually a bootable QEMU image. When
@ -73,18 +82,18 @@
will only contain blocks that have changed compared to the backing file, so
enabling this option can significantly reduce disk usage.
- `machine_type` (string) - The type of machine emulation to use. Run your
qemu binary with the flags -machine help to list available types for
your system. This defaults to pc.
- `machine_type` (string) - The type of machine emulation to use. Run your qemu binary with the
flags `-machine help` to list available types for your system. This
defaults to `pc`.
- `memory` (int) - The amount of memory to use when building the VM
in megabytes. This defaults to 512 megabytes.
- `net_device` (string) - The driver to use for the network interface. Allowed
values ne2k_pci, i82551, i82557b, i82559er, rtl8139, e1000,
pcnet, virtio, virtio-net, virtio-net-pci, usb-net, i82559a,
i82559b, i82559c, i82550, i82562, i82557a, i82557c, i82801,
vmxnet3, i82558a or i82558b. The Qemu builder uses virtio-net by
- `net_device` (string) - The driver to use for the network interface. Allowed values `ne2k_pci`,
`i82551`, `i82557b`, `i82559er`, `rtl8139`, `e1000`, `pcnet`, `virtio`,
`virtio-net`, `virtio-net-pci`, `usb-net`, `i82559a`, `i82559b`,
`i82559c`, `i82550`, `i82562`, `i82557a`, `i82557c`, `i82801`,
`vmxnet3`, `i82558a` or `i82558b`. The Qemu builder uses `virtio-net` by
default.
- `output_directory` (string) - This is the path to the directory where the
@ -94,11 +103,68 @@
the builder. By default this is output-BUILDNAME where "BUILDNAME" is the
name of the build.
- `qemuargs` ([][]string) - Allows complete control over the
qemu command line (though not, at this time, qemu-img). Each array of
strings makes up a command line switch that overrides matching default
switch/value pairs. Any value specified as an empty string is ignored. All
values after the switch are concatenated with no separator.
- `qemuargs` ([][]string) - Allows complete control over the qemu command line (though not, at this
time, qemu-img). Each array of strings makes up a command line switch
that overrides matching default switch/value pairs. Any value specified
as an empty string is ignored. All values after the switch are
concatenated with no separator.
~&gt; **Warning:** The qemu command line allows extreme flexibility, so
beware of conflicting arguments causing failures of your run. For
instance, using --no-acpi could break the ability to send power signal
type commands (e.g., shutdown -P now) to the virtual machine, thus
preventing proper shutdown. To see the defaults, look in the packer.log
file and search for the qemu-system-x86 command. The arguments are all
printed for review.
The following shows a sample usage:
``` json {
"qemuargs": [
[ "-m", "1024M" ],
[ "--no-acpi", "" ],
[
"-netdev",
"user,id=mynet0,",
"hostfwd=hostip:hostport-guestip:guestport",
""
],
[ "-device", "virtio-net,netdev=mynet0" ]
]
} ```
would produce the following (not including other defaults supplied by
the builder and not otherwise conflicting with the qemuargs):
``` text qemu-system-x86 -m 1024m --no-acpi -netdev
user,id=mynet0,hostfwd=hostip:hostport-guestip:guestport -device
virtio-net,netdev=mynet0" ```
~&gt; **Windows Users:** [QEMU for Windows](https://qemu.weilnetz.de/)
builds are available though an environmental variable does need to be
set for QEMU for Windows to redirect stdout to the console instead of
stdout.txt.
The following shows the environment variable that needs to be set for
Windows QEMU support:
``` text setx SDL_STDIO_REDIRECT=0 ```
You can also use the `SSHHostPort` template variable to produce a packer
template that can be invoked by `make` in parallel:
``` json {
"qemuargs": [
[ "-netdev", "user,hostfwd=tcp::{{ .SSHHostPort }}-:22,id=forward"],
[ "-device", "virtio-net,netdev=forward,id=net0"]
]
} ```
`make -j 3 my-awesome-packer-templates` spawns 3 packer processes, each
of which will bind to their own SSH port as determined by each process.
This will also work with WinRM, just change the port forward in
`qemuargs` to map to WinRM's default port of `5985` or whatever value
you have the service set to listen on.
- `qemu_binary` (string) - The name of the Qemu binary to look for. This
defaults to qemu-system-x86_64, but may need to be changed for

View File

@ -0,0 +1,20 @@
<!-- Code generated from the comments of the BootConfig struct in common/bootcommand/config.go; DO NOT EDIT MANUALLY -->
- `boot_keygroup_interval` (string) - Time to wait after sending a group of key pressses. The value of this
should be a duration. Examples are `5s` and `1m30s` which will cause
Packer to wait five seconds and one minute 30 seconds, respectively. If
this isn't specified, a sensible default value is picked depending on
the builder type.
- `boot_wait` (string) - The time to wait after booting the initial virtual machine before typing
the `boot_command`. The value of this should be a duration. Examples are
`5s` and `1m30s` which will cause Packer to wait five seconds and one
minute 30 seconds, respectively. If this isn't specified, the default is
`10s` or 10 seconds.
- `boot_command` ([]string) - This is an array of commands to type when the virtual machine is first
booted. The goal of these commands should be to type just enough to
initialize the operating system installer. Special keys can be typed as
well, and are covered in the section below on the boot command. If this
is not specified, it is assumed the installer will start itself.

View File

@ -0,0 +1,80 @@
<!-- Code generated from the comments of the BootConfig struct in common/bootcommand/config.go; DO NOT EDIT MANUALLY -->
The boot configuration is very important: `boot_command` specifies the keys
to type when the virtual machine is first booted in order to start the OS
installer. This command is typed after boot_wait, which gives the virtual
machine some time to actually load.
The boot_command is an array of strings. The strings are all typed in
sequence. It is an array only to improve readability within the template.
There are a set of special keys available. If these are in your boot
command, they will be replaced by the proper key:
- `<bs>` - Backspace
- `<del>` - Delete
- `<enter> <return>` - Simulates an actual "enter" or "return" keypress.
- `<esc>` - Simulates pressing the escape key.
- `<tab>` - Simulates pressing the tab key.
- `<f1> - <f12>` - Simulates pressing a function key.
- `<up> <down> <left> <right>` - Simulates pressing an arrow key.
- `<spacebar>` - Simulates pressing the spacebar.
- `<insert>` - Simulates pressing the insert key.
- `<home> <end>` - Simulates pressing the home and end keys.
- `<pageUp> <pageDown>` - Simulates pressing the page up and page down
keys.
- `<menu>` - Simulates pressing the Menu key.
- `<leftAlt> <rightAlt>` - Simulates pressing the alt key.
- `<leftCtrl> <rightCtrl>` - Simulates pressing the ctrl key.
- `<leftShift> <rightShift>` - Simulates pressing the shift key.
- `<leftSuper> <rightSuper>` - Simulates pressing the ⌘ or Windows key.
- `<wait> <wait5> <wait10>` - Adds a 1, 5 or 10 second pause before
sending any additional keys. This is useful if you have to generally
wait for the UI to update before typing more.
- `<waitXX>` - Add an arbitrary pause before sending any additional keys.
The format of `XX` is a sequence of positive decimal numbers, each with
optional fraction and a unit suffix, such as `300ms`, `1.5h` or `2h45m`.
Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For
example `<wait10m>` or `<wait1m20s>`.
- `<XXXOn> <XXXOff>` - Any printable keyboard character, and of these
"special" expressions, with the exception of the `<wait>` types, can
also be toggled on or off. For example, to simulate ctrl+c, use
`<leftCtrlOn>c<leftCtrlOff>`. Be sure to release them, otherwise they
will be held down until the machine reboots. To hold the `c` key down,
you would use `<cOn>`. Likewise, `<cOff>` to release.
- `{{ .HTTPIP }} {{ .HTTPPort }}` - The IP and port, respectively of an
HTTP server that is started serving the directory specified by the
`http_directory` configuration parameter. If `http_directory` isn't
specified, these will be blank!
- `Name` - The name of the VM.
Example boot command. This is actually a working boot command used to start an
CentOS 6.4 installer:
``` json
"boot_command": [
"<tab><wait>",
" ks=http://{{ .HTTPIP }}:{{ .HTTPPort }}/centos6-ks.cfg<enter>"
]
```
For more examples of various boot commands, see the sample projects from our
[community templates page](/community-tools.html#templates).

View File

@ -0,0 +1,7 @@
<!-- Code generated from the comments of the VNCConfig struct in common/bootcommand/config.go; DO NOT EDIT MANUALLY -->
- `disable_vnc` (bool) - Whether to create a VNC connection or not. A boot_command cannot be used
when this is true. Defaults to false.
- `boot_key_interval` (string) - Time in ms to wait between each key press

View File

@ -0,0 +1,18 @@
<!-- Code generated from the comments of the VNCConfig struct in common/bootcommand/config.go; DO NOT EDIT MANUALLY -->
The boot command "typed" character for character over a VNC connection to
the machine, simulating a human actually typing the keyboard.
Keystrokes are typed as separate key up/down events over VNC with a default
100ms delay. The delay alleviates issues with latency and CPU contention.
You can tune this delay on a per-builder basis by specifying
"boot_key_interval" in your Packer template, example:
``` json
"builders": [
{
"type": "...",
"boot_key_interval": "10ms"
...
}
]
```