Scrutiny

In a Hub & Spoke deployment, use a host-id to associate devices with a friendly hostname. This ID is passed from the collector to the web-api during data upload. You can set the host-id using one of three methods:

1. Collector Config File: Define it in your collector.yaml.
2. CLI Argument: Use the --host-id flag when running the collector.
3. Environment Variable: Set the COLLECTOR_HOST_ID variable.

To ensure data is collected periodically, add a cron job via the pfSense webGUI at Services/Cron. Use the following configuration to run the collector every 15 minutes as root and suppress confirmation emails:

• Minute: */15
• Hour: *
• Day of the Month: *
• Month of the Year: *
• Day of the Week: *
• User: root
• Command: /opt/scrutiny/bin/scrutiny-collector-metrics-freebsd-amd64 run --api-endpoint "http://localhost:8080" >/dev/null 2>&1

To install Scrutiny on UnRAID, you first need the Community Applications plugin.

1. Navigate to your UnRAID plugins tab at <UnRaid_IP_Address>/Plugins.
2. Select the 'Install Plugin' tab.
3. Enter the following URL into the input field to install the plugin:

https://raw.githubusercontent.com/Squidly271/community.applications/master/plugins/community.applications.plg

Scrutiny supports a "script" based notification system that executes a custom script whenever a notification is triggered. When the script is executed, Scrutiny provides notification data via the following environment variables:

SCRUTINY_SUBJECT - eg. "Scrutiny SMART error (%s) detected on device: %s"
SCRUTINY_DATE 
SCRUTINY_FAILURE_TYPE - EmailTest, SmartFail, ScrutinyFail
SCRUTINY_DEVICE_NAME - eg. /dev/sda
SCRUTINY_DEVICE_TYPE - ATA/SCSI/NVMe
SCRUTINY_DEVICE_SERIAL - eg. WDDJ324KSO
SCRUTINY_MESSAGE - eg. "Scrutiny SMART error notification for device: %s\nFailure Type: %s\nDevice Name: %s\nDevice Serial: %s\nDevice Type: %s\nDate: %s"
SCRUTINY_HOST_ID - (optional) eg. "my-custom-host-id"

To improve device detection, download the drivedb.h file and run smartctl once to load it into the application.

1. Download the database:

   cd /volume1/@Entware/scrutiny/bin/
   wget https://raw.githubusercontent.com/smartmontools/smartmontools/master/smartmontools/drivedb.h

2. Run smartctl with the --drivedb flag for a specific device:

   smartctl -d sat --all /dev/sda --drivedb=/volume1/@Entware/scrutiny/bin/drivedb.h

To run Scrutiny rootless, you must first create a restricted service account (refer to INSTALL_MANUAL.md for account creation). After creating the account (e.g., scrutiny-svc), you must assign sub-UIDs/GIDs and enable lingering so the services continue running when the user is not logged in.

# Add sub-uids and sub-gids (starting at 500000 to avoid conflicts)
sudo usermod --add-subuids 500000-565535 scrutiny-svc
sudo usermod --add-subgids 500000-565535 scrutiny-svc

# Enable lingering so quadlets stay running without an active session
sudo loginctl enable-linger scrutiny-svc

For users on Windows using WSL with Docker, you can run the database and web interface using Docker Compose.

1. Copy the example.hubspoke.docker-compose.yml file.
2. Remove the collector section from the bottom of the file.
3. Run docker-compose up -d to start the services.

Once completed, the webapp is accessible at http://localhost:8080 (default), though the dashboard will be empty until the collector is configured.

You can enable debug logging and specify a log file for the collector using environment variables (for Docker) or CLI arguments (for direct execution).

Using Docker (Environment Variables):

DEBUG=true
COLLECTOR_LOG_FILE=/tmp/collector.log

Using CLI (Direct Execution):

scrutiny-collector-metrics run --debug --log-file /tmp/collector.log

# Docker environment variables
DEBUG=true
COLLECTOR_LOG_FILE=/tmp/collector.log

# CLI arguments
scrutiny-collector-metrics run --debug --log-file /tmp/collector.log