diff --git a/docs/deploy-and-configure/README.md b/docs/deploy-and-configure/README.md index 16f87cc..7830487 100644 --- a/docs/deploy-and-configure/README.md +++ b/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 diff --git a/docs/deploy-and-configure/deployment-tokens.md b/docs/deploy-and-configure/deployment-tokens.md index d0bef63..9853f74 100644 --- a/docs/deploy-and-configure/deployment-tokens.md +++ b/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,32 @@ 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. +::: -```bash -export ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 -``` +**[Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install)** lists that file for every supported platform: -Adding this line to your shell's configuration is outside of the scope of this document. +| Platform | Where `ORB_DEPLOYMENT_TOKEN` goes | +| -------- | --------------------------------- | +| Ubuntu, Debian, Raspberry Pi OS, RHEL/Fedora/CentOS, Arch | [`/etc/default/orb`](/docs/deploy-and-configure/preconfigure-at-install#linux-with-systemd) | +| Alpine and other OpenRC systems | [`/etc/conf.d/orb`](/docs/deploy-and-configure/preconfigure-at-install#alpine-linux-and-other-openrc-systems) | +| OpenWrt, GL.iNet | [`/etc/config/orb`](/docs/deploy-and-configure/preconfigure-at-install#openwrt) | +| Docker, Synology, QNAP, Firewalla, Proxmox | [container `environment:`](/docs/deploy-and-configure/preconfigure-at-install#docker) | +| Podman | [quadlet `Environment=`](/docs/deploy-and-configure/preconfigure-at-install#podman) | +| Windows | [service registry key or installer flag](/docs/deploy-and-configure/preconfigure-at-install#windows) | +| macOS | [MDM profile, or a token file for Homebrew](/docs/deploy-and-configure/preconfigure-at-install#macos) | +| MikroTik RouterOS | [app environment settings](/docs/deploy-and-configure/preconfigure-at-install#mikrotik-routeros) | +| Cisco IOx | [`package.yaml`](/docs/deploy-and-configure/preconfigure-at-install#cisco-iox) | -:::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 +108,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/deploy-and-configure/preconfigure-at-install#freebsd) and [Homebrew on macOS](/docs/deploy-and-configure/preconfigure-at-install#macos). + ### 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. diff --git a/docs/deploy-and-configure/preconfigure-at-install.md b/docs/deploy-and-configure/preconfigure-at-install.md new file mode 100644 index 0000000..7e57b6a --- /dev/null +++ b/docs/deploy-and-configure/preconfigure-at-install.md @@ -0,0 +1,317 @@ +--- +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 | + +All three are read at startup, so set them **before you first start Orb**. If Orb is already running, apply the change and restart the service — it will link on the next start. + +:::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 + +| Platform | Where the configuration goes | +| -------- | ---------------------------- | +| Ubuntu, Debian, Raspberry Pi OS, RHEL/Fedora/CentOS, Arch | [`/etc/default/orb`](#linux-with-systemd) | +| Alpine Linux and other OpenRC systems | [`/etc/conf.d/orb`](#alpine-linux-and-other-openrc-systems) | +| OpenWrt, GL.iNet | [`/etc/config/orb`](#openwrt) | +| Docker | [`environment:` in `docker-compose.yml`](#docker) | +| Podman | [`Environment=` in the quadlet](#podman) | +| Windows (service) | [Service registry key](#windows) or `deployment_token.txt` | +| Windows (app, at scale) | [Installer flag or Intune](#windows) | +| macOS (app) | [MDM configuration profile](#macos) | +| macOS (Homebrew CLI) | [`deployment_token.txt`](#macos) | +| FreeBSD | [`deployment_token.txt`](#freebsd) | +| MikroTik RouterOS | [App environment settings](#mikrotik-routeros) | +| Cisco IOx | [`package.yaml`](#cisco-iox) | +| Synology, QNAP, Firewalla, Proxmox | [Container environment variables](#nas-and-appliance-platforms) | + +### Linux with systemd + +This covers Ubuntu, Debian, Raspberry Pi OS, RHEL, Fedora, CentOS, Arch, and most other mainstream distributions installed via `https://pkgs.orb.net/install.sh`. + +The `orb` systemd service reads `/etc/default/orb`. Create it before installing, or create it and restart the service afterwards: + +```bash +sudo tee /etc/default/orb >/dev/null <<'EOF' +ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 +EOF +``` + +If Orb is already installed, apply it with: + +```bash +sudo systemctl restart orb +``` + +:::note +`/etc/default/orb` is a systemd environment file, not a shell script. Use plain `KEY=VALUE` lines — no `export`, no quotes, and no shell expansion (`$OTHER_VAR` will not be substituted). +::: + +Related install guides: [Linux](/docs/setup-sensor/linux), [Raspberry Pi](/docs/setup-sensor/raspberry-pi), [UniFi Routers](/docs/setup-sensor/unifi-routers). + +### Alpine Linux and other OpenRC systems + +The OpenRC service reads `/etc/conf.d/orb`. Unlike systemd, OpenRC sources this file as a shell script, so the variables **must be exported** to reach the Orb process: + +```bash +cat > /etc/conf.d/orb <<'EOF' +export ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 +EOF +``` + +If Orb is already installed: + +```bash +rc-service orb restart +``` + +Related install guide: [Alpine Linux](/docs/setup-sensor/linux/alpine). + +### OpenWrt + +OpenWrt uses a UCI config file at `/etc/config/orb`, with one `list env` entry per variable: + +```bash +cat << EOF > /etc/config/orb +config orb 'orb' + list env 'ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678' + list env 'ORB_DATA_DIR=/root' + list env 'ORB_EPHEMERAL_MODE=1' + list env 'ORB_LOG_CONSOLE_FORMAT=syslog' +EOF +``` + +Create this file **before** running the install script — the Orb service starts as soon as the package is installed. If Orb is already running: + +```bash +/etc/init.d/orb restart +``` + +Related install guides: [OpenWrt](/docs/setup-sensor/linux/openwrt#step-2-pre-configure-orb-recommended-), [GL.iNet Brume 2](/docs/setup-sensor/gl-mt2500-standalone). + +### Docker + +Add the variable to the `environment:` section of your `docker-compose.yml`: + +```yaml +services: + orb-docker: + image: orbforge/orb:latest + container_name: orb-sensor + network_mode: host + volumes: + - orb-data:/root/.config/orb + restart: always + environment: + - ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 +``` + +Then `docker compose up -d`. If the container is already running, `docker compose up -d` recreates it with the new environment. + +Related install guides: [Docker](/docs/setup-sensor/docker), [Docker Multi-WAN](/docs/setup-sensor/docker-multiple-interfaces). + +### Podman + +Add an `Environment=` line to the `[Container]` section of your quadlet at `/etc/containers/systemd/orb-sensor.container`: + +```ini +[Container] +AutoUpdate=registry +Image=docker.io/orbforge/orb:latest +ContainerName=orb-sensor +Network=host +AddCapability=CAP_NET_RAW +Volume=orb-data:/root/.config/orb:z +Environment=ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 +``` + +Then reload and restart: + +```bash +systemctl daemon-reload +systemctl restart orb-sensor +``` + +Related install guide: [Podman Quadlet](/docs/setup-sensor/podman). + +### Windows + +**Running the sensor as a Windows service:** the service reads environment variables from its own registry key. Set them with PowerShell, then restart the service: + +```powershell +New-ItemProperty ` + -Path "HKLM:\SYSTEM\CurrentControlSet\Services\Orb" ` + -Name "Environment" ` + -PropertyType MultiString ` + -Value @("ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678") + +Restart-Service -Name "Orb" +``` + +Alternatively, drop a token file into the Orb configuration directory: + +```cmd +echo orb-dt1-yourdeploymenttoken678 > C:\ProgramData\Orb\deployment_token.txt +``` + +**Deploying the Windows app at scale:** pass the token to the installer directly, which is how the Intune guide provisions machines: + +``` +Orb-installer.exe /S /LAUNCH_AT_STARTUP=1 /START_IN_BACKGROUND=1 /ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 +``` + +Related guides: [Windows sensor](/docs/setup-sensor/windows#using-deployment-tokens), [Microsoft Intune](/docs/deploy-and-configure/mdm/intune). + +### macOS + +**The macOS app** runs in a restricted sandbox and has no access to your shell environment, so environment variables do not work. Deliver the token as a managed app setting through an MDM configuration profile — see the [Jamf Pro](/docs/deploy-and-configure/mdm/jamf-pro) or [Mosyle](/docs/deploy-and-configure/mdm/mosyle) guides. For a one-off machine, you can instead paste the token into the app directly (see [Using the apps](/docs/deploy-and-configure/deployment-tokens#using-the-apps)). + +**The Homebrew CLI sensor** does read environment variables, but `brew services` generates its own launchd plist, so the reliable way to pre-configure it is the token file: + +```bash +mkdir -p ~/.config/orb +echo "orb-dt1-yourdeploymenttoken678" > ~/.config/orb/deployment_token.txt +brew services restart orbforge/orb/orb +``` + +If you run the sensor in the foreground yourself, the environment variable works as expected: + +```bash +ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 orb sensor +``` + +Related install guide: [macOS sensor](/docs/setup-sensor/macos). + +### FreeBSD + +The FreeBSD rc.d service does not source an environment file, so use the token file in the config directory of the user the service runs as. With the rc.d script from the install guide, that user is `root`: + +```bash +mkdir -p /root/.config/orb +echo "orb-dt1-yourdeploymenttoken678" > /root/.config/orb/deployment_token.txt +service orb restart +``` + +Related install guide: [FreeBSD](/docs/setup-sensor/freebsd#using-deployment-tokens). + +### MikroTik RouterOS + +Set the token under the app's **Environment** settings in WebFig before enabling the app, or from the terminal — note that values must be prefixed with the service name `orb:`: + +```routeros +/app/set [find name=orb-sensor] network=lan use-https=no auto-update=yes environment="orb:ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678,orb:ORB_FIRSTHOP_DISABLED=1" +/app/enable [find name=orb-sensor] +``` + +Related install guide: [MikroTik](/docs/setup-sensor/mikrotik). + +### Cisco IOx + +The token is baked into the IOx package at build time, in the `env` section of `package.yaml`: + +```yaml + ORB_DEPLOYMENT_TOKEN: orb-dt1-yourdeploymenttoken678 +``` + +Because the token travels with the package, every device you deploy that package to links itself automatically — and the configuration survives updates. Build one package per token if you need to separate deployments. + +Related install guides: [Cisco IOx overview](/docs/setup-sensor/cisco), [Building the IOx package](/docs/setup-sensor/cisco/ioxclient#building-the-iox-package). + +### NAS and appliance platforms + +Synology (Container Manager), QNAP (Container Station), Firewalla, and Proxmox all run Orb as a container. Set `ORB_DEPLOYMENT_TOKEN` wherever that platform exposes container environment variables — the "Environment" tab of the container's settings, or the `environment:` section of the `docker-compose.yml` you deploy. See [Docker](#docker) above for the syntax. + +:::note +The Home Assistant add-on 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. +::: + +Related install guides: [Synology](/docs/setup-sensor/synology), [QNAP](/docs/setup-sensor/qnap), [Firewalla](/docs/setup-sensor/firewalla), [Proxmox](/docs/setup-sensor/proxmox). + +## 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 diff --git a/docs/orb-app/linking-orb-to-account.md b/docs/orb-app/linking-orb-to-account.md index 5a97b9d..8879b3d 100644 --- a/docs/orb-app/linking-orb-to-account.md +++ b/docs/orb-app/linking-orb-to-account.md @@ -7,9 +7,14 @@ section: Orb app # Linking an Orb to Your Account -This guide explains how to link Orb sensors to your account, allowing you to monitor multiple devices or locations from all Orb app instances. +Linking an Orb sensor to your account (or your Orb Cloud Space) is what makes it visible from every Orb app you're signed in to, and what lets you manage its configuration centrally. -## What is an Orb Sensor? +This guide covers every way to link an Orb. If you're not sure which to use: + +- **One or two Orbs on your own home network** → [link from the Orb app on the same network](#link-from-the-orb-app-on-the-same-network). +- **Anything else — a remote site, a fleet, a device you won't have hands on** → [pre-configure a Deployment Token at install time](#pre-configure-a-deployment-token-at-install-time). + +## What is an Orb sensor? An Orb sensor is any device running the Orb software that monitors network connectivity. This can be: @@ -18,83 +23,99 @@ An Orb sensor is any device running the Orb software that monitors network conne - A dedicated device like a Raspberry Pi running the Orb agent - A router with Orb monitoring capabilities -## Benefits of Linking Multiple Sensors - -Linking multiple sensors to your account provides several advantages: - -- Monitor different networks (home, office, vacation property) -- Compare wired vs. wireless performance -- Track network health in different parts of your home -- Have a dedicated 24/7 monitoring device while still using the mobile app +Linking multiple sensors to one account lets you monitor different networks (home, office, vacation property), compare wired against wireless performance, track network health in different parts of a building, and keep a dedicated 24/7 monitoring device running while still using the mobile app. -## Linking Methods - -Orbs can be linked to your account via the device running Orb or remotely. - -:::tip -If you are managing and deploying many Orbs, or have complex configuration needs, consider utilizing [Deployment Tokens](/docs/deploy-and-configure/deployment-tokens). -::: +## Signing in on a device running the Orb app -### Orb on Your Phone, Desktop, or Tablet - -If you have the Orb app installed on your phone, tablet, or desktop, you can link it to your account by signing in. +If you have the Orb app installed on your phone, tablet, or desktop, that device links itself when you sign in. 1. Install the Orb app on the new device 2. Open the app and tap "Sign In" 3. Enter your Orb account email and password 4. The device will automatically be added as a sensor to your account -### Orb on Another Device (e.g., Raspberry Pi) +Headless sensors — a Raspberry Pi, a router, a container — have no app to sign in to, so they use one of the methods below. -#### Automatic Discovery (Recommended) +## Link from the Orb app on the same network -If your new Orb sensor is on the same local network as a device already signed in to your Orb account: +**Best for simple home networks.** If a new Orb sensor is on the same local network as a device already signed in to your Orb account, the app will find it for you. -1. Install Orb on the new device -2. Start the app and wait for the automatic discovery process -3. On your already-linked device, you'll receive a notification about the new sensor -4. Tap "Link to my account" to connect the sensor +1. Install Orb on the new device and let it start +2. Open the Orb app on your already-linked phone or computer, on the same network +3. You'll receive a notification about the newly discovered sensor +4. Tap "Link to my account" to connect it Auto Link -#### Manually Linking a Discovered Sensor +This depends on mDNS/Bonjour (UDP port 5353) working between the two devices. Many corporate, guest, and segmented networks block it, and it won't cross subnets or VLANs at all — which is why it is only recommended for simple home networks. + +## Pre-configure a Deployment Token at install time + +**Best for everything else, and the primary path for deploying Orbs at scale.** Instead of linking the Orb after it starts, you give it a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) before it starts. The Orb links itself to your Space on first run — no app, no LAN discovery, no shell on the device. + +This also applies the token's Configuration and Tags at link time, so every Orb you deploy with a given token arrives already configured the same way, and can be reconfigured later from Orb Cloud. + +In outline: + +1. Copy a Deployment Token from the [Orchestration](https://cloud.orb.net/orchestration) section of Orb Cloud +2. Set `ORB_DEPLOYMENT_TOKEN` in the config file the Orb service reads on your platform — `/etc/default/orb` on most Linux systems, `/etc/config/orb` on OpenWrt, the `environment:` block for containers, the service registry key on Windows, an MDM profile on macOS +3. Install Orb and confirm the sensor appears in [Status](https://cloud.orb.net/status) + +The exact file to edit for each platform, and the other options worth setting at the same time, are in **[Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install)**. -If you want to link an Orb sensor that was automatically discovered (listed under "Orbs on this network"): +:::tip +Setting the variable in your shell is not enough — service managers don't inherit your shell environment. The pre-configuration guide covers where it actually needs to go on each platform. +::: + +If you'd rather link an existing Orb with a token by hand, you can also paste a Deployment Token directly into the Orb app: tap the device menu (dots), select "Link to a Space", and enter the token. See [Using the apps](/docs/deploy-and-configure/deployment-tokens#using-the-apps). + +## Alternate linking methods + +These work, but are more error-prone than the two methods above and generally shouldn't be your first choice. + +### Manually linking a discovered sensor + +If a sensor was automatically discovered and is listed under "Orbs on this network" but wasn't linked: 1. In the Orb Summary, find the Orb sensor you would like to link (see "Orbs on this network") 2. Tap on the Orb settings menu (... near the sensor name) -3. Tap "Link this Orb to your account" - Note: this method will only work for headless/CLI devices (e.g., Raspberry Pi). To manually link a device running the Orb app, sign into your account from this device. +3. Tap "Link this Orb to your account" Account Link -#### Linking a Sensor from the CLI +:::note +This method only works for headless/CLI devices (e.g. a Raspberry Pi). To link a device running the Orb app, sign into your account from that device instead. +::: -If the newly started Orb sensor is not automatically discovered, you can link it manually using the command line interface: +### Linking a sensor from the CLI + +If the sensor isn't discovered and wasn't pre-configured, you can link it from a shell on the device. This requires access to the device and a browser session, so it does not scale well. 1. Open a terminal on the device -2. Run the `orb link` command - Note: this command needs to be run as the same user that runs the Orb Sensor. - You could use `su` to switch to that user before running the command, or you can use `sudo` to run the command as that user directly. - On most systems (Debian, Redhat, Alpine), this is typically the `orb` user. For OpenWRT variants, it is typically the `root` user. +2. Run the `orb link` command as the same user that runs the Orb sensor. + Use `su` to switch to that user first, or `sudo` to run the command as that user directly. On most systems (Debian, Redhat, Alpine) this is the `orb` user; on OpenWrt variants it is typically `root`. - For example, if you are using Debian or Redhat, you can run: + For example, on Debian or Redhat: ```bash sudo -u orb orb link ``` -3. The output of that command will include a short URL to link to your account -4. Copy that URL into a browser on any machine, and log in to your account at the prompt -5. That Orb will now show up in any app where you’re logged in +3. The output of that command will include a short URL +4. Open that URL in a browser on any machine and log in to your account at the prompt +5. That Orb will now show up in any app where you're logged in :::info -If utilizing containers, see the sections on linking with [Docker](/docs/setup-sensor/docker#device-on-a-different-network) and [Podman](/docs/setup-sensor/podman#step-3-link-your-new-orb-sensor). +For containers, see the linking sections for [Docker](/docs/setup-sensor/docker#device-on-a-different-network) and [Podman](/docs/setup-sensor/podman#step-3-link-your-new-orb-sensor). ::: -## Managing Linked Sensors +### Guest Orb invitations + +To link Orbs on devices you don't administer — guests on a campus, hotel, or venue network — see [Guest Orbs](/docs/deploy-and-configure/guest-orbs). -### Naming Your Orb Sensors +## Managing linked sensors + +### Naming your Orb sensors After linking a sensor, it's helpful to give it a descriptive name: @@ -107,7 +128,9 @@ After linking a sensor, it's helpful to give it a descriptive name: Rename Orb 2 -### Unlinking a Sensor +You can also name an Orb before it ever starts, using `ORB_DEVICE_NAME_OVERRIDE` — see [Setting other options at install time](/docs/deploy-and-configure/preconfigure-at-install#setting-other-options-at-install-time). + +### Unlinking a sensor If you need to remove a sensor from your account: @@ -117,22 +140,29 @@ If you need to remove a sensor from your account: Remove Orb -Note that unlinking a sensor will not delete historical data already collected from that sensor. +Unlinking a sensor will not delete historical data already collected from that sensor. + +An Orb can only belong to one Space at a time. If linking fails because the Orb is already linked elsewhere, unlink it here first. ## Troubleshooting -### Sensor Not Discovered Automatically +### Sensor not discovered automatically If automatic discovery fails: -- Ensure both devices are on the same local network -- Check that your network allows device discovery (some corporate or public networks restrict this) -- Try the CLI linking method instead +- Ensure both devices are on the same local network and subnet +- Check that your network allows device discovery — mDNS/Bonjour on UDP port 5353 is commonly blocked on corporate and guest networks +- Use [pre-configuration with a Deployment Token](/docs/deploy-and-configure/preconfigure-at-install) instead, which doesn't depend on discovery at all + +### Pre-configured Orb didn't link + +See [Troubleshooting](/docs/deploy-and-configure/preconfigure-at-install#troubleshooting) in the pre-configuration guide. -## Next Steps +## Next steps Now that you've linked your sensors, learn more about: +- [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install.md) - [Orb summary view](/docs/orb-app/orb-summary-view.md) - [App Settings](/docs/orb-app/app-settings.md) - [Notifications](/docs/orb-app/notifications.md) diff --git a/docs/setup-sensor/README.md b/docs/setup-sensor/README.md index 0f7d6f9..dca2b2c 100644 --- a/docs/setup-sensor/README.md +++ b/docs/setup-sensor/README.md @@ -13,6 +13,15 @@ An Orb sensor is the Orb software that continuously monitors your network connec The Orb app can be installed on phones, tablets, or computers and runs an Orb sensor while active. However, for continuous monitoring, we recommend setting up a dedicated device (like a Raspberry Pi or a spare phone) that runs an Orb sensor 24/7. You can access the information from this device through any Orb app. +## Before you install: pre-configure and link + +Orb sensors work best when linked to your Orb Cloud Space for central viewing and management. You have two good options to link sensors: + +- **A simple home network, one or two Orbs** — install first, then link from the Orb app on the same network. Each install guide below ends with these steps. +- **Anything else** — put a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) in place *before* the sensor first starts, and it links itself with the right configuration and tags already applied. This is the recommended path for remote sites, fleets, and any device you won't have hands on. + +[Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install) shows exactly which config file to use on each platform. [Linking an Orb to your account](/docs/orb-app/linking-orb-to-account) covers every linking method. + ## Choosing the Right Device The best sensor device for you depends on your specific needs: diff --git a/docs/setup-sensor/docker.md b/docs/setup-sensor/docker.md index c191ca6..7469529 100644 --- a/docs/setup-sensor/docker.md +++ b/docs/setup-sensor/docker.md @@ -156,6 +156,17 @@ Depending on your Docker version, you may need to use "`docker compose`" rather ## Step 3: Link your new Orb sensor +### Pre-configured with a Deployment Token (recommended) + +If you add a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) to the container's `environment:` section before starting it, the sensor links itself to your Orb Space on first start and there is nothing else to do: + +```yaml + environment: + - ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 +``` + +Run `docker compose up -d` to apply it, then confirm the sensor appears on the [Status](https://cloud.orb.net/status) page in Orb Cloud. This is the only linking method that works regardless of network topology, mDNS, or shell access — see [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install). + ### Device on the same network If your Docker container is running on the same network as your phone or computer and your network supports Bonjour/zeroconf, you can link it to your account using the Orb app. diff --git a/docs/setup-sensor/firewalla.md b/docs/setup-sensor/firewalla.md index bfcb905..511e040 100644 --- a/docs/setup-sensor/firewalla.md +++ b/docs/setup-sensor/firewalla.md @@ -98,6 +98,14 @@ Now, create the Orb configuration and start the container: - ORB_FIRSTHOP_DISABLED=1 ``` + Add a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) line here as well, and the sensor will link itself to your Orb Space on first start, letting you skip Step 4 entirely: + + ```yaml + - ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 + ``` + + See [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install) for details. + Start the Orb sensor in the background. Orb will automatically be kept up-to-date. See [Install Orb on Docker](/docs/setup-sensor/docker) for more details. ```bash diff --git a/docs/setup-sensor/linux/README.md b/docs/setup-sensor/linux/README.md index 2388888..e47fabc 100644 --- a/docs/setup-sensor/linux/README.md +++ b/docs/setup-sensor/linux/README.md @@ -20,6 +20,26 @@ curl -fsSL https://pkgs.orb.net/install.sh | sh On supported platforms, the installation will provide a prompt (y/n) asking if you would like to enable automated updates to keep Orb up to date. We recommend enabling automated updates. +## Pre-configure before installing (recommended) + +Rather than installing first and linking afterwards, you can put a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) in place beforehand so the sensor links itself to your Orb Space the first time it starts. + +On distributions using systemd — Ubuntu, Debian, Raspberry Pi OS, RHEL, Fedora, CentOS, Arch — the Orb service reads `/etc/default/orb`: + +```bash +sudo tee /etc/default/orb >/dev/null <<'EOF' +ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 +EOF +``` + +On Alpine and other OpenRC systems, use `/etc/conf.d/orb` instead, and `export` each variable. + +Any other [configuration](/docs/deploy-and-configure/configuration) option can go in the same file. See [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install) for details, other platforms, and troubleshooting. + +## Linking + +If you didn't pre-configure a Deployment Token, link the sensor after installing — see [Linking an Orb to your account](/docs/orb-app/linking-orb-to-account). + ## Advanced Installation Options For detailed manual installation steps for specific Linux distributions, please see the following pages: diff --git a/docs/setup-sensor/linux/alpine.md b/docs/setup-sensor/linux/alpine.md index 4255dea..754c9ac 100644 --- a/docs/setup-sensor/linux/alpine.md +++ b/docs/setup-sensor/linux/alpine.md @@ -18,6 +18,22 @@ echo https://pkgs.orb.net/stable/alpine | tee -a /etc/apk/repositories wget -O /etc/apk/keys/packages@orb.net.rsa.pub https://pkgs.orb.net/stable/alpine/orb.pub ``` +Pre-configure Orb (recommended) + +Alpine runs Orb under OpenRC, which reads `/etc/conf.d/orb`. Creating this file before installing lets you set a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) so the sensor links itself to your Orb Space on first start. + +```bash +cat > /etc/conf.d/orb <<'EOF' +export ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 +EOF +``` + +:::warning +OpenRC sources this file as a shell script, so each variable must be `export`ed or the Orb process will not see it. This differs from `/etc/default/orb` on systemd distributions, which takes bare `KEY=VALUE` lines. +::: + +Any other [configuration](/docs/deploy-and-configure/configuration) option can go in the same file — see [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install). If Orb is already installed, apply changes with `rc-service orb restart`. + Update package list and install Orb ```bash diff --git a/docs/setup-sensor/linux/openwrt.md b/docs/setup-sensor/linux/openwrt.md index 89d65c7..840cb22 100644 --- a/docs/setup-sensor/linux/openwrt.md +++ b/docs/setup-sensor/linux/openwrt.md @@ -41,8 +41,11 @@ Before you begin, make sure you have: 3. If prompted about the authenticity of the host, type `yes` and press Enter. 4. Enter the root password for your OpenWrt device when prompted. You should now have a command prompt logged into your OpenWrt device. -## Step 2: Pre-configure Orb (Optional) -You can optionally create a configuration file to customize Orb behavior from the start. You can set a deployment token to automatically link this Orb to your Orb Space, or adjust other settings. See the [configuration docs](/docs/deploy-and-configure/configuration) for all available options. +## Step 2: Pre-configure Orb (Recommended) + +Creating `/etc/config/orb` before you install lets you set a [Deployment Token](/docs/deploy-and-configure/deployment-tokens), so this Orb links itself to your Orb Space the moment it starts — no discovery or manual linking needed in Step 4. You can set any other [configuration](/docs/deploy-and-configure/configuration) option here at the same time. + +On OpenWrt the Orb service reads its environment from this UCI config file, one `list env` entry per variable. Create it **before** running the install script, since Orb starts as soon as the package is installed. 1. Create the configuration file: @@ -56,6 +59,12 @@ You can optionally create a configuration file to customize Orb behavior from th EOF ``` + Replace `` with the token from the [Orchestration](https://cloud.orb.net/orchestration) section of Orb Cloud. + +:::tip +For the equivalent file on other platforms, and the other options worth setting before first start, see [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install). +::: + ## Step 3: Install Orb 1. At the OpenWrt command prompt, run the following command exactly as shown: @@ -72,14 +81,18 @@ You can optionally create a configuration file to customize Orb behavior from th - Enable auto-updates to keep Orb up-to-date. 3. Wait for the script to complete. You should see output indicating the progress of the installation. -## Step 4: Link your new Orb Sensor (Optional) +## Step 4: Link your new Orb Sensor + +If you set a Deployment Token in Step 2, your Orb has already linked itself — check the [Status](https://cloud.orb.net/status) page in Orb Cloud and skip to the end. -If you didn't configure a Deployment Token to auto-link your new Orb in Step 2, you can link it to your Orb Space now. +Otherwise, link it from the Orb app: 1. Once the installation script finishes, the Orb Sensor should be running on your OpenWrt device. -2. Open the Orb app on your phone or personal computer. +2. Open the Orb app on your phone or personal computer, on the same network. 3. Your new Orb Sensor should be automatically detected on your network and appear in the app, ready to be linked to your account. Follow the prompts in the app to link it. +For other linking options, see [Linking an Orb to your account](/docs/orb-app/linking-orb-to-account). + Congratulations! Your OpenWrt device is now running as an Orb Sensor, monitoring your network. ## Troubleshooting @@ -112,7 +125,7 @@ Add the Orb public key curl https://pkgs.orb.net/stable/openwrt/key.pub | tee /etc/opkg/keys/744a82bfef3c5690 ``` -Optionally, you can create a configuration file to customize Orb behavior from the start. You can set a deployment token to automatically link this Orb to your Orb Space, or adjust other settings. See the [configuration docs](/docs/deploy-and-configure/configuration) for all available options. +Create a configuration file to customize Orb behavior from the start (recommended). Setting a deployment token here automatically links this Orb to your Orb Space on first start. See [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install) and the [configuration docs](/docs/deploy-and-configure/configuration) for all available options. ```bash cat << EOF > /etc/config/orb diff --git a/docs/setup-sensor/macos.md b/docs/setup-sensor/macos.md index a72881a..a4bf892 100644 --- a/docs/setup-sensor/macos.md +++ b/docs/setup-sensor/macos.md @@ -27,6 +27,22 @@ To start orbforge/orb/orb immediately and restart at login: brew services start orbforge/orb/orb ``` +## Linking with a Deployment Token + +To have the sensor link itself to your Orb Space on first start, place a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) in Orb's configuration directory before starting the service: + +```bash +mkdir -p ~/.config/orb +echo "orb-dt1-yourdeploymenttoken678" > ~/.config/orb/deployment_token.txt +brew services restart orbforge/orb/orb +``` + +A token file is used here rather than an environment variable because `brew services` generates its own launchd job and won't pass through your shell environment. If you run the sensor in the foreground yourself, `ORB_DEPLOYMENT_TOKEN=... orb sensor` works as expected. + +See [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install#macos) for details, and the [MDM guides](/docs/deploy-and-configure/mdm) for deploying the macOS app across a fleet. + +## Other CLI usage + If you don't want or need a background service or would like to use other CLI functions, you can run: ```bash diff --git a/docs/setup-sensor/podman.md b/docs/setup-sensor/podman.md index 06732d0..ddeed45 100644 --- a/docs/setup-sensor/podman.md +++ b/docs/setup-sensor/podman.md @@ -121,6 +121,10 @@ Quadlets are systemd unit files with a `.container` extension that define contai ## Step 3: Link your new Orb sensor +:::tip +You can skip this step entirely by adding an `Environment=ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678` line to the `[Container]` section of the quadlet before starting it. The sensor then links itself to your Orb Space on first start, with no discovery or CLI step. See [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install#podman). +::: + 1. Once the Orb container is running, it should start broadcasting its presence on your network. 2. Open the Orb app on your phone or personal computer (which must be on the same network). 3. Your new Podman-based Orb sensor should be automatically detected and appear in the app, ready to be linked to your account. Follow the prompts in the app to link it. diff --git a/docs/setup-sensor/proxmox.md b/docs/setup-sensor/proxmox.md index b2c071e..d8482c6 100644 --- a/docs/setup-sensor/proxmox.md +++ b/docs/setup-sensor/proxmox.md @@ -56,6 +56,10 @@ If you have a Proxmox cluster and want to monitor multiple nodes, repeat Step 1 ## Step 4: Link Your Orb to Your Account +:::tip +When adding several nodes, pre-configure a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) instead of linking each one by hand — every node then links itself on first start with identical configuration. See [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install). +::: + The final step is to link your new Orb sensor(s) to your account: 1. Open the Orb app on your mobile device or computer. diff --git a/docs/setup-sensor/qnap.md b/docs/setup-sensor/qnap.md index 8a6819d..2125b63 100644 --- a/docs/setup-sensor/qnap.md +++ b/docs/setup-sensor/qnap.md @@ -64,6 +64,10 @@ Now you're ready to launch the Orb sensor: ## Step 5: Link Your Orb to Your Account +:::tip +You can skip this step by adding `ORB_DEPLOYMENT_TOKEN` to the container's environment variables in Container Station before starting it — the sensor then links itself to your Orb Space on first start. See [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install). +::: + The final step is to link your new Orb sensor to your account: 1. Open the Orb app on your mobile device or computer. diff --git a/docs/setup-sensor/raspberry-pi.md b/docs/setup-sensor/raspberry-pi.md index 0df6231..fdc8caa 100644 --- a/docs/setup-sensor/raspberry-pi.md +++ b/docs/setup-sensor/raspberry-pi.md @@ -72,20 +72,45 @@ When prompted with **"Use OS customization?"**, click **"EDIT SETTINGS"** and co 6. Enter your password and press Enter (the cursor will not move as you type). 7. You are now connected when you see: `orb@raspberrypi-orb:~$` -## Step 4: Install the Orb Service +## Step 4: Pre-configure Orb (Optional) + +The Orb service on Raspberry Pi OS reads its environment from `/etc/default/orb`. Creating this file before you install lets you set a [Deployment Token](/docs/deploy-and-configure/deployment-tokens) — so the sensor links itself to your Orb Space on first start, with no discovery or manual linking needed — along with any other settings you want applied from the beginning. ```bash -curl -fsSL https://pkgs.orb.net/install.sh | sh +sudo tee /etc/default/orb >/dev/null <<'EOF' +ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 +ORB_EPHEMERAL_MODE=1 +EOF ``` +Replace the token with the one from the [Orchestration](https://cloud.orb.net/orchestration) section of Orb Cloud, or leave that line out if you'd rather link from the Orb app in Step 6. + :::info -If you are using an SD card as instructed in this guide (rather than using an M.2 hat), it is recommended you run your Orb in [ephemeral mode](/docs/deploy-and-configure/configuration) to preserve the life of your SD card and prevent your Orb sensor from failing. To do so, add the line `ORB_EPHEMERAL_MODE=1` to `/etc/default/orb` +If you are using an SD card as instructed in this guide (rather than using an M.2 hat), it is recommended you run your Orb in [ephemeral mode](/docs/deploy-and-configure/configuration) to preserve the life of your SD card and prevent your Orb sensor from failing. That's the `ORB_EPHEMERAL_MODE=1` line above. ::: -## Step 5: Link to your Orb account +:::tip +`/etc/default/orb` is a systemd environment file — use plain `KEY=VALUE` lines, with no `export` and no quotes. The same file works on Ubuntu, Debian, RHEL, Fedora, CentOS, and Arch. See [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install) for the equivalent on every other platform, and for the full list of options worth setting here. +::: + +If Orb is already installed when you create or edit this file, apply it with `sudo systemctl restart orb`. + +## Step 5: Install the Orb Service + +```bash +curl -fsSL https://pkgs.orb.net/install.sh | sh +``` + +## Step 6: Link to your Orb account + +If you set a Deployment Token in Step 4, your Orb has already linked itself — check the [Status](https://cloud.orb.net/status) page in Orb Cloud, or open the Orb app, and you're done. + +Otherwise: 1. Once the installation script finishes, the Orb sensor should be running on your Raspberry Pi device. -2. Open the Orb app on your phone or personal computer. +2. Open the Orb app on your phone or personal computer, on the same network. 3. Your new Orb sensor should be automatically detected on your network and appear in the app, ready to be linked to your account. Follow the prompts in the app to link it. +For other linking options, see [Linking an Orb to your account](/docs/orb-app/linking-orb-to-account). + Congratulations! Your Raspberry Pi is now running as an Orb sensor, monitoring your network. diff --git a/docs/setup-sensor/synology.md b/docs/setup-sensor/synology.md index 2defe2c..2611590 100644 --- a/docs/setup-sensor/synology.md +++ b/docs/setup-sensor/synology.md @@ -101,6 +101,10 @@ You can verify the container is running by checking its status in the Container ## Step 8: Link Your Orb to Your Account +:::tip +You can skip this step by adding `ORB_DEPLOYMENT_TOKEN` to the container's environment variables in Container Manager before starting it — the sensor then links itself to your Orb Space on first start. See [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install). +::: + The final step is to link your new Orb sensor to your account: 1. Open the Orb app on your mobile device or computer diff --git a/docs/setup-sensor/windows.md b/docs/setup-sensor/windows.md index e28faed..042510a 100644 --- a/docs/setup-sensor/windows.md +++ b/docs/setup-sensor/windows.md @@ -218,7 +218,9 @@ Replace `orb-dt1-yourdeploymenttoken678` with your actual deployment token from When the Orb service starts, it will automatically read this file and link to your Space. -For more details on deployment tokens and other linking methods, see the [Deployment Tokens](/docs/deploy-and-configure/deployment-tokens) guide. +Set this before the service first starts, or restart the service afterwards with `Restart-Service -Name "Orb"` — the token is only read at startup. + +For more details on deployment tokens and other linking methods, see the [Deployment Tokens](/docs/deploy-and-configure/deployment-tokens) guide and [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install#windows). To deploy the Windows app across a fleet, see [Microsoft Intune](/docs/deploy-and-configure/mdm/intune). ### Data Storage diff --git a/navigation.md b/navigation.md index 4d2e1e5..676d796 100644 --- a/navigation.md +++ b/navigation.md @@ -71,6 +71,7 @@ - [Datasets](/docs/deploy-and-configure/datasets.md) - [Local Analytics](/docs/deploy-and-configure/local-analytics.md) - [Deployment Tokens](/docs/deploy-and-configure/deployment-tokens.md) +- [Pre-configure at install](/docs/deploy-and-configure/preconfigure-at-install.md) - [MDM](/docs/deploy-and-configure/mdm) - [Guest Orbs](/docs/deploy-and-configure/guest-orbs) - [Endpoints & Engines](/docs/deploy-and-configure/endpoints)