Control Server

Control Server

logme can optionally run a built-in control server that allows runtime inspection and management of the logging system without restarting the application.

The control server speaks a simple telnet-like, line-based CLI protocol over TCP, and can be used from the bundled logmectl utility or from your own tooling.

See also: Getting Started – JSON-based Setup, Configuration JSON – control

---

When to use it

The control server is useful for long-running processes where a full restart is undesirable:

• quickly check which channels exist and what they output
• enable/disable channels at runtime
• change log level and output flags for a channel
• add/remove backends (with default settings) for troubleshooting
• adjust subsystem reporting rules

---

Enabling the server

From JSON configuration

The control server can be configured in JSON via the control object:

{
  "control": {
    "enable": true,
    "interface": "127.0.0.1",
    "port": 9010,
    "pass": "secret"
  }
}

Notes:

• interface is an IPv4 address string (127.0.0.1, 0.0.0.0, etc.) or localhost.
• pass enables per-connection authentication (see Authentication below).
• TLS can be enabled via cert/key PEM strings, but for most applications it is recommended to set the certificate programmatically (to avoid keeping a private key in a JSON file).

From C++ code

Logme::ControlConfig c{};
c.Enable = true;
c.Port = 9010;
c.Interface = /* IPv4 address */;
c.Cert = nullptr;
c.Key = nullptr;
c.Password = "secret";

logger.StartControlServer(c);

To stop the server:

logger.StopControlServer();

---

TLS (encrypted connections)

If a TLS certificate is configured, the control server accepts TLS only connections. You can set the certificate and key programmatically:

logger.SetControlCertificate(cert, key);

Client side: use logmectl --ssl to connect.

---

Authentication

If a password is configured (control.pass / ControlConfig::Password), the server requires the client to authenticate per connection.

• Before authentication, most commands return: error: unauthorized
• Authenticate using:

auth <password>

Responses:

• ok — authenticated
• error: invalid password — wrong password
• error: missing password — command was sent without a password

If no password is configured, auth always returns ok and is effectively a no-op.

Client side: logmectl --pass <password> performs authentication automatically for the session.

---

Output formats

Text (default)

All commands return human-readable text. Errors start with error:.

JSON

For machine parsing, wrap any command using:

format json <command...>

Example:

format json list

The JSON wrapper format:

{
  "ok": true,
  "error": null,
  "data": {
    "text": "<original text response>",
    "...": "optional parsed fields"
  }
}

data.text always contains the original text response.

Additional parsed fields are currently provided for:

• list → data.channels (array of channel names, default channel is "")
• level → data.level
• flags → data.value (integer), data.names (array of enabled flag names)
• subsystem → data.blockReportedSubsystems (bool), data.reportedSubsystems (array)

Client side: logmectl --format json ... automatically wraps the command using format json.

---

Using logmectl

logmectl is a small CLI client that connects to the control server and executes a command.

logmectl -p <port> [-i <ip>] [--ssl] [--pass <password>] [--format text|json] <command...>

Examples:

logmectl -p 9010 help
logmectl -p 9010 list
logmectl -p 9010 channel logme
logmectl -p 9010 --pass secret level --channel logme debug
logmectl -p 9010 --format json flags --channel logme

---

Command reference

Command names are case-insensitive.

help

Prints a compact list of supported commands.

list

List all channels.

• The default channel is shown as <default> in text mode.
• In JSON mode it is represented as an empty name "" in data.channels.

channel

Show channel information or manage channels.

channel [name]
channel --create <name>
channel --delete <name>
channel --enable <name>
channel --disable <name>

Notes:

• The default channel is represented by an empty name "" and cannot be deleted.
• channel [name] prints details such as status, flags, level, link target and backends. (Some clients may render small HTML fragments like enable/disable links; treat the response as plain text.)

level

Get or set the channel filter level.

level [--channel <name>] [debug|info|warn|error|critical]

• If --channel is omitted, the default channel is used.
• Common aliases are accepted: information, warning, err, crit.

flags

Get or set output flags for the channel.

flags [--channel <name>] [flag[=value] ...]

• If no flags are provided, prints current flags (hex value + names).
• For boolean flags, accepted values include: true/false, 1/0, on/off, yes/no.

Supported flags:

• timestamp = none|local|tz|utc or integer
• location = none|short|full or integer
• console = cout|cerr|warncerr|errcerr|cerrcerr or integer
• signature (bool)
• method (bool)
• eol (bool)
• errorprefix (bool)
• duration (bool)
• threadid (bool)
• processid (bool)
• channel (bool) — print channel name
• highlight (bool) — console backend only
• disablelink (bool) — do not send to linked channel
• transition (bool) — thread name transitions

Examples:

flags --channel logme
flags --channel logme timestamp=utc signature=on method=on
flags --channel logme console=warncerr highlight=true

backend

Add or remove a backend for a channel (created with default settings).

backend [--channel <name>] --add <type>
backend [--channel <name>] --delete <type>

Backend type names are case-insensitive and accept common aliases:

• console, con, ConsoleBackend
• debug, dbg, DebugBackend
• file, FileBackend
• sharedfile, shared, sfile, SharedFileBackend
• buffer, buf, BufferBackend

Examples:

backend --add console
backend --channel logme --add file
backend --channel logme --delete file

subsystem

Configure subsystem reporting rules.

subsystem --block-reported
subsystem --unblock-reported
subsystem --report <name>
subsystem --unreport <name>
subsystem [name]

• When block mode is enabled, subsystems from the list are blocked.
• When block mode is disabled, only subsystems from the list are allowed.
• subsystem [name] returns whether the given subsystem is currently reported.

auth

Authenticate the current connection (only meaningful if a password is configured).

auth <password>

format

Switch output format for a single command.

format json <command...>
format text <command...>

Accepted text format aliases: text, plain, plain/text.

---

Extending with application-specific commands

Applications can register an extension handler for custom commands:

logger.SetControlExtension(handler);

The extension handler can implement additional commands specific to your application.

---

Security notes

The control server is intended for trusted environments and debugging/operations workflows.

Recommendations:

• Prefer binding to 127.0.0.1 and access via SSH port forwarding if remote control is needed.
• If remote access is required, enable TLS and authentication.
• Do not expose the control port directly to untrusted networks (no rate limiting, no hardening).