github.com/hashicorp/packer@v1.14.3/website/content/docs/configure.mdx (about)

     1  ---
     2  description: |
     3    Learn how to configure Packer's global behavior using environment variables.
     4  page_title: Configure Packer
     5  ---
     6  
     7  # Configure Packer
     8  
     9  This topic describes how to configure Packer. The default configurations are suitable for learning how to get started, but you should refer to this topic for guidance as you become more familiar with Packer.
    10  
    11  ## Overview
    12  
    13  You can set Packer-specific environment variables in a configuration file to configure Packer behavior globally. Install configuration files in the Packer configuration directory to implement the configurations. You can also install plugin files and their SHA256SUM files to the plugins subdirectory under the configuration directory. Refer to [Installing Plugins](/packer/docs/plugins/install) for instructions.
    14  
    15  You can also define Packer settings in a JSON configuration file and add it to the execution path. This configuration method is deprecated.
    16  
    17  ## Install a configuration file
    18  
    19  You can place internal configuration files into Packer's `config` directory. Packer checks the following paths for configuration files:
    20  
    21  | OS | Path | Notes |
    22  | --- | ---| --- |
    23  | Unix | `${HOME}/.config/packer/` | Packer follows the XDG base directory specification by default. As a result, Packer uses `$HOME/.config/packer` as the default directory when the `PACKER_CONFIG_DIR` environment variable is unset or empty. Packer ignores the XDG specification when the `PACKER_CONFIG_DIR` variable is set or when the installation uses legacy `.packer.d`-style directories, for example `$HOME/.packer.d/`. Refer to the [XDG specification](https://specifications.freedesktop.org/basedir-spec/latest/) for additional information. |
    24  | Windows | `%APPDATA%\packer.d\` | |
    25  
    26  
    27  ### Examples
    28  
    29  - **Unix**: If `$PACKER_CONFIG_DIR` is set to `/home/packer`, then the configuration directory is `/home/packer/.packer.d/`. Packer does not check other values.
    30  - **Windows**: If `PACKER_CONFIG_DIR` is set to `C:/`, then the configuration directory is `C:/packer.d/`. Packer does not check other values.
    31  
    32  
    33  <a id="packer-s-config-file"></a>
    34  
    35  ##  Install a JSON configuration file
    36  
    37  This installation method is deprecated since 1.7. Instead, use the [HCL2
    38  `required_plugins` block](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) to configure how Packer installs plugins. 
    39  
    40  You use a JSON file to set core Packer settings. Packer checks the following paths for the configuration file:
    41  
    42  | Unix                             | Windows                           |
    43  | -------------------------------- | --------------------------------- |
    44  | `${PACKER_CONFIG}`               | `%PACKER_CONFIG%`                 |
    45  | `${HOME}/.packerconfig`          | `%APPDATA%\packer.config\`        |
    46  
    47  
    48  ### JSON configuration file reference 
    49  
    50  Use basic JSON to configure the file. You can specify the configuration parameters for the core
    51  configuration file. All parameters are optional. None of these are required, since all have defaults.
    52  
    53  - `plugin_min_port`: Number that specifies the lowest port that Packer can use for communicating with plugins. Packer communicates with plugins over TCP or Unix sockets on your local host. Default is `10000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run.
    54  - `plugin_max_port`: Number that specifies highest port that Packer can for communicating with plugins. Packer communicates with plugins over TCP  connections on your local Unix host. Default is `25000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run.
    55  
    56  The [`packer init`](/packer/docs/commands/init) command takes precedence over JSON-configure settings when installing plugins.
    57  
    58  
    59  ## Configure the cache directory
    60  
    61  Packer uses a cache directory to download large files and for logistics around large file download. By default, Packer caches files in the `.packer_cache` folder of the current directory. Use the `PACKER_CACHE_DIR` environment variable to configure the cache directory. Refer to [`PACKER_CACHE_DIR`](/packer/docs/configure#packer_config_dir) for details.
    62  
    63  We recommend using the same Packer cache directory across your builds if multiple builds perform similar actions. This is to avoid downloading the same large file, such as an ISO, multiple times.
    64  
    65  
    66  ## Configuration reference
    67  
    68  Packer uses a variety of environmental variables. A listing and description of
    69  each can be found below:
    70  
    71  - `PACKER_CACHE_DIR` - The location of the Packer cache. This defaults to
    72    `./packer_cache/`. Relative paths can be used. Some plugins can cache large
    73    files like ISOs in the cache dir.
    74  
    75  - `PACKER_CONFIG` - The location of the core configuration file. The format
    76    of the configuration file is basic JSON. See [Packer's Config
    77    file](#packer-s-config-file).
    78  
    79  - `PACKER_CONFIG_DIR` - The location for the home directory of Packer. See
    80    [Packer's home directory](#packer-s-home-directory) for more.
    81  
    82  - `PACKER_GETTER_READ_TIMEOUT` - Override the timeout when a packer plugin
    83    tries to fetch a ISO. The default is `30m`. This is specified as a string with
    84    a duration suffix.  The plugin needs to be built on 
    85    [v0.6.0](https://github.com/hashicorp/packer-plugin-sdk/releases/tag/v0.6.0)
    86    and above of the SDK to be compatible with this variable.
    87  
    88  - `PACKER_GITHUB_API_TOKEN` - When using Packer init on HCL2 templates, Packer
    89    queries the public API from GitHub which has rate-limits on its APIs.
    90    You can set the `PACKER_GITHUB_API_TOKEN` environment variable
    91    with a GitHub Token to make it higher.
    92  
    93  - `PACKER_LOG` - Setting this to any value other than "" (empty string) or
    94    "0" will enable the logger. See the [debugging
    95    page](/packer/docs/debugging).
    96  
    97  - `PACKER_LOG_PATH` - The location of the log file. Note: `PACKER_LOG` must
    98    be set for any logging to occur. See the [debugging
    99    page](/packer/docs/debugging).
   100  
   101  - `PACKER_NO_COLOR` - Setting this to any value will disable color in the
   102    terminal.
   103  
   104  - `PACKER_PLUGIN_MAX_PORT` - The maximum port that Packer uses for
   105    communication with plugins, since plugin communication happens over TCP
   106    connections on your local host. The default is 25,000. This can also be set
   107    using the Packer's config file, see the [config file configuration
   108    reference](#packer-config-file-configuration-reference) for more.
   109  
   110  - `PACKER_PLUGIN_MIN_PORT` - The minimum port that Packer uses for
   111    communication with plugins, since plugin communication happens over TCP
   112    connections on your local host. The default is 10,000. This can also be set
   113    using the Packer's config file, see the [config file configuration
   114    reference](#packer-config-file-configuration-reference) for more.
   115  
   116  - `PACKER_PLUGIN_PATH` - a PATH variable for finding packer plugins. This takes
   117       precedence over `PACKER_CONFIG_DIR/plugins` for plugin discovery if
   118       defined. Plugin installation requires access to temporary files under
   119       `TMPDIR`. If the system's temp directory is non-writable or non-executable,
   120       refer to `TMPDIR` to override the location of the temporary file store used by
   121       Packer.
   122  
   123  - `CHECKPOINT_DISABLE` - When Packer is invoked it sometimes calls out to
   124    [checkpoint.hashicorp.com](https://checkpoint.hashicorp.com/) to look for
   125    new versions of Packer. If you want to disable this for security or privacy
   126    reasons, you can set this environment variable to `1`.
   127  
   128  - `TMPDIR` (Unix) / `TMP`, `TEMP`, `USERPROFILE` (Windows) - This specifies the
   129       directory for temporary files (defaulting to `/tmp` on Linux/Unix and
   130       `%USERPROFILE%\AppData\Local\Temp` on Windows Vista and later). Customizing
   131       this setting might be necessary for systems where the default temporary
   132       directory is either non-writable or non-executable.