# openbmc/obmc-console architecture

> Architecture diagram of the GitHub repository openbmc/obmc-console, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbmc/obmc-console
- Repository: https://github.com/openbmc/obmc-console

## Overview

#### 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`](https://github.com/openbmc/obmc-console/blob/master/console-server.c) (Console server), [`config.c`](https://github.com/openbmc/obmc-console/blob/master/config.c) (Configuration resolver), [`tty-handler.c`](https://github.com/openbmc/obmc-console/blob/master/tty-handler.c) (TTY handler), [`console-client.c`](https://github.com/openbmc/obmc-console/blob/master/console-client.c) (Console client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Service activation"]
  node_server_unit["Server service template<br/>systemd template"]
  node_ssh_socket["SSH socket activation<br/>systemd socket"]
  node_ssh_unit["SSH client service<br/>systemd template"]
  node_server_config["Server console config<br/>INI template"]
  node_client_config["Client console config<br/>INI template"]
end

subgraph group_server["Console server"]
  node_server_main["Console server<br/>C binary<br/>[console-server.c]"]
  node_config["Configuration resolver<br/>C module<br/>[config.c]"]
  node_tty["TTY handler<br/>C module<br/>[tty-handler.c]"]
  node_mux["Hardware mux control<br/>C module<br/>[console-mux.c]"]
  node_server_socket["Console socket manager<br/>C module<br/>[console-socket.c]"]
  node_mux_docs["Mux support guide<br/>documentation<br/>[mux-support.md]"]
end

subgraph group_client["Client access"]
  node_client_main["Console client<br/>C binary<br/>[console-client.c]"]
end

subgraph group_runtime["Runtime services"]
  node_unix_socket["Abstract console socket<br/>Unix-domain socket"]
  node_ringbuffer["Retained output buffer<br/>C module<br/>[ringbuffer.c]"]
  node_socket_handler["Socket event handler<br/>C module<br/>[socket-handler.c]"]
  node_logging["Console logging<br/>handler modules<br/>[log-handler.c]"]
  node_dbus["D-Bus integration<br/>C module<br/>[console-dbus.c]"]
end

node_build["Meson build<br/>build definition<br/>[meson.build]"]

node_server_unit -->|"launches"| node_server_main
node_server_config -->|"parsed by"| node_config
node_client_config -->|"parsed by"| node_config
node_config -->|"server settings"| node_server_main
node_config -->|"target console ID"| node_client_main
node_server_main -->|"uses"| node_tty
node_server_main -->|"uses"| node_server_socket
node_server_socket -->|"publishes"| node_unix_socket
node_tty -.->|"selects path when needed"| node_mux
node_tty -->|"retains output"| node_ringbuffer
node_server_socket -->|"event processing"| node_socket_handler
node_ringbuffer -->|"supplies output"| node_logging
node_server_main -.->|"integrates with"| node_dbus
node_ssh_socket -->|"activates"| node_ssh_unit
node_ssh_unit -->|"starts"| node_client_main
node_client_main -->|"connects to"| node_unix_socket
node_unix_socket -->|"bidirectional terminal traffic"| node_tty
node_mux_docs -.->|"documents"| node_mux
node_build -->|"builds"| node_server_main
node_build -->|"builds"| node_client_main

click node_server_unit "https://github.com/openbmc/obmc-console/blob/master/conf/obmc-console%40.service.in"
click node_ssh_socket "https://github.com/openbmc/obmc-console/blob/master/conf/obmc-console-ssh.socket.in"
click node_ssh_unit "https://github.com/openbmc/obmc-console/blob/master/conf/obmc-console-ssh%40.service.in"
click node_server_config "https://github.com/openbmc/obmc-console/blob/master/conf/server.ttyVUART0.conf.in"
click node_client_config "https://github.com/openbmc/obmc-console/blob/master/conf/client.2200.conf.in"
click node_server_main "https://github.com/openbmc/obmc-console/blob/master/console-server.c"
click node_config "https://github.com/openbmc/obmc-console/blob/master/config.c"
click node_tty "https://github.com/openbmc/obmc-console/blob/master/tty-handler.c"
click node_mux "https://github.com/openbmc/obmc-console/blob/master/console-mux.c"
click node_server_socket "https://github.com/openbmc/obmc-console/blob/master/console-socket.c"
click node_client_main "https://github.com/openbmc/obmc-console/blob/master/console-client.c"
click node_ringbuffer "https://github.com/openbmc/obmc-console/blob/master/ringbuffer.c"
click node_socket_handler "https://github.com/openbmc/obmc-console/blob/master/socket-handler.c"
click node_logging "https://github.com/openbmc/obmc-console/blob/master/log-handler.c"
click node_dbus "https://github.com/openbmc/obmc-console/blob/master/console-dbus.c"
click node_mux_docs "https://github.com/openbmc/obmc-console/blob/master/docs/mux-support.md"
click node_build "https://github.com/openbmc/obmc-console/blob/master/meson.build"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_unit,node_ssh_socket,node_ssh_unit,node_server_config,node_client_config toneBlue
class node_server_main,node_config,node_tty,node_mux,node_server_socket,node_mux_docs toneAmber
class node_client_main toneMint
class node_unix_socket,node_ringbuffer,node_socket_handler,node_logging,node_dbus toneRose
class node_build toneNeutral
```

## Components

### Service activation

- [Server service template](https://github.com/openbmc/obmc-console/blob/master/conf/obmc-console%40.service.in): systemd template · Launches one bridge per console instance. · `conf/obmc-console@.service.in`
- [SSH socket activation](https://github.com/openbmc/obmc-console/blob/master/conf/obmc-console-ssh.socket.in): systemd socket · `conf/obmc-console-ssh.socket.in`
- [SSH client service](https://github.com/openbmc/obmc-console/blob/master/conf/obmc-console-ssh%40.service.in): systemd template · Starts a connector session for SSH users. · `conf/obmc-console-ssh@.service.in`
- [Server console config](https://github.com/openbmc/obmc-console/blob/master/conf/server.ttyVUART0.conf.in): INI template · Defines console identity and TTY endpoint. · `conf/server.ttyVUART0.conf.in`
- [Client console config](https://github.com/openbmc/obmc-console/blob/master/conf/client.2200.conf.in): INI template · Selects the target console. · `conf/client.2200.conf.in`

### Console server

- [Console server](https://github.com/openbmc/obmc-console/blob/master/console-server.c): C binary · Owns a UART endpoint and publishes its console socket. · `console-server.c`
- [Configuration resolver](https://github.com/openbmc/obmc-console/blob/master/config.c): C module · Parses INI files and resolves the shared console ID. · `config.c`
- [TTY handler](https://github.com/openbmc/obmc-console/blob/master/tty-handler.c): C module · Manages serial UART I/O. · `tty-handler.c`
- [Hardware mux control](https://github.com/openbmc/obmc-console/blob/master/console-mux.c): C module · Selects the active UART path on muxed platforms. · `console-mux.c`
- [Console socket manager](https://github.com/openbmc/obmc-console/blob/master/console-socket.c): C module · Accepts consumers on the console-specific Unix socket. · `console-socket.c`
- [Mux support guide](https://github.com/openbmc/obmc-console/blob/master/docs/mux-support.md): documentation · Documents platform-specific mux constraints. · `docs/mux-support.md`

### Client access

- [Console client](https://github.com/openbmc/obmc-console/blob/master/console-client.c): C binary · Forwards terminal I/O and handles session escapes. · `console-client.c`

### Runtime services

- **Abstract console socket**: Unix-domain socket · Isolation boundary keyed by console-id.
- [Retained output buffer](https://github.com/openbmc/obmc-console/blob/master/ringbuffer.c): C module · Provides output retention plus offset/poll reads. · `ringbuffer.c`
- [Socket event handler](https://github.com/openbmc/obmc-console/blob/master/socket-handler.c): C module · Abstracts file-descriptor socket event processing. · `socket-handler.c`
- [Console logging](https://github.com/openbmc/obmc-console/blob/master/log-handler.c): handler modules · Pluggable output logging and persistence. · `log-handler.c`
- [D-Bus integration](https://github.com/openbmc/obmc-console/blob/master/console-dbus.c): C module · `console-dbus.c`

### Other components

- [Meson build](https://github.com/openbmc/obmc-console/blob/master/meson.build): build definition · Builds native binaries and resolves vendored dependencies. · `meson.build`

## Connections

- 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