From c618d99ddccf286da986bbffe2c1d076ed441c96 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 25 Aug 2026 12:35:54 +0200 Subject: [PATCH] docs: clarify Windows client updates need no user admin on the service path (#944) * 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 placeholder. * docs: state Force Automatic Updates version scope (server and clients) * docs: promote update section to top level and fix Automatic Updates note placement --- src/pages/get-started/install/windows.mdx | 38 +++++++++++++++++++++++ src/pages/manage/peers/auto-update.mdx | 6 +++- 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/src/pages/get-started/install/windows.mdx b/src/pages/get-started/install/windows.mdx index b3d533a0..00b17170 100644 --- a/src/pages/get-started/install/windows.mdx +++ b/src/pages/get-started/install/windows.mdx @@ -18,6 +18,10 @@ The NetBird client allows a peer to join a pre-existing NetBird deployment. If a Both installers support silent (unattended) installation for use with RMM tools, MDM platforms, and scripted deployments. + + 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. + + ### EXE Installer (NSIS) Run the EXE installer with the `/S` flag for a silent installation: @@ -62,6 +66,40 @@ netbird up --setup-key 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). +## 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__windows_amd64.exe /S +``` + +Or with the MSI installer: + +```bash +msiexec /i netbird_installer__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. + + + 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. + + + + 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. + + +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. diff --git a/src/pages/manage/peers/auto-update.mdx b/src/pages/manage/peers/auto-update.mdx index 3fec21b9..946f20bd 100644 --- a/src/pages/manage/peers/auto-update.mdx +++ b/src/pages/manage/peers/auto-update.mdx @@ -48,10 +48,14 @@ When you need updates to be installed without user interaction, enable the **For 3. **Update Process**: 1. If the Peer is running an older version than specified, it will prompt the user to install the update via a system notification and an install entry in the NetBird tray menu. 2. Client will then download the update package from the official NetBird repository. - 3. The Peer will then install the update and restart itself to apply the changes. + 3. The NetBird background service, which runs with system privileges, installs the update and restarts the client to apply it. When **Force Automatic Updates** is enabled, step 3.1 is skipped, the update is installed automatically in the background without user interaction. + + Accepting a prompted update does **not** require the user to have administrator rights. The installation in step 3.3 is performed by the NetBird background service, which already runs with system privileges, not by the logged-in user. This is the same install mechanism as a forced update; the only difference is who triggers it. Manually running the installer instead (for example, from the tray's download link when Automatic Updates is off) is a per-machine install and does require elevation. + + ## Supported Platforms Automatic Updates are supported on the following platforms only: