docs: add architecture/interface-overview
This adds an overview of the BMC's primary external interfaces and
selected internal interfaces.
Signed-off-by: Joseph Reynolds <joseph-reynolds@charter.net>
Change-Id: Ib7565c3a3d6ba5b06beb583e46a2badfe791a9e3
diff --git a/architecture/interface-overview.md b/architecture/interface-overview.md
new file mode 100644
index 0000000..2f05d66
--- /dev/null
+++ b/architecture/interface-overview.md
@@ -0,0 +1,450 @@
+# OpenBMC interfaces
+
+Purpose: This introduces a simplified view of the BMC's primary interfaces.
+It is intended to provide a reference suitable for a wide audience:
+ - Engineers provide domain expertise in specific areas and learn about use
+ cases and threats their interfaces poses.
+ - Give BMC administrators and system integrators a simplified view of the
+ BMC's system interfaces. For example, to understand which interfaces can
+ be disabled.
+ - Management and security folks need everything to work and play together
+ nicely. For example, to understand the BMC's attack surfaces.
+
+## Introduction to the interfaces and services
+
+This section shows the BMC's primary interfaces and how they are related. It
+begins with the BMC's physical interfaces and moves toward abstractions such
+as network services. The intent is to show the interfaces essential to the
+OpenBMC project in a framework to reason about which interfaces are present,
+how they are related. This provides a foundation to reason about which can be
+disabled, how they are secured, etc. The appendix provides details about each
+interface and service shown.
+
+OpenBMC's services and the interfaces they provide are controlled by
+`systemd`. This document references OpenBMC `systemd` unit names to help link
+concepts to the source code. The reader is assumed to be familiar with
+[systemd concepts][]. The templated units ("unit@.service") may be omitted
+for clarity. Relevant details from the unit file may be shown, such as the
+program which implements a service.
+
+The OpenBMC [Service Management][] interface can control `systemd` services.
+For example, disabling a BMC service will disable the corresponding external
+interface.
+
+[systemd concepts]: https://www.freedesktop.org/software/systemd/man/systemd.html#Concepts
+[Service Management]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Control/Service/README.md
+
+Diagrams are included to help visualize relationships. The diagrams show
+management agents on the left side, the BMC in the center, and host elements
+on the right side. The diagrams are simplified and are not intended to be
+complete.
+
+### Physical interfaces
+
+This shows the BMC's physical connections including network, USB, UART serial,
+and connections to its host platform. This uses a simplified view of the host
+which shows only the host interfaces that connect directly to the BMC. A
+typical host would have additional connections for console, network, etc.
+
+Interfaces between the BMC and its host platform vary considerably based on
+BMC and host platform implementation. The information presented in this
+section and its subsections is intended to illustrate common elements, not to
+represent any particular system. This section is intended to be referenced by
+additional documentation which gives details for specific BMC and host
+implementations.
+
+```
+ +----------------+ +----------------+
+ | BMC | | Host |
+ | | | |
+ | Network -+- LPC ---+- |
+ -+- eth0 -+--PCIe --+- |
+ -+- eth1 -+--UART --+- |
+ | lo -+- I2C ---+- |
+ | -+--I3C ---+- |
+ | USB -+- SPI ---+- |
+ -+- usb0 -+- PECI --+- |
+ | -+- GPIOs -+- |
+ | Serial -+- UTMI --+- |
+ -+- tty0 | | |
+ | | | |
+ +----------------+ +----------------+
+```
+
+#### Host-BMC physical interface transport protocols
+
+This lists protocols that operate over the BMC-host physical interfaces:
+ - Host IPMI.
+ - [MCTP][]. OpenBMC offers MCTP over LPC, PCIe, UART.
+ - Custom OEM solution.
+
+[MCTP]: https://www.dmtf.org/sites/default/files/standards/documents/DSP0236_1.3.0.pdf
+
+#### Host-BMC data models
+
+This lists specifications for the data which flows over the BMC-host transport
+protocols:
+ - Host IPMI.
+ - PLDM (DMTF document DSP0240).
+ - Custom OEM solution.
+
+### Network services provided
+
+OpenBMC provides services via its management network. The default services
+are listed here by port number. More information about each service is given
+in sections below or in the appendix.
+
+```
+ +----------------------------------+
+ | BMC |
+ | |
+ -+-+ Network services |
+ | | |
+ | +-+ TCP ports |
+ | | +- 22 ssh - shell |
+ | | +- 80 HTTP (no connection) |
+ | | +- 443 HTTPS |
+ | | +- 2200 ssh - host console |
+ | | +- 5355 mDNS service discovery |
+ | | |
+ | +-+ UDP ports |
+ | +- 427 SLP |
+ | +- 623 RCMP+ IPMI |
+ | +- 5355 mDNS service discovery |
+ | |
+ +----------------------------------+
+```
+
+Services provided to connected clients may use ports for:
+ - Active SSH sessions.
+ - Active KVM-IP sessions.
+ - Active virtual media sessions.
+
+### Network services consumed
+
+This section lists network services used by OpenBMC systems. OpenBMC uses the
+typical services in the usual way, such as NTP, DNS, and DHCP. In addition,
+OpenBMC uses:
+ - TFTP (disabled by default, when invoked by BMC operator) - Trivial FTP
+ client to fetch firmware images for [code update][].
+ - SNMP manager to catch [SNMP traps][] (when enabled).
+
+[code update]: https://github.com/openbmc/docs/blob/master/code-update/code-update.md
+[SNMP traps]: https://github.com/openbmc/phosphor-snmp/blob/master/docs/snmp-configuration.md
+
+### Host console
+
+OpenBMC provides access to its host's serial console in various ways:
+ - Client access via network IPMI.
+ - Client access via ssh port 2200.
+ - The hostlogger facility.
+
+```
+ +---------------------------+ +-----------------+
+ | BMC | | Host |
+ ipmitool sol | | | |
+ activate | | | |
+ UDP port 623 .... netipmid ------------} | | |
+ | } | | |
+ ssh -p 2200 ... obmc-console-client -}---+----+- serial UART |
+ TCP port 2200 | } | | console |
+ | hostlogger ----------} | | |
+ | | | |
+ +---------------------------+ +-----------------+
+```
+
+The [obmc-console][] details how the host UART connection is abstracted within
+the BMC as a Unix domain socket.
+
+[obmc-console]: https://github.com/openbmc/obmc-console/blob/master/README.md
+
+### Web services
+
+OpenBMC provides a custom HTTP/Web server called BMCWeb.
+
+```
+ +--------------------------------------------------+
+ | BMC |
+ | |
+ -+-+ Network services |
+ | ++ TCP |
+ | +- 443 HTTPS - BMCWeb -> { static content |
+ | | { Web app (webui) |
+ | +- (other ports) <---+ { Redfish schema |
+ | | | { /login |
+ | V | { Redfish REST APIs |
+ -+- Websockets -+ | { Phosphor REST APIs |
+ | | +<--{-- can set up: |
+ | | { KVM-IP, USB-IP, |
+ | various { Virtual Media |
+ | |
+ +--------------------------------------------------+
+```
+
+In the diagram, the arrowheads represent the flow of control from web agents to
+BMCWeb APIs, some of which set up Websockets which give the network agent
+direct communication with the desired interface (not via BMCWeb).
+
+Note that [BMCWeb is configurable][] at compile time. This section describes
+the default configuration (which serves the HTTP application protocol over the
+HTTPS transport protocol on TCP port 443).
+
+[BMCWeb is configurable]: https://github.com/openbmc/bmcweb/blob/master/CMakeLists.txt
+
+Services provided:
+ - Web application (phosphor-webui) and other static content
+ - REST APIs including custom phosphor-rest and Redfish APIs
+ - KVM-IP (Keyboard, Video, Mouse over IP)
+ - Virtual media via USB-IP (Universal Serial Bus over IP)
+ - others
+
+
+### Host IPMI services
+
+OpenBMC provides a host IPMI service.
+
+```
+ +---------------+ +-----------------+
+ | BMC | | Host |
+ | | | |
+ | ipmid -+----+- |
+ | | | |
+ +---------------+ +-----------------+
+```
+
+The IPMI firmware firewall (which aims to control which host commands and
+channels can be used) is not implemented in OpenBMC. There is support for a
+[Phosphor host IPMI whitelist][] scheme.
+
+[Phosphor host IPMI whitelist]: https://github.com/openbmc/openbmc/blob/master/meta-phosphor/classes/phosphor-ipmi-host-whitelist.bbclass
+
+### D-Bus interfaces
+
+OpenBMC uses D-Bus interfaces as the primary way to communicate (inter-process
+communication) between OpenBMC applications. Note that other methods are
+used, for example Unix domain sockets.
+
+```
+ +--------------------------------------------------+
+ | BMC |
+ | |
+ | +-------+ |
+ | | D-Bus | |
+ | | -+- bmcweb |
+ | | -+- ipmid |
+ | | -+- ... |
+ | | -+- many more (not shown here) |
+ | | -+- ... |
+ | | | |
+ | +-------+ |
+ | |
+ +--------------------------------------------------+
+```
+
+To learn more, read the [Phosphor D-Bus interface docs][] and search for
+README files in various subdirectories under the xyz/openbmc_project path.
+
+[Phosphor D-Bus interface docs]: https://github.com/openbmc/phosphor-dbus-interfaces
+
+
+## Interfaces and services
+
+This section lists each interface and service shown in this document. The
+intent is to give the relevance of each item and how to locate details in the
+source code.
+
+### BMC network
+
+This sections shows variations in the operational environment of the BMC's
+management network.
+
+The BMC may be connected to a network used to manage the BMC. This is dubbed
+the "management network" to distinguish it from the payload network the host
+system is connected to. These are typically separate networks.
+```
+ +-----------+ +----------------+
+ | BMC | | Host |
+management | | | |
+network ---+- Network | | Network -+- payload
+ | | | | network
+ +-----------+ +----------------+
+```
+
+The BMC may be served by a Network Controller Sideband Interface (NC-SI) which
+maintains a logically separate network from the host, as shown in this diagram:
+```
+ +-----------+ +----------------+
+ | BMC | | Host |
+management | | | |
+network +-+- Network | | Network -+-+
+ | | | | | |
+ | +-----------+ +----------------+ |
+ | |
+ | +------------------+ |
+ | | NIC | |
+ | |.........+ -+-------------+
+ +------+- side- : |
+management -------+- band : -+- payload
+network |.........+ | network
+ +------------------+
+```
+
+The BMC's management network may be provided by its host system and have no
+direct connection external to the host, as shown in this diagram:
+```
+ +-----------+ +----------------+
+ | BMC | | Host |
+ | | | |
+ +--+- Network | | Network -+- payload
+ | | | | | network
+ | | | +--+- management |
+ | | | | | network |
+ | +-----------+ | +----------------+
+ | |
+ +------------------+
+```
+
+The BMC's management network may be connected to USB (LAN over USB):
+```
+ +-----------+ +----------------+
+ | BMC | | Host |
+ +-+ | | | |
+ USB --+---+- Network | | Network -+- payload
+ +-+ | | | | network
+ | | | |
+ +-----------+ +----------------+
+```
+
+### BMC serial
+
+This gives access to the BMC's console which provides such function as
+controlling the BMC's U-Boot and then providing access to the BMC's shell.
+Contrast with the host serial console access.
+
+### Network interfaces
+
+This refers to the standard NIC and Linux network services on the BMC.
+
+### Secure Shell (SSH)
+
+This refers to the SSH protocol which provides both secure shell (ssh) and
+secure copy (scp) access to the BMC. OpenBMC uses the Dropbear SSH
+implementation. Note that port 22 connects to the BMC's shell, while port 2200
+connects to the host console.
+
+### HTTP and HTTPS
+
+OpenBMC supports the HTTP application protocol over HTTPS, both handled by the
+BMCWeb server. The "http" URI scheme is disabled by default but can be
+enabled at compile time by BMCWeb configuration options.
+
+### Host serial console
+
+Refers to the BMC's access to its host's serial connection which typically
+accesses the host system's console. See also `obmc-console-server` which
+provides host serial access to various internal BMC services. Contrast with
+access to the BMC's serial connection which provides access to the BMC's
+console.
+
+### Service discovery
+
+Refers to the multicast discovery service (mDNS). For example, you can find
+the BMC via the `avahi-browse -rt _obmc_rest._tcp` command.
+
+### Service Location Protocol (SLP)
+
+Refers to the unicast service discovery protocol provided by `slpd`. For
+example, you can find the BMC via the `slptool -u ${ip} findsrvtypes or
+findsrvs` command.
+
+### RCMP+, IPMI, and ipmitool
+
+Refers to the RCMP+ protocol and IPMI implementation provided by `netipmid`
+with source here: `https://github.com/openbmc/phosphor-net-ipmid` and some
+details provided by [IPMI Session management][]. Network IPMI provides access
+to many resources including host IPMI access, SOL (access to the host
+console), and more. Also known as out of band IPMI. Contrast with host-IPMI
+which interacts with the host and with Redfish which provides alternate
+function.
+
+The BMC's RCMP+ IPMI interface is designed to be operated by the
+`[ipmitool][]` external command.
+
+[IPMI Session management]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Ipmi/SESSION_README.md
+[ipmitool]: https://github.com/ipmitool/ipmitool
+
+### Host IPMI
+
+Refers to the host-facing IPMI service provided by the `ipmid` program with
+source here: `https://github.com/openbmc/phosphor-host-ipmid`. The systemd
+service is `phosphor-ipmi-host` implemented by the `ipmid` program. Also
+known as in-band IPMI. Contrast with RCMP+ which faces the network and with
+PLDM which provides alternate function.
+
+### BMC shell
+
+This refers to the BMC's command line interface which defaults to the `bash`
+program provided via the `/bin/sh` path on the BMC's file system. Note that
+the shell (together with its utility programs) provides access to many of the
+BMC's internal and external interfaces.
+
+### obmc-console
+
+This refers to support for multiple independent consoles in
+https://github.com/openbmc/obmc-console and two applications:
+ - The `obmc-console-server` abstracts the host console (UART) connection as a
+ Unix domain socket.
+ - The `obmc-console-client` can connect a console to an SSH session.
+
+Other applications use the console server.
+
+### hostlogger
+
+Refers to the BMC service provided by the `hostlogger` program here:
+https://github.com/openbmc/phosphor-hostlogger which listens to the
+`obmc-console-server` and logs host console messages into the BMC's file
+system.
+
+### BMCWeb web server
+
+Refers to the custom HTTP/Web server with source here:
+https://github.com/openbmc/bmcweb Note that BMCWeb is configurable per
+https://github.com/openbmc/bmcweb/blob/master/CMakeLists.txt with build-time
+options to control which interfaces it provides. For example, there are
+configurations options to:
+ - enable downloading firmware images from a TFTP server
+ - enable the "http" URI scheme
+ - others
+
+The webserver also sets up Secure Websockets for services such as KVM-IP,
+Virtual-USB, and more.
+
+### Redfish
+
+Refers to the set of Redfish REST APIs served by the BMCWeb web server. See
+details here: https://github.com/openbmc/bmcweb/blob/master/Redfish.md with
+docs here: https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md
+
+### phosphor-dbus-rest
+
+Refers to the legacy REST APIs optionally served by the BMCWeb server.
+Docs: https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md
+
+### KVM-IP
+
+Refers to the OpenBMC implementation of the Remote Frame Buffer (RFB, aka VNC)
+protocol which lets you operate the host system's keyboard, video, and mouse
+(KVM) remotely. See https://github.com/openbmc/obmc-ikvm/blob/master/README.md
+Also known as IPKvm. Do not confuse with Kernel Virtual Machine (the other
+KVM).
+
+### Virtual media
+
+Also known as: remote media and USB-over-IP. Design:
+https://github.com/openbmc/docs/blob/master/designs/VirtualMedia.md
+Contrast with LAN-over-USB.
+
+### Virtual USB
+
+Also known as USB-over-IP, and helps implement virtual media. Contrast with
+the BMC and host physical USB ports.