haskal
/
vagrant
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #10341 from chrisroberts/e-docs-update 

Update vagrantfile documentation content to use list
This commit is contained in:
Chris Roberts 2018-10-29 08:29:44 -07:00 committed by GitHub
parent 7a725d7424 32dbb6185a
commit df874adf69
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 166 additions and 351 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
website/source/docs/vagrantfile/machine_settings.html.md
View File

@ -16,145 +16,106 @@ machine that Vagrant manages.
## Available Settings
`config.vm.boot_timeout` - The time in seconds that Vagrant will wait
* `config.vm.base_mac` (string) - The MAC address to be assigned to the default
NAT interface on the guest. _Support for this option is provider dependent._
* `config.vm.base_address` (string) - The IP address to be assigned to the default
NAT interface on the guest. _Support for this option is provider dependent._
* `config.vm.boot_timeout` (integer) - The time in seconds that Vagrant will wait
for the machine to boot and be accessible. By default this is 300 seconds.
<hr>
`config.vm.box` - This configures what [box](/docs/boxes.html) the
* `config.vm.box` (string) - This configures what [box](/docs/boxes.html) the
machine will be brought up against. The value here should be the name
of an installed box or a shorthand name of a box in
[HashiCorp's Vagrant Cloud](/docs/vagrant-cloud).
This option requires Vagrant 1.5 or higher. You can download the latest version
of Vagrant from the [Vagrant installers page](/downloads.html).
<hr>
`config.vm.box_check_update` - If true, Vagrant will check for updates to
* `config.vm.box_check_update` (boolean) - If true, Vagrant will check for updates to
the configured box on every `vagrant up`. If an update is found, Vagrant
will tell the user. By default this is true. Updates will only be checked
for boxes that properly support updates (boxes from
[HashiCorp's Vagrant Cloud](/docs/vagrant-cloud)
or some other versioned box).
<hr>
`config.vm.box_download_checksum` - The checksum of the box specified by
* `config.vm.box_download_checksum` (string) - The checksum of the box specified by
`config.vm.box_url`. If not specified, no checksum comparison will be done.
If specified, Vagrant will compare the checksum of the downloaded box to
this value and error if they do not match. Checksum checking is only done
when Vagrant must download the box.
when Vagrant must download the box. If this is specified, then
`config.vm.box_download_checksum_type` must also be specified.
If this is specified, then `config.vm.box_download_checksum_type` must
also be specified.
<hr>
`config.vm.box_download_checksum_type` - The type of checksum specified
* `config.vm.box_download_checksum_type` (string) - The type of checksum specified
by `config.vm.box_download_checksum` (if any). Supported values are
currently "md5", "sha1", and "sha256".
<hr>
`config.vm.box_download_client_cert` - Path to a client certificate to
* `config.vm.box_download_client_cert` (string) - Path to a client certificate to
use when downloading the box, if it is necessary. By default, no client
certificate is used to download the box.
<hr>
`config.vm.box_download_ca_cert` - Path to a CA cert bundle to use when
* `config.vm.box_download_ca_cert` (string) - Path to a CA cert bundle to use when
downloading a box directly. By default, Vagrant will use the Mozilla CA cert
bundle.
<hr>
`config.vm.box_download_ca_path` - Path to a directory containing
* `config.vm.box_download_ca_path` (string) - Path to a directory containing
CA certificates for downloading a box directly. By default, Vagrant will
use the Mozilla CA cert bundle.
<hr>
`config.vm.box_download_insecure` - If true, then SSL certificates
* `config.vm.box_download_insecure` (boolean) - If true, then SSL certificates
from the server will not be verified. By default, if the URL is an HTTPS
URL, then SSL certs will be verified.
<hr>
`config.vm.box_download_location_trusted` - If true, then all HTTP redirects will be
* `config.vm.box_download_location_trusted` (boolean) - If true, then all HTTP redirects will be
treated as trusted. That means credentials used for initial URL will be used for
all subsequent redirects. By default, redirect locations are untrusted so credentials
(if specified) used only for initial HTTP request.
<hr>
`config.vm.box_url` - The URL that the configured box can be found at.
* `config.vm.box_url` (string, array of strings) - The URL that the configured box can be found at.
If `config.vm.box` is a shorthand to a box in [HashiCorp's Vagrant Cloud](/docs/vagrant-cloud)
then this value does not need to be specified. Otherwise, it should
point to the proper place where the box can be found if it is not
installed.
installed. This can also be an array of multiple URLs. The URLs will be tried in
order.
This can also be an array of multiple URLs. The URLs will be tried in
order. Note that any client certificates, insecure download settings, and
so on will apply to all URLs in this list.
Note that any client certificates, insecure download settings, and
so on will apply to all URLs in this list. The URLs can also be local files
by using the `file://` scheme. For example: "file:///tmp/test.box".
The URLs can also be local files by using the `file://` scheme. For
example: "file:///tmp/test.box".
<hr>
`config.vm.box_version` - The version of the box to use. This defaults to
* `config.vm.box_version` (string) - The version of the box to use. This defaults to
">= 0" (the latest version available). This can contain an arbitrary list
of constraints, separated by commas, such as: `>= 1.0, < 1.5`. When constraints
are given, Vagrant will use the latest available box satisfying these
constraints.
<hr>
`config.vm.communicator` - The communicator type to use to connect to the
* `config.vm.communicator` (string) - The communicator type to use to connect to the
guest box. By default this is `"ssh"`, but should be changed to `"winrm"` for
Windows guests.
<hr>
`config.vm.graceful_halt_timeout` - The time in seconds that Vagrant will
* `config.vm.graceful_halt_timeout` (integer) - The time in seconds that Vagrant will
wait for the machine to gracefully halt when `vagrant halt` is called.
Defaults to 60 seconds.
<hr>
`config.vm.guest` - The guest OS that will be running within this
* `config.vm.guest` (string, symbol) - The guest OS that will be running within this
machine. This defaults to `:linux`, and Vagrant will auto-detect the
proper distro. However, this should be changed to `:windows` for Windows guests.
Vagrant needs to know this information to perform some guest OS-specific things
proper distro. However, this should be changed to `:windows` for Windows guests.
Vagrant needs to know this information to perform some guest OS-specific things
such as mounting folders and configuring networks.
<hr>
`config.vm.hostname` - The hostname the machine should have. Defaults
* `config.vm.hostname` (string) - The hostname the machine should have. Defaults
to nil. If nil, Vagrant will not manage the hostname. If set to a string,
the hostname will be set on boot. If set, Vagrant will update `/etc/hosts`
on the guest with the configured hostname.
<hr>
`config.vm.ignore_box_vagrantfile` - If true, Vagrant will not load the the
* `config.vm.ignore_box_vagrantfile` (boolean) - If true, Vagrant will not load the the
settings found inside a boxes Vagrantfile, if present. Defaults to `false`.
<hr>
`config.vm.network` - Configures [networks](/docs/networking/) on
* `config.vm.network` - Configures [networks](/docs/networking/) on
the machine. Please see the networking page for more information.
<hr>
`config.vm.post_up_message` - A message to show after `vagrant up`. This
* `config.vm.post_up_message` (string) - A message to show after `vagrant up`. This
will be shown to the user and is useful for containing instructions
such as how to access various components of the development environment.
<hr>
`config.vm.provider` - Configures [provider-specific configuration](/docs/providers/configuration.html),
* `config.vm.provider` - Configures [provider-specific configuration](/docs/providers/configuration.html),
which is used to modify settings which are specific to a certain
[provider](/docs/providers/). If the provider you are configuring
does not exist or is not setup on the system of the person who runs
@ -162,23 +123,15 @@ does not exist or is not setup on the system of the person who runs
a Vagrantfile that is configured for many providers to be shared among
a group of people who may not have all the same providers installed.
<hr>
`config.vm.provision` - Configures [provisioners](/docs/provisioning/)
* `config.vm.provision` - Configures [provisioners](/docs/provisioning/)
on the machine, so that software can be automatically installed and configured
when the machine is created. Please see the page on provisioners for more
information on how this setting works.
<hr>
`config.vm.synced_folder` - Configures [synced folders](/docs/synced-folders/)
* `config.vm.synced_folder` - Configures [synced folders](/docs/synced-folders/)
on the machine, so that folders on your host machine can be synced to
and from the guest machine. Please see the page on synced folders for
more information on how this setting works.
<hr>
`config.vm.usable_port_range` - A range of ports Vagrant can use for
* `config.vm.usable_port_range` (range) - A range of ports Vagrant can use for
handling port collisions and such. Defaults to `2200..2250`.
<hr>

143
website/source/docs/vagrantfile/ssh_settings.html.md
View File

@ -18,165 +18,120 @@ defaults are typically fine, but you can fine tune whatever you would like.
## Available Settings
`config.ssh.username` - This sets the username that Vagrant will SSH
* `config.ssh.username` (string) - This sets the username that Vagrant will SSH
as by default. Providers are free to override this if they detect a more
appropriate user. By default this is "vagrant", since that is what most
public boxes are made as.
<hr>
`config.ssh.password` - This sets a password that Vagrant will use to
* `config.ssh.password` (string) - This sets a password that Vagrant will use to
authenticate the SSH user. Note that Vagrant recommends you use key-based
authentication rather than a password (see `private_key_path`) below. If
you use a password, Vagrant will automatically insert a keypair if
`insert_key` is true.
<hr>
`config.ssh.host` - The hostname or IP to SSH into. By default this is
* `config.ssh.host` (string) - The hostname or IP to SSH into. By default this is
empty, because the provider usually figures this out for you.
<hr>
* `config.ssh.port` (integer) - The port to SSH into. By default this is port 22.
`config.ssh.port` - The port to SSH into. By default this is port 22.
<hr>
`config.ssh.guest_port` - The port on the guest that SSH is running on. This
* `config.ssh.guest_port` (integer) - The port on the guest that SSH is running on. This
is used by some providers to detect forwarded ports for SSH. For example, if
this is set to 22 (the default), and Vagrant detects a forwarded port to
port 22 on the guest from port 4567 on the host, Vagrant will attempt
to use port 4567 to talk to the guest if there is no other option.
<hr>
`config.ssh.private_key_path` - The path to the private key to use to
SSH into the guest machine. By default this is the insecure private key
* `config.ssh.private_key_path` (string, array of strings) - The path to the private
key to use to SSH into the guest machine. By default this is the insecure private key
that ships with Vagrant, since that is what public boxes use. If you make
your own custom box with a custom SSH key, this should point to that
private key.
You can also specify multiple private keys by setting this to be an array.
private key. You can also specify multiple private keys by setting this to be an array.
This is useful, for example, if you use the default private key to bootstrap
the machine, but replace it with perhaps a more secure key later.
<hr>
`config.ssh.keys_only` - Only use Vagrant-provided SSH private keys (do not use
* `config.ssh.keys_only` (boolean) - Only use Vagrant-provided SSH private keys (do not use
any keys stored in ssh-agent). The default value is `true`.
<hr>
* `config.ssh.verify_host_key` (string, symbol) - Perform strict host-key verification. The
default value is `:never`.
`config.ssh.verify_host_key` - Perform strict host-key verification. The default
value is `:never`.
* `config.ssh.paranoid` (boolean) - Perform strict host-key verification. The default value is
`false`.
<hr>
__Deprecation:__ The `config.ssh.paranoid` option is deprecated and will be removed
in a future release. Please use the `config.ssh.verify_host_key` option instead.
`config.ssh.paranoid` - Perform strict host-key verification. The default value
is `false`.
__Deprecation:__
The `config.ssh.paranoid` option is deprecated and will be removed in a future release.
Please use the `config.ssh.verify_host_key` option instead.
<hr>
`config.ssh.forward_agent` - If `true`, agent forwarding over SSH
* `config.ssh.forward_agent` (boolean) - If `true`, agent forwarding over SSH
connections is enabled. Defaults to false.
<hr>
`config.ssh.forward_x11` - If `true`, X11 forwarding over SSH connections
* `config.ssh.forward_x11` (boolean) - If `true`, X11 forwarding over SSH connections
is enabled. Defaults to false.
<hr>
`config.ssh.forward_env` - An array of host environment variables to forward to
the guest. If you are familiar with OpenSSH, this corresponds to the `SendEnv`
* `config.ssh.forward_env` (array of strings) - An array of host environment variables to
forward to the guest. If you are familiar with OpenSSH, this corresponds to the `SendEnv`
parameter.
```ruby
config.ssh.forward_env = ["CUSTOM_VAR"]
```
```ruby
config.ssh.forward_env = ["CUSTOM_VAR"]
```
<hr>
* `config.ssh.insert_key` (boolean) - If `true`, Vagrant will automatically insert
a keypair to use for SSH, replacing Vagrant's default insecure key inside the machine
if detected. By default, this is true.
`config.ssh.insert_key` - If `true`, Vagrant will automatically insert
a keypair to use for SSH, replacing Vagrant's default insecure key
inside the machine if detected. By default, this is true.
This only has an effect if you do not already
use private keys for authentication or if you are relying on the default insecure key.
If you do not have to care about security in your project and want to
keep using the default insecure key, set this to `false`.
This only has an effect if you do not already use private keys for
authentication or if you are relying on the default insecure key.
If you do not have to care about security in your project and want to
keep using the default insecure key, set this to `false`.
<hr>
`config.ssh.proxy_command` - A command-line command to execute that receives
* `config.ssh.proxy_command` (string) - A command-line command to execute that receives
the data to send to SSH on stdin. This can be used to proxy the SSH connection.
`%h` in the command is replaced with the host and `%p` is replaced with
the port.
<hr>
* `config.ssh.pty` (boolean) - If `true`, pty will be used for provisioning. Defaults to false.
`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
absolutely necessary. It breaks some other features of Vagrant, and is
really only exposed for cases where it is absolutely necessary. If you can find
a way to not use a pty, that is recommended instead.
This setting is an _advanced feature_ that should not be enabled unless
absolutely necessary. It breaks some other features of Vagrant, and is
really only exposed for cases where it is absolutely necessary. If you can find
a way to not use a pty, that is recommended instead.
When pty is enabled, it is important to note that command output will _not_ be
streamed to the UI. Instead, the output will be delivered in full to the UI
once the command has completed.
When pty is enabled, it is important to note that command output will _not_ be
streamed to the UI. Instead, the output will be delivered in full to the UI
once the command has completed.
<hr>
`config.ssh.keep_alive` If `true`, this setting SSH will send keep-alive packets
* `config.ssh.keep_alive` (boolean) - If `true`, this setting SSH will send keep-alive packets
every 5 seconds by default to keep connections alive.
<hr>
`config.ssh.shell` - The shell to use when executing SSH commands from
* `config.ssh.shell` (string) - The shell to use when executing SSH commands from
Vagrant. By default this is `bash -l`. Note that this has no effect on
the shell you get when you run `vagrant ssh`. This configuration option
only affects the shell to use when executing commands internally in Vagrant.
<hr>
`config.ssh.export_command_template` - The template used to generate
* `config.ssh.export_command_template` (string) - The template used to generate
exported environment variables in the active session. This can be useful
when using a Bourne incompatible shell like C shell. The template supports
two variables which are replaced with the desired environment variable key and
environment variable value: `%ENV_KEY%` and `%ENV_VALUE%`. The default template
is:
```ruby
config.ssh.export_command_template = 'export %ENV_KEY%="%ENV_VALUE%"'
```
```ruby
config.ssh.export_command_template = 'export %ENV_KEY%="%ENV_VALUE%"'
```
<hr>
`config.ssh.sudo_command` - The command to use when executing a command
* `config.ssh.sudo_command` (string) - The command to use when executing a command
with `sudo`. This defaults to `sudo -E -H %c`. The `%c` will be replaced by
the command that is being executed.
<hr>
`config.ssh.compression` - If `false`, this setting will not include the
* `config.ssh.compression` (boolean) - If `false`, this setting will not include the
compression setting when ssh'ing into a machine. If this is not set, it will
default to `true` and `Compression=yes` will be enabled with ssh.
<hr>
`config.ssh.dsa_authentication` - If `false`, this setting will not include
* `config.ssh.dsa_authentication` (boolean) - If `false`, this setting will not include
`DSAAuthentication` when ssh'ing into a machine. If this is not set, it will
default to `true` and `DSAAuthentication=yes` will be used with ssh.
<hr>
`config.ssh.extra_args` - This settings value is passed directly into the
ssh executable. This allows you to pass any arbitrary commands to do things such
* `config.ssh.extra_args` (array of strings) - This settings value is passed directly
into the ssh executable. This allows you to pass any arbitrary commands to do things such
as reverse tunneling down into the ssh program. These options can either be
single flags set as strings such as `"-6"` for IPV6 or an array of arguments
such as `["-L", "8008:localhost:80"]` for enabling a tunnel from host port 8008

54
website/source/docs/vagrantfile/vagrant_settings.html.md
View File

@ -16,48 +16,48 @@ itself.
## Available Settings
`config.vagrant.host` - This sets the type of host machine that is running
Vagrant. By default this is `:detect`, which causes Vagrant to auto-detect
the host. Vagrant needs to know this information in order to perform some
host-specific things, such as preparing NFS folders if they're enabled.
* `config.vagrant.host` (string, symbol) - This sets the type of host machine
that is running Vagrant. By default this is `:detect`, which causes Vagrant to
auto-detect the host. Vagrant needs to know this information in order to perform
some host-specific things, such as preparing NFS folders if they're enabled.
You should only manually set this if auto-detection fails.
`config.vagrant.plugins` - (string, array, hash) - Define plugin, list of
* `config.vagrant.plugins` - (string, array, hash) - Define plugin, list of
plugins, or definition of plugins to install for the local project. Vagrant
will require these plugins be installed and available for the project. If
the plugins are not available, it will attempt to automatically install
them into the local project. When requiring a single plugin, a string can
be provided:
```ruby
config.vagrant.plugins = "vagrant-plugin"
```
```ruby
config.vagrant.plugins = "vagrant-plugin"
```
If multiple plugins are required, they can be provided as an array:
If multiple plugins are required, they can be provided as an array:
```ruby
config.vagrant.plugins = ["vagrant-plugin", "vagrant-other-plugin"]
```
```ruby
config.vagrant.plugins = ["vagrant-plugin", "vagrant-other-plugin"]
```
Plugins can also be defined as a Hash, which supports setting extra options
for the plugins. When a Hash is used, the key is the name of the plugin, and
the value is a Hash of options for the plugin. For example, to set an explicit
version of a plugin to install:
Plugins can also be defined as a Hash, which supports setting extra options
for the plugins. When a Hash is used, the key is the name of the plugin, and
the value is a Hash of options for the plugin. For example, to set an explicit
version of a plugin to install:
```ruby
config.vagrant.plugins = {"vagrant-scp" => {"version" => "1.0.0"}}
```
```ruby
config.vagrant.plugins = {"vagrant-scp" => {"version" => "1.0.0"}}
```
Supported options are:
Supported options are:
* `entry_point` - Path for Vagrant to load plugin
* `sources` - Custom sources for downloading plugin
* `version` - Version constraint for plugin
* `entry_point` - Path for Vagrant to load plugin
* `sources` - Custom sources for downloading plugin
* `version` - Version constraint for plugin
`config.vagrant.sensitive` - (string, array) - Value or list of values that
* `config.vagrant.sensitive` - (string, array) - Value or list of values that
should not be displayed in Vagrant's output. Value(s) will be removed from
Vagrant's normal UI output as well as logger output.
```ruby
config.vagrant.sensitive = ["MySecretPassword", ENV["MY_TOKEN"]]
```
```ruby
config.vagrant.sensitive = ["MySecretPassword", ENV["MY_TOKEN"]]
```

61
website/source/docs/vagrantfile/winrm_settings.html.md
View File

@ -20,59 +20,56 @@ These settings are only used if you've set your communicator type to `:winrm`.
## Available Settings
`config.winrm.username` - This sets the username that Vagrant will use
* `config.winrm.username` (string) - This sets the username that Vagrant will use
to login to the WinRM web service by default. Providers are free to override
this if they detect a more appropriate user. By default this is "vagrant,"
since that is what most public boxes are made as.
<hr>
`config.winrm.password` - This sets a password that Vagrant will use to
* `config.winrm.password` (string) - This sets a password that Vagrant will use to
authenticate the WinRM user. By default this is "vagrant," since that is
what most public boxes are made as.
<hr>
`config.winrm.host` - The hostname or IP to connect to the WinRM service.
* `config.winrm.host` (string) - The hostname or IP to connect to the WinRM service.
By default this is empty, because the provider usually figures this out for
you.
<hr>
* `config.winrm.port` (integer) - The WinRM port to connect to, by default 5985.
`config.winrm.port` - The WinRM port to connect to, by default 5985.
<hr>
`config.winrm.guest_port` - The port on the guest that WinRM is running on.
* `config.winrm.guest_port` (integer) - The port on the guest that WinRM is running on.
This is used by some providers to detect forwarded ports for WinRM. For
example, if this is set to 5985 (the default), and Vagrant detects a forwarded
port to port 5985 on the guest from port 4567 on the host, Vagrant will attempt
to use port 4567 to talk to the guest if there is no other option.
<hr>
* `config.winrm.transport` (symbol)- The transport used for WinRM communication.
Valid settings include: `:negotiate`, `:ssl`, and `:plaintext`. The default is `:negotiate`.
`config.winrm.transport` - The transport used for WinRM communication. Valid settings include: `:negotiate`, `:ssl`, and `:plaintext`. The default is `:negotiate`.
* `config.winrm.basic_auth_only` (boolean) - Whether to use Basic Authentication. Defaults
to `false`. If set to `true` you should also use the `:plaintext` transport setting and
the Windows machine must be configured appropriately.
<hr>
**Note:** It is strongly recommended that you only use basic authentication for
debugging purposes. Credentials will be transferred in plain text.
`config.winrm.basic_auth_only` - Whether to use Basic Authentication. Defaults to `false`. If set to `true` you should also use the `:plaintext` transport setting and the Windows machine must be configured appropriately. <strong>Note:</strong> It is strongly recommended that you only use basic authentication for debugging purposes. Credentials will be transferred in plain text.
* `config.winrm.ssl_peer_verification` (boolean) - When set to `false` ssl certificate
validation is not performed.
<hr>
* `config.winrm.timeout` (integer) - The maximum amount of time to wait for a response
from the endpoint. This defaults to 60 seconds. Note that this will not "timeout"
commands that exceed this amount of time to process, it just requires the endpoint to
report the status of the command before the given amount of time passes.
`config.winrm.ssl_peer_verification` - When set to `false` ssl certificate validation is not performed.
* `config.winrm.retry_limit` (integer) - The maximum number of times to retry opening
a shell after failure. This defaults to 3.
<hr>
* `config.winrm.retry_delay` (integer) - The amount of time to wait between retries and
defaults to 10 seconds.
`config.winrm.timeout` - The maximum amount of time to wait for a response from the endpoint. This defaults to 60 seconds. Note that this will not "timeout" commands that exceed this amount of time to process, it just requires the endpoint to report the status of the command before the given amount of time passes.
* `config.winrm.codepage` (string) - The WINRS_CODEPAGE which is the client's console
output code page. The default is 65001 (UTF-8).
<hr>
`config.winrm.retry_limit` - The maximum number of times to retry opening a shell after failure. This defaults to 3.
<hr>
`config.winrm.retry_delay` - The amount of time to wait between retries and defaults to 10 seconds.
<hr>
`config.winrm.codepage` - The WINRS_CODEPAGE which is the client's console output code page. The default is 65001 (UTF-8). <strong>Note:</strong> Versions of Windows older than Windows 7/Server 2008 R2 may exhibit undesirable behavior using the default UTF-8 codepage. When using these older versions of Windows, its best to use the native code page of the server's locale. For example, en-US servers will have a codepage of 437. The Windows `chcp` command can be used to determine the value of the native codepage.
**Note:** Versions of Windows older than Windows 7/Server 2008 R2 may exhibit
undesirable behavior using the default UTF-8 codepage. When using these older
versions of Windows, its best to use the native code page of the server's locale.
For example, en-US servers will have a codepage of 437. The Windows `chcp` command
can be used to determine the value of the native codepage.

136
website/source/docs/vagrantfile/winssh_settings.html.md
View File

@ -15,9 +15,6 @@ port of OpenSSH. It does not rely on a POSIX-like environment which
removes the requirement of extra software installation (like cygwin)
for proper functionality.
_NOTE: The Windows native port of OpenSSH is still considered
"pre-release" and is non-production ready._
For more information, see the [Win32-OpenSSH project page](https://github.com/PowerShell/Win32-OpenSSH/).
# WinSSH Settings
@ -26,143 +23,56 @@ The WinSSH communicator uses the same connection configuration options
as the SSH communicator. These settings provide the information for the
communicator to establish a connection to the VM.
**Config namespace: `config.ssh`**
The settings within `config.ssh` relate to configuring how Vagrant
will access your machine over SSH. As with most Vagrant settings, the
defaults are typically fine, but you can fine tune whatever you would like.
## Available Settings
`config.ssh.username` - This sets the username that Vagrant will SSH
as by default. Providers are free to override this if they detect a more
appropriate user. By default this is "vagrant," since that is what most
public boxes are made as.
<hr>
`config.ssh.password` - This sets a password that Vagrant will use to
authenticate the SSH user. Note that Vagrant recommends you use key-based
authentication rather than a password (see `private_key_path`) below. If
you use a password, Vagrant will automatically insert a keypair if
`insert_key` is true.
<hr>
`config.ssh.host` - The hostname or IP to SSH into. By default this is
empty, because the provider usually figures this out for you.
<hr>
`config.ssh.port` - The port to SSH into. By default this is port 22.
<hr>
`config.ssh.guest_port` - The port on the guest that SSH is running on. This
is used by some providers to detect forwarded ports for SSH. For example, if
this is set to 22 (the default), and Vagrant detects a forwarded port to
port 22 on the guest from port 4567 on the host, Vagrant will attempt
to use port 4567 to talk to the guest if there is no other option.
<hr>
`config.ssh.private_key_path` - The path to the private key to use to
SSH into the guest machine. By default this is the insecure private key
that ships with Vagrant, since that is what public boxes use. If you make
your own custom box with a custom SSH key, this should point to that
private key.
You can also specify multiple private keys by setting this to be an array.
This is useful, for example, if you use the default private key to bootstrap
the machine, but replace it with perhaps a more secure key later.
<hr>
`config.ssh.insert_key` - If `true`, Vagrant will automatically insert
a keypair to use for SSH, replacing Vagrant's default insecure key
inside the machine if detected. By default, this is true.
This only has an effect if you do not already use private keys for
authentication or if you are relying on the default insecure key.
If you do not have to care about security in your project and want to
keep using the default insecure key, set this to `false`.
<hr>
`config.ssh.keys_only` - Only use Vagrant-provided SSH private keys (do not use
any keys stored in ssh-agent). The default value is `true`.`
<hr>
`config.ssh.paranoid` - Perform strict host-key verification. The default value
is `false`.
# WinSSH Settings
The configuration options below are specific to the WinSSH communicator.
**Config namespace: `config.winssh`**
## Available Settings
`config.winssh.forward_agent` - If `true`, agent forwarding over SSH
* `config.winssh.forward_agent` (boolean) - If `true`, agent forwarding over SSH
connections is enabled. Defaults to false.
<hr>
* `config.winssh.forward_env` (array of strings) - An array of host environment
variables to forward to the guest. If you are familiar with OpenSSH, this corresponds
to the `SendEnv` parameter.
`config.winssh.forward_env` - An array of host environment variables to forward to
the guest. If you are familiar with OpenSSH, this corresponds to the `SendEnv`
parameter.
```ruby
config.winssh.forward_env = ["CUSTOM_VAR"]
```
* `config.winssh.proxy_command` (string) - A command-line command to execute that
receives the data to send to SSH on stdin. This can be used to proxy the SSH connection.
`%h` in the command is replaced with the host and `%p` is replaced with the port.
```ruby
config.winssh.forward_env = ["CUSTOM_VAR"]
```
* `config.winssh.keep_alive` (boolean) - If `true`, this setting SSH will send keep-alive
packets every 5 seconds by default to keep connections alive.
<hr>
`config.winssh.proxy_command` - A command-line command to execute that receives
the data to send to SSH on stdin. This can be used to proxy the SSH connection.
`%h` in the command is replaced with the host and `%p` is replaced with
the port.
<hr>
`config.winssh.keep_alive` If `true`, this setting SSH will send keep-alive packets
every 5 seconds by default to keep connections alive.
<hr>
`config.winssh.shell` - The shell to use when executing SSH commands from
* `config.winssh.shell` (string) - The shell to use when executing SSH commands from
Vagrant. By default this is `cmd`. Valid values are `"cmd"` or `"powershell"`.
Note that this has no effect on the shell you get when you run `vagrant ssh`.
This configuration option only affects the shell to use when executing commands
internally in Vagrant.
<hr>
`config.winssh.export_command_template` - The template used to generate
* `config.winssh.export_command_template` (string) - The template used to generate
exported environment variables in the active session. This can be useful
when using a Bourne incompatible shell like C shell. The template supports
two variables which are replaced with the desired environment variable key and
environment variable value: `%ENV_KEY%` and `%ENV_VALUE%`. The default template
for a `cmd` configured shell is:
```ruby
config.winssh.export_command_template = 'set %ENV_KEY%="%ENV_VALUE%"'
```
```ruby
config.winssh.export_command_template = 'set %ENV_KEY%="%ENV_VALUE%"'
```
The default template for a `powershell` configured shell is:
The default template for a `powershell` configured shell is:
```ruby
config.winssh.export_command_template = '$env:%ENV_KEY%="%ENV_VALUE%"'
```
```ruby
config.winssh.export_command_template = '$env:%ENV_KEY%="%ENV_VALUE%"'
```
`config.winssh.sudo_command` - The command to use when executing a command
* `config.winssh.sudo_command` (string) - The command to use when executing a command
with `sudo`. This defaults to `%c` (assumes vagrant user is an administrator
and needs no escalation). The `%c` will be replaced by the command that is
being executed.
<hr>
`config.winssh.upload_directory` - The upload directory used on the guest
* `config.winssh.upload_directory` (string) - The upload directory used on the guest
to store scripts for execute. This is set to `C:\Windows\Temp` by default.