Basic commands and functionality of the OpenBMC tool

The OpenBMC tool provides support for working with system event logs, updating system firmware, identifying the system, powering off the system, and other service-related functions.

Before you begin

The following list gives examples of some basic commands that are supported by the OpenBMC tool:

OpenBMC tool top-level options

Learn more about the top-level options for the OpenBMC tool commands.

About this task

  • -H: Host name or IP address of the BMC.
  • -U: User name to log in with.
  • -A: Provides a prompt to ask for the password.
  • -P: Password for the user name.
  • -j: Change output format to JSON.
  • -t: Location of the policy table to use.
  • -T: Provides time statistics for logging in, running the command, and logging out.
  • -V: Displays current version of the OpenBMC tool.

System event log commands

Learn more about system event log commands for the OpenBMC tool.

Procedure

  • To print a list of the system event logs in a readable format, use the following command:
    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> sel print
  • To list the system event logs in raw data, use the following command:
    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> sel list
  • To change the status of a system event log to resolved, use the following command:
    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> sel resolve -n x, where x is the system event log number.
  • To collect all service data including system event logs, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> collect_service_data.

  • To clear gard records for disable hardware, use the following command:
    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> gardclear
  • To clear the alert logs of entries, use the following command:
    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> sel clear

System firmware update command

Learn more about the system firmware update command.

Procedure

  • To update the system firmware, use the following command:
    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> firmware flash <bmc or pnor> -f xxx.tar, where bmc or pnor is the type of image you wish to flash to the system.
    Note: If you are not in the same folder as the TAR file, you must include the full path to the folder where the file resides.
  • To activate a firmware image that is available in the BMC, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> firmware activate <firmware image ID>

System identify commands

Learn more about the system identify commands.

Procedure

  • To activate the blue system identify LED, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> chassis identify on

  • To turn off the blue system identify LED, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> chassis identify off

  • To check the status of the blue system identify LED, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> chassis identify status

System power on and power off commands

Learn more about the system power on and power off commands.

Procedure

  • To check the power status of the system, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> chassis power status

  • To power on the system, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> chassis power on

  • To power off the system normally, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> chassis power softoff

  • To power off the system immediately, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> chassis power hardoff

System sensor commands

Learn more about the system sensor commands.

Procedure

To display a list of all monitoring sensors, use the following command:

openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> sensors print

or

openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> sensors list

System FRU commands

Learn more about the system FRU commands.

Procedure

  • To display a list of all inventory items, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> fru print

    or

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> fru list

  • To display the known status of all FRU items, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> fru status

    Note: The FRU item must be designated as a replaceable FRU by the BMC.
  • To automate the review of FRU status commands and to determine if there is a performance impact on the system, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> health_check

    Note: This command does not guarantee a healthy system as there can be system event logs entries that are not associated with the inventory items.

System BMC reset commands

Learn more about the system BMC reset commands.

Procedure

  • To do a warm reset of the BMC remotely and without an AC cycle, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> bmc reset warm

  • To do a cold reset of the BMC remotely and without an AC cycle, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> bmc reset cold

System dump commands

Learn more about the system dump commands.

Procedure

  • To create a new dump file, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> dump create

  • To list all dump files in the system, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> dump list

  • To delete a specific dump file from the system, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> dump delete -n <dump file entry>

  • To delete all dump files from the system, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> dump delete all

  • To retrieve a specific dump file, use the following command:

    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> dump retrieve -n <dump file entry>

  • To retrieve a dump file and save it to specific directory, use the following command:
    openbmctool -U <username> -P <password> -H <BMC IP address or BMC host name> dump retrieve -s <location to save dump file>
    Note: If you do not specify a location, the file is saved in the OS where the command is run in the temp directory.

Enabling and disabling local BMC user accounts

Learn more about the local_userscommands.

About this task

The local user accounts on the BMC, such as root, can be disabled, queried, and re-enabled with the local_users sub-command.
Note: After disabling local users, the LDAP user needs to be available for further interaction with the BMC, including enabling local users by using OpenBMC tool.

Procedure

  • To view current local user account status, use the following command:

    openbmctool <connection options> local_users queryenabled

  • To disable all local user accounts, use the following command:

    openbmctool <connection options> local_users disableall

  • To enable all local user accounts, use the following command:

    openbmctool <connection options> local_users enableall

Remote logging by using rsyslog

Learn more about the remote logging commands.

About this task

The BMC can stream out local logs (that go to the systemd journal) by using RSYSLOG. The BMC sends everything in the logs. Any kind of filtering and appropriate storage has to be managed on the rsyslog server.

Procedure

  • To configure the rsyslog server for remote logging, use the following command:

    openbmctool <connection options> logging remote_logging_config -a <IP address> -p <port>

    Note: The IP address and port are for the remote rsyslog server. After the command is run, the remote rsyslog server starts to receive logs from the BMC.
  • To disable remote logging, use the following command:

    openbmctool <connection options> logging remote_logging disable

    Note: Disable remote logging before you switch remote logging from an existing remote server to a new one.
  • To view the remote logging configuration, use the following command:

    openbmctool <connection options> logging remote_logging view

    Note: This command prints out the IP address and port of the remote rsyslog server in JavaScript Object Notation (JSON) format.
  • To turn REST API logging on, use the following command:

    openbmctool <connection options> logging rest_api on

  • To turn REST API logging off, use the following command:

    openbmctool <connection options> logging rest_api off

    Note: REST API logging is turned off by default.

Certificate management

Learn more about the certificate management commands.

About this task

You can replace the existing certificate and private key file with another (possibly CA signed) certificate and private key file. You can install server, client, and root certificates.

Procedure

  • To update the HTTPS server certificate, use the following command:

    openbmctool <connection options> certificate update server https -f <File>

    Note: The <File> is the privacy-enhanced mail (PEM) file that contains both the certificate and the private key.
  • To update the LDAP client certificate, use the following command:

    openbmctool <connection options> certificate update client ldap -f <File>

    Note: The <File> is the PEM file that contains both the certificate and the private key.
  • To update the LDAP root certificate, use the following command:

    openbmctool <connection options> certificate update authority ldap -f <File>

    Note: The <File> is the PEM file that contains only the certificate.
  • To delete the HTTPS server certificate, use the following command:

    openbmctool <connection options> certificate delete server https

    Note: Deleting a certificate creates and installs a new self-signed certificate.
  • To delete the LDAP client certificate, use the following command:

    openbmctool <connection options> certificate delete client ldap

  • To delete the LDAP root certificate, use the following command:

    openbmctool <connection options> certificate delete authority ldap

    Note: Deleting the root certificate can cause an LDAP service outage.

LDAP configuration

Learn more about the LDAP configuration commands.

About this task

In the BMC, LDAP is used for remote authentication. The BMC does not support remote user-management functionality. The BMC supports both secure and non-secure LDAP configuration.

Procedure

  • To create the LDAP configuration (non-secure), use the following command:

    openbmctool.py <connection options> ldap enable --uri="ldap://<ldap server IP/hostname>" --bindDN=<bindDN> --baseDN=<basDN> --bindPassword=<bindPassword> --scope="sub/one/base" --serverType="OpenLDAP/ActiveDirectory"

    Note: Configuring a fully qualified domain name or hostname in the uri parameter requires the domain name system (DNS) server to be configured on the BMC.
  • To create the LDAP configuration (secure), use the following command:

    openbmctool.py <connection options> ldap enable --uri="ldaps://<ldap server IP/hostname>" --bindDN=<bindDN> --baseDN=<basDN> --bindPassword=<bindPassword> --scope="sub/one/base" --serverType="OpenLDAP/ActiveDirectory"

    Notes:
    1. It is common to encounter the following error when you run the above openbmctool.py command string:

      xyz.openbmc_project.Common.Error.NoCACertificate

      This error means that the BMC client needs to verify that the LDAP server certificate is signed by a known certification authority (CA). An administrator needs to upload the CA certificate to the BMC to resolve this error.

    2. The OpenBMC tool does not support individual LDAP configuration property updates. To update a single property, the administrator must recreate the LDAP configuration with the changed values.
  • To delete the LDAP configuration, use the following command:

    openbmctool.py <connection options> ldap disable

    Note: The root user must be enabled before you run the command, otherwise the BMC is not accessible. To enable all local user accounts, see Enabling and disabling local user accounts.
  • To add privilege mapping use the following command:

    openbmctool.py <connection options> ldap privilege-mapper create --groupName=<groupName> --privilege="priv-admin/priv-user"

  • To delete privilege mapping, use the following command:

    openbmctool.py <connection options> ldap privilege-mapper delete --groupName=<groupName>

  • To list privilege mapping, use the following command:

    openbmctool.py <connection options> ldap privilege-mapper list

    The normal workflow for LDAP configuration is in the following order:
    1. Configure the DNS server.
    2. Configure LDAP.
      1. Configure the CA certificate for secure LDAP configuration.
      2. Create LDAP configuration with local user.
    3. Configure user privilege.
    Notes:
    1. If you login with LDAP credentials and have not added privilege mapping for the LDAP credentials, then you will get the following error message:

      403, 'LDAP group privilege mapping does not exist'.

      You can avoid this error by adding privilege mapping.

    2. The following error message might mean that user lacks sufficient privileges on the BMC:

      Insufficient privileges

      You can avoid this error by adding privilege mapping.

    3. After you setup the LDAP, the OpenBMC tool connection options work with both LDAP and local users.

Network configuration

Learn more about the network configuration commands.

Procedure

  • To enable DHCP, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network enableDHCP -I <Interface name>

  • To disable DHCP, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network disableDHCP -I <Interface name>

  • To get the host name, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network getHostName

  • To set the host name, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network setHostName -H <host name>

  • To get the domain name, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network getDomainName -I <Interface name>

  • To set the domain name, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network setDomainName -I <Interface name> -D DomainName1,DomainName2,..

  • To get the media access control (MAC) address, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network getMACAddress -I <Interface name>

  • To set the MAC address, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network setMACAddress -I <Interface name> -MA xx:xx:xx:xx:xx

  • To get the default gateway, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network getDefaultGW

  • To set the default gateway, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network setDefaultGW -GW <default gw>

  • To view the current network configuration, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network view-config

  • To get the network time protocol (NTP), use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network getNTP -I <Interface name>

  • To set the NTP, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network setNTP -I <Interface name> -N NTP1,NTP2,...

  • To get the domain name system (DNS), use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network getDNS -I <Interface name>

  • To set the DNS, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network setDNS -I <Interface name> -d DNS1,DNS2,...

  • To get the IP address, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network getIP -I <Interface name>

  • To set the IP address, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network addIP -a <ADDRESS> \-gw <GATEWAY> -l <PREFIXLENGTH> -p <protocol type> -I <Interface name>

  • To delete the IP address, use the following command:

    openbmctool.py -H <BMC_IP> -U root -P <root password> network rmIP -I <Interface name> -a <ADDRESS>

  • To enable a virtual local area network (VLAN), use the following command:

    openbmctool.py <connection options> network addVLAN -I <Interface name> -n <IDENTIFIER>

  • To disable a virtual local area network (VLAN), use the following command:

    openbmctool.py <connection options> network deleteVLAN -I <Interface name>

  • To view the DHCP configuration properties, use the following command:

    openbmctool.py <connection options> network viewDHCPConfig

  • To configure the DHCP properties, use the following command:

    openbmctool.py <connection options> network configureDHCP -d <DNSENABLED> -n <HOSTNAMEENABLED> -t <NTPENABLED> -s <SENDHOSTNAMEENABLED>

    Note: DNSENABLED, HOSTNAMEENABLED, NTPENABLED, and SENDHOSTNAMEENABLED are boolean values (true or false).
  • To reset the network settings to the factory defaults, use the following command:

    openbmctool.py <connection options> network nwReset

    Note: Reset settings are applied after the rebooting of the BMC.