1# OpenBMC interfaces
2
3Purpose: This introduces a simplified view of the BMC's primary interfaces.
4It is intended to provide a reference suitable for a wide audience:
5 - Engineers provide domain expertise in specific areas and learn about use
6   cases and threats their interfaces poses.
7 - Give BMC administrators and system integrators a simplified view of the
8   BMC's system interfaces.  For example, to understand which interfaces can
9   be disabled.
10 - Management and security folks need everything to work and play together
11   nicely.  For example, to understand the BMC's attack surfaces.
12
13## Introduction to the interfaces and services
14
15This section shows the BMC's primary interfaces and how they are related.  It
16begins with the BMC's physical interfaces and moves toward abstractions such
17as network services.  The intent is to show the interfaces essential to the
18OpenBMC project in a framework to reason about which interfaces are present,
19how they are related.  This provides a foundation to reason about which can be
20disabled, how they are secured, etc.  The appendix provides details about each
21interface and service shown.
22
23OpenBMC's services and the interfaces they provide are controlled by
24`systemd`.  This document references OpenBMC `systemd` unit names to help link
25concepts to the source code.  The reader is assumed to be familiar with
26[systemd concepts][].  The templated units ("unit@.service") may be omitted
27for clarity.  Relevant details from the unit file may be shown, such as the
28program which implements a service.
29
30The OpenBMC [Service Management][] interface can control `systemd` services.
31For example, disabling a BMC service will disable the corresponding external
32interface.
33
34[systemd concepts]: https://www.freedesktop.org/software/systemd/man/systemd.html#Concepts
35[Service Management]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Service/README.md
36
37Diagrams are included to help visualize relationships.  The diagrams show
38management agents on the left side, the BMC in the center, and host elements
39on the right side.  The diagrams are simplified and are not intended to be
40complete.
41
42### Physical interfaces
43
44This shows the BMC's physical connections including network, USB, UART serial,
45and connections to its host platform.  This uses a simplified view of the host
46which shows only the host interfaces that connect directly to the BMC.  A
47typical host would have additional connections for console, network, etc.
48
49Interfaces between the BMC and its host platform vary considerably based on
50BMC and host platform implementation.  The information presented in this
51section and its subsections is intended to illustrate common elements, not to
52represent any particular system.  This section is intended to be referenced by
53additional documentation which gives details for specific BMC and host
54implementations.
55
56```
57        +----------------+         +----------------+
58        | BMC            |         | Host           |
59        |                |         |                |
60        | Network       -+- LPC ---+-               |
61       -+- eth0         -+--PCIe --+-               |
62       -+- eth1         -+--UART --+-               |
63        |  lo           -+- I2C ---+-               |
64        |               -+--I3C ---+-               |
65        | USB           -+- SPI ---+-               |
66       -+- usb0         -+- PECI --+-               |
67        |               -+- GPIOs -+-               |
68        | Serial        -+- UTMI --+-               |
69       -+- tty0          |         |                |
70        |                |         |                |
71        +----------------+         +----------------+
72```
73
74#### Host-BMC physical interface transport protocols
75
76This lists protocols that operate over the BMC-host physical interfaces:
77 - Host IPMI.
78 - [MCTP][].  OpenBMC offers MCTP over LPC, PCIe, UART.
79 - Custom OEM solution.
80 - SMBus.
81
82[MCTP]: https://www.dmtf.org/sites/default/files/standards/documents/DSP0236_1.3.0.pdf
83
84#### Host-BMC data models
85
86This lists specifications for the data which flows over the BMC-host transport
87protocols:
88 - Host IPMI.
89 - PLDM (DMTF document DSP0240).
90 - Custom OEM solution.
91
92### Network services provided
93
94OpenBMC provides services via its management network.  The default services
95are listed here by port number.  More information about each service is given
96in sections below or in the appendix.
97
98```
99        +----------------------------------+
100        | BMC                              |
101        |                                  |
102       -+-+ Network services               |
103        | |                                |
104        | +-+ TCP ports                    |
105        | | +- 22 ssh - shell              |
106        | | +- 80 HTTP (no connection)     |
107        | | +- 443 HTTPS                   |
108        | | +- 2200 ssh - host console     |
109        | | +- 5355 mDNS service discovery |
110        | |                                |
111        | +-+ UDP ports                    |
112        |   +- 427 SLP                     |
113        |   +- 623 RMCP+ IPMI              |
114        |   +- 5355 mDNS service discovery |
115        |                                  |
116        +----------------------------------+
117```
118
119Services provided to connected clients may use ports for:
120 - Active SSH sessions.
121 - Active KVM-IP sessions.
122 - Active virtual media sessions.
123
124### Network services consumed
125
126This section lists network services used by OpenBMC systems.  OpenBMC uses the
127typical services in the usual way, such as NTP, DNS, and DHCP.  In addition,
128OpenBMC uses:
129 - TFTP (disabled by default, when invoked by BMC operator) - Trivial FTP
130   client to fetch firmware images for [code update][].
131 - SNMP manager to catch [SNMP traps][] (when enabled).
132
133[code update]: https://github.com/openbmc/docs/blob/master/code-update/code-update.md
134[SNMP traps]: https://github.com/openbmc/phosphor-snmp/blob/master/docs/snmp-configuration.md
135
136### Host console
137
138OpenBMC provides access to its host's serial console in various ways:
139 - Client access via network IPMI.
140 - Client access via ssh port 2200.
141 - The hostlogger facility.
142
143```
144                +---------------------------+    +-----------------+
145                | BMC                       |    | Host            |
146 ipmitool sol   |                           |    |                 |
147 activate       |                           |    |                 |
148 UDP port 623 .... netipmid ------------}   |    |                 |
149                |                       }   |    |                 |
150 ssh -p 2200   ... obmc-console-client -}---+----+- serial UART    |
151 TCP port 2200  |                       }   |    |  console        |
152                |  hostlogger ----------}   |    |                 |
153                |                           |    |                 |
154                +---------------------------+    +-----------------+
155```
156
157The [obmc-console][] details how the host UART connection is abstracted within
158the BMC as a Unix domain socket.
159
160[obmc-console]: https://github.com/openbmc/obmc-console/blob/master/README.md
161
162### Web services
163
164OpenBMC provides a custom HTTP/Web server called BMCWeb.
165
166```
167        +--------------------------------------------------+
168        | BMC                                              |
169        |                                                  |
170       -+-+ Network services                               |
171        | ++ TCP                                           |
172        |  +- 443 HTTPS - BMCWeb -> { static content       |
173        |  |                        {   Web app (webui)    |
174        |  +- (other ports) <---+   {   Redfish schema     |
175        |       |               |   { /login               |
176        |       V               |   { Redfish REST APIs    |
177       -+- Websockets -+        |   { Phosphor REST APIs   |
178        |              |        +<--{-- can set up:        |
179        |              |            {     KVM-IP, USB-IP,  |
180        |           various         {     Virtual Media    |
181        |                                                  |
182        +--------------------------------------------------+
183```
184
185In the diagram, the arrowheads represent the flow of control from web agents to
186BMCWeb APIs, some of which set up Websockets which give the network agent
187direct communication with the desired interface (not via BMCWeb).
188
189Note that [BMCWeb is configurable][] at compile time.  This section describes
190the default configuration (which serves the HTTP application protocol over the
191HTTPS transport protocol on TCP port 443).
192
193[BMCWeb is configurable]: https://github.com/openbmc/bmcweb/blob/master/CMakeLists.txt
194
195Services provided:
196 - Web application (webui-vue) and other static content
197 - REST APIs including custom phosphor-rest and Redfish APIs
198 - KVM-IP (Keyboard, Video, Mouse over IP)
199 - Virtual media via USB-IP (Universal Serial Bus over IP)
200 - others
201
202
203### Host IPMI services
204
205OpenBMC provides a host IPMI service.
206
207```
208    +---------------+    +-----------------+
209    | BMC           |    | Host            |
210    |               |    |                 |
211    |        ipmid -+----+-                |
212    |               |    |                 |
213    +---------------+    +-----------------+
214```
215
216The IPMI firmware firewall (which aims to control which host commands and
217channels can be used) is not implemented in OpenBMC.  There is support for a
218[Phosphor host IPMI whitelist][] scheme.
219
220[Phosphor host IPMI whitelist]: https://github.com/openbmc/openbmc/blob/master/meta-phosphor/classes/phosphor-ipmi-host-whitelist.bbclass
221
222### D-Bus interfaces
223
224OpenBMC uses D-Bus interfaces as the primary way to communicate (inter-process
225communication) between OpenBMC applications.  Note that other methods are
226used, for example Unix domain sockets.
227
228```
229        +--------------------------------------------------+
230        | BMC                                              |
231        |                                                  |
232        | +-------+                                        |
233        | | D-Bus |                                        |
234        | |      -+- bmcweb                                |
235        | |      -+- ipmid                                 |
236        | |      -+- ...                                   |
237        | |      -+- many more (not shown here)            |
238        | |      -+- ...                                   |
239        | |       |                                        |
240        | +-------+                                        |
241        |                                                  |
242        +--------------------------------------------------+
243```
244
245To learn more, read the [Phosphor D-Bus interface docs][] and search for
246README files in various subdirectories under the xyz/openbmc_project path.
247
248[Phosphor D-Bus interface docs]: https://github.com/openbmc/phosphor-dbus-interfaces
249
250
251## Interfaces and services
252
253This section lists each interface and service shown in this document.  The
254intent is to give the relevance of each item and how to locate details in the
255source code.
256
257### BMC network
258
259This sections shows variations in the operational environment of the BMC's
260management network.
261
262The BMC may be connected to a network used to manage the BMC.  This is dubbed
263the "management network" to distinguish it from the payload network the host
264system is connected to.  These are typically separate networks.
265```
266             +-----------+      +----------------+
267             | BMC       |      | Host           |
268management   |           |      |                |
269network   ---+- Network  |      |       Network -+- payload
270             |           |      |                |  network
271             +-----------+      +----------------+
272```
273
274The BMC may be served by a Network Controller Sideband Interface (NC-SI) which
275maintains a logically separate network from the host, as shown in this diagram:
276```
277             +-----------+      +----------------+
278             | BMC       |      | Host           |
279management   |           |      |                |
280network    +-+- Network  |      |       Network -+-+
281           | |           |      |                | |
282           | +-----------+      +----------------+ |
283           |                                       |
284           |      +------------------+             |
285           |      | NIC              |             |
286           |      |.........+       -+-------------+
287           +------+- side-  :        |
288management -------+- band   :       -+- payload
289network           |.........+        |  network
290                  +------------------+
291```
292
293The BMC's management network may be provided by its host system and have no
294direct connection external to the host, as shown in this diagram:
295```
296             +-----------+      +----------------+
297             | BMC       |      | Host           |
298             |           |      |                |
299          +--+- Network  |      |       Network -+- payload
300          |  |           |      |                |  network
301          |  |           |   +--+- management    |
302          |  |           |   |  |  network       |
303          |  +-----------+   |  +----------------+
304          |                  |
305          +------------------+
306```
307
308The BMC's management network may be connected to USB (LAN over USB):
309```
310             +-----------+      +----------------+
311             | BMC       |      | Host           |
312        +-+  |           |      |                |
313   USB --+---+- Network  |      |       Network -+- payload
314        +-+  |           |      |                |  network
315             |           |      |                |
316             +-----------+      +----------------+
317```
318
319### BMC serial
320
321This gives access to the BMC's console which provides such function as
322controlling the BMC's U-Boot and then providing access to the BMC's shell.
323Contrast with the host serial console access.
324
325### Network interfaces
326
327This refers to the standard NIC and Linux network services on the BMC.
328
329### Secure Shell (SSH)
330
331This refers to the SSH protocol which provides both secure shell (ssh) and
332secure copy (scp) access to the BMC.  OpenBMC uses the Dropbear SSH
333implementation.  Note that port 22 connects to the BMC's shell, while port 2200
334connects to the host console.
335
336### HTTP and HTTPS
337
338OpenBMC supports the HTTP application protocol over HTTPS, both handled by the
339BMCWeb server.  The "http" URI scheme is disabled by default but can be
340enabled at compile time by BMCWeb configuration options.
341
342### Host serial console
343
344Refers to the BMC's access to its host's serial connection which typically
345accesses the host system's console.  See also `obmc-console-server` which
346provides host serial access to various internal BMC services.  Contrast with
347access to the BMC's serial connection which provides access to the BMC's
348console.
349
350### Service discovery
351
352Refers to the multicast discovery service (mDNS).  For example, you can find
353the BMC via the `avahi-browse -rt _obmc_rest._tcp` command.
354
355### Service Location Protocol (SLP)
356
357Refers to the unicast service discovery protocol provided by `slpd`.  For
358example, you can find the BMC via the `slptool -u ${ip} findsrvtypes or
359findsrvs` command.
360
361### RMCP+, IPMI, and ipmitool
362
363Refers to the RMCP+ protocol and IPMI implementation provided by `netipmid`
364with source here: `https://github.com/openbmc/phosphor-net-ipmid` and some
365details provided by [IPMI Session management][].  Network IPMI provides access
366to many resources including host IPMI access, SOL (access to the host
367console), and more.  Also known as out of band IPMI.  Contrast with host-IPMI
368which interacts with the host and with Redfish which provides alternate
369function.
370
371The BMC's RMCP+ IPMI interface is designed to be operated by the
372`[ipmitool][]` external command.
373
374[IPMI Session management]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Ipmi/SESSION_README.md
375[ipmitool]: https://github.com/ipmitool/ipmitool
376
377### Host IPMI
378
379Refers to the host-facing IPMI service provided by the `ipmid` program with
380source here: `https://github.com/openbmc/phosphor-host-ipmid`.  The systemd
381service is `phosphor-ipmi-host` implemented by the `ipmid` program.  Also
382known as in-band IPMI.  Contrast with RMCP+ which faces the network and with
383PLDM which provides alternate function.
384
385### BMC shell
386
387This refers to the BMC's command line interface which defaults to the `bash`
388program provided via the `/bin/sh` path on the BMC's file system.  Note that
389the shell (together with its utility programs) provides access to many of the
390BMC's internal and external interfaces.
391
392### obmc-console
393
394This refers to support for multiple independent consoles in
395https://github.com/openbmc/obmc-console and two applications:
396 - The `obmc-console-server` abstracts the host console (UART) connection as a
397   Unix domain socket.
398 - The `obmc-console-client` can connect a console to an SSH session.
399
400Other applications use the console server.
401
402### hostlogger
403
404Refers to the BMC service provided by the `hostlogger` program here:
405https://github.com/openbmc/phosphor-hostlogger which listens to the
406`obmc-console-server` and logs host console messages into the BMC's file
407system.
408
409### BMCWeb web server
410
411Refers to the custom HTTP/Web server with source here:
412https://github.com/openbmc/bmcweb Note that BMCWeb is configurable per
413https://github.com/openbmc/bmcweb/blob/master/CMakeLists.txt with build-time
414options to control which interfaces it provides.  For example, there are
415configurations options to:
416 - enable downloading firmware images from a TFTP server
417 - enable the "http" URI scheme
418 - others
419
420The webserver also sets up Secure Websockets for services such as KVM-IP,
421Virtual-USB, and more.
422
423### Redfish
424
425Refers to the set of Redfish REST APIs served by the BMCWeb web server.  See
426details here: https://github.com/openbmc/bmcweb/blob/master/Redfish.md with
427docs here: https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md
428
429### phosphor-dbus-rest
430
431Refers to the legacy REST APIs optionally served by the BMCWeb server.
432Docs: https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md
433
434### KVM-IP
435
436Refers to the OpenBMC implementation of the Remote Frame Buffer (RFB, aka VNC)
437protocol which lets you operate the host system's keyboard, video, and mouse
438(KVM) remotely.  See https://github.com/openbmc/obmc-ikvm/blob/master/README.md
439Also known as IPKvm.  Do not confuse with Kernel Virtual Machine (the other
440KVM).
441
442### Virtual media
443
444Also known as: remote media and USB-over-IP.  Design:
445https://github.com/openbmc/docs/blob/master/designs/VirtualMedia.md
446Contrast with LAN-over-USB.
447
448### Virtual USB
449
450Also known as USB-over-IP, and helps implement virtual media.  Contrast with
451the BMC and host physical USB ports.
452