github.com/aclaygray/packer@v1.3.2/website/source/docs/builders/qemu.html.md.erb (about) 1 --- 2 modeline: | 3 vim: set ft=pandoc: 4 description: | 5 The Qemu Packer builder is able to create KVM and Xen virtual machine images. 6 layout: docs 7 page_title: 'QEMU - Builders' 8 sidebar_current: 'docs-builders-qemu' 9 --- 10 11 # QEMU Builder 12 13 Type: `qemu` 14 15 The Qemu Packer builder is able to create [KVM](http://www.linux-kvm.org) and 16 [Xen](http://www.xenproject.org) virtual machine images. 17 18 The builder builds a virtual machine by creating a new virtual machine from 19 scratch, booting it, installing an OS, rebooting the machine with the boot media 20 as the virtual hard drive, provisioning software within the OS, then shutting it 21 down. The result of the Qemu builder is a directory containing the image file 22 necessary to run the virtual machine on KVM or Xen. 23 24 ## Basic Example 25 26 Here is a basic example. This example is functional so long as you fixup paths 27 to files, URLS for ISOs and checksums. 28 29 ``` json 30 { 31 "builders": 32 [ 33 { 34 "type": "qemu", 35 "iso_url": "http://mirror.raystedman.net/centos/6/isos/x86_64/CentOS-6.9-x86_64-minimal.iso", 36 "iso_checksum": "af4a1640c0c6f348c6c41f1ea9e192a2", 37 "iso_checksum_type": "md5", 38 "output_directory": "output_centos_tdhtest", 39 "shutdown_command": "echo 'packer' | sudo -S shutdown -P now", 40 "disk_size": 5000, 41 "format": "qcow2", 42 "accelerator": "kvm", 43 "http_directory": "path/to/httpdir", 44 "ssh_username": "root", 45 "ssh_password": "s0m3password", 46 "ssh_timeout": "20m", 47 "vm_name": "tdhtest", 48 "net_device": "virtio-net", 49 "disk_interface": "virtio", 50 "boot_wait": "10s", 51 "boot_command": [ 52 "<tab> text ks=http://{{ .HTTPIP }}:{{ .HTTPPort }}/centos6-ks.cfg<enter><wait>" 53 ] 54 } 55 ] 56 } 57 ``` 58 59 This is an example only, and will time out waiting for SSH because we have not 60 provided a kickstart file. You must add a valid kickstart file to the 61 "http_directory" and then provide the file in the "boot_command" in order for 62 this build to run. We recommend you check out the 63 [Community Templates](https://www.packer.io/community-tools.html#templates) 64 for a practical usage example. 65 66 ## Configuration Reference 67 68 There are many configuration options available for the Qemu builder. They are 69 organized below into two categories: required and optional. Within each 70 category, the available options are alphabetized and described. 71 72 In addition to the options listed here, a 73 [communicator](/docs/templates/communicator.html) can be configured for this 74 builder. 75 76 Note that you will need to set `"headless": true` if you are running Packer 77 on a Linux server without X11; or if you are connected via ssh to a remote 78 Linux server and have not enabled X11 forwarding (`ssh -X`). 79 80 ### Required: 81 82 - `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO 83 files are so large, this is required and Packer will verify it prior to 84 booting a virtual machine with the ISO attached. The type of the checksum is 85 specified with `iso_checksum_type`, documented below. At least one of 86 `iso_checksum` and `iso_checksum_url` must be defined. This has precedence 87 over `iso_checksum_url` type. 88 89 - `iso_checksum_type` (string) - The type of the checksum specified in 90 `iso_checksum`. Valid values are `none`, `md5`, `sha1`, `sha256`, or 91 `sha512` currently. While `none` will skip checksumming, this is not 92 recommended since ISO files are generally large and corruption does happen 93 from time to time. 94 95 - `iso_checksum_url` (string) - A URL to a GNU or BSD style checksum file 96 containing a checksum for the OS ISO file. At least one of `iso_checksum` 97 and `iso_checksum_url` must be defined. This will be ignored if 98 `iso_checksum` is non empty. 99 100 - `iso_url` (string) - A URL to the ISO containing the installation image. 101 This URL can be either an HTTP URL or a file URL (or path to a file). If 102 this is an HTTP URL, Packer will download it and cache it between runs. 103 This can also be a URL to an IMG or QCOW2 file, in which case QEMU will 104 boot directly from it. When passing a path to an IMG or QCOW2 file, you 105 should set `disk_image` to `true`. 106 107 ### Optional: 108 109 - `accelerator` (string) - The accelerator type to use when running the VM. 110 This may be `none`, `kvm`, `tcg`, `hax`, `hvf`, or `xen`. The appropriate 111 software must have already been installed on your build machine to use the 112 accelerator you specified. When no accelerator is specified, Packer will try 113 to use `kvm` if it is available but will default to `tcg` otherwise. 114 115 -> The `hax` accelerator has issues attaching CDROM ISOs. This is an 116 upstream issue which can be tracked 117 [here](https://github.com/intel/haxm/issues/20). 118 119 -> The `hvf` accelerator is new and experimental as of 120 [QEMU 2.12.0](https://wiki.qemu.org/ChangeLog/2.12#Host_support). 121 You may encounter issues unrelated to Packer when using it. You may need to 122 add [ "-global", "virtio-pci.disable-modern=on" ] to `qemuargs` depending on the 123 guest operating system. 124 125 - `boot_command` (array of strings) - This is an array of commands to type 126 when the virtual machine is first booted. The goal of these commands should 127 be to type just enough to initialize the operating system installer. Special 128 keys can be typed as well, and are covered in the section below on the 129 boot command. If this is not specified, it is assumed the installer will 130 start itself. 131 132 - `boot_wait` (string) - The time to wait after booting the initial virtual 133 machine before typing the `boot_command`. The value of this should be 134 a duration. Examples are `5s` and `1m30s` which will cause Packer to wait 135 five seconds and one minute 30 seconds, respectively. If this isn't 136 specified, the default is `10s` or 10 seconds. 137 138 - `disk_cache` (string) - The cache mode to use for disk. Allowed values 139 include any of `writethrough`, `writeback`, `none`, `unsafe` 140 or `directsync`. By default, this is set to `writeback`. 141 142 - `disk_compression` (boolean) - Apply compression to the QCOW2 disk file 143 using `qemu-img convert`. Defaults to `false`. 144 145 - `disk_discard` (string) - The discard mode to use for disk. Allowed values 146 include any of `unmap` or `ignore`. By default, this is set to `ignore`. 147 148 - `disk_detect_zeroes` (string) - The detect-zeroes mode to use for disk. 149 Allowed values include any of `unmap`, `on` or `off`. Defaults to `off`. 150 151 - `disk_image` (boolean) - Packer defaults to building from an ISO file, this 152 parameter controls whether the ISO URL supplied is actually a bootable 153 QEMU image. When this value is set to `true`, the machine will either clone 154 the source or use it as a backing file (if `use_backing_file` is `true`); 155 then, it will resize the image according to `disk_size` and boot it. 156 157 - `disk_interface` (string) - The interface to use for the disk. Allowed 158 values include any of `ide`, `scsi`, `virtio` or `virtio-scsi`^\*. Note 159 also that any boot commands or kickstart type scripts must have proper 160 adjustments for resulting device names. The Qemu builder uses `virtio` by 161 default. 162 163 ^\* Please be aware that use of the `scsi` disk interface has been disabled 164 by Red Hat due to a bug described 165 [here](https://bugzilla.redhat.com/show_bug.cgi?id=1019220). 166 If you are running Qemu on RHEL or a RHEL variant such as CentOS, you 167 *must* choose one of the other listed interfaces. Using the `scsi` 168 interface under these circumstances will cause the build to fail. 169 170 - `disk_size` (number) - The size, in megabytes, of the hard disk to create 171 for the VM. By default, this is `40960` (40 GB). 172 173 - `floppy_dirs` (array of strings) - A list of directories to place onto 174 the floppy disk recursively. This is similar to the `floppy_files` option 175 except that the directory structure is preserved. This is useful for when 176 your floppy disk includes drivers or if you just want to organize it's 177 contents as a hierarchy. Wildcard characters (\*, ?, and \[\]) are allowed. 178 The maximum summary size of all files in the listed directories are the 179 same as in `floppy_files`. 180 181 - `floppy_files` (array of strings) - A list of files to place onto a floppy 182 disk that is attached when the VM is booted. This is most useful for 183 unattended Windows installs, which look for an `Autounattend.xml` file on 184 removable media. By default, no floppy will be attached. All files listed in 185 this setting get placed into the root directory of the floppy and the floppy 186 is attached as the first floppy device. Currently, no support exists for 187 creating sub-directories on the floppy. Wildcard characters (\*, ?, 188 and \[\]) are allowed. Directory names are also allowed, which will add all 189 the files found in the directory to the floppy. The summary size of the 190 listed files must not exceed 1.44 MB. The supported ways to move large 191 files into the OS are using `http_directory` or [the file provisioner](https://www.packer.io/docs/provisioners/file.html). 192 193 - `format` (string) - Either `qcow2` or `raw`, this specifies the output 194 format of the virtual machine image. This defaults to `qcow2`. 195 196 - `headless` (boolean) - Packer defaults to building QEMU virtual machines by 197 launching a GUI that shows the console of the machine being built. When this 198 value is set to `true`, the machine will start without a console. 199 200 You can still see the console if you make a note of the VNC display 201 number chosen, and then connect using `vncviewer -Shared <host>:<display>` 202 203 - `http_directory` (string) - Path to a directory to serve using an 204 HTTP server. The files in this directory will be available over HTTP that 205 will be requestable from the virtual machine. This is useful for hosting 206 kickstart files and so on. By default this is an empty string, which means 207 no HTTP server will be started. The address and port of the HTTP server will 208 be available as variables in `boot_command`. This is covered in more detail 209 below. 210 211 - `http_port_min` and `http_port_max` (number) - These are the minimum and 212 maximum port to use for the HTTP server started to serve the 213 `http_directory`. Because Packer often runs in parallel, Packer will choose 214 a randomly available port in this range to run the HTTP server. If you want 215 to force the HTTP server to be on one port, make this minimum and maximum 216 port the same. By default the values are `8000` and `9000`, respectively. 217 218 - `iso_skip_cache` (boolean) - Use iso from provided url. Qemu must support 219 curl block device. This defaults to `false`. 220 221 - `iso_target_extension` (string) - The extension of the iso file after 222 download. This defaults to `iso`. 223 224 - `iso_target_path` (string) - The path where the iso should be saved after 225 download. By default will go in the packer cache, with a hash of the 226 original filename as its name. 227 228 - `iso_urls` (array of strings) - Multiple URLs for the ISO to download. 229 Packer will try these in order. If anything goes wrong attempting to 230 download or while downloading a single URL, it will move on to the next. All 231 URLs must point to the same file (same checksum). By default this is empty 232 and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified. 233 234 - `machine_type` (string) - The type of machine emulation to use. Run your 235 qemu binary with the flags `-machine help` to list available types for 236 your system. This defaults to `pc`. 237 238 - `net_device` (string) - The driver to use for the network interface. Allowed 239 values `ne2k_pci`, `i82551`, `i82557b`, `i82559er`, `rtl8139`, `e1000`, 240 `pcnet`, `virtio`, `virtio-net`, `virtio-net-pci`, `usb-net`, `i82559a`, 241 `i82559b`, `i82559c`, `i82550`, `i82562`, `i82557a`, `i82557c`, `i82801`, 242 `vmxnet3`, `i82558a` or `i82558b`. The Qemu builder uses `virtio-net` by 243 default. 244 245 - `output_directory` (string) - This is the path to the directory where the 246 resulting virtual machine will be created. This may be relative or absolute. 247 If relative, the path is relative to the working directory when `packer` 248 is executed. This directory must not exist or be empty prior to running 249 the builder. By default this is `output-BUILDNAME` where "BUILDNAME" is the 250 name of the build. 251 252 - `qemu_binary` (string) - The name of the Qemu binary to look for. This 253 defaults to `qemu-system-x86_64`, but may need to be changed for 254 some platforms. For example `qemu-kvm`, or `qemu-system-i386` may be a 255 better choice for some systems. 256 257 - `qemuargs` (array of array of strings) - Allows complete control over the 258 qemu command line (though not, at this time, qemu-img). Each array of 259 strings makes up a command line switch that overrides matching default 260 switch/value pairs. Any value specified as an empty string is ignored. All 261 values after the switch are concatenated with no separator. 262 263 ~> **Warning:** The qemu command line allows extreme flexibility, so beware 264 of conflicting arguments causing failures of your run. For instance, using 265 --no-acpi could break the ability to send power signal type commands (e.g., 266 shutdown -P now) to the virtual machine, thus preventing proper shutdown. To see 267 the defaults, look in the packer.log file and search for the qemu-system-x86 268 command. The arguments are all printed for review. 269 270 The following shows a sample usage: 271 272 ``` json 273 { 274 "qemuargs": [ 275 [ "-m", "1024M" ], 276 [ "--no-acpi", "" ], 277 [ 278 "-netdev", 279 "user,id=mynet0,", 280 "hostfwd=hostip:hostport-guestip:guestport", 281 "" 282 ], 283 [ "-device", "virtio-net,netdev=mynet0" ] 284 ] 285 } 286 ``` 287 288 would produce the following (not including other defaults supplied by the 289 builder and not otherwise conflicting with the qemuargs): 290 291 ``` text 292 qemu-system-x86 -m 1024m --no-acpi -netdev user,id=mynet0,hostfwd=hostip:hostport-guestip:guestport -device virtio-net,netdev=mynet0" 293 ``` 294 295 ~> **Windows Users:** [QEMU for Windows](https://qemu.weilnetz.de/) builds are available though an environmental variable does need 296 to be set for QEMU for Windows to redirect stdout to the console instead of stdout.txt. 297 298 The following shows the environment variable that needs to be set for Windows QEMU support: 299 300 ``` text 301 setx SDL_STDIO_REDIRECT=0 302 ``` 303 304 You can also use the `SSHHostPort` template variable to produce a packer 305 template that can be invoked by `make` in parallel: 306 307 ``` json 308 { 309 "qemuargs": [ 310 [ "-netdev", "user,hostfwd=tcp::{{ .SSHHostPort }}-:22,id=forward"], 311 [ "-device", "virtio-net,netdev=forward,id=net0"] 312 ] 313 } 314 ``` 315 316 `make -j 3 my-awesome-packer-templates` spawns 3 packer processes, each of which 317 will bind to their own SSH port as determined by each process. This will also 318 work with WinRM, just change the port forward in `qemuargs` to map to WinRM's 319 default port of `5985` or whatever value you have the service set to listen on. 320 321 - `use_backing_file` (boolean) - Only applicable when `disk_image` is `true` 322 and `format` is `qcow2`, set this option to `true` to create a new QCOW2 323 file that uses the file located at `iso_url` as a backing file. The new file 324 will only contain blocks that have changed compared to the backing file, so 325 enabling this option can significantly reduce disk usage. 326 327 - `use_default_display` (boolean) - If true, do not pass a `-display` option 328 to qemu, allowing it to choose the default. This may be needed when running 329 under macOS, and getting errors about `sdl` not being available. 330 331 - `shutdown_command` (string) - The command to use to gracefully shut down the 332 machine once all the provisioning is done. By default this is an empty 333 string, which tells Packer to just forcefully shut down the machine unless a 334 shutdown command takes place inside script so this may safely be omitted. It 335 is important to add a `shutdown_command`. By default Packer halts the virtual 336 machine and the file system may not be sync'd. Thus, changes made in a 337 provisioner might not be saved. If one or more scripts require a reboot it is 338 suggested to leave this blank since reboots may fail and specify the final 339 shutdown command in your last script. 340 341 - `shutdown_timeout` (string) - The amount of time to wait after executing the 342 `shutdown_command` for the virtual machine to actually shut down. If it 343 doesn't shut down in this time, it is an error. By default, the timeout is 344 `5m` or five minutes. 345 346 - `skip_compaction` (boolean) - Packer compacts the QCOW2 image using 347 `qemu-img convert`. Set this option to `true` to disable compacting. 348 Defaults to `false`. 349 350 - `ssh_host_port_min` and `ssh_host_port_max` (number) - The minimum and 351 maximum port to use for the SSH port on the host machine which is forwarded 352 to the SSH port on the guest machine. Because Packer often runs in parallel, 353 Packer will choose a randomly available port in this range to use as the 354 host port. By default this is `2222` to `4444`. 355 356 - `vm_name` (string) - This is the name of the image (QCOW2 or IMG) file for 357 the new virtual machine. By default this is `packer-BUILDNAME`, where 358 "BUILDNAME" is the name of the build. Currently, no file extension will be 359 used unless it is specified in this option. 360 361 - `vnc_bind_address` (string / IP address) - The IP address that should be 362 binded to for VNC. By default packer will use `127.0.0.1` for this. If you 363 wish to bind to all interfaces use `0.0.0.0`. 364 365 - `vnc_port_min` and `vnc_port_max` (number) - The minimum and maximum port 366 to use for VNC access to the virtual machine. The builder uses VNC to type 367 the initial `boot_command`. Because Packer generally runs in parallel, 368 Packer uses a randomly chosen port in this range that appears available. By 369 default this is `5900` to `6000`. The minimum and maximum ports are inclusive. 370 371 ## Boot Command 372 373 The `boot_command` configuration is very important: it specifies the keys to 374 type when the virtual machine is first booted in order to start the OS 375 installer. This command is typed after `boot_wait`, which gives the virtual 376 machine some time to actually load the ISO. 377 378 As documented above, the `boot_command` is an array of strings. The strings are 379 all typed in sequence. It is an array only to improve readability within the 380 template. 381 382 The boot command is "typed" character for character over a VNC connection to the 383 machine, simulating a human actually typing the keyboard. 384 385 -> Keystrokes are typed as separate key up/down events over VNC with a 386 default 100ms delay. The delay alleviates issues with latency and CPU 387 contention. You can tune this delay on a per-builder basis by specifying 388 "boot_key_interval" in your Packer template, for example: 389 390 ``` 391 { 392 "builders": [ 393 { 394 "type": "qemu", 395 "boot_key_interval": "10ms" 396 ... 397 } 398 ] 399 } 400 ``` 401 402 <%= partial "partials/builders/boot-command" %> 403 404 Example boot command. This is actually a working boot command used to start an 405 CentOS 6.4 installer: 406 407 ``` json 408 { 409 "boot_command": [ 410 "<tab><wait>", 411 " ks=http://{{ .HTTPIP }}:{{ .HTTPPort }}/centos6-ks.cfg<enter>" 412 ] 413 } 414 ``` 415 416 For more examples of various boot commands, see the sample projects from our 417 [community templates page](/community-tools.html#templates). 418 419 ### Troubleshooting 420 421 Some users have experienced errors complaining about invalid keymaps. This 422 seems to be related to having a `common` directory or file in the directory 423 they've run Packer in, like the packer source directory. This appears to be an 424 upstream bug with qemu, and the best solution for now is to remove the 425 file/directory or run in another directory. 426 427 Some users have reported issues with incorrect keymaps using qemu version 2.11. 428 This is a bug with qemu, and the solution is to upgrade, or downgrade to 2.10.1 429 or earlier.