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#configuration 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#configuration 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