From b1ca1bfd04ce7b9afd4b381a493fef0a955fa8bb Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 19 Jun 2019 17:37:52 +0200 Subject: [PATCH] Document the virtualbox-ovf builder using partials --- .../docs/builders/virtualbox-ovf.html.md.erb | 270 +++--------------- 1 file changed, 46 insertions(+), 224 deletions(-) diff --git a/website/source/docs/builders/virtualbox-ovf.html.md.erb b/website/source/docs/builders/virtualbox-ovf.html.md.erb index 4953f4132..04ad6f2bb 100644 --- a/website/source/docs/builders/virtualbox-ovf.html.md.erb +++ b/website/source/docs/builders/virtualbox-ovf.html.md.erb @@ -54,256 +54,73 @@ provisioner might not be saved. ## Configuration Reference -There are many configuration options available for the VirtualBox builder. They -are organized below into two categories: required and optional. Within each -category, the available options are alphabetized and described. -In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) can be configured for this -builder. +There are many configuration options available for the builder. In addition to +the items listed here, you will want to look at the general configuration +references for [ISO](#iso-configuration), +[HTTP](#http-directory-configuration), +[Floppy](#floppy-configuration), +[Export](#export-configuration), +[Boot](#boot-configuration), +[Shutdown](#shutdown-configuration), +[Run](#run-configuration), +[Communicator](#communicator-configuration) +configuration references, which are +necessary for this build to succeed and can be found further down the page. ### Required: -- `source_path` (string) - The path to an OVF or OVA file that acts as the - source of this build. This currently must be a local file. +<%= partial "partials/builder/virtualbox/ovf/Config-required" %> -- `checksum` (string) - The checksum for the `source_path` file. The - algorithm to use when computing the checksum can be optionally specified - with `checksum_type`. When `checksum_type` is not set packer will guess the - checksumming type based on `checksum` length. `checksum` can be also be a - file or an URL, in which case `checksum_type` must be set to `file`; the - go-getter will download it and use the first hash found. +#### Optional: -### Optional: +<%= partial "partials/builder/virtualbox/ovf/Config-not-required" %> +<%= partial "partials/builder/virtualbox/common/VBoxVersionConfig-not-required" %> +<%= partial "partials/builder/virtualbox/common/GuestAdditionsConfig-not-required" %> -- `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. +### Http directory configuration -- `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/HTTPConfig" %> +#### Optional: -- `checksum_type` (string) - The type of the checksum specified in `checksum`. - Valid values are `none`, `md5`, `sha1`, `sha256`, or `sha512`. Although the - checksum will not be verified when `checksum_type` is set to "none", this is - not recommended since OVA files can be very large and corruption does happen - from time to time. +<%= partial "partials/common/HTTPConfig-not-required" %> -- `export_opts` (array of strings) - Additional options to pass to the - [VBoxManage - export](https://www.virtualbox.org/manual/ch09.html#vboxmanage-export). This - can be useful for passing product information to include in the resulting - appliance file. Packer JSON configuration file example: +### Floppy configuration - ``` json - { - "type": "virtualbox-ovf", - "export_opts": - [ - "--manifest", - "--vsys", "0", - "--description", "{{user `vm_description`}}", - "--version", "{{user `vm_version`}}" - ], - "format": "ova", - } - ``` +<%= partial "partials/common/FloppyConfig" %> - A VirtualBox [VM - description](https://www.virtualbox.org/manual/ch09.html#vboxmanage-export-ovf) - may contain arbitrary strings; the GUI interprets HTML formatting. However, - the JSON format does not allow arbitrary newlines within a value. Add a - multi-line description by preparing the string in the shell before the - packer call like this (shell `>` continuation character snipped for easier - copy & paste): +#### Optional: - ``` {.shell} +<%= partial "partials/common/FloppyConfig-not-required" %> - vm_description='some - multiline - description' +### Export configuration - vm_version='0.2.0' +#### Optional: - packer build \ - -var "vm_description=${vm_description}" \ - -var "vm_version=${vm_version}" \ - "packer_conf.json" - ``` +<%= partial "partials/builder/virtualbox/common/ExportConfig-not-required" %> -- `floppy_dirs` (array of strings) - A list of directories to place onto the - floppy disk recursively. This is similar to the `floppy_files` option except - that the directory structure is preserved. This is useful for when your - floppy disk includes drivers or if you just want to organize it's contents - as a hierarchy. Wildcard characters (\*, ?, and \[\]) are allowed. +### Output configuration -- `floppy_files` (array of strings) - A list of files to place onto a floppy - disk that is attached when the VM is booted. This is most useful for - unattended Windows installs, which look for an `Autounattend.xml` file on - removable media. By default, no floppy will be attached. All files listed in - this setting get placed into the root directory of the floppy and the floppy - is attached as the first floppy device. Currently, no support exists for - creating sub-directories on the floppy. Wildcard characters (\*, ?, - and \[\]) are allowed. Directory names are also allowed, which will add all - the files found in the directory to the floppy. +#### Optional: -- `format` (string) - Either `ovf` or `ova`, this specifies the output format - of the exported virtual machine. This defaults to `ovf`. +<%= partial "partials/builder/virtualbox/common/OutputConfig-not-required" %> -- `guest_additions_interface` (string) - The interface type to use to mount - guest additions when `guest_additions_mode` is set to `attach`. Will - default to "ide" if not set. Options are "ide" and "sata". +### Run configuration -- `guest_additions_mode` (string) - The method by which guest additions are - made available to the guest for installation. Valid options are `upload`, - `attach`, or `disable`. If the mode is `attach` the guest additions ISO will - be attached as a CD device to the virtual machine. If the mode is `upload` - the guest additions ISO will be uploaded to the path specified by - `guest_additions_path`. The default value is `upload`. If `disable` is used, - guest additions won't be downloaded, either. +#### Optional: -- `guest_additions_path` (string) - The path on the guest virtual machine - where the VirtualBox guest additions ISO will be uploaded. By default this - is `VBoxGuestAdditions.iso` which should upload into the login directory of - the user. This is a [configuration - template](/docs/templates/engine.html) where the `Version` - variable is replaced with the VirtualBox version. +<%= partial "partials/builder/virtualbox/common/RunConfig-not-required" %> -- `guest_additions_sha256` (string) - The SHA256 checksum of the guest - additions ISO that will be uploaded to the guest VM. By default the - checksums will be downloaded from the VirtualBox website, so this only needs - to be set if you want to be explicit about the checksum. +### Shutdown configuration -- `guest_additions_url` (string) - The URL to the guest additions ISO - to upload. This can also be a file URL if the ISO is at a local path. By - default the VirtualBox builder will go and download the proper guest - additions ISO from the internet. +#### Optional: -- `headless` (boolean) - Packer defaults to building VirtualBox 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. +<%= partial "partials/builder/virtualbox/common/ShutdownConfig-not-required" %> -- `http_directory` (string) - Path to a directory to serve using an - HTTP server. The files in this directory will be available over HTTP that - will be requestable from the virtual machine. This is useful for hosting - kickstart files and so on. By default this is an empty string, which means - no HTTP server will be started. The address and port of the HTTP server will - be available as variables in `boot_command`. This is covered in more detail - below. +### Boot Configuration -- `http_port_min` and `http_port_max` (number) - These are the minimum and - maximum port to use for the HTTP server started to serve the - `http_directory`. Because Packer often runs in parallel, Packer will choose - a randomly available port in this range to run the HTTP server. If you want - to force the HTTP server to be on one port, make this minimum and maximum - port the same. By default the values are `8000` and `9000`, respectively. - -- `import_flags` (array of strings) - Additional flags to pass to - `VBoxManage import`. This can be used to add additional command-line flags - such as `--eula-accept` to accept a EULA in the OVF. - -- `import_opts` (string) - Additional options to pass to the - `VBoxManage import`. This can be useful for passing `keepallmacs` or - `keepnatmacs` options for existing ovf images. - -- `keep_registered` (boolean) - Set this to `true` if you would like to keep - the VM registered with virtualbox. Defaults to `false`. - -- `output_directory` (string) - This is the path to the directory where the - resulting virtual machine will be created. This may be relative or absolute. - If relative, the path is relative to the working directory when `packer` - is executed. This directory must not exist or be empty prior to running - the builder. By default this is `output-BUILDNAME` where "BUILDNAME" is the - name of the build. - -- `post_shutdown_delay` (string) - The amount of time to wait after shutting - down the virtual machine. If you get the error - `Error removing floppy controller`, you might need to set this to `5m` - or so. By default, the delay is `0s` or disabled. - -- `shutdown_command` (string) - The command to use to gracefully shut down the - machine once all the provisioning is done. By default this is an empty - string, which tells Packer to just forcefully shut down the machine unless a - shutdown command takes place inside script so this may safely be omitted. If - one or more scripts require a reboot it is suggested to leave this blank - since reboots may fail and specify the final shutdown command in your - last script. - -- `shutdown_timeout` (string) - The amount of time to wait after executing the - `shutdown_command` for the virtual machine to actually shut down. If it - doesn't shut down in this time, it is an error. By default, the timeout is - `5m` or five minutes. - -- `skip_export` (boolean) - Defaults to `false`. When enabled, Packer will - not export the VM. Useful if the build output is not the resultant image, - but created inside the VM. - -- `ssh_host_port_min` and `ssh_host_port_max` (number) - The minimum and - maximum port to use for the SSH port on the host machine which is forwarded - to the SSH port on the guest machine. Because Packer often runs in parallel, - Packer will choose a randomly available port in this range to use as the - host port. By default this is `2222` to `4444`. - -- `ssh_skip_nat_mapping` (boolean) - Defaults to false. When enabled, Packer - does not setup forwarded port mapping for SSH requests and uses `ssh_port` - on the host to communicate to the virtual machine. - -- `target_path` (string) - The path where the OVA should be saved - after download. By default, it will go in the packer cache, with a hash of - the original filename as its name. - -- `vboxmanage` (array of array of strings) - Custom `VBoxManage` commands to - execute in order to further customize the virtual machine being created. The - value of this is an array of commands to execute. The commands are executed - in the order defined in the template. For each command, the command is - defined itself as an array of strings, where each string represents a single - argument on the command-line to `VBoxManage` (but excluding - `VBoxManage` itself). Each arg is treated as a [configuration - template](/docs/templates/engine.html), where the `Name` - variable is replaced with the VM name. More details on how to use - `VBoxManage` are below. - -- `vboxmanage_post` (array of array of strings) - Identical to `vboxmanage`, - except that it is run after the virtual machine is shutdown, and before the - virtual machine is exported. - -- `virtualbox_version_file` (string) - The path within the virtual machine to - upload a file that contains the VirtualBox version that was used to create - the machine. This information can be useful for provisioning. By default - this is `.vbox_version`, which will generally be upload it into the - home directory. Set to an empty string to skip uploading this file, which - can be useful when using the `none` communicator. - -- `vm_name` (string) - This is the name of the virtual machine when it is - imported as well as the name of the OVF file when the virtual machine - is exported. By default this is `packer-BUILDNAME`, where "BUILDNAME" is the - name of the build. - -- `vrdp_bind_address` (string / IP address) - The IP address that should be - binded to for VRDP. By default packer will use `127.0.0.1` for this. If you - wish to bind to all interfaces use `0.0.0.0`. - -- `vrdp_port_min` and `vrdp_port_max` (number) - The minimum and maximum port - to use for VRDP access to the virtual machine. Packer uses a randomly chosen - port in this range that appears available. By default this is `5900` to - `6000`. The minimum and maximum ports are inclusive. - -## Boot Command - -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`. - -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. +<%= partial "partials/common/bootcommand/BootConfig" %> +<%= partial "partials/common/bootcommand/VNCConfig" %> The boot command is sent to the VM through the `VBoxManage` utility in as few invocations as possible. We send each character in groups of 25, with a default @@ -316,13 +133,18 @@ contention. If you notice missing keys, you can tune this delay by specifying "builders": [ { "type": "virtualbox", - "boot_keygroup_interval": "500ms", + "boot_keygroup_interval": "500ms" ... } ] } ``` +#### Optional: + +<%= partial "partials/common/bootcommand/VNCConfig-not-required" %> +<%= partial "partials/common/bootcommand/BootConfig-not-required" %> + <%= partial "partials/builders/boot-command" %> <%= partial "partials/builders/virtualbox-ssh-key-pair" %>