Run trace-cmd-agent Safely for Remote Kernel Tracing

trace-cmd agent opens a listener that lets another machine control kernel tracing on this one, so the transport and trust boundary matter. This guide sets it up deliberately: the default virtual-machine vsocket, or TCP for one named client only. The installed manual is blunt about TCP: it's very insecure and belongs only on a trusted network with a completely trusted controller.

Allow about 15 minutes for a foreground smoke test, plus time to review the VM or network boundary properly. This guide uses trace-cmd 3.2.0 from the installed trace-cmd package, version 3.2-1ubuntu2.

1. Check the installed command

Run these checks as the account that will operate the agent. Starting an agent can expose tracing control, so don't test it on a shared host or as a casual background process:

$ command -v trace-cmd
/usr/bin/trace-cmd
$ trace-cmd --version
trace-cmd version 3.2.0 (not-a-git-repo)
$ trace-cmd agent --help
trace-cmd version 3.2.0 (not-a-git-repo)
...
 trace-cmd agent -p port[-D][-N IP][-P cid]

Your version line may differ on another machine; keep the local help output with your deployment notes. The agent is a subcommand of trace-cmd, there's no separate trace-cmd-agent executable to launch despite the name.

2. Choose the transport and controller

Use the default vsocket when the controller and agent share a virtual-machine setup with vsock available. The manpage describes the agent as listening on a vsocket for virtual machines and passing trace data to the controlling connection. A vsocket setup still needs a defined guest or host boundary; it's not a reason to treat every local process as trusted.

Use TCP only when you have a specific controller address and a network design that protects the connection. The -N value isn't a bind address, it names the one client host or IP that may connect. The manual also says any process on that client can control the agent, which is a broad trust decision, not per-user authentication.

3. Select a listening port

The -p option supplies the port number to listen on. Pick a documented, permitted port that doesn't collide with another service; the installed command's usage requires -p even when the default vsocket transport is what you're actually using:

$ TRACE_PORT='REPLACE_WITH_YOUR_PORT'
$ printf 'agent port: %s\n' "$TRACE_PORT"
agent port: REPLACE_WITH_YOUR_PORT

Replace the placeholder with a real numeric port before launching the agent, and never paste the placeholder itself into a production command. Choosing a port doesn't restrict who can control a vsocket agent; that access comes from the transport and the VM configuration around it.

4. Run a foreground vsocket smoke test

For the first test, leave out -D. Starting the agent in the foreground keeps its lifetime visible, and lets you stop it with the normal interrupt for your shell. This opens a listening endpoint, changing runtime state, but it doesn't touch any configuration file:

$ sudo trace-cmd agent -p REPLACE_WITH_YOUR_PORT

Use sudo only if your account needs it for tracing facilities on this host. A successfully started agent normally waits for a controlling connection rather than printing anything, that wait is the expected foreground state. Keep the terminal open while the trusted controller runs its own connection test.

5. Use TCP only with an explicit trusted client

For a TCP test, combine -N with -p. Replace both placeholders with the controller's real address and the chosen port; the address should be an exact host name or IP, never a whole subnet:

$ sudo trace-cmd agent -N CONTROLLER_HOST_OR_IP -p REPLACE_WITH_YOUR_PORT

The agent accepts a connection only from the client supplied to -N, per the installed manual. That's an allow-list for the client host, not encryption, user authentication or per-command authorisation. A compromised or multi-user controller can still control the agent, so put the endpoint behind the narrowest network path available and treat the connection as sensitive.

6. Add daemon mode only after the test works

-D makes the agent daemonise and run in the background. Add it only once the foreground command has proven the right transport, port and controller boundary:

$ sudo trace-cmd agent -N CONTROLLER_HOST_OR_IP -p REPLACE_WITH_YOUR_PORT -D

There's no foreground terminal to act as your checkpoint after -D, so use the process manager or service wrapper that owns the command, and confirm its process and listening endpoint through the host's normal operational checks. No reliable owner for the background process means leaving out -D rather than creating an unmanaged listener.

7. Treat proxy mode as a separate VM design

The -P option makes the agent also act as a proxy server. Its argument is a context ID, or CID, for the client guest allowed to connect, a vsock concept, not a TCP port and not a hostname:

$ sudo trace-cmd agent -P REPLACE_WITH_CLIENT_CID -p REPLACE_WITH_YOUR_PORT

Use this only when the host and guest tracing path has been designed around vsock and you've confirmed the guest's CID from your VM tooling. Don't substitute the guest's IP address. Proxy mode changes which VM endpoint can reach the agent, so test it in the foreground first and document the host, guest, CID and port together.

8. Turn on focused diagnostics when needed

The optional --verbose setting accepts named levels none, critical, error, warning, info, debug and all, or the identifiers 0 through 6. With no level supplied, the manual says it defaults to info, and a selected level also enables the preceding ones:

$ sudo trace-cmd agent -N CONTROLLER_HOST_OR_IP -p REPLACE_WITH_YOUR_PORT --verbose=warning

Pick a level that answers the current question, then return to the default once the test is done. The manual's example shows the syntax on trace-cmd listen, but it's documented for the agent too. Diagnostics don't add authentication or fix a transport mismatch.