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      -&gt; 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      -&gt; 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  ~&gt; **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  ~&gt; **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  -&gt; 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.