diff --git a/docs/deploy-and-configure/configuration.md b/docs/deploy-and-configure/configuration.md index 29380b8..5484c77 100644 --- a/docs/deploy-and-configure/configuration.md +++ b/docs/deploy-and-configure/configuration.md @@ -21,6 +21,8 @@ The following environment variables can be set: | `ORB_FIRSTHOP_DISABLED` | Disables measuring and storing first-hop latency. Should generally be utilized on devices that are acting as a router | `ORB_FIRSTHOP_DISABLED=1` | 1.2 | | `ORB_BANDWIDTH_DISABLED` | Disables perfoming periodic content speed tests | `ORB_BANDWIDTH_DISABLED=1` | 1.2 | | `ORB_DEPLOYMENT_TOKEN` | Sets the [Deployment Token](/docs/deploy-and-configure/deployment-tokens#using-environment-variable) | `ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678` | 1.2 | +| `ORB_EPHEMERAL_MODE` | Sets Orb measurement data storage to in-memory only. Protects flash memory from frequent writes. All measurement data stored on the Orb is lost when Orb is stopped or restarted. | `ORB_EPHEMERAL_MODE=1` | 1.4.0 | +| `ORB_DEVICE_NAME_OVERRIDE` | Sets this Orb's name which appears in Orb apps and Orb Cloud | `ORB_DEVICE_NAME_OVERRIDE=MyDeviceName` | 1.4.1 | ## Remote Configuration @@ -40,4 +42,35 @@ On the Status page, you can select Orbs, click "Apply Configuration", and select ### Configuring Datasets -Orb applications and sensors are capable of producing [Datasets](/docs/deploy-and-configure/datasets) for Scores, Responsiveness, Web Responsiveness, and Speed data. These datasets may be streamed to Orb Cloud, Orb [Local Analytics](/docs/deploy-and-configure/local-analytics), or a destination of your choice. See [Datasets Configuration](/docs/deploy-and-configure/datasets-configuration) for details. \ No newline at end of file +Orb applications and sensors are capable of producing [Datasets](/docs/deploy-and-configure/datasets) for Scores, Responsiveness, Web Responsiveness, and Speed data. These datasets may be streamed to Orb Cloud, Orb [Local Analytics](/docs/deploy-and-configure/local-analytics), or a destination of your choice. See [Datasets Configuration](/docs/deploy-and-configure/datasets-configuration) for details. + +### Configuring Collection of Identifiable Information +Orb can collect attributes of your device and network which may be considered identifiable information (e.g. public IP address, network name, or device MAC address). By default, Orb minimizes the amount of potentially identifiable information collected, collecting enough to make the experience work (like your network name) without collecting more potentially identifiable information (like your device MAC address or private IP). + +Some users may want to see that extra detail in Orb Cloud, Local Analytics, or via Orb APIs to better identify their devices and networks. + +#### Identifiable levels +| Level | Description | +|-------|-------------| +| `none` | Orb will obfuscate any fields that are known to potentially identify your device or network. Your experience in Orb apps and Orb Cloud may be impacted as networks and device details will be obfuscated and it may be hard to tell which device you are looking at. | +| `minimal` | (Default) Orb will not obfuscate some basic potentially identifiable information, like network name, to make the normal Orb app and Orb Cloud user experiences work. Identifiable fields not required for basic app usage, like MAC Address, will still be obfuscated. | +| `full` | Orb will not obfuscate any fields of collected data. | + +#### Configuration + +Identifiable level is controlled via the `orb.identifiable_level` field in Orb Cloud config. + +##### Advanced Configuration Editor +To set the identifiable level using the advanced configuration editor, add the following property to the root of your configuration JSON. + +```json +{ + "orb.identifiable_level": ["full"], + ... +} +``` + +#### Enabling identifiable information in datasets +While `orb.identifiable_level` informs which attributes of your device and network an Orb obfuscates during collection, there is an additonal option to only obfuscate identifiable information in Datasets outputs. + +This allows you to control whether identifiable information is included in Datasets sent to Orb Cloud, Local Analytics, or custom endpoints separately from what is collected. See [Datasets Configuration](/docs/deploy-and-configure/datasets-configuration#identifiable-information) for details. diff --git a/docs/deploy-and-configure/mdm/intune.md b/docs/deploy-and-configure/mdm/intune.md index 93b35db..d794c6c 100644 --- a/docs/deploy-and-configure/mdm/intune.md +++ b/docs/deploy-and-configure/mdm/intune.md @@ -192,3 +192,8 @@ Verify the installation parameters: 2. Check that `/START_IN_BACKGROUND=1` is included for silent operation 3. Verify Windows startup items aren't disabled by Group Policy 4. Verify the `LaunchAtStartup` and `StartInBackground` items exists in the Registry Editor and have values of `1` in `COMPUTER\HKEY_LOCAL_MACHINE\SOFTWARE\Orb\MDM` + +## Additional Configuration Options + +### Device Name Overrides +You can set a custom device name to use during installation by setting the `OrbDeviceNameOverride` item key in the Registry Editor for `COMPUTER\HKEY_LOCAL_MACHINE\SOFTWARE\Orb\MDM`. diff --git a/docs/deploy-and-configure/mdm/jamf-pro.md b/docs/deploy-and-configure/mdm/jamf-pro.md index 5396744..ef78681 100644 --- a/docs/deploy-and-configure/mdm/jamf-pro.md +++ b/docs/deploy-and-configure/mdm/jamf-pro.md @@ -105,6 +105,8 @@ In a text editor, such as Visual Studio Code, create a new file called my-config HideDockIcon + OrbDeviceNameOverride + REPLACE WITH DESIRED NAME (optional) PayloadDisplayName diff --git a/docs/deploy-and-configure/mdm/mosyle.md b/docs/deploy-and-configure/mdm/mosyle.md index 4ffc09e..0b57a0a 100644 --- a/docs/deploy-and-configure/mdm/mosyle.md +++ b/docs/deploy-and-configure/mdm/mosyle.md @@ -115,6 +115,8 @@ In a text editor, such as Visual Studio Code, create a new file called my-config HideDockIcon + OrbDeviceNameOverride + REPLACE WITH DESIRED NAME (optional) PayloadDisplayName diff --git a/docs/setup-sensor/docker.md b/docs/setup-sensor/docker.md index f53b0f0..e886b10 100644 --- a/docs/setup-sensor/docker.md +++ b/docs/setup-sensor/docker.md @@ -42,11 +42,10 @@ Otherwise, read on! ## Step 1: Prepare the Docker Compose file 1. Create a file named `docker-compose.yml` in this directory. -2. Paste the following content exactly into the `docker-compose.yml` file: +2. Paste the one of the following content blocks exactly into the `docker-compose.yml` file: + a. `docker-compose.yml` with [WUD](https://getwud.github.io/wud) for auto-update (**recommended**) ```yaml - version: '3.0' - services: orb-docker: image: orbforge/orb:latest @@ -54,29 +53,59 @@ Otherwise, read on! network_mode: host # Optional: alternatively you can use 'bridge' mode and map ports :7443 and :5353 volumes: - orb-data:/root/.config/orb # Persists Orb configuration + restart: always # Ensures Orb restarts if it stops or on system reboot + labels: + - "wud.watch=true" + - "wud.trigger.include=docker.orb" + # # Optional: Limit resources if needed + # # deploy: # resources: # limits: # memory: 512m - restart: always # Ensures Orb restarts if it stops or on system reboot - labels: - - 'com.centurylinklabs.watchtower.enable=true' # Enable auto-updates with Watchtower - - 'com.centurylinklabs.watchtower.scope=orb' # Scope for Watchtower to monitor - # Optional: Watchtower automatically updates the Orb image when a new version is released - watchtower: - image: containrrr/watchtower - container_name: watchtower + wud: + image: ghcr.io/getwud/wud + container_name: wud restart: unless-stopped volumes: - - /var/run/docker.sock:/var/run/docker.sock # Required to monitor other containers - command: --label-enable --scope orb --cleanup --interval 3600 # Check for updates every hour (3600s) + - /var/run/docker.sock:/var/run/docker.sock + environment: + - WUD_WATCHER_LOCAL_WATCHBYDEFAULT=false + - WUD_TRIGGER_DOCKER_ORB_AUTO=true + - WUD_TRIGGER_DOCKER_ORB_PRUNE=true + # + # Optional: expose WUD web interface (default host port 3000, adjust as needed) + # + # ports: + # - "3000:3000" volumes: orb-data: # Creates a named volume for persistent data ``` + b. `docker-compose.yml` without auto-update (*please ensure some orchestration or process exists to update Orb regularly*) + ```yaml + services: + orb-docker: + image: orbforge/orb:latest + container_name: orb-sensor # Optional: Give the container a specific name + network_mode: host # Optional: alternatively you can use 'bridge' mode and map ports :7443 and :5353 + volumes: + - orb-data:/root/.config/orb # Persists Orb configuration + restart: always # Ensures Orb restarts if it stops or on system reboot + # + # Optional: Limit resources if needed + # + # deploy: + # resources: + # limits: + # memory: 512m + + volumes: + orb-data: # Creates a named volume for persistent data + ``` **Explanation:** - `orb-docker`: Defines the main Orb service. @@ -84,8 +113,8 @@ Otherwise, read on! - `network_mode: host`: **Crucial** for Orb to monitor network traffic directly from the host's network interfaces. - `volumes: - orb-data:/root/.config/orb`: Stores Orb's configuration persistently in a Docker named volume (`orb-data`). - `restart: always`: Keeps the Orb container running. - - `labels`: Used by Watchtower to know this container should be auto-updated. - - `watchtower`: (Optional but recommended) Defines the Watchtower service to automatically update the Orb container when new images are published. + - `labels`: Used by WUD to know this container should be auto-updated. + - `wud`: (Optional but recommended) Defines the WUD service to automatically update the Orb container when new images are published. - `volumes: orb-data:`: Declares the named volume used by the `orb-docker` service. ## Step 2: Start the Orb Container @@ -101,13 +130,13 @@ Otherwise, read on! Depending on your Docker version, you may need to use "`docker compose`" rather than "`docker-compose`". ::: -3. Docker Compose will pull the necessary images (`orbforge/orb` and `containrrr/watchtower`) and start the containers. You can check the status with: +3. Docker Compose will pull the necessary images (`orbforge/orb` and `ghcr.io/getwud/wud`) and start the containers. You can check the status with: ```bash docker-compose ps ``` - You should see `orb-sensor` (or `orb-docker` if you didn't set `container_name`) and `watchtower` with state `Up`. + You should see `orb-sensor` (or `orb-docker` if you didn't set `container_name`) and `wud` with state `Up`. 4. You can view the logs for the Orb container using: ```bash @@ -141,7 +170,7 @@ If your docker container is running on a different network than your phone or co ## You're Done -Congratulations! Your Docker container is now running as an Orb sensor, monitoring your network. Thanks to Watchtower, it will automatically update when new versions are released. +Congratulations! Your Docker container is now running as an Orb sensor, monitoring your network. Thanks to WUD, it will automatically update when new versions are released. ## Troubleshooting @@ -153,12 +182,12 @@ Congratulations! Your Docker container is now running as an Orb sensor, monitori - Make sure the device running the Orb app is on the _exact same_ network/subnet as the Docker host machine. - **Permission Errors (especially volume mounts):** - Using Docker named volumes (`orb-data:` in the example) usually avoids permission issues compared to bind-mounting host directories. If you switched to bind mounts, ensure Docker has the correct permissions to write to the host directory. -- **Watchtower Issues:** - - Check Watchtower logs: `docker-compose logs watchtower`. +- **Auto-update Issues:** + - Check WUD logs: `docker-compose logs wud`. - Ensure the Docker socket is correctly mounted (`/var/run/docker.sock:/var/run/docker.sock`). - **Stopping Orb:** - Navigate to the directory containing `docker-compose.yml` and run `docker-compose down`. -- **Updating Orb Manually (if not using Watchtower):** +- **Updating Orb Manually (if not using WUD):** - Navigate to the directory containing `docker-compose.yml`. - `docker-compose pull orb-docker` (pulls the latest image). - `docker-compose up -d` (recreates the container with the new image). diff --git a/docs/setup-sensor/windows.md b/docs/setup-sensor/windows.md index f0d14d5..4eb95fa 100644 --- a/docs/setup-sensor/windows.md +++ b/docs/setup-sensor/windows.md @@ -6,10 +6,71 @@ section: setup-sensor layout: guides subtitle: 'Difficulty: Beginner 🧑‍💻' --- +# Orb Sensor on Windows -# Install the Orb Sensor on Windows +## Install the Orb Sensor on Windows using Chocolatey -## Installation +Chocolatey is a popular command-line package manager for Windows that simplifies software installation and management. +See the [Orb package on Chocolatey](https://community.chocolatey.org/packages/orb) for available versions and package details. + +0. Ensure you have [Chocolatey installed](https://chocolatey.org/install#individual) on your Windows machine. +1. Open Command Prompt or PowerShell as Administrator. +2. Run the following command to install the Orb sensor and follow the prompts: +```cmd +choco install orb +``` +Once the installation is complete, you can verify that it succeeded by [looking at the service status](#check-service-status). + +## Keeping Orb Up to Date with Chocolatey + +If you installed Orb using Chocolatey, you can easily keep it updated to the latest version. + +### Manual Updates + +To manually update Orb to the latest version, run: + +```cmd +choco upgrade orb -y +``` + +The `-y` flag automatically confirms the upgrade without prompting. + +### Automatic Updates with Task Scheduler + +To ensure Orb stays up to date automatically, you can set up a Windows Task Scheduler task to run regular updates. + +Open PowerShell as Administrator and run: + +```powershell +Register-ScheduledTask -TaskName "Orb Auto-Update" ` + -Action (New-ScheduledTaskAction -Execute "C:\ProgramData\chocolatey\bin\choco.exe" -Argument "upgrade orb -y") ` + -Trigger (New-ScheduledTaskTrigger -Daily -At 3am) ` + -Principal (New-ScheduledTaskPrincipal -UserId "SYSTEM" -LogonType ServiceAccount -RunLevel Highest) ` + -Settings (New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable) ` + -Description "Automatically updates Orb sensor via Chocolatey" +``` + +#### Verify the Scheduled Task + +To verify the task was created successfully: + +```powershell +Get-ScheduledTask -TaskName "Orb Auto-Update" +``` + +You can manually run the task to test it: + +```powershell +Start-ScheduledTask -TaskName "Orb Auto-Update" +``` + +:::note +After Chocolatey updates Orb, the Windows service will automatically restart with the new version. +::: + +## Install the Orb Sensor on Windows (manual) + +### Installation Setting up a Windows device as an Orb sensor allows you to run continuous network monitoring as a background service. @@ -25,12 +86,11 @@ The Orb CLI for Windows is currently Early Access software. After downloading, extract `orb.exe` to a permanent location on your system (e.g., `C:\Program Files\Orb\orb.exe`). -## Setting Up as a Windows Service +### Setting Up as a Windows Service You can install Orb as a Windows service using either PowerShell or the `sc.exe` command. -### Option 1: Using PowerShell (Recommended) - +#### Option 1: Using PowerShell (Recommended) Open PowerShell as Administrator and run: ```powershell @@ -39,7 +99,7 @@ New-Service -Name "Orb" -BinaryPathName "C:\Program Files\Orb\orb.exe windowsser Replace `C:\Program Files\Orb\orb.exe` with the actual path where you placed the Orb executable. -### Option 2: Using sc.exe +#### Option 2: Using sc.exe Open Command Prompt as Administrator and run: @@ -51,7 +111,7 @@ sc.exe create Orb binPath= "C:\Program Files\Orb\orb.exe windowsservice" Display Note the space after `binPath=`, `DisplayName=`, and `start=` in the `sc.exe` command. This is required syntax. ::: -## Starting the Service +### Starting the Service After creating the service, start it using: @@ -67,19 +127,27 @@ sc.exe start Orb The service will now start automatically on system boot. -## Data Storage +## Configuring the Orb Sensor +You can configure the Orb sensor with any options from [Orb Configuration](/docs/deploy-and-configure/configuration) docs. -When running as LocalSystem (the default), Orb saves data in: +### Environment Variables +To set environment variables for the Orb sensor Windows Service, you can use the `New-ItemProperty` cmdlet in PowerShell. -``` -C:\ProgramData\Orb + +Example with `ORB_FIRSTHOP_DISABLED` and `ORB_DEPLOYMENT_TOKEN` environment variables: +```powershell +New-ItemProperty ` + -Path "HKLM:\SYSTEM\CurrentControlSet\Services\Orb" ` + -Name "Environment" ` + -PropertyType MultiString ` + -Value @("ORB_FIRSTHOP_DISABLED=1", "ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678") ``` -## Using Deployment Tokens +### Using Deployment Tokens You can automatically link your Orb sensor to your Orb Cloud Space using a deployment token. This is especially useful for deploying multiple sensors or automating setup. -To use a deployment token, create a file named `deployment_token.txt` in the Orb configuration directory containing your token: +To use a deployment token, you can use the [Environment Variables](#environment-variables) approach above to set `ORB_DEPLOYMENT_TOKEN`, or create a file named `deployment_token.txt` in the Orb configuration directory containing your token: ```cmd echo orb-dt1-yourdeploymenttoken678 > C:\ProgramData\Orb\deployment_token.txt @@ -91,7 +159,15 @@ When the Orb service starts, it will automatically read this file and link to yo For more details on deployment tokens and other linking methods, see the [Deployment Tokens](/docs/deploy-and-configure/deployment-tokens) guide. -## Orb CLI Commands +### Data Storage + +When running as LocalSystem (the default), Orb saves data in: + +``` +C:\ProgramData\Orb +``` + +### Orb CLI Commands The Orb CLI provides a set of commands to manage your Orb sensors and interact with your Orb account. To use these commands, run `orb.exe` directly (not as a service): @@ -141,6 +217,13 @@ sc.exe query Orb ### Uninstall the Service +**Chocolatey Uninstall:** +If you installed Orb using Chocolatey, you can uninstall it with: +```cmd +choco uninstall orb +``` + +**Manual Uninstall:** First, stop the service, then remove it: **PowerShell:** @@ -155,6 +238,7 @@ sc.exe stop Orb sc.exe delete Orb ``` + ## Troubleshooting If the service fails to start: diff --git a/scripts/docker/docker-compose.yml b/scripts/docker/docker-compose.yml index 8d63388..54aaa28 100644 --- a/scripts/docker/docker-compose.yml +++ b/scripts/docker/docker-compose.yml @@ -1,30 +1,37 @@ -version: '3.0' - services: orb-docker: image: orbforge/orb:latest container_name: orb-sensor # Optional: Give the container a specific name - network_mode: host # Required: Allows Orb to see network traffic + network_mode: host # Optional: alternatively you can use 'bridge' mode and map ports :7443 and :5353 volumes: - orb-data:/root/.config/orb # Persists Orb configuration + restart: always # Ensures Orb restarts if it stops or on system reboot + labels: + - "wud.watch=true" + - "wud.trigger.include=docker.orb" + # # Optional: Limit resources if needed + # # deploy: # resources: # limits: # memory: 512m - restart: always # Ensures Orb restarts if it stops or on system reboot - labels: - - 'com.centurylinklabs.watchtower.enable=true' # Enable auto-updates with Watchtower - - 'com.centurylinklabs.watchtower.scope=orb' # Scope for Watchtower to monitor - # Optional: Watchtower automatically updates the Orb image when a new version is released - watchtower: - image: containrrr/watchtower - container_name: watchtower + wud: + image: ghcr.io/getwud/wud + container_name: wud restart: unless-stopped volumes: - - /var/run/docker.sock:/var/run/docker.sock # Required to monitor other containers - command: --label-enable --scope orb --cleanup --interval 3600 # Check for updates every hour (3600s) + - /var/run/docker.sock:/var/run/docker.sock + environment: + - WUD_WATCHER_LOCAL_WATCHBYDEFAULT=false + - WUD_TRIGGER_DOCKER_ORB_AUTO=true + - WUD_TRIGGER_DOCKER_ORB_PRUNE=true + # + # Optional: expose WUD web interface (default host port 3000, adjust as needed) + # + # ports: + # - "3000:3000" volumes: orb-data: # Creates a named volume for persistent data \ No newline at end of file