Getting Started with tlBMC

go/tlbmc-getting-started

This is an introduction for how to enable tlBMC and begin development with tlBMC.

Enabling tlBMC

To enable tlBMC on a machine, we need to enable the command line flag. We can do so by modifying the service file for bmcweb and adding the--enable_tlbmc=true flag, then restarting the service.

See example below:

$ vi /lib/systemd/system/bmcweb.service

## Inside bmcweb.service
# [Unit]
# Description=Start bmcweb server
# ...
# [Service]
# ExecReload=kill -s HUP $MAINPID
### MODIFY THE LINE BELOW
# ExecStart=/usr/bin/bmcweb --enable_tlbmc=true [optional: --entity_config_location=${PATH_TO_EM_CONFIG_DIR}]
# Type=simple
# WorkingDirectory=/home/root
# Restart=on-failure
# MemoryMax=300M
# StartLimitInterval=3
# StartLimitBurst=10
# ...

$ systemctl daemon-reload
$ systemctl restart bmcweb

Note: As shown above, there is an optional flag for --entity_config_location this allows the user to define their own directory where EM configs will be read from. This may be useful for testing and development without using all config files by default.

Faster tlBMC Development

For faster modify-build-test cycles during BMCWeb code development, testing on a dev machine, we can update just the BMCWeb daemon without a full gBMC firmware update (which can take upwards of 10 min).

For convenience, a summary of the commands necessary is provided below:

# Modify bmcweb code as necessary

$ devtool modify -n bmcweb ${MODIFIED_BMCWEB_CODE_DIR} $ bitbake bmcweb

# scp bmcweb executable over to machine, path may differ depending on machine

$ scp
./tmp/work/armv7a-openbmc-linux-gnueabi/bmcweb/1.0+git/packages-split/bmcweb/usr/bin/bmcweb
root@${HOSTNAME}-nfd01:/tmp/

Service File Change

Similar to above, we can modify the service file to run the bmcweb executable from our /tmp directory, after scp-ing the executable over.

See example below:

$ vi /lib/systemd/system/bmcweb.service

## Inside bmcweb.service
# [Unit]
# Description=Start bmcweb server
# ...
# [Service]
# ExecReload=kill -s HUP $MAINPID
### MODIFY THE LINE BELOW
# ExecStart=/tmp/bmcweb --enable_tlbmc=true [optional: --entity_config_location=${PATH_TO_EM_CONFIG_DIR}]
# Type=simple
# WorkingDirectory=/home/root
# Restart=on-failure
# MemoryMax=300M
# StartLimitInterval=3
# StartLimitBurst=10
# ...

$ systemctl daemon-reload
$ systemctl restart bmcweb

Running from /tmp

For faster iteration cycles, we can run the bmcweb executable directly without modifying the service file, this requires stopping the existing bmcweb service beforehand.

# Stop the existing bmcweb service
$ systemctl stop bmcweb.socket
$ systemctl stop bmcweb

# Run your bmcweb executable
$ /tmp/bmcweb --enable_tlbmc=true

Verifying tlBMC is Active

To verify tlBMC is working, check the logs for a status message from tlBMC on startup.

# Successful startup of tlBMC
$ journalctl -u bmcweb | grep tlbmc
W0000 00:00:1741819016.315426   26690 webserver_main_setup.hpp:224] tlbmc enabled: true

# Failed startup of tlBMC
$ journalctl -u bmcweb | grep -i tlBMC
E0000 00:00:1728402303.645911    2273 webserver_main_setup.hpp:218] Cannot create tlBMC store!! Error: INTERNAL: Invalid config: No root node found - Disabling tlBMC.
W0000 00:00:1728402303.647016    2273 webserver_main_setup.hpp:224] tlbmc enabled: false

Sending tlBMC Only Query

To send a query to tlBMC, with smart routing enabled, any supported tlBMC query will automatically be routed to the tlBMC route.

Supported Query

For supported queries, using curl may be the simplest way to send the query.

# Example of a supported tlBMC query
root@HOSTNAME-nfd01:~# curl localhost/redfish/v1/Chassis
{
  "@odata.id": "/redfish/v1/Chassis",
  "@odata.type": "#ChassisCollection.ChassisCollection",
  "Members": [
    {
      "@odata.id": "/redfish/v1/Chassis/foo"
    },
    {
      "@odata.id": "/redfish/v1/Chassis/bar"
    },
    ...
    {
      "@odata.id": "/redfish/v1/Chassis/baz"
    }
  ],
  "Members@odata.count": 10,
  "Name": "Chassis Collection"
}