github.com/ratanraj/packer@v1.3.2/website/source/docs/provisioners/file.html.md (about)

     1  ---
     2  description: |
     3      The file Packer provisioner uploads files to machines built by Packer. The
     4      recommended usage of the file provisioner is to use it to upload files, and
     5      then use shell provisioner to move them to the proper place, set permissions,
     6      etc.
     7  layout: docs
     8  page_title: 'File - Provisioners'
     9  sidebar_current: 'docs-provisioners-file'
    10  ---
    11  
    12  # File Provisioner
    13  
    14  Type: `file`
    15  
    16  The file Packer provisioner uploads files to machines built by Packer. The
    17  recommended usage of the file provisioner is to use it to upload files, and then
    18  use [shell provisioner](/docs/provisioners/shell.html) to move them to the
    19  proper place, set permissions, etc.
    20  
    21  The file provisioner can upload both single files and complete directories.
    22  
    23  ## Basic Example
    24  
    25  ``` json
    26  {
    27    "type": "file",
    28    "source": "app.tar.gz",
    29    "destination": "/tmp/app.tar.gz"
    30  }
    31  ```
    32  
    33  ## Configuration Reference
    34  
    35  The available configuration options are listed below.
    36  
    37  ### Required
    38  
    39  -   `source` (string) - The path to a local file or directory to upload to
    40      the machine. The path can be absolute or relative. If it is relative, it is
    41      relative to the working directory when Packer is executed. If this is a
    42      directory, the existence of a trailing slash is important. Read below on
    43      uploading directories.
    44  
    45  -   `destination` (string) - The path where the file will be uploaded to in
    46      the machine. This value must be a writable location and any parent
    47      directories must already exist. If the source is a file, it's a good idea to
    48      make the destination a file as well, but if you set your destination as a
    49      directory, at least make sure that the destination ends in a trailing slash
    50      so that Packer knows to use the source's basename in the final upload path.
    51      Failure to do so may cause Packer to fail on file uploads. If the
    52      destination file already exists, it will be overwritten.
    53  
    54  -   `direction` (string) - The direction of the file transfer. This defaults to
    55      "upload". If it is set to "download" then the file "source" in the machine
    56      will be downloaded locally to "destination"
    57  
    58  ### Optional
    59  
    60  -   `generated` (boolean) - For advanced users only. If true, check the file
    61      existence only before uploading, rather than upon pre-build validation.
    62      This allows to upload files created on-the-fly. This defaults to false. We
    63      don't recommend using this feature, since it can cause Packer to become
    64      dependent on system state. We would prefer you generate your files before
    65      the Packer run, but realize that there are situations where this may be
    66      unavoidable.
    67  
    68  ## Directory Uploads
    69  
    70  The file provisioner is also able to upload a complete directory to the remote
    71  machine. When uploading a directory, there are a few important things you should
    72  know.
    73  
    74  First, the destination directory must already exist. If you need to create it,
    75  use a shell provisioner just prior to the file provisioner in order to create
    76  the directory. If the destination directory does not exist, the file
    77  provisioner may succeed, but it will have undefined results.
    78  
    79  Next, the existence of a trailing slash on the source path will determine
    80  whether the directory name will be embedded within the destination, or whether
    81  the destination will be created. An example explains this best:
    82  
    83  If the source is `/foo` (no trailing slash), and the destination is `/tmp`, then
    84  the contents of `/foo` on the local machine will be uploaded to `/tmp/foo` on
    85  the remote machine. The `foo` directory on the remote machine will be created by
    86  Packer.
    87  
    88  If the source, however, is `/foo/` (a trailing slash is present), and the
    89  destination is `/tmp`, then the contents of `/foo` will be uploaded into `/tmp`
    90  directly.
    91  
    92  This behavior was adopted from the standard behavior of rsync. Note that under
    93  the covers, rsync may or may not be used.
    94  
    95  ## Uploading files that don't exist before Packer starts
    96  
    97  In general, local files used as the source **must** exist before Packer is run.
    98  This is great for catching typos and ensuring that once a build is started,
    99  that it will succeed. However, this also means that you can't generate a file
   100  during your build and then upload it using the file provisioner later.
   101  A convenient workaround is to upload a directory instead of a file. The
   102  directory still must exist, but its contents don't. You can write your
   103  generated file to the directory during the Packer run, and have it be uploaded
   104  later.
   105  
   106  ## Symbolic link uploads
   107  
   108  The behavior when uploading symbolic links depends on the communicator. The
   109  Docker communicator will preserve symlinks, but all other communicators will
   110  treat local symlinks as regular files. If you wish to preserve symlinks when
   111  uploading, it's recommended that you use `tar`. Below is an example of what
   112  that might look like:
   113  
   114  ``` text
   115  $ ls -l files
   116  total 16
   117  drwxr-xr-x  3 mwhooker  staff  102 Jan 27 17:10 a
   118  lrwxr-xr-x  1 mwhooker  staff    1 Jan 27 17:10 b -> a
   119  -rw-r--r--  1 mwhooker  staff    0 Jan 27 17:10 file1
   120  lrwxr-xr-x  1 mwhooker  staff    5 Jan 27 17:10 file1link -> file1
   121  $ ls -l toupload
   122  total 0
   123  -rw-r--r--  1 mwhooker  staff    0 Jan 27 17:10 files.tar
   124  ```
   125  
   126  ``` json
   127  {
   128    "provisioners": [
   129      {
   130        "type": "shell-local",
   131        "command": "tar cf toupload/files.tar files"
   132      },
   133      {
   134        "destination": "/tmp/",
   135        "source": "./toupload",
   136        "type": "file"
   137      },
   138      {
   139        "inline": [
   140          "cd /tmp && tar xf toupload/files.tar",
   141          "rm toupload/files.tar"
   142        ],
   143        "type": "shell"
   144      }
   145    ]
   146  }
   147  ```
   148  
   149  ## Slowness when transferring large files over WinRM.
   150  
   151  Because of the way our WinRM transfers works, it can take a very long time to
   152  upload and download even moderately sized files. If you're experiencing
   153  slowness using the file provisioner on Windows, it's suggested that you set up
   154  an SSH server and use the [ssh
   155  communicator](/docs/templates/communicator.html#ssh-communicator). If you only
   156  want to transfer files to your guest, and if your builder supports it, you may
   157  also use the `http_directory` directive. This will cause that directory to be
   158  available to the guest over http, and set the environment variable
   159  `PACKER_HTTP_ADDR` to the address.