Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท Provisioning

File Provisioner and Triggers

Copy files and folders into a guest with the file provisioner, understand the destination rules, and run actions before or after Vagrant commands using triggers.

Not everything you need in a machine is a command. Often you need to put a file in a certain place: an nginx configuration, a systemd unit, an SSH key, a dotfile, a database dump. The file provisioner uploads files and folders from your host into the guest. Its companion, triggers, lets you run your own actions on the host (or in the guest) before or after Vagrant commands such as up, halt or destroy. Both are small features that make a Vagrantfile much more complete.

The file provisioner

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"

  config.vm.provision "file", source: "config/nginx-site.conf", destination: "/tmp/site.conf"
  config.vm.provision "shell", inline: <<~SHELL
    mv /tmp/site.conf /etc/nginx/sites-available/shop
    ln -sf /etc/nginx/sites-available/shop /etc/nginx/sites-enabled/shop
    nginx -t && systemctl reload nginx
  SHELL
end

The two required options are source (a path on the host, relative to the Vagrantfile) and destination (a path in the guest).

There is one rule that surprises everyone: the file provisioner connects as the vagrant user, not as root. It can therefore only write to places that user may write to, such as /home/vagrant and /tmp. Writing straight to /etc/nginx/... fails with a permission error. The standard pattern is exactly the example above: upload to /tmp, then use a privileged shell provisioner to move the file where it belongs and set ownership.

Files versus folders

Ruby
# a single file
config.vm.provision "file", source: "~/.gitconfig", destination: "$HOME/.gitconfig"

# a whole folder: the trailing slash matters
config.vm.provision "file", source: "dotfiles", destination: "/home/vagrant/dotfiles"

The trailing-slash behavior of folders is like scp -r/rsync: with source: "dotfiles" the folder itself is created inside the parent of the destination path, and with source: "dotfiles/" its contents are copied into the destination. If the layout looks wrong, list the result with vagrant ssh -c "ls -R /home/vagrant/dotfiles".

When to use file and when not

Situation Better choice
One-off configuration files and dotfiles File provisioner
A file that you edit constantly on the host and want live in the guest Synced folder, see Synced folders
Big directories, many files Synced folder or rsync
Templated config with variables Ansible/Puppet/Chef templates, or generate the file in Ruby
Secrets Do not commit; read from the host's environment

Because the file provisioner is a provisioner, it follows the same rules as all of them: it runs on first creation, or with --provision, and you can give it run: "always" when the file must be refreshed at every boot.

Generating files with Ruby

A neat trick is to render a file in the Vagrantfile (Ruby has string interpolation built in) and send it to the guest through a shell provisioner, with Shellwords.escape protecting special characters:

Ruby
require "shellwords"

nginx_port = 8080
site = <<~CONF
  server {
    listen #{nginx_port};
    root /vagrant/public;
  }
CONF

config.vm.provision "shell",
  inline: "echo #{Shellwords.escape(site)} > /etc/nginx/sites-available/shop"

Keep this for small files. For anything larger, store the template in a file and let a configuration tool render it.

Triggers

Triggers attach your actions to Vagrant's own lifecycle. They are configured with config.trigger and can run before or after commands (up, halt, destroy, reload, provision, ssh...). They are built in to Vagrant since version 2.1, so no plugin is needed.

Ruby
Vagrant.configure("2") do |config|
  config.trigger.before :destroy do |t|
    t.name = "Dump the database before destroying the VM"
    t.info = "Saving a backup..."
    t.run_remote = { inline: "pg_dump shop > /vagrant/backup.sql" }
    t.on_error = :continue
  end

  config.trigger.after :up do |t|
    t.name = "Notify"
    t.run = { inline: "echo Machine is up" }      # runs on the HOST
  end
end

The important distinction:

  • t.run executes a command or script on the host.
  • t.run_remote executes it inside the guest.
  • t.warn and t.info print messages; t.exit_code can stop Vagrant.
  • t.only_on limits the trigger to named machines in a multi-machine file.
  • t.on_error is :halt (default) or :continue.
  • t.ruby runs a Ruby block instead of a shell command.

Typical uses: back up data before destroy, start a local proxy after up, warn about the license before running on production-like data, update /etc/hosts on the host (with care), or clean up temporary files after halt.

sequenceDiagram
    participant You
    participant Vagrant
    participant Trigger
    You->>Vagrant: vagrant destroy
    Vagrant->>Trigger: before :destroy
    Trigger-->>Vagrant: backup finished
    Vagrant->>Vagrant: delete VM
    Vagrant->>Trigger: after :destroy
    Vagrant-->>You: done

A trigger wraps a command: before, the command itself, then after.

A model of before and after hooks

The stand-in below shows the hook mechanics in plain Ruby: hooks are stored per command, run in order, and an error in a hook either stops the command (:halt) or is reported and skipped (:continue). It is not Vagrant, but it behaves like its triggers.

Ruby Before and after hooks with error handling (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Practical advice

  • Triggers run on the host, so write them in a portable way, or choose commands that exist for all team members' systems.
  • Use t.on_error = :continue for optional steps (notifications, backups that may not exist) and keep the default for essential ones.
  • Do not hide long, complex logic in a trigger. Put it in a script and call the script.
  • A before-destroy backup into the synced folder (/vagrant) survives the VM; a backup in the guest does not.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does a file provisioner fail when the destination is /etc/nginx/site.conf?

    Upload to /tmp or the home directory, then use a privileged shell provisioner to move the file into place.
  2. 2. What is the difference between t.run and t.run_remote in a trigger?

    run is for host-side commands; run_remote runs inside the virtual machine.
  3. 3. Which is the better tool for a source folder you edit all day on the host and want live in the guest?

    The file provisioner copies once at provisioning time; a synced folder shares changes continuously.
  4. 4. What does t.on_error = :continue do?

    By default a failing trigger halts the command; :continue reports the error but proceeds.

Summary

  • The file provisioner copies host files into the guest as the vagrant user; stage in /tmp, then move with a privileged shell step.
  • Mind the trailing slash for folders, and prefer synced folders for live-edited files.
  • Triggers run actions before or after Vagrant commands, on the host (run) or in the guest (run_remote).
  • Use on_error, only_on and name to keep triggers safe and readable.

Next: Config Management Provisioners