Skip to content

Updated FreeBSD docs #103

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

Updated FreeBSD docs #103

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7238245
Updated FreeBSD docs
mignaulo Jul 17, 2026
0b0fef2
add supported versions
mignaulo Jul 17, 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
170 changes: 34 additions & 136 deletions docs/setup-sensor/freebsd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,179 +9,77 @@ subtitle: 'Difficulty: Beginner 🧑‍💻'

# Install the Orb Sensor on FreeBSD

## Installation
Orb supports FreeBSD 13, 14, and 15. These instructions install Orb with the `pkg` package manager; run the commands below as `root`.

Setting up a FreeBSD system as an Orb sensor allows you to run continuous network monitoring.
## Add the Orb repository and key

### Download

Download the Orb CLI for FreeBSD from our Early Access page:

**AMD64:**
[Download Orb CLI for FreeBSD (AMD64)](https://pkgs.orb.net/earlyaccess/orb-freebsd-amd64.zip)

**ARM64:**
[Download Orb CLI for FreeBSD (ARM64)](https://pkgs.orb.net/earlyaccess/orb-freebsd-arm64.zip)

:::note
The Orb CLI for FreeBSD is currently Early Access software. This is an experimental release that is not yet packaged, does not auto-update, and does not yet run as a service automatically.
:::

After downloading, extract the archive and move the `orb` binary to a location in your PATH (e.g., `/usr/local/bin/orb`):

```bash
unzip orb-freebsd-amd64.zip
sudo mv orb /usr/local/bin/orb
sudo chmod +x /usr/local/bin/orb
```

## Usage

### Running Manually

To start the Orb sensor, run:
Create the directories used by `pkg` and download the Orb repository configuration and public key:

```bash
orb sensor
mkdir -p /usr/local/etc/pkg/repos /usr/local/share/keys
fetch -o /usr/local/etc/pkg/repos/Orb.conf https://pkgs.orb.net/stable/freebsd/Orb.conf
fetch -o /usr/local/share/keys/orb-repo.pub https://pkgs.orb.net/stable/freebsd/repo.pub
```

If you would like to use other CLI functions, you can run:

```bash
orb help
```

for a list of available commands.

### Running as a Service

To run Orb continuously in the background (so it persists after your shell session ends), you can set it up as an rc.d service.
## Install Orb

Create an rc.d script at `/usr/local/etc/rc.d/orb`:
Force-refresh the package catalogue, then install Orb:

```bash
sudo ee /usr/local/etc/rc.d/orb
pkg update -f
pkg install orb
```

Add the following content:
The package installs the Orb service script at `/usr/local/etc/rc.d/orb`.

```bash
#!/bin/sh
#
# PROVIDE: orb
# REQUIRE: NETWORKING
# KEYWORD: shutdown

. /etc/rc.subr

name="orb"
rcvar=orb_enable

command="/usr/local/bin/orb"
command_args="sensor"
pidfile="/var/run/${name}.pid"

orb_user="root"

start_cmd="${name}_start"
stop_cmd="${name}_stop"

orb_start()
{
echo "Starting ${name}."
/usr/sbin/daemon -p ${pidfile} -u ${orb_user} ${command} ${command_args}
}

orb_stop()
{
if [ -f ${pidfile} ]; then
echo "Stopping ${name}."
kill -TERM `cat ${pidfile}`
rm -f ${pidfile}
else
echo "${name} is not running."
fi
}

load_rc_config $name
run_rc_command "$1"
```
## Enable and start Orb

Make the script executable:
Enable Orb at boot and start the service:

```bash
sudo chmod +x /usr/local/etc/rc.d/orb
sysrc orb_enable=YES
service orb start
```

Enable the service to start at boot:
Confirm that Orb is running:

```bash
sudo sysrc orb_enable="YES"
service orb status
```

Start the service:

```bash
sudo service orb start
```

To check the status:

```bash
sudo service orb status
```
## FreeBSD-specific Configuration

To stop the service:
### Measure router responsiveness (optional)

```bash
sudo service orb stop
```
By default, the Orb service runs as the unprivileged `orb` user. With these permissions, Orb cannot measure responsiveness to your router.

:::tip
You can modify `orb_user="root"` in the rc.d script to run Orb as a different user if desired. Make sure that user has appropriate permissions.
:::warning
Running Orb as `root` gives the service full system privileges. Only make this change if measuring router responsiveness is required and you accept the additional security risk.
:::

## Orb CLI Commands

The Orb CLI provides a set of commands to manage your Orb sensors and interact with your Orb account. Below are some common commands you can use:
To run Orb as `root`, set the service user and restart Orb:

```bash
orb [command]
sysrc orb_user=root
service orb restart
```

Available Commands:
```
sensor Run the Orb sensor
listen Connect to a running Orb service
link Link this Orb to an account
version Current version of Orb
summary Show the latest summary for this Orb
help This screen

Flags:
-h, --help help for example
-r --remote connect to remote host
```
### Environment variables (optional)

## 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 (typically `~/.config/orb`) containing your token:
To configure the Orb service with [environment variables](/docs/deploy-and-configure/configuration), create `/usr/local/etc/orb.env`. Each variable must be written as a shell export. For example, to enable ephemeral mode:

```bash
mkdir -p ~/.config/orb
echo "orb-dt1-yourdeploymenttoken678" > ~/.config/orb/deployment_token.txt
export ORB_EPHEMERAL_MODE=1
```

Replace `orb-dt1-yourdeploymenttoken678` with your actual deployment token from the [Orchestration](https://cloud.orb.net/orchestration) section of Orb Cloud.
:::info
[Ephemeral mode](/docs/deploy-and-configure/configuration) stores measurement data in memory instead of a local database. This prevents frequent disk writes, but the locally stored measurement data is lost whenever Orb stops or restarts.
:::

Alternatively, you can use the `ORB_DEPLOYMENT_TOKEN` environment variable:
Restart Orb after creating or changing the environment file:

```bash
ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 orb sensor
service orb restart
```

For more details on deployment tokens and other linking methods, see the [Deployment Tokens](/docs/deploy-and-configure/deployment-tokens) guide.

For instructions on linking your Orb sensor to your account, refer to the [Linking an Orb to Your Account](/docs/orb-app/linking-orb-to-account.md) guide.
Your FreeBSD system is now running an Orb sensor. See [Linking an Orb to your account](/docs/orb-app/linking-orb-to-account.md) to connect it to your Orb account.