Configuring Shell Provisioner

1. Running Inline Commands

Property	Values	Description
inline	`string`	Command to run as a string. This is the primary way to execute inline shell commands.
inline	`array`	Array of commands to run. Each command is executed in sequence.

Example: Running a single inline command

vagrant> config.vm.provision :shell, inline: "echo \"Hello World\""

Example: Running multiple inline commands

vagrant> config.vm.provision :shell, inline: ["echo \"Step 1\"", "ls -la"]

Note: Inline commands are executed in the context of the guest machine and have access to all installed packages and environment variables.

2. Executing External Scripts

Property	Description	Example
script	Path to the external script file to execute	`script = "provision.sh"`
args	Arguments to pass to the script	`args = ["arg1", "arg2"]`

Example: Executing External Script

Vagrant.configure("2") do |config|
  config.vm.provision :shell, :path => "scripts/setup.sh", :args => ["dev", "local"]
end

Note: The script path is relative to the Vagrantfile location.

3. Setting Script Arguments

Argument	Description	Example
args	List of arguments to pass to the script	`["arg1", "arg2"]`
inline	Script content as a string (alternative to script file)	`"echo 'Hello World'"`

Example: Passing Arguments to a Script

Vagrant.configure("2") do |config|
  config.vm.provision :shell, :path => "script.sh", :args => ["arg1", "arg2"]
end

Example: Inline Script with Arguments

Vagrant.configure("2") do |config|
  config.vm.provision :shell, :inline => "echo $1 $2", :args => ["Hello", "World"]
end

4. Using Environment Variables

Variable	Value	Description
VAGRANT_ENV	`production`	Environment identifier for Vagrant configuration
VAGRANT_BOX	`ubuntu/focal64`	Box name used for provisioning
VAGRANT_SHELL_SCRIPT	`/path/to/script.sh`	Path to the shell script to execute during provisioning

Example: Setting Environment Variables in Vagrantfile

Vagrant.configure("2") do |config|
  config.vm.provision "shell", inline: <<-SCRIPT
    echo "Environment: $VAGRANT_ENV"
    echo "Box: $VAGRANT_BOX"
  SCRIPT
end

Note: Environment variables can be set in the Vagrantfile or via command-line using vagrant up --provider=virtualbox with environment overrides.

5. Setting Execute Privileges

Property	Description	Default	Notes
privileged	Whether to run the script with elevated privileges	`false`	Set to `true` to run with root privileges
path	Path to the script file on the guest machine	`nil`	Must be an absolute path or relative to the project root
inline	Script content to execute directly	`nil`	Cannot be used with `path`

Example: Setting Execute Privileges

config.vm.provision "shell", privileged: true do |s|
  s.path = "scripts/setup.sh"
end

Note: Setting privileged to true allows the script to run with root privileges, which is necessary for system-level changes.

Warning: Be cautious when using privileged as it can lead to security vulnerabilities if the script content is not trusted.

6. Uploading Files

Option	Values	Description
upload	`string`	Path to file or directory on the host to upload to the guest
destination	`string`	Path on the guest where the file or directory will be uploaded

Example: Upload a configuration file

config.vm.provision "file", source: "./app.conf", destination: "/etc/app.conf"

Example: Upload a directory

config.vm.provision "file", source: "./assets/", destination: "/var/www/assets/"

Note: The upload option can also be used with the inline provisioner to upload and execute a script in one step.

7. Setting Binary Mode

Option	Values	Description
binary	`true` \| `false`	When set to `true`, Vagrant will treat the script as a binary file and not perform any shell interpretation or escaping. This is useful for scripts that contain binary data or special characters that should not be interpreted by the shell.

Example: Setting Binary Mode in Vagrantfile

Vagrant.configure("2") do |config|
  config.vm.provision :shell, binary: true, inline: "echo \"Binary mode enabled\""
end

8. Configuring Keep Color

Option	Values	Notes
keep_color	`true` \| `false`	Preserves color codes in shell provisioner output. Defaults to `false`.

Example: Enabling Color Output

Vagrant.configure("2") do |config|
  config.vm.provision :shell, keep_color: true do |s|
    s.inline = "echo \"\033[32mGreen Text\033[0m\""
  end
end

9. Setting Script Name

Property	Values	Description
script	`string`	Path to the script file to be executed on the guest machine. Must be a valid path relative to the Vagrantfile or an absolute path.

Example: Setting Script Name

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

10. Using PowerShell

Property	Values	Description
powershell_script	`string`	Path to a PowerShell script file or inline script content to execute.
powershell_elevated_interpreter	`string`	Path to the elevated PowerShell interpreter (e.g., `PowerShell.exe`).
powershell_execution_policy	`string`	Execution policy to set before running the script (e.g., `Bypass`, `Unrestricted`).
powershell_no_profile	`boolean`	If `true`, disables loading the PowerShell profile.

Example: Running a PowerShell Script

config.vm.provision "shell", inline: <<-SCRIPT
  Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
  .\my-script.ps1
SCRIPT

Example: Inline PowerShell Script

config.vm.provision "shell", inline: <<-PS1
  Write-Output "Hello from PowerShell"
  Get-Date
PS1

11. Handling Reboot

Property	Description	Default	Notes
reboot	Whether to reboot the machine after provisioning	`false`	Set to `true` to reboot after provisioning completes
reboot_timeout	Timeout in seconds for reboot process	`300`	Maximum time to wait for machine to come back online after reboot
reboot_wait	Time in seconds to wait before rebooting	`0`	Delay between provisioning and rebooting (useful for cleanup)

Example: Reboot After Provisioning

config.vm.provision "shell", inline: <<-SHELL
  echo "Installing packages..."
  apt-get update
  apt-get install -y nginx
SHELL

config.vm.provision "shell", inline: <<-SHELL
  echo "Starting services..."
  systemctl start nginx
SHELL, reboot: true, reboot_timeout: 600

Note: Rebooting can cause provisioning to fail if the machine is not ready to accept new connections. Ensure your reboot_timeout is sufficient for the system to fully restart.

Warning: If reboot is set to true, any subsequent provisioners will run after the machine has rebooted. This may require reconfiguration of network or SSH settings.