User Servers ref when relevant instead of User Devices (#770)
|
Before Width: | Height: | Size: 178 KiB After Width: | Height: | Size: 226 KiB |
|
Before Width: | Height: | Size: 209 KiB After Width: | Height: | Size: 226 KiB |
|
Before Width: | Height: | Size: 70 KiB After Width: | Height: | Size: 226 KiB |
|
Before Width: | Height: | Size: 121 KiB After Width: | Height: | Size: 74 KiB |
|
Before Width: | Height: | Size: 216 KiB After Width: | Height: | Size: 433 KiB |
@@ -80,7 +80,7 @@ ls /dev/net
|
|||||||
Before we install NetBird, we are going to want to generate a one-off setup key to use with our LXC installation. While [NetBird's documentation offers comprehensive guidance on this process](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys), let's quickly review the essential steps:
|
Before we install NetBird, we are going to want to generate a one-off setup key to use with our LXC installation. While [NetBird's documentation offers comprehensive guidance on this process](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys), let's quickly review the essential steps:
|
||||||
|
|
||||||
- Access your [NetBird dashboard](https://app.netbird.io/)
|
- Access your [NetBird dashboard](https://app.netbird.io/)
|
||||||
- Navigate to `Peers` → `Setup Keys`
|
- Navigate to `Settings` → `Setup Keys`
|
||||||
- Click the `Create Setup Key` button on the right
|
- Click the `Create Setup Key` button on the right
|
||||||
- Name your key (e.g., "ProxmoxLXC")
|
- Name your key (e.g., "ProxmoxLXC")
|
||||||
- Set an expiration date (recommended for enhanced security)
|
- Set an expiration date (recommended for enhanced security)
|
||||||
|
|||||||
@@ -45,7 +45,7 @@ The first step in this process is [creating a NetBird setup key](/manage/peers/r
|
|||||||
To create an appropriate setup key for this use case:
|
To create an appropriate setup key for this use case:
|
||||||
|
|
||||||
1. Log in to your NetBird dashboard.
|
1. Log in to your NetBird dashboard.
|
||||||
2. Navigate to `Peers` → `Setup Keys`.
|
2. Navigate to `Settings` → `Setup Keys`.
|
||||||
3. Click on `Add Setup Key` to create a new key.
|
3. Click on `Add Setup Key` to create a new key.
|
||||||
4. Provide a descriptive name for your key.
|
4. Provide a descriptive name for your key.
|
||||||
5. Enable the `Reusable` option to allow multiple pods to use the same key.
|
5. Enable the `Reusable` option to allow multiple pods to use the same key.
|
||||||
|
|||||||
@@ -41,7 +41,7 @@ Login to NetBird and navigate to `Peers`. Ensure you see your local peer connect
|
|||||||
|
|
||||||
To add your remote web server to NetBird's peer network, first you need to generate a setup key:
|
To add your remote web server to NetBird's peer network, first you need to generate a setup key:
|
||||||
|
|
||||||
* Navigate to `Peers` → `Setup Keys` in the left menu
|
* Navigate to `Settings` → `Setup Keys` in the left menu
|
||||||
* Click `Create Setup Key`
|
* Click `Create Setup Key`
|
||||||
* Configure the key by assigning it a descriptive name (e.g., "Remote Web Server"), setting an expiration date, and defining auto-assigned groups (if required). Read the documentation for [detailed setup key configuration](/manage/peers/register-machines-using-setup-keys).
|
* Configure the key by assigning it a descriptive name (e.g., "Remote Web Server"), setting an expiration date, and defining auto-assigned groups (if required). Read the documentation for [detailed setup key configuration](/manage/peers/register-machines-using-setup-keys).
|
||||||
* Copy the generated key to a secure location as you'll need it shortly
|
* Copy the generated key to a secure location as you'll need it shortly
|
||||||
|
|||||||
@@ -41,7 +41,7 @@ This process will demonstrate how Setup Keys simplify and secure the addition of
|
|||||||
To seamlessly integrate virtual machines or Docker containers into your NetBird network, you'll start by creating a setup key. While [NetBird's documentation offers comprehensive guidance on this process](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys), let's quickly review the essential steps:
|
To seamlessly integrate virtual machines or Docker containers into your NetBird network, you'll start by creating a setup key. While [NetBird's documentation offers comprehensive guidance on this process](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys), let's quickly review the essential steps:
|
||||||
|
|
||||||
* Access your NetBird dashboard
|
* Access your NetBird dashboard
|
||||||
* Navigate to `Peers` → `Setup Keys`
|
* Navigate to `Settings` → `Setup Keys`
|
||||||
* Click the `Create Setup Key` button on the right
|
* Click the `Create Setup Key` button on the right
|
||||||
* Name your key (e.g., "VM-Docker-Demo")
|
* Name your key (e.g., "VM-Docker-Demo")
|
||||||
* Set an expiration date (recommended for enhanced security)
|
* Set an expiration date (recommended for enhanced security)
|
||||||
|
|||||||
@@ -1,77 +1,74 @@
|
|||||||
|
# Automate Deployments and Onboard Machines at Scale with Setup Keys
|
||||||
|
|
||||||
# Use setup keys to run automated deployments and add machines to your network at scale
|
A setup key is a pre-authentication token used to register new machines in your network.
|
||||||
|
On a machine's first run, it associates that machine with your account.
|
||||||
|
|
||||||
Setup key is a pre-authentication key that allows to register new machines in your network.
|
## Registering Machines Using Setup Keys
|
||||||
It simply associates a machine with an account on a first run.
|
|
||||||
|
|
||||||
## Related Video Content
|
Pass the setup key to the ```netbird up``` command to authenticate a machine without interactive SSO login.
|
||||||
For a comprehensive guide, part of our "Getting started with NetBird" video specifically covers setup keys:
|
This unlocks automated, unattended deployments and integrates cleanly with infrastructure-as-code tools such as Ansible, CloudFormation, and Terraform.
|
||||||
<YouTube videoId="JRCZy4rLi-c" start={175} />
|
|
||||||
|
|
||||||
The setup key can be provided as a parameter to the ```netbird up``` command.
|
```bash
|
||||||
This makes it possible to run automated deployments with infrastructure-as-code software like Ansible, Cloudformation or Terraform.
|
netbird up --setup-key <SETUP KEY>
|
||||||
|
|
||||||
```bash {{ title: 'Starting NetBird Client' }}
|
|
||||||
sudo netbird up --setup-key <SETUP KEY>
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Types of setup keys
|
## Types of Setup Keys
|
||||||
|
|
||||||
There are 2 types of setup keys:
|
There are two types of setup keys:
|
||||||
* **One-off key**. This type of key can be used only once to authenticate a machine.
|
* **One-off key** — can be used only once to authenticate a single machine.
|
||||||
* **Reusable key**. This type of key can be used multiple times to authenticate machines.
|
* **Reusable key** — can be used multiple times to authenticate a configurable number of machines.
|
||||||
|
|
||||||
## Ephemeral peers
|
## Ephemeral Peers
|
||||||
|
|
||||||
You can create a setup key with the ephemeral peers option enabled.
|
You can create a setup key with the ephemeral peers option enabled.
|
||||||
Peers added with this key that later become offline for over 10 minutes will be removed automatically from the NetBird system.
|
Peers registered with this key are automatically removed from NetBird after staying offline for more than 10 minutes.
|
||||||
|
|
||||||
This is useful when you want to add containers or auto scaling instances to your network.
|
This is useful for short-lived workloads such as containers or autoscaling instances.
|
||||||
|
|
||||||
## Using setup keys
|
## Managing Setup Keys
|
||||||
|
|
||||||
Setup keys are available in the NetBird Management Dashboard under `Peers` → `Setup Keys` [https://app.netbird.io/setup-keys](https://app.netbird.io/setup-keys).
|
Setup keys are available in the NetBird Management Dashboard under `Settings` → `Setup Keys`.
|
||||||
You can easily add new or revoke keys.
|
Use [this page](https://app.netbird.io/settings?tab=setup-keys) to view and manage your setup keys.
|
||||||
|
From there, you can add new keys or revoke existing ones.
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<img src="/docs-static/img/manage/peers/register-machines-using-setup-keys/setup-keys.png" alt="high-level-dia" className="imagewrapper-big"/>
|
<img src="/docs-static/img/manage/peers/register-machines-using-setup-keys/setup-keys.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<Note>
|
<Note>
|
||||||
When revoking a key, all machines authenticated with this key will remain connected to the network. The same logic applies when the key expires.
|
When you revoke a key, all machines already authenticated with it remain connected to the network. The same applies when the key expires.
|
||||||
</Note>
|
</Note>
|
||||||
|
|
||||||
## Expiration
|
## Expiration
|
||||||
|
|
||||||
You can set expiration when creating a key. When expired, the setup key can't be used anymore.
|
You can set an expiration date when creating a key. Once expired, the key can no longer be used.
|
||||||
|
|
||||||
## Usage limit
|
## Usage Limit
|
||||||
|
|
||||||
By default, every reusable key has unlimited usage.
|
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.
|
We recommend limiting the number of times a key can be used — for example, set it to 30 if you only need to enroll 30 machines.
|
||||||
|
|
||||||
## Allow Extra DNS Labels
|
## Allow Extra DNS Labels
|
||||||
|
|
||||||
You can create a setup key with the **Allow Extra DNS Labels** option enabled.
|
You can create a setup key with the **Allow Extra DNS Labels** option enabled.
|
||||||
When enabled, peers registered with this key can set additional DNS names using the `--extra-dns-labels` flag. Other peers in the network can then reach them by these names.
|
When enabled, peers registered with this key can set additional DNS names using the `--extra-dns-labels` flag, so other peers in the network can reach them by those names.
|
||||||
|
|
||||||
If multiple peers share the same label, they form a DNS round-robin group for that label, distributing queries across all of them.
|
If multiple peers share the same label, they form a DNS round-robin group for that label, with queries distributed across all of them.
|
||||||
|
|
||||||
See [Extra DNS Labels](/manage/dns/extra-dns-labels) for full details, including wildcard labels and usage examples.
|
See [Extra DNS Labels](/manage/dns/extra-dns-labels) for full details, including wildcard labels and usage examples.
|
||||||
|
|
||||||
## Peer Auto-grouping
|
## Peer Auto-Grouping
|
||||||
|
|
||||||
|
|
||||||
NetBird offers a powerful [access control feature](/manage/access-control/manage-network-access) that allows easy access management of your resources.
|
NetBird offers a powerful [access control feature](/manage/access-control/manage-network-access) for managing access to 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.
|
In a typical setup, you create multiple groups of peers and define access rules that determine which groups can reach each other.
|
||||||
Adding peers to groups might become time-consuming in large networks with dozens of machines.
|
Adding peers to groups manually can become time-consuming in large networks with dozens of machines.
|
||||||
|
|
||||||
Starting NetBird [v0.9.2](https://github.com/netbirdio/netbird/releases), when creating or updating a setup key,
|
Starting with NetBird [v0.9.2](https://github.com/netbirdio/netbird/releases), you can specify a list of auto-assign groups 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
|
Every peer registered with this key is automatically added to those groups, and all access control rules for those groups apply automatically.
|
||||||
to these groups. All the access control rules enabled for these groups will apply automatically.
|
|
||||||
|
|
||||||
To add `Auto-assign groups`, open `Peers` → `Setup Keys` and create or update any existing setup key.
|
To configure `Auto-assign groups`, open `Settings` → `Setup Keys` and create or update a setup key.
|
||||||
Then use this key to enroll new machine.
|
Then use this key to enroll new machines.
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<img src="/docs-static/img/manage/peers/register-machines-using-setup-keys/netbird-peer-auto-tagging-newkey.png" alt="high-level-dia" className="imagewrapper"/>
|
<img src="/docs-static/img/manage/peers/register-machines-using-setup-keys/netbird-peer-auto-tagging-newkey.png" alt="high-level-dia" className="imagewrapper"/>
|
||||||
@@ -81,17 +78,17 @@ Then use this key to enroll new machine.
|
|||||||
Auto-assign groups will apply only to newly registered machines.
|
Auto-assign groups will apply only to newly registered machines.
|
||||||
</Note>
|
</Note>
|
||||||
|
|
||||||
## Create setup key
|
## Create Setup Key
|
||||||
|
|
||||||
Go to `Peers` → `Setup Keys` and click the `Create Setup Key` button
|
Go to `Settings` → `Setup Keys` and click the `Create Setup Key` button.
|
||||||
In the opened popup, give your new key an easily identifiable name, choose type, set usage limit, and assign auto groups.
|
In the dialog that opens, give your new key a recognizable name, choose its type, set a 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.
|
The defaults are suitable for most cases. For security reasons, we recommend using one-off keys.
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<img src="/docs-static/img/manage/peers/register-machines-using-setup-keys/add-setup-key.png" alt="high-level-dia" className="imagewrapper"/>
|
<img src="/docs-static/img/manage/peers/register-machines-using-setup-keys/add-setup-key.png" alt="high-level-dia" className="imagewrapper"/>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
After your key has been successfully created, copy and store it in a secure location.
|
Once the key has been created, copy it and store it in a secure location.
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<img src="/docs-static/img/manage/peers/register-machines-using-setup-keys/setup-key-created.png" alt="high-level-dia" className="imagewrapper"/>
|
<img src="/docs-static/img/manage/peers/register-machines-using-setup-keys/setup-key-created.png" alt="high-level-dia" className="imagewrapper"/>
|
||||||
|
|||||||
@@ -102,7 +102,7 @@ One of the simplest ways of running NetBird client application is to use a pre-b
|
|||||||
|
|
||||||
You would need to obtain a [setup key](/manage/peers/register-machines-using-setup-keys) to associate NetBird client with your account.
|
You would need to obtain a [setup key](/manage/peers/register-machines-using-setup-keys) to associate NetBird client with your account.
|
||||||
|
|
||||||
The setup key could be found in the NetBird Management dashboard under `Peers` → `Setup Keys` - [https://app.netbird.io/setup-keys](https://app.netbird.io/setup-keys).
|
The setup key could be found in the NetBird Management dashboard under `Settings` → `Setup Keys` - [https://app.netbird.io/setup-keys](https://app.netbird.io/setup-keys).
|
||||||
|
|
||||||
Set the ```NB_SETUP_KEY``` environment variable and run the command.
|
Set the ```NB_SETUP_KEY``` environment variable and run the command.
|
||||||
|
|
||||||
|
|||||||
@@ -20,7 +20,7 @@ from hosts running on a Hetzner without exposing them to the public internet.
|
|||||||
|
|
||||||
## Step-by-Step guide
|
## Step-by-Step guide
|
||||||
### Step 1: Create a setup key
|
### Step 1: Create a setup key
|
||||||
Navigate to `Peers` → `Setup Keys` in the NetBird management dashboard and click on "Create setup key".
|
Navigate to `Settings` → `Setup Keys` in the NetBird management dashboard and click on "Create setup key".
|
||||||
|
|
||||||
Choose a name, e.g. `Kubernetes routing peers`, mark the key as `reusable` and enable `Ephemeral peers`. This option is
|
Choose a name, e.g. `Kubernetes routing peers`, mark the key as `reusable` and enable `Ephemeral peers`. This option is
|
||||||
ideal for stateless workloads like containers, where peers that are offline for over 10 minutes are automatically removed.
|
ideal for stateless workloads like containers, where peers that are offline for over 10 minutes are automatically removed.
|
||||||
|
|||||||