Guide: Debugging with Nebula SSH commands #119
Conversation
✅ Deploy Preview for nebula-docs-dn ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
This seems like a fine start, but it's largely repeating what already exists on the sshd page. I do think the list of available commands is useful. That being said, it would be even more useful if you could give a little extra color about them, or provide insight into how this tool could be useful.
For example, a note I'm aware of that were shared in recent team meetings: query-lighthouse <some-ip> will return an empty result set initially if the host is not connected, but it will trigger a background request to the Lighthouse. Meaning, you need to run it twice to actually get a result.
Or another thing I know if is that change-remote has only a temporary effect: after a period of time, Nebula will "revert" to its preferred remote (i.e. based on the rules here: https://nebula.defined.net/docs/config/preferred-ranges/#how-nebula-orders-underlay-ip-addresses-it-learns-about)
|
|
||
| First you need to configure the [`sshd`](https://nebula.defined.net/docs/config/sshd/) section on the host you want to debug. | ||
|
|
||
| Please follow the instructions here: https://nebula.defined.net/docs/config/sshd/. |
There was a problem hiding this comment.
This and the line just above it seem to be stating the same thing. Maybe you can combine them into a single sentence?
"First, update the config of the host you'd like to debug using the instructions found in the [sshd] section of the docs." for example?
The example config below is also copy and pasted from that page. Do you think that's necessary? Maybe it would be better to use this guide as a chance to give more detailed instructions on configuration, rather than copying what exists on the sshd page? e.g. You could walk through how to generate a host key, and an SSH public / private keypair for authentication, in case they don't already have one.
| pretty prints json, assumes -json | ||
| ``` | ||
|
|
||
| Now you can debug your nebula installation, querying things like your hostmap: |
There was a problem hiding this comment.
nit / stye thing, but just because it's "Now you can debug..." I'd consider moving this up before mentioning help. Then you can have the help bit as the note this guide ends on.
| a background request to the Lighthouse. Meaning, you need to run it twice to actually get a result. | ||
|
|
||
| `change-remote` has only a temporary effect: after a period of time, Nebula will "revert" to its preferred remote (i.e. | ||
| based on the rules here: |
There was a problem hiding this comment.
Maybe instead of the (i.e.) thing just link "preferred remote"?
| In this case `steeeeve` and `[ssh public key string]` should be the values for the user you want to enable access for | ||
| debugging. You must add the correct public ssh key for the users you wish to access the ssh server with. If you don't | ||
| already have an SSH key for the host you want to access from, follow this guide by GitHub: | ||
| [Generating a new SSH key and adding it to the ssh-agent](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). |
There was a problem hiding this comment.
nit, but i don't think the ssh-agent part is necessary / relevant. could link https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key
and use "Generating a new SSH key" as text instead.
There was a problem hiding this comment.
Why isn't it relevant? This is for the host that is accessing the nebula node, so you'd want it in your ssh-agent, I agree it's not required for the nebula config side of things.
There was a problem hiding this comment.
It's not necessary to add an SSH key to ssh-agent in order to use it. By default, SSH will use identities stored in ~/.ssh without adding it to the agent.
Putting it in the agent is mostly useful to avoid repeatedly entering a password, or unlocking a tpm, if that's where you've stored your key.
So it's an optional step, that's not relevant to getting an SSH debug server connected, IMO.
There was a problem hiding this comment.
Just a nit though, feel free to land as-is.
| Set the `listen` property to localhost for local debugging or to your nebula IP to enable access over the nebula overlay | ||
| network. | ||
|
|
||
| Next, restart nebula and ssh via `ssh 127.0.0.1 -p 2222` for example. |
…aveats about commands # Conflicts: # docs/guides/debug-ssh-commands/index.mdx
jasikpark
force-pushed
the
04-04-guide_debugging_with_nebula_ssh_commands
branch
from
249d92e to
2fc6395
Compare
jasikpark
force-pushed
the
04-04-guide_debugging_with_nebula_ssh_commands
branch
from
108005f to
1ca8d22
Compare
Deploy Preview: https://deploy-preview-119--nebula-docs-dn.netlify.app/docs/guides/debug-ssh-commands/
Fixes #115
This guide attempts to describe how to setup and use the sshd debugability features of nebula.
I considered adding a section describing each command, but I think it'll be more useful to simply update the help messages for each command to be more useful.
Ref: slackhq/nebula#1109