mirror of
https://github.com/netbirdio/docs.git
synced 2026-08-26 17:51:27 +02:00
c618d99ddc
* docs: clarify Windows client updates need no user admin on the service path The 'update needs admin' confusion comes from mixing two paths. Clarify both: - auto-update: accepting a prompted update is installed by the NetBird service (system privileges), not the logged-in user, so no admin rights are needed. Only the manual download-link path is a per-machine install that requires elevation. - Windows install: silent install/upgrade needs an elevated (SYSTEM) context, which RMM/MDM tools provide; a standard user gets 1625. Add an Updating section: the same installer upgrades in place (no separate update package), pushed via the same RMM/MDM tool; downgrades are blocked. All claims lab-verified 2026-08-20 (WS2022, v0.76.0 -> v0.77.0). * docs: qualify elevation context and warn install-only deploy jobs skip upgrades - Not every deployment configuration runs as SYSTEM; a user-context job fails with 1625. Say the job must run elevated. - The GPO deployment script exits when NetBird is already installed, so it is install-only. Warn that upgrades need an upgrade-capable job. * docs: correct downgrade behavior per installer and address review on update section The MSI (WiX MajorUpgrade) blocks downgrades; the NSIS EXE has no version check and will downgrade. Stop teaching 1603 as a downgrade signature, add same-installer-type guidance, service-restart warning, rollback path, Automatic Updates version floors and Latest Version pinning conflict. Match the page's EXE-first order and <VERSION> placeholder. * docs: state Force Automatic Updates version scope (server and clients) * docs: promote update section to top level and fix Automatic Updates note placement
153 lines
8.6 KiB
Plaintext
153 lines
8.6 KiB
Plaintext
import {Note} from "@/components/mdx";
|
|
|
|
# Windows Installation
|
|
|
|
The NetBird client allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
|
|
|
|
1. Download the latest Windows release:
|
|
- <Button href="https://pkgs.netbird.io/windows/x64" variant="text">EXE Installer</Button><br />
|
|
- <Button href="https://pkgs.netbird.io/windows/msi/x64" variant="text">MSI Installer</Button><br />
|
|
2. Execute the installer and proceed with the installation steps
|
|
3. This will install the UI client in the `C:\Program Files\NetBird` and add the daemon service
|
|
4. After installing, you can follow the steps from [Running NetBird with SSO Login](#running-net-bird-with-sso-login).
|
|
<Note>
|
|
To uninstall the client and service, you can use Add/Remove programs
|
|
</Note>
|
|
|
|
## Silent and Automated Installation
|
|
|
|
Both installers support silent (unattended) installation for use with RMM tools, MDM platforms, and scripted deployments.
|
|
|
|
<Note>
|
|
Silent installation writes to `C:\Program Files` and registers a Windows service, so it requires an elevated administrator or `SYSTEM` context. Make sure the deployment job runs elevated: tools such as PDQ, Intune, and Group Policy typically install as `SYSTEM` when targeting computers, but a job configured to run in the user's context is not elevated and fails with exit code `1625` (`This installation is forbidden by system policy`). A standard user running the installer interactively is prompted for elevation instead.
|
|
</Note>
|
|
|
|
### EXE Installer (NSIS)
|
|
|
|
Run the EXE installer with the `/S` flag for a silent installation:
|
|
|
|
```bash
|
|
netbird_installer_<VERSION>_windows_amd64.exe /S
|
|
```
|
|
|
|
The installer no longer writes a machine-wide `HKLM\Software\Microsoft\Windows\CurrentVersion\Run` entry. Starting with v0.75.0, the desktop app manages launch at login as a per-user preference.
|
|
|
|
### MSI Installer
|
|
|
|
Run the MSI installer with `msiexec` for a silent installation:
|
|
|
|
```bash
|
|
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi /quiet
|
|
```
|
|
|
|
The MSI does not expose an `AUTOSTART` property. On a fresh desktop installation, the app enables **Launch NetBird UI at Login** for the current user the first time the UI runs. Upgrades preserve the user's existing preference. Users can change it under **Settings → General**, and administrators can suppress or remove the per-user registration with the [`disableAutostart` MDM setting](/client/mdm-integration#disableAutostart).
|
|
|
|
<Note>
|
|
**Launch NetBird UI at Login** affects only the graphical interface. The NetBird background service starts independently and can maintain connectivity even when the UI does not launch.
|
|
</Note>
|
|
|
|
### Combining with a Setup Key
|
|
|
|
For fully automated deployments where peers should register without user interaction, combine silent installation with a [setup key](/manage/peers/register-machines-using-setup-keys):
|
|
|
|
```bash
|
|
netbird_installer_<VERSION>_windows_amd64.exe /S
|
|
netbird up --setup-key <SETUP KEY>
|
|
```
|
|
|
|
Or with the MSI installer:
|
|
|
|
```bash
|
|
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi /quiet
|
|
netbird up --setup-key <SETUP KEY>
|
|
```
|
|
|
|
<Note>
|
|
For MDM-specific deployment guides, see [Deploy with Intune](/manage/peers/mdm-deployment/intune-netbird-integration) or [Deploy with Acronis](/manage/for-partners/acronis-integration).
|
|
</Note>
|
|
|
|
## Updating an Existing Installation
|
|
|
|
There is no separate update package. The same installer upgrades an existing installation in place: run the newer version and it replaces the installed one, keeping the peer's registration and configuration under `C:\ProgramData\Netbird`. There is no need to re-run `netbird up` or pass a setup key again after an upgrade.
|
|
|
|
```bash
|
|
netbird_installer_<VERSION>_windows_amd64.exe /S
|
|
```
|
|
|
|
Or with the MSI installer:
|
|
|
|
```bash
|
|
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi /quiet /norestart /L*v netbird_upgrade.log
|
|
```
|
|
|
|
The `/L*v` log is optional but makes a failed silent upgrade far easier to diagnose.
|
|
|
|
Like the initial install, an upgrade requires an elevated context, so the upgrade job must run as administrator or `SYSTEM`. Two more things the upgrade job must get right:
|
|
|
|
- **Use the same installer type you deployed with.** Neither installer detects an installation made by the other, so switching from EXE to MSI (or back) produces a second, overlapping installation instead of an upgrade.
|
|
- **Use a job that runs the installer even when NetBird is already present.** Some install jobs deliberately skip machines where the application is already installed, and a job like that will never upgrade. The script in the [Group Policy deployment guide](/manage/peers/mdm-deployment/windows-gpo-deployment), for example, exits early if NetBird is already installed, so use an upgrade-capable job for updates.
|
|
|
|
<Note>
|
|
The upgrade stops and restarts the NetBird service, so the peer briefly disconnects during the install. This also applies when you push the upgrade over the NetBird tunnel itself: the session drops mid-install and comes back once the service restarts.
|
|
</Note>
|
|
|
|
<Note>
|
|
Alternatively, an administrator can enable [Automatic Updates](/manage/peers/auto-update) under **Settings » Clients** (requires v0.61.0 or later on the clients and, when self-hosting, on the Management server). Clients then prompt the user to install the configured version and the NetBird service performs the install, with no administrator rights required from the user; the **Force Automatic Updates** toggle (v0.67.0 or later, again on both the clients and the Management server) installs without prompting. If you deploy and hold a specific version with the installer while Automatic Updates is set to **Latest Version**, clients will be prompted, or with Force updated, past the version you are holding, so pin a **Custom Version** instead.
|
|
</Note>
|
|
|
|
The two installers treat downgrades differently:
|
|
|
|
- **The MSI refuses to downgrade.** Installing an MSI older than the installed version changes nothing and fails with *"A newer version of NetBird is already installed"*. In quiet mode `msiexec` exits with `1603`, but `1603` is Windows Installer's generic fatal-error code and also fires on unrelated failures, so confirm a suspected downgrade attempt in the `/L*v` log rather than from the exit code alone. To roll back an MSI installation, uninstall NetBird and then install the older MSI; the uninstall leaves the configuration under `C:\ProgramData\Netbird` in place, so the peer keeps its identity.
|
|
- **The EXE does not check versions.** It removes the existing EXE installation and installs the packaged version even when that version is older, so rolling back an EXE installation is just a normal silent run of the older installer.
|
|
|
|
## Running NetBird with SSO Login
|
|
### Desktop UI Application
|
|
Launch the desktop app and click **Connect** in the main window or system-tray menu. On first launch, choose NetBird Cloud or enter the URL of your self-hosted deployment. NetBird opens your browser to authenticate the device. See the [desktop app guide](/client/desktop-app) for the complete interface.
|
|
|
|
### 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="/docs-static/img/get-started/netbird-sso-login-cmd.gif" alt="high-level-dia" className="imagewrapper-big"/>
|
|
</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](/manage/peers/register-machines-using-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.
|
|
|
|
For unattended deployments across many machines, pre-populate the client config so each peer registers on first start. See [Bootstrap peers via config file](/manage/peers/bootstrap-via-config-file).
|
|
|
|
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/manage/peers/register-machines-using-setup-keys)).
|
|
|
|
For all systems:
|
|
```bash
|
|
netbird up --setup-key <SETUP KEY>
|
|
```
|
|
|
|
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:
|
|
|
|
```bash
|
|
netsh interface ip show config name="wt0"
|
|
```
|