Installation

1) Install NetBird (script method)

• Prepare prerequisites (Debian/Ubuntu):
• sudo apt update
• sudo apt install -y ca-certificates curl gnupg
• Prepare prerequisites (RHEL/CentOS):
• sudo yum install -y ca-certificates curl
• Run the official install script (works on most distros):
• curl -fsSL https://pkgs.netbird.io/install.sh | sudo sh
• The script installs the NetBird package and systemd service. On completion the netbird binary will typically be available as /usr/bin/netbird and the service name is netbird.

2) Configure the management URL (set to https://bird.gen.network) There are two common ways to set the management URL: via the NetBird CLI (recommended if supported) or by writing a local config file. After changing config, restart the service.

A — Configure using the NetBird CLI (preferred when available)

• Example CLI form (replace with actual flags if your NetBird version differs):
• sudo netbird login --management-url https://bird.gen.network
• Or, if the client supports a direct join: sudo netbird join --url https://bird.gen.network
• If the CLI opens a browser to complete interactive login, the management URL above will be used.

B — Configure by editing the service configuration file

• Common location (check which file exists on your installation): /etc/netbird/config.yaml or /etc/netbird/config.json
• If no file exists, create /etc/netbird/config.yaml with the management URL entry. Example YAML fragment:
• management_url: "https://bird.gen.network"
• Or example JSON (if the client uses JSON):
• { "management_url": "https://bird.gen.network" }
• Save the file and ensure ownership and permissions are correct (root only):
• sudo chown root:root /etc/netbird/config.yaml
• sudo chmod 600 /etc/netbird/config.yaml
• Restart the service:
• sudo systemctl restart netbird
• Check status: sudo systemctl status netbird

3) Authenticate the client Two common authentication flows are a setup key (token) for automated/node registration and interactive user/password login. Use the method your organisation provides.

A — Authenticate with a setup key (machine / automated enrolment)

• If your organisation supplied a setup key (single-use or scoped token), run:
• sudo netbird join --setup-key "" --management-url https://bird.gen.network
• If the client requires the key in the config file, add an auth block to /etc/netbird/config.yaml (example):
• management_url: "https://bird.gen.network"

auth: type: "setupkey" setupkey: ""

• Protect the file: sudo chmod 600 /etc/netbird/config.yaml
• Restart service: sudo systemctl restart netbird
• Verify registration and connection: sudo netbird status or sudo journalctl -u netbird -f

B — Authenticate with a user and password (interactive)

• Many NetBird deployments use interactive web-based authentication. Use the CLI to start:
• sudo netbird login --management-url https://bird.gen.network
• The command may print a URL or automatically open a browser for user/password / SSO sign-in. Complete the web flow with the account credentials provided by your organisation.
• If the client supports direct username/password flags (some versions do), example:
• sudo netbird login --management-url https://bird.gen.network --username user@example.com --password "SecretPassword"
• After successful login the service will register and start. Check:
• sudo systemctl status netbird
• sudo netbird status
• sudo journalctl -u netbird -f

4) Troubleshooting and verification

• See current logs while testing:
• sudo journalctl -u netbird -f
• Confirm the client is connected and has an assigned WireGuard address:
• sudo netbird status
• ip addr show wg0 (or the interface name used by NetBird)
• Common problems:
• Management URL wrong or blocked by corporate firewall — verify DNS and HTTPS access to https://bird.gen.network from the host:
• curl -v https://bird.gen.network
• Setup key expired or incorrect — request a fresh key from your admin portal.
• Service failed to start — check journalctl logs for configuration parsing errors; file permissions may prevent reading credentials.

Security and best practice notes

• Store setup keys and passwords only in protected files (root only) or use secrets management; avoid plain text in world-readable files.
• If using interactive login, prefer SSO where available.
• When automating enrolment, use scoped/limited lifetime setup keys and rotate them regularly.