Skip to content

Commit

Permalink
Update windows.md
Browse files Browse the repository at this point in the history
  • Loading branch information
tomjn authored Sep 18, 2024
1 parent 75ebf2c commit f2973d1
Showing 1 changed file with 25 additions and 3 deletions.
28 changes: 25 additions & 3 deletions docs/en-US/troubleshooting/windows.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,16 +25,38 @@ If you are using Windows and see this:
==> default: timeout during server version negotiating
```

Then it's likely you don't have a working SSH Agent. The primary reason git is listed in the software requirements is because it installs git bash and provides an SSH Agent that Vagrant knows how to talk to.
Then it's likely you don't have a working SSH Agent, or you are using VirtualBox and have issues with your computer going to sleep.

It's also possible that your SSH Agent previously worked but is no longer running!
### Missing SSH Agents

In order to talk to the VM we need an SSH Agent, and since Windows doesn't support this we ask that you install Git for Windows as it comes with one.

Unfortunately sometimes the SSH Agent doesn't start or it exits/ends for various reasons, leading to the timeout issue above. You can work around this by restarting the SSH Agent, and making sure you're using git bash ( some terminals don't work with git bash's SSH agent, or have conflicting issues, e.g. Powershell ISE ).

To fix this, we recommend that:

- use Git Bash to run vagrant commands on Windows
- use Git Bash to run `vagrant` commands on Windows
- If using VirtualBox, use at least VirtualBox 7 or higher
- Ensure the SSH Agent is running by using the command `eval "$(ssh-agent -s)"`

It's also strongly recommended you read this GitHub troubleshooting article:

https://docs.github.com/en/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases

#### Can I Use The OpenSSH Windows Service?

No. While this service has an SSH Agent, Vagrant does not know how to talk to it, so it cannot be used. Vagrant knows how to talk with the ssh agents provided by cygwin and git bash.

### VirtualBox and Sleep

There is a known bug in VirtualBox that makes a VM unreachable when your computer goes to sleep, e.g. closing a laptops lid. If your VVV instance works but then mysteriously breaks if you put your computer to sleep, yet a `vagrant up` after a full restart works then this may be the cause of your troubles.

Whil there is no VVV specific solution to this, we recommend that:

- Keep VirtualBox and Windows up to date
- Run `vagrant halt` or `vagrant suspend` before putting your machine to sleep, then waking it up with `vagrant up` when you return.
- Investigating an alternative provider such as Docker or Hyper-V that doesn't have this problem.

## Symlink Provisioning Errors

If you're seeing errors related to creating symlinks in the provisioning then you need to double check that you're using an admin/elevated command prompt to run the vagrant provisioning commands. This is because on Windows creating a symlink requires elevated priviledges that a normal command prompt doesn't have. You might be able to get away with a `vagrant up` for a VM that has already been created though.

0 comments on commit f2973d1

Please sign in to comment.