Data Structure and Backup

Understanding how the ConHive Agent organizes its data is crucial for configuration, troubleshooting, and performing backups, especially when running in standalone mode.

📂 Agent Working Directory (workdir)

When the ConHive Agent runs, it uses a working directory (often referred to as workdir) to store all its operational data, including configurations, logs, and databases.

• Finding the Location: The exact location of the workdir can vary depending on the installation method and operating system.

  • A common default location might be ~/.conhive/agent/ on Linux or a similar path in the user profile on Windows.
  • However, the most reliable way to find the actual location on your system is to use the agent’s built-in command:

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

• Typical Structure: Inside the workdir, you will typically find the following subdirectories:

  • configs/: Contains the JSON configuration files for each individual agent module (e.g., agentmanager.json, statusmanager.json).
  • data/: Stores runtime data required by the agent and its modules.
  • logs/: Holds the agent’s log files, recording its activities and potential errors.

💾 Data Folder (workdir/data/)

This folder is the primary storage location for the agent’s operational data.

• SQLite Database: It typically contains a SQLite database file (.db). The agent uses this database to store information related to its state, managed items, or module-specific data. Tables within the database are usually created and managed automatically by the agent.
• Other Data: Depending on the enabled modules and configuration, this folder might also contain subdirectories for specific data types (e.g., temporary files, module-specific caches).

🗒️ Logs Folder (workdir/logs/)

This folder contains log files that record the agent’s activities, status updates, warnings, and errors.

• Purpose: Essential for monitoring the agent’s behavior and troubleshooting issues.
• Rotation: Log files are typically generated automatically and rotated (e.g., daily) to manage disk space, ensuring you have access to recent activity logs without files growing indefinitely. Configuration for logging behavior (level, rotation) is usually found in logs/logmanager.json.

⚙️ Configuration Files (workdir/configs/)

As mentioned, the configs directory holds the individual JSON configuration files for each module.

• Modularity: This structure allows for flexible and organized configuration.
• Defaults: If a configuration file for a specific module is missing, the agent will typically fall back to built-in default settings for that module. You can generate default files using ./conhive-agent config create.

🔄 Backup and Recovery

When the ConHive Agent operates in standalone mode (not connected to a central platform), all its operational data is stored locally within the workdir. Regularly backing up this data is crucial to prevent data loss in case of hardware failure or other issues.

Method 1: Manual Backup

You can manually back up the essential agent data.

1. Stop the Agent (Recommended): While SQLite is resilient, stopping the agent ensures data consistency during the copy process.
   • Service: sudo systemctl stop conhive-agent.service
   • Manual: Ctrl+C or kill <PID>
   • Docker: docker stop <container_name>
2. Copy Key Data: Copy the following directories/files from your workdir to a secure backup location (e.g., external drive, network share):
   • The entire data/ directory (especially the SQLite .db file within it).
   • The configs/ directory (to preserve your custom settings).
3. Restart the Agent: Restart the agent after the copy is complete.

Method 2: Automatic Database Backup

The agent may support configuring automatic backups for its SQLite database.

• Configuration: This feature is enabled and configured within one of the agent’s JSON configuration files.

  Example Configuration Snippet:

  // IMPORTANT: Add this snippet to the correct configuration file!
  // (e.g., agentmanager.json or a dedicated backup config file - Verify in module docs)
  {
    // ... other settings ...
    "database_backup": { // Key name might vary, verify in docs
      "enabled": true, // Set to true to enable automatic backups
      "folder": "backup", // Subdirectory within workdir to store backups (e.g., workdir/backup/)
      "maxAgeDays": 7, // How long to keep backups (e.g., delete backups older than 7 days)
      "intervalHours": 12 // How often to perform a backup (e.g., every 12 hours)
    }
    // ... other settings ...
  }

• Verification Needed:

  • You must identify the correct .json configuration file (e.g., agentmanager.json, databasemanager.json?) where this database_backup (or similar) section should be placed. Consult the specific module documentation or default configuration files.
  • Verify the exact key names (database_backup, enabled, folder, etc.) used by your agent version.
  • The folder path is typically relative to the workdir.

• Recovery from Auto-Backup: To restore from an automatic backup, you would typically stop the agent, replace the current SQLite file in the data/ folder with a desired backup copy from the backup/ folder, and then restart the agent.