sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-21 01:46:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

restructure how-to

Browse Source
This commit is contained in:
Pascal Fischer
2023-05-09 18:24:11 +02:00
parent f8b501cd6f
commit 722435a9a4
22 changed files with 869 additions and 831 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
src/pages/docs/how-to/access-control.mdx Normal file
View File

@@ -0,0 +1,119 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern/>
# Access Control
NetBird allows administrators to restrict access to resources (peers) by creating access rules and
defining what peer groups are permitted to establish connections with one another.
<div class="videowrapper">
<iframe src="https://www.youtube.com/embed/WvbkACjdsHA" allow="fullscreen;" width="800" height="500" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}></iframe>
</div>
## Introduction
A NetBird account comes with a `Default` rule that allows all peers of the account to connect to each other forming a full mesh network.
In most cases, this is the desired state for a small network or network that has low-security requirements.
When you need to restrict access to certain resources that belong to specific users or services within your organization, you can create rules that dictate who can access what.
Access control rules make use of groups to control connections between peers; these groups can be added as `Source` or `Destination` of a rule and will be evaluated when the Management service distributes the list of peers across your network.
## Concepts
### Groups
A NetBird group works and follows a similar concept to tags in other platforms; they are easily created and can be associated with peers and used in rules to control traffic within your network.
Some characteristics of groups:
- They are unique.
- One group can have multiple peers.
- Peers can belong to multiple groups.
- Rules can have multiple groups in their `Source` and `Destination` lists.
- They are created in the `Access Control` or `Peers` tabs.
- They can only be deleted via API.
- There is a default group called `All`.
<Note>
You can assign groups automatically with the [peer auto-grouping feature](/overview/setup-keys#peer-auto-grouping).
</Note>
### The All Group
The `All` group is a default group to which every peer in your network is automatically added to. This group cannot be modified or deleted.
### Rules
Rules are lists of `Source` and `Destination` groups of peers that can communicate with each other.
Rules are processed when the Management service distributes a network map to all peers of your account. Because you can only create ALLOW rules, there is no processing
order or priority, so the decision to distribute peer information is based on its association with a group belonging to an existing rule.
Currently, the communication between lists of groups in source and destination lists of a rule is bidirectional,
meaning that destinations can also initiate connections to a group of peers listed in the source field of the rule.
The behavior of a network without any rules is to deny traffic. No peers will be able to communicate with each other.
<Note>
If you need to allow peers from the same group to communicate with each other, just add the same group to the `Source` and `Destination` lists.
</Note>
### The Default Rule
The `Default` rule is created when you first create your account. This rule is very permissive because it allows communication between all peers in your network.
It uses the [`All`](#the-all-group) group as a source and destination. If you want to have better
control over your network, it is recommended that you delete this rule and create more restricted rules with custom groups.
<Note>
If you need to restrict communication within your network, you can create new rules and use different groups, and then remove the default rule to achieve the desired behavior.
</Note>
### Multiple Mesh Networks
As mentioned above, rules are bidirectional, which is basically the control of how your network will behave as a mesh network.
There is a `Default` rule, which configures a Default mesh connection between all peers of your network. With rules, you can define smaller mesh networks by grouping peers and adding these groups to `Source` and `Destination` lists.
## Managing Rules
### Creating Rules
After accessing the `Access Control` tab, you can click on the `Add Rule` button to create a new rule. This will open a screen
where you need to name the rule, set its status, and add groups to the source and destination lists.
<p align="center">
<img src="/img/overview/create-rule.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
If required, you can create new groups by simply entering new names in the input box for either source or destination lists.
<p align="center">
<img src="/img/overview/create-group-in-rule.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
Once you are done configuring the rule, click the `Create` button to save it. You will then see your new rule in the table.
<p align="center">
<img src="/img/overview/new-rule-list.png" alt="high-level-dia" width="600" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
Because of its permissiveness, new rules will take effect once you remove the `Default` rule.
</Note>
### Adding peers to groups
If you create a new group when defining a rule, you will need to associate peers with this group.
You can do it by accessing the `Peers` tab and clicking the `Groups` column of any peer you want to associate with the new group.
<p align="center">
<img src="/img/overview/associate-peer-groups.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
You can assign groups automatically with the [peer auto-grouping feature](/overview/setup-keys#peer-auto-grouping).
</Note>
### Updating Rules
To update a rule, you can click on the rule's `Name` or on either `Sources` and `Destinations` columns. You could also click the menu
button of a rule and select `View`. This will open the same screen where you can update rule groups, description, or status.
### Disabling Rules
To disable a rule, you should follow the steps of [updating rules](#updating-rules) changing its status, and then click on Save.
### Deleting Rules
To delete a rule, you should click on the rule's menu and choose `Delete`. A confirmation window will pop up.
<p align="center">
<img src="/img/overview/delete-rule-menu.png" alt="high-level-dia" width="600" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<p align="center">
<img src="/img/overview/delete-rule-popup.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>

32
src/pages/docs/how-to/activity.mdx Normal file
View File

@@ -0,0 +1,32 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern/>
# Activity
## Monitor system and network activity
The activity monitoring feature lets you quickly see what's happening with your network.
Whether a new machine or user joined your network or the access control policy has been modified, the activity log allows you to track the changes to your network.
Activity monitoring is enabled by default for every network, and you can access it in the web UI under the [Activity tab](https://app.netbird.io/activity).
You can also use the search bar to filter events by activity type.
<p align="center">
<img src="/img/how-to-guides/activity-monitoring.png" alt="activity-monitoring" width="800" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
The current version of NetBird tracks network changes that occur in the Management server. E.g., changes related to the list of peers, groups, system settings, setup keys, access control, etc.
The future versions will support connection events that occur in NetBird agents (e.g., peer A connected to peer B).
</Note>
### Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on Twitter](https://twitter.com/netbird)
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

346
src/pages/docs/how-to/cli.mdx Normal file
View File

@@ -0,0 +1,346 @@
import {HeroPattern} from "@/components/HeroPattern"; import {Note} from "@/components/mdx";
<HeroPattern />
# NetBird CLI
The NetBird client installation adds a binary called `netbird` to your system. This binary runs as a daemon service to connect
your computer or server to the NetBirt network as a peer. But it can also be used as a client to control the daemon service.
This section will explore the commands available in `netbird`.
### Syntax
Use the following syntax to run `netbird` commands from your terminal window:
```shell
netbird [command] [subcommand] [flags]
```
* `command`: Specifies the operation that you want to perform or a top-level command: `up`, `login`, `down`, `status`, `ssh`, `version`, and `service`
* `subcommand`: Specifies the operation to be executed for a top-level command like `service`: `install`, `uninstall`, `start`, and `stop`
* `flags`: Specifies optional flags. For example, you can use the `--setup-key` flag to specify the setup key to be used in the commands `login` and `up`
<Note>
To see detailed command information, use the flag `--help` after each command
</Note>
### Global flags
`netbird` has a set of global flags that are available in every command. They specify settings that are core or shared between two or more commands, e.g. `--setup-key` is used by `login` and `up` to authenticate the client against a management service.
Below is the list of global flags:
```shell
--admin-url string Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io")
-c, --config string Netbird config file location (default "/etc/netbird/config.json")
--daemon-addr string Daemon service address to serve CLI requests [unix|tcp]://[path|host:port] (default "unix:///var/run/netbird.sock")
--log-file string sets Netbird log path. If console is specified the the log will be output to stdout (default "/var/log/netbird/client.log")
-l, --log-level string sets Netbird log level (default "info")
-m, --management-url string Management Service URL [http|https]://[host]:[port] (default "https://api.wiretrustee.com:443")
-p, --preshared-key string Sets Wireguard PreSharedKey property. If set, then only peers that have the same key can communicate.
-k, --setup-key string Setup key obtained from the Management Service Dashboard (used to register peer)
```
### Environment Variables
Every flag of a `netbird` command can be passed as an environment variable. We are using the following rule for the environment variables composition:
* `PREFIX_FLAGNAME` and for flags with multiple parts: `PREFIX_FLAGNAMEPART1_FLAGNAMEPART2`
* The prefix is always **NB**
* The flag parts are separated by a dash ("-") when passing as flags and with an underscore ("_") when passing as an environment variable
For example, let's check how we can pass `--config` and `--management-url` as environment variables:
```shell
export NB_CONFIG="/opt/netbird/config.json"
export NB_MANAGEMENT_URL="https://api.self-hosted.com:33073"
netbird up
```
The `up` command would process the variables, read the configuration file on `/opt/netbird/config.json` and attempt to connect to the management service running at `https://api.self-hosted.com:33073`.
### Commands
#### up
Single command to log in and start the NetBird client. It can send a signal to the daemon service or run in the foreground with the flag `--foreground-mode`.
The command will check if the peer is logged in and connect to the management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.
##### Flags
```shell
--dns-resolver-address string Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best ip and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address ""
--external-ip-map strings Sets external IPs maps between local addresses and interfaces.You can specify a comma-separated list with a single IP and IP/IP or IP/Interface Name. An empty string "" clears the previous configuration. E.g. --external-ip-map 12.34.56.78/10.0.0.1 or --external-ip-map 12.34.56.200,12.34.56.78/10.0.0.1,12.34.56.80/eth1 or --external-ip-map ""
-F, --foreground-mode start service in foreground
```
##### Usage
The minimal form of running the command is:
```shell
netbird up
```
If you are running on a self-hosted environment, you can pass your management url by running the following:
```shell
netbird up --management-url https://api.self-hosted.com:33073
```
if you want to run in the foreground, you can use "console" as the value for `--log-file` and run the command with sudo:
```shell
sudo netbird up --log-file console
```
<Note>
On Windows, you may need to run the command from an elevated terminal session.
</Note>
In case you need to use a setup key, use the `--setup-key` flag :
```shell
netbird up --setup-key AAAA-BBB-CCC-DDDDDD
```
#### login
Command to authenticate the NetBird client to a management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.
##### Usage
The minimal form of running the command is:
```shell
netbird login
```
If you are running on a self-hosted environment, you can pass your management url by running the following:
```shell
netbird login --management-url https://api.self-hosted.com:33073
```
In case you need to use a setup key, use the `--setup-key` flag:
```shell
netbird login --setup-key AAAA-BBB-CCC-DDDDDD
```
Passing a management url and a setup key:
```shell
netbird login --setup-key AAAA-BBB-CCC-DDDDDD --management-url https://api.self-hosted.com:33073
```
#### down
Command to stop a connection with the management service and other peers in a NetBird network. After running this command, the daemon service will enter an `Idle` state.
##### Usage
The minimal form of running the command is:
```shell
netbird down
```
#### status
Retrieves the peer status from the daemon service.
##### Flags
```shell
-d, --detail display detailed status information
--filter-by-ips strings filters the detailed output by a list of one or more IPs, e.g. --filter-by-ips 100.64.0.100,100.64.0.200
--filter-by-status string filters the detailed output by connection status(connected|disconnected), e.g. --filter-by-status connected
```
##### Usage
The minimal form of running the command is:
```shell
netbird status
```
This will output:
```shell
Daemon status: Connected
Management: Connected
Signal: Connected
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
If you want to see more details about the peer connections, you can use the `--detail` or `-d` flag:
```shell
netbird status -d
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.85.4
Public key: 2lI3F+fDUWh58g5oRN+y7lPHpNcEVWhiDv/wr1/jiF8=
Status: Disconnected
-- detail --
Connection type: -
Direct: false
ICE candidate (Local/Remote): -/-
Last connection update: 2022-07-07 12:21:31
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:32
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:33
Daemon status: Connected
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
To filter the peers' output by connection status, you can use the `--filter-by-status` flag with either "connected" or "disconnected" as value:
```shell
netbird status -d --filter-by-status connected
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:32
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:33
Daemon status: Connected
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
To filter the peers' output by peer IP addresses, you can use the `--filter-by-ips` flag with one or more IPs separated by a comma as a value:
```shell
netbird status -d --filter-by-ips 100.119.201.225
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:32
Daemon status: Connected
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
You can combine both filters and get the peers that are both connected and with specific IPs:
```shell
netbird status -d --filter-by-status connected --filter-by-ips 100.119.85.4,100.119.230.104
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:33
Daemon status: Connected
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
<Note>
The peer with IP `100.119.85.4` wasn't returned because it was not connected
</Note>
#### ssh
Command to connect using ssh to a remote peer in your NetBird network.
You should run the ssh command with elevated permissions.
##### Flags
```shell
-p, --port int Sets remote SSH port. Defaults to 44338 (default 44338)
```
##### Arguments
The ssh command accepts one argument, `user@host`; this argument indicates the remote host to connect:
* `user`: indicates the remote user to login
* `host`: indicates the remote peer host IP address
##### Usage
The minimal form of running the command is:
```shell
sudo netbird ssh user@100.119.230.104
```
If you the remote peer agent is running the ssh service on a different port, you can use the `--port` or `-p` flag:
```shell
sudo netbird ssh -p 3434 user@100.119.230.104
```
#### version
Outputs the `netbird` command version.
##### Usage
The minimal form of running the command is:
```shell
netbird version
```
This will output:
```shell
0.8.2
```
#### service
The service command is a top-level command with subcommands to perform operations related to the daemon service.
You should run the service command with elevated permissions.
#### service install
The install installs the daemon service on the system.
##### Usage
The minimal form of running the command is:
```shell
sudo netbird service install
```
You can use the global flags to configure the daemon service. For instance, you can set a debug log level with the flag `--log-level`
```shell
sudo netbird service install --log-level debug
```
You can set a custom configuration path with the flag `--config`
```shell
sudo netbird service install --config /opt/netbird/config.json
```
#### service uninstall
The uninstall uninstalls the daemon service from the system.
##### Usage
The minimal form of running the command is:
```shell
sudo netbird service uninstall
```
#### service start
Starts the daemon service
##### Usage
The minimal form of running the command is:
```shell
sudo netbird service start
```
#### service stop
Stops the daemon service
##### Usage
The minimal form of running the command is:
```shell
sudo netbird service stop
```

158
src/pages/docs/how-to/dns.mdx Normal file
View File

@@ -0,0 +1,158 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern/>
# DNS
## Manage DNS in your network
<div class="videowrapper">
<iframe src="https://www.youtube.com/embed/xxQ_QeEMC0U" allow="fullscreen;"></iframe>
</div>
<br/><br/>
You don't need to design a network or configure [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol)
as it is automatically done in a single place - the NetBird Management service.
NetBird assigns and automatically distributes IP addresses to your peers.
Once peers have IPs, they can communicate with one another and establish direct encrypted WireGuard® tunnels.
You can use these IPs to access the services running on the connected peers (e.g., SSH).
Even though we trust our memory capacity, there is a limit to what we can remember,
especially when it comes to IP addresses like this one, 100.128.185.34.
Starting [v0.11.0](https://github.com/netbirdio/netbird/releases), NetBird automatically assigns a domain name
to each peer in a private `netbird.cloud` space that can be used to access the machines. E.g., `my-server.netbird.cloud`.
Besides accessing machines by their domain names, you can configure NetBird to use your private nameservers,
control what nameservers a specific [peer group](https://netbird.io/docs/overview/acls#groups) should use, and set up split DNS.
<Note>
Nameservers is available for NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
### Concepts
#### Local resolver
To minimize the number of changes in your system, NetBird will spin up a local DNS resolver.
This local resolver will be responsible for queries to the domain names of peers registered in your network and forwarding queries to upstream nameservers you configure in the system.
It listens on the peer's IP, and usually, it will use the default port 53, but if it is in use, it will use the 5053 port.
<Note>
Custom port support is not builtin into most operating systems. At the time of release, the supported systems are:
- MacOS
- Linux with systemd-resolved
</Note>
#### Nameserver
Nameserver is an upstream DNS server for name resolution, if a query comes and is not a peer domain name, it will be resolved by one of the upstream servers. You can assign private and public IPs and custom ports. Remember that you might need a network route for private addresses to allow peers to connect to it.
#### Match domains
Match domains allow you to route queries of names, matching them to specific nameservers. This is useful when you have an internal DNS configuration that only internal servers can resolve.
#### All domains option
The all domains option defines a default nameserver configuration to resolve all domains that don't have a match domain setting. Because not all operating systems support match domain configuration, we recommend configuring at least one nameserver set with this option enabled per distribution group. You may also consider using the group All for distribution, so you don't have to define multiple sets of nameservers to resolve all domains.
<Note>
A nameserver set may only be configured with either All domains or match domains, you can have both settings in a single configuration as they overlap.
</Note>
#### Distribution groups
Distribution defines that peers that belong to groups set in this field will receive the nameserver configuration.
<Note>
When using private nameservers, you may use these groups to link routing peers and clients of the private servers.
</Note>
### Managing nameserver groups
A nameserver group defines up to 2 nameservers to resolve DNS to a set of peers in distribution groups.
#### Creating a nameserver group
Access the `DNS` tab and click the `Add Nameserver` button to create a new nameserver.
<p align="center">
<img src="/img/how-to-guides/netbird-nameserver-add-button.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
That will open a nameserver selection configuration screen where you can choose between using three predefined public
nameservers or using a custom setup.
##### Selecting predefined nameservers
If you choose a predefined public nameserver option, you can select the following nameservers:
- [Google DNS servers](https://developers.google.com/speed/public-dns/docs/using)
- [Cloudflare DNS servers](https://one.one.one.one/dns/)
- [Quad9 DNS servers](https://www.quad9.net/)
<p align="center">
<img src="/img/how-to-guides/netbird-nameserver-selection-view-open.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
After selecting one of the three options, you need to assign a peer group for which this nameserver will be effective.
In the example below, we chose the "All" group:
<p align="center">
<img src="/img/how-to-guides/netbird-nameserver-all-group.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
##### Creating custom nameservers
You can also configure a custom nameserver by clicking the `Add custom` button. Now you can enter the details of your nameserver.
In the example below, we are creating a nameserver with the following information:
- Name: `Office resolver`
- Description: `Berlin office resolver`
- Add at least one nameserver: `192.168.0.32` with port `53`
- Match mode: `All domains`
- Distribution group: `Remote developers`
<p align="center">
<img src="/img/how-to-guides/netbird-nameserver-custom.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
#### Creating a nameserver for specific domains
Sometimes we want to forward DNS queries to specific nameservers but only for particular domains that match a setting.
Taking the example of custom nameservers above, you could select a match mode for only domains listed there.
Below you can see the same nameserver setup but only for the `berlinoffice.com` domain:
<p align="center">
<img src="/img/how-to-guides/netbird-nameserver-remote-resolver.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
Currently, only MacOS, Windows 10+, and Linux running systemd-resolved support nameservers without an all domains resolver. For a better experience, we recommend setting at least one all domain resolver to be applied to all groups.
</Note>
#### Distributing the settings with groups
You can select as many distribution groups as you want for your nameserver setup. Keep in mind to link them to peers and, if required, to add access control rules when using private nameservers.
#### Adding remote private DNS servers
To add a private DNS server that is running behind routing peers, you need to create resources to ensure communication between your nameserver clients can communicate. In the Berlin office example from previous steps, we have a peer from the `Office network` that can route traffic to the `192.168.0.32` IP, so we need to ensure that a similar network route exists:
<p align="center">
<img src="/img/how-to-guides/netbird-nameserver-remote-route.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
Then we need to confirm that an access rule exists to connect `Remote developers` to `Office network` group:
<p align="center">
<img src="/img/how-to-guides/netbird-nameserver-remote-rule.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
### Testing configuration
#### Querying records
DNS configuration has evolved in the last few years, and each operating system might expose its nameserver configuration differently. Unfortunately, tools like `nslookup` or `dig` didn't get updated to match these OS configurations, and in many cases, they won't use the same servers as your browser to query domain names.
For these cases, we listed some tools to support your checks:
##### MacOS
You can use `dscacheutil`:
```shell
dscacheutil -q host -a name peer-a.netbird.cloud
```
##### Windows
You can use `Resolve-DnsName` on `Powershell`:
```shell
Resolve-DnsName -Name peer-a.netbird.cloud
```
##### Linux
In most cases, you will be fine with traditional tools because most DNS managers on Linux tend to update the /etc/resolv.conf.
```shell
dig peer-a.netbird.cloud
# or
nslookup peer-a.netbird.cloud
```
If your system is running systemd-resolved, you can also use ```resolvectl```:
```shell
resolvectl query peer-a.netbird.cloud
```
### Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on Twitter](https://twitter.com/netbird)
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

118
src/pages/docs/how-to/examples.mdx Normal file
View File

@@ -0,0 +1,118 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern />
export const title = 'Examples'
## NetBird Client on AWS ECS (Terraform)
<p align="center">
<img src="/img/examples/wiretrustee-on-aws-ecs.png" alt="high-level-dia" width="400"/>
</p>
A common way to run containers in the AWS cloud is to use Elastic Container Service (ECS).
ECS is a fully managed container orchestration service that makes it easy to deploy, manage, and scale containerized applications.
It is best practice and common to run this infrastructure behind security guardrails like strict security groups and private subnets.
Also, a routine for many System's administrators and Developers, is to connect to servers that run their company's software in order to troubleshoot, validate output and even install dependencies.
If you have your systems running in a private network, you got a few options to allow communication to hosts in that network:
* Add a [bastion host](https://en.wikipedia.org/wiki/Bastion_host) or [jump server](https://en.wikipedia.org/wiki/Jump_server).
* Connect a [site-2-site](https://en.wikipedia.org/wiki/Virtual_private_network#Types) VPN.
* [Remote access](https://en.wikipedia.org/wiki/Virtual_private_network#Types) VPN.
* Allow IP(s) address in the server's security group.
All these options are valid and proved to work over the years, but they come with some costs that in the short to mid-term you start to deal with:
* Hard implementation.
* Fragile firewall configuration.
* Yet, another server to secure and maintain.
**In this example, we will run NetBird client configured as a daemon set in ECS deployed with Terraform.**
This allows you to:
* Run NetBird as an ECS native service, you can manage and maintain it the same way you do with your other services.
* Connect to EC2 running on private subnets without the need to open firewall rules or configure bastion servers.
* Access other services connected to your NetBird network and running anywhere.
### Requirements
* Terraform > 1.0.
* A NetBird account with a Setup Key.
* Another NetBird client in your network to validate the connection (possibly your laptop or a machine you are running this example on).
* The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed.
* An [AWS account](https://aws.amazon.com/free/).
* Your AWS credentials. You can [create a new Access Key on this page](https://console.aws.amazon.com/iam/home?#/security_credentials).
### Notice
> Before getting started with this example, be aware that creating the resources from it may incur charges from AWS.
### Getting started
Clone this repository, download, and install Terraform following the guide [here](https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/aws-get-started).
Login to https://app.netbird.io and [add your machine as a peer](https://app.netbird.io/add-peer), once you are done with the steps described there, copy your [Setup key](https://app.netbird.io/setup-keys).
Using a text editor, edit the [variables.tf](https://github.com/wiretrustee/wiretrustee-examples/tree/master/ecs-client-daemon/variables.tf) file, and update the `wt_setup_key` variable with your setup key. Also, make sure that `ssh_public_key_path` variable is pointing to the correct public key path. If necessary, update the remaining variables according to your requirements and their descriptions.
Before continuing, you may also update the [provider.tf](https://github.com/wiretrustee/wiretrustee-examples/tree/master/ecs-client-daemon/provider.tf) to configure proper AWS region and default tags.
#### Creating the resources with Terraform
Follow the steps below to run terraform and create your test environment:
1. From the root of the cloned repository, enter the ecs-client-daemon folder and run terraform init to download the modules and providers used in this example.
```shell
cd ecs-client-daemon
terraform init
```
2. Run terraform plan to get the estimated changes
```shell
terraform plan -out plan.tf
```
3. Run terraform apply to create your infrastructure
```shell
terraform apply plan.tf
```
#### Validating the deployment
After a few minutes, the autoscaling group will launch an EC2 instance and there you will find the NetBird's ECS Daemon service running. With that, we can go to our [NetBird dashboard](https://app.netbird.io) and pick the IP of the node that is running NetBird, then we can connect to the node via ssh. For Unix(s) systems:
```shell
ssh ec2-user@100.64.0.200
```
Once you've login, you should be able to see the containers running by using the docker command:
```shell
sudo docker ps
```
#### Deleting the infrastructure resources used in the example
Once you are done validating the example, you can remove the resources with the following steps:
1. Run terraform plan with the flag `-destroy`
```shell
terraform plan -out plan.tf -destroy
```
2. Then execute the apply command:
```shell
terraform apply plan.tf
```
## NetBird Client in Docker
One of the simplest ways of running NetBird client application is to use a pre-built [Docker image](https://hub.docker.com/r/netbirdio/netbird).
**Prerequisites:**
* **Docker installed.**
If you don't have docker installed, please refer to the installation guide on the official [Docker website](https://docs.docker.com/get-docker/).
* **NetBird account.**
Register one at [app.netbird.io](https://app.netbird.io/).
You would need to obtain a [setup key](/overview/setup-keys) to associate NetBird client with your account.
The setup key could be found in the NetBird Management dashboard under the Setup Keys tab - [https://app.netbird.io/setup-keys](https://app.netbird.io/setup-keys).
Set the ```NB_SETUP_KEY``` environment variable and run the command.
```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest
```
That is it! Enjoy using NetBird.
If you would like to learn how to run NetBird Client as an ECS agent on AWS, please refer to [this guide](/examples/aws-ecs-client-daemon).

350
src/pages/docs/how-to/getting-started.mdx Normal file
View File

@@ -0,0 +1,350 @@
import {HeroPattern} from "@/components/HeroPattern"; import {Note} from "@/components/mdx";
<HeroPattern />
export const title = 'Getting Started'
## Quickstart Guide
Step-by-step video guide on YouTube:
<div class="videowrapper">
<iframe src="https://www.youtube.com/embed/HYlhvr_eu2U" allow="fullscreen;"></iframe>
</div>
<br/>
This guide describes how to quickly get started with NetBird and create a secure private network with 2 connected machines.
One machine is a Linux laptop, and the other one a EC2 node running on AWS.
Both machines are running Linux but NetBird also works on Windows and MacOS.
1. Sign-up at [https://app.netbird.io/](https://app.netbird.io/)
You can use your Google, GitHub or Microsoft account.
![](/img/getting-started/auth.png)
2. After a successful login you will be redirected to the ```Peers``` screen which is empty because you don't have any peers yet.
Click ```Add peer``` to add a new machine.
![](/img/getting-started/empty-peers.png)
3. Choose your machine operating system (in our case it is ```Linux```) and proceed with the installation steps.
![](/img/getting-started/add-peer.png)
4. If you installed NetBird Desktop UI you can use it to connect to the network instead of running `netbird up` command. Look for `NetBird` in your application list, run it, and click `Connect`.
>
![](/img/getting-started/systray.png)
5. At this point a browser window pops up starting a device registration process. Click confirm and follow the steps if required.
![](/img/getting-started/device-confirmation.png)
6. On the EC2 node repeat the installation steps and run `netbird up` command.
```bash
sudo netbird up
```
7. Copy the verification URL from the terminal output and paste it in your browser. Repeat step #5
![](/img/getting-started/netbird-up.png)
8. Return to ```Peers``` and you should notice 2 new machines with status ```online```
![](/img/getting-started/peers.png)
9. To test the connection you could try pinging devices:
On your laptop:
```bash
ping 100.64.0.2
```
On the EC2 node:
```bash
ping 100.64.0.1
```
10. Done! You now have a secure peer-to-peer private network configured.
<br/>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on Twitter](https://twitter.com/netbird)
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
- NetBird release page on GitHub: [releases](https://github.com/netbirdio/netbird/releases/latest)
## Installation
### Linux
**APT/Debian**
1. Add the repository:
```bash
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg -y
curl -sSL https://pkgs.wiretrustee.com/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/wiretrustee-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/wiretrustee-archive-keyring.gpg] https://pkgs.wiretrustee.com/debian stable main' | sudo tee /etc/apt/sources.list.d/wiretrustee.list
```
2. Update APT's cache
```bash
sudo apt-get update
```
3. Install the package
```bash
# for CLI only
sudo apt-get install netbird
# for GUI package
sudo apt-get install netbird-ui
```
**RPM/Red hat**
1. Add the repository:
```bash
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
[Wiretrustee]
name=Wiretrustee
baseurl=https://pkgs.wiretrustee.com/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
```
2. Install the package
```bash
# for CLI only
sudo yum install netbird
# for GUI package
sudo yum install netbird-ui
```
**Fedora**
1. Create the repository file:
```bash
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
[Wiretrustee]
name=Wiretrustee
baseurl=https://pkgs.wiretrustee.com/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
```
2. Import the file
```bash
sudo dnf config-manager --add-repo /etc/yum.repos.d/wiretrustee.repo
```
3. Install the package
```bash
# for CLI only
sudo dnf install netbird
# for GUI package
sudo dnf install netbird-ui
```
**NixOS 22.11+/unstable**
1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)
```nix
{ config, pkgs, ... }:
{
services.netbird.enable = true; # for netbird service & CLI
environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
}
```
2. Build and apply new configuration
```bash
sudo nixos-rebuild switch
```
### macOS
**Homebrew install**
1. Download and install homebrew at https://brew.sh/
2. If wiretrustee was previously installed with homebrew, you will need to run:
```bash
# Stop and uninstall daemon service:
sudo wiretrustee service stop
sudo wiretrustee service uninstall
# unlik the app
brew unlink wiretrustee
```
> netbird will copy any existing configuration from the Wiretrustee's default configuration paths to the new NetBird's default location
3. Install the client
```bash
# for CLI only
brew install netbirdio/tap/netbird
# for GUI package
brew install --cask netbirdio/tap/netbird-ui
```
4. If you installed CLI only, you need to install and start the client daemon service:
```bash
sudo netbird service install
sudo netbird service start
```
### Windows
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
2. Download the latest Windows release installer ```netbird_installer_<VERSION>_windows_amd64.exe``` (**Switch VERSION to the latest**):
3. Proceed with the installation steps
4. This will install the UI client in the C:\\Program Files\\NetBird and add the daemon service
5. After installing, you can follow the steps from [Running NetBird with SSO Login](#Running-NetBird-with-SSO-Login) steps.
> To uninstall the client and service, you can use Add/Remove programs
⚠️ In case of any issues with the connection on Windows check the firewall settings. With default Windows 11 firewall setup there could be connectivity issue related to egress traffic.
Recommended way is to add NetBird in firewall settings:
1. Go to "Control panel".
2. Select "Windows Defender Firewall".
3. Select "Advanced settings".
4. Select "Outbound Rules" -> "New rule".
5. In the new rule select "Program" and click "Next".
6. Point to the NetBird installation exe file (usually in `C:\Program Files\NetBird\netbird.exe`) and click "Next".
7. Select "Allow the connection" and click "Next".
8. Select the network in which rule should be applied (Domain, Private, Public) according to your needs and click "Next".
9. Provide rule name (e.g. "Netbird Egress Traffic") and click "Finish".
10. Disconnect and connect to NetBird.
### Binary Install
**Installation from binary (CLI only)**
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
2. Download the latest release:
```bash
curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
```
<Note>
You need to replace some variables from the URL above:
- Replace **VERSION** with the latest released verion.
- Replace **OS** with "linux", "darwin" for MacOS or "windows"
- Replace **Arch** with your target system CPU archtecture
</Note>
3. Decompress
```bash
tar xcf ./netbird_<VERSION>.tar.gz
sudo mv netbird /usr/bin/netbird
sudo chown root:root /usr/bin/netbird
sudo chmod +x /usr/bin/netbird
```
After that you may need to add /usr/bin in your PATH environment variable:
````bash
export PATH=$PATH:/usr/bin
````
4. Install and run the service
```bash
sudo netbird service install
sudo netbird service start
```
### Running NetBird with SSO Login
#### Desktop UI Application
If you installed the Desktop UI client, you can launch it and click on Connect.
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/img/getting-started/netbird-sso-login-ui.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
#### CLI
Alternatively, you could use command line. Simply run
```bash
netbird up
```
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/img/getting-started/netbird-sso-login-cmd.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
Check connection status:
```bash
netbird status
```
### Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/overview/setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/overview/setup-keys)).
For all systems:
```bash
netbird up --setup-key <SETUP KEY>
```
For **Docker**, you can run with the following command:
```bash
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:<TAG>
```
> TAG > 0.6.0 version
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
2. Check connection status:
```bash
netbird status
```
3. Check your IP:
On **macOS** :
````bash
sudo ifconfig utun100
````
On **Linux**:
```bash
ip addr show wt0
```
On **Windows**:
```bash
netsh interface ip show config name="wt0"
```
### Running NetBird in Docker
Set the ```NB_SETUP_KEY``` environment variable and run the command.
<Note>
You can pass other settings as environment variables. See [Environment variables](reference/netbird-commands.md#environment-variables) for details.
</Note>
```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest
```
See [Docker example](examples/netbird-docker.md) for details.
### Troubleshooting
1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL
which is ```https://api.wiretrustee.com:33073```.
2. If you have specified a wrong `--management-url` (e.g., just by mistake when self-hosting)
to override it you can do the following:
```bash
netbird down
netbird up --management-url https://<CORRECT HOST:PORT>/
```
To override it see the solution #1 above.

189
src/pages/docs/how-to/network-routes.mdx Normal file
View File

@@ -0,0 +1,189 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern/>
# Network Routes
## Routing traffic to private networks
<div class="videowrapper">
<iframe src="https://www.youtube.com/embed/VQuPuBOAknQ" allow="fullscreen;"></iframe>
</div>
<br/><br/>
NetBird provides fast and reliable end-to-end encryption between peers in your network. You can install the agent on every desktop, VM, container, or physical server and have a fast, secure peer-to-peer mesh network. That is the desired configuration, but some cases do not allow for agent installation or can slow down migration from legacy systems:
- Side-by-side migrations where part of your network is already using NetBird but needs to access services that are not.
- Systems that have limited operating system access. e.g., IoT devices, printers, and managed services.
- Legacy networks where an administrator is unable to install the agent on all nodes.
In these cases, you can configure network routes assigning routing peers to connect existing infrastructure. Routing peers will forward packets between your NetBird peers and your other networks; they can masquerade traffic going to your data centers or embedded devices, reducing the need for external route configuration and agent installation.
<p align="center">
<img src="/img/how-to-guides/netbird-network-routes.png" alt="high-level-dia" />
</p>
<Note>
If you want to see the Network Routes feature in action, try our managed version at https://app.netbird.io/routes.
It's free and simple! :)
</Note>
### Concepts
#### Network routes
A network route describes the network you want to connect with your NetBird peers. It has an identifier, a network range, a routing peer, and some parameters available for managing priority and masquerading.
<Note>
Network routes is available for NetBird [v0.9.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
#### Network identifiers and ranges
Network identifiers are names for each network you want to route traffic from your peers, and ranges are IP ranges declared in CIDR notation which refers to an external network. The combination of identifiers and these ranges makes a single network.
#### Routing peer
A routing peer is a node that will route packets between your routed network and the other NetBird peers.
<Note>
Only Linux OS nodes can be assigned as routing peers.
</Note>
#### High availability routes
A highly available route is a combination of multiple routes with the same network identifier and ranges. They have different routing peers offering high-available paths for communication between your peers and external networks.
Nodes connected to routing peers will choose one of them to route packets to external networks based on connection type and defined metrics.
#### Masquerade
Masquerade hides other NetBird network IPs behind the routing peer local address when accessing the target Network range. This option allows access to your private networks without configuring routes on your local routers or other devices.
If you don't enable this option, you must configure a route to your NetBird network in your external network infrastructure.
#### Metric and priority
Metric defines prioritization when choosing the main routing peer in a high availability network. Lower metrics have higher priority.
#### Distribution groups
Distribution groups define that peers that belong to groups set in this field will receive the network route.
<Note>
It doesn't remove the need for the routing peer to be connected to these peers
</Note>
### Managing network routes
A network route describes a network you want to connect with your NetBird peers. It has an identifier, a network range, a routing peer, and some parameters available for managing priority and masquerading.
#### Creating a network route
Access the `Network Routes` tab and click the `Add Route` button to create a new route.
That will open a route configuration screen where you can add the information about the network you want to route:
<p align="center">
<img src="/img/how-to-guides/netbird-network-routes-add-button.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
Now you can enter the details of your route.
In the example below, we are creating a route with the following information:
- Network identifier: `aws-eu-central-1-vpc`
- Description: `Production VPC in Frankfurt`
- Network range: `172.31.0.0/16`
- Routing peer: `aws-nb-europe-router-az-a`
- Distribution Groups: `All`
<p align="center">
<img src="/img/how-to-guides/netbird-network-routes-create.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
Once you fill in the route information, you can click on the `Save` button to save your new route.
<p align="center">
<img src="/img/how-to-guides/netbird-network-routes-saved-new.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
Done! Now every peer connected to your routing peer will be able to send traffic to your external network.
#### Creating highly available routes
To avoid a single point of failure when managing your network, we recommend installing NetBird on every resource.
However, you still want to ensure a reliable connection to your private network when running NetBird on every machine is not feasible.
NetBird Network Routes feature has a High Availability (HA) mode,
allowing one or more NetBird peers to serve as routing peers for the same private network.
To enable high-available mode, you can click on `Configure` and select a new peer in the `Add additional routing peer` field, then select the distribution groups and click on `Save`.
In the following screenshot, we are adding the peer `aws-nb-europe-router-az-b` to the `aws-eu-central-1-vpc` route:
<p align="center">
<img src="/img/how-to-guides/netbird-network-routes-create-ha.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
This way, nodes connected to both peer `aws-nb-europe-router-az-a` and peer `aws-nb-europe-router-az-b` would have a highly available connection with the network `172.31.0.0/16`.
<p align="center">
<img src="/img/how-to-guides/netbird-network-routes-saved-new-ha.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
Currently, there is no limitation in the number of routes that form a highly available route. Each connected peer will pick one routing peer to use as the router for a network; this decision is based on metric prioritization and connection attributes like direct or relayed connections.
</Note>
#### Filtering routes distribution with groups
You can select as many distribution groups as you want for your network route. You can update them at the routing peer or high-availability group level. Keep in mind to link them to peers and, if required, to add access control rules ensuring connectivity between these peers and the routing peers of your route
#### Routes without masquerading
If you want more transparency and would like to manage your external network routers, you may choose to disable masquerade for your network routes.
In this case, the routing peer won't hide any NetBird peer IP and will forward the packets to the target network transparently.
That will require a routing configuration on your external network router pointing your NetBird network back to your routing peer.
This way, devices that don't have the agent installed can communicate with your NetBird peers.
<p align="center">
<img src="/img/how-to-guides/netbird-network-routes-masquerading.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
### Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on Twitter](https://twitter.com/netbird)
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
## Add Users to your network
Whether you have a network for personal use or manage your company's corporate network, you'd probably want to invite
people to your account and join your NetBird network.
There are two ways of adding users to a NetBird account - indirect and direct.
### Indirect user invites
This way of adding users is managed by the NetBird system and doesn't require administrator input.
It works only for organizations with private domains.
Whenever a new user signs up with a private domain (e.g., @netbird.io),
NetBird creates a new account and associates it with the netbird.io organization (domain) automatically. Every consequent user signup with the same @netbird.io domain in their email address will end up under the same organization.
How does it work? Every time a previously unknown user registers at [app.netbird.io](https://app.netbird.io/),
the system classifies the domain part of the email.
The domain can fall into one of the following categories - `public`, `private`, or `unclassified`.
The domains of the private category are the ones that are automatically grouped under the same account.
Public domains are the ones of the public email providers like Gmail.
<Note>
It might happen (unlikely) that the domain classification system didn't classify your company's domain as private.
Our system was unsure about your domain and assigned an unclassified or public category to be on the safe side.
Just email us at [hello@netbird.io](mailto:hello@netbird.io) or ping us on [Slack](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A) to fix this.
</Note>
### Direct user invites
As the name stands, this way of inviting users is straightforward and works through the web UI.
To invite a new user, proceed to the `Users` tab and click the <button name="button" className="button-6">Invite User</button> button.
A user window will pop up where you can specify the name and email address of the invited user. Optionally, you could select a set of groups with which you want this user to be associated.
The invited users will receive an email invitation that they have to confirm.
After logging in to the system, they will join your network automatically.
<p align="center">
<img src="/img/how-to-guides/user-invites.gif" alt="high-level-dia" width="800" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
If a user already has a NetBird account, you can't invite them.
This is a limitation that is likely to be removed in future versions.
</Note>
### Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on Twitter](https://twitter.com/netbird)
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

7
src/pages/docs/how-to/peers.mdx Normal file
View File

@@ -0,0 +1,7 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern/>
# Peers
tba

55
src/pages/docs/how-to/settings.mdx Normal file
View File

@@ -0,0 +1,55 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern/>
# Settings
## Configure periodic user authentication
To ensure a high level of security, NetBird offers a peer login expiration feature that requires users to periodically reauthenticate their devices.
Every new network has this feature enabled, and the expiration period is set to 24 hours by default. You can disable this feature and configure the expiration period in the account settings in the web UI https://app.netbird.io/settings.
<Note>
This feature is only applied to peers added with the [interactive SSO login feature](/getting-started/installation#running-netbird-with-sso-login). Peers, added with a setup key, won't be affected.
</Note>
Expired peers will appear in the peers' view with the status `needs login`.
<p align="center">
<img src="/img/how-to-guides/peer-needs-login.png" alt="peer-needs-login.png" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
### Configure and disable expiration
The expiration period can be set to anything between one hour and 180 days.
Go to the Web UI Settings tab and set the desired period in the Authentication section.
You can also disable the expiration for the whole network in the same section.
<p align="center">
<img src="/img/how-to-guides/peer-login-expiration.png" alt="peer-login-expiration" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
Enabling peer expiration or changing the expiration period will cause some peers added with the SSO login to disconnect,
and re-authentication will be required.
</Note>
### Disable expiration individually per peer
Sometimes, you might want to disable peer expiration for some peers.
With NetBird you can disable login expiration per peer without disabling expiration globally.
In the Peers tab of the web UI click on the peer you want to disable expiration for and use the Login Expiration switch.
Peers with `expiration disabled` will be marked with a corresponding label in the peers' table.
<p align="center">
<img src="/img/how-to-guides/individual-peer-login-expiration.png" alt="peer-login-expiration" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
### Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on Twitter](https://twitter.com/netbird)
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

64
src/pages/docs/how-to/setup-keys.mdx Normal file
View File

@@ -0,0 +1,64 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern/>
# Setup Keys
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.
```bash {{ title: 'Starting NetBird Client' }}
sudo netbird up --setup-key <SETUP KEY>
```
## Types of Setup Keys
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.
## Using Setup Keys
Setup keys are available in the NetBird Management dashboard under the Setup Keys tab [https://app.netbird.io/setup-keys](https://app.netbird.io/setup-keys).
By default, we generate 2 setup keys right after account creation. You can easily add new or revoke keys.
<p align="center">
<img src="/img/architecture/setup-keys.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
When revoking a key, all machines authenticated with this key will remain connected in the network. The same logic applies when the key expires.
</Note>
### Expiration
Setup keys are set to expire after 30 days. When expired, the setup key can't be used anymore.
## Peer Auto-grouping
<p align="center">
<img src="/img/architecture/peer-auto-tagging-setupkey.gif" alt="high-level-dia" width="800" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
NetBird offers a powerful [Access Control feature](/overview/acls) 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](https://github.com/netbirdio/netbird/releases), 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.
<p align="center">
<img src="/img/architecture/netbird-peer-auto-tagging-newkey.png" alt="high-level-dia" width="500" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
Auto-assign groups will apply only to newly registered machines.
</Note>

84
src/pages/docs/how-to/users.mdx Normal file
View File

@@ -0,0 +1,84 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern/>
# Users
## Service Users
Service users are a type of account that allow applications or services to access resources and perform actions within your organization.
### What are Service Users used for?
Service users are typically used to authenticate requests to a web service on behalf of an application or a service. They are an alternative to using a personal account, and can provide additional security by allowing you to limit the scope of access granted to the service user.
Service users can be used in a variety of scenarios, including:
- **Automated scripts**: If you need to run automated scripts that access resources within your organization, you can use service users instead of storing your login credentials in plain text.
- **Third-party integrations**: If you want to integrate your resources with a third-party service, you can use a service user to provide access to your data without giving the third-party service access to your personal account.
- **Access control**: If you need to grant access to a specific set of resources to a particular application or service, you can create a service user with the necessary permissions.
### Creating a Service User
To create a service user, you'll need to log in to your organization's account and navigate to the "Service Users" section of your account settings.
<p align="center">
<img src="/img/overview/service-user-overview.png" alt="service-user-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
From there, you can create a new service user and specify the permissions that the user should have.
<p align="center">
<img src="/img/overview/service-user-creation.png" alt="service-user-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
It's important to keep your service users secure, as they can provide access to sensitive data and actions within your organization. You should treat your service users like you would treat your own personal account and limit the scope of access granted to the service user.
</Note>
## Personal Access Tokens
Personal access tokens are a type of authentication credential that allow you to access your account and perform actions on behalf of yourself or your organization.
### What are Personal Access Tokens used for?
Personal access tokens are typically used to authenticate API requests to a web service. They are an alternative to using your username and password, and can provide additional security by allowing you to limit the scope of access granted to the token.
Personal access tokens can be used in a variety of scenarios, including:
- **Automated scripts**: If you need to run automated scripts that access your account, you can use personal access tokens instead of storing your login credentials in plain text.
- **Third-party integrations**: If you want to integrate your account with a third-party service, you can use a personal access token to provide access to your data without giving the third-party service your login credentials.
- **Command-line tools**: If you use command-line tools to interact with your account, you can use personal access tokens to authenticate those requests.
### Creating a Personal Access Token
To create a personal access token, you'll need to log in to your account and navigate to the "Users" section and look for your user or create a [service user](#) to use for your API requests.
<p align="center">
<img src="/img/overview/personal-access-token-overview.png" alt="personal-access-token-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
From there, you can create a new token and specify the permissions that the token should have.
<p align="center">
<img src="/img/overview/personal-access-token-creation.png" alt="personal-access-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
After the token was generated successfully you will see a plain version of your token to copy and store in a secure place.
Be aware that once you close the popup it is impossible to see the plain version of the token again as NetBird only stores a hashed version of the token.
<p align="center">
<img src="/img/overview/personal-access-token-example.png" alt="personal-access-token-example" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
<Note>
It's important to keep your personal access tokens secure, as they can provide access to sensitive data and actions within your account. You should treat your personal access tokens like you would treat your password and never share them with anyone else.
</Note>
### Using Personal Access Tokens
Once you have created a personal access token, you can use it to authenticate requests to a web service that supports token-based authentication. To use a personal access token, you typically include it as an authentication header in your API requests.
For example, if you were using the GitHub API, you might include your personal access token like this:
With this header included, the GitHub API would authenticate your request using your personal access token and grant you access to the resources that the token has been authorized to access.