Frequently Asked Question

Linux Installation - custom configurations
Last Updated 9 months ago

Linux Installation

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.

    Powered by GEN UK CLEAN GREEN ENERGY

    Loading ...