Configuring Packer

Packer's home directory

Plugins and core configuration files can exist in the home directory of Packer. The home directory of Packer will be the first one of the following env values to be set :

Packer's config file

Packer can optionally read a JSON file for the end user to set core settings. The config file of Packer will be looked up on the following paths:

It is not an error if no config file was found.

Packer's config directory

Packer's configuration directory can potentially contain plugins and internal Packer files. The config dir of Packer will be looked up on the following paths:

Examples:

• On a 'unix' system, if the $PACKER_CONFIG_DIR env var is set to /home/packer, the config directory will be: /home/packer/.packer.d/ and other values will not be checked.
• On a 'unix' system, if the HOME env var is /home/azr or the USER env var is azr, then the config directory will default to /home/azr/.packer.d/.
• On a 'windows' system, if the PACKER_CONFIG_DIR env var is set to C:/,the config directory will be: C:/packer.d/ and other values will not be checked.

Packer's plugin directory

Plugins will usually be located in the PACKER_HOME_DIR.

• packer init will install plugins in the last directory in the following numbered list.

• During the initialization of Packer, any plugin required in the required_plugins section will be looked up in all entries of the following list. First plugin found takes precedence. Two binaries of the same plugin with two different version will be considered as two different plugins. Highest found version matching required_plugins will be taken into consideration.

1. The directory where packer is, or the executable directory.
2. The current working directory. (".")
3. The PACKER_HOME_DIR/plugins directory. PACKERHOME_DIR refers to Packer's home directory_, if it could be found.
4. The director(y/ies) under the PACKER_PLUGIN_PATH env var, if PACKER_PLUGIN_PATH is set.

Using the following example :

    required_plugins {
      happycloud = {
        version = ">= 2.7.0"
        source = "github.com/azr/happycloud"
      }
    }

The plugin getter will then install the binaries in the following location for a system with no PACKER_PLUGIN_PATH env var set.

• PACKER_HOME_DIR/plugins/github.com/hashicorp/happycloud/

During initialization, on a darwin_amd64 system, Packer will look-up for the following files:

• PACKER_EXEC_DIR/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64
• ./github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64
• PACKER_HOME_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64
• PACKER_PLUGIN_PATH/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64
• ./packer-plugin-happycloud

The first plugin-name/version files found will take precedence.

For plugins located under the github.com/azr/happycloud/ directory structure an accompanying SHA256SUM file will be required in order for packer init to ensure the plugin being loaded has not been tampered with. The SHA256SUM file will be automatically generated when a plugin is installed via packer init if the plugin was installed manually into PACKER_HOME_DIR/plugins/github.com/azr/happycloud/ then the file PACKER_HOME_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64_SHA256SUM must be generated manually as well.

The format of the configuration file is basic JSON.

Packer's cache directory

Packer uses a cache directory to download large files and for logistics around large file download. By default, Packer caches things in the current directory, under: ./packer_cache/. This can be changed by setting the PACKER_CACHE_DIR env var. It is recommended to share the same Packer cache dir across your builds if you have multiple builds doing similar things to avoid downloading the same ISO twice for example.

Packer config file configuration Reference

Below is the list of all available configuration parameters for the core configuration file. None of these are required, since all have defaults.

• plugin_min_port and plugin_max_port (number) - These are the minimum and maximum ports that Packer uses for communication with plugins, since plugin communication happens over TCP connections on your local host. By default these are 10,000 and 25,000, respectively. Be sure to set a fairly wide range here, since Packer can easily use over 25 ports on a single run.

• builders, commands, post-processors, and provisioners are objects that are used to install plugins. The details of how exactly these are set is covered in more detail in the installing plugins documentation page. It is instead recommended to use HCL2 required_plugins and the packer init command to install plugins; if you are using both, the required_plugin config will take precedence.

Full list of Environment Variables usable for Packer

Packer uses a variety of environmental variables. A listing and description of each can be found below:

• PACKER_CACHE_DIR - The location of the Packer cache. This defaults to ./packer_cache/. Relative paths can be used. Some plugins can cache large files like ISOs in the cache dir.

• PACKER_CONFIG - The location of the core configuration file. The format of the configuration file is basic JSON. See Packer's Config file.

• PACKER_CONFIG_DIR - The location for the home directory of Packer. See Packer's home directory for more.

• PACKER_GITHUB_API_TOKEN - When using Packer init on HCL2 templates, Packer queries the public API from Github which limits the amount of queries on can set the PACKER_GITHUB_API_TOKEN with a Github Token to make it higher.

• PACKER_LOG - Setting this to any value other than "" (empty string) or "0" will enable the logger. See the debugging page.

• PACKER_LOG_PATH - The location of the log file. Note: PACKER_LOG must be set for any logging to occur. See the debugging page.

• PACKER_NO_COLOR - Setting this to any value will disable color in the terminal.

• PACKER_PLUGIN_MAX_PORT - The maximum port that Packer uses for communication with plugins, since plugin communication happens over TCP connections on your local host. The default is 25,000. This can also be set using the Packer's config file, see the config file configuration reference for more.

• PACKER_PLUGIN_MIN_PORT - The minimum port that Packer uses for communication with plugins, since plugin communication happens over TCP connections on your local host. The default is 10,000. This can also be set using the Packer's config file, see the config file configuration reference for more.

• PACKER_PLUGIN_PATH - a PATH variable for finding third-party packer plugins. For example: ~/custom-dir-1:~/custom-dir-2. Separate directories in the PATH string using a colon (:) on posix systems and a semicolon (;) on windows systems. The above example path would be able to find a provisioner named packer-provisioner-foo in either ~/custom-dir-1/packer-provisioner-foo or ~/custom-dir-2/packer-provisioner-foo. See the documentation on plugin directories for more.

• CHECKPOINT_DISABLE - When Packer is invoked it sometimes calls out to checkpoint.hashicorp.com to look for new versions of Packer. If you want to disable this for security or privacy reasons, you can set this environment variable to 1.

• TMPDIR (Unix) / TMP TEMP USERPROFILE (Windows) - The location of the directory used for temporary files (defaults to /tmp on Linux/Unix and %USERPROFILE%\AppData\Local\Temp on Windows Vista and above). It might be necessary to customize it when working with large files since /tmp is a memory-backed filesystem in some Linux distributions in which case /var/tmp might be preferred.