add troubleshooting

Troubleshooting.md

@@ -0,0 +1,103 @@
+# Troubleshooting
+## General tips
+There are some rare problems that can happen when playing the game. The vast majority of them happen when first starting the game. In general, when encountering the problem, you should first make sure that:
+- You have virtualization really turned on (in BIOS).
+- You haven't ran out of disk space.
+- You haven't ran out of RAM.
+- On Windows, make sure you're running your terminal/powershell window as administrator.
+
+You can hard-exit a running assistant by Ctrl+C, and then confirming by writing `yes`. (Unlike typing `exit` or `abort`, this will not shut down the underlying VirtualBox and Vagrant processes.)
+
+Finally, most problems are best solved by "turning it on and off again". If something goes wrong, you can turn your computer off and back on, run `abort` in the assistant, and there's a good chance that the problem won't occur the second time you try to play the game.
+
+# Known Errors
+## Vagrant can't verify certificates
+For some people, Vagrant isn't able to verify the used boxes (virtual machines) necessary for the game.
+
+The exact error messages look something like this:
+```
+vagrant box add munikypo/kali-2019.4
+The box 'munikypo/kali-2019.4' could not be found or
+could not be accessed in the remote catalog. If this is a private
+box on HashiCorp's Vagrant Cloud, please verify you're logged in via
+`vagrant login`. Also, please double-check the name. The expanded
+URL and error message are shown below:
+
+URL: ["https://vagrantcloud.com/munikypo/kali-2019.4"]
+Error: schannel: next InitializeSecurityContext failed: Unknown error (0x80092012) - The revocation function was unable to check revocation for the certificate.
+```
+### Possible solutions
+The exact causes of this error are unknown, but you can try the following:
+- Temporarily disable your antivirus.
+- Temporarily disable any running VPN connection
+
+This usually fixes the problem.
+### The workaround
+If no above solutions work, you can use the following workaround.
+
+By adding the necessary boxes with `--insecure`, Vagrant will skip the certificate check. (This is generally not a good idea, but the boxes used for your game should be known and tested to be safe.)
+
+Examples of commands to run: (these may differ depending on the game)
+```
+vagrant box add munikypo/kali-2019.4 --insecure
+vagrant box add generic/debian10 --insecure
+```
+When downloading the debian10 box, select `virtualbox` as your provider.
+
+## Vagrant gets stuck during setup of a machine (usually `br`)
+The game sometimes gets stuck during setup while setting up. **This mostly happens on Windows.** (but can happen on other operating systems too.)
+
+The exact messages usually look like this:
+```
+Bringing machine 'br' up with 'virtualbox' provider...
+```
+```
+==> br: Running provisioner: ansible_local...
+```
+
+The recommended way of getting rid of this bug is just resetting your computer (or killing all vagrant/ruby processes), restarting the assistant, then running `abort` and `start` again.
+### Alternative workaround
+If the problem persists for multiple tries, there's a workaround.
+The instructions are as follows:
+
+0. Run `abort` in the assistant to start over.
+1. Run `start` in the assistant. When a machine gets stuck, Ctrl+C to exit the assistant.
+2. Kill all vagrant/ruby processes (or restart your computer)
+3. Go to the `game` folder and run `vagrant provision [name_of_stuck_nachine]` (If an error shows up, continue to step 4 anyway.)
+4. Go back to the `assistant` folder, run the assistant, and run `start` again. (DON'T `abort`)
+5. If there are no errors and you can begin playing the game, the game was started succesfully.
+
+This workaround manually prepares the virtual machine the assistant gets stuck on, and then the assistant works as usual when restarted. It's possible that this can possibly make the game error out later.
+## Vagrant (Ruby) error: "Unknown encoding name"
+On Windows, if your system locale/language is not English, you can encounter the following error:
+```
+[...] in `find': unknown encoding name - CP720 (ArgumentError)
+```
+You can fix the problem by running `chcp 1252` in the command prompt before you launch the assistant. (The command changes the encoding just for the running terminal session, so that you can play the game, but your system settings remain unchanged.)
+
+## Vagrant error: "incompatible character encodings: CP852 and Windows-1250"
+On Windows, Vagrant doesn't like special characters (like "é", "á", etc.) in the username of the Windows user. It attempts to download files to a folder in the user directory, and fails because of that.
+
+The workaround for that is to change the folder it downloads the file to by changing the `VAGRANT_HOME` system variable.
+
+1. Make a new folder with no special characters in its path (like `C:\VagrantBoxes`)
+2. Open an admin command prompt, and run `setx VAGRANT_HOME "C:\VagrantBoxes"` (change `C:\VagrantBoxes` for your folder's path)
+3. In a new command prompt, run the assistant again -- all should work fine now.
+
+Another more difficult workaround would be making a new Windows user account with no special characters in the path, and then installing and running the game on that account.
+
+## Ansible error: Repository changed its Suite value from "stable" to "oldstable"
+This error can happen if you previously played a similar game, and the game is trying to build itself from old virtual machines.
+
+You can fix this problem by going to the `game/` subfolder in the project, and running `vagrant box update` in it.
+
+(Alternatively, you can also delete the `.vagrant.d/` folder in your home, but this will delete all the virtual machines, and possibly other vagrant data.)
+
+## Further Hyper-V problems: Very slow VMs, or stuck on `SSH auth method: private key`, etc.
+Sometimes it is not enough to disable Hyper-V in Settings.
+If you use WSL, then you might get the same issues as you would with Hyper-V, because WSL uses a subset of Hyper-V.
+
+If your game is acting ridiculously slow, or if Vagrant can't setup the game because it gets stuck on `SSH auth method: private key` line, or if you get `Timed out while waiting for machine to boot` error, you can try to run the command below.
+1. Run `bcdedit /set hypervisorlaunchtype off` in admin command prompt.
+2. Reset your computer, and try running the game again. (WSL will NOT work for the time being.)
+3. After you're done playing the game, run `bcdedit /set hypervisorlaunchtype auto`. WSL will work again after you restart.