github.com/mmcquillan/packer@v1.1.1-0.20171009221028-c85cf0483a5d/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. All elements are required.
    36  
    37  -   `source` (string) - The path to a local file or directory to upload to
    38      the machine. The path can be absolute or relative. If it is relative, it is
    39      relative to the working directory when Packer is executed. If this is a
    40      directory, the existence of a trailing slash is important. Read below on
    41      uploading directories.
    42  
    43  -   `destination` (string) - The path where the file will be uploaded to in
    44      the machine. This value must be a writable location and any parent
    45      directories must already exist.
    46  
    47  -   `direction` (string) - The direction of the file transfer. This defaults to
    48      "upload". If it is set to "download" then the file "source" in the machine
    49      will be downloaded locally to "destination"
    50  
    51  ## Directory Uploads
    52  
    53  The file provisioner is also able to upload a complete directory to the remote
    54  machine. When uploading a directory, there are a few important things you should
    55  know.
    56  
    57  First, the destination directory must already exist. If you need to create it,
    58  use a shell provisioner just prior to the file provisioner in order to create
    59  the directory. If the destination directory does not exist, the file
    60  provisioner may succeed, but it will have undefined results.
    61  
    62  Next, the existence of a trailing slash on the source path will determine
    63  whether the directory name will be embedded within the destination, or whether
    64  the destination will be created. An example explains this best:
    65  
    66  If the source is `/foo` (no trailing slash), and the destination is `/tmp`, then
    67  the contents of `/foo` on the local machine will be uploaded to `/tmp/foo` on
    68  the remote machine. The `foo` directory on the remote machine will be created by
    69  Packer.
    70  
    71  If the source, however, is `/foo/` (a trailing slash is present), and the
    72  destination is `/tmp`, then the contents of `/foo` will be uploaded into `/tmp`
    73  directly.
    74  
    75  This behavior was adopted from the standard behavior of rsync. Note that under
    76  the covers, rsync may or may not be used.
    77  
    78  ## Symbolic link uploads
    79  
    80  The behavior when uploading symbolic links depends on the communicator. The
    81  Docker communicator will preserve symlinks, but all other communicators will
    82  treat local symlinks as regular files. If you wish to preserve symlinks when
    83  uploading, it's recommended that you use `tar`. Below is an example of what
    84  that might look like:
    85  
    86  ``` text
    87  $ ls -l files
    88  total 16
    89  drwxr-xr-x  3 mwhooker  staff  102 Jan 27 17:10 a
    90  lrwxr-xr-x  1 mwhooker  staff    1 Jan 27 17:10 b -> a
    91  -rw-r--r--  1 mwhooker  staff    0 Jan 27 17:10 file1
    92  lrwxr-xr-x  1 mwhooker  staff    5 Jan 27 17:10 file1link -> file1
    93  ```
    94  
    95  ``` json
    96  {
    97    "provisioners": [
    98      {
    99        "type": "shell-local",
   100        "command": "mkdir -p toupload; tar cf toupload/files.tar files"
   101      },
   102      {
   103        "destination": "/tmp/",
   104        "source": "./toupload",
   105        "type": "file"
   106      },
   107      {
   108        "inline": [
   109          "cd /tmp && tar xf toupload/files.tar",
   110          "rm toupload/files.tar"
   111        ],
   112        "type": "shell"
   113      }
   114    ]
   115  }
   116  ```