Add documentation recommending pre-configuring orb sensors

docs/deploy-and-configure/README.md

@@ -13,6 +13,7 @@ The Orb platform supports a range of deployment options and is highly configurab
 
 * [Set up Orb Cloud Analytics](/docs/orb-cloud#pro-plan-quickstart) - view, manage, and analyze your data in the cloud
 * [Set up Local Analytics](/docs/deploy-and-configure/local-analytics) - host your own Orb analytics dashboard
+* [Pre-configure an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install) - have sensors link and configure themselves on first start, on any platform
 * [Link Orbs with Deployment Tokens](/docs/deploy-and-configure/deployment-tokens) - configure and link Orbs at scale
 * [Windows & macOS MDM](/docs/deploy-and-configure/mdm) - easily deploy to corporate laptops or POS systems
 * [Guest Orbs](/docs/deploy-and-configure/guest-orbs) - easily link any Orb to your account with Guest Orbs

docs/deploy-and-configure/deployment-tokens.md

@@ -37,6 +37,10 @@ Deployment Tokens can be utilized to easily link Orbs to your Space and ensure t
 4. [Utilizing Mobile Device Management (MDM) tools for Windows and macOS](/docs/deploy-and-configure/deployment-tokens#using-mdm)
 
 :::tip
+Setting a token before the Orb ever starts is the recommended way to deploy sensors at scale. For the exact usage on each platform, see [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install).
+:::
+
+:::info
 If you are using Orb as an individual with a handful of Orbs to manage, Deployment Tokens are not necessary for Linking or Configuration, as you may use other options such as logging into the application, discovery from another logged in Orb application, or using the CLI. See [Linking an Orb to your account](/docs/orb-app/linking-orb-to-account) for more details.
 :::
 
@@ -63,26 +67,35 @@ Your Orb is now linked to your Space! If you receive an error, the Orb is likely
 
 The environment variable `ORB_DEPLOYMENT_TOKEN` can be used to set the Deployment Token and link an Orb with your Space.
 
-:::warning
-As macOS apps run in restricted sandboxes, they do not have access to your shell environment. Therefore, using an environment variable does not function for the macOS app. The Orb macOS binary, Docker images, and Homebrew install options all support environment variables.
-:::
-
 You can simply insert the environment variable before running `orb sensor`:
 
 ```bash
 ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 orb sensor
 ```
 
-Alternatively, you can export the environment variable to make it available to your shell and Orb.
+:::warning
+This only works when you launch the sensor yourself. In most real deployments Orb runs as a service, and service managers do not inherit your shell environment. Setting the variable in your shell or exporting it from `.bashrc` will have no effect on the running Orb. The variable has to go in the config file that your platform's service reads.
+:::
+
+**[Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install)** lists that file for every supported platform:
 
-```bash
-export ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678
-```
+| Platform | Where `ORB_DEPLOYMENT_TOKEN` goes |
+| -------- | --------------------------------- |
+| Ubuntu, Debian, RHEL/Fedora/CentOS, Arch | [`/etc/default/orb`](/docs/setup-sensor/linux#pre-configure-orb) |
+| Raspberry Pi OS | [`/etc/default/orb`](/docs/setup-sensor/raspberry-pi#step-4-pre-configure-orb-optional-) |
+| Alpine and other OpenRC systems | [`/etc/conf.d/orb`](/docs/setup-sensor/linux/alpine#pre-configure-orb) |
+| OpenWrt | [`/etc/config/orb`](/docs/setup-sensor/linux/openwrt#step-2-pre-configure-orb-optional-) |
+| Docker | [container `environment:`](/docs/setup-sensor/docker#pre-configure-orb-optional-) |
+| Podman | [quadlet `Environment=`](/docs/setup-sensor/podman#pre-configure-orb-optional-) |
+| Windows | [service registry key or installer flag](/docs/setup-sensor/windows#using-deployment-tokens) |
+| macOS | [MDM profile, or a token file for Homebrew](/docs/setup-sensor/macos#linking-with-a-deployment-token) |
+| MikroTik RouterOS | [app environment settings](/docs/setup-sensor/mikrotik#step-4-install-and-configure-orb) |
+| Cisco IOx | [`package.yaml`](/docs/setup-sensor/cisco/ioxclient#step-3-create-the-package-descriptor) |
 
-Adding this line to your shell's configuration is outside of the scope of this document.
+Synology, QNAP, Firewalla, Proxmox, UniFi routers, and WLAN Pi are covered there too.
 
-:::tip
-If you're unsure how to add ORB_DEPLOYMENT_TOKEN to your shell's configuration file and source it, an AI chatbot can walk you through this task.
+:::warning
+As macOS apps run in restricted sandboxes, they do not have access to your shell environment. Therefore, using an environment variable does not function for the macOS app. The Orb macOS binary, Docker images, and Homebrew install options all support environment variables.
 :::
 
 ### Using a .txt file
@@ -98,6 +111,8 @@ echo "orb-dt1-yourdeploymenttoken678" > ~/.config/orb/deployment_token.txt
 
 Ensure you replace the deployment token and specify the correct configuration directory for your system. Orb will utilize the Deployment Token in the text file on the next run.
 
+Note that the file must live in the configuration directory of the user the Orb *service* runs as, which is often not your own user. This is the recommended approach on platforms with no service environment file, such as [FreeBSD](/docs/setup-sensor/freebsd#using-deployment-tokens) and [Homebrew on macOS](/docs/setup-sensor/macos#linking-with-a-deployment-token).
+
 ### Using MDM
 
 Mobile Device Managment (MDM) systems can be used to deploy Orb at scale on Windows and macOS, and ensure the Orbs are linked to your Space. Details for using Deployment Tokens with MDM solutions are contained within the guides in the [MDM](/docs/deploy-and-configure/mdm) section.

docs/deploy-and-configure/preconfigure-at-install.md

@@ -0,0 +1,129 @@
+---
+title: Pre-configuring an Orb at install time
+shortTitle: Pre-configure at install
+metaDescription: Link and configure an Orb sensor automatically on first start using a Deployment Token, with the exact config file to use for each platform.
+section: Deploy & Configure
+---
+
+# Pre-configuring an Orb at install time
+
+Pre-configuring means telling an Orb who it belongs to and how it should behave *before* it starts for the first time. When you do this, the Orb links itself to your Space on first start — nobody has to open an app, discover it on the LAN, or run a CLI command on the device.
+
+This is the recommended way to deploy Orb sensors anywhere beyond a simple home network, and it is the only practical way to deploy many Orbs at once.
+
+The mechanism is the same everywhere: Orb reads a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) (and any other [configuration](/docs/deploy-and-configure/configuration)) from its environment at startup. What differs by platform is *where* you put that environment variable so the Orb service actually sees it — a service manager does not inherit your shell environment, so setting the variable in your terminal is not enough. This page covers the correct location for each platform.
+
+:::tip
+If you are setting up a single Orb on your own home network, you may not need any of this — see [Linking an Orb to your account](/docs/orb-app/linking-orb-to-account) for the simpler app-based options.
+:::
+
+## What you get
+
+- **Automatic linking.** The Orb appears in your Space the first time it starts, already named and grouped by whatever Tags the token carries.
+- **Consistent configuration.** The Configuration attached to the token is applied on link, so every Orb deployed with that token behaves identically.
+- **Ongoing management.** Because the Orb is associated with the token's Configuration, you can change settings later from [Orchestration](https://cloud.orb.net/orchestration) and apply them to every Orb linked with that token. See [Remote Configuration](/docs/deploy-and-configure/configuration#remote-configuration).
+- **No physical or network access required.** Useful for sensors shipped to remote sites, deployed by a field tech, or provisioned by an image or MDM.
+
+## Step 1: Create a Deployment Token
+
+1. Log in to Orb Cloud and open the [Orchestration](https://cloud.orb.net/orchestration) section.
+2. Every Space has a "Default Token" you can use immediately. To create a separate token — for a site, a customer, or a group of Orbs that need different settings — click "+ Create new configuration", name it, and click "Create".
+3. Copy the value in the "Token" column. It looks like `orb-dt1-yourdeploymenttoken678`.
+
+Use different tokens for sets of Orbs that need different Tags or Configurations. See [Deployment Tokens](/docs/deploy-and-configure/deployment-tokens) for full details on generating and managing tokens.
+
+:::info
+Every Space includes the Default Token. Generating *additional* tokens requires the Pro plan or a service contract.
+:::
+
+## Step 2: Choose how to deliver the token
+
+There are three delivery mechanisms. Most platforms support the first; the table in [Step 3](#step-3-set-the-token-on-your-platform) tells you which to use.
+
+| Mechanism | How it works | Best for |
+| --------- | ------------ | -------- |
+| **Environment variable** | Set `ORB_DEPLOYMENT_TOKEN` where the Orb *service* will read it — usually a service-specific config file, not your shell | Linux, OpenWrt, containers, Windows, network appliances |
+| **Token file** | Place a `deployment_token.txt` file containing only the token in Orb's config directory | Platforms with no service environment file (FreeBSD, Homebrew on macOS), or when you'd rather ship a file than edit a service |
+| **MDM configuration profile** | Push the token as a managed app setting | macOS and Windows fleets under Intune, Jamf Pro, or Mosyle |
+
+:::warning
+An Orb can only belong to one Space. If the Orb was already linked somewhere else, pre-configuring a token will not move it — unlink it first. See [Unlinking a sensor](/docs/orb-app/linking-orb-to-account#unlinking-a-sensor).
+:::
+
+## Step 3: Set the token on your platform
+
+Each install guide has a pre-configuration section with the exact steps for that platform. Find yours below.
+
+| Platform | Where the configuration goes | Guide |
+| -------- | ---------------------------- | ----- |
+| Ubuntu, Debian, RHEL, Fedora, CentOS, Arch | `/etc/default/orb` | [Linux](/docs/setup-sensor/linux#pre-configure-orb) |
+| Raspberry Pi OS | `/etc/default/orb` | [Raspberry Pi](/docs/setup-sensor/raspberry-pi#step-4-pre-configure-orb-optional-) |
+| Alpine and other OpenRC systems | `/etc/conf.d/orb` | [Alpine Linux](/docs/setup-sensor/linux/alpine#pre-configure-orb) |
+| OpenWrt | `/etc/config/orb` | [OpenWrt](/docs/setup-sensor/linux/openwrt#step-2-pre-configure-orb-optional-) |
+| GL.iNet Brume 2 | `/etc/config/orb` | [GL.iNet Brume 2](/docs/setup-sensor/gl-mt2500-standalone#step-1-create-your-openwrt-image) |
+| Docker | `environment:` in `docker-compose.yml` | [Docker](/docs/setup-sensor/docker#pre-configure-orb-optional-) |
+| Podman | `Environment=` in the quadlet | [Podman](/docs/setup-sensor/podman#pre-configure-orb-optional-) |
+| Windows | Service registry key, installer flag, or `deployment_token.txt` | [Windows](/docs/setup-sensor/windows#using-deployment-tokens) |
+| macOS | MDM profile for the app, `deployment_token.txt` for Homebrew | [macOS](/docs/setup-sensor/macos#linking-with-a-deployment-token) |
+| FreeBSD | `deployment_token.txt` | [FreeBSD](/docs/setup-sensor/freebsd#using-deployment-tokens) |
+| MikroTik RouterOS | App environment settings | [MikroTik](/docs/setup-sensor/mikrotik#step-4-install-and-configure-orb) |
+| Cisco IOx | `package.yaml` | [Cisco IOx](/docs/setup-sensor/cisco/ioxclient#step-3-create-the-package-descriptor) |
+| Synology NAS | Container environment variables | [Synology](/docs/setup-sensor/synology#pre-configure-orb-optional-) |
+| QNAP NAS | Container environment variables | [QNAP](/docs/setup-sensor/qnap#pre-configure-orb-optional-) |
+| Firewalla | `environment:` in `docker-compose.yml` | [Firewalla](/docs/setup-sensor/firewalla#step-3-install-orb-using-docker-compose) |
+| Proxmox | `/etc/default/orb` | [Proxmox](/docs/setup-sensor/proxmox#pre-configure-orb-optional-) |
+| UniFi routers | `/etc/default/orb` | [UniFi Routers](/docs/setup-sensor/unifi-routers#step-2-install-orb) |
+| WLAN Pi | `/etc/default/orb` | [WLAN Pi](/docs/setup-sensor/wlan-pi#pre-configure-orb-optional-) |
+
+Two rules apply everywhere, whatever the platform:
+
+- **Set it before Orb first starts.** If Orb is already running, apply the change and restart the service — it links on the next start.
+- **Your shell doesn't count.** Orb runs as a service, and service managers do not inherit your shell environment. Exporting the variable in your terminal or `.bashrc` will have no effect; it has to go in the file the service itself reads.
+
+:::note
+The [Home Assistant add-on](/docs/setup-sensor/home-assistant) does not currently expose a Deployment Token option. Link Home Assistant Orbs using [local network discovery](/docs/orb-app/linking-orb-to-account#link-from-the-orb-app-on-the-same-network) instead.
+:::
+
+## Step 4: Install and verify
+
+1. Install Orb using the [guide for your platform](/docs/setup-sensor).
+2. Open [Status](https://cloud.orb.net/status) in Orb Cloud. The new Orb should appear within a minute or two of first start, carrying the Tags from the token's Configuration.
+3. Confirm the Orb is reporting data rather than sitting idle. An Orb linked in "View Only" mode will not collect data.
+
+If the Orb does not appear, see [Troubleshooting](#troubleshooting) below.
+
+## Setting other options at install time
+
+Anything on the [Configuration](/docs/deploy-and-configure/configuration) page can be set the same way, in the same file, at the same time. The ones most worth setting before first start:
+
+| Variable | When to set it |
+| -------- | -------------- |
+| `ORB_EPHEMERAL_MODE=1` | The device stores data on flash that is sensitive to repeated writes — SD cards, NAND on routers and single-board computers. Keeps measurement data in memory only. |
+| `ORB_FIRSTHOP_DISABLED=1` | The device *is* the router. First-hop latency is not meaningful when there is no hop to measure. |
+| `ORB_DEVICE_NAME_OVERRIDE=...` | You want the Orb to arrive in your Space already named, rather than renaming it by hand later. |
+| `ORB_DATA_DIR=...` | Orb's default location is on constrained or volatile storage, and you want data on a different volume. |
+
+Everything attached to the token's Configuration is also applied on link, and can be changed later from [Orchestration](https://cloud.orb.net/orchestration) without touching the device.
+
+## Troubleshooting
+
+**The Orb never appears in your Space.**
+
+- Confirm the variable reached the service, not just your shell. On systemd: `sudo systemctl show orb --property=Environment`. In a container: `docker exec orb-sensor env | grep ORB_`.
+- Check that you edited the file the service actually reads — a token in `~/.bashrc` or `/etc/environment` will not be seen by the Orb service on most platforms.
+- Restart the service after any change. The token is only read at startup.
+
+**The Orb starts but reports a linking error.**
+
+- The Orb is most likely already linked to another Space. Unlink it first — see [Unlinking a sensor](/docs/orb-app/linking-orb-to-account#unlinking-a-sensor).
+- Verify the token was copied whole, including the `orb-dt1-` prefix, with no trailing whitespace or newline.
+
+**The Orb links but sends no data.** Check that "View Only" mode is disabled in the Orb app for that device.
+
+## Related
+
+- [Deployment Tokens](/docs/deploy-and-configure/deployment-tokens) — creating and managing tokens
+- [Configuration](/docs/deploy-and-configure/configuration) — every available environment variable and remote configuration
+- [Linking an Orb to your account](/docs/orb-app/linking-orb-to-account) — all linking methods, including the app-based ones
+- [MDM deployment](/docs/deploy-and-configure/mdm) — Intune, Jamf Pro, and Mosyle walkthroughs
+- [Set up an Orb sensor](/docs/setup-sensor) — install guides for every platform