Agent Command-Line Reference

The Server Scout agent provides several command-line options for configuration, troubleshooting, and management. Whilst the agent typically runs as a systemd service, these options are invaluable during initial setup and ongoing maintenance.

Basic Usage

The agent binary is located at /opt/scout-agent/scout-agent and accepts various flags to control its behaviour:

/opt/scout-agent/scout-agent [options]

Connection Options

Setting the Monitoring Server URL

Use the --url flag to specify your Server Scout monitoring server:

scout-agent --url https://monitor.example.com

This sets the endpoint where the agent will send collected metrics. The URL should include the protocol (https:// or http://).

API Key Authentication

The --key flag accepts your 64-character hexadecimal API key:

scout-agent --key 1a2b3c4d5e6f...

This key authenticates your server with the monitoring platform and must be obtained from your Server Scout dashboard.

Collection Timing

Adjusting Collection Intervals

The --interval option controls how frequently the agent collects metrics:

scout-agent --interval 10

This sets the collection cycle to 10 seconds. The default is 5 seconds. Lower values provide more granular monitoring but increase system overhead.

Metric Configuration

Interactive Configuration Menu

Launch the metric configuration interface with:

scout-agent --configure

This presents an interactive menu allowing you to enable or disable optional metrics such as:

  • Extended disk I/O statistics
  • Network interface details
  • Process monitoring
  • Custom application metrics

Changes are saved to the configuration file and apply after the next agent restart.

Operational Commands

Forcing Immediate Collection

To trigger an immediate collection cycle across all monitoring tiers:

scout-agent --refresh

This sends a SIGUSR1 signal to the running agent process, useful for testing configuration changes or obtaining fresh data immediately.

Complete Removal

The --uninstall flag provides complete agent removal:

sudo scout-agent --uninstall

This command:

  1. Stops the systemd service
  2. Removes all agent files and directories
  3. Cleans up configuration files

Root privileges are required, and the system will prompt for confirmation before proceeding.

Environment Variables

As an alternative to command-line flags, you can use environment variables:

| Variable | Equivalent Flag | Description | |----------|----------------|-------------| | MONITORURL | --url | Monitoring server URL | | MONITORKEY | --key | API authentication key | | MONITORINTERVAL | --interval | Collection interval in seconds | | MONITORCONFIG | N/A | Path to configuration file |

Example using environment variables:

export MONITOR_URL="https://monitor.example.com"
export MONITOR_KEY="1a2b3c4d5e6f..."
export MONITOR_INTERVAL="10"
scout-agent

Configuration Files

The agent uses two primary configuration files:

Main Configuration

Location: /opt/scout-agent/scout.conf

Contains metric collection settings, enabled modules, and operational parameters set through the --configure option.

Environment Configuration

Location: /opt/scout-agent/agent.env

Stores environment variables including connection details and collection intervals. This file is sourced by the systemd service.

Service Integration

The agent typically runs as a systemd service called scout-agent. When using command-line options for configuration, remember to:

  1. Stop the service before making changes
  2. Update the environment file if needed
  3. Restart the service to apply new settings
sudo systemctl stop scout-agent
sudo systemctl start scout-agent
sudo systemctl status scout-agent

Troubleshooting Usage

Command-line options are particularly useful when diagnosing issues:

  • Use --url and --key to test connectivity with different credentials
  • Employ --interval 1 for high-frequency debugging
  • Run --refresh to verify the agent responds to signals
  • Execute --configure to review current metric settings

These options provide the flexibility needed for effective server monitoring whilst maintaining the simplicity of automated service operation.

Frequently Asked Questions

How do I set up the ServerScout agent with my monitoring server URL?

Use the --url flag to specify your Server Scout monitoring server: scout-agent --url https://monitor.example.com. The URL should include the protocol (https:// or http://). You can also set this using the MONITOR_URL environment variable as an alternative to command-line flags.

What command-line options are available for the ServerScout agent?

The main options include --url for setting the monitoring server, --key for API authentication, --interval for collection timing, --configure for metric settings, --refresh for immediate collection, and --uninstall for complete removal. The agent binary is located at /opt/scout-agent/scout-agent.

How do I troubleshoot ServerScout agent connection issues?

Use command-line options for debugging: test connectivity with different credentials using --url and --key, employ --interval 1 for high-frequency debugging, run --refresh to verify the agent responds to signals, and execute --configure to review current metric settings.

How does the ServerScout agent metric collection interval work?

The --interval option controls how frequently the agent collects metrics, specified in seconds. For example, scout-agent --interval 10 sets collection to every 10 seconds. The default is 5 seconds. Lower values provide more granular monitoring but increase system overhead.

What environment variables can I use instead of command-line flags?

You can use MONITOR_URL (equivalent to --url), MONITOR_KEY (equivalent to --key), MONITOR_INTERVAL (equivalent to --interval), and MONITOR_CONFIG for configuration file path. These are stored in /opt/scout-agent/agent.env and sourced by the systemd service.

How do I completely uninstall the ServerScout agent?

Run sudo scout-agent --uninstall to completely remove the agent. This command stops the systemd service, removes all agent files and directories, and cleans up configuration files. Root privileges are required and the system will prompt for confirmation before proceeding.

How do I configure which metrics the ServerScout agent collects?

Use scout-agent --configure to launch an interactive configuration menu. This allows you to enable or disable optional metrics including extended disk I/O statistics, network interface details, process monitoring, and custom application metrics. Changes are saved to the configuration file and apply after restart.

Was this article helpful?

Related Articles