github.com/raghuse92/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.