Boxes are the package format for Vagrant environments. A box can be used by 4 | anyone on any platform that Vagrant supports to bring up an identical 5 | working environment.
6 | 7 |The vagrant box utility provides all the functionality for managing
8 | boxes. You can read the documentation on the vagrant box
9 | command for more information.
The easiest way to use a box is to add a box from the 12 | publicly available catalog of Vagrant boxes. 13 | You can also add and share your own customized boxes on this website.
14 | 15 |Boxes also support versioning so that members of your team using Vagrant 16 | can update the underlying box easily, and the people who create boxes 17 | can push fixes and communicate these fixes efficiently.
18 | 19 |You can learn all about boxes by reading this page as well as the 20 | sub-pages in the navigation to the left.
21 | 22 |The easiest way to find boxes is to look on the 25 | public Vagrant box catalog 26 | for a box matching your use case. The catalog contains most major operating 27 | systems as bases, as well as specialized boxes to get you up and running 28 | quickly with LAMP stacks, Ruby, Python, etc.
29 | 30 |The boxes on the public catalog work with many different 31 | providers. Whether you're using Vagrant with 32 | VirtualBox, VMware, AWS, etc. you should be able to find a box you need.
33 | 34 |Adding a box from the catalog is very easy. Each box shows you instructions 35 | with how to add it, but they all follow the same format:
36 | 37 |$ vagrant box add USER/BOX
38 | ...
39 | For example: vagrant box add hashicorp/precise64. You can also quickly
42 | initialize a Vagrant environment with vagrant init hashicorp/precise64.
Command: vagrant connect NAME
The connect command compliments the 6 | share command by enabling access to shared 7 | environments. You can learn about all the details of Vagrant Share in the 8 | Vagrant Share section.
9 | 10 |The reference of available command-line flags to this command 11 | is available below.
12 | 13 |--disable-static-ip - The connect command will not spin up a small
17 | virtual machine to create a static IP you can access. When this flag is
18 | set, the only way to access the connection is to use the SOCKS proxy
19 | address outputted.
--static-ip IP - Tells connect what static IP address to use for the virtual
21 | machine. By default, Vagrant connect will use an IP address that looks
22 | available in the 172.16.0.0/16 space.
--ssh - Connects via SSH to an environment shared with
24 | vagrant share --ssh.
Command: vagrant destroy
This command stops the running machine Vagrant is managing and 6 | destroys all resources that were created during the machine creation process. 7 | After running this command, your computer should be left at a clean state, 8 | as if you never created the guest machine in the first place.
9 | 10 |This command usually asks for confirmation before destroying. This
11 | confirmation can be skipped by passing in the -f or --force flag.
-f or --force - Don't ask for confirmation before destroying.Command: vagrant global-status
This command will tell you the state of all active Vagrant environments 6 | on the system for the currently logged in user.
7 | 8 |This command doesn't actively verify the state of the machines listed,
9 | and is instead based on a cache. Because of this, it is possible to see
10 | stale results (machines say they're running but they're not). For example,
11 | if you restart your computer, Vagrant wouldn't know. To prune the invalid
12 | entries, run global status with the --prune flag.
The IDs in the output that look like a1b2c3 can be used to control
15 | the Vagrant machine from anywhere on the system. Any Vagrant command
16 | that takes a target machine (such as up, halt, destroy) can be
17 | used with this ID to control it. For example: vagrant destroy a1b2c3.
--prune - Prunes invalid entries from the list. This is much more time
23 | consuming than simply listing the entries.If your environment is not showing up, you may have to do a vagrant destroy
29 | followed by a vagrant up.
If you just upgraded from a previous version of Vagrant, existing environments 32 | won't show up in global-status until they are destroyed and recreated.
-------------------------------------------------------------------------------- /v2/cli/halt.html: -------------------------------------------------------------------------------- 1 |Command: vagrant halt
This command shuts down the running machine Vagrant is managing.
6 | 7 |Vagrant will first attempt to gracefully shut down the machine by running
8 | the guest OS shutdown mechanism. If this fails, or if the --force flag is
9 | specified, Vagrant will effectively just shut off power to the machine.
-f or --force - Don't attempt to gracefully shut down the machine.
15 | This effectively pulls the power on the guest machine.Almost all interaction with Vagrant is done through the command-line 4 | interface.
5 | 6 |The interface is available using the vagrant command, and comes installed
7 | with Vagrant automatically. The vagrant command in turn has many subcommands,
8 | such as vagrant up, vagrant destroy, etc.
If you run vagrant by itself, help will be displayed showing all available
11 | subcommands. In addition to this, you can run any Vagrant command with the
12 | -h flag to output help about that specific command. For example, try
13 | running vagrant init -h. The help will output a one sentence synopsis of
14 | what the command does as well as a list of all the flags the command
15 | accepts.
In depth documentation and use cases of various Vagrant commands is 18 | available by reading the appropriate sub-section available in the left 19 | navigational area of this site.
20 | 21 |You may also wish to consult the 22 | documentation regarding the 23 | environmental variables that can be used to configure and control 24 | Vagrant in a global way.
25 | -------------------------------------------------------------------------------- /v2/cli/init.html: -------------------------------------------------------------------------------- 1 |Command: vagrant init [box-name] [box-url]
This initializes the current directory to be a Vagrant environment 6 | by creating an initial Vagrantfile if 7 | one doesn't already exist.
8 | 9 |If a first argument is given, it will prepopulate the config.vm.box
10 | setting in the created Vagrantfile.
If a second argument is given, it will prepopulate the config.vm.box_url
13 | setting in the created Vagrantfile.
--force - If specified, this command will overwite any existing
19 | Vagrantfile.
--minimal - If specified, a minimal Vagrantfile will be created. This
21 | Vagrantfile does not contain the instructional comments that the normal
22 | Vagrantfile contains.
--output FILE - This will output the Vagrantfile to the given file.
24 | If this is "-", the Vagrantfile will be sent to stdout.
Command: vagrant login
The login command is used to authenticate with the 6 | HashiCorp's Atlas server. Logging is only 7 | necessary if you're accessing protected boxes or using 8 | Vagrant Share.
9 | 10 |Logging in is not a requirement to use Vagrant. The vast majority 11 | of Vagrant does not require a login. Only certain features such as protected 12 | boxes or Vagrant Share require a login.
13 | 14 |The reference of available command-line flags to this command 15 | is available below.
16 | 17 |--check - This will check if you're logged in. In addition to outputting
21 | whether you're logged in or not, the command will have exit status 0 if you're
22 | logged in, and exit status 1 if you're not.
--logout - This will log you out if you're logged in. If you're already
24 | logged out, this command will do nothing. It is not an error to call this
25 | command if you're already logged out.
--token - This will set the Atlas login token manually to the provided
27 | string. It is assumed this token is a valid Atlas access token.
Securely authenticate to Atlas using a username and password:
33 | 34 |$ vagrant login
35 | # ...
36 | Atlas username:
37 | Atlas password:
38 | Check if the current user is authenticated:
41 | 42 |$ vagrant login --check
43 | You are already logged in.
44 | Securely authenticate with Atlas using a token:
47 | 48 |$ vagrant login --token ABCD1234
49 | The token was successfully saved.
50 | In addition to the commands listed in the sidebar and shown in vagrant -h,
4 | Vagrant comes with some more commands that are hidden from basic help output.
5 | These commands are hidden because they're not useful to beginners or they're
6 | not commonly used. We call these commands "non-primary subcommands".
You can view all subcommands, including the non-primary subcommands,
9 | by running vagrant list-commands, which itself is a non-primary subcommand!
Note that while you have to run a special command to list the non-primary
12 | subcommands, you don't have to do anything special to actually run the
13 | non-primary subcommands. They're executed just like any other subcommand:
14 | vagrant COMMAND.
The list of non-primary commands is below. Click on any command to learn 17 | more about it.
18 | 19 |Command: vagrant package
This packages a currently running VirtualBox environment into a 6 | re-usable box. This command cannot be used with 7 | any other provider. A future version of Vagrant 8 | will address packaging boxes for other providers. Until then, they must 9 | be made by hand.
10 | 11 |--base NAME - Instead of packaging a VirtualBox machine that Vagrant
15 | manages, this will package a VirtualBox machine that VirtualBox manages.
16 | NAME should be the name or UUID of the machine from the VirtualBox GUI.
--output NAME - The resulting package will be saved as NAME. By default,
18 | it will be saved as package.box.
--include x,y,z - Additional files will be packaged with the box. These
20 | can be used by a packaged Vagrantfile (documented below) to perform additional
21 | tasks.
--vagrantfile FILE - Packages a Vagrantfile with the box, that is loaded
23 | as part of the Vagrantfile load order
24 | when the resulting box is used.
29 | A common misconception is that the --vagrantfile
30 | option will package a Vagrantfile that is used when vagrant init
31 | is used with this box. This is not the case. Instead, a Vagrantfile
32 | is loaded and read as part of the Vagrant load process when the box is
33 | used. For more information, read about the
34 | Vagrantfile load order.
35 |
Command: vagrant plugin
This is the command used to manage plugins.
6 | 7 |The main functionality of this command is exposed via another level 8 | of subcommands:
9 | 10 |installlicenselistuninstallupdateCommand: vagrant plugin install <name>...
This installs a plugin with the given name or file path. If the name
23 | is not a path to a file, then the plugin is installed from remote
24 | repositories, usually RubyGems. This command will
25 | also update a plugin if it is already installed, but you can also use
26 | vagrant plugin update for that.
If multiple names are specified, multiple plugins will be installed. If 29 | flags are given below, the flags will apply to all plugins being installed 30 | by the current command invocation.
31 | 32 |This command accepts optional command-line flags:
33 | 34 |--entry-point ENTRYPOINT - By default, installed plugins are loaded
36 | internally by loading an initialization file of the same name as the plugin.
37 | Most of the time, this is correct. If the plugin you're installing has
38 | another entrypoint, this flag can be used to specify it.
--plugin-source SOURCE - Adds a source from which to fetch a plugin. Note
40 | that this doesn't only affect the single plugin being installed, by all future
41 | plugin as well. This is a limitation of the underlying plugin installer
42 | Vagrant uses.
--plugin-version VERSION - The version of the plugin to install. By default,
44 | this command will install the latest version. You can constrain the version
45 | using this flag. You can set it to a specific version, such as "1.2.3" or
46 | you can set it to a version contraint, such as "> 1.0.2". You can set it
47 | to a more complex constraint by comma-separating multiple constraints:
48 | "> 1.0.2, < 1.1.0" (don't forget to quote these on the command-line).
Command: vagrant plugin license <name> <license-file>
This command installs a license for a proprietary Vagrant plugin, 56 | such as the VMware Fusion provider.
57 | 58 |Command: vagrant plugin list
This lists all installed plugins and their respective installed versions. 63 | If a version constraint was specified for a plugin when installing it, the 64 | constraint will be listed as well. Other plugin-specific information may 65 | be shown, too.
66 | 67 |Command: vagrant plugin uninstall <name> [<name2> <name3> ...]
This uninstalls the plugin with the given name. Any dependencies of the 72 | plugin will also be uninstalled assuming no other plugin needs them.
73 | 74 |If multiple plugins are given, multiple plugins will be uninstalled.
75 | 76 |Command: vagrant plugin update [<name>]
This updates the plugins that are installed within Vagrant. If you specified
81 | version constraints when installing the plugin, this command will respect
82 | those constraints. If you want to change a version constraint, re-install
83 | the plugin using vagrant plugin install.
If a name is specified, only that single plugin will be updated. If a 86 | name is specified of a plugin that is not installed, this command will not 87 | install it.
88 | -------------------------------------------------------------------------------- /v2/cli/provision.html: -------------------------------------------------------------------------------- 1 |Command: vagrant provision
Runs any configured provisioners 6 | against the running Vagrant managed machine.
7 | 8 |This command is a great way to quickly test any provisioners, and is especially
9 | useful for incremental development of shell scripts, Chef cookbooks, or Puppet
10 | modules. You can just make simple modifications to the provisioning scripts
11 | on your machine, run a vagrant provision, and check for the desired results.
12 | Rinse and repeat.
--provision-with x,y,z - This will only run the given provisioners. For
18 | example, if you have a :shell and :chef_solo provisioner and run
19 | vagrant provision --provision-with shell, only the shell provisioner will
20 | be run.Command: vagrant rdp
This will start an RDP client for a remote desktop session with the 6 | guest. This only works for Vagrant environments that support remote 7 | desktop, which is typically only Windows.
8 | 9 |You can pass raw arguments through to your RDP client on the
12 | command-line by appending it after a --. Vagrant just passes
13 | these through. For example:
$ vagrant rdp -- /span
16 | ...
17 | The above command on Windows will execute mstsc.exe /span config.rdp,
20 | allowing your RDP to span multiple desktops.
Command: vagrant reload
The equivalent of running a halt followed by an 6 | up.
7 | 8 |This command is usually required for changes made in the Vagrantfile to
9 | take effect. After making any modifications to the Vagrantfile, a reload
10 | should be called.
The configured provisioners will not run again, by default. You can force
13 | the provisioners to re-run by specifying the --provision flag.
--provision - Force the provisioners to run.
--provision-with x,y,z - This will only run the given provisioners. For
20 | example, if you have a :shell and :chef_solo provisioner and run
21 | vagrant provision --provision-with shell, only the shell provisioner will
22 | be run.
Command: vagrant resume
This resumes a Vagrant managed machine that was previously suspended, 6 | perhaps with the suspend command.
-------------------------------------------------------------------------------- /v2/cli/rsync-auto.html: -------------------------------------------------------------------------------- 1 |Command: vagrant rsync-auto
This command watches all local directories of any 6 | rsync synced folders and automatically 7 | initiates an rsync transfer when changes are detected. This command does 8 | not exit until an interrupt is received.
9 | 10 |The change detection is optimized to use platform-specific APIs to listen 11 | for filesystem changes, and does not simply poll the directory.
12 | 13 |--[no-]poll - Force Vagrant to watch for changes using filesystem
17 | polling instead of filesystem events. This is required for some filesystems
18 | that don't support events. Warning: enabling this will make rsync-auto
19 | much slower. By default, polling is disabled.The rsync-auto command does not currently handle machine state changes
25 | gracefully. For example, if you start the rsync-auto command, then
26 | halt the guest machine, then make changes to some files, then boot it
27 | back up, rsync-auto will not attempt to resync.
To ensure that the command works properly, you should start rsync-auto
30 | only when the machine is running, and shut it down before any machine
31 | state changes.
You can always force a resync with the rsync command.
34 | 35 |If you change or move your Vagrantfile, the rsync-auto command will have
38 | to be restarted. For example, if you add synced folders to the Vagrantfile,
39 | or move the directory that contains the Vagrantfile, the rsync-auto
40 | command will either not pick up the changes or may begin experiencing
41 | strange behavior.
Before making any such changes, it is recommended that you turn off
44 | rsync-auto, then restart it afterwards.
Command: vagrant rsync
This command forces a resync of any 6 | rsync synced folders.
7 | -------------------------------------------------------------------------------- /v2/cli/share.html: -------------------------------------------------------------------------------- 1 |Command: vagrant share
The share command initializes a Vagrant Share session, allowing you to 6 | share your Vagrant environment with anyone in the world, enabling collaboration 7 | directly in your Vagrant environment in almost any network environment.
8 | 9 |You can learn about all the details of Vagrant Share in the 10 | Vagrant Share section.
11 | 12 |The reference of available command-line flags to this command 13 | is available below.
14 | 15 |--disable-http - Disables the creation of a publicly accessible
19 | HTTP endpoint to your Vagrant environment. With this set, the only way
20 | to access your share is with vagrant connect.
--http PORT - The port of the HTTP server running in the Vagrant
22 | environment. By default, Vagrant will attempt to find this for you.
23 | This has no effect if --disable-http is set.
--https PORT - The port of an HTTPS server running in the Vagrant
25 | environment. By default, Vagrant will attempt to find this for you.
26 | This has no effect if --disable-http is set.
--ssh - Enables SSH sharing (more information below). By default, this
28 | is not enabled.
--ssh-no-password - Disables the encryption of the SSH keypair created
30 | when SSH sharing is enabled.
--ssh-port PORT - The port of the SSH server running in the Vagrant
32 | environment. By default, Vagrant will attempt to find this for you.
--ssh-once - Allows SSH access only once. After the first attempt to
34 | connect via SSH to the Vagrant environment, the generated keypair is
35 | destroyed.
Command: vagrant ssh
This will SSH into a running Vagrant machine and give you access to a shell.
6 | 7 |If a -- (two hyphens) are found on the command line, any arguments after
8 | this are passed directly into the ssh executable. This allows you to pass
9 | any arbitrary commands to do things such as reverse tunneling down into the
10 | ssh program.
-c COMMAND or --command COMMAND - This executes a single SSH command, prints
16 | out the stdout and stderr, and exits. stdin will not be functional on this
17 | executed command.
-p or --plain - This does an SSH without authentication, leaving
19 | authentication up to the user.
Command: vagrant ssh-config
This will output valid configuration for an SSH config file to SSH
6 | into the running Vagrant machine from ssh directly (instead of
7 | using vagrant ssh).
--host NAME - Name of the host for the outputted configuration.Command: vagrant status
This will tell you the state of the machines Vagrant is managing.
6 | 7 |It is quite easy, especially once you get comfortable with Vagrant, to 8 | forget whether your Vagrant machine is running, suspended, not created, etc. 9 | This command tells you the state of the underlying guest machine.
-------------------------------------------------------------------------------- /v2/cli/suspend.html: -------------------------------------------------------------------------------- 1 |Command: vagrant suspend
This suspends the guest machine Vagrant is managing, rather than fully 6 | shutting it down or destroying it.
7 | 8 |A suspend effectively saves the exact point-in-time state of the machine, 9 | so that when you resume it later, it begins running 10 | immediately from that point, rather than doing a full boot.
11 | 12 |This generally requires extra disk space to store all the contents of the 13 | RAM within your guest machine, but the machine no longer consumes the 14 | RAM of your host machine or CPU cycles while it is suspended.
-------------------------------------------------------------------------------- /v2/cli/up.html: -------------------------------------------------------------------------------- 1 |Command: vagrant up
This command creates and configures guest machines according to your 6 | Vagrantfile.
7 | 8 |This is the single most important command in Vagrant, since it is how 9 | any Vagrant machine is created. Anyone using Vagrant must use this command 10 | on a day-to-day basis.
11 | 12 |--[no-]destroy-on-error - Destroy the newly created machine if a fatal,
16 | unexpected error occurs. This will only happen on the first vagrant up.
17 | By default this is set.
--[no-]parallel - Bring multiple machines up in parallel if the provider
19 | supports it. Please consult the provider documentation to see if this feature
20 | is supported.
--provider x - Bring the machine up with the given
22 | provider. By default this is "virtualbox".
--provision - Force the provisioners to run.
--provision-with x,y,z - This will only run the given provisioners. For
25 | example, if you have a :shell and :chef_solo provisioner and run
26 | vagrant provision --provision-with shell, only the shell provisioner will
27 | be run.
Command: vagrant version
This command tells you the version of Vagrant you have installed 6 | as well as the latest version of Vagrant that is currently available.
7 | 8 |In order to determine the latest available Vagrant version, this
9 | command must make a network call. If you only want to see the currently
10 | installed version, use vagrant --version.
The Docker provider in Vagrant behaves just like any other provider. 4 | If you're familiar with Vagrant already, then using the Docker provider 5 | should be intuitive and simple.
6 | 7 |The Docker provider does not require a config.vm.box setting. Since
8 | the "base image" for a Docker container is pulled from the
9 | Docker Index or
10 | built from a Dockerfile, the box doesn't
11 | add much value, and is optional for this provider.
The first method that Vagrant can use to source a Docker container 16 | is via an image. This image can be from any Docker registry. An 17 | example is shown below:
18 | 19 |
20 | Vagrant.configure("2") do |config|
21 | config.vm.provider "docker" do |d|
22 | d.image = "foo/bar"
23 | end
24 | end
25 |
26 |
27 | When vagrant up --provider=docker is run, this will bring up the
28 | image foo/bar.
This is useful for extra components of your application that it might 31 | depend on: databases, queues, etc. Typically, the primary application 32 | you're working on is built with a Dockerfile, or via a container with 33 | SSH.
34 | 35 |Vagrant can also automatically build and run images based on a local 38 | Dockerfile. This is useful for iterating on an application locally 39 | that is built into an image later. An example is shown below:
40 | 41 |
42 | Vagrant.configure("2") do |config|
43 | config.vm.provider "docker" do |d|
44 | d.build_dir = "."
45 | end
46 | end
47 |
48 |
49 | The above configuration will look for a Dockerfile in the same
50 | directory as the Vagrantfile. When vagrant up --provider=docker is run, Vagrant
51 | automatically builds that Dockerfile and starts a container
52 | based on that Dockerfile.
The Dockerfile is rebuilt when vagrant reload is called.
When using Docker, Vagrant automatically converts synced folders 59 | and networking options into Docker volumes and forwarded ports. 60 | You don't have to use the Docker-specific configurations to do this. 61 | This helps keep your Vagrantfile similar to how it has always looked.
62 | 63 |Private and public networks are not currently supported.
64 | 65 |On systems that can't run Linux containers natively, such as Mac OS X 68 | or Windows, Vagrant automatically spins up a "host VM" to run Docker. 69 | This allows your Docker-based Vagrant environments to remain portable, 70 | without inconsistencies depending on the platform they are running on.
71 | 72 |Vagrant will spin up a single instance of a host VM and run multiple 73 | containers on this one VM. This means that with the Docker provider, 74 | you only have the overhead of one virtual machine, and only if it is 75 | absolutely necessary.
76 | 77 |By default, the host VM Vagrant spins up is 78 | backed by boot2docker, 79 | because it launches quickly and uses little resources. But the host VM 80 | can be customized to point to any Vagrantfile. This allows the host VM 81 | to more closely match production by running a VM running Ubuntu, RHEL, 82 | etc. It can run any operating system supported by Vagrant.
83 | 84 |An example of changing the host VM is shown below. Remember that this 93 | is optional, and Vagrant will spin up a default host VM if it isn't 94 | specified:
95 | 96 |
97 | Vagrant.configure("2") do |config|
98 | config.vm.provider "docker" do |d|
99 | d.vagrant_vagrantfile = "../path/to/Vagrantfile"
100 | end
101 | end
102 |
103 |
104 | The host VM will be spun up at the first vagrant up where the provider
105 | is Docker. To control this host VM, use the
106 | global-status command
107 | along with global control.
The Docker provider doesn't require a Vagrant box. The config.vm.box
4 | setting is completely optional.
A box can still be used and specified, however, to provide defaults.
7 | Because the Vagrantfile within a box is loaded as part of the
8 | configuration loading sequence, it can be used to configure the
9 | foundation of a development environment.
In general, however, you won't need a box with the Docker provider.
-------------------------------------------------------------------------------- /v2/docker/commands.html: -------------------------------------------------------------------------------- 1 |The Docker provider exposes some additional Vagrant commands that are 4 | useful for interacting with Docker containers. This helps with your 5 | workflow on top of Vagrant so that you have full access to Docker 6 | underneath.
7 | 8 |vagrant docker-logs can be used to see the logs of a running container.
11 | Because most Docker containers are single-process, this is used to see
12 | the logs of that one process. Additionally, the logs can be tailed.
vagrant docker-run can be used to run one-off commands against
17 | a Docker container. The one-off Docker container that is started shares
18 | all the volumes, links, etc. of the original Docker container. An
19 | example is shown below:
22 | $ vagrant docker-run app -- rake db:migrate 23 |24 | 25 |
The above would run rake db:migrate in the context of an app container.
The Docker provider has some provider-specific configuration options 4 | you may set. A complete reference is shown below.
5 | 6 |build_dir (string) - The path to a directory containing a Dockerfile.
10 | One of this or image is required.
image (string) - The image to launch, specified by the image ID or a name
12 | such as ubuntu:12.04. One of this or build_dir is required.
General settings:
18 | 19 |build_args (array of strings) - Extra arguments to pass to
21 | docker build when build_dir is in use.
cmd (array of strings) - Custom command to run on the container.
23 | Example: ["ls", "/app"].
create_args (array of strings) - Additional arguments to pass to
25 | docker run when the container is started. This can be used to set
26 | parameters that aren't exposed via the Vagrantfile.
env (hash) - Environmental variables to expose into the container.
expose (array of integers) - Ports to expose from the container
29 | but not to the host machine. Useful for links.
link (method, string argument) - Link this container to another
31 | by name. The argument should be in the format of (name:alias).
32 | Example: docker.link("db:db"). Note, if you're linking to
33 | another container in the same Vagrantfile, make sure you call
34 | vagrant up with the --no-parallel flag.
force_host_vm (boolean) - If true, then a host VM will be spun up
36 | even if the computer running Vagrant supports Linux containers. This
37 | is useful to enforce a consistent environment to run Docker.
has_ssh (boolean) - If true, then Vagrant will support SSH with
39 | the container. This allows vagrant ssh to work, provisioners, etc.
40 | This defaults to false.
host_vm_build_dir_options (hash) - Synced folder options for the
42 | build_dir, since the build directory is synced using a synced folder
43 | if a host VM is in use.
name (string) - Name of the container. Note that this has to be unique
45 | across all containers on the host VM. By default Vagrant will generate
46 | some random name.
ports (array of strings) - Ports to expose from the container to the
48 | host. These should be in the format of host:container.
remains_running (boolean) - If true, Vagrant expects this container
50 | to remain running and will make sure that it does for a certain amount
51 | of time. If false, then Vagrant expects that this container will
52 | automatically stop at some point, and won't error if it sees it do that.
stop_timeout (integer) - The amount of time to wait when stopping
54 | a container before sending a SIGTERM to the process.
vagrant_machine (string) - The name of the Vagrant machine in the
56 | vagrant_vagrantfile to use as the host machine. This defaults to
57 | "default".
vagrant_vagrantfile (string) - Path to a Vagrantfile that contains
59 | the vagrant_machine to use as the host VM if needed.
volumes (array of strings) - List of directories to mount as
61 | volumes into the container. These directories must exist in the
62 | host where Docker is running. If you want to sync folders from the
63 | host Vagrant is running, just use synced folders.
Below, we have settings related to auth. If these are set, then Vagrant
67 | will docker login prior to starting containers, allowing you to pull
68 | images from private repositories.
email (string) - Email address for logging in.
username (string) - Username for logging in.
password (string) - Password for logging in.
auth_server (string) - The server to use for authentication. If not
75 | set, the Docker Hub will be used.
Vagrant comes with support out of the box for 4 | using Docker as a provider. This allows for your development environments 5 | to be backed by Docker containers rather than virtual machines. Additionally, 6 | it provides for a good workflow for developing Dockerfiles.
7 | 8 |10 | Warning: Docker knowledge assumed. We assume that 11 | you know what Docker is and that you're comfortable with the basics 12 | of Docker. If not, we recommend starting with another provider such 13 | as VirtualBox. 14 |
15 |Use the navigation to the left to find a specific Docker topic 18 | to read more about.
19 | -------------------------------------------------------------------------------- /v2/getting-started/boxes.html: -------------------------------------------------------------------------------- 1 |从头开始创建一个虚拟机，因为这是一个漫长而乏味的过程，因此 Vagrant 是通过基础镜像包来实现快速克隆创建虚拟机的。这些基础镜像包在 Vagrant 中被称为 boxes ， 4 | 而在创建 Vagrantfile 文件后的第一件事情就是指定 Vagrant 环境使用哪一个 Box。
5 | 6 |如果你之前按照 入门指引首页执行了命令，那么你现在已经安装好了一个 Box，因此不必再次执行下面的命令了。虽然如此，本章节还是值得一读，这将学会如何管理 boxes。
9 | 10 |Boxes 是通过 vagrant box add 命令来添加到 Vagrant 中的， This stores the box
11 | under a specific name so that multiple Vagrant environments can re-use it.
12 | If you haven't added a box yet, you can do so now:
$ vagrant box add hashicorp/precise32
15 | 这将从 HashiCorp's Atlas box catalog 这个专门用来存放 boxes 的地方下载一个名叫 "hashicorp/precise32" 的 box。你不但可以从 HashiCorp's Atlas 下载boxes，其外还可以从本地文件、自定义 URL 等方式添加 boxes。
18 | 19 |已经添加了的 boxes 可以被多个项目重复使用。每个项目其实是从 box 克隆并初始化出一个镜像，不会对原有的 box 基础镜像进行任何修改。所以，当你两个项目都使用了 hashicorp/precise32 这个 box，你在其中一个项目虚拟机中添加了文件，不会对另外一个项目中的虚拟机造成任何影响。
现在，我们已经将 box 添加到了 Vagrant 中，我们需要对我们的项目进行配置，才能将这个项目作为我们今后的基础环境。打开 Vagrantfile 文件，对其内容依照以下进行编辑：
Vagrant.configure("2") do |config|
26 | config.vm.box = "hashicorp/precise32"
27 | end
28 | "hashicorp/precise32" 这个名字必须和你前面添加进去的 box 名称相同。 Vagrant 是根据这个名字去判断进行哪种操作的。如果你之前没有添加过 box，当你运行 Vagrant 时它会根据这个名字自动下载并添加该 box 进来。
31 | 32 |In the next section, we'll bring up the Vagrant environment and interact 33 | with it a little bit.
34 | 35 |在 入门指引 中，我们只用到了在前面就已经添加了的 "hashicorp/precise32" 这个 box， 但在完成了入门指引后，你可能首先会想到的问题是 "在哪里可找到更多 Boxes?"？
38 | 39 |查找 Boxes 最好的地方就是 HashiCorp's Atlas box catalog。 40 | HashiCorp's Atlas 拥有一个存放大量免费且适用于各种平台的 Boxes 公共目录。HashiCorp's Atlas 拥有良好的搜索功能，因此你可以快速查找到自己想要的 Boxes。
41 | 42 |除了查找下载 Boxes, HashiCorp's Atlas 还允许你存放自己的 Boxes，此外还支持存放企业内部使用的私有 Boxes。
43 | 44 | -------------------------------------------------------------------------------- /v2/getting-started/index.html: -------------------------------------------------------------------------------- 1 |入门指引 将带着你一起创建第一个 Vagrant 项目，并向您展示一下 Vagrant 的基本功能特性。
4 | 5 |如果好奇 Vagrant 能为你带来什么好处, 你可以阅读 "为何选择 Vagrant?" 。
6 | 7 |在本操作指引中，将使用 VirtualBox 作为虚拟机管理器（providers）,因为它是免费的、适用于各大平台，且在 Vagrant 已集成。通过阅读指引，别忘记 Vagrant 还可以使用 其他虚拟机管理器（providers）。
8 | 9 |在开始创建你的第一个项目前, 请确保已 安装最新版 Vagrant。 10 | 此外，因为我们使用 VirtualBox 作为虚拟机管理器(provider)，因此也需要安装好它。
11 | 12 |14 | 需要书籍？ 如果你更喜欢阅读纸质的书籍，你可能对这本书感兴趣 15 | 16 | Vagrant: Up and Running 17 | ，这本书是由 Vagrant 的作者编写， O'Reilly出版。 18 |
19 |$ vagrant init hashicorp/precise32
24 | $ vagrant up
25 | 在执行以上两条命令后, 你将拥有一台运行在 VirtualBox 下的 Ubuntu 12.04 LTS 32位 虚拟机。你可以通过 vagrant ssh 命令来 SSH 登录到这台虚拟机上，当你用完以后，可以通过 vagrant destroy 命令来销毁所有的使用痕迹。
现在可以想像一下，你曾经的项目都可以像现在这样简单快速地创建并开始工作。
30 | 31 |使用 Vagrant, 你只需要执行 vagrant up 命令，Vagrant 会自动安装该项目所有环境依赖，设置好网络及共享目录，因此你可以舒舒服服地在你自己的虚拟机上进行工作。
接下来的操作指引将带着你创建一个完整的项目，包括了 Vagrant 更多的功能使用。
34 | 35 | -------------------------------------------------------------------------------- /v2/getting-started/networking.html: -------------------------------------------------------------------------------- 1 |At this point we have a web server up and running with the ability to 4 | modify files from our host and have them automatically synced to the guest. 5 | However, accessing the web pages simply from the terminal from inside 6 | the machine is not very satisfying. In this step, we'll use Vagrant's 7 | networking features to give us additional options for accessing the 8 | machine from our host machine.
9 | 10 |One option is to use port forwarding. Port forwarding allows you to 13 | specify ports on the guest machine to share via a port on the host machine. 14 | This allows you to access a port on your own machine, but actually have 15 | all the network traffic forwarded to a specific port on the guest machine.
16 | 17 |Let's setup a forwarded port so we can access Apache in our guest. Doing so 18 | is a simple edit to the Vagrantfile, which now looks like this:
19 | 20 |Vagrant.configure("2") do |config|
21 | config.vm.box = "hashicorp/precise32"
22 | config.vm.provision :shell, path: "bootstrap.sh"
23 | config.vm.network :forwarded_port, host: 4567, guest: 80
24 | end
25 | Run a vagrant reload or vagrant up (depending on if the machine
28 | is already running) so that these changes can take effect.
Once the machine is running again, load http://127.0.0.1:4567 in
31 | your browser. You should see a web page that is being served from
32 | the virtual machine that was automatically setup by Vagrant.
Vagrant also has other forms of networking, allowing you to assign 37 | a static IP address to the guest machine, or to bridge the guest 38 | machine onto an existing network. If you're interested in other options, 39 | read the networking page.
40 | 41 |Provisioning 42 | Share
-------------------------------------------------------------------------------- /v2/getting-started/project_setup.html: -------------------------------------------------------------------------------- 1 |在创建使用 Vagrant 的第一步，就是对 Vagrantfile 配置文件进行配置。Vagrantfile 配置文件的作用有两个方面：
4 | 5 |设置项目的根目录，很多 Vagrant 的配置都是与根目录有紧密关系。
指定你在项目中所需的虚拟机类型及资源，例如需要安装哪些软件以及在哪里可以访问到这些资源。
Vagrant 有一个内置的命令来初始化一个目录作为 Vagrant 项目的根目录： vagrant init 。在本操作指引中，请根据以下命令在终端进行操作：
$ mkdir vagrant_getting_started
13 | $ cd vagrant_getting_started
14 | $ vagrant init
15 | 上面这些命令会创建一个 Vagrantfile 文件在你当前的目录，你可以打开 Vagrantfile 配置文件查看一下，内容包含了注释说明及实例。不要对配置文件中的内容感到恐惧，稍后我们将对它进行修改。
你也可以在已存在的项目目录中执行 vagrant init 命令，来设置一个已存在的项目。
如果你在项目中使用了版本控制，Vagrantfile 配置文件肯定是需要添加到版本控制中的。这样一来， 每个人都在无需进行前期配置工作即可直接使用该项目。
22 | 23 | -------------------------------------------------------------------------------- /v2/getting-started/providers.html: -------------------------------------------------------------------------------- 1 |In this getting started guide, your project was always backed with 4 | VirtualBox. But Vagrant can work with 5 | a wide variety of backend providers, such as VMware, 6 | AWS, and more. Read the page 7 | of each provider for more information on how to set them up.
8 | 9 |Once you have a provider installed, you don't need to make any modifications
10 | to your Vagrantfile, just vagrant up with the proper provider and
11 | Vagrant will do the rest:
$ vagrant up --provider=vmware_fusion
14 | ...
15 | Ready to move that to the cloud? Take it to AWS:
18 | 19 |$ vagrant up --provider=aws
20 | ...
21 | Once you run vagrant up with another provider, every other Vagrant
24 | command doesn't need to be told what provider to use. Vagrant can automatically
25 | figure it out. So when you're ready to SSH or destroy or anything else,
26 | just run the commands like normal, such as vagrant destroy. No extra
27 | flags necessary.
For more information on providers, read the full documentation on 30 | providers.
31 | 32 | -------------------------------------------------------------------------------- /v2/getting-started/provisioning.html: -------------------------------------------------------------------------------- 1 |目前，我们已经拥有一台运行着 Ubuntu 系统的虚拟机，且我们可以在宿主机上进行开发，文件自动同步到虚拟机中，下面我们将使用web服务器来执行同步目录下的文件。
4 | 5 |We could just SSH in and install a webserver and be on our way, but then
6 | every person who used Vagrant would have to do the same thing. Instead,
7 | Vagrant has built-in support for automated provisioning. Using this
8 | feature, Vagrant will automatically install software when you vagrant up
9 | so that the guest machine can be repeatably created and ready-to-use.
We'll just setup Apache for our basic project,
14 | and we'll do so using a shell script. Create the following shell script
15 | and save it as bootstrap.sh in the same directory as your Vagrantfile:
#!/usr/bin/env bash
18 |
19 | apt-get update
20 | apt-get install -y apache2
21 | if ! [ -L /var/www ]; then
22 | rm -rf /var/www
23 | ln -fs /vagrant /var/www
24 | fi
25 | Next, we configure Vagrant to run this shell script when setting up 28 | our machine. We do this by editing the Vagrantfile, which should now 29 | look like this:
30 | 31 |Vagrant.configure("2") do |config|
32 | config.vm.box = "hashicorp/precise32"
33 | config.vm.provision :shell, path: "bootstrap.sh"
34 | end
35 | The "provision" line is new, and tells Vagrant to use the shell provisioner
38 | to setup the machine, with the bootstrap.sh file. The file path is relative
39 | to the location of the project root (where the Vagrantfile is).
After everything is configured, just run vagrant up to create your
44 | machine and Vagrant will automatically provision it. You should see
45 | the output from the shell script appear in your terminal. If the guest
46 | machine is already running from a previous step, run vagrant reload --provision,
47 | which will quickly restart your virtual machine, skipping the initial
48 | import step. The provision flag on the reload command instructs Vagrant to
49 | run the provisioners, since usually Vagrant will only do this on the first
50 | vagrant up.
After Vagrant completes running, the web server will be up and running. 53 | You can't see the website from your own browser (yet), but you can verify 54 | that the provisioning works by loading a file from SSH within the machine:
55 | 56 |$ vagrant ssh
57 | ...
58 | vagrant@precise32:~$ wget -qO- 127.0.0.1
59 | This works because in the shell script above we installed Apache and
62 | setup the default DocumentRoot of Apache to point to our /vagrant
63 | directory, which is the default synced folder setup by Vagrant.
You can play around some more by creating some more files and viewing 66 | them from the terminal, but in the next step we'll cover networking 67 | options so that you can use your own browser to access the guest machine.
68 | 69 |Synced Folders 70 | Networking
-------------------------------------------------------------------------------- /v2/getting-started/rebuild.html: -------------------------------------------------------------------------------- 1 |When you're ready to come back to your project, whether it is tomorrow, 4 | a week from now, or a year from now, getting it up and running is easy:
5 | 6 |$ vagrant up
7 | That's it! Since the Vagrant environment is already all configured via
10 | the Vagrantfile, you or any of your coworkers simply have to run a
11 | vagrant up at any time and Vagrant will recreate your work environment.
Now that we have a web server up and running and accessible from your machine, 4 | we have a fairly functional development environment. But in addition to 5 | providing a development environment, Vagrant also makes it easy to share 6 | and collaborate on these environments. The primary feature to do this in 7 | Vagrant is called Vagrant Share.
8 | 9 |Vagrant Share lets you share your Vagrant environment to anyone around the 10 | world. It will give you a URL that will route directly to your Vagrant 11 | environment from any device in the world that is connected to the internet.
12 | 13 |Before being able to share your Vagrant environment, you'll need an account on 16 | HashiCorp's Atlas. Don't worry, it's free.
17 | 18 |Once you have an account, log in using vagrant login:
$ vagrant login
21 | Username or Email: mitchellh
22 | Password (will be hidden):
23 | You're now logged in!
24 | Once you're logged in, run vagrant share:
$ vagrant share
31 | ...
32 | ==> default: Your Vagrant Share is running!
33 | ==> default: URL: http://frosty-weasel-0857.vagrantshare.com
34 | ...
35 | Your URL will be different, so don't try the URL above. Instead, copy
38 | the URL that vagrant share outputted for you and visit that in a web
39 | browser. It should load the index page we setup in the previous pages.
Now, modify your "index.html" file and refresh the URL. It will be updated! 42 | That URL is routing directly into your Vagrant environment, and works from 43 | any device in the world that is connected to the internet.
44 | 45 |To end the sharing session, hit Ctrl+C in your terminal. You can refresh
46 | the URL again to verify that your environment is no longer being shared.
Vagrant Share is much more powerful than simply HTTP sharing. For more 49 | details, see the complete Vagrant Share documentation.
50 | 51 |Networking 52 | Teardown
-------------------------------------------------------------------------------- /v2/getting-started/synced_folders.html: -------------------------------------------------------------------------------- 1 |轻轻松松就能创建拥有一台虚拟是一件很酷的事情，但是并不是所有人都喜欢使用SSH登录上去，在终端界面下进行文件的编辑工作。 4 | 幸运的是，Vagrant 可以让你不必这么做，使用 同步目录， Vagrant 5 | 会自动在宿主机和虚拟机间同步该目录。
6 | 7 |默认情况下，Vagrant 共享你的项目跟路径（注意，这个可在 Vagrantfile 中配置）到你宿主机的 /vagrant 目录中。
8 | 再次执行 vagrant up 命令，SSH 登录到你的虚拟机中查看：
$ vagrant up
11 | ...
12 | $ vagrant ssh
13 | ...
14 | vagrant@precise32:~$ ls /vagrant
15 | Vagrantfile
16 | 无论你是否相信， 通过以上命令，在虚拟机中显示的 Vagrantfile 实际与你宿主机 /vagrant/ 目录下的 Vagrantfile 文件是一样的。 19 | 继续创建一个文件来证实：
20 | 21 |vagrant@precise32:~$ touch /vagrant/foo
22 | vagrant@precise32:~$ exit
23 | $ ls
24 | foo Vagrantfile
25 | 哇! "foo" 这个文件已经在你宿主机的 /Vagrant 目录下出现了！因此，Vagrant 是保持了虚拟机与宿主机间这个目录的同步的。
28 | 29 |有了 /Vagrant 这个同步目录，你可以继续在宿主机上使用你惯用的编辑器进行开发，文件则会自动同步至虚拟机中。
30 | 31 |启动并使用SSH登录 32 | Provisioning
-------------------------------------------------------------------------------- /v2/getting-started/teardown.html: -------------------------------------------------------------------------------- 1 |We now have a fully functional virtual machine we can use for basic 4 | web development. But now let's say it is time to switch gears, maybe work 5 | on another project, maybe go out to lunch, or maybe just time to go home. 6 | How do we clean up our development environment?
7 | 8 |With Vagrant, you suspend, halt, or destroy the guest machine. 9 | Each of these options have pros and cons. Choose the method that works 10 | best for you.
11 | 12 |Suspending the virtual machine by calling vagrant suspend will
13 | save the current running state of the machine and stop it. When you're
14 | ready to begin working again, just run vagrant up, and it will be
15 | resumed from where you left off. The main benefit of this method is that it
16 | is super fast, usually taking only 5 to 10 seconds to stop and start your
17 | work. The downside is that the virtual machine still eats up your disk space,
18 | and requires even more disk space to store all the state of the virtual
19 | machine RAM on disk.
Halting the virtual machine by calling vagrant halt will gracefully
22 | shut down the guest operating system and power down the guest machine.
23 | You can use vagrant up when you're ready to boot it again. The benefit of
24 | this method is that it will cleanly shut down your machine, preserving the
25 | contents of disk, and allowing it to be cleanly started again. The downside is
26 | that it'll take some extra time to start from a cold boot, and the guest machine
27 | still consumes disk space.
Destroying the virtual machine by calling vagrant destroy will remove
30 | all traces of the guest machine from your system. It'll stop the guest machine,
31 | power it down, and remove all of the guest hard disks. Again, when you're ready to
32 | work again, just issue a vagrant up. The benefit of this is that no cruft
33 | is left on your machine. The disk space and RAM consumed by the guest machine
34 | is reclaimed and your host machine is left clean. The downside is that
35 | vagrant up to get working again will take some extra time since it
36 | has to reimport the machine and reprovision it.
是时候启动你的第一个 Vagrant 虚拟环境了，执行以下命令：
4 | 5 |$ vagrant up
6 | 一分钟之内，这个命令会执行完毕，你将拥有一个运行 Ubuntu 的虚拟机。你是无法真实地看到 到任何变化，因为 Vagrant 在运行时没有提供 UI 界面。为了证实 Vagrant 已经正确地运行，你可以通过 SSH 登录到虚拟机中查看：
9 | 10 |$ vagrant ssh
11 | 这个命令会带你进入一个完整的 SSH 会话，你可以继续与虚拟机进行交互，也可以进行任何你想做的操作。虽然这个环境可能是临时的，但轻易不要执行 rm -rf / 命令，因为 Vagrant 共享了一个 /vagrant 目录，这个目录是存放在宿主机上的（具体在宿主机在哪个路径是由 Vagrantfile 文件中设置的），如果执行了这个命令，也将删除了宿主机上的这个目录。关于这个同步目录，在下一章节中将会讲到。
我们停下来想一想：只需要一行的配置以及一行的终端命令代码，我们就可以拥有一个功能强大，可 SSH 登录的虚拟机，非常Cool！
16 | 17 |当你摆弄完了这台虚拟机不想再使用的时候, 在你的宿主机器上执行 vagrant destroy
18 | 命令，Vagrant 就会删除所有数据及痕迹。
As with every provider, the Hyper-V 4 | provider has a custom box format that affects how base boxes are made.
5 | 6 |Prior to reading this, you should read the 7 | general guide to creating base boxes. Actually, 8 | it would probably be most useful to keep this open in a separate tab 9 | as you may be referencing it frequently while creating a base box. That 10 | page contains important information about common software to install 11 | on the box.
12 | 13 |Additionally, it is helpful to understand the 14 | basics of the box file format.
15 | 16 |18 | Advanced topic! This is a reasonably advanced topic that 19 | a beginning user of Vagrant doesn't need to understand. If you're 20 | just getting started with Vagrant, skip this and use an available 21 | box. If you're an experienced user of Vagrant and want to create 22 | your own custom boxes, this is for you. 23 |
24 |In addition to the software that should be installed based on the 29 | general guide to creating base boxes, 30 | Hyper-V base boxes require some additional software.
31 | 32 |You'll need to install Hyper-V kernel modules. While this improves performance, 35 | it also enables necessary features such as reporting its IP address so that 36 | Vagrant can access it.
37 | 38 |You can verify Hyper-V kernel modules are properly installed by
39 | running lsmod on Linux machines and looking for modules prefixed with
40 | hv_. Additionally, you'll need to verify that the "Network" tab for your
41 | virtual machine in the Hyper-V manager is reporting an IP address. If it
42 | is not reporting an IP address, Vagrant will not be able to access it.
For most newer Linux distributions, the Hyper-V modules will be available 45 | out of the box.
46 | 47 |Ubuntu 12.04 requires some special steps to make networking work. These 48 | are reproduced here in case similar steps are needed with other distributions. 49 | Without these commands, Ubuntu 12.04 will not report an IP address to 50 | Hyper-V:
51 | 52 |$ sudo apt-get install linux-tools-3.11.0-15-generic
53 | $ sudo apt-get install hv-kvp-daemon-init
54 | $ sudo cp /usr/lib/linux-tools/3.11.0-15/hv_* /usr/sbin/
55 | To package a Hyper-V box, export the virtual machine from the 60 | Hyper-V Manager using the "Export" feature. This will create a directory 61 | with a structure similar to the following:
62 | 63 |.
64 | |-- Snapshots
65 | |-- Virtual Hard drives
66 | |-- Virtual Machines
67 | Delete the "Snapshots" folder. It is of no use to the Vagrant Hyper-V 70 | provider and can only add to the size of the box if there are snapshots 71 | in that folder.
72 | 73 |Then, create the "metadata.json" file necessary for the box, as documented 74 | in basics of the box file format. The proper 75 | provider value to use for the metadata is "hyperv".
76 | 77 |Finally, create an archive of those contents (but not the parent folder)
78 | using a tool such as tar:
$ tar cvzf ~/custom.box ./*
81 | A common mistake is to also package the parent folder by accident. Vagrant 84 | will not work in this case. To verify you've packaged it properly, add the 85 | box to Vagrant and try to bring up the machine.
-------------------------------------------------------------------------------- /v2/hyperv/configuration.html: -------------------------------------------------------------------------------- 1 |The Hyper-V provider has some provider-specific configuration options 4 | you may set. A complete reference is shown below:
5 | 6 |vmname (string) - Name of virtual mashine as shown in Hyper-V manager.
8 | Defaults is taken from box image XML.cpus (integer) - Number of virtual CPU given to mashine.
10 | Defaults is taken from box image XML.memory (integer) - Number of MegaBytes allocated to VM at startup.
12 | Defaults is taken from box image XML.maxmemory (integer) - Number of MegaBytes maximal allowed to allocate for VM
14 | This parameter is switch on Dynamic Allocation of memory.
15 | Defaults is taken from box image XML.ip_address_timeout (integer) - The time in seconds to wait for the
17 | virtual machine to report an IP address. This defaults to 120 seconds.
18 | This may have to be increased if your VM takes longer to boot.Vagrant comes with support out of the box for Hyper-V, 4 | a native hypervisor written by Microsoft. Hyper-V is available by default for 5 | almost all Windows 8.1 installs.
6 | 7 |The Hyper-V provider is compatible with Windows 8.1 only. Prior versions 8 | of Hyper-V do not include the necessary APIs for Vagrant to work.
9 | 10 |Hyper-V must be enabled prior to using the provider. Most Windows installations 11 | will not have Hyper-V enabled by default. To enable Hyper-V, go to 12 | "Programs and Features" and check the box next to "Hyper-V."
13 | 14 |The Hyper-V provider works in almost every way like the VirtualBox 4 | or VMware provider would, but has some limitations that are inherent to 5 | Hyper-V itself.
6 | 7 |Vagrant doesn't yet know how to create and configure new networks for 10 | Hyper-V. When launching a machine with Hyper-V, Vagrant will prompt you 11 | asking what virtual switch you want to connect the virtual machine to.
12 | 13 |A result of this is that networking configurations in the Vagrantfile 14 | are completely ignored with Hyper-V. Vagrant can't enforce a static IP 15 | or automatically configure a NAT.
16 | 17 |However, the IP address of the machine will be reported as part of
18 | the vagrant up, and you can use that IP address as if it were
19 | a host only network.
Vagrant doesn't implement the vagrant package command for Hyper-V
24 | yet, though this should be fairly straightforward to add in a Vagrant
25 | release in the near future.
The Hyper-V provider is used just like any other provider. Please 4 | read the general basic usage page for 5 | providers.
6 | 7 |The value to use for the --provider flag is hyperv.
Hyper-V also requires that you execute Vagrant with administrative 10 | privileges. Creating and managing virtual machines with Hyper-V requires 11 | admin rights. Vagrant will show you an error if it doesn't have the proper 12 | permissions.
13 | 14 |Boxes for Hyper-V can be easily found on
15 | HashiCorp's Atlas. To get started, you might
16 | want to try the hashicorp/precise64 box.
4 | 欢迎访问 Vagrant 中文文档！本文档对 Vagrant 的每一个功能及特性进行了详尽的说明。如果您刚接触 Vagrant，建议您首先阅读 5 | 入门指南 6 | . 7 |
-------------------------------------------------------------------------------- /v2/installation/backwards-compatibility.html: -------------------------------------------------------------------------------- 1 |Vagrant 1.1+ 版提供了向后全兼容 Vagrant 1.0.x 版本（不带插件）。 升级到 Vagrant 1.1 后, 原 1.0.x 的环境无需进行修改便可继续使用，且现有运行的虚拟机也可进行正常的管理。
6 | 7 |兼容性将支持 Vagrant 升级，直至 Vagrant 2.0。 It may still exist after that, but Vagrant's compatibility promise is only for two versions. Seeing that major Vagrant releases take years to develop and release, it is safe to stick with your version 1.0.x Vagrantfile for the time being.
8 | 9 |如果您使用了 Vagrant 1.0.x 插件，您必须移除这些插件，才能进行升级。 Vagrant 1.1+ 采用了新的插件格式，以避免再次发生这种不兼容的情况发生。
10 | 11 |升级后如果你的 Vagrantfile 文件在 1.1 版本下无法运行，且没有使用任何插件，请点击 提交 bug。
12 | 13 |在 2.0 最终版前，我们无法承诺 1.x 版本之间的向后兼容,及 Vagrantfile 配置文件的语法稳定性。任何的向后不兼容将会做出明确的文档说明。
16 | 17 |This is similar to how Vagrant 0.x was handled. In practice, Vagrant 0.x 18 | only introduced a handful of backwards incompatibilities during the entire 19 | development cycle, but the possibility of backwards incompatibilities 20 | is made clear so people aren't surprised.
21 | 22 |Vagrant 2.0 最终会提供一个标准固定的 VagrantFile 配置文件格式，将保留向后兼容，就如 1.0 那样经过斟酌后固定标准。
-------------------------------------------------------------------------------- /v2/installation/index.html: -------------------------------------------------------------------------------- 1 |Vagrant 的安装非常简单。根据你的平台，到这里 4 | 下载 对应的安装包，然后按照普通程序一样进行安装。
5 | 6 |安装包会自动添加 vagrant 到你的系统 path 变量中，
7 | 这样你就可以在命令行下使用 vagrant。如果发现无法使用，请注销并重新登录你的系统（在 Windows 下有时候必须要这样操作才生效）。
如果您之前通过 RubyGems 安装了 Vagrant 1.0.x 旧版本， 请在安装新版本之前卸载掉旧版 Vagrant。
10 | 11 |14 | Vagrant 1.0.x 旧版可以通过 15 | RubyGem 进行安装， 这个安装方式已经被取消，目前只可通过安装包进行安装。 16 |
17 |卸载 Vagrant 非常简单. 你可选择卸载 Vagrant 程序，或删除用户数据，或同时清楚程序及用户数据。 4 | 接下来将介绍如何在各种平台下如何卸载 Vagrant。
5 | 6 |删除 Vagrant 程序将删除vagrant 二进制文件及所有在你机器上的依赖库。删除程序后，你可以通过标准的方法
9 | 重新安装 Vagrant。
Windows平台, 使用控制面板中 添加/删除程序 即可对 Vagrant 进行卸载。
12 | 13 |Mac OS X平台, 删除 /Applications/Vagrant 目录和 /usr/bin/vagrant 文件。然后执行命令
14 | sudo pkgutil --forget com.vagrant.vagrant 使得 OS X
15 | 清除 Vagrant 安装过的痕迹。
Linux平台, 删除 /opt/vagrant 目录和 /usr/bin/vagrant
18 | 文件。
删除用户数据将删除所有 boxes, 23 | plugins, 以及 Vagrant 使用的状态存储数据。 删除用户数据就好比重新安装了一个干净的 Vagrant 。
24 | 25 |在所有的平台上， 删除 ~/.vagrant.d 目录即可删除用户数据。
运行 Vagrant 会自动重新生成运行所需要的数据，所以删除用户数据对程序运行来说是安全的。
-------------------------------------------------------------------------------- /v2/installation/upgrading-from-1-0.html: -------------------------------------------------------------------------------- 1 |从 1.0.x 升级到 1.x 的过程是很简单的。Vagrant 对 1.0.x 版本具有良好的 4 | 向后兼容性 5 | ， 所以你可以很简单地通过下载最新的安装包按照你所在平台的标准安装程序进行安装，即可重新安装 Vagrant。
6 | 7 |就如 向后兼容性 8 | 页面提到的, Vagrant 1.0.x 插件无法升级到 Vagrant 1.1+。许多插件已随着 Vagrant 升级更新到新版本，因此你可以查看所需插件是否已更新，在升级前，最好删除旧版本插件。
9 | 10 |强烈建议，在升级插件之前，最好删除所有 旧版插件, 然后逐步重新添加插件，这样，升级过程变得更加平滑顺利。
11 |但是, 如果你的 Vagrant 版本是通过 RubyGems 安装的, 则必须在安装新版本之前，使用
12 | gem uninstall 卸载旧版本 Vagrant。 基于 RubyGems 的安装方式已经被放弃。
如果从 Vagrant 1.0.x 升级, 请参考 4 | 从 1.0.x 升级 。 5 | 本页涵盖了1.x 系列的升级说明。
6 | 7 |1.x 系列的升级比较简单: 8 | 下载新的安装包，安装并覆盖现有程序，安装程序自动移除旧版文件，linux 安装包管理器也自动清除旧版程序包。
9 | 10 |请注意，Vagrantfile 配置文件的语法兼容性在 2.0 最终版前都不会做出约定，所以 1.0.x 创建 Vagrantfiles 配置文件 11 | 可继续使用, 12 | 新版 Vagrantfile 配置文件 在 2.0 最终版之前都是可向后兼容的。
13 | 14 |Vagrant offers multiple options for how you are able to connect your 4 | guest machines to the network, but there is a standard usage pattern as 5 | well as some points common to all network configurations that 6 | are important to know.
7 | 8 |All networks are configured within your Vagrantfile
11 | using the config.vm.network method call. For example, the Vagrantfile
12 | below defines some port forwarding:
Vagrant.configure("2") do |config|
15 | # other config here
16 |
17 | config.vm.network "forwarded_port", guest: 80, host: 8080
18 | end
19 | Every network type has an identifier such as :forwarded_port in the above
22 | example. Following this is a set of configuration arguments that can differ
23 | for each network type. In the case of forwarded ports, two numeric arguments
24 | are expected: the port on the guest followed by the port on the host that
25 | the guest port can be accessed by.
Multiple networks can be defined by having multiple config.vm.network
30 | calls within the Vagrantfile. The exact meaning of this can differ for
31 | each provider, but in general the order specifies
32 | the order in which the networks are enabled.
Networks are automatically configured and enabled after they've been defined
37 | in the Vagrantfile as part of the vagrant up or vagrant reload process.
Network identifier: forwarded_port
Forwarded ports allow you to access a port on your host machine and have 6 | all data forwarded to a port on the guest machine, over either TCP or UDP.
7 | 8 |For example: If the guest machine is running a web server listening on port 80,
9 | you can make a forwarded port mapping to port 8080 (or anything) on your host
10 | machine. You can then open your browser to localhost:8080 and browse the
11 | website, while all actual network data is being sent to the guest.
The forwarded port configuration expects two parameters, the port on the 16 | guest and the port on the host. Example:
17 | 18 |Vagrant.configure("2") do |config|
19 | config.vm.network "forwarded_port", guest: 80, host: 8080
20 | end
21 | This will allow accessing port 80 on the guest via port 8080 on the host.
24 | 25 |This is a complete list of the options that are available for forwarded
28 | ports. Only the guest and host options are required. Below this section,
29 | there are more detailed examples of using these options.
guest (int) - The port on the guest that you want to be exposed on
33 | the host. This can be any port.
guest_ip (string) - The guest IP to bind the forwarded port to. If
35 | this is not set, the port will go to the every interface. By default,
36 | this is empty.
host (int) - The port on the host that you want to use to access the
38 | port on the guest. This must be greater than port 1024 unless Vagrant
39 | is running as root (which is not recommended).
host_ip (string) - The IP on the host you want to bind the forwarded
41 | port to. If not specified, it will be bound to every IP. By default,
42 | this is empty.
protocol (string) - Either "udp" or "tcp". This specifies the protocol
44 | that will be allowed through the forwarded port. By default this is "tcp".
By default, any defined port will only forward the TCP protocol. As an optional
50 | third parameter, you may specify protocol: 'udp' in order to pass UDP
51 | traffic. If a given port needs to be able to listen to the same port on both
52 | protocols, you must define the port twice with each protocol specified, like
53 | so:
Vagrant.configure("2") do |config|
56 | config.vm.network "forwarded_port", guest: 2003, host: 12003, protocol: 'tcp'
57 | config.vm.network "forwarded_port", guest: 2003, host: 12003, protocol: 'udp'
58 | end
59 | It is common when running multiple Vagrant machines to unknowingly create 64 | forwarded port definitions that collide with each other (two separate 65 | Vagrant projects forwarded to port 8080, for example). Vagrant includes 66 | built-in mechanism to detect this and correct it, automatically.
67 | 68 |Port collision detection is always done. Vagrant will not allow you to 69 | define a forwarded port where the port on the host appears to be accepting 70 | traffic or connections.
71 | 72 |Port collision auto-correction must be manually enabled for each forwarded 73 | port, since it is often surprising when it occurs and can lead the Vagrant 74 | user to think that the port wasn't properly forwarded. Enabling auto correct 75 | is easy:
76 | 77 |Vagrant.configure("2") do |config|
78 | config.vm.network "forwarded_port", guest: 80, host: 8080,
79 | auto_correct: true
80 | end
81 | The final :auto_correct parameter set to true tells Vagrant to auto
84 | correct any collisions. During a vagrant up or vagrant reload, Vagrant
85 | will output information about any collisions detections and auto corrections
86 | made, so you can take notice and act accordingly.
In order to access the Vagrant environment created, Vagrant exposes 4 | some high-level networking options for things such as forwarded ports, 5 | connecting to a public network, or creating a private network.
6 | 7 |The high-level networking options are meant to define an abstraction that 8 | works across multiple providers. This means that 9 | you can take your Vagrantfile you used to spin up a VirtualBox machine and 10 | you can reasonably expect that Vagrantfile to behave the same with something 11 | like VMware.
12 | 13 |You should first read the basic usage page 14 | and then continue by reading the documentation for a specific networking 15 | primitive by following the navigation to the left.
16 | 17 |In some cases, 20 | these options are too high-level, and you may want to more finely tune 21 | and configure the network interfaces of the underlying machine. Most 22 | providers expose provider-specific configuration 23 | to do this, so please read the documentation for your specific provider 24 | to see what options are available.
25 | 26 |28 | For beginners: It is strongly recommended you use 29 | only the high-level networking options until you are comfortable 30 | with the Vagrant workflow and have things working at a basic level. 31 | Provider-specific network configuration can very quickly lock you out 32 | of your guest machine if improperly done. 33 |
34 |Network identifier: private_network
Private networks allow you to access your guest machine by some address 6 | that is not publicly accessible from the global internet. In general, this 7 | means your machine gets an address in the private address space.
8 | 9 |Multiple machines within the same private network (also usually with the 10 | restriction that they're backed by the same provider) 11 | can communicate with each other on private networks.
12 | 13 |15 | Guest operating system support. Private networks 16 | generally require configuring the network adapters on the guest 17 | machine. This process varies from OS to OS. Vagrant ships with 18 | knowledge of how to configure networks on a variety of guest 19 | operating systems, but it is possible if you're using a particularly 20 | old or new operating system that private networks won't properly 21 | configure. 22 |
23 |The easiest way to use a private network is to allow the IP to be assigned 28 | via DHCP.
29 | 30 |Vagrant.configure("2") do |config|
31 | config.vm.network "private_network", type: "dhcp"
32 | end
33 | This will automatically assign an IP address from the reserved address space.
36 | The IP address can be determined by using vagrant ssh to SSH into the
37 | machine and using the appropriate command line tool to find the IP,
38 | such as ifconfig.
You can also specify a static IP address for the machine. This lets you 43 | access the Vagrant managed machine using a static, known IP. The 44 | Vagrantfile for a static IP looks like this:
45 | 46 |Vagrant.configure("2") do |config|
47 | config.vm.network "private_network", ip: "192.168.50.4"
48 | end
49 | It is up to the users to make sure that the static IP doesn't collide 52 | with any other machines on the same network.
53 | 54 |While you can choose any IP you'd like, you should use an IP from 55 | the reserved private address space. These IPs are guaranteed to never be publicly routable, 56 | and most routers actually block traffic from going to them from the 57 | outside world.
58 | 59 |If you want to manually configure the network interface yourself, you
62 | can disable Vagrant's auto-configure feature by specifying auto_config:
Vagrant.configure("2") do |config|
65 | config.vm.network "private_network", ip: "192.168.50.4",
66 | auto_config: false
67 | end
68 | Network identifier: public_network
Public networks are less private than private networks, and the exact 6 | meaning actually varies from provider to provider, 7 | hence the ambiguous definition. The idea is that while 8 | private networks should never allow the 9 | general public access to your machine, public networks can.
10 | 11 |
13 | Confused? We kind of are, too. It is likely that
14 | public networks will be replaced by :bridged in a
15 | future release, since that is in general what should be done with
16 | public networks, and providers that don't support bridging generally
17 | don't have any other features that map to public networks either.
18 |
23 | Warning! Vagrant boxes are insecure by default 24 | and by design, featuring public passwords, insecure keypairs 25 | for SSH access, and potentially allow root access over SSH. With 26 | these known credentials, your box is easily accessible by anyone on 27 | your network. Before configuring Vagrant to use a public network, 28 | consider all potential security implications 29 | and review the default box 30 | configuration to identify potential security risks. 31 |
32 |The easiest way to use a public network is to allow the IP to be assigned 37 | via DHCP. In this case, defining a public network is trivially easy:
38 | 39 |Vagrant.configure("2") do |config|
40 | config.vm.network "public_network"
41 | end
42 | When DHCP is used, the IP can be determined by using vagrant ssh to
45 | SSH into the machine and using the appropriate command line tool to find
46 | the IP, such as ifconfig.
Depending on your setup, you may wish to manually set the IP of your
51 | bridged interface. To do so, add a :ip clause to the network definition.
config.vm.network "public_network", ip: "192.168.0.17"
54 | If more than one network interface is available on the host machine, Vagrant will
59 | ask you to choose which interface the virtual machine should bridge to. A default
60 | interface can be specified by adding a :bridge clause to the network definition.
config.vm.network "public_network", bridge: 'en1: Wi-Fi (AirPort)'
63 | The string identifying the desired interface must exactly match the name of an 66 | available interface. If it can't be found, Vagrant will ask you to pick 67 | from a list of available network interfaces.
-------------------------------------------------------------------------------- /v2/other/debugging.html: -------------------------------------------------------------------------------- 1 |As much as we try to keep Vagrant stable and bug free, it is inevitable 4 | that issues will arise and Vagrant will behave in unexpected ways. In 5 | these cases, Vagrant has amazing support 6 | channels available to assist you.
7 | 8 |When using these support channels, it is generally helpful to include 9 | debugging logs along with any error reports. These logs can often help you 10 | troubleshoot any problems you may be having.
11 | 12 |To enable detailed logging, set the VAGRANT_LOG environmental variable
13 | to the desired log level name, which is one of debug (loud), info (normal),
14 | warn (quiet), and error (very quiet). When asking for support, please
15 | set this to debug. When troubleshooting your own issues, you should start
16 | with info, which is much quieter, but contains important information
17 | about the behavior of Vagrant.
On Linux and Mac systems, this can be done by prepending the vagrant
20 | command with an environmental variable declaration:
$ VAGRANT_LOG=info vagrant up
23 | ...
24 | On Windows, multiple steps are required:
27 | 28 |$ set VAGRANT_LOG=info
29 | $ vagrant up
30 | ...
31 | You can also get the debug level output using the --debug command line
34 | option. For example:
$ vagrant up --debug
37 | ...
38 | If you plan on submitting a bug report, please submit debug-level logs 41 | along with the report using gist or 42 | some other paste service.
-------------------------------------------------------------------------------- /v2/other/environmental-variables.html: -------------------------------------------------------------------------------- 1 |Vagrant has a set of environmental variables that can be used to 4 | configure and control it in a global way. This page lists those environmental 5 | variables.
6 | 7 |Vagrant does occasional network calls to check whether the version of Vagrant
10 | that is running locally is up to date. We understand that software making remote
11 | calls over the internet for any reason can be undesirable. To surpress these
12 | calls, set the environment variable VAGRANT_CHECKPOINT_DISABLE to any
13 | non-empty value.
VAGRANT_CWD can be set to change the working directory of Vagrant. By
18 | default, Vagrant uses the current directory you're in. The working directory
19 | is important because it is where Vagrant looks for the Vagrantfile. It
20 | also defines how relative paths in the Vagrantfile are expanded, since they're
21 | expanded relative to where the Vagrantfile is found.
This environmental variable is most commonly set when running Vagrant from 24 | a scripting environment in order to set the directory that Vagrant sees.
25 | 26 |VAGRANT_DOTFILE_PATH can be set to change the directory where Vagrant stores VM-specific state, such as the VirtualBox VM UUID. By default, this is set to .vagrant. If you keep your Vagrantfile in a Dropbox folder in order to share the folder between your desktop and laptop (for example), Vagrant will overwrite the files in this directory with the details of the VM on the most recently-used host. To avoid this, you could set VAGRANT_DOTFILE_PATH to .vagrant-laptop and .vagrant-desktop on the respective machines. (Remember to update your .gitignore!)
VAGRANT_HOME can be set to change the directory where Vagrant stores
33 | global state. By default, this is set to ~/.vagrant.d. The Vagrant home
34 | directory is where things such as boxes are stored, so it can actually become
35 | quite large on disk.
VAGRANT_LOG specifies the verbosity of log messages from Vagrant.
40 | By default, Vagrant does not actively show any log messages.
Log messages are very useful when troubleshooting issues, reporting 43 | bugs, or getting support. At the most verbose level, Vagrant outputs 44 | basically everything it is doing.
45 | 46 |Available log levels are "debug," "info," "warn," and "error." Both 47 | "warn" and "error" are practically useless since there are very few 48 | cases of these, and Vagrant generally reports them within the normal 49 | output.
50 | 51 |"info" is a good level to start with if you're having problems, because 52 | while it is much louder than normal output, it is still very human-readable 53 | and can help identify certain issues.
54 | 55 |"debug" output is extremely verbose and can be difficult to read without 56 | some knowledge of Vagrant internals. It is the best output to attach to 57 | a support request or bug report, however.
58 | 59 |If this is set to any value, then Vagrant will not use any colorized 62 | output. This is useful if you're logging the output to a file or 63 | on a system that doesn't support colors.
64 | 65 |The equivalent behavior can be achieved by using the --no-color flag
66 | on a command-by-command basis. This environmental variable is useful
67 | for setting this flag globally.
If this is set to any value, then Vagrant will not load any 3rd party 72 | plugins. This is useful if you install a plugin and it is introducing 73 | instability to Vagrant, or if you want a specific Vagrant environment to 74 | not load plugins.
75 | 76 |Note that any vagrant plugin commands automatically don't load any
77 | plugins, so if you do install any unstable plugins, you can always use
78 | the vagrant plugin commands without having to worry.
This specifies the filename of the Vagrantfile that Vagrant searches for. 83 | By default, this is "Vagrantfile." Note that this is not a file path, 84 | but just a filename.
85 | 86 |This environmental variable is commonly used in scripting environments 87 | where a single folder may contain multiple Vagrantfiles representing 88 | different configurations.
-------------------------------------------------------------------------------- /v2/other/index.html: -------------------------------------------------------------------------------- 1 |This section covers other information that doesn't quite fit under the 4 | other categories. Please see the navigation to the left.
5 | -------------------------------------------------------------------------------- /v2/plugins/guest-capabilities.html: -------------------------------------------------------------------------------- 1 |This page documents how to add new capabilities for guests 4 | to Vagrant, allowing Vagrant to perform new actions on specific guest 5 | operating systems. 6 | Prior to reading this, you should be familiar 7 | with the plugin development basics.
8 | 9 |11 | Warning: Advanced Topic! Developing plugins is an 12 | advanced topic that only experienced Vagrant users who are reasonably 13 | comfortable with Ruby should approach. 14 |
15 |Guest capabilities augment guests by attaching 18 | specific "capabilities" to the guest, which are actions that can be performed 19 | in the context of that guest operating system.
20 | 21 |The power of capabilities is that plugins can add new capabilities to 22 | existing guest operating systems without modifying the core of Vagrant. 23 | In earlier versions of Vagrant, all the guest logic was contained in the 24 | core of Vagrant and wasn't easily augmented.
25 | 26 |Within the context of a plugin definition, guest capabilities can be 29 | defined like so:
30 | 31 |guest_capability "ubuntu", "my_custom_capability" do
32 | require_relative "cap/my_custom_capability"
33 | Cap::MyCustomCapability
34 | end
35 | Guest capabilities are defined by calling the guest_capability method,
38 | which takes two parameters: the guest to add the capability to, and the
39 | name of the capability itself. Then, the block argument returns a class
40 | that implements a method named the same as the capability. This is
41 | covered in more detail in the next section.
Implementations should be classes or modules that have a method with
46 | the same name as the capability. The method must be immediately accessible
47 | on the class returned from the guest_capability component, meaning that
48 | if it is an instance method, an instance should be returned.
In general, class methods are used for capabilities. For example, here 51 | is the implementation for the capability above:
52 | 53 |module Cap
54 | class MyCustomCapability
55 | def self.my_custom_capability(machine)
56 | # implementation
57 | end
58 | end
59 | end
60 | All capabilities get the Vagrant machine object as the first argument. 63 | Additional arguments are determined by the specific capability, so view the 64 | documentation or usage of the capability you're trying to implement for more 65 | information.
66 | 67 |Some capabilities must also return values back to the caller, so be aware 68 | of that when implementing a capability.
69 | 70 |Capabilities always have access to communication channels such as SSH 71 | on the machine, and the machine can generally be assumed to be booted.
72 | 73 |Since you have access to the machine in every capability, capabilities can 76 | also call other capabilities. This is useful for using the inheritance 77 | mechanism of capabilities to potentially ask helpers for more information. 78 | For example, the "redhat" guest has a "network_scripts_dir" capability that 79 | simply returns the directory where networking scripts go.
80 | 81 |Capabilities on child guests of RedHat such as CentOS or Fedora use this 82 | capability to determine where networking scripts go, while sometimes overriding 83 | it themselves.
84 | 85 |Capabilities can be called like so:
86 | 87 |machine.guest.capability(:capability_name)
88 | Any additional arguments given to the method will be passed on to the 91 | capability, and the capability will return the value that the actual 92 | capability returned.
-------------------------------------------------------------------------------- /v2/plugins/guests.html: -------------------------------------------------------------------------------- 1 |This page documents how to add new guest OS detection to Vagrant, allowing 4 | Vagrant to properly configure new operating systems. 5 | Prior to reading this, you should be familiar 6 | with the plugin development basics.
7 | 8 |10 | Warning: Advanced Topic! Developing plugins is an 11 | advanced topic that only experienced Vagrant users who are reasonably 12 | comfortable with Ruby should approach. 13 |
14 |Vagrant has many features that requires doing guest OS-specific 17 | actions, such as mounting folders, configuring networks, etc. These 18 | tasks vary from operating system to operating system. If you find that 19 | one of these doesn't work for your operating system, then maybe the 20 | guest implementation is incomplete or incorrect.
21 | 22 |Within the context of a plugin definition, new guests can be defined 25 | like so:
26 | 27 |guest "ubuntu" do
28 | require_relative "guest"
29 | Guest
30 | end
31 | Guests are defined with the guest method. The first argument is the
34 | name of the guest. This name isn't actually used anywhere, but may in the
35 | future, so choose something helpful. Then, the block argument returns a
36 | class that implements the Vagrant.plugin(2, :guest) interface.
Implementations of guests subclass Vagrant.plugin("2", "guest"). Within
41 | this implementation, only the detect? method needs to be implemented.
The detect? method is called by Vagrant at some point after the machine
44 | is booted in order to determine what operating system the guest is running.
45 | If you detect that it is your operating system, return true from detect?.
46 | Otherwise, return false.
Communication channels to the machine are guaranteed to be running at this 49 | point, so the most common way to detect the operating system is to do 50 | some basic testing:
51 | 52 |class MyGuest < Vagrant.plugin("2", "guest")
53 | def detect?(machine)
54 | machine.communicate.test("cat /etc/myos-release")
55 | end
56 | end
57 | After detecting an OS, that OS is used for various 60 | guest capabilities that may be 61 | required.
62 | 63 |Vagrant also supports a form of inheritance for guests, since sometimes 66 | operating systems stem from a common root. A good example of this is Linux 67 | is the root of Debian, which further is the root of Ubuntu in many cases. 68 | Inheritance allows guests to share a lot of common behavior while allowing 69 | distro-specific overrides.
70 | 71 |Inheritance is not done via standard Ruby class inheritance because Vagrant 72 | uses a custom capability-based system. 73 | Vagrant handles inheritance dispatch for you.
74 | 75 |To subclass another guest, specify that guest's name as a second parameter 76 | in the guest definition:
77 | 78 |guest "ubuntu", "debian" do
79 | require_relative "guest"
80 | Guest
81 | end
82 | With the above component, the "ubuntu" guest inherits from "debian." When 85 | a capability is looked up for "ubuntu", all capabilities from "debian" are 86 | also available, and any capabilities in "ubuntu" override parent capabilities.
87 | 88 |When detecting operating systems with detect?, Vagrant always does a
89 | depth-first search by searching the children operating systems before
90 | checking their parents. Therefore, it is guaranteed in the above example
91 | that the detect? method on "ubuntu" will be called before "debian."
This page documents how to add new capabilities for hosts 4 | to Vagrant, allowing Vagrant to perform new actions on specific host 5 | operating systems. 6 | Prior to reading this, you should be familiar 7 | with the plugin development basics.
8 | 9 |11 | Warning: Advanced Topic! Developing plugins is an 12 | advanced topic that only experienced Vagrant users who are reasonably 13 | comfortable with Ruby should approach. 14 |
15 |Host capabilities augment hosts by attaching 18 | specific "capabilities" to the host, which are actions that can be performed 19 | in the context of that host operating system.
20 | 21 |The power of capabilities is that plugins can add new capabilities to 22 | existing host operating systems without modifying the core of Vagrant. 23 | In earlier versions of Vagrant, all the host logic was contained in the 24 | core of Vagrant and wasn't easily augmented.
25 | 26 |The definition and implementation of host capabilities is identical 29 | to guest capabilities.
30 | 31 |The main difference from guest capabilities, however, is that instead of
32 | taking a machine as the first argument, all host capabilities take an
33 | instance of Vagrant::Environment as their first argument.
Access to the environment allows host capabilities to access global state, 36 | specific machines, and also allows them to call other host capabilities.
37 | 38 |Since you have access to the environment in every capability, capabilities can 41 | also call other host capabilities. This is useful for using the inheritance 42 | mechanism of capabilities to potentially ask helpers for more information. 43 | For example, the "linux" guest has a "nfs_check_command" capability that 44 | returns the command to use to check if NFS is running.
45 | 46 |Capabilities on child guests of Linux such as RedHat or Arch use this 47 | capability to mostly inherit the Linux behavior, except for this minor 48 | detail.
49 | 50 |Capabilities can be called like so:
51 | 52 |environment.host.capability(:capability_name)
53 | Any additional arguments given to the method will be passed on to the 56 | capability, and the capability will return the value that the actual 57 | capability returned.
-------------------------------------------------------------------------------- /v2/plugins/hosts.html: -------------------------------------------------------------------------------- 1 |This page documents how to add new host OS detection to Vagrant, allowing 4 | Vagrant to properly execute host-specific operations on new operating systems. 5 | Prior to reading this, you should be familiar 6 | with the plugin development basics.
7 | 8 |10 | Warning: Advanced Topic! Developing plugins is an 11 | advanced topic that only experienced Vagrant users who are reasonably 12 | comfortable with Ruby should approach. 13 |
14 |Vagrant has some features that require host OS-specific actions, such as 17 | exporting NFS folders. These tasks vary from operating system to operating 18 | system. Vagrant uses host detection as well as 19 | host capabilities to perform these 20 | host OS-specific operations.
21 | 22 |Within the context of a plugin definition, new hosts can be defined 25 | like so:
26 | 27 |host "ubuntu" do
28 | require_relative "host"
29 | Host
30 | end
31 | Hosts are defined with the host method. The first argument is the
34 | name of the host. This name isn't actually used anywhere, but may in the
35 | future, so choose something helpful. Then, the block argument returns a
36 | class that implements the Vagrant.plugin(2, :host) interface.
Implementations of hosts subclass Vagrant.plugin("2", "host"). Within
41 | this implementation, only the detect? method needs to be implemented.
The detect? method is called by Vagrant very early on in its initialization
44 | process to determine if the OS that Vagrant is running on is this host.
45 | If you detect that it is your operating system, return true from detect?.
46 | Otherwise, return false.
class MyHost < Vagrant.plugin("2", "host")
49 | def detect?(environment)
50 | File.file?("/etc/arch-release")
51 | end
52 | end
53 | After detecting an OS, that OS is used for various 56 | host capabilities that may be 57 | required.
58 | 59 |Vagrant also supports a form of inheritance for hosts, since sometimes 62 | operating systems stem from a common root. A good example of this is Linux 63 | is the root of Debian, which further is the root of Ubuntu in many cases. 64 | Inheritance allows hosts to share a lot of common behavior while allowing 65 | distro-specific overrides.
66 | 67 |Inheritance is not done via standard Ruby class inheritance because Vagrant 68 | uses a custom capability-based system. 69 | Vagrant handles inheritance dispatch for you.
70 | 71 |To subclass another host, specify that host's name as a second parameter 72 | in the host definition:
73 | 74 |host "ubuntu", "debian" do
75 | require_relative "host"
76 | Host
77 | end
78 | With the above component, the "ubuntu" host inherits from "debian." When 81 | a capability is looked up for "ubuntu", all capabilities from "debian" are 82 | also available, and any capabilities in "ubuntu" override parent capabilities.
83 | 84 |When detecting operating systems with detect?, Vagrant always does a
85 | depth-first search by searching the children operating systems before
86 | checking their parents. Therefore, it is guaranteed in the above example
87 | that the detect? method on "ubuntu" will be called before "debian."
Vagrant comes with many great features out of the box to get your environments up 4 | and running. Sometimes, however, you want to change the way Vagrant does something 5 | or add additional functionality to Vagrant. This can be done via Vagrant 6 | plugins.
7 | 8 |Plugins are powerful, first-class citizens that extend Vagrant using a 9 | well-documented, stable API that can withstand major version upgrades.
10 | 11 |In fact, most of the core of Vagrant is implemented using plugins. 12 | Since Vagrant dogfoods its own 13 | plugin API, you can be confident that the interface is stable and well supported.
14 | 15 |Use the navigation on the left below the "Plugins" section to learn more 16 | about how to use and build your own plugins.
-------------------------------------------------------------------------------- /v2/plugins/provisioners.html: -------------------------------------------------------------------------------- 1 |This page documents how to add new provisioners to Vagrant, 4 | allowing Vagrant to automatically install software and configure software 5 | using a custom provisioner. Prior to reading this, you should be familiar 6 | with the plugin development basics.
7 | 8 |10 | Warning: Advanced Topic! Developing plugins is an 11 | advanced topic that only experienced Vagrant users who are reasonably 12 | comfortable with Ruby should approach. 13 |
14 |Within the context of a plugin definition, new provisioners can be defined 19 | like so:
20 | 21 |provisioner "custom" do
22 | require_relative "provisioner"
23 | Provisioner
24 | end
25 | Provisioners are defined with the provisioner method, which takes a
28 | single argument specifying the name of the provisioner. This is the
29 | name that used with config.vm.provision when configuring and enabling
30 | the provisioner. So in the case above, the provisioner would be enabled
31 | using config.vm.provision :custom.
The block argument then lazily loads and returns a class that implements
34 | the Vagrant.plugin(2, :provisioner) interface, which is covered next.
The provisioner class should subclass and implement
39 | Vagrant.plugin(2, :provisioner) which is an upgrade-safe way to let
40 | Vagrant return the proper parent class for provisioners.
This class and the methods that need to be implemented are 43 | very well documented. 44 | The documentation on the class in the comments should be enough 45 | to understand what needs to be done.
46 | 47 |There are two main methods that need to be implemented: the
48 | configure method and the provision method.
The configure method is called early in the machine booting process
51 | to allow the provisioner to define new configuration on the machine, such
52 | as sharing folders, defining networks, etc. As an example, the
53 | Chef solo provisioner
54 | uses this to define shared folders.
The provision method is called when the machine is booted and ready
57 | for SSH connections. In this method, the provisioner should execute
58 | any commands that need to be executed.
Installing a plugin is easy, and shouldn't take more than a few seconds.
4 | 5 |Please refer to the documentation of any plugin you plan on using for 6 | more information on how to use it, but there is one common method for 7 | installation and plugin activation.
8 | 9 |11 | Warning! 3rd party plugins can introduce instabilities 12 | into Vagrant due to the nature of them being written by non-core users. 13 |
14 |Plugins are installed using vagrant plugin install:
$ vagrant plugin install vagrant-example-plugin
21 | ...
22 | Once a plugin is installed, it will automatically be loaded by Vagrant. 25 | Plugins which cannot be loaded shouldn't crash Vagrant. Instead, 26 | Vagrant will show an error message that a plugin failed to load.
27 | 28 |Once a plugin is installed, you should refer to the plugin's documentation
31 | to see exactly how to use it. Plugins which add commands should be instantly
32 | available via vagrant, provisioners should be available via
33 | config.vm.provision, etc.
Note: In the future, the vagrant plugin command will include a
36 | subcommand that will document the components that each plugin installs.
Plugins can be updated by running vagrant plugin update. This will
41 | update every installed plugin to the latest version. You can update a
42 | specific plugin by calling vagrant plugin update NAME. Vagrant will
43 | output what plugins were updated and to what version.
To determine the changes in a specific version of a plugin, refer to 46 | the plugin's homepage (usually a GitHub page or similar). It is the 47 | plugin author's responsibility to provide a change log if he or she 48 | chooses to.
49 | 50 |Uninstalling a plugin is as easy as installing it. Just use the
53 | vagrant plugin uninstall command and the plugin will be removed. Example:
$ vagrant plugin uninstall vagrant-example-plugin
56 | ...
57 | To view what plugins are installed into your Vagrant environment at
62 | any time, use the vagrant plugin list command. This will list the plugins
63 | that are installed along with their version.
Boxes are all provider-specific. A box for VirtualBox is incompatible with 6 | the VMware Fusion provider, or any other provider. A box must be installed 7 | for each provider, and can share the same name as other boxes as long 8 | as the providers differ. So you can have both a VirtualBox and VMware Fusion 9 | "precise64" box.
10 | 11 |Installing boxes hasn't changed at all:
12 | 13 |$ vagrant box add \
14 | precise64 http://files.vagrantup.com/precise64.box
15 | Vagrant now automatically detects what provider a box is for. This is 18 | visible when listing boxes. Vagrant puts the provider in parentheses next 19 | to the name, as can be seen below.
20 | 21 |$ vagrant box list
22 | precise64 (virtualbox)
23 | precise64 (vmware_fusion)
24 | Once a provider is installed, you can use it by calling vagrant up
29 | with the --provider flag. This will force Vagrant to use that specific
30 | provider. No other configuration is necessary!
In normal day-to-day usage, the --provider flag isn't necessary
33 | since Vagrant can usually pick the right provider for you. More details
34 | on how it does this is below.
$ vagrant up --provider=vmware_fusion
37 | If you specified a --provider flag, you only need to do this for the
40 | up command. Once a machine is up and running, Vagrant is able to
41 | see what provider is backing a running machine, so commands such as
42 | destroy, suspend, etc. do not need to be told what provider to use.
47 | Vagrant currently restricts you to bringing up one provider per machine. 48 | If you have a multi-machine environment, you can bring up one machine 49 | backed by VirtualBox and another backed by VMware Fusion, for example, but you 50 | can't back the same machine with both VirtualBox and 51 | VMware Fusion. 52 |
53 | 54 |55 | This is a limitation that will be removed in a future version of 56 | Vagrant. 57 |
58 |As mentioned earlier, you typically don't need to specify --provider
63 | ever. Vagrant is smart enough about being able to detect the provider
64 | you want for a given environment.
Vagrant attempts to find the default provider in the following order:
67 | 68 |The --provider flag on a vagrant up is chosen above all else, if
70 | it is present.
If the VAGRANT_DEFAULT_PROVIDER environmental variable is set,
72 | it takes next priority and will be the provider chosen.
Vagrant will go through all of the config.vm.provider calls in the
74 | Vagrantfile and try each in order. It will choose the first provider
75 | that is usable. For example, if you configure Hyper-V, it will never
76 | be chosen on Mac this way. It must be both configured and usable.
Vagrant will go through all installed provider plugins (including the 78 | ones that come with Vagrant), and find the first plugin that reports 79 | it is usable. There is a priority system here: systems that are known 80 | better have a higher priority than systems that are worse. For example, 81 | if you have the VMware provider installed, it will always take priority 82 | over VirtualBox.
If Vagrant still hasn't found any usable providers, it will error.
Using this method, there are very few cases that Vagrant doesn't find the 87 | correct provider for you. This also allows each 88 | Vagrantfile to define what providers 89 | the development environment is made for by ordering provider configurations.
90 | 91 |A trick is to use config.vm.provider with no configuration at the top of
92 | your Vagrantfile to define the order of providers you prefer to support:
Vagrant.configure("2") do |config|
95 | # ... other config up here
96 |
97 | # Prefer VMware Fusion before VirtualBox
98 | config.vm.provider "vmware_fusion"
99 | config.vm.provider "virtualbox"
100 | end
101 | While well-behaved providers should work with any Vagrantfile with sane 4 | defaults, providers generally expose unique configuration 5 | options so that you can get the most out of each provider.
6 | 7 |This provider-specific configuration is done within the Vagrantfile 8 | in a way that is portable, easy to use, and easy to understand.
9 | 10 |An important fact is that even if you configure other providers within 13 | a Vagrantfile, the Vagrantfile remains portable even to individuals who 14 | don't necessarily have that provider installed.
15 | 16 |For example, if you configure VMware Fusion and send it to an individual 17 | who doesn't have the VMware Fusion provider, Vagrant will silently ignore 18 | that part of the configuration.
19 | 20 |Configuring a specific provider looks like this:
23 | 24 |Vagrant.configure("2") do |config|
25 | # ... (other config)
26 |
27 | config.vm.provider "virtualbox" do |vb|
28 | vb.customize ["modifyvm", :id, "--cpuexecutioncap", "50"]
29 | end
30 | end
31 | Multiple config.vm.provider blocks can exist to configure multiple
34 | providers.
The configuration format should look very similar to how provisioners
37 | are configured. The config.vm.provider takes a single parameter: the
38 | name of the provider being configured. Then, an inner block with custom
39 | configuration options is exposed that can be used to configure that
40 | provider.
This inner configuration differs among providers, so please read the 43 | documentation for your provider of choice to see available configuration 44 | options.
45 | 46 |Remember, some providers don't require any provider-specific configuration 47 | and work directly out of the box. Provider-specific configuration is meant 48 | as a way to expose more options to get the most of the provider of your 49 | choice. It is not meant as a roadblock to running against a specific provider.
50 | 51 |Providers can also override non-provider specific configuration, such
54 | as config.vm.box and any other Vagrant configuration. This is done by
55 | specifying a second argument to config.vm.provider. This argument is
56 | just like the normal config, so set any settings you want, and they will
57 | be overridden only for that provider.
Example:
60 | 61 |Vagrant.configure("2") do |config|
62 | config.vm.box = "precise64"
63 |
64 | config.vm.provider "vmware_fusion" do |v, override|
65 | override.vm.box = "precise64_fusion"
66 | end
67 | end
68 | In the above case, Vagrant will use the "precise64" box by default, but 71 | will use "precise64_fusion" if the VMware Fusion provider is used.
72 | 73 |75 | The Vagrant Way: The proper "Vagrant way" is to 76 | avoid any provider-specific overrides if possible by making boxes 77 | for multiple providers that are as identical as possible, since box 78 | names can map to multiple providers. However, this isn't always possible, 79 | and in those cases, overrides are available. 80 |
81 |To learn how to make your own custom providers, read the plugin development 4 | guide on creating custom providers.
-------------------------------------------------------------------------------- /v2/providers/default.html: -------------------------------------------------------------------------------- 1 |By default, VirtualBox is the default provider for Vagrant. VirtualBox is 4 | still the most accessible platform to use Vagrant: it is free, cross-platform, 5 | and has been supported by Vagrant for years. With VirtualBox as the default 6 | provider, it provides the lowest friction for new users to get started with 7 | Vagrant.
8 | 9 |However, you may find after using Vagrant for some time that you prefer
10 | to use another provider as your default. In fact, this is quite common.
11 | To make this experience better, Vagrant allows specifying the default
12 | provider to use by setting the VAGRANT_DEFAULT_PROVIDER environmental
13 | variable.
Just set VAGRANT_DEFAULT_PROVIDER to the provider you wish to be the
16 | default. For example, if you use Vagrant with VMware Fusion, you can set
17 | the environmental variable to vmware_fusion and it will be your default.
While Vagrant ships out of the box with support for VirtualBox, 4 | Vagrant has the ability to manage other types of machines as well. This is done 5 | by using other providers with Vagrant.
6 | 7 |Alternate providers can offer different features that make more sense in your use case. 8 | For example, if you're using Vagrant for any real work, VMware 9 | providers are recommended since they're well supported and generally more 10 | stable and performant than VirtualBox.
11 | 12 |Before you can use another provider, you must install it. Vagrant only ships 13 | with VirtualBox support. Installation of other providers is done via the 14 | Vagrant plugin system.
15 | 16 |Once the provider is installed, usage is straightforward and simple, as 17 | you would expect with Vagrant. Read into the relevant subsections found in 18 | the navigation to the left for more information.
-------------------------------------------------------------------------------- /v2/providers/installation.html: -------------------------------------------------------------------------------- 1 |Providers are distributed as Vagrant plugins, and are therefore installed 4 | using standard plugin installation steps. After 5 | installing a plugin which contains a provider, the provider should 6 | immediately be available.
-------------------------------------------------------------------------------- /v2/provisioning/chef_zero.html: -------------------------------------------------------------------------------- 1 |Provisioner name: chef_zero
The Chef Zero provisioner allows you to provision the guest using 6 | Chef, specifically with 7 | Chef Zero/local mode.
8 | 9 |This new provisioner is a middle ground between running a full blown 10 | Chef Server and using the limited Chef Solo 11 | provisioner. It runs a local in-memory Chef Server and fakes the validation 12 | and client key registration.
13 | 14 |16 | Warning: If you're not familiar with Chef and Vagrant already, 17 | I recommend starting with the shell 18 | provisioner. However, if you're comfortable with Vagrant already, Vagrant 19 | is the best way to learn Chef. 20 |
21 |This section lists the complete set of available options for the Chef Zero 26 | provisioner. More detailed examples of how to use the provisioner are 27 | available below this section.
28 | 29 |nodes_path (string) - A path where the Chef nodes are stored. Be default,
31 | no node path is set.In addition to all the options listed above, the Chef Zero provisioner supports 35 | the common options for all Chef provisioners.
36 | 37 |The Chef Zero provisioner is configured basically the same way as the Chef Solo 40 | provisioner. See the Chef Solo documentations 41 | for more information.
42 | 43 |A basic example could look like this:
44 | 45 |Vagrant.configure("2") do |config|
46 | config.vm.provision "chef_zero" do |chef|
47 | # Specify the local paths where Chef data is stored
48 | chef.cookbooks_path = "cookbooks"
49 | chef.roles_path = "roles"
50 | chef.nodes_path = "nodes"
51 |
52 | # Add a recipe
53 | chef.add_recipe "apache"
54 |
55 | # Or maybe a role
56 | chef.add_role "web"
57 | end
58 | end
59 | Provisioner name: "file"
The file provisioner allows you to upload a file from the host machine to 6 | the guest machine.
7 | 8 |File provisioning is a simple way to, for example, replicate your local
9 | ~/.gitconfig to the vagrant user's home directory on the guest machine so
10 | you won't have to run git config --global every time you provision a
11 | new VM.
Vagrant.configure("2") do |config|
14 | # ... other configuration
15 |
16 | config.vm.provision "file", source: "~/.gitconfig", destination: ".gitconfig"
17 | end
18 | Note that, unlike with synced folders, files that are uploaded will not 21 | be kept in sync. Continuing with the example above, if you make further 22 | changes to your local ~/.gitconfig, they will not be immediately reflected 23 | in the copy you uploaded to the guest machine.
24 | 25 |The file provisioner takes only two options, both of which are required:
28 | 29 |source (string) - Is the local path of the file to be uploaded.
destination (string) - Is the remote path on the guest machine where
32 | the file will be uploaded to. The file is uploaded as the SSH user over
33 | SCP, so this location must be writable to that user. The SSH user can be
34 | determined by running vagrant ssh-config, and defaults to "vagrant".
Provisioners in Vagrant allow you to automatically install software, alter configurations,
4 | and more on the machine as part of the vagrant up process.
This is useful since boxes typically aren't
7 | built perfectly for your use case. Of course, if you want to just use
8 | vagrant ssh and install the software by hand, that works. But by using
9 | the provisioning systems built-in to Vagrant, it automates the process so
10 | that it is repeatable. Most importantly, it requires no human interaction,
11 | so you can vagrant destroy and vagrant up and have a fully ready-to-go
12 | work environment with a single command. Powerful.
Vagrant gives you multiple options for provisioning the machine, from 15 | simple shell scripts to more complex, industry-standard configuration 16 | management systems.
17 | 18 |If you've never used a configuration management system before, it is 19 | recommended you start with basic shell scripts 20 | for provisioning.
21 | 22 |You can find the full list of built-in provisioners and usage of these 23 | provisioners in the navigational area to the left.
24 | 25 |Provisioning happens at certain points during the lifetime of your 28 | Vagrant environment:
29 | 30 |On the first vagrant up that creates the environment, provisioning is run.
32 | If the environment was already created and the up is just resuming a machine
33 | or booting it up, they won't run unless the --provision flag is explicitly
34 | provided.
When vagrant provision is used on a running environment.
When vagrant reload --provision is called. The --provision flag must
37 | be present to force provisioning.
You can also bring up your environment and explicitly not run provisioners
41 | by specifying --no-provision.
Provisioner name: puppet_server
The Puppet agent provisioner allows you to provision the guest using
6 | Puppet, specifically by
7 | calling puppet agent, connecting to a Puppet master, and retrieving
8 | the set of modules and manifests from there.
12 | Warning: If you're not familiar with Puppet and Vagrant already, 13 | I recommend starting with the shell 14 | provisioner. However, if you're comfortable with Vagrant already, Vagrant 15 | is the best way to learn Puppet. 16 |
17 |The puppet_server provisioner takes various options. None are strictly
22 | required. They are listed below:
client_cert_path (string) - Path to the client certificate for the
26 | node on your disk. This defaults to nothing, in which case a client
27 | cert won't be uploaded.
client_private_key_path (string) - Path to the client private key for
29 | the node on your disk. This defaults to nothing, in which case a client
30 | private key won't be uploaded.
facter (hash) - Additional Facter facts to make available to the
32 | Puppet run.
options (string or array) - Additional command line options to pass
34 | to puppet agent when Puppet is ran.
puppet_node (string) - The name of the node. If this isn't set,
36 | this will attempt to use a hostname if set via config.vm.hostname.
37 | Otherwise, the box name will be used.
puppet_server (string) - Hostname of the Puppet server. By default
39 | "puppet" will be used.
The quickest way to get started with the Puppet agent provisioner is to just 45 | specify the location of the Puppet master:
46 | 47 |Vagrant.configure("2") do |config|
48 | config.vm.provision "puppet_server" do |puppet|
49 | puppet.puppet_server = "puppet.example.com"
50 | end
51 | end
52 | By default, Vagrant will look for the host named "puppet" on the 55 | local domain of the guest machine.
56 | 57 |The node name that the agent registers as can be customized. Remember 60 | this is important because Puppet uses the node name as part of the process 61 | to compile the catalog the node will run.
62 | 63 |The node name defaults to the hostname of the guest machine, but can 64 | be customized using the Vagrantfile:
65 | 66 |Vagrant.configure("2") do |config|
67 | config.vm.provision "puppet_server" do |puppet|
68 | puppet.puppet_node = "node.example.com"
69 | end
70 | end
71 | Puppet supports a lot of command-line flags. Basically any setting can 76 | be overridden on the command line. To give you the most power and flexibility 77 | possible with Puppet, Vagrant allows you to specify custom command line 78 | flags to use:
79 | 80 |Vagrant.configure("2") do |config|
81 | config.vm.provision "puppet_server" do |puppet|
82 | puppet.options = "--verbose --debug"
83 | end
84 | end
85 | Atlas is HashiCorp's commercial offering to bring your Vagrant development 6 | environments to production. You can read more about HashiCorp's Atlas and all 7 | its features on the Atlas homepage. The Vagrant Push Atlas strategy 8 | pushes your application's code to HashiCorp's Atlas service.
9 | 10 |The Vagrant Push Atlas strategy supports the following configuration options:
11 | 12 |app - The name of the application in HashiCorp's Atlas. If the
14 | application does not exist, it will be created with user confirmation.
exclude - Add a file or file pattern to exclude from the upload, relative to
16 | the dir. This value may be specified multiple times and is additive.
17 | exclude take precedence over include values.
include - Add a file or file pattern to include in the upload, relative to
19 | the dir. This value may be specified multiple times and is additive.
dir - The base directory containing the files to upload. By default this is
21 | the same directory as the Vagrantfile, but you can specify this if you have
22 | a src folder or bin folder or some other folder you want to upload.
vcs - If set to true, Vagrant will automatically use VCS data to determine
24 | the files to upload. Uncommitted changes will not be deployed.
Additionally, the following options are exposed for power users of the Vagrant 28 | Atlas push strategy. Most users will not require these options:
29 | 30 |address - The address of the Atlas server to upload to. By default this will
32 | be the public Atlas server.
token - The Atlas token to use. If the user has run vagrant login, this
34 | will the token generated by that command. If the environment variable
35 | ATLAS_TOKEN is set, the uploader will use this value. By default, this is
36 | nil.
The Vagrant Push Atlas strategy is defined in the Vagrantfile using the
42 | atlas key:
config.push.define "atlas" do |push|
45 | push.app = "username/application"
46 | end
47 | And then push the application to Atlas:
50 | 51 |$ vagrant push
52 | Vagrant Push FTP and SFTP strategy pushes the code in your Vagrant development 6 | environment to a remote FTP or SFTP server.
7 | 8 |The Vagrant Push FTP And SFTP strategy supports the following configuration 9 | options:
10 | 11 |host - The address of the remote (S)FTP server. If the (S)FTP server is
13 | running on a non-standard port, you can specify the port after the address
14 | (host:port).
username - The username to use for authentication with the (S)FTP server.
password - The password to use for authentication with the (S)FTP server.
passive - Use passive FTP (default is true).
secure - Use secure (SFTP) (default is false).
destination - The root destination on the target system to sync the files
20 | (default is /).
exclude - Add a file or file pattern to exclude from the upload, relative to
22 | the dir. This value may be specified multiple times and is additive.
23 | exclude take precedence over include values.
include - Add a file or file pattern to include in the upload, relative to
25 | the dir. This value may be specified multiple times and is additive.
dir - The base directory containing the files to upload. By default this is
27 | the same directory as the Vagrantfile, but you can specify this if you have
28 | a src folder or bin folder or some other folder you want to upload.
The Vagrant Push FTP and SFTP strategy is defined in the Vagrantfile using the
34 | ftp key:
config.push.define "ftp" do |push|
37 | push.host = "ftp.company.com"
38 | push.username = "username"
39 | push.password = "password"
40 | end
41 | And then push the application to the FTP or SFTP server:
44 | 45 |$ vagrant push
46 | Heroku is a public PAAS provider that makes it easy to deploy an 6 | application. The Vagrant Push Heroku strategy pushes your application's code to 7 | Heroku.
8 | 9 |11 | Warning: The Vagrant Push Heroku strategy requires you 12 | have configured your Heroku credentials and created the Heroku application. 13 | This documentation will not cover these prerequisites, but you can read more 14 | about them in the Heroku documentation. 15 |
16 |Only files which are committed to the Git repository will be pushed to Heroku. 19 | Additionally, the current working branch is always pushed to the Heroku, even if 20 | it is not the "master" branch.
21 | 22 |The Vagrant Push Heroku strategy supports the following configuration options:
23 | 24 |app - The name of the Heroku application. If the Heroku application does not
26 | exist, an exception will be raised. If this value is not specified, the
27 | basename of the directory containing the Vagrantfile is assumed to be the
28 | name of the Heroku application. Since this value can change between users, it
29 | is highly recommended that you add the app setting to your Vagrantfile.
dir - The base directory containing the Git repository to upload to Heroku.
31 | By default this is the same directory as the Vagrantfile, but you can specify
32 | this if you have a nested Git directory.
remote - The name of the Git remote where Heroku is configured. The default
34 | value is "heroku".
The Vagrant Push Heroku strategy is defined in the Vagrantfile using the
40 | heroku key:
config.push.define "heroku" do |push|
43 | push.app = "my_application"
44 | end
45 | And then push the application to Heroku:
48 | 49 |$ vagrant push
50 | As of version 1.7, Vagrant is capable of deploying or "pushing" application code 4 | in the same directory as your Vagrantfile to a remote such as an FTP server or 5 | HashiCorp's Atlas.
6 | 7 |Pushes are defined in an application's Vagrantfile and are invoked using the
8 | vagrant push subcommand. Much like other components of Vagrant, each Vagrant
9 | Push plugin has its own configuration options. Please consult the documentation
10 | for your Vagrant Push plugin for more information. Here is an example Vagrant
11 | Push configuration section in a Vagrantfile:
config.push.define "ftp" do |push|
14 | push.host = "ftp.company.com"
15 | push.username = "..."
16 | # ...
17 | end
18 | When the application is ready to be deployed to the FTP server, just run a 21 | single command:
22 | 23 |$ vagrant push
24 | Much like Vagrant Providers, Vagrant Push also supports multiple backend 27 | declarations. Consider the common scenario of a staging and QA environment:
28 | 29 |config.push.define "staging", strategy: "ftp" do |push|
30 | # ...
31 | end
32 |
33 | config.push.define "qa", strategy: "ftp" do |push|
34 | # ...
35 | end
36 | In this scenario, the user must pass the name of the Vagrant Push to the 39 | subcommand:
40 | 41 |$ vagrant push staging
42 | Vagrant Push is the easiest way to deploy your application. You can read more 45 | in the documentation links on the sidebar.
-------------------------------------------------------------------------------- /v2/push/local-exec.html: -------------------------------------------------------------------------------- 1 |The Vagrant Push Local Exec strategy allows the user to invoke an arbitrary 6 | shell command or script as part of a push.
7 | 8 |10 | Warning: The Vagrant Push Local Exec strategy does not 11 | perform any validation on the correctness of the shell script. 12 |
13 |The Vagrant Push Local Exec strategy supports the following configuration 16 | options:
17 | 18 |script - The path to a script on disk (relative to the Vagrantfile) to
20 | execute. Vagrant will attempt to convert this script to an executable, but an
21 | exception will be raised if that fails.inline - The inline script to execute (as a string).Please note - only one of the script and inline options may be specified in
26 | a single push definition.
The Vagrant Push Local Exec strategy is defined in the Vagrantfile using the
31 | local-exec key:
config.push.define "local-exec" do |push|
34 | push.inline = <<-SCRIPT
35 | scp . /var/www/website
36 | SCRIPT
37 | end
38 | For more complicated scripts, you may store them in a separate file and read
41 | them from the Vagrantfile like so:
config.push.define "local-exec" do |push|
44 | push.script = "my-script.sh"
45 | end
46 | And then invoke the push with Vagrant:
49 | 50 |$ vagrant push
51 | Vagrant can share any or every port to your Vagrant environment, not
4 | just SSH and HTTP. The vagrant connect command gives the connecting person
5 | a static IP they can use to communicate to the shared Vagrant environment.
6 | Any TCP traffic sent to this IP is sent to the shared Vagrant environment.
Just call vagrant share. This will automatically share as many ports as
11 | possible for remote connections. If the Vagrant environment has a static IP or DNS address, then every port
12 | will be available. Otherwise, Vagrant will only expose forwarded ports on
13 | the machine.
Note the share name at the end of calling vagrant share, and give this to
16 | the person who wants to connect to your machine. They simply have to call
17 | vagrant connect NAME. This will give them a static IP they can use to access
18 | your Vagrant environment.
vagrant connect works by doing what Vagrant does best: managing virtual
23 | machines. vagrant connect creates a tiny virtual machine that takes up
24 | only around 20 MB in RAM, using VirtualBox or VMware (more provider support
25 | is coming soon).
Any traffic sent to this tiny virtual machine is then proxied through to 28 | the shared Vagrant environment as if it were directed at it.
29 | 30 |If the Vagrant environment or box you're using is protected with the 33 | Vagrant insecure keypair (most public boxes are), then SSH will be easily 34 | available to anyone who connects.
35 | 36 |While hopefully you're sharing with someone you trust, in certain environments 37 | you might be sharing with a class, or a conference, and you don't want them 38 | to be able to SSH in.
39 | 40 |In this case, we recommend changing or removing the insecure key from 41 | the Vagrant machine.
42 | 43 |Finally, we want to note that we are working on making it so that when 44 | Vagrant share is used, the Vagrant private key is actively rejected unless 45 | explicitly allowed. This feature is not yet done, however.
-------------------------------------------------------------------------------- /v2/share/http.html: -------------------------------------------------------------------------------- 1 |Vagrant Share can create a publicly accessible URL endpoint to access an
4 | HTTP server running in your Vagrant environment. This is known as "HTTP
5 | sharing," and is enabled by default when vagrant share is used.
Because this mode of sharing creates a publicly accessible URL, the accessing 8 | party does not need to have Vagrant installed in order to view your environment.
9 | 10 |This has a number of useful use cases: you can test webhooks by exposing 11 | your Vagrant environment to the internet, you can show your work to clients, 12 | teammates, or managers, etc.
13 | 14 |To use HTTP sharing, simply run vagrant share:
$ vagrant share
19 | ==> default: Detecting network information for machine...
20 | default: Local machine address: 192.168.163.152
21 | default: Local HTTP port: 4567
22 | default: Local HTTPS port: disabled
23 | ==> default: Checking authentication and authorization...
24 | ==> default: Creating Vagrant Share session...
25 | default: Share will be at: ghastly-wombat-4051
26 | ==> default: Your Vagrant Share is running!
27 | default: Name: ghastly-wombat-4051
28 | ==> default: URL: http://ghastly-wombat-4051.vagrantshare.com
29 | Vagrant detects where your HTTP server is running in your Vagrant environment 32 | and outputs the endpoint that can be used to access this share. Just give 33 | this URL to anyone you want to share it with, and they'll be able to access 34 | your Vagrant environment!
35 | 36 |If Vagrant has trouble detecting the port of your servers in your environment,
37 | use the --http and/or --https flags to be more explicit.
The share will be accessible for the duration that vagrant share is running.
40 | Press Ctrl-C to quit the sharing session.
If you want to disable the creation of the publicly accessible endpoint,
50 | run vagrant share with the --disable-http flag. This will share your
51 | environment using one of the other methods available, and will not create
52 | the URL endpoint.
Shared web applications must use relative paths for loading any 57 | local assets such as images, stylesheets, javascript.
58 | 59 |The web application under development will be accessed remotely. This means
60 | that if you have any hardcoded asset (images, stylesheets, etc.) URLs
61 | such as <img src="http://127.0.0.1/header.png">, then they won't load
62 | for people accessing your share.
Most web frameworks or toolkits have settings or helpers to generate 65 | relative paths. For example, if you're a WordPress developer, the 66 | Root Relative URLs plugin 67 | will automatically do this for you.
68 | 69 |Relative URLs to assets is generally a best practice in general, so you 70 | should do this anyways!
71 | 72 |Vagrant Share can also expose an SSL port that can be accessed over
75 | SSL. For example, instead of accessing http://foo.vagrantshare.com, it
76 | could be accessed at https://foo.vagrantshare.com.
vagrant share by default looks for any SSL traffic on port 443 in your
79 | development environment. If it can't find any, then SSL is disabled by
80 | default.
You can force SSL by setting the --https flag to point to the accessible
83 | SSL port.
Vagrant Share allows you to share your Vagrant environment with anyone in
4 | the world, enabling collaboration directly in your Vagrant environment
5 | in almost any network environment with just a single command:
6 | vagrant share.
Vagrant share has three primary modes or features. These features aren't 9 | mutually exclusive, meaning that any combination of them can be active 10 | at any given time:
11 | 12 |HTTP sharing will create a URL that you can give to anyone. This 14 | URL will route directly into your Vagrant environment. The person using 15 | this URL does not need Vagrant installed, so it can be shared with anyone. 16 | This is useful for testing webhooks or showing your work to clients, 17 | teammates, managers, etc.
SSH sharing will allow instant SSH access to your Vagrant environment
19 | by anyone by running vagrant connect --ssh on the remote side. This
20 | is useful for pair programming, debugging ops problems, etc.
General sharing allows anyone to access any exposed port of your
22 | Vagrant environment by running vagrant connect on the remote side.
23 | This is useful if the remote side wants to access your Vagrant
24 | environment as if it were a computer on the LAN.
The details of each are covered in their specific section in the sidebar 28 | to the left. We also have a section where we go into detail about the 29 | security implications of this feature.
30 | 31 |Vagrant Share requires an account with 32 | HashiCorp's Atlas to be used.
-------------------------------------------------------------------------------- /v2/share/provider.html: -------------------------------------------------------------------------------- 1 |5 | Warning: Advanced Topic! This topic is related to 6 | developing Vagrant plugins. If you're not interested in this or 7 | you're just starting with Vagrant, it is safe to skip this page. 8 |
9 |If you're developing a custom provider, you'll 12 | need to do a tiny bit more work in order for it to work well with Vagrant 13 | Share.
14 | 15 |For now, this is only one step:
16 | 17 |public_address provider capability - You must implement this capability
19 | to return a string that is an address that can be used to access the
20 | guest from Vagrant. This does not need to be a globally routable address,
21 | it only needs to be accessible from the machine running Vagrant. If you
22 | can't detect an address, return nil.Sharing your Vagrant environment understandably raises a number of security 4 | concerns.
5 | 6 |The primary security mechanism for Vagrant 7 | Share is security through obscurity along with an encryption key for SSH. 8 | Additionally, there are several configuration options made available to 9 | help control access and manage security:
10 | 11 |--disable-http will not create a publicly accessible HTTP URL. When
13 | this is set, the only way to access the share is with vagrant connect.
--ssh-once will allow only one person to SSH into your shared environment.
15 | After the first SSH access, the keypair is physically deleted and SSH
16 | access won't be possible anymore.
In addition to these options, there are other features we've built to help:
20 | 21 |Vagrant share uses end-to-end TLS connections. So even unencrypted TCP streams 23 | are encrypted through the various proxies and only unencrypted during the final 24 | local communication between the local proxy and the Vagrant environment.
Share names, such as happy-panda-1234, are randomly chosen from a pool 26 | of over 40,000,000 possible names. And we're routinely adding more 27 | words to grow this pool. It is unlikely that anyone will guess your 28 | share name.
SSH keys are encrypted by default, using a password that is not transmitted 30 | to our servers or across the network at all.
SSH is not shared by default, it must explicitly be shared with the
32 | --ssh flag.
A web interface we've built shows share history and will show basic 34 | access logs in the future.
Share sessions expire after a short time (currently 1 hour), but
36 | can also be expired manually by ctrl-c from the sharing machine
37 | or via the web interface.
Most importantly, you must understand that by running vagrant share,
41 | you are making your Vagrant environment accessible by anyone who knows
42 | the share name. When share is not running, it is not accessible.
Later, we will be expanding the security of this feature by adding ACLs, 45 | so you're able to explicitly allow 46 | access to your share based on who is connecting.
47 | 48 |For maximum security, we will also allow you to run your own Vagrant 49 | Share server. This option isn't available yet.
-------------------------------------------------------------------------------- /v2/share/ssh.html: -------------------------------------------------------------------------------- 1 |Vagrant share makes it trivially easy to allow remote SSH access to your
4 | Vagrant environment by supplying the --ssh flag to vagrant share.
Easy SSH sharing is incredibly useful if you want to give access to 7 | a colleague for troubleshooting ops issues. Additionally, it enables 8 | pair programming with a Vagrant environment, if you want!
9 | 10 |SSH sharing is disabled by default as a security measure. To enable
11 | SSH sharing, simply supply the --ssh flag when calling vagrant share.
Just run vagrant share --ssh!
When SSH sharing is enabled, Vagrant generates a brand new keypair for 18 | SSH access. The public key portion is automatically inserted 19 | into the Vagrant machine, and the private key portion is uploaded to the 20 | server managing the Vagrant shares. This private key is encrypted using 21 | a password that you will be prompted for. This password is never transmitted 22 | across the network by Vagrant, and is an extra layer of security preventing 23 | us or anyone who may know your share name from easily accessing your machine.
24 | 25 |After running vagrant share --ssh, it will output the name of your share:
$ vagrant share --ssh
28 | ==> default: Detecting network information for machine...
29 | default: Local machine address: 192.168.163.152
30 | default: Local HTTP port: 4567
31 | default: Local HTTPS port: disabled
32 | default: SSH Port: 22
33 | ==> default: Generating new SSH key...
34 | default: Please enter a password to encrypt the key:
35 | default: Repeat the password to confirm:
36 | default: Inserting generated SSH key into machine...
37 | ==> default: Checking authentication and authorization...
38 | ==> default: Creating Vagrant Share session...
39 | default: Share will be at: itty-bitty-polar-8667
40 | ==> default: Your Vagrant Share is running!
41 | default: Name: itty-bitty-polar-8667
42 | ...
43 | Anyone can then SSH directly to your Vagrant environment by running
46 | vagrant connect --ssh NAME where NAME is the name of the share outputted
47 | previously.
$ vagrant connect --ssh itty-bitty-polar-8667
50 | Loading share 'itty-bitty-polar-8667'...
51 | The SSH key to connect to this share is encrypted. You will
52 | require the password entered when creating to share to
53 | decrypt it. Verify you access to this password before
54 | continuing.
55 |
56 | Press enter to continue, or Ctrl-C to exit now.
57 | Password for the private key:
58 | Executing SSH...
59 | Welcome to Ubuntu 12.04.3 LTS (GNU/Linux 3.8.0-29-generic x86_64)
60 |
61 | * Documentation: https://help.ubuntu.com/
62 | Last login: Fri Mar 7 17:44:50 2014 from 192.168.163.1
63 | vagrant@vagrant:~$
64 | If the private key is encrypted (the default behavior), then the connecting 67 | person will be prompted for the password to decrypt the private key.
68 | 69 |Additional flags are available such as --ssh-once to add another layer
70 | of security to your SSH shared session. With this flag active, only one
71 | vagrant connect --ssh can be attempted before the keypair is destroyed,
72 | preventing any future connections.
Synced folders are configured within your Vagrantfile using the
6 | config.vm.synced_folder method. Usage of the configuration directive
7 | is very simple:
Vagrant.configure("2") do |config|
10 | # other config here
11 |
12 | config.vm.synced_folder "src/", "/srv/website"
13 | end
14 | The first parameter is a path to a directory on the host machine. If 17 | the path is relative, it is relative to the project root. The second 18 | parameter must be an absolute path of where to share the folder within 19 | the guest machine. This folder will be created (recursively, if it must) 20 | if it doesn't exist.
21 | 22 |You may also specify additional optional parameters when configuring 25 | synced folders. These options are listed below. More detailed examples of using 26 | some of these options are shown below this section, note the owner/group example 27 | supplies two additional options separated by commas.
28 | 29 |In addition to these options, the specific synced folder type might 30 | allow more options. See the documentation for your specific synced folder 31 | type for more details. The built-in synced folder types are documented 32 | in other pages available in the navigation for these docs.
33 | 34 |create (boolean) - If true, the host path will be created if it
36 | does not exist. Defaults to false.
disabled (boolean) - If true, this synced folder will be disabled and
38 | won't be setup. This can be used to disable a previously defined synced
39 | folder or to conditionally disable a definition based on some external
40 | factor.
group (string) - The group that will own the synced folder. By default
42 | this will be the SSH user. Some synced folder types don't support
43 | modifying the group.
mount_options (array) - A list of additional mount options to pass
45 | to the mount command.
owner (string) - The user who should be the owner of this synced folder.
47 | By default this will be the SSH user. Some synced folder types don't
48 | support modifying the owner.
type (string) - The type of synced folder. If this is not specified,
50 | Vagrant will automatically choose the best synced folder option for your
51 | environment. Otherwise, you can specify a specific type such as "nfs".
Synced folders are automatically setup during vagrant up and
57 | vagrant reload.
Synced folders can be disabled by adding the disabled option to
62 | any definition:
Vagrant.configure("2") do |config|
65 | config.vm.synced_folder "src/", "/srv/website", disabled: true
66 | end
67 | Disabling the default /vagrant share can be done as follows:
config.vm.synced_folder ".", "/vagrant", disabled: true
72 | By default, Vagrant mounts the synced folders with the owner/group set 77 | to the SSH user. Sometimes it is preferable to mount folders with a different 78 | owner and group. It is possible to set these options:
79 | 80 |config.vm.synced_folder "src/", "/srv/website",
81 | owner: "root", group: "root"
82 | Synced folders enable Vagrant to sync a folder on the host machine to the 4 | guest machine, allowing you to continue working on your project's files 5 | on your host machine, but use the resources in the guest machine to 6 | compile or run your project.
7 | 8 |By default, Vagrant will share your project directory (the directory
9 | with the Vagrantfile) to /vagrant.
Read the basic usage page to get started 12 | with synced folders.
-------------------------------------------------------------------------------- /v2/synced-folders/rsync.html: -------------------------------------------------------------------------------- 1 |Synced folder type: rsync
Vagrant can use rsync as a mechanism 6 | to sync a folder to the guest machine. This synced folder type is useful 7 | primarily in situations where other synced folder mechanisms are not available, 8 | such as when NFS or VirtualBox shared folders aren't available in the guest 9 | machine.
10 | 11 |The rsync synced folder does a one-time one-way sync from the machine running 12 | to the machine being started by Vagrant.
13 | 14 |The rsync and rsync-auto
15 | commands can be used to force a resync and to automatically resync when
16 | changes occur in the filesystem. Without running these commands, Vagrant
17 | only syncs the folders on vagrant up or vagrant reload.
To use the rsync synced folder type, the machine running Vagrant must have
22 | rsync (or rsync.exe) on the path. This executable is expected to behave
23 | like the standard rsync tool.
On Windows, rsync installed with Cygwin or MinGW will be detected by 26 | Vagrant and works well.
27 | 28 |The destination machine must also have rsync installed, but Vagrant 29 | can automatically install rsync into many operating systems. If Vagrant 30 | is unable to automatically install rsync for your operating system, 31 | it will tell you.
32 | 33 |The destination folder will be created as the user initiating the connection,
34 | this is vagrant by default. This user requires the appropiate permissions on
35 | the destination folder.
The rsync synced folder type accepts the following options:
40 | 41 |rsync__args (array of strings) - A list of arguments to supply
43 | to rsync. By default this is ["--verbose", "--archive", "--delete", "-z", "--copy-links"].
rsync__auto (boolean) - If false, then rsync-auto will not
45 | watch and automatically sync this folder. By default, this is true.
rsync__chown (boolean) - If false, then the
47 | owner and group
48 | options for the synced folder are ignored and Vagrant won't execute
49 | a recursive chown. This defaults to true. This option exists because
50 | the chown causes issues for some development environments. Note that
51 | any rsync__args options for ownership will be overridden by
52 | rsync__chown.
rsync__exclude (string or array of strings) - A list of files or directories
54 | to exclude from the sync. The values can be any acceptable rsync exclude
55 | pattern. By default, the ".vagrant/" directory is excluded. We recommend
56 | excluding revision control directories such as ".git/" as well.
The following is an example of using RSync to sync a folder:
62 | 63 |
64 | Vagrant.configure("2") do |config|
65 | config.vm.synced_folder ".", "/vagrant", type: "rsync",
66 | rsync__exclude: ".git/"
67 | end
68 |
69 |
70 | If required to copy to a destination where vagrant user doesn't have
73 | permissions, use "--rsync-path='sudo rsync'" to run rsync with sudo on the guest
76 | Vagrant.configure("2") do |config|
77 | config.vm.synced_folder "bin", "/usr/local/bin", type: "rsync",
78 | rsync__exclude: ".git/",
79 | rsync__args: ["--verbose", "--rsync-path='sudo rsync'", "--archive", "--delete", "-z"]
80 | end
81 |
--------------------------------------------------------------------------------
/v2/synced-folders/smb.html:
--------------------------------------------------------------------------------
1 | Synced folder type: smb
Vagrant can use SMB 6 | as a mechanism to create a bi-directional synced folder between the host 7 | machine and the Vagrant machine.
8 | 9 |SMB is built-in to Windows machines and provides a higher performance 10 | alternative to some other mechanisms such as VirtualBox shared folders.
11 | 12 |14 | Windows only! SMB is currently only supported 15 | when the host machine is Windows. The guest machine can be Windows 16 | or Linux. 17 |
18 |To use the SMB synced folder type, the machine running Vagrant must be 23 | a Windows machine. In addition to this, the command prompt executing Vagrant 24 | must have administrative privileges. Vagrant requires these privileges in 25 | order to create new network folder shares.
26 | 27 |The destination machine must be able to mount SMB filesystems. On Linux
28 | the package to do this is usually called smbfs or cifs. Vagrant knows
29 | how to automatically install this for some operating systems.
The SMB synced folder type has a variety of options it accepts:
34 | 35 |smb_host (string) - The host IP where the SMB mount is located. If this
37 | isn't specified, Vagrant will attempt to determine this automatically.
smb_password (string) - The password used for authentication to mount
39 | the SMB mount. This is the password for the username specified by
40 | smb_username. If this is not specified, Vagrant will prompt you for it.
41 | It is highly recommended that you do not set this, since it would expose
42 | your password directly in your Vagrantfile.
smb_username (string) - The username used for authentication to mount
44 | the SMB mount. This is the username to access the mount, not the username
45 | of the account where the folder is being mounted to. This is usually your
46 | Windows username. If this isn't specified, Vagrant will prompt you for
47 | it.
The following is an example of using SMB to sync a folder:
53 | 54 |
55 | Vagrant.configure("2") do |config|
56 | config.vm.synced_folder ".", "/vagrant", type: "smb"
57 | end
58 |
59 |
60 | Because SMB is a relatively new synced folder type in Vagrant, it still 63 | has some rough edges. Hopefully, future versions of Vagrant will address 64 | these.
65 | 66 |The primary limitation of SMB synced folders at the moment is that they are
67 | never pruned or cleaned up. Once the folder share is defined, Vagrant never
68 | removes it. To clean up SMB synced folder shares, periodically run
69 | net share in a command prompt, find the shares you don't want, then
70 | run net share NAME /delete for each, where NAME is the name of the share.
If you're using the VirtualBox provider, then 4 | VirtualBox shared folders are the default synced folder type. These synced 5 | folders use the VirtualBox shared folder system to sync file changes from 6 | the guest to the host and vice versa.
7 | 8 |There is a VirtualBox bug related to sendfile which can result
11 | in corrupted or non-updating files. You should deactivate sendfile in any
12 | web servers you may be running.
In Nginx:
15 | 16 |sendfile off;
17 | In Apache:
20 | 21 |EnableSendfile Off
22 | The primary function of the Vagrantfile is to describe the type
4 | of machine required for a project, and how to configure and
5 | provision these machines. Vagrantfiles are called Vagrantfiles because
6 | the actual literal filename for the file is Vagrantfile (casing doesn't
7 | matter unless your file system is running in a strict case sensitive mode).
Vagrant is meant to run with one Vagrantfile per project, and the Vagrantfile
10 | is supposed to be committed to version control. This allows other developers
11 | involved in the project to check out the code, run vagrant up, and be on
12 | their way. Vagrantfiles are portable across every platform Vagrant supports.
The syntax of Vagrantfiles is Ruby, but knowledge 15 | of the Ruby programming language is not necessary to make modifications to the 16 | Vagrantfile, since it is mostly simple variable assignment. In fact, Ruby isn't 17 | even the most popular community Vagrant is used within, which should help show 18 | you that despite not having Ruby knowledge, people are very successful with 19 | Vagrant.
20 | 21 |When you run any vagrant command, Vagrant climbs up the directory tree
24 | looking for the first Vagrantfile it can find, starting first in the
25 | current directory. So if you run vagrant in /home/mitchellh/projects/foo,
26 | it will search the following paths in order for a Vagrantfile, until it
27 | finds one:
/home/mitchellh/projects/foo/Vagrantfile
30 | /home/mitchellh/projects/Vagrantfile
31 | /home/mitchellh/Vagrantfile
32 | /home/Vagrantfile
33 | /Vagrantfile
34 | This feature lets you run vagrant from any directory in your project.
You can change the starting directory where Vagrant looks for a Vagrantfile
39 | by setting the VAGRANT_CWD environmental variable to some other path.
An important concept to understand is how Vagrant loads Vagrantfiles. Vagrant 46 | actually loads a series of Vagrantfiles, merging the settings as it goes. This 47 | allows Vagrantfiles of varying level of specificity to override prior settings. 48 | Vagrantfiles are loaded in the order shown below. Note that if a Vagrantfile 49 | is not found at any step, Vagrant continues with the next step.
50 | 51 |~/.vagrant.d).
55 | This lets you specify some defaults for your system user.At each level, settings set will be merged with previous values. What this 64 | exactly means depends on the setting. For most settings, this means that 65 | the newer setting overrides the older one. However, for things such as defining 66 | networks, the networks are actually appended to each other. By default, you 67 | should assume that settings will override each other. If the behavior is 68 | different, it will be noted in the relevant documentation section.
69 | 70 |Within each Vagrantfile, you may specify multiple Vagrant.configure blocks.
71 | All configurations will be merged within a single Vagrantfile in the order
72 | they're defined.
You can learn more about the available configuration options by clicking 77 | the relevant section in the left navigational area.
-------------------------------------------------------------------------------- /v2/vagrantfile/ssh_settings.html: -------------------------------------------------------------------------------- 1 |Config namespace: config.ssh
The settings within config.ssh relate to configuring how Vagrant
6 | will access your machine over SSH. As with most Vagrant settings, the
7 | defaults are typically fine, but you can fine tune whatever you'd like.
config.ssh.username - This sets the username that Vagrant will SSH
12 | as by default. Providers are free to override this if they detect a more
13 | appropriate user. By default this is "vagrant," since that is what most
14 | public boxes are made as.
config.ssh.password - This sets a password that Vagrant will use to
19 | authenticate the SSH user. Note that Vagrant recommends you use key-based
20 | authentiation rather than a password (see private_key_path) below. If
21 | you use a password, Vagrant will automatically insert a keypair if
22 | insert_key is true.
config.ssh.host - The hostname or IP to SSH into. By default this is
27 | empty, because the provider usually figures this out for you.
config.ssh.port - The port to SSH into. By default this is port 22.
config.ssh.guest_port - The port on the guest that SSH is running on. This
36 | is used by some providers to detect forwarded ports for SSH. For example, if
37 | this is set to 22 (the default), and Vagrant detects a forwarded port to
38 | port 22 on the guest from port 4567 on the host, Vagrant will attempt
39 | to use port 4567 to talk to the guest if there is no other option.
config.ssh.private_key_path - The path to the private key to use to
44 | SSH into the guest machine. By default this is the insecure private key
45 | that ships with Vagrant, since that is what public boxes use. If you make
46 | your own custom box with a custom SSH key, this should point to that
47 | private key.
You can also specify multiple private keys by setting this to be an array. 50 | This is useful, for example, if you use the default private key to bootstrap 51 | the machine, but replace it with perhaps a more secure key later.
52 | 53 |config.ssh.forward_agent - If true, agent forwarding over SSH
56 | connections is enabled. Defaults to false.
config.ssh.forward_x11 - If true, X11 forwarding over SSH connections
61 | is enabled. Defaults to false.
config.ssh.insert_key - If true, Vagrant will automatically insert
66 | an insecure keypair to use for SSH. By default, this is true. This only
67 | has an effect if you don't already use private keys for authentication.
config.ssh.proxy_command - A command-line command to execute that receives
72 | the data to send to SSH on stdin. This can be used to proxy the SSH connection.
73 | %h in the command is replaced with the host and %p is replaced with
74 | the port.
config.ssh.pty - If true, pty will be used for provisioning. Defaults to false.
This setting is an advanced feature that should not be enabled unless 81 | absolutely necessary. It breaks some other features of Vagrant, and is 82 | really only exposed for cases where it is absolutely necessary. If you can find 83 | a way to not use a pty, that is recommended instead.
84 | 85 |config.ssh.shell - The shell to use when executing SSH commands from
88 | Vagrant. By default this is bash -l. Note that this has no effect on
89 | the shell you get when you run vagrant ssh. This configuration option
90 | only affects the shell to use when executing commands internally in Vagrant.
The Vagrantfile is a very flexible configuration format. Since it is just 4 | Ruby, there is a lot you can do with it. However, in that same vein, since 5 | it is Ruby, there are a lot of ways you can shoot yourself in the foot. When 6 | using some of the tips and tricks on this page, please take care to use them 7 | correctly.
8 | 9 |If you want to apply a slightly different configuration to many 12 | multi-machine machines, you can use a loop to do this. For example, if 13 | you wanted to create three machines:
14 | 15 |
16 | (1..3).each do |i|
17 | config.vm.define "node-#{i}" do |node|
18 | node.vm.provision "shell",
19 | inline: "echo hello from node #{i}"
20 | end
21 | end
22 |
23 |
24 | Warning: The inner portion of multi-machine definitions 25 | and provider overrides are lazy-loaded. This can cause issues if you change 26 | the value of a variable used within the configs. For example, the loop below 27 | does not work:
28 | 29 |
30 | # THIS DOES NOT WORK!
31 | for i in 1..3 do
32 | config.vm.define "node-#{i}" do |node|
33 | node.vm.provision "shell",
34 | inline: "echo hello from node #{i}"
35 | end
36 | end
37 |
38 |
39 | The "for i in ..." construct in Ruby actually modifies the value of i
40 | for each iteration, rather than making a copy. Therefore, when you run this,
41 | every node will actually provision with the same text.
This is an easy mistake to make, and Vagrant can't really protect against it, 44 | so the best we can do is mention it here.
-------------------------------------------------------------------------------- /v2/vagrantfile/vagrant_settings.html: -------------------------------------------------------------------------------- 1 |Config namespace: config.vagrant
The settings within config.vagrant modify the behavior of Vagrant
6 | itself.
config.vagrant.host - This sets the type of host machine that is running
11 | Vagrant. By default this is :detect, which causes Vagrant to auto-detect
12 | the host. Vagrant needs to know this information in order to perform some
13 | host-specific things, such as preparing NFS folders if they're enabled.
14 | You should only manually set this if auto-detection fails.
A set of Vagrant version requirements can be specified in the Vagrantfile 4 | to enforce that people use a specific version of Vagrant with a Vagrantfile. 5 | This can help with compatibility issues that may otherwise arise from using 6 | a too old or too new Vagrant version with a Vagrantfile.
7 | 8 |Vagrant version requirements should be specified at the top of a Vagrantfile
9 | with the Vagrant.require_version helper:
Vagrant.require_version ">= 1.3.5"
12 | In the case above, the Vagrantfile will only load if the version loading it 15 | is Vagrant 1.3.5 or greater.
16 | 17 |Multiple requirements can be specified as well:
18 | 19 |Vagrant.require_version ">= 1.3.5", "< 1.4.0"
20 | Configuration versions are the mechanism by which Vagrant 1.1+ is able 4 | to remain backwards compatible 5 | with Vagrant 1.0.x Vagrantfiles, while introducing dramatically new features 6 | and configuration options.
7 | 8 |If you run vagrant init today, the Vagrantfile will be in roughly the
9 | following format:
Vagrant.configure(2) do |config|
12 | # ...
13 | end
14 | The "2" in the first line above represents the version of the configuration
17 | object config that will be used for configuration for that block (the
18 | section between the do and the end). This object can be very
19 | different from version to version.
Currently, there are only two supported versions: "1" and "2". Version 1 22 | represents the configuration from Vagrant 1.0.x. "2" represents the configuration 23 | for 1.1+ leading up to 2.0.x.
24 | 25 |When loading Vagrantfiles, Vagrant uses the proper configuration object 26 | for each version, and properly merges them, just like any other configuration.
27 | 28 |The important thing to understand as a general user of Vagrant is that
29 | within a single configuration section, only a single version can be used.
30 | You can't use the new config.vm.provider configurations in a version 1
31 | configuration section. Likewise, config.vm.forward_port won't work
32 | in a version 2 configuration section (it was renamed).
If you want, you can mix and match multiple configuration versions in the 35 | same Vagrantfile. This is useful if you found some useful configuration 36 | snippet or something that you want to use. Example:
37 | 38 |Vagrant.configure("1") do |config|
39 | # v1 configs...
40 | end
41 |
42 | Vagrant.configure("2") do |config|
43 | # v2 configs...
44 | end
45 |
49 | What is Vagrant::Config.run?
50 | You may see this in Vagrantfiles. This was actually how Vagrant 1.0.x
51 | did configuration. In Vagrant 1.1+, this is synonymous with
52 | Vagrant.configure("1").
53 |
Config namespace: config.winrm
The settings within config.winrm relate to configuring how Vagrant
6 | will access your Windows guest over WinRM. As with most Vagrant settings, the
7 | defaults are typically fine, but you can fine tune whatever you'd like.
These settings are only used if you've set your communicator type to :winrm.
config.winrm.username - This sets the username that Vagrant will use
14 | to login to the WinRM web service by default. Providers are free to override
15 | this if they detect a more appropriate user. By default this is "vagrant,"
16 | since that is what most public boxes are made as.
config.winrm.password - This sets a password that Vagrant will use to
21 | authenticate the WinRM user. By default this is "vagrant," since that is
22 | what most public boxes are made as.
config.winrm.host - The hostname or IP to connect to the WinRM service.
27 | By default this is empty, because the provider usually figures this out for
28 | you.
config.winrm.port - The WinRM port to connect to, by default 5985.
config.winrm.guest_port - The port on the guest that WinRM is running on.
37 | This is used by some providers to detect forwarded ports for WinRM. For
38 | example, if this is set to 5985 (the default), and Vagrant detects a forwarded
39 | port to port 5985 on the guest from port 4567 on the host, Vagrant will attempt
40 | to use port 4567 to talk to the guest if there is no other option.
Warning: In order for Vagrant to communicate with a Windows
45 | guest, you must allow unencrypted WinRM connections on the guest machine
46 | itself. Some public boxes already have this configured, but if you are
47 | attempting to vagrant up a Windows box and the command hangs at
48 | Waiting for WinRM to become available..., then you will need to run the
49 | commands below on the guest machine itself, at the box setup stage,
50 | after provisioning, or through a start up script.
53 | Set-Item WSMan:\localhost\Service\AllowUnencrypted -Value True 54 | Set-Item WSMan:\localhost\Service\Auth\Basic -Value True 55 |-------------------------------------------------------------------------------- /v2/why-vagrant/index.html: -------------------------------------------------------------------------------- 1 |
4 | Vagrant 提供了易于配置、便于重现、且便携的工作环境，它基于行业技术标准，通过一个统一的流程控制来最大限度地提高 5 | 团队的灵活性及生产力。 6 |
7 | 8 |9 | 为了实现其功能，Vagrant 站在了巨人的肩膀上，基于VirtualBox, VMware, AWS, 或 10 | 其他 虚拟机管理软件(provider) 11 | 的接口来创建虚拟机。 12 | 因此，标准的 配置管理工具（provisioning tools 13 | （例如 shell 脚本, Chef, 或 Puppet）都可以在 Vagrant 创建的虚拟机上使用，用来进行自动安装及配置管理。 14 |
15 | 16 |
19 | 如果你是一位 开发者 , Vagrant 可以为你创建一个将所有依赖及配置隔离、便携统一的虚拟开发环境，因此你可以继续使用已经习惯了的开发工具（比如 编辑器、浏览器、调试器等）进行工作，编写的代码则运行在 Vagrant 创建的统一虚拟开发环境下。 当你或其他人创建了一个 Vagrantfile 配置文件 后, 只需要输入
20 | vagrant up
21 | 命令便可自动安装及配置，你便可以进行开发工作了。团队其他成员使用相同的 Vagrantfile 配置文件创建自己的开发环境后，则所有成员都具有相同的代码运行环境，所以无论你工作在 Linux、Mac OS X 还是 Windows 下，你团队所有成员的代码都运行在拥有相同依赖及配置的统一虚拟环境里。跟 “在我的机器上运行没事” 说再见吧，再也不会出现因环境不同而出现 bug 的情况了。
22 |
25 | 如果你是一位 运维工程师 26 | , Vagrant 为你提供了一个便携环境和统一的流程，来对运维脚本进行开发及测试。 你可以快速地测试 shell 脚本、 Chef cookbooks、 27 | Puppet 模块, 以及使用本地虚拟化，例如 VirtualBox 或 VMware。此外, 你还可以在远程的云端，例如 AWS 或 RackSpace 上使用 相同的配置和相同的流程。例如，使用你的自定义脚本来回收 EC2 实例, stop juggling SSH prompts to various machines, 使用 Vagrant 将使你的人生更加智能。 28 |
29 | 30 |
31 | 如果你是
32 | 设计师
33 | , Vagrant 将自动设置好一切 Web App 开发所需环境，可以使你只专注于你擅长的设计工作。 当开发者配置好了 Vagrant, 你无需担心如何使你的 App 能够在新的环境中运行起来，也不用再麻烦开发人员为你配置开发环境， 你只需要输入命令
34 | ,
35 | vagrant up
36 | , 便可开始设计工作.
37 |