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