Agent Configuration

Overview

Monitoring agents run on every managed node and are responsible for collecting host-level metrics, forwarding logs, and reporting health status to the XIMP platform. Agents are deployed automatically when a node is registered in XDeploy, or manually for nodes outside XDeploy management.

Administrator Access Required — This operation requires the admin role. Contact your Xloud administrator if you do not have sufficient permissions.

Prerequisites

Administrator credentials with the admin role
Access to XDeploy (the Xloud Dashboard) for node management
SSH access to target nodes for manual agent installation

Deploy via XDeploy

Register the node

Navigate to XDeploy → Infrastructure → Nodes → Add Node. Provide the node IP, hostname, and role. XDeploy installs and configures the XIMP agent as part of the node onboarding process.

Verify agent registration

Navigate to Monitor Center > Monitoring (Agents, admin view). The new node appears with status Active within 2–3 minutes of registration.

Check agent status via CLI

ximp agent list --status all

Agent shows ACTIVE and last-seen timestamp is within the scrape interval.

Configure custom scrape targets

If the node runs application-specific metric endpoints (e.g., a database exporter), add them as additional scrape targets:Navigate to Monitor Center > Monitoring (Add Scrape Target, admin view) and provide the endpoint URL and scrape interval.

Metric endpoints must be accessible from the XIMP collector nodes. Ensure security group rules permit inbound connections on the target port from the collector IP range.

Manual Agent Installation

For nodes not managed by XDeploy, install and configure the agent manually.

Install the agent package

Install XIMP agent

apt install ximp-agent

Retrieve an agent token

Generate an agent authentication token from the XIMP portal:

Create agent token

ximp agent token create \
  --node <HOSTNAME> \
  --expires 365d

Store the token securely — it cannot be retrieved after the command completes.

Configure the agent

Edit /etc/ximp/agent.yaml:

/etc/ximp/agent.yaml

server:
  endpoint: https://ximp.xloud.internal:9090
  auth_token: <AGENT_AUTH_TOKEN>

node:
  hostname: compute-node-04
  labels:
    role: compute
    az: zone-a

scrape_interval: 30s
log_paths:
  - /var/log/syslog
  - /var/log/nova/nova-compute.log

Start and enable the agent

Enable and start XIMP agent

systemctl enable --now ximp-agent

Verify agent is running

systemctl status ximp-agent

Agent service is active (running) and registers with XIMP within 30 seconds.

Managing Agent Tokens

Token Operations
Token Rotation

List all agent tokens

ximp agent token list

Create a new token

ximp agent token create --node compute-node-04 --expires 365d

Revoke a token (e.g., for decommissioned nodes)

ximp agent token revoke <TOKEN_ID>

Rotate agent tokens periodically (recommended: every 365 days) or immediately if a node is decommissioned or suspected compromised.

Generate a new token

Create replacement token

ximp agent token create --node compute-node-04 --expires 365d

Update agent configuration

Update /etc/ximp/agent.yaml on the node with the new token, then restart:

Restart agent with new token

systemctl restart ximp-agent

Revoke the old token

Revoke old token

ximp agent token revoke <OLD_TOKEN_ID>

Old token is revoked and agent authenticates successfully with the new token.

Troubleshooting Agents

Symptom	Diagnostic	Resolution
Agent shows `offline`	`systemctl status ximp-agent`	Restart service; check token validity
Agent not in list	`ximp agent list --status all`	Verify token; re-register node
High scrape latency	`ximp agent stats --node <HOST>`	Reduce scrape targets; scale up node resources
Authentication errors	Check `/var/log/ximp/agent.log`	Rotate token; verify endpoint URL

Next Steps

Metric Endpoints

Add custom application scrape targets to agents

Log Collection

Configure which log files are forwarded by each agent

Security

Agent token management and dashboard access control

Troubleshooting

Diagnose agent connectivity and metric collection issues

Core Services

Other Services

Agent Configuration

Overview

Deploy via XDeploy

Register the node

Verify agent registration

Configure custom scrape targets

Manual Agent Installation

Install the agent package

Retrieve an agent token

Configure the agent

Start and enable the agent

Managing Agent Tokens

Generate a new token

Update agent configuration

Revoke the old token

Troubleshooting Agents

Next Steps

Metric Endpoints

Log Collection

Security

Troubleshooting

​Overview

​Deploy via XDeploy

Register the node

Verify agent registration

Configure custom scrape targets

​Manual Agent Installation

Install the agent package

Retrieve an agent token

Configure the agent

Start and enable the agent

​Managing Agent Tokens

Generate a new token

Update agent configuration

Revoke the old token

​Troubleshooting Agents

​Next Steps

Metric Endpoints

Log Collection

Security

Troubleshooting

Overview

Deploy via XDeploy

Manual Agent Installation

Managing Agent Tokens

Troubleshooting Agents

Next Steps