Difference between -ips and -subnets in certificate creation and signing

[ZelnickB]

According to the help text for the nebula-cert ca command, the options -ips and -subnets are used as follows:

-ips string
  Optional: comma separated list of ipv4 address and network in CIDR notation. This will limit which ipv4 addresses and networks subordinate certs can use for ip addresses
-subnets string
  Optional: comma separated list of ipv4 address and network in CIDR notation. This will limit which ipv4 addresses and networks subordinate certs can use in subnets

Likewise, according to the help text for the nebula-cert sign command, the options -ip and -subnets are used as follows:

-ip string
  Required: ipv4 address and network in CIDR notation to assign the cert
-subnets string
  Optional: comma separated list of ipv4 address and network in CIDR notation. Subnets this cert can serve for

I'm confused about the difference between the options in these pairs and what each one does:

1. If -ips and -ip both support CIDR notation, which is used to denote subnets, then what is the point of the -subnets option?
2. Can someone provide examples of when it would be appropriate to use each of the options and when (if ever) it would be appropriate to use the two options together?
3. If I want to allow a device to use only one IP address, should I sign the device's certificate with -ip 10.12.34.56/32, and if I want to allow a device to listen on more than one IP address, should I sign the device's certificate with, for example, -ip 10.12.34.56/30 (for two IPs)?

I'm also wondering if I need to sign all device certificates with the root CA or if I can create different intermediate CAs to sign, for example, different subnets.

[johnmaguire]

Hi @ZelnickB -

In a host certificate, -ip is the node's IP and the CIDR within which it resides. For example, 192.168.100.1/24 will have IP 192.168.100.1 and can talk to the 192.168.100.0/24 subnet. You always need to pass this when creating a host certificate.

In a host certificate, -subnets allows a host to act as a router for the unsafe_routes feature. It can only route traffic to subnets defined in its certificate. You only need to pass this if you plan on routing traffic through a host to computers which cannot run Nebula. (For example, printers. This is different than relays which routes traffic between two Nebula nodes when direct connectivity cannot be achieved and doesn't require any configuration in the host certificate.)

For the CA, -ips restricts what you can pass for -ip and -subnets restricts what you can pass for -subnets when signing host certificates. For small networks, you'll likely have a single CA where -ips is your entire network CIDR. You would not pass any value for -subnets if you don't need unsafe_routes. In a larger organization with multiple teams, you might have multiple CAs with the ability to assign to different sub-CIDRs of your network,

If I want to allow a device to use only one IP address, should I sign the device's certificate with -ip 10.12.34.56/32, and if I want to allow a device to listen on more than one IP address, should I sign the device's certificate with, for example, -ip 10.12.34.56/31 (for two IPs)?

AFAIK, it is not possible to have two Nebula IP addresses on the same network.

I'm also wondering if I need to sign all device certificates with the root CA or if I can create different intermediate CAs to sign, for example, different subnets.

Nebula has no concept of intermediate certs. You can create multiple root CAs and add each of them in a host's CA bundle (pki.ca).

[ZelnickB]

Thanks for the explanation! Could you perhaps clarify this in the command help text? I think that it would be helpful.

[johnmaguire]

Hi @ZelnickB - if you think you can clarify the text, perhaps you'd be willing to submit a PR? :)

Otherwise, I generally recommend checking out the Nebula docs which offer far more info than we're able to stuff in that one-line description. :)

[ZelnickB]

If I can think of a better (and succinct) way of phrasing it, I'll certainly open a PR!