Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a Tips and Tricks page #140

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add a Tips and Tricks page #140

wants to merge 6 commits into from

Conversation

jasikpark
Copy link
Collaborator

@jasikpark jasikpark commented Jun 7, 2024

This incorporates a bunch of little bits of missing info suggested by a user of nebula, LMK if there's someplace obvious where these should go elsewhere

Copy link

netlify bot commented Jun 7, 2024

Deploy Preview for nebula-docs-dn ready!

Name Link
🔨 Latest commit fefead7
🔍 Latest deploy log https://app.netlify.com/sites/nebula-docs-dn/deploys/6668618fd7d7c800087122a2
😎 Deploy Preview https://deploy-preview-140--nebula-docs-dn.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@jasikpark jasikpark marked this pull request as ready for review June 7, 2024 18:34
@johnmaguire
Copy link
Member

johnmaguire commented Aug 27, 2024

Some of this information might be useful to users, but I'm not sure when in a user's Nebula journey they will find the "Tips n Tricks" page, or what they are looking for to get there. How are you envisioning users will find and use this information? Personally, I would not merge this change.

Make sure you get your preferred overlay network correct, because you will have to re-cert every host if you want to

This is true, but probably is a better note for the getting started guide.

Nebula subnets must be contiguous, you cannot have a 10.0.0.0/8 and 172.16.0.0/16 in the same cert, if you want
multiple separate subnets it requires multiple Nebula networks with incompatible certs.

I think this is also a fact useful only during setup. And, while true, I think it's also obvious from the fact that nebula-cert offers no way to specify multiple networks. I'm not sure this is useful to explicitly mention. It may also change with IPv6 support. Or this could be in an FAQ: "Q: How can I connect hosts using multiple Nebula network spaces? A: Run a separate Nebula instance for each network space."

Nebula has multiple options for encryption key material: 25519 or p256. It's required that you choose one and only
one for your network, as different encryption algorithims do not interopt.

True and maybe worth calling out during first time setup. That being said, most users won't use P256 at all, so I'm not sure it's even worth mentioning. (This is something you'd really only think about if you're trying to achieve FIPS compliance - I think we consciously don't document this too heavily as we don't want to make any guarantees or else I'd say it deserves its own page. It's something Slack is using in some environments.)

What happens when when a nebula host's cert expires? It continues running, but handshakes with other hosts will start to
fail.

Depends on pki.disconnect_invalid setting and Nebula version. I'm not sure I would include this. I think it's already documented elsewhere.

Nebula doesn't use X509, it has its own custom-built certificate format defined via protobuffs:
https://github.com/slackhq/nebula/blob/master/cert/cert.proto. The encryption algorithm uses the well tested Noise
protocol.

This is also true but isn't really a tip or a trick - it's a technical detail. Maybe it makes more sense for a "High-Level Overview" style documentation page. The part about using the Noise protocol is already listed under "Technical Details" on the main docs page. We don't explicitly mention that it's not X.509, and I am "meh" on doing so especially without explaining why not.

Also the cert format will likely change with IPv6 to be ASN.1-based instead of protobuf-based.

Nebula is a peer-to-peer VPN, meaning by default it only routes to hosts
that have the software installed with an associated cert. If you want Nebula to function like
OpenVPN, set up unsafe routes.

True, but perhaps better suited for a high level overview of Nebula. (e.g. part of this description - https://nebula.defined.net/docs/)

Consider using some/all of 100.64.0.0/10 as your overlay network, its_free_real_estate.jpg.

CGNAT does tend to be a decent choice for many users, but not all. For example, people who also use Tailscale may experience conflicts this way. I think an "Network Space Considerations" page would make more sense than this contextless tidbit.

@IanVS IanVS removed their request for review September 9, 2024 13:06
@johnmaguire johnmaguire removed their request for review October 2, 2024 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants