toolshed/docs.coopcloud.tech
3
1
Fork 21
Code Issues 4 Pull Requests 1 Packages Releases Activity

docs: new ssh consolidation changes
All checks were successful
continuous-integration/drone/push Build is passing
Details

Browse Source 
See coop-cloud/abra#255
This commit is contained in:
decentral1se
2023-02-01 08:16:58 +01:00
parent a71e3397f8
commit 1d77ae2392
4 changed files with 14 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/abra/trouble.md
View File

@ -8,51 +8,21 @@ You can use [this issue tracker](https://git.coopcloud.tech/coop-cloud/organisin
## SSH connection issues?
`abra` tries its best to learn from your system configuration or command-line input what the correct SSH connection details are for a given server. This doesn't always work out. Here are some things to try to fix it.
When you run `abra server add <host>`, `abra` will read from your `~/.ssh/config` and try to match a `Host <host>` entry. If you can `ssh <host>` then you should be able to `abra server add <host>`.
First, ensure that you can `ssh <my-server>` and things work. If you can't SSH to your server then neither can `abra`. If you have a password protected SSH key, then you'll need to make sure your `ssh-agent` is running and you've added your SSH key part:
For example, if you do `abra server add example.com`, you should have a matching entry that looks like this:
```
eval $(ssh-agent -k)
ssh-add ~/.ssh/<my-secret-key-part>
ssh-add -L # validate loaded keys
Host example.com
Hostname example.com
User exampleUser
Port 12345
IdentityFile ~/.ssh/example@somewhere
```
The first thing `abra` will check for is the connection details listed in `abra server ls`. Check those details are correct. If you haven't managed to `abra server add` your server yet, then no details will appear in that list. You may need to take a look at [this entry](/abra/trouble/#abra-server-ls-shows-the-wrong-details) to clean up old values depending on your situation.
`abra` will then try to read your `~/.ssh/config` entries and match the server domain against a `Host` entry. So, if you do `ssh myserver.com` and you have:
```
Host myserver.com
Hostname myserver.com
User myuser
Port 222
IdentityFile ~/.ssh/my@myserver.com
```
Then `abra` should have all it needs to build a working SSH connection. You can validate this by passing `-d/--debug` to your commands.
However, sometimes, you use an alias in your SSH configuration, say:
```
Host mys
...
```
So that you can simply type `ssh mys`. `abra` won't be able to match against those entries to discover connection details. You can use aliases to remedy this:
```
Host mys, myserver.com
...
```
`abra` will try to read the relevant `IdentityFile` entry from your `~/.ssh/config` but if it can't make a match, it will rely on your key being added to the `ssh-agent`.
Due to a limitation in our implementation, `abra` uses 2 methods of making SSH connections, the main `abra` -> `remote docker` connection using `/usr/bin/ssh` which can seamlessly pick up loaded SSH keys. However, for SSH host key checking, `abra` uses an SSH library & Golang SSH internals. We're working on resolving this to a single implementation but it is tricky work.
## "abra server ls" shows the wrong details?
You can use `abra server rm` to remove the incorrect details. Make sure to take a backup of your `~/.abra/servers/<domain>` first. You can then try to re-create by using `abra server add ...` again, making sure to take care if you need to use `<user> <port>`, see `abra server add -h` for more help on this.
You can use `abra server rm` to remove the incorrect details. Make sure to take a backup of your `~/.abra/servers/<domain>` first. You can then try to re-create by using `abra server add ...` again.
However, if you have Docker installed on the same machine you have `abra`, then there might be some confusion. If you run `docker context ls` you'll see that Docker uses context connection strings also. `abra` simply uses this approach. Sometimes, your Docker defined context details & your `abra` context details can get out of sync. You can use `docker context rm` to resolve this.
@ -62,7 +32,7 @@ If you need to create a new context from Docker, you can do:
docker context create <domain> --docker "host=ssh://<user>@<domain>:<port>"
```
(This is what we used to before we wrote `abra` to make it more convenient.)
This is what we used to before we wrote `abra` to make it more convenient.
## Command-line flag handling is weird?
@ -104,10 +74,6 @@ ln -s ~/.abra/bash-src/abra ~/.local/bin/babra
This appears to be an upstream issue for which we can't do much in `abra` to solve. See [`coop-cloud/organising#420`](https://git.coopcloud.tech/coop-cloud/organising/issues/420) for more info. The work-around is to leave more time in between undeploy/deploy operations so the runtime can catch up.
## I am seeing very weird `lookup <domain> on <ip>: write udp <ip>: write: operation not permitted` errors
You should turn off your VPN. `abra` has trouble dealing with it right now. We welcome change sets to make it work though!
## Caller path in debug stacktrace doesn't exist
Debug stacktrace currently begins with `/drone/` due to CI. Remove the initial `/drone/` and the path is relative to the abra project root.