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/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 81[MCTP]: https://www.dmtf.org/sites/default/files/standards/documents/DSP0236_1.3.0.pdf 82 83#### Host-BMC data models 84 85This lists specifications for the data which flows over the BMC-host transport 86protocols: 87 - Host IPMI. 88 - PLDM (DMTF document DSP0240). 89 - Custom OEM solution. 90 91### Network services provided 92 93OpenBMC provides services via its management network. The default services 94are listed here by port number. More information about each service is given 95in sections below or in the appendix. 96 97``` 98 +----------------------------------+ 99 | BMC | 100 | | 101 -+-+ Network services | 102 | | | 103 | +-+ TCP ports | 104 | | +- 22 ssh - shell | 105 | | +- 80 HTTP (no connection) | 106 | | +- 443 HTTPS | 107 | | +- 2200 ssh - host console | 108 | | +- 5355 mDNS service discovery | 109 | | | 110 | +-+ UDP ports | 111 | +- 427 SLP | 112 | +- 623 RCMP+ IPMI | 113 | +- 5355 mDNS service discovery | 114 | | 115 +----------------------------------+ 116``` 117 118Services provided to connected clients may use ports for: 119 - Active SSH sessions. 120 - Active KVM-IP sessions. 121 - Active virtual media sessions. 122 123### Network services consumed 124 125This section lists network services used by OpenBMC systems. OpenBMC uses the 126typical services in the usual way, such as NTP, DNS, and DHCP. In addition, 127OpenBMC uses: 128 - TFTP (disabled by default, when invoked by BMC operator) - Trivial FTP 129 client to fetch firmware images for [code update][]. 130 - SNMP manager to catch [SNMP traps][] (when enabled). 131 132[code update]: https://github.com/openbmc/docs/blob/master/code-update/code-update.md 133[SNMP traps]: https://github.com/openbmc/phosphor-snmp/blob/master/docs/snmp-configuration.md 134 135### Host console 136 137OpenBMC provides access to its host's serial console in various ways: 138 - Client access via network IPMI. 139 - Client access via ssh port 2200. 140 - The hostlogger facility. 141 142``` 143 +---------------------------+ +-----------------+ 144 | BMC | | Host | 145 ipmitool sol | | | | 146 activate | | | | 147 UDP port 623 .... netipmid ------------} | | | 148 | } | | | 149 ssh -p 2200 ... obmc-console-client -}---+----+- serial UART | 150 TCP port 2200 | } | | console | 151 | hostlogger ----------} | | | 152 | | | | 153 +---------------------------+ +-----------------+ 154``` 155 156The [obmc-console][] details how the host UART connection is abstracted within 157the BMC as a Unix domain socket. 158 159[obmc-console]: https://github.com/openbmc/obmc-console/blob/master/README.md 160 161### Web services 162 163OpenBMC provides a custom HTTP/Web server called BMCWeb. 164 165``` 166 +--------------------------------------------------+ 167 | BMC | 168 | | 169 -+-+ Network services | 170 | ++ TCP | 171 | +- 443 HTTPS - BMCWeb -> { static content | 172 | | { Web app (webui) | 173 | +- (other ports) <---+ { Redfish schema | 174 | | | { /login | 175 | V | { Redfish REST APIs | 176 -+- Websockets -+ | { Phosphor REST APIs | 177 | | +<--{-- can set up: | 178 | | { KVM-IP, USB-IP, | 179 | various { Virtual Media | 180 | | 181 +--------------------------------------------------+ 182``` 183 184In the diagram, the arrowheads represent the flow of control from web agents to 185BMCWeb APIs, some of which set up Websockets which give the network agent 186direct communication with the desired interface (not via BMCWeb). 187 188Note that [BMCWeb is configurable][] at compile time. This section describes 189the default configuration (which serves the HTTP application protocol over the 190HTTPS transport protocol on TCP port 443). 191 192[BMCWeb is configurable]: https://github.com/openbmc/bmcweb/blob/master/CMakeLists.txt 193 194Services provided: 195 - Web application (phosphor-webui) and other static content 196 - REST APIs including custom phosphor-rest and Redfish APIs 197 - KVM-IP (Keyboard, Video, Mouse over IP) 198 - Virtual media via USB-IP (Universal Serial Bus over IP) 199 - others 200 201 202### Host IPMI services 203 204OpenBMC provides a host IPMI service. 205 206``` 207 +---------------+ +-----------------+ 208 | BMC | | Host | 209 | | | | 210 | ipmid -+----+- | 211 | | | | 212 +---------------+ +-----------------+ 213``` 214 215The IPMI firmware firewall (which aims to control which host commands and 216channels can be used) is not implemented in OpenBMC. There is support for a 217[Phosphor host IPMI whitelist][] scheme. 218 219[Phosphor host IPMI whitelist]: https://github.com/openbmc/openbmc/blob/master/meta-phosphor/classes/phosphor-ipmi-host-whitelist.bbclass 220 221### D-Bus interfaces 222 223OpenBMC uses D-Bus interfaces as the primary way to communicate (inter-process 224communication) between OpenBMC applications. Note that other methods are 225used, for example Unix domain sockets. 226 227``` 228 +--------------------------------------------------+ 229 | BMC | 230 | | 231 | +-------+ | 232 | | D-Bus | | 233 | | -+- bmcweb | 234 | | -+- ipmid | 235 | | -+- ... | 236 | | -+- many more (not shown here) | 237 | | -+- ... | 238 | | | | 239 | +-------+ | 240 | | 241 +--------------------------------------------------+ 242``` 243 244To learn more, read the [Phosphor D-Bus interface docs][] and search for 245README files in various subdirectories under the xyz/openbmc_project path. 246 247[Phosphor D-Bus interface docs]: https://github.com/openbmc/phosphor-dbus-interfaces 248 249 250## Interfaces and services 251 252This section lists each interface and service shown in this document. The 253intent is to give the relevance of each item and how to locate details in the 254source code. 255 256### BMC network 257 258This sections shows variations in the operational environment of the BMC's 259management network. 260 261The BMC may be connected to a network used to manage the BMC. This is dubbed 262the "management network" to distinguish it from the payload network the host 263system is connected to. These are typically separate networks. 264``` 265 +-----------+ +----------------+ 266 | BMC | | Host | 267management | | | | 268network ---+- Network | | Network -+- payload 269 | | | | network 270 +-----------+ +----------------+ 271``` 272 273The BMC may be served by a Network Controller Sideband Interface (NC-SI) which 274maintains a logically separate network from the host, as shown in this diagram: 275``` 276 +-----------+ +----------------+ 277 | BMC | | Host | 278management | | | | 279network +-+- Network | | Network -+-+ 280 | | | | | | 281 | +-----------+ +----------------+ | 282 | | 283 | +------------------+ | 284 | | NIC | | 285 | |.........+ -+-------------+ 286 +------+- side- : | 287management -------+- band : -+- payload 288network |.........+ | network 289 +------------------+ 290``` 291 292The BMC's management network may be provided by its host system and have no 293direct connection external to the host, as shown in this diagram: 294``` 295 +-----------+ +----------------+ 296 | BMC | | Host | 297 | | | | 298 +--+- Network | | Network -+- payload 299 | | | | | network 300 | | | +--+- management | 301 | | | | | network | 302 | +-----------+ | +----------------+ 303 | | 304 +------------------+ 305``` 306 307The BMC's management network may be connected to USB (LAN over USB): 308``` 309 +-----------+ +----------------+ 310 | BMC | | Host | 311 +-+ | | | | 312 USB --+---+- Network | | Network -+- payload 313 +-+ | | | | network 314 | | | | 315 +-----------+ +----------------+ 316``` 317 318### BMC serial 319 320This gives access to the BMC's console which provides such function as 321controlling the BMC's U-Boot and then providing access to the BMC's shell. 322Contrast with the host serial console access. 323 324### Network interfaces 325 326This refers to the standard NIC and Linux network services on the BMC. 327 328### Secure Shell (SSH) 329 330This refers to the SSH protocol which provides both secure shell (ssh) and 331secure copy (scp) access to the BMC. OpenBMC uses the Dropbear SSH 332implementation. Note that port 22 connects to the BMC's shell, while port 2200 333connects to the host console. 334 335### HTTP and HTTPS 336 337OpenBMC supports the HTTP application protocol over HTTPS, both handled by the 338BMCWeb server. The "http" URI scheme is disabled by default but can be 339enabled at compile time by BMCWeb configuration options. 340 341### Host serial console 342 343Refers to the BMC's access to its host's serial connection which typically 344accesses the host system's console. See also `obmc-console-server` which 345provides host serial access to various internal BMC services. Contrast with 346access to the BMC's serial connection which provides access to the BMC's 347console. 348 349### Service discovery 350 351Refers to the multicast discovery service (mDNS). For example, you can find 352the BMC via the `avahi-browse -rt _obmc_rest._tcp` command. 353 354### Service Location Protocol (SLP) 355 356Refers to the unicast service discovery protocol provided by `slpd`. For 357example, you can find the BMC via the `slptool -u ${ip} findsrvtypes or 358findsrvs` command. 359 360### RCMP+, IPMI, and ipmitool 361 362Refers to the RCMP+ protocol and IPMI implementation provided by `netipmid` 363with source here: `https://github.com/openbmc/phosphor-net-ipmid` and some 364details provided by [IPMI Session management][]. Network IPMI provides access 365to many resources including host IPMI access, SOL (access to the host 366console), and more. Also known as out of band IPMI. Contrast with host-IPMI 367which interacts with the host and with Redfish which provides alternate 368function. 369 370The BMC's RCMP+ IPMI interface is designed to be operated by the 371`[ipmitool][]` external command. 372 373[IPMI Session management]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Ipmi/SESSION_README.md 374[ipmitool]: https://github.com/ipmitool/ipmitool 375 376### Host IPMI 377 378Refers to the host-facing IPMI service provided by the `ipmid` program with 379source here: `https://github.com/openbmc/phosphor-host-ipmid`. The systemd 380service is `phosphor-ipmi-host` implemented by the `ipmid` program. Also 381known as in-band IPMI. Contrast with RCMP+ which faces the network and with 382PLDM which provides alternate function. 383 384### BMC shell 385 386This refers to the BMC's command line interface which defaults to the `bash` 387program provided via the `/bin/sh` path on the BMC's file system. Note that 388the shell (together with its utility programs) provides access to many of the 389BMC's internal and external interfaces. 390 391### obmc-console 392 393This refers to support for multiple independent consoles in 394https://github.com/openbmc/obmc-console and two applications: 395 - The `obmc-console-server` abstracts the host console (UART) connection as a 396 Unix domain socket. 397 - The `obmc-console-client` can connect a console to an SSH session. 398 399Other applications use the console server. 400 401### hostlogger 402 403Refers to the BMC service provided by the `hostlogger` program here: 404https://github.com/openbmc/phosphor-hostlogger which listens to the 405`obmc-console-server` and logs host console messages into the BMC's file 406system. 407 408### BMCWeb web server 409 410Refers to the custom HTTP/Web server with source here: 411https://github.com/openbmc/bmcweb Note that BMCWeb is configurable per 412https://github.com/openbmc/bmcweb/blob/master/CMakeLists.txt with build-time 413options to control which interfaces it provides. For example, there are 414configurations options to: 415 - enable downloading firmware images from a TFTP server 416 - enable the "http" URI scheme 417 - others 418 419The webserver also sets up Secure Websockets for services such as KVM-IP, 420Virtual-USB, and more. 421 422### Redfish 423 424Refers to the set of Redfish REST APIs served by the BMCWeb web server. See 425details here: https://github.com/openbmc/bmcweb/blob/master/Redfish.md with 426docs here: https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md 427 428### phosphor-dbus-rest 429 430Refers to the legacy REST APIs optionally served by the BMCWeb server. 431Docs: https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md 432 433### KVM-IP 434 435Refers to the OpenBMC implementation of the Remote Frame Buffer (RFB, aka VNC) 436protocol which lets you operate the host system's keyboard, video, and mouse 437(KVM) remotely. See https://github.com/openbmc/obmc-ikvm/blob/master/README.md 438Also known as IPKvm. Do not confuse with Kernel Virtual Machine (the other 439KVM). 440 441### Virtual media 442 443Also known as: remote media and USB-over-IP. Design: 444https://github.com/openbmc/docs/blob/master/designs/VirtualMedia.md 445Contrast with LAN-over-USB. 446 447### Virtual USB 448 449Also known as USB-over-IP, and helps implement virtual media. Contrast with 450the BMC and host physical USB ports. 451