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