tlbmc/g3doc/general/getting_started.md

# Getting Started with tlBMC

go/tlbmc-getting-started

<!--*
# Document freshness: For more information, see go/fresh-source.
freshness: { owner: 'tlbmc-dev' reviewed: '2025-03-12' }
*-->

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

[TOC]

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

```shell
$ 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:

```shell
# 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:

```shell
$ 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.

```shell
# 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.

```shell
# 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.

```shell
# 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"
}
```