Skip to main content
Video tutorial · 1:45

Clients

The Clients console — connected edge agents The Clients console — connected edge agents

A client is an edge node running the elchi-client agent next to Envoy. The Clients console is the fleet's remote-control surface: it lists every connected node and is where you send it commands, read its host metrics and logs, and — on cloud hosts — look up network interfaces and available IPs.

The clients list​

Open Clients (/clients) for the list of every registered node in the current project:

GET /api/op/clients?project=<project>&with_service_ips=true
ColumnMeaning
NameThe client (node) name.
StatusLive (connected) or Offline.
HAThe HA pair the node belongs to and its role (Active, Standby, …), or —.
VersionThe elchi-client agent version.
Service IPsCount of downstream service IPs the node serves; expand a row to see them.
CPULive load average per core, for connected nodes.
MemoryLive memory usage, for connected nodes.
Last seenWhen the node last reported in.

The CPU and Memory columns are populated by a bulk statistics command (CLIENT_STATS) sent to all connected clients when the list loads — this is command dispatch (below) used for live telemetry. Use the search box (Find by name, host, IP, OS or version) to filter by name, client id, hostname, OS, arch, version, HA pair name or service IP.

Members of an HA pair are grouped under a header row (HA pair · N of 2 members · members hear each other); a pair in HA mode shows its vacant slot as an awaiting peer row. Searching for a pair name keeps the whole pair together.

New clients are added by installing the agent on the host; they appear here once they register. Row actions are Edit (open the detail page), Delete and, for Owner/Admin on an Elchi OS client that is in no pair, Enable HA mode (see Setting up a pair).

Deleting a client​

Delete first asks for a plain confirmation (Delete Client) and calls DELETE /api/op/clients/:client_id. A client that no service references is removed outright.

If the client is still referenced by services, or is a member of an HA pair, the controller refuses the plain delete and a second dialog opens — Client Still Has Services (or Client Is an HA Pair Member). It shows whether the client is Live or Offline and lists every service record that points at it (Service, Version, Address). From there:

  • Force Delete (DELETE /api/op/clients/:client_id?force=true) is only enabled when the client is offline and the controller allows it. On a live client the button is disabled: remove its services from each service page instead (Manage service → Remove, see Removing a service from an offline client).
  • A force delete detaches records only: the agent is not contacted and nothing is stopped or removed on the host. The service records are detached from the client, GSLB IPs it owned are removed (an IP shared with a live client is kept), its Envoy connection entries and pending deploy intents are dropped, and OpenStack addresses are cleaned up best-effort (failures are reported, not retried). It cannot be undone.
  • On an HA pair member, a force delete frees its slot: the pair runs on with the other member alone (degraded) until a new member is added — see Replacing a failed member. A member that is still connected should leave the pair by unpairing instead.

When it finishes, a Client Force-Deleted report (or Force Delete Stopped Partway, if it stopped after detaching some records) lists the Services detached, GSLB IPs removed / kept, Envoy entries pruned, Deploy intents dropped and OpenStack cleanup results, plus any warnings.

Listener units may still run on the host

If a force-deleted host ever comes back, its Envoy listener units are orphans. Remove them on the host with system listener remove <name> in the Elchi OS console, or sudo elchi-client undeploy-local <listener>-<port> --yes on other hosts.

Client detail​

Clicking a row opens /clients/:client_id:

GET /api/op/clients/:client_id?project=<project>

The header shows a live Live/Offline badge. The tabs are:

  • Overview — identity and connection facts: client id, hostname, OS, architecture, kernel, agent version, last-seen, connect/disconnect time and reason, whether BGP is enabled, cloud/provider (for cloud hosts), and any metadata. It also lists the services running on the node.
  • Network — sub-tabs Interfaces, Route, Routing policy, Routing tables and BGP. On Elchi OS appliances the console owns the interfaces, so Interfaces is view-only there while the rest stays editable. See Network & BGP.
  • Statistics — host resource metrics.
  • Logs — agent and service logs pulled from the node.
  • Apps — the Envoy versions downloaded on the node, and the releases you can install on it.
  • Settings — per-client agent settings.
  • Shield — the node's elchi-shield status and on-disk policy files.
  • Appliance — only on Elchi OS clients (see below).

On a member of an HA pair, the header also shows the pair and the node's role, and the overview has an HA pair panel: pair status, role, priority and epoch, peer, heartbeat paths, data plane, VIPs held here or on the peer, configuration revision and the elchi-ha daemon's state and alarms — see Monitoring a pair.

Orphan listener units​

The Overview tab warns about listener units that run on the host without a service record:

  • Offline client — a Client is offline notice explains that if the host is gone for good you can detach its services from the service page (Manage service → Remove; offline clients can be selected) or delete the client (Delete → Force Delete). Neither contacts the agent.
  • Connected client — the agent reports the <listener>-<adminPort> units it finds on the host (the deployed_listeners registration metadata). Any unit with no matching service record is listed under N listener unit(s) on this host have no service record; these were detached while the host was unreachable (force delete / force remove) and keep running there. The check repeats every 15 seconds.

Remove each orphan on the host:

# Elchi OS console
system listener remove <name>

# any other host
sudo elchi-client undeploy-local <name>-<port> --yes

The agent re-registers afterwards and the notice clears.

The Appliance tab​

Clients running Elchi OS (the agent reports os_id=elchi, or that the network is managed by the OS) get an extra Appliance tab. Its status is read live from the agent, so it is only shown while the appliance is connected; it needs Elchi OS 0.5.0 or later and a recent enough agent, and says so otherwise. Refresh fetches a freshly collected status.

  • Summary — the product name and worst health level, then Version, Hostname, Uptime, Boot slot (running and committed), Slot A / Slot B, Upgraded (the release it was upgraded from, when present) and Collected. Banners flag sections that could not be read, a reboot required to finish installed updates, and a trial boot (running slot differs from the committed one).
  • Health — the appliance's health items (Level, Area, Status), worst first, plus any check that did not answer in time.
  • Upgrade — State, Available, Schedule, Last result and the upgrade history.
  • Firewall — the firewall decision, whether the ruleset is loaded, an unconfirmed change and its revert countdown, SSH from, Open data ports and Operator rules.
  • Network — the Management interface, the Last revert, and warnings for a change that waits for network confirm on the console or a configured card that is not present.
  • Compliance (CIS benchmark) — pass / fail / deviation / n/a counts, when it was checked and when the next run is due, and the failing controls (Control, Title, Evidence). Owners and admins can start a check with Run now (it takes a few minutes).
  • Exports (Owner/Admin) — Support bundle (logs and configuration for support, with tokens, passwords and private keys removed) and Configuration archive (the appliance configuration without proxy binaries, to restore on the console with config import). The appliance builds the file in the background; when it is ready, a Download button streams it through a single-use link. The configuration archive asks for confirmation first: it contains the appliance's control-plane token (and, when set, the admin password hash and egress proxy setting), is not encrypted, and must be stored like a private key.

Sending remote commands​

Remote commands are dispatched by posting to the clients collection:

POST /api/op/clients
{
"type": "CLIENT_STATS",
"clients": [{ "client_id": "edge-01" }],
"command": { "count": 100 }
}

The controller authorizes the command against your role and its type, selects a processor for that type (which validates the body and builds the protobuf message), then fans the command out to the target clients over the command stream — sending directly to clients on this controller and, for clients elsewhere, forwarding through the Registry to the controller that owns them. Responses come back per client, with partial success (one failed client does not abort the rest).

Command types​

Each command type maps to a registered processor on the controller. The verifiable set:

typePurpose
DEPLOYDeploy an Envoy service to the client.
UNDEPLOYRemove a deployed Envoy service from the client.
SERVICEControl the service unit on the host (start / stop / restart / status).
UPDATE_BOOTSTRAPPush an updated Envoy bootstrap to the client.
PROXYProxy/admin operations against the running Envoy (read vs. write distinguished by path).
ENVOY_VERSIONManage the Envoy binary version on the host.
UPGRADE_LISTENERPerform a listener upgrade on the deployment.
NETWORKHost networking — netplan apply/get/rollback, routes, policies, tables (via sub-types).
FRRFRR/BGP routing management.
CLIENT_LOGSFetch host/agent logs from the node.
FRR_LOGSFetch FRR routing logs from the node.
CLIENT_STATSCollect live host statistics (CPU, memory, …).
FILEBEATManage Filebeat config/status on the node.
RSYSLOGManage rsyslog config/status on the node.
SHIELDGet/update the client's elchi-shield config and read its status.
HAHA pair commands on a pair member — configure/unconfigure, failover, maintenance, resend GARP, clear a suspension, start alone, status. Pairs themselves are managed through the HA Pairs API.

Many commands carry a sub-type to select the exact operation — for example the network command uses sub-types such as netplan apply/get/rollback and route/policy/table management, and the service command uses start/stop/restart/status. BGP operations are a large family of FRR sub-types.

Command routing across controllers

When the target client is connected to a different controller, the command is forwarded there transparently via the Registry. If routing is failing for reachable-but-remote clients, check Registry & HA.

OpenStack interface and IP lookups​

For clients running on OpenStack, the console can query the cloud's networking directly (used when assigning fixed IPs or allowed-address-pairs to an Envoy). These lookups go against the OpenStack Neutron API using the project's stored cloud credentials — the client must have provider = openstack.

List a server's interfaces​

GET /api/op/clients/:client_id/openstack/interfaces?os_uuid=<server-uuid>&osp_project=<openstack-project-uuid>&project=<db-project>

Returns each port on the server, enriched with its network and subnet details (name, status, MAC, fixed IPs, allowed address pairs, CIDR, gateway, and so on). All three query parameters are required: os_uuid (the OpenStack server), osp_project (the OpenStack project UUID), and project (the Elchi project whose cloud config supplies the credentials).

Available IPs in a subnet​

GET /api/op/clients/:client_id/openstack/subnets/:subnet_id/available_ips?osp_project=<openstack-project-uuid>&project=<db-project>

Returns the free and used IPs for a subnet — the subnet/network names, CIDR, gateway, the list of available IPs, the list of used IPs, and totals. Availability is computed from the subnet's allocation pools minus the network's in-use addresses and the gateway.

Cloud configuration

These endpoints resolve the OpenStack credentials from the project's cloud settings. Configuring those credentials is covered in Cloud & OpenStack.

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Register a New Elchi OS ApplianceYouTube ↗