Configuring the ConHive Agent

The ConHive Agent’s features and behavior are highly configurable, allowing you to tailor it to your specific needs. Configuration is managed through simple JSON files.

Configuration Fundamentals

Understand these core concepts before you start editing:

• Location: All configuration files are stored in a configs subdirectory within the agent’s main working directory (workdir). The agent usually creates the workdir in the location where it’s first run, unless installed via a method that specifies a different path (like the Linux installer script). You can always find the exact location using the CLI (see below).
• Format: Configurations use the standard JSON (JavaScript Object Notation) format. Ensure your edits result in valid JSON.
• Modularity: The agent is composed of various modules (e.g., Status Manager, Log Manager). Each active module typically has its own corresponding configuration file in the configs directory (e.g., statusmanager.json, logmanager.json). This keeps settings organized.
• Applying Changes: The agent reads its configuration files on startup. Therefore, any changes made to configuration files require the agent to be restarted to take effect.

Managing Configuration Files via CLI

The agent provides command-line tools to help manage configuration files:

1. Find Configuration Location

To find out where your agent’s workdir and configs subfolder are located, run:

# Linux / macOS
./conhive-agent config location

# Windows (PowerShell/CMD)
.\conhive-agent.exe config location

This command prints the full path to the working directory.

2. Create Default Configuration Files

If configuration files are missing, or if you want to start with the default settings for all modules, use this command. It will create the default .json file for each module within the configs directory if it doesn’t already exist.

# Linux / macOS
./conhive-agent config create

# Windows (PowerShell/CMD)
.\conhive-agent.exe config create

Tip: This is useful to see the structure and available options for each module.

3. View Current Configuration

To see the complete configuration currently loaded by the agent (which is a merge of all individual .json files), use:

# Linux / macOS
./conhive-agent config get

# Windows (PowerShell/CMD)
.\conhive-agent.exe config get

This outputs the combined configuration in JSON format to your console.

Editing Configuration Files Manually

Follow these steps to customize the agent’s behavior:

1. Locate the configs Directory: Use the config location command shown above if you’re unsure where it is.
2. Choose the File: Identify the .json file corresponding to the module you want to configure (e.g., agentmanager.json for core settings, statusmanager.json for status checks).
3. Open in Editor: Open the chosen file using your preferred text editor (e.g., nano, vim, VS Code, Notepad++).

   # Example using nano on Linux for the agent manager config
   # Replace /path/to/your/workdir with the actual path
   nano /path/to/your/workdir/configs/agentmanager.json

4. Modify Settings: Carefully edit the values within the JSON structure. Ensure you maintain valid JSON syntax (correct use of quotes "", commas ,, brackets [], and braces {}).
5. Save Changes: Save the file and close the editor.
6. Restart the Agent: For the changes to be applied, restart the ConHive Agent:
   • If running manually in the foreground: Stop the agent (usually Ctrl+C) and start it again (./conhive-agent run or .\conhive-agent.exe run).
   • If running as a systemd service (Linux):

     sudo systemctl restart conhive-agent.service

   • If running via Docker:

     docker restart <your-container-name> # e.g., docker restart conhive-agent

Module-Specific Configuration Parameters

Each module’s .json file contains parameters specific to its function.

• agentmanager.json: Typically controls core agent settings like identification, connection details (if connecting to a platform), API server settings, etc.
• statusmanager.json: Configures intervals for checking system status (CPU, RAM, Disk, Network), thresholds for alerts, etc.
• logmanager.json: Sets the logging level (e.g., DEBUG, INFO, ERROR), log rotation policies (size, age), potential log forwarding rules, etc.
• (Configuration files exist for other modules like processmanager.json, filemanager.json, twinmanager.json, etc.)

How to Find Parameter Details:

• Default Files: The easiest way to see available parameters and their default values is to use the ./conhive-agent config create command and then inspect the generated .json files.
• Modules Documentation: Refer to the Modules documentation for descriptions of what each module does, which often provides context for its configuration options.

Always ensure your JSON syntax is correct after editing. You can use online JSON validators to check your files before restarting the agent if you encounter issues.