Skip to main content

Config

This guide documents technical reference for Breeze configuration files and parameters.

Install Locations​

  • Linux/macOS: /opt/breeze-agent
  • Windows: C:\\Program Files\\Breeze

Common files:

  • etc/agent.conf: main JSON configuration
  • etc/tags: key=value pairs (e.g., environment=prod)
  • app.sh / app.bat: launcher; set ENV/PROXY/CA variables

Scheduling:

  • Linux/macOS: breeze-agent.timer (systemd) or /etc/cron.d/breeze-agent
  • Windows: Task Scheduler task Breeze Agent

agent.conf (JSON)​

Path:

  • Linux/macOS: /opt/breeze-agent/etc/agent.conf
  • Windows: C:\\Program Files\\Breeze\\etc\\agent.conf

Format: JSON with key/value pairs.

Parameters​

Server connection:

  • server_url (string, required): Breeze server endpoint URL, e.g. https://breeze-server.cloudaware.com/

Authentication & security:

  • agent_certificate (path, required): X.509 certificate, e.g. etc/ssl/agent.crt
  • agent_private_key (path, required): private key matching the certificate, e.g. etc/ssl/agent.key

Logging:

  • log_file (path or stream, required): stdout, stderr, or a file path
  • log_level (string/number, required): 0=debug, 1=info, 2=warn, 3=error, 4=fatal, 5=unknown

Directories:

  • lib_dir (path, required): core libraries directory, e.g. lib
  • plugins_dir (path, required): plugins directory, e.g. plugins

Identification:

  • hw_physical ("true"|"false"): use hardware UUID for physical machines

Tags and environment hints (optional):

  • eks.cluster.arn: EKS cluster ARN when metadata is unavailable
  • preferred.descriptor: forced descriptor, e.g. intune

Deprecated (avoid in new deployments):

  • vmware.vmid, vmware.service.uuid

Example​

{
  "server_url": "https://breeze-server.cloudaware.com/",
  "agent_certificate": "etc/ssl/agent.crt",
  "agent_private_key": "etc/ssl/agent.key",
  "log_file": "/var/log/breeze-agent.log",
  "log_level": "2",
  "lib_dir": "lib",
  "plugins_dir": "plugins",
  "hw_physical": "true"
}

Best Practices​

  • Restrict permissions on certificate/key files (e.g., 600)
  • Use absolute paths for security‑sensitive files in production
  • Rotate certificates per policy
  • Use log_level 2 (warn) or higher in production; temporarily lower for troubleshooting

Modifying Configuration​

  1. Stop the scheduled run if needed
  2. Edit etc/agent.conf with elevated permissions
  3. Validate JSON syntax
  4. Run the agent manually (./app.sh -vT) or wait for next schedule
  5. Verify logs for applied changes

Troubleshooting​

  • Permissions and paths: ensure the agent process can read etc/agent.conf, certificate files, plugin directories, and log paths. On Linux/macOS, check ownership and mode bits; on Windows, check the account used by the scheduled task.
  • Invalid JSON: validate agent.conf after each edit. A missing comma, unescaped backslash, or unsupported value can prevent the agent from starting.
  • Certificate mismatch/expiration: verify that agent_certificate and agent_private_key belong to the same key pair and that the certificate is not expired.
  • Proxy or CA changes: if the agent stops connecting after proxy or TLS inspection changes, confirm proxy environment variables and custom CA settings in the launcher script.
  • Stale scheduled runs: after changing configuration, run the agent manually once with verbose logging before waiting for the next scheduled run.

See also: Troubleshooting

Install Directory Structure​

  • etc/: agent configuration
  • etc/ssl/: agent certificate and private key
  • install/: scheduler artifacts (cron/systemd) used by installer
  • lib/: agent core libraries (synchronized with server)
  • lib/breeze/facter/facts.d: core facts
  • plugins/: plugins synchronized with the server