Documentation

Agents

Agents connect datacenter networks to DCIM so the platform can run local infrastructure operations.
An agent is installed on a server that can reach the infrastructure inside a datacenter. DCIM uses it for PXE, provisioning, remote operations and network tasks that cannot run from the main application server alone.
Open Infrastructure > Agents and use Create Agent.

Host requirements

  • Fresh Ubuntu or Debian server
  • Root access or a user with sudo access
  • Systemd available
  • At least 2 CPU cores
  • At least 2 GB RAM, 4 GB recommended
  • At least 40 GB free disk space

Network requirements

  • Outbound HTTPS access to DCIM, release downloads and package repositories
  • The Agent URL must be reachable from DCIM and from users opening remote console sessions
  • PXE/DHCP/TFTP access to the server network if provisioning will be used
  • BMC access to server management interfaces if power control or remote console will be used
  • Switch management access if switch sync or port actions will be used

Before you install

  • Use a clean server if possible
  • Do not install the agent on the same host as another DHCP or TFTP service when PXE is used
  • Choose the datacenter locations this agent can reach before creating it
  • Have the public or private hostname ready for the Agent URL

Create agent

Select one or more Datacenters where the agent can operate. Use a clear name that identifies the site or role, such as LIS-1 Agent.
A single agent can serve multiple datacenters when it has network access to those locations. Racks can only use agents assigned to their own datacenter.
Set Agent URL to the base URL used by the DCIM API, browsers and PXE clients to reach the agent. Use an absolute http or https URL without a path, query string or credentials.
Leave Auto boot control enabled when the agent should be allowed to set PXE boot automatically through BMC.

Install agent

After creating the agent, DCIM shows the token, environment values, install URL and install command. Copy the install command and run it on the server that will host the agent.
The command shown by DCIM has this format:
Example install command
curl -fsSL 'https://dcim.example.com/agent-install/<token>/install.sh' | sudo bash
Do not reuse the example token above. Use the command generated for the specific agent, because the token belongs to that agent and can expire.
Wait until the agent reports ONLINE. Then open the related rack and assign a compatible agent to it.

Agent installation video

agentctl utilities

The installer creates agentctl on the agent server. Use it when you need to check health, restart services, read logs or update the local agent runtime.
Commands that change services should be run with sudo. Status and version checks can normally be run without it.
Common agent commands
agentctl status
agentctl status --agent
agentctl status --pxe
agentctl doctor
agentctl version
sudo agentctl restart --agent
sudo agentctl restart --pxe
sudo agentctl update
Agent install and update also build the versioned local images used by the Java and HTML5 remote-console runtimes. If one of those images is missing, run sudo agentctl update again. The current-version update restores the missing image without replacing images that are already present.
The service flags limit the command to one part of the agent. --agent targets the DCIM agent service, --pxe targets DHCP and TFTP, and --proxy targets Caddy. Without a flag, service commands use all agent services.
Log commands
agentctl logs --agent --lines 100
agentctl logs --agent --follow
agentctl logs --pxe --lines 200
agentctl logs --proxy --lines 100
Use agentctl doctor when the dashboard shows the agent as offline or degraded. It checks required commands, files, environment values, systemd services, local health and API authentication.

Reset agent locally

Use reset only when this server should be cleaned and prepared for a fresh agent installation. It removes local agent services, files, remote-console containers and generated runtime data.
Reset commands
sudo agentctl reset
sudo agentctl reset --all
agentctl reset keeps downloaded templates and ISOs. agentctl reset --all removes them as well.

Before inventory connections

Inventory connections are only possible after the assigned rack agent is online and linked to the rack datacenter. If the agent is offline, installing, missing or not assigned to that datacenter, DCIM disables actions that depend on that agent.