Skip to content

Commit 8308775

Browse files
authored
Update troubleshooting document to address #1463 and related issues (#1835)
Clarify instructions in troubleshooting re: removing wireguard and config files as well as add troubleshooting step re: localhost being used instead of a domain name or IP address.
1 parent f76d361 commit 8308775

File tree

1 file changed

+39
-2
lines changed

1 file changed

+39
-2
lines changed

docs/troubleshooting.md

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ First of all, check [this](https://github.com/trailofbits/algo#features) and ens
1818
* [DigitalOcean: error tagging resource 'xxxxxxxx': param is missing or the value is empty: resources](#digitalocean-error-tagging-resource)
1919
* [Windows: The value of parameter linuxConfiguration.ssh.publicKeys.keyData is invalid](#windows-the-value-of-parameter-linuxconfigurationsshpublickeyskeydata-is-invalid)
2020
* [Docker: Failed to connect to the host via ssh](#docker-failed-to-connect-to-the-host-via-ssh)
21+
* [Error: Failed to create symlinks for deploying to localhost](#error-failed-to-create-symlinks-for-deploying-to-localhost)
2122
* [Wireguard: Unable to find 'configs/...' in expected paths](#wireguard-unable-to-find-configs-in-expected-paths)
2223
* [Ubuntu Error: "unable to write 'random state'" when generating CA password](#ubuntu-error-unable-to-write-random-state-when-generating-ca-password)
2324
* [Connection Problems](#connection-problems)
@@ -273,6 +274,41 @@ You need to add the following to the ansible.cfg in repo root:
273274
control_path_dir=/dev/shm/ansible_control_path
274275
```
275276

277+
### Error: Failed to create symlinks for deploying to localhost
278+
279+
You tried to run Algo and you received an error like this one:
280+
281+
```
282+
TASK [Create a symlink if deploying to localhost] ********************************************************************
283+
fatal: [localhost]: FAILED! => {"changed": false, "gid": 1000, "group": "ubuntu", "mode": "0775", "msg": "the directory configs/localhost is not empty, refusing to convert it", "owner": "ubuntu", "path": "configs/localhost", "size": 4096, "state": "directory", "uid": 1000}
284+
included: /home/ubuntu/algo-master/playbooks/rescue.yml for localhost
285+
286+
TASK [debug] *********************************************************************************************************
287+
ok: [localhost] => {
288+
"fail_hint": [
289+
"Sorry, but something went wrong!",
290+
"Please check the troubleshooting guide.",
291+
"https://trailofbits.github.io/algo/troubleshooting.html"
292+
]
293+
}
294+
295+
TASK [Fail the installation] *****************************************************************************************
296+
```
297+
This error is usually encountered when using the local install option and `localhost` is provided in answer to this question, which is expecting an IP address or domain name of your server:
298+
```
299+
Enter the public IP address or domain name of your server: (IMPORTANT! This is used to verify the certificate)
300+
[localhost]
301+
:
302+
```
303+
304+
You should remove the files in /etc/wireguard/ and configs/ as follows:
305+
```ssh
306+
sudo rm -rf /etc/wireguard/*
307+
rm -rf configs/*
308+
```
309+
310+
And then immediately re-run `./algo` and provide a domain name or IP address in response to the question referenced above.
311+
276312
### Wireguard: Unable to find 'configs/...' in expected paths
277313

278314
You tried to run Algo and you received an error like this one:
@@ -283,10 +319,11 @@ TASK [wireguard : Generate public keys] ****************************************
283319
284320
fatal: [localhost]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: configs/xxx.xxx.xxx.xxx/wireguard//private/dan"}
285321
```
286-
This error is usually hit when using the local install option on a server that isn't Ubuntu 18.04 or later. You should upgrade your server to Ubuntu 18.04 or later. If this doesn't work, try removing `*.lock` files at /etc/wireguard/ as follows:
322+
This error is usually hit when using the local install option on a server that isn't Ubuntu 18.04 or later. You should upgrade your server to Ubuntu 18.04 or later. If this doesn't work, try removing files in /etc/wireguard/ and the configs directories as follows:
287323

288324
```ssh
289-
sudo rm -rf /etc/wireguard/*.lock
325+
sudo rm -rf /etc/wireguard/*
326+
rm -rf configs/*
290327
```
291328
Then immediately re-run `./algo`.
292329

0 commit comments

Comments
 (0)