141 lines
4.4 KiB
Plaintext
141 lines
4.4 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: File Uploads - Provisioning
|
|
description: |-
|
|
The Vagrant file provisioner allows you to upload a file or directory from the
|
|
host machine to the guest machine.
|
|
---
|
|
|
|
# File Provisioner
|
|
|
|
**Provisioner name: `"file"`**
|
|
|
|
The Vagrant file provisioner allows you to upload a file or directory from the
|
|
host machine to the guest machine.
|
|
|
|
File provisioning is a simple way to, for example, replicate your local
|
|
~/.gitconfig to the vagrant user's home directory on the guest machine so
|
|
you will not have to run `git config --global` every time you provision a
|
|
new VM.
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
# ... other configuration
|
|
|
|
config.vm.provision "file", source: "~/.gitconfig", destination: ".gitconfig"
|
|
end
|
|
```
|
|
|
|
If you want to upload a folder to your guest system, it can be accomplished by
|
|
using a file provisioner seen below. This will copy the your local `folder`
|
|
(specified as the `source`) to the the `newfolder` on the guest machine
|
|
(specified as the `destination`). Note that if you'd like the same folder name
|
|
on your guest machine, make sure that the destination path has the same name as
|
|
the folder on your host.
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
# ... other configuration
|
|
|
|
config.vm.provision "file", source: "~/path/to/host/folder", destination: "$HOME/remote/newfolder"
|
|
end
|
|
```
|
|
|
|
Prior to copying `~/path/to/host/folder` to the guest machine:
|
|
|
|
```text
|
|
folder
|
|
├── script.sh
|
|
├── otherfolder
|
|
│ └── hello.sh
|
|
├── goodbye.sh
|
|
├── hello.sh
|
|
└── woot.sh
|
|
|
|
1 directory, 5 files
|
|
```
|
|
|
|
After to copying `~/path/to/host/folder` into `$HOME/remote/newfolder` to the guest machine:
|
|
|
|
```text
|
|
newfolder
|
|
├── script.sh
|
|
├── otherfolder
|
|
│ └── hello.sh
|
|
├── goodbye.sh
|
|
├── hello.sh
|
|
└── woot.sh
|
|
|
|
1 directory, 5 files
|
|
```
|
|
|
|
Note that, unlike with synced folders, files or directories that are uploaded
|
|
will not be kept in sync. Continuing with the example above, if you make
|
|
further changes to your local ~/.gitconfig, they will not be immediately
|
|
reflected in the copy you uploaded to the guest machine.
|
|
|
|
The file uploads by the file provisioner are done as the
|
|
_SSH or PowerShell user_. This is important since these users generally
|
|
do not have elevated privileges on their own. If you want to upload files to
|
|
locations that require elevated privileges, we recommend uploading them
|
|
to temporary locations and then using the
|
|
[shell provisioner](/vagrant/docs/provisioning/shell)
|
|
to move them into place.
|
|
|
|
## Options
|
|
|
|
The file provisioner takes only two options, both of which are required:
|
|
|
|
- `source` (string) - Is the local path of the file or directory to be
|
|
uploaded.
|
|
|
|
- `destination` (string) - Is the remote path on the guest machine where
|
|
the source will be uploaded to. The file/folder is uploaded as the SSH user
|
|
over SCP, so this location must be writable to that user. The SSH user can be
|
|
determined by running `vagrant ssh-config`, and defaults to "vagrant". Both
|
|
forward and backward slash work for Windows guest. Variables like `$HOME` are
|
|
expanded by Vagrant, not by guest.
|
|
|
|
## Caveats
|
|
|
|
While the file provisioner does support trailing slashes or "globing", this can
|
|
lead to some confusing results due to the underlying tool used to copy files and
|
|
folders between the host and guests. For example, if you have a source and
|
|
destination with a trailing slash defined below:
|
|
|
|
```ruby
|
|
config.vm.provision "file", source: "~/pathfolder", destination: "/remote/newlocation/"
|
|
```
|
|
|
|
You are telling vagrant to upload `~/pathfolder` under the remote dir `/remote/newlocation`,
|
|
which will look like:
|
|
|
|
```text
|
|
newlocation
|
|
├── pathfolder
|
|
│ └── file.sh
|
|
|
|
1 directory, 2 files
|
|
```
|
|
|
|
This behavior can also be achieved by defining your file provisioner below:
|
|
|
|
```ruby
|
|
config.vm.provision "file", source: "~/pathfolder", destination: "/remote/newlocation/pathfolder"
|
|
```
|
|
|
|
Another example is using globing on the host machine to grab all files within a
|
|
folder, but not the top level folder itself:
|
|
|
|
```ruby
|
|
config.vm.provision "file", source: "~/otherfolder/.", destination: "/remote/otherlocation"
|
|
```
|
|
|
|
The file provisioner is defined to include all files under `~/otherfolder`
|
|
to the new location `/remote/otherlocation`. This idea can be achieved by simply
|
|
having your destination folder differ from the source folder:
|
|
|
|
```ruby
|
|
config.vm.provision "file", source: "/otherfolder", destination: "/remote/otherlocation"
|
|
```
|