vagrant-ssh

SSH into the machine running in the current directory

$ vagrant ssh

$ vagrant ssh [name|id]

$ vagrant ssh [[-c|--command]] [ssh_command]

$ vagrant ssh [[-p|--plain]]

vagrant ssh [options] [vm-name] [-c <command>] [-- <ssh-args>]

[vm-name]
    The name of the specific virtual machine to connect to. Required if multiple VMs are defined in the Vagrantfile.

-c <command>, --command <command>
    Executes a single command on the remote virtual machine and then exits the SSH session. The command should be enclosed in quotes if it contains spaces.

--extra-args <args>
    Passes additional, raw arguments directly to the underlying ssh client. Arguments should typically be wrapped in quotes. This is an alternative to using --.

--plain
    Uses a 'plain' SSH connection without any Vagrant-specific configuration. This means Vagrant will not try to forward ports or setup authentication based on its internal knowledge.

--pty, --tty
    Forces pseudo-terminal allocation. This is useful when the remote command expects an interactive terminal, even if it's not a full shell.

--host-key-check
    Enables strict host key checking. By default, Vagrant often bypasses this for convenience in development environments. Use this for stricter security.

--debug
    Enables verbose debugging output for the SSH connection process, which can be useful for troubleshooting connectivity issues.

-- <ssh-args>
    A separator indicating that all subsequent arguments should be passed directly to the underlying ssh client. This is the recommended way to pass raw SSH arguments.

The vagrant ssh command allows users to securely connect to a running Vagrant virtual machine (VM) via SSH. It simplifies the process by automatically handling SSH key management, port forwarding, and user configuration, abstracting away the complexities of direct SSH client usage. This command is essential for interacting with the guest operating system, enabling tasks such as installing software, configuring services, debugging applications, or simply exploring the VM's environment. It can be used to open an interactive shell session or to execute a single command remotely and then exit, providing flexibility for both manual interaction and automation workflows within your Vagrant development environment. If multiple VMs are defined in your Vagrantfile, you must specify which VM to connect to.

The vagrant ssh command requires the target virtual machine to be in a 'running' state. If the VM is halted, suspended, or not initialized, the command will fail. Ensure that an SSH server is running and accessible within the guest operating system. Network configurations (e.g., firewalls within the guest or on the host) can block SSH access. If using a multi-machine environment, failing to specify a vm-name will result in an error or a prompt to select a VM.

Vagrant automatically generates and manages SSH key pairs for each VM, placing the private key in a secure location and configuring the guest OS with the corresponding public key. This removes the need for manual key generation and distribution, making the SSH connection seamless. It also configures SSH client settings like user and port automatically based on the Vagrantfile and provider information.

Beyond interactive shells, vagrant ssh -c "<command>" is incredibly useful for scripting and automation. It allows you to execute commands like 'vagrant ssh -c "sudo apt update"' or 'vagrant ssh webserver -c "service apache2 restart"' without needing to manually log in, making it a powerful tool for provisioning, testing, and deployment workflows.

In a multi-machine Vagrantfile, where multiple virtual machines are defined (e.g., 'webserver', 'dbserver'), you must specify which VM you want to connect to: 'vagrant ssh webserver'. If you omit the VM name and multiple VMs exist, Vagrant will either error or prompt you to choose, preventing ambiguous connections.

The ability to SSH into a guest machine has been a fundamental feature of Vagrant since its inception by Mitchell Hashimoto. It addresses the core need for interacting with the development environment running within the VM. Over time, the vagrant ssh command has evolved to become more robust, handling various networking scenarios, multi-machine setups, and offering more options for passing raw SSH arguments, reflecting the growing complexity and versatility of Vagrant environments.

vagrant(1), vagrant up(1), vagrant halt(1), vagrant suspend(1), ssh(1)