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