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

     1  ---
     2  description: |
     3    Learn how to debug issues with Packer builds and plugins using `packer build`, logs, and other troubleshooting tools. 
     4  page_title: Debugging Packer
     5  ---
     6  
     7  # Debugging Packer Builds
     8  
     9  Using `packer build -on-error=ask` allows you to inspect failures and try out
    10  solutions before restarting the build.
    11  
    12  For remote builds with cloud providers like Amazon Web Services AMIs, debugging
    13  a Packer build can be eased greatly with `packer build -debug`. This disables
    14  parallelization and enables debug mode.
    15  
    16  Debug mode informs the builders that they should output debugging information.
    17  The exact behavior of debug mode is left to the builder. In general, builders
    18  usually will stop between each step, waiting for keyboard input before
    19  continuing. This will allow you to inspect state and so on.
    20  
    21  In debug mode once the remote instance is instantiated, Packer will emit to the
    22  current directory an ephemeral private SSH key as a .pem file. Using that you
    23  can `ssh -i <key.pem>` into the remote build instance and see what is going on
    24  for debugging. The key will only be emitted for cloud-based builders. The
    25  ephemeral key will be deleted at the end of the Packer run during cleanup.
    26  
    27  For a local builder, the SSH session initiated will be visible in the detail
    28  provided when `PACKER_LOG=1` environment variable is set prior to a build, and
    29  you can connect to the local machine using the userid and password defined in
    30  the kickstart or preseed associated with initializing the local VM.
    31  
    32  It should be noted that one of the options `-on-error` is to `retry`, the retry
    33  of the step in question has limitations:
    34  
    35  - the template Packer is building is **not** reloaded from file.
    36  - the resources specified from builders **are** reloaded from file.
    37  
    38  Check the specifics on your builder to confirm their behavior.
    39  
    40  ### Windows
    41  
    42  As of Packer 0.8.1 the default WinRM communicator will emit the password for a
    43  Remote Desktop Connection into your instance. This happens following the
    44  several minute pause as the instance is booted. Note a .pem key is still
    45  created for securely transmitting the password. Packer automatically decrypts
    46  the password for you in debug mode.
    47  
    48  ## Debugging Packer
    49  
    50  Issues occasionally arise where certain things may not work entirely correctly,
    51  or may not appear to work correctly. In these cases, it is sometimes helpful to
    52  see more details about what Packer is actually doing.
    53  
    54  Packer has detailed logs which can be enabled by setting the `PACKER_LOG`
    55  environmental variable to any value but `""` (empty string) and `"0"` like this
    56  `PACKER_LOG=1 packer build <config.json>`. This will cause detailed logs to
    57  appear on stderr. The logs contain log messages from Packer as well as any
    58  plugins that are being used. Log messages from plugins are prefixed by their
    59  application name.
    60  
    61  Note that because Packer is highly parallelized, log messages sometimes appear
    62  out of order, especially with respect to plugins. In this case, it is important
    63  to pay attention to the timestamp of the log messages to determine order.
    64  
    65  In addition to simply enabling the log, you can set `PACKER_LOG_PATH` in order
    66  to force the log to always go to a specific file when logging is enabled. Note
    67  that even when `PACKER_LOG_PATH` is set, `PACKER_LOG` must be set in order for
    68  any logging to be enabled.
    69  
    70  ### Debugging Plugins
    71  
    72  Each packer plugin runs in a separate process and communicates with RPC over a
    73  socket therefore using a debugger will not work (be complicated at least).
    74  
    75  But most of the Packer code is really simple and easy to follow with PACKER_LOG
    76  turned on. If that doesn't work adding some extra debug print outs when you have
    77  homed in on the problem is usually enough.
    78  
    79  ### Debugging Packer in Powershell/Windows
    80  
    81  In Windows you can set the detailed logs environmental variable `PACKER_LOG` or
    82  the log variable `PACKER_LOG_PATH` using PowerShell environment variables. For
    83  example:
    84  
    85  ```powershell
    86  $env:PACKER_LOG=1
    87  $env:PACKER_LOG_PATH="packerlog.txt"
    88  ```
    89  
    90  If you find a bug with Packer, please include the detailed log by using a
    91  service such as [gist](https://gist.github.com).
    92  
    93  ## Issues Installing Ubuntu Packages
    94  
    95  Issues may arise using and building Ubuntu AMIs where common packages that
    96  _should_ be installed from Ubuntu's Main repository are not found during a
    97  provisioner step:
    98  
    99  ```text
   100  amazon-ebs: No candidate version found for build-essential
   101  amazon-ebs: No candidate version found for build-essential
   102  ```
   103  
   104  This, obviously can cause problems where a build is unable to finish
   105  successfully as the proper packages cannot be provisioned correctly. The
   106  problem arises when cloud-init has not finished fully running on the source AMI
   107  by the time that packer starts any provisioning steps.
   108  
   109  Adding the following provisioner to the Packer template, allows for the
   110  cloud-init process to fully finish before packer starts provisioning the source
   111  AMI.
   112  
   113  ```json
   114  {
   115    "type": "shell",
   116    "inline": [
   117      "cloud-init status --wait"
   118    ]
   119  }
   120  ```
   121  
   122  ## Issues when using numerous Builders/Provisioners/Post-Processors
   123  
   124  Packer uses a separate process for each builder, provisioner, post-processor,
   125  and plugin. In certain cases, if you have too many of these, you can run out of
   126  [file descriptors](https://en.wikipedia.org/wiki/File_descriptor). This results
   127  in an error that might look like
   128  
   129  ```text
   130  error initializing provisioner 'powershell': fork/exec /files/go/bin/packer:
   131  too many open files
   132  ```
   133  
   134  On Unix systems, you can check what your file descriptor limit is with
   135  `ulimit -Sn`. You should check with your OS vendor on how to raise this limit.
   136  
   137  ## Issues when using long temp directory
   138  
   139  Packer uses Unix sockets internally, which are created inside the default
   140  directory for temporary files. Some operating systems place a limit on the
   141  length of the socket name, usually between 80 and 110 characters. If you get an
   142  error like this (for any builder, not just Docker):
   143  
   144  ```text
   145  Failed to initialize build 'docker': error initializing builder 'docker': plugin exited before we could connect
   146  ```
   147  
   148  you should try setting your temp directory to something shorter. This can be
   149  done through the `TMPDIR` environment variable.