» Shell Provisioner

» Shell Provisioner

Provisioner name: "shell"

The Vagrant Shell provisioner allows you to upload and execute a script withinthe guest machine.

Shell provisioning is ideal for users new to Vagrant who want to get upand running quickly and provides a strong alternative for users who are notcomfortable with a full configuration management system such as Chef orPuppet.

For POSIX-like machines, the shell provisioner executes scripts withSSH. For Windows guest machines that are configured to use WinRM, theshell provisioner executes PowerShell and Batch scripts over WinRM.

» Options

The shell provisioner takes various options. One of inline or pathis required:

inline (string) - Specifies a shell command inline to execute on theremote machine. See the inline scripts section belowfor more information.
path (string) - Path to a shell script to upload and execute. It can be ascript relative to the project Vagrantfile or a remote script (like a gist).

The remainder of the available options are optional:

args (string or array) - Arguments to pass to the shell script when executing itas a single string. These arguments must be written as if they were typeddirectly on the command line, so be sure to escape characters, quote,etc. as needed. You may also pass the arguments in using an array. In thiscase, Vagrant will handle quoting for you.
binary (boolean) - Vagrant automatically replaces Windows line endings withUnix line endings. If this is false, then Vagrant will not do this. By defaultthis is "false". If the shell provisioner is communicating over WinRM, thisdefaults to "true".
env (hash) - List of key-value pairs to pass in as environment variables tothe script. Vagrant will handle quoting for environment variable values, butthe keys remain untouched.
keep_color (boolean) - Vagrant automatically colors output in green andred depending on whether the output is from stdout or stderr. If this istrue, Vagrant will not do this, allowing the native colors from the scriptto be outputted.
md5 (string) - MD5 checksum used to validate remotely downloaded shell files.
name (string) - This value will be displayed in the output so thatidentification by the user is easier when many shell provisioners are present.
powershell_args (string) - Extra arguments to pass to PowerShellif you are provisioning with PowerShell on Windows.
powershell_elevated_interactive (boolean) - Run an elevated script in interactive modeon Windows. By default this is "false". Must also be privileged. Be sure toenable auto-login for Windows as the user must be logged in for interactivemode to work.
privileged (boolean) - Specifies whether to execute the shell scriptas a privileged user or not (sudo). By default this is "true". Windowsguests use a scheduled task to run as a true administrator without theWinRM limitations.
reboot (boolean) - Reboot the guest. This requires the guest to have areboot capability implemented.
reset (boolean) - Reset the communicator to the machine after completion. Thisis useful when a shell may need to be reloaded.
sha1 (string) - SHA1 checksum used to validate remotely downloaded shell files.
sensitive (boolean) - Marks the Hash values used in the env option as sensitiveand hides them from output. By default this is "false".
upload_path (string) - Is the remote path where the shell script willbe uploaded to. The script is uploaded as the SSH user over SCP, so thislocation must be writable to that user. By default this is"/tmp/vagrant-shell". On Windows, this will default to"C:\tmp\vagrant-shell".

» Inline Scripts

Perhaps the easiest way to get started is with an inline script. Aninline script is a script that is given to Vagrant directly withinthe Vagrantfile. An example is best:

Vagrant.configure("2") do |config|
  config.vm.provision "shell",
    inline: "echo Hello, World"
end

This causes echo Hello, World to be run within the guest machine whenprovisioners are run.

Combined with a little bit more Ruby, this makes it very easy to embedyour shell scripts directly within your Vagrantfile. Another example below:

$script = <<-SCRIPT
echo I am provisioning...
date > /etc/vagrant_provisioned_at
SCRIPT
Vagrant.configure("2") do |config|
  config.vm.provision "shell", inline: $script
end

It is understandable that if you are not familiar with Ruby, the above may seem veryadvanced or foreign. But do not fear, what it is doing is quite simple:the script is assigned to a global variable $script. This global variablecontains a string which is then passed in as the inline script to theVagrant configuration.

Of course, if any Ruby in your Vagrantfile outside of basic variable assignmentmakes you uncomfortable, you can use an actual script file, documented inthe next section.

For Windows guest machines, the inline script must be PowerShell. Batchscripts are not allowed as inline scripts.

» External Script

The shell provisioner can also take an option specifying a path toa shell script on the host machine. Vagrant will then upload this scriptinto the guest and execute it. An example:

Vagrant.configure("2") do |config|
  config.vm.provision "shell", path: "script.sh"
end

Relative paths, such as above, are expanded relative to the locationof the root Vagrantfile for your project. Absolute paths can also be used,as well as shortcuts such as ~ (home directory) and .. (parent directory).

If you use a remote script as part of your provisioning process, you can pass inits URL as the path argument as well:

Vagrant.configure("2") do |config|
  config.vm.provision "shell", path: "https://example.com/provisioner.sh"
end

If you are running a Batch or PowerShell script for Windows, make surethat the external path has the proper extension (".bat" or ".ps1"), becauseWindows uses this to determine what kind of file it is to execute. If youexclude this extension, it likely will not work.

To run a script already available on the guest you can use an inline script toinvoke the remote script on the guest.

Vagrant.configure("2") do |config|
  config.vm.provision "shell",
    inline: "/bin/sh /path/to/the/script/already/on/the/guest.sh"
end

» Script Arguments

You can parameterize your scripts as well like any normal shell script.These arguments can be specified to the shell provisioner. They shouldbe specified as a string as they'd be typed on the command line, sobe sure to properly escape anything:

Vagrant.configure("2") do |config|
  config.vm.provision "shell" do |s|
    s.inline = "echo $1"
    s.args   = "'hello, world!'"
  end
end

You can also specify arguments as an array if you do not want to worry aboutquoting:

Vagrant.configure("2") do |config|
  config.vm.provision "shell" do |s|
    s.inline = "echo $1"
    s.args   = ["hello, world!"]
  end
end