From 480c938162a19abd833bfead9ebffc1ac5469409 Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Fri, 8 May 2020 12:36:00 -0700 Subject: [PATCH 1/2] generate virtualbox-vm docs instead of letting them be copy pasted --- builder/virtualbox/vm/config.go | 64 ++++- builder/virtualbox/vm/config.hcl2spec.go | 14 +- website/pages/docs/builders/virtualbox/vm.mdx | 261 +++++------------- 3 files changed, 131 insertions(+), 208 deletions(-) diff --git a/builder/virtualbox/vm/config.go b/builder/virtualbox/vm/config.go index e5f37392b..41ef57d20 100644 --- a/builder/virtualbox/vm/config.go +++ b/builder/virtualbox/vm/config.go @@ -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 } diff --git a/builder/virtualbox/vm/config.hcl2spec.go b/builder/virtualbox/vm/config.hcl2spec.go index 94d0e1a54..ffdfab042 100644 --- a/builder/virtualbox/vm/config.hcl2spec.go +++ b/builder/virtualbox/vm/config.hcl2spec.go @@ -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. diff --git a/website/pages/docs/builders/virtualbox/vm.mdx b/website/pages/docs/builders/virtualbox/vm.mdx index dbfbb0154..f491e4f0f 100644 --- a/website/pages/docs/builders/virtualbox/vm.mdx +++ b/website/pages/docs/builders/virtualbox/vm.mdx @@ -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' From 2733109294ded7d1d5db66c8acac04341b9ed00b Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Fri, 8 May 2020 12:36:20 -0700 Subject: [PATCH 2/2] add generated docs --- .../virtualbox/vm/Config-not-required.mdx | 54 +++++++++++++++++++ .../builder/virtualbox/vm/Config-required.mdx | 5 ++ .../partials/builder/virtualbox/vm/Config.mdx | 2 + 3 files changed, 61 insertions(+) create mode 100644 website/pages/partials/builder/virtualbox/vm/Config-not-required.mdx create mode 100644 website/pages/partials/builder/virtualbox/vm/Config-required.mdx create mode 100644 website/pages/partials/builder/virtualbox/vm/Config.mdx diff --git a/website/pages/partials/builder/virtualbox/vm/Config-not-required.mdx b/website/pages/partials/builder/virtualbox/vm/Config-not-required.mdx new file mode 100644 index 000000000..5e53a59db --- /dev/null +++ b/website/pages/partials/builder/virtualbox/vm/Config-not-required.mdx @@ -0,0 +1,54 @@ + + +- `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. + +- `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. + +- `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. + +- `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. + +- `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. + +- `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. + +- `force_delete_snapshot` (bool) - 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. + +- `keep_registered` (bool) - 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`. + +- `skip_export` (bool) - Defaults to `false`. When enabled, Packer will + not export the VM. Useful if the builder should be applied again on the created + target snapshot. + \ No newline at end of file diff --git a/website/pages/partials/builder/virtualbox/vm/Config-required.mdx b/website/pages/partials/builder/virtualbox/vm/Config-required.mdx new file mode 100644 index 000000000..3743c6d6a --- /dev/null +++ b/website/pages/partials/builder/virtualbox/vm/Config-required.mdx @@ -0,0 +1,5 @@ + + +- `vm_name` (string) - This is the name of the virtual machine to which the + builder shall attach. + \ No newline at end of file diff --git a/website/pages/partials/builder/virtualbox/vm/Config.mdx b/website/pages/partials/builder/virtualbox/vm/Config.mdx new file mode 100644 index 000000000..01a0b80df --- /dev/null +++ b/website/pages/partials/builder/virtualbox/vm/Config.mdx @@ -0,0 +1,2 @@ + +Config is the configuration structure for the builder.