From 20a152d4aa11e8835fd34310fabf37232e90a9f7 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 12 Jun 2019 16:02:02 +0200 Subject: [PATCH] add comments to common/iso_config.go from docs --- common/iso_config.go | 98 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 8 deletions(-) diff --git a/common/iso_config.go b/common/iso_config.go index a66042efc..435cfa3c7 100644 --- a/common/iso_config.go +++ b/common/iso_config.go @@ -8,15 +8,97 @@ import ( "github.com/hashicorp/packer/template/interpolate" ) -// ISOConfig contains configuration for downloading ISO images. +// By default, Packer will symlink, download or copy image files to the Packer +// cache into a "`hash($iso_url+$iso_checksum).$iso_target_extension`" file. +// Packer uses [hashicorp/go-getter](https://github.com/hashicorp/go-getter) in +// file mode in order to perform a download. +// +// go-getter supports the following protocols: +// +// * Local files +// * Git +// * Mercurial +// * HTTP +// * Amazon S3 +// +// +// \~> On windows - when referencing a local iso - if packer is running +// without symlinking rights, the iso will be copied to the cache folder. Read +// [Symlinks in Windows 10 +// !](https://blogs.windows.com/buildingapps/2016/12/02/symlinks-windows-10/) +// for more info. +// +// Examples: +// go-getter can guess the checksum type based on `iso_checksum` len. +// +// ``` json +// { +// "iso_checksum": "946a6077af6f5f95a51f82fdc44051c7aa19f9cfc5f737954845a6050543d7c2", +// "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso" +// } +// ``` +// +// ``` json +// { +// "iso_checksum_type": "file", +// "iso_checksum": "ubuntu.org/..../ubuntu-14.04.1-server-amd64.iso.sum", +// "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso" +// } +// ``` +// +// ``` json +// { +// "iso_checksum_url": "./shasums.txt", +// "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso" +// } +// ``` +// +// ``` json +// { +// "iso_checksum_type": "sha256", +// "iso_checksum_url": "./shasums.txt", +// "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso" +// } +// ``` +// type ISOConfig struct { - ISOChecksum string `mapstructure:"iso_checksum"` - ISOChecksumURL string `mapstructure:"iso_checksum_url"` - ISOChecksumType string `mapstructure:"iso_checksum_type"` - ISOUrls []string `mapstructure:"iso_urls"` - TargetPath string `mapstructure:"iso_target_path"` - TargetExtension string `mapstructure:"iso_target_extension"` - RawSingleISOUrl string `mapstructure:"iso_url"` + // The checksum for the ISO file or virtual hard drive file. The algorithm + // to use when computing the checksum can be optionally specified with + // `iso_checksum_type`. When `iso_checksum_type` is not set packer will + // guess the checksumming type based on `iso_checksum` length. + // `iso_checksum` can be also be a file or an URL, in which case + // `iso_checksum_type` must be set to `file`; the go-getter will download + // it and use the first hash found. + ISOChecksum string `mapstructure:"iso_checksum" required:"true"` + // An URL to a checksum file containing a checksum for the ISO file. At + // least one of `iso_checksum` and `iso_checksum_url` must be defined. + // `iso_checksum_url` will be ignored if `iso_checksum` is non empty. + ISOChecksumURL string `mapstructure:"iso_checksum_url"` + // The algorithm to be used when computing the checksum of the file + // specified in `iso_checksum`. Currently, valid values are "", "none", + // "md5", "sha1", "sha256", "sha512" or "file". Since the validity of ISO + // and virtual disk files are typically crucial to a successful build, + // Packer performs a check of any supplied media by default. While setting + // "none" will cause Packer to skip this check, corruption of large files + // such as ISOs and virtual hard drives can occur from time to time. As + // such, skipping this check is not recommended. `iso_checksum_type` must + // be set to `file` when `iso_checksum` is an url. + ISOChecksumType string `mapstructure:"iso_checksum_type"` + // A URL to the ISO containing the installation image or virtual hard drive + // (VHD or VHDX) file to clone. + RawSingleISOUrl string `mapstructure:"iso_url" required:"true"` + // Multiple URLs for the ISO to download. Packer will try these in order. + // If anything goes wrong attempting to download or while downloading a + // single URL, it will move on to the next. All URLs must point to the same + // file (same checksum). By default this is empty and `iso_url` is used. + // Only one of `iso_url` or `iso_urls` can be specified. + ISOUrls []string `mapstructure:"iso_urls"` + // The path where the iso should be saved after download. By default will + // go in the packer cache, with a hash of the original filename and + // checksum as its name. + TargetPath string `mapstructure:"iso_target_path"` + // The extension of the iso file after download. This defaults to `iso`. + TargetExtension string `mapstructure:"iso_target_extension"` } func (c *ISOConfig) Prepare(ctx *interpolate.Context) (warnings []string, errs []error) {