Configuration guide - openbmc/openbmc GitHub Wiki

Configuration guide

Purpose: This lists BMC configuration items, provides guidance, and shows how to configure each item.

Entries in this wiki page are work-in-progress and user beware. This is intended to be helpful but is not guaranteed to be complete or accurate. Please contribute.

This relates directly to https://github.com/openbmc/docs/blob/master/architecture/user-management.md#deployment---out-of-factory and to what the BMC admin does with a newly-deployed system. The reader is assumed to be familiar with concepts and terminology in https://github.com/openbmc/docs/blob/master/architecture/user-management.md, and specifically, privilege roles and group roles.

There are three sections:

  1. The Build Configuration section lists items that are configured at build time.
  2. The Admin Configuration section lists items that are configured by a BMC administrator.
  3. The Installation and Operation section lists items for the physical installation.

Ideally OpenBMC would incorporate configuration guidance from its upstream projects:

Build Configuration

This shows configuration items for a system integrator to consider when building a BMC firmware image.

Image identification

Customize the os-release file on the BMC's file system. The default appears as NAME="Phosphor OpenBMC (Phosphor OpenBMC Project Reference Distro)" and is set via bitbake variable DISTRO_NAME in phosphor-base.inc.

You can find the OpenBMC version like this:

  • If you are in your source tree, git log -1 will show the commit number.
  • If you have access to the BMC's file system, see file /etc/os-release.

See OpenBMC releases here: https://github.com/openbmc/openbmc/wiki/Releases

If you require a reproducible build, set the BUILD_ID per https://gerrit.openbmc-project.xyz/c/openbmc/openbmc/+/48204

Component software license and version.

Given a specific OpenBMC version, which versions of open source packages are pulled in and what licenses apply to them?

The bitbake build process can produce license information; this also has the exact source package versions used. For example, it can reliably tell you which version of OpenSSL was used. For details, refer to the Yocto project license.bbclass and the Yocto project development manual section titled "Maintaining Open Source License Compliance During Your Product's Lifecycle". OpenBMC builds write this license manifest data to files under build/tmp/deploy/licenses/{your-image-name}/.

Here are some specifics for component parts including the Linux kernel and OpenSSL:

  1. You can find the Linux kernel version from your source, like this: https://github.com/openbmc/openbmc/blob/master/meta-aspeed/recipes-kernel/linux/linux-aspeed_git.bb
  2. You can find the OpenSSL recipe under: https://github.com/openbmc/openbmc/tree/master/poky/meta/recipes-connectivity/openssl

Predefined accounts.

This specifies which accounts are pre-created (if any) such as root and admin. This also includes account properties including role (aka privilege role), initial password, and access privileges (aka group roles). Currently: The root account is created. See also "sudo access".

See Yocto extrausers to create built-in users [6]. This creates new built-in users, set their initial password, privilege role, and group roles. However, if the users have "ipmi" access, additional work is needed to set IPMI's copy of the password. [6]: https://github.com/openbmc/openbmc/blob/master/meta-phosphor/conf/distro/include/phosphor-defaults.inc [3]: https://github.com/openbmc/pam-ipmi/ How to compute the password hash: https://lists.ozlabs.org/pipermail/openbmc/2020-August/022645.html

Understand and handle the initial IPMI passwords. https://lists.ozlabs.org/pipermail/openbmc/2020-April/021246.html

The phosphor-user-manager ENABLE_ROOT_USER_MGMT configuration option controls if the root account participates in OpenBMC user management per https://github.com/openbmc/phosphor-user-manager/blob/master/configure.ac.

Sudo access.

This specifies if the sudo command is present, and what accounts have access to it. Currently: The sudo command is not installed.

Role-to-default-group-roles mapping.

This specifies which interfaces a newly-created local account is allowed to access (aka group roles). Contrast with the Redfish role-to-privilege mapping. Currently: New users get all access privileges. However, see https://github.com/openbmc/openbmc/issues/3643.

Which interfaces are present and enabled.

You can configure which BMC interfaces are present in the firmware image. Includes: Redfish, network IPMI, host IPMI, BMC serial console, SSH, etc. You can control if each interface is enabled by default. See https://github.com/openbmc/docs/blob/master/architecture/interface-overview.md

Network IPMI service.

This specifies if the network IPMI service is present in the image, and if so, if it is enabled by default. Currently: The phosphor-ipmi-net recipe is built into the image, along with supporting pieces such as pam-ipmi and the presence of the "ipmi" group in phosphor-user-manager. It is enabled by default. Create a new encryption key (nominally /etc/key_file) for the IPMI password file (/etc/ipmi_pass) https://github.com/openbmc/pam-ipmi/blob/master/key_file. Control if the network IPMI service is enabled by default by adding a bbappend to the phosphor-ipmi-net recipe with content like: SYSTEMD_AUTO_ENABLE_${PN} = "disable". Obviously, this applies only when network IPMI is included in the image.

SSH service.

This specifies if the SSH service is built into the image, and if so, if it is enabled by default. Currently: SSH is built into the image, along with supporting pieces such as for Linux-PAM and the presence of the "ssh" group in phosphor-user-manager. It is enabled by default.

The "scp" (secure copy) protocol is provided along with SSH. The BMC's provides an "sftp" server as SFTP-over-SSH. Details how to disable sftp are given in the Yocto Reference manual, Features chapter, Image Features section. For example: BAD_RECOMMENDATIONS += "openssh-sftp-server"

The SSH server SSL transport layer security is configured by compile time options here: https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-core/dropbear/dropbear/options.patch

The SSH server per-session idle timeout can be configured. For the dropbear SSH server, set either the compile-time symbol DEFAULT_IDLE_TIMEOUT per https://github.com/mkj/dropbear/blob/master/default_options.h or start the dropbear service with the -I option, for example by setting DROPBEAR_EXTRA_ARGS.

BMC console shell access.

By default, the BMC's serial console provides access to the BMC's command shell. Configure this as follows:

BMCWeb.

See https://github.com/openbmc/bmcweb/blob/master/README.md#configuration

If wanted, pre-load a mTLS certificate.

The SSL transport layer security is configured here: https://github.com/openbmc/bmcweb/blob/master/include/ssl_key_handler.hpp

A per-session inactivity timeout is set via compile-time constant timeoutInSeconds which defaults to 3600 seconds (1 hour).

Web application.

Customize the web application: https://gerrit.openbmc-project.xyz/c/openbmc/webui-vue/+/29079

Certificate manager

Customize the Certificate Manager service. For example, determine if you want to allow the BMC to accept expired certificates (allow-expired in https://github.com/openbmc/phosphor-certificate-manager/blob/master/meson.options) which may be needed when the BMC does not have a reliable time source.

Image signature.

This specifies the keys used to create and validate the digital signature over the BMC firmware image. See https://github.com/openbmc/openbmc/blob/master/meta-phosphor/classes/image_types_phosphor.bbclass.

Assign SIGNING_KEY to your private key for signing image. If it is not set, https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/flash/phosphor-insecure-signing-key-native.bb will be applied.

TODO: Advice on how to generate and handle private keys.

KVM aka ikvm aka KVMip implements VNC

This provides a KVM (keyboard, video, mouse) function which connects the host to network users via URI /kvm/0 via BMC port 5900. Carefully consider if this function is desired. You can remove this function by adding a line your system's recipes-phosphor/packagegroups/packagegroup-obmc-apps.bbappend file, like this: RDEPENDS:${PN}-extras:remove = "obmc-ikvm".

Or in your machine's conf/machine/include configuration: IMAGE_FEATURES:remove = "obmc-ikvm".

And disabling BMCWeb's kvm feature.

ICMP message type 13

Years ago when systems didn't have modern hardware to collect entropy, the system timestamp was an input to the random number generator. So if an attacker knew the system's approximate time, they could have an easier time breaking any ciphers which were based on "random" numbers. Accordingly, systems were told not to give out their timestamp, such as by blocking ICMP message type 13.

Modern BMCs (such as the AST2500 and follow on) do not use the timestamp to generate random numbers, so this vulnerability does not apply, and the Linux kernel is not configured to block ICMP message type 13. Reference: https://lore.kernel.org/all/[email protected]/

Admin Configuration

This shows topics for a BMC administrator to perform. The BMC defaults to DHCP and can be discovered via Avahi mDNS.

Genesis boot. Give guidance to the BMC administrator for the following:

  • How to access the BMC (which interfaces are available).
  • Logging in and setting a password.
  • Configure IP.
  • Set or check the BMC's time of day.
  • Add users or configure LDAP.
  • Replace BMCWeb HTTPS site certificate.
  • Disable unneeded interfaces

Secure the default admin account

Change the admin password. See https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md (but choose a better password).

BMC user interfaces

Understand which interfaces the BMC offers {Redfish, network IPMI, host IPMI, BMC serial console, SSH, etc.} and how the admin can enable and disable them, and how they can authorize specific users to each interface.

BMCWeb

An administrator can configure the BMC by using REST APIs as follows:

  • /redfish/v1/AccountService properties:
    • Oem.OpenBMC.AuthMethods
    • LDAP
    • AccountLockoutDuration
    • AccountLockoutThreshold
  • /redfish/v1/SessionService properties:
    • SessionTimeout
  • TODO: APIs related the the BMC's time of day

Network setup

See https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Network/README.md

Site-identity certificate

Replace the self-signed HTTPS site identity certificate with one signed by a certificate authority (CA). Is this URI /xyz/openbmc_project/certs/server/https? See also https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Certs

For general advice: https://cheatsheetseries.owasp.org/cheatsheets/Key_Management_Cheat_Sheet.html

TLS authentication

Install certificates for Transport Layer Security (TLS) authentication. https://github.com/openbmc/docs/blob/master/security/TLS-configuration.md

Disable U-Boot's interaction capability

Consider if you want to disable U-Boot's "Press any key to stop autoboot" so a user present at the console has no way to stop U-Boot. Disabling this make it harder for an attacker to modify U-Boot settings, but also may limit the ability to service the BMC. See U-Boot docs, for example, set the U-Boot environment variable bootdelay to -2.

Additional admin tasks

Ensure only intended BMC users have access to the “SSH” group privilege.

Privacy considerations

The BMC admin must understand privacy considerations.

Privacy is discussed in review comments in https://gerrit.openbmc-project.xyz/c/openbmc/bmcweb/+/32911 per the comment "has anyone done a reasonable look into storing ip addresses and security law? https://www.jdsupra.com/legalnews/privacy-faqs-is-an-ip-address-75159/"?

Here is some additional detail:

How do consumer privacy laws apply to a BMC? Some provisions (such as "don't sell my information") apply to a larger system (like a consumer website) and would not impose any requirements on the BMC. Other provisions (such as "reasonable security" and "forget me") may apply to the BMC. There may be value in reviewing these laws.

What are the issues with storing personal data on a BMC?

What personal data does a BMC process?

  • Client IP addresses and usernames may be considered personal information.
  • Password data (including hashed or encrypted passwords) may also be considered personal information.
  • The BMC is intended to process dumps (like core dumps, service event log (SEL) entries, and similar) whose content may not be known and may contain personal data.

Is this a correct understanding of laws, regulations, guidelines, and best practices?

  • You should have a good reason to collect personal information.
  • You must inform the user what personal information is collected, how it is used, and require them to opt-in.
  • You must give the user a way to delete their personal information.

Here is a list of specific personal data items the BMC processes:

  • The BMC already handles username and passwords, and stores usernames, hashed and encrypted passwords, and IP addresses in various logs and files.
  • Usernames and password data (hashed or encrypted) are needed to authenticate the user. Per accepted practice, users are not explicitly informed that their username and password are stored.
  • Facts about client network access (including username, IP address, and a timestamp) are logged to meet security audit requirements.
  • The BMC's HTTPS/web server has data about active sessions. These session objects store the username. Per https://gerrit.openbmc-project.xyz/c/openbmc/bmcweb/+/32911, the IP address used to originate a network session is also stored in the session.
  • BMC dump data is specific to the kind of host system the BMC is dedicated to serve. Accounting for personal data in those dumps ought to be scoped to that system.

Additional privacy-related BMC functions:

  • The BMC does not have self-serve account creation. The BMC administrator (creating local accounts or configuring the BMC to use an LDAP server) ought to be responsible for educating the users about how the BMC uses their personal data and getting their consent. BMC access is typically given as part of a job role.
  • The username and password are deleted when the account is removed, but information about them may remain in the BMCs logs.
  • The BMC factory reset function clears all personal data from the BMC. However, it may not do it in a cryptographically secure way as in as in NIST Guidelines for Media Sanitization.
  • Note that various dumps (including kdump and host dumps) and logs provided by, streamed through, or otherwise handled by the BMC may contain sensitive information (such as unencrypted personal identifiable, medical, financial, clear text passwords, etc.).

Installation and Operation

Consider deploying the BMC only to physically protected areas. Doing so prevent users from accessing the BMC's serial console and other more sensitive physical interfaces.

Continue to perform administrative tasks identified above, for example, checking audit logs.