generate virtualbox-vm docs instead of letting them be copy pasted
This commit is contained in:
Megan Marsh
parent
0f3e749f1a
commit
480c938162
|
|
@ -1,3 +1,4 @@
|
|||
//go:generate struct-markdown
|
||||
//go:generate mapstructure-to-hcl2 -type Config
|
||||
|
||||
package vm
|
||||
|
|
@ -30,16 +31,61 @@ type Config struct {
|
|||
vboxcommon.VBoxManageConfig `mapstructure:",squash"`
|
||||
vboxcommon.VBoxVersionConfig `mapstructure:",squash"`
|
||||
|
||||
GuestAdditionsMode string `mapstructure:"guest_additions_mode"`
|
||||
GuestAdditionsPath string `mapstructure:"guest_additions_path"`
|
||||
// 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.
|
||||
GuestAdditionsMode string `mapstructure:"guest_additions_mode"`
|
||||
// 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) where the `Version`
|
||||
// variable is replaced with the VirtualBox version.
|
||||
GuestAdditionsPath string `mapstructure:"guest_additions_path"`
|
||||
// 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.
|
||||
GuestAdditionsSHA256 string `mapstructure:"guest_additions_sha256"`
|
||||
GuestAdditionsURL string `mapstructure:"guest_additions_url"`
|
||||
VMName string `mapstructure:"vm_name"`
|
||||
AttachSnapshot string `mapstructure:"attach_snapshot"`
|
||||
TargetSnapshot string `mapstructure:"target_snapshot"`
|
||||
DeleteTargetSnapshot bool `mapstructure:"force_delete_snapshot"`
|
||||
KeepRegistered bool `mapstructure:"keep_registered"`
|
||||
SkipExport bool `mapstructure:"skip_export"`
|
||||
// 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 attempt to find the guest additions ISO
|
||||
// on the local file system. If it is not available locally, the builder will
|
||||
// download the proper guest additions ISO from the internet.
|
||||
GuestAdditionsURL string `mapstructure:"guest_additions_url" required:"false"`
|
||||
// This is the name of the virtual machine to which the
|
||||
// builder shall attach.
|
||||
VMName string `mapstructure:"vm_name" required:"true"`
|
||||
// Default to `null/empty`. The name of an
|
||||
// **existing** snapshot to which the builder shall attach the VM before
|
||||
// starting it. If no snapshot is specified the builder will simply start the
|
||||
// VM from it's current state i.e. snapshot.
|
||||
AttachSnapshot string `mapstructure:"attach_snapshot" required:"false"`
|
||||
// Default to `null/empty`. The name of the
|
||||
// snapshot which shall be created after all provisioners has been run by the
|
||||
// builder. If no target snapshot is specified and `keep_registered` is set to
|
||||
// `false` the builder will revert to the snapshot to which the VM was attached
|
||||
// before the builder has been executed, which will revert all changes applied
|
||||
// by the provisioners. This is handy if only an export shall be created and no
|
||||
// further snapshot is required.
|
||||
TargetSnapshot string `mapstructure:"target_snapshot" required:"false"`
|
||||
// Defaults to `false`. If set to `true`,
|
||||
// overwrite an existing `target_snapshot`. Otherwise the builder will yield an
|
||||
// error if the specified target snapshot already exists.
|
||||
DeleteTargetSnapshot bool `mapstructure:"force_delete_snapshot" required:"false"`
|
||||
// Set this to `true` if you would like to keep
|
||||
// the VM attached to the snapshot specified by `attach_snapshot`. Otherwise
|
||||
// the builder will reset the VM to the snapshot to which the VM was attached
|
||||
// before the builder started. Defaults to `false`.
|
||||
KeepRegistered bool `mapstructure:"keep_registered" required:"false"`
|
||||
// Defaults to `false`. When enabled, Packer will
|
||||
// not export the VM. Useful if the builder should be applied again on the created
|
||||
// target snapshot.
|
||||
SkipExport bool `mapstructure:"skip_export" required:"false"`
|
||||
|
||||
ctx interpolate.Context
|
||||
}
|
||||
|
|
|
|||
|
|
@ -92,13 +92,13 @@ type FlatConfig struct {
|
|||
GuestAdditionsMode *string `mapstructure:"guest_additions_mode" cty:"guest_additions_mode"`
|
||||
GuestAdditionsPath *string `mapstructure:"guest_additions_path" cty:"guest_additions_path"`
|
||||
GuestAdditionsSHA256 *string `mapstructure:"guest_additions_sha256" cty:"guest_additions_sha256"`
|
||||
GuestAdditionsURL *string `mapstructure:"guest_additions_url" cty:"guest_additions_url"`
|
||||
VMName *string `mapstructure:"vm_name" cty:"vm_name"`
|
||||
AttachSnapshot *string `mapstructure:"attach_snapshot" cty:"attach_snapshot"`
|
||||
TargetSnapshot *string `mapstructure:"target_snapshot" cty:"target_snapshot"`
|
||||
DeleteTargetSnapshot *bool `mapstructure:"force_delete_snapshot" cty:"force_delete_snapshot"`
|
||||
KeepRegistered *bool `mapstructure:"keep_registered" cty:"keep_registered"`
|
||||
SkipExport *bool `mapstructure:"skip_export" cty:"skip_export"`
|
||||
GuestAdditionsURL *string `mapstructure:"guest_additions_url" required:"false" cty:"guest_additions_url"`
|
||||
VMName *string `mapstructure:"vm_name" required:"true" cty:"vm_name"`
|
||||
AttachSnapshot *string `mapstructure:"attach_snapshot" required:"false" cty:"attach_snapshot"`
|
||||
TargetSnapshot *string `mapstructure:"target_snapshot" required:"false" cty:"target_snapshot"`
|
||||
DeleteTargetSnapshot *bool `mapstructure:"force_delete_snapshot" required:"false" cty:"force_delete_snapshot"`
|
||||
KeepRegistered *bool `mapstructure:"keep_registered" required:"false" cty:"keep_registered"`
|
||||
SkipExport *bool `mapstructure:"skip_export" required:"false" cty:"skip_export"`
|
||||
}
|
||||
|
||||
// FlatMapstructure returns a new FlatConfig.
|
||||
|
|
|
|||
|
|
@ -55,219 +55,70 @@ 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.
|
||||
|
||||
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.
|
||||
In addition to the options listed here, a
|
||||
[communicator](/docs/templates/communicator) can be configured for this
|
||||
builder.
|
||||
|
||||
|
||||
### Required:
|
||||
|
||||
- `vm_name` (string) - This is the name of the virtual machine to which the
|
||||
builder shall attach.
|
||||
@include 'builder/virtualbox/vm/Config-required.mdx'
|
||||
|
||||
### Optional:
|
||||
|
||||
- `attach_snapshot` (string) - Default to `null/empty`. The name of an
|
||||
**existing** snapshot to which the builder shall attach the VM before
|
||||
starting it. If no snapshot is specified the builder will simply start the
|
||||
VM from it's current state i.e. snapshot.
|
||||
@include 'builder/virtualbox/vm/Config-not-required.mdx'
|
||||
|
||||
- `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.
|
||||
@include 'builder/virtualbox/common/VBoxVersionConfig-not-required.mdx'
|
||||
|
||||
- `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.
|
||||
#### Optional:
|
||||
|
||||
- `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:
|
||||
@include 'builder/virtualbox/common/ShutdownConfig-not-required.mdx'
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "virtualbox-vm",
|
||||
"export_opts": [
|
||||
"--manifest",
|
||||
"--vsys",
|
||||
"0",
|
||||
"--description",
|
||||
"{{user `vm_description`}}",
|
||||
"--version",
|
||||
"{{user `vm_version`}}"
|
||||
],
|
||||
"format": "ova"
|
||||
}
|
||||
```
|
||||
### Http directory configuration
|
||||
|
||||
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):
|
||||
@include 'common/HTTPConfig.mdx'
|
||||
|
||||
```shell
|
||||
vm_description='some
|
||||
multiline
|
||||
description'
|
||||
#### Optional:
|
||||
|
||||
vm_version='0.2.0'
|
||||
@include 'common/HTTPConfig-not-required.mdx'
|
||||
|
||||
packer build \
|
||||
-var "vm_description=${vm_description}" \
|
||||
-var "vm_version=${vm_version}" \
|
||||
"packer_conf.json"
|
||||
```
|
||||
### Floppy configuration
|
||||
|
||||
- `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.
|
||||
@include 'common/FloppyConfig.mdx'
|
||||
|
||||
- `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:
|
||||
|
||||
- `force_delete_snapshot` (boolean) - Defaults to `false`. If set to `true`,
|
||||
overwrite an existing `target_snapshot`. Otherwise the builder will yield an
|
||||
error if the specified target snapshot already exists.
|
||||
@include 'common/FloppyConfig-not-required.mdx'
|
||||
|
||||
- `format` (string) - Either `ovf` or `ova`, this specifies the output format
|
||||
of the exported virtual machine. This defaults to `ovf`.
|
||||
### Export configuration
|
||||
|
||||
- `guest_additions_interface` (string) - The interface type to use to mount
|
||||
guest additions when `guest_additions_mode` is set to `attach`. Will
|
||||
default to the value set in `iso_interface`, if `iso_interface` is set.
|
||||
Will default to "ide", if `iso_interface` is not set. Options are "ide" and
|
||||
"sata".
|
||||
#### Optional:
|
||||
|
||||
- `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.
|
||||
@include 'builder/virtualbox/common/ExportConfig-not-required.mdx'
|
||||
|
||||
- `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) where the `Version`
|
||||
variable is replaced with the VirtualBox version.
|
||||
### Output configuration
|
||||
|
||||
- `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.
|
||||
#### Optional:
|
||||
|
||||
- `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 attempt to find the guest additions ISO
|
||||
on the local file system. If it is not available locally, the builder will
|
||||
download the proper guest additions ISO from the internet.
|
||||
@include 'builder/virtualbox/common/OutputConfig-not-required.mdx'
|
||||
|
||||
- `guest_os_type` (string) - The guest OS type being installed. By default
|
||||
this is `other`, but you can get _dramatic_ performance improvements by
|
||||
setting this to the proper value. To view all available values for this run
|
||||
`VBoxManage list ostypes`. Setting the correct value hints to VirtualBox how
|
||||
to optimize the virtual hardware to work best with that operating system.
|
||||
### Run configuration
|
||||
|
||||
- `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.
|
||||
#### Optional:
|
||||
|
||||
- `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.
|
||||
|
||||
- `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.
|
||||
|
||||
- `keep_registered` (boolean) - Set this to `true` if you would like to keep
|
||||
the VM attached to the snapshot specified by `attach_snapshot`. Otherwise
|
||||
the builder will reset the VM to the snapshot to which the VM was attached
|
||||
before the builder started. 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.
|
||||
|
||||
- `skip_export` (boolean) - Defaults to `false`. When enabled, Packer will
|
||||
not export the VM. Useful if the builder should be applied again on the created
|
||||
target snapshot.
|
||||
|
||||
@include 'builder/virtualbox/common/CommConfig-not-required.mdx'
|
||||
|
||||
- `target_snapshot` (string) - Default to `null/empty`. The name of the
|
||||
snapshot which shall be created after all provisioners has been run by the
|
||||
builder. If no target snapshot is specified and `keep_registered` is set to
|
||||
`false` the builder will revert to the snapshot to which the VM was attached
|
||||
before the builder has been executed, which will revert all changes applied
|
||||
by the provisioners. This is handy if only an export shall be created and no
|
||||
further snapshot is required.
|
||||
|
||||
- `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), 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 uploaded into the home
|
||||
directory. Set to an empty string to skip uploading this file, which can be
|
||||
useful when using the `none` communicator.
|
||||
|
||||
- `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.
|
||||
@include 'builder/virtualbox/common/RunConfig-not-required.mdx'
|
||||
|
||||
### Shutdown configuration
|
||||
|
||||
|
|
@ -275,16 +126,38 @@ builder.
|
|||
|
||||
@include 'builder/virtualbox/common/ShutdownConfig-not-required.mdx'
|
||||
|
||||
## Boot Command
|
||||
### Hardware configuration
|
||||
|
||||
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.
|
||||
#### Optional:
|
||||
|
||||
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.
|
||||
@include 'builder/virtualbox/common/HWConfig-not-required.mdx'
|
||||
|
||||
### VBox Manage configuration
|
||||
|
||||
#### Optional:
|
||||
|
||||
@include 'builder/virtualbox/common/VBoxManageConfig-not-required.mdx'
|
||||
|
||||
### Communicator configuration
|
||||
|
||||
#### Optional common fields:
|
||||
|
||||
@include 'helper/communicator/Config-not-required.mdx'
|
||||
|
||||
@include 'builder/virtualbox/common/CommConfig-not-required.mdx'
|
||||
|
||||
#### Optional SSH fields:
|
||||
|
||||
@include 'helper/communicator/SSH-not-required.mdx'
|
||||
|
||||
#### Optional WinRM fields:
|
||||
|
||||
@include 'helper/communicator/WinRM-not-required.mdx'
|
||||
|
||||
|
||||
### Boot Configuration
|
||||
|
||||
@include 'common/bootcommand/BootConfig.mdx'
|
||||
|
||||
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
|
||||
|
|
@ -304,6 +177,10 @@ contention. If you notice missing keys, you can tune this delay by specifying
|
|||
}
|
||||
```
|
||||
|
||||
#### Optional:
|
||||
|
||||
@include 'common/bootcommand/BootConfig-not-required.mdx'
|
||||
|
||||
@include 'builders/boot-command.mdx'
|
||||
|
||||
@include 'builders/virtualbox-ssh-key-pair.mdx'
|
||||
|
|
|
|||
Loading…
Reference in New Issue