Skip to content

Installation

simob is shipped as a single binary. There are two ways to obtain the binary. Either using prebuilt binaries that are built from our Github repo. Or you can compile the agent yourself.

Once you have the binary, the install process depends on your OS platform and the desired level of control you want to have. You can use an automatic install script for an automated setup (recommended) or do a manual install by following our step-by-step guide.

Before starting, you should get a server key from your Simple Observability account. It's used by the agent to authenticate itself with our platform. Get it by adding a new server from app.simpleobservability.com

The following details install instructions for:

Linux

You can install simob on Linux with a single command:

curl -fsSL https://simpleobservability.com/install.sh | sudo bash -s -- <SERVER_KEY>

Note

Replace <SERVER_KEY> with the server key from your simpleobservability.com account.

This command downloads our install script (install.sh) and executes it with sudo.

The script does the following:

  1. Downloads the latest agent binary for your system architecture.
  2. Installs the binary in /opt/simob and creates a symlink in /usr/local/bin.
  3. Creates a dedicated simob-agent user and simob-admins group for security isolation.
  4. Grants simob-agent and simob-admins read and write access to the install directory.
  5. Grants journal access to this custom user.
  6. Runs the initial configuration (via simob init) with your provided server key.
  7. Configures and enables a systemd service for automatic startup.

Info

The install script is fully documented with verbose comments and is designed to be easy to read, understand, and audit before execution.

Install without sudo

A non-sudo install is available, but it is mainly meant for testing and not a production use case.

The script does the following:

  1. Downloads the latest agent binary for your system architecture.
  2. Installs the binary in $HOME/.local/simob and creates a symlink in $HOME/.local/bin.
  3. Runs the initial configuration (via simob init) with your provided server key.

This method completely skips the dedicated user part and the systemd service.

Warning

Because the systemd service is skipped, the simob agent cannot run as a persistent daemon in the background automatically. To set up your own service, check the service configuration section.

Install flags

The install script accepts the following flags:

Flag Description
--no-system-read Skips granting the service system-wide read access (CAP_DAC_READ_SEARCH).
--no-journal-access Skips granting access to the system journal.
--skip-key-check Skips validation of the server key at the start of the script.

The install script also uses the following environment variables:

Environment Variable Description
BINARY_PATH Local path to a binary. When set, the script uses this file instead of downloading one.
SKIP_TELEMETRY When set to 1, disables sending the anonymized error-telemetry message.

Systemd service configuration

The default service file configuration used in the install script (for sudo mode) is: 

[Unit]
Description=simob daemon
After=network.target

[Service]
Type=simple
ExecStart=<INSTALL PATH> start
Restart=always
User=<USER USED>
Group=<GROUP USED>
# Prevent gaining any further privileges
NoNewPrivileges=yes
# Mount /usr, /boot, /etc read-only
ProtectSystem=full
# Isolate /home, /root, /run/user
ProtectHome=yes
# Private /tmp and /var/tmp
PrivateTmp=true

[Install]
WantedBy=multi-user.target

By default, we also add system-wide read access by adding to the [Service] block: 

# Grant read/search access to the filesystem (bypassing some permission checks)
AmbientCapabilities=CAP_DAC_READ_SEARCH
CapabilityBoundingSet=CAP_DAC_READ_SEARCH
This is skipped if the install script is called with --no-system-read flag.

Note

The system-wide read capability (controlled by the CAP_DAC_READ_SEARCH capability) is not strictly essential for the agent to function. However, if this capability is not granted to the agent, you must manually grant read access to the simob agent user for every single log file that you wish to collect outside of the standard systemd journal.

Privacy

The only case where the script sends data to our server is a simple anonymous telemetry message that is sent if a certain error is triggered. This allows us to improve the installation process.

If you do not want this, use the SKIP_TELEMETRY environment variable.

Verification

After installation, you can verify that the agent is correctly installed and running using the following commands:

  • Confirm that the installation was successful and that the simob binary is correctly located within your system's $PATH environment variables. If the command executes and returns a version number, the binary is accessible. 

    simob version

  • Determine if the agent is actively running as a daemon in the background (which should be the case if you used the recommended sudo installation with systemd). The output will confirm the agent's current operational state.

    • Using the agent command: 

      simob status
      Expected output if running: [✔] simob is running.

    • Using systemd: 

      systemctl status simob
      Expected output if running: The status should show Active: active (running).

Troubleshooting

If the agent is not reporting data, use these steps to diagnose potential issues.

Restarting the service

If the status check above indicated that the service is not running, attempt to start it. 

sudo systemctl start simob
If the agent fails to start or remains inactive after attempting to start it, proceed to check the logs.

Checking agent logs

The most crucial step in troubleshooting is reviewing the agent's logs to identify startup errors, configuration problems, or communication failures. Since the agent is managed by systemd, use journalctl:

  • View recent logs: 

    sudo journalctl -u simob --since "10 minutes ago"

  • Follow live logs (for real-time startup diagnosis): 

    sudo journalctl -u simob -f

Windows

You can install simob on Windows by running the following command in an Administrator PowerShell terminal:

iwr 'https://simpleobservability.com/install.ps1' -OutFile "$env:TEMP\install.ps1"; & "$env:TEMP\install.ps1" -ApiKey <SERVER_KEY>

Note

Replace <SERVER_KEY> with the server key from your simpleobservability.com account.

This command downloads our install script (install.ps1), stores it in a temporary directory, and executes it with the provided server key.

The script performs the following actions:

  1. Downloads the latest agent binary for your system architecture.
  2. Installs the binary into Program Files\SimpleObservability\simob.
  3. Runs the initial configuration using simob init with your server key.
  4. Configures and enables a Windows Service so the agent runs automatically in the background.

Install without admin rights

A full installation of simob is not possible without Administrator privileges.

This is because:

  • Writing to Program Files requires elevation.
  • Creating or managing a Windows Service always requires admin rights.

Install flags

The install script accepts the following flags:

Flag Description
-SkipKeyCheck Skips validation of the server key at the beginning of the script.
-SkipTelemetry Disables sending the anonymized error-telemetry message on exit.

The install script also uses the following environment variable:

Environment Variable Description
BINARY_PATH Local path to a binary. When set, the script will use this file instead of downloading a release binary.

Privacy

The only case where the script sends data to our server is a simple anonymous telemetry message that is sent if a certain error is triggered. This allows us to improve the installation process.

If you do not want this, use the -SkipTelemetry flag.