Use setup keys to run automated deployments and add machines to your network at scale
Setup key is a pre-authentication key that allows to register new machines in your network. It simply associates a machine with an account on a first run.
The setup key can be provided as a parameter to the netbird up command.
This makes it possible to run automated deployments with infrastructure-as-code software like Ansible, Cloudformation or Terraform.
Starting NetBird Client
sudo netbird up --setup-key <SETUP KEY>
Types of setup seys
There are 2 types of setup keys:
- One-off key. This type of key can be used only once to authenticate a machine.
- Reusable key. This type of key can be used multiple times to authenticate machines.
Ephemeral peers
You can create a setup key with the ephemeral peers option enabled. Peers that are offline for over 10 minutes will be removed automatically.
Using setup keys
Setup keys are available in the NetBird Management Dashboard under the Setup Keys tab https://app.netbird.io/setup-keys.
You can easily add new or revoke keys.
When revoking a key, all machines authenticated with this key will remain connected to the network. The same logic applies when the key expires.
Expiration
You can set expiration when creating a key. When expired, the setup key can't be used anymore.
Usage limit
By default, every reusable key has unlimited usage. We recommend limiting the number of times the key can be used, e.g., set it to 30 if you need to enroll only 30 machines.
Peer Auto-grouping
NetBird offers a powerful access control feature that allows easy access management of your resources. In a basic scenario, you would create multiple groups of peers and create access rules to define what groups can access each other. Adding peers to groups might become time-consuming in large networks with dozens of machines.
Starting NetBird v0.9.2, when creating or updating a setup key, it is possible to specify a list of auto-assign groups. Every peer registered with this key will be automatically added to these groups. All the access control rules enabled for these groups will apply automatically.
To add Auto-assign groups, open the Setup Keys tab and create or update any existing setup key.
Then use this key to enroll new machine.
Auto-assign groups will apply only to newly registered machines.
Create setup key
Click the Add Key button in the `Setup Keys'.
In the opened popup, give your new key an easily identifiable name, choose type, set usage limit, and assign auto groups.
The defaults should be suitable for most of the cases. We recommend using one-off keys for security reasons.
After your key has been successfully created, copy and store it in a secure location.
