How openbmc/obmc-console works
Purpose and entry points
obmc-console exposes host UART consoles through Unix-domain sockets so local services and SSH-connected users can access them. Primary binaries are the UART/socket bridge in console-server.c and the interactive connector in console-client.c. Systemd templates launch per-console server instances and SSH-facing client sessions: conf/obmc-console@.service.in, conf/obmc-console-ssh@.service.in.
Configuration and console identity
Configuration parsing and resolution are centralized in config.c and config.h, using INI-style per-client and per-server files. A shared console-id determines the abstract Unix socket name, allowing independent console instances. Deployment templates demonstrate the two sides: conf/server.ttyVUART0.conf.in and conf/client.2200.conf.in.
Server: UART-to-client bridge
console-server.c owns a configured serial/TTY endpoint and publishes its console socket. tty-handler.c manages UART I/O; console-socket.c accepts and manages Unix-domain socket clients. The server mediates bidirectional traffic between the UART and connected consumers while preserving a console-specific isolation boundary.
Client and remote access
console-client.c resolves the target console ID, connects to its Unix socket, and forwards terminal input/output. Its escape handling supports session disconnect behavior. Socket-activated SSH access is composed from conf/obmc-console-ssh.socket.in and conf/obmc-console-ssh@.service.in, with the client configuration selecting the target console.
Eventing, buffering, and handlers
The runtime is event-driven around file descriptors. ringbuffer.c provides retained console output and offset/poll semantics for readers. socket-handler.c abstracts socket event processing, while log-handler.c and text-log-handler.c provide pluggable console logging/output persistence. These separate transport, retained data, and logging concerns.
Multiplexed UART support
console-mux.c and console-mux.h add a hardware-mux layer for platforms where several UART paths share a mux. Server-side control can select the active path before terminal traffic reaches the underlying TTY. The platform-specific design and constraints are documented in docs/mux-support.md.
Runtime, packaging, and dependencies
The project is native C built with Meson (meson.build) and runs on Linux, relying on serial TTYs, abstract Unix-domain sockets, systemd socket/service activation, and D-Bus-related integration in console-dbus.c. External dependencies are vendored through Meson wraps, notably INI parsing and GPIO support: subprojects/iniparser.wrap, subprojects/libgpiod.wrap.
Main entry points: console-server.c Console server · config.c Configuration resolver · tty-handler.c TTY handler · console-client.c Console client
Components 18
Service activation
- Server service template · Launches one bridge per console instance.
conf/obmc-console@.service.in - SSH socket activation
conf/obmc-console-ssh.socket.in - SSH client service · Starts a connector session for SSH users.
conf/obmc-console-ssh@.service.in - Server console config · Defines console identity and TTY endpoint.
conf/server.ttyVUART0.conf.in - Client console config · Selects the target console.
conf/client.2200.conf.in
Console server
- Console server · Owns a UART endpoint and publishes its console socket.
console-server.c - Configuration resolver · Parses INI files and resolves the shared console ID.
config.c - TTY handler · Manages serial UART I/O.
tty-handler.c - Hardware mux control · Selects the active UART path on muxed platforms.
console-mux.c - Console socket manager · Accepts consumers on the console-specific Unix socket.
console-socket.c - Mux support guide · Documents platform-specific mux constraints.
docs/mux-support.md
Client access
- Console client · Forwards terminal I/O and handles session escapes.
console-client.c
Runtime services
- Abstract console socket · Isolation boundary keyed by console-id.
- Retained output buffer · Provides output retention plus offset/poll reads.
ringbuffer.c - Socket event handler · Abstracts file-descriptor socket event processing.
socket-handler.c - Console logging · Pluggable output logging and persistence.
log-handler.c - D-Bus integration
console-dbus.c
Other components
- Meson build · Builds native binaries and resolves vendored dependencies.
meson.build
Connections 20
- Server service template → Console server: launches
- Server console config → Configuration resolver: parsed by
- Client console config → Configuration resolver: parsed by
- Configuration resolver → Console server: server settings
- Configuration resolver → Console client: target console ID
- Console server → TTY handler: uses
- Console server → Console socket manager: uses
- Console socket manager → Abstract console socket: publishes
- TTY handler → Hardware mux control: selects path when needed
- TTY handler → Retained output buffer: retains output
- Console socket manager → Socket event handler: event processing
- Retained output buffer → Console logging: supplies output
- Console server → D-Bus integration: integrates with
- SSH socket activation → SSH client service: activates
- SSH client service → Console client: starts
- Console client → Abstract console socket: connects to
- Abstract console socket → TTY handler: bidirectional terminal traffic
- Mux support guide → Hardware mux control: documents
- Meson build → Console server: builds
- Meson build → Console client: builds