Skip to content

powershell install script, cleanup #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mignaulo wants to merge 2 commits into
base: main
Choose a base branch
from
Open

powershell install script, cleanup #58

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
14044f6
powershell install, cleanup
mignaulo Jan 29, 2026
fd73cbe
update action and add randomness to trigger
mignaulo Jan 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 96 additions & 85 deletions docs/setup-sensor/windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,34 +8,77 @@ subtitle: 'Difficulty: Beginner 🧑‍💻'
---
# Orb Sensor on Windows

## Install the Orb Sensor on Windows using Chocolatey
## PowerShell Install Script

### Installation

You can install the Orb sensor on Windows using PowerShell by following these steps:
1. Open PowerShell as Administrator.
2. Run the following commands to download and install the Orb sensor:
```powershell
iwr -useb https://pkgs.orb.net/install.ps1 | iex
```
3. Follow the prompts to complete the installation.
Once the installation is complete, you can verify that it succeeded by [looking at the service status](#check-service-status). You can return the previous command in the future to update the Orb sensor to the latest version.

### Management
The installation script also provides additional functions that you can use to manage the Orb sensor:
```powershell
# Install only
iex "& { $(iwr -useb https://pkgs.orb.net/install.ps1) } -InstallOnly"

# Update only
iex "& { $(iwr -useb https://pkgs.orb.net/install.ps1) } -UpdateOnly"

# Uninstall
iex "& { $(iwr -useb https://pkgs.orb.net/install.ps1) } -Uninstall"
```

### Automatic Updates

You can configure Windows Task Scheduler to automatically check for and install Orb updates on a regular schedule.

**Create a Scheduled Task using PowerShell:**

Open PowerShell as Administrator and run:

```powershell
$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument '-NoProfile -WindowStyle Hidden -Command "iwr -useb https://pkgs.orb.net/install.ps1 | iex"'
$trigger = New-ScheduledTaskTrigger -Daily -At 3am -RandomDelay (New-TimeSpan -Hours 1)
$principal = New-ScheduledTaskPrincipal -UserId "SYSTEM" -LogonType ServiceAccount -RunLevel Highest
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable
Register-ScheduledTask -TaskName "Orb Auto Update" -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Description "Automatically updates the Orb sensor daily"
```

## 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:
### Installation
See the [Orb package on Chocolatey](https://community.chocolatey.org/packages/orb) for available versions and package details.
1. Ensure you have [Chocolatey installed](https://chocolatey.org/install#individual) on your Windows machine.
2. Open Command Prompt or PowerShell as Administrator.
3. 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.
### Management

### Manual Updates

To manually update Orb to the latest version, run:
You can uninstall the Orb sensor with:
```cmd
choco uninstall orb
```

You can upgrade the Orb sensor with:
```cmd
choco upgrade orb -y
```

The `-y` flag automatically confirms the upgrade without prompting.

### Automatic Updates with Task Scheduler

### Automatic Updates

To ensure Orb stays up to date automatically, you can set up a Windows Task Scheduler task to run regular updates.

Expand All @@ -44,14 +87,12 @@ 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) `
-Trigger (New-ScheduledTaskTrigger -Daily -At 3am -RandomDelay (New-TimeSpan -Hours 1)) `
-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
Expand All @@ -68,29 +109,21 @@ Start-ScheduledTask -TaskName "Orb Auto-Update"
After Chocolatey updates Orb, the Windows service will automatically restart with the new version.
:::

## Install the Orb Sensor on Windows (manual)
## Manual Installation

### Installation

Setting up a Windows device as an Orb sensor allows you to run continuous network monitoring as a background service.

### Download

#### Download
Download the Orb CLI for Windows from our Early Access page:

[Download Orb CLI for Windows](https://orb.net/the-forge/early-access/orb-cli-for-windows)

:::note
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 the Windows Service

You can install Orb as a Windows service using either PowerShell or the `sc.exe` command.

#### Option 1: Using PowerShell (Recommended)
**PowerShell:**
Open PowerShell as Administrator and run:

```powershell
Expand All @@ -99,10 +132,8 @@ 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

**Command Prompt:**
Open Command Prompt as Administrator and run:

```cmd
sc.exe create Orb binPath= "C:\Program Files\Orb\orb.exe windowsservice" DisplayName= "Orb Sensor Service" start= auto
```
Expand All @@ -111,7 +142,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
#### Start the Service

After creating the service, start it using:

Expand All @@ -124,11 +155,41 @@ Start-Service -Name "Orb"
```cmd
sc.exe start Orb
```

The service will now start automatically on system boot.

## Configuring the Orb Sensor
You can configure the Orb sensor with any options from [Orb Configuration](/docs/deploy-and-configure/configuration) docs.
### Management

**Uninstall:**
First, stop the service, then remove it:

**PowerShell:**
```powershell
Stop-Service -Name "Orb"
Remove-Service -Name "Orb"
```

**Command Prompt:**
```cmd
sc.exe stop Orb
sc.exe delete Orb
```
The Orb.exe file can then be deleted from your system if desired.

## Check Service Status

**PowerShell:**
```powershell
Get-Service -Name "Orb"
```

**Command Prompt:**
```cmd
sc.exe query Orb
```


## Configuration
You can configure the Orb sensor with any options from [Orb Configuration](docs/deploy-and-configure/configuration) docs.

### Environment Variables
To set environment variables for the Orb sensor Windows Service, you can use the `New-ItemProperty` cmdlet in PowerShell.
Expand Down Expand Up @@ -189,56 +250,6 @@ Flags:
-r --remote connect to remote host
```

## Managing the Service

### Stop the Service

**PowerShell:**
```powershell
Stop-Service -Name "Orb"
```

**Command Prompt:**
```cmd
sc.exe stop Orb
```

### Check Service Status

**PowerShell:**
```powershell
Get-Service -Name "Orb"
```

**Command Prompt:**
```cmd
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:**
```powershell
Stop-Service -Name "Orb"
Remove-Service -Name "Orb"
```

**Command Prompt:**
```cmd
sc.exe stop Orb
sc.exe delete Orb
```


## Troubleshooting

If the service fails to start:
Expand Down