manifest
Access rate limit exceeded. Please log in to continue.
manifest
This code repository is an openUBMC product integration configuration repository.
Setting Up the Development Environment
openUBMC currently supports code development only on Ubuntu 24.04. To help developers quickly set up the environment, the following methods are available:
Method 1: Local environment initialization script (applicable to Ubuntu 24.04)
Method 2: Using an officially released Docker image to create a Docker container
Method 3: Building a Docker container from source code (Using a Dockerfile source code file)
Choose any of the above methods to configure a complete openUBMC development environment.
-
If your OS is Ubuntu 24.04, run the local script to initialize the environment.
-
For container-based development, choose method 2 or 3. Method 2 provides a stable Docker environment with only the openUBMC development environment. Method 3 provides the latest development version with the openUBMC environment and dependencies for compiling and running QEMU and Studio.
Select a proper solution based on your requirements.
Method 1: Initializing the Local Environment
[NOTE] This method works only on Ubuntu 24.04. The environment initialization script prioritizes the local APT source and downloads the bingo tool. If no APT source is configured, it automatically uses the official openUBMC APT source.
The init.py script in the repository root directory initializes the openUBMC development environment. Pull the code repository to your local PC, then download the community component bmcsdk from the openUBMC community software application center. Import the downloaded bmcsdk package path as a parameter and run the script to initialize the development environment.
cd manifest
python3 init.py -path <bmc_sdk.zip_file_path > -user <openUBMC_community_username> -psw <openUBMC_community_user_password>
[NOTE] If
-pswand-userare not specified, you need to enter the account and password in interactive mode. (Recommended)
Method 2: Building an openUBMC Development Environment Using an Official Docker Image
For details, see Official Document - Setting Up the Development Environment with Docker.
Method 3: Building an openUBMC Development Environment Using the Dockerfile
[NOTE] During image creation using the Dockerfile, it configures the official openUBMC APT source by default and downloads bingo. To use a custom APT source, modify the APT source configuration in the
init.py --> install_bingo()method.
This repository provides a Dockerfile with all instructions for building the openUBMC environment image.
- Download the community component
bmcsdkfrom the openUBMC community software application center and record the local path (anywhere). In themanifestdirectory, use the providedbuild_image.pyscript to build the image, passing the SDK path and openUBMC community account information as parameters.
cd manifest
python3 build_image.py \
-s <bmc_sdk.zip_file_path, which can be a relative or absolute path> \
-u <openUBMC_community_username> \
-p <openUBMC_community_password.> \
-t openubmc/xx.yy
[NOTE]
build_image.pyuses BuildKit secrets to mount the SDK and credentials during the build. Credentials are not written into the Dockerfile or image layers during the entire process. For Docker versions ≤ 20.09, setDOCKER_BUILDKIT=1to use the secret mechanism. The script automatically configures this variable.
Parameter description:
-t defines the image name.
- After the build is successful, verify whether the image is successfully loaded.
docker images
- Create a container instance for the generated
openubmc/xx.yyimage and name the container instanceopenubmc.
docker run \
-p <BMC_Studio_service_port>:10000 \
-p <qemu_ssh_external_service_port>:<qemu_ssh_service_port> \
...
-d --mount type=bind,source=/root/workspace,target=/home/workspace \
--restart=always --name openubmc openubmc/xx.yy
Parameter description:
-p specifies container port mappings. Set this parameter as needed. The default port for BMC Studio is 10000. The default ports are 10022 for the QEMU SSH service, 10023 for Telnet, 10443 for the HTTPS service, and 10623 for the IPMI service.
-d starts the container in non-interactive mode.
--mount links the /root/workspace folder created on the host to the /home/workspace folder in the container as a synchronization folder.
--restart=always automatically starts the container when the system restarts.
--name defines the container name.
- View running containers.
docker ps
- Access the
openubmccontainer.
docker exec -it openubmc /bin/bash
If the command is executed successfully, you have accessed the openubmc container.
Git Repository Configuration
The required tools and dependencies for openUBMC development are already configured in the environment. Next, complete the global Git configuration on your local PC and add your local SSH public key to the SSH keys of the GitCode repository. Then, you can start code development, upload code to the repository, and perform local builds. For steps 2 to 4, see Configuring SSH for GitCode.
- Complete the global Git configuration on your local PC:
git config --global user.name <Your_username>
git config --global user.email <Your_email_address>
- Generate an RSA key:
ssh-keygen -t rsa -b 2048 -C <Your_email_address>
- View the RSA public key:
cat ~/.ssh/id_rsa.pub
- The preceding steps will return the RSA key in the local console. Add the key to the SSH public keys of GitCode.
Then, you can clone the code from the Git repository in the container and develop and build code in the container.
QEMU Startup
openUBMC also provides a QEMU simulation environment for verifying the openUBMC artifact package. Run the following command to start QEMU:
bingo qemu >qemu_stdout.log 2>qemu_stderr.log
If the following output appears, QEMU has started successfully:
Uncompressing... done, booting...
[ 0.000000] Booting Linux on physical CPU 0x0000000000 [0x412fd050]
[ 0.000000] Linux version 5.10.0 (oe-user@oe-host) (aarch64-euler-linux-gcc (BiSheng Embedded CPU 302.1.0.B016) 7.3.0, GNU ld (BiSheng Embedded CPU 302.1.0.B016) 2.41) #1 SMP PREEMPT Tue Nov 26 22:03:48 CST 2024
You can also configure the build/works/packet/qemu_shells/config.json file to determine the way to start QEMU. For details, see build/works/packet/qemu_shells/schema.json.
One-Click Deployment of Visualization Backends
The openUBMC image provides all visualization backends required by the observability feature. Developers can use the installation script to deploy all backends in one-click mode, saving the installation time.
Observability Feature
For the basic concepts, see Observability. For details about how to use the observability feature, see Observability User Guide, which describes how to configure the BMC observability page and how to use the visualized backend integrated in the image.
Deployment Method
Follow these steps to deploy visualization backends:
-
- The observability feature requires TLS transmission. The image does not include a pre-configured certificate. You must provide a TLS certificate.
-
- When configuring the container instance creation command for the generated
openubmc/xx.yyimage, you must also bind the required ports and mount the necessary folders for visualization backend communication. This prevents port connection issues and communication failures between the BMC and the visualization backends.
- When configuring the container instance creation command for the generated
-
- After entering the container, run the deployment script. Once the script executes successfully, the deployment is complete.
1 Preparing Certificates
For details, see section 2.2 "Preparing Certificates and Key Files" in Observable Environment Setup of the community wiki.
After the certificate is created, ensure that:
-
- The SSL certificate is named
observability.otelcol.crt.
- The SSL certificate is named
-
- The SSL key is named
observability.otelcol.key.pem.
- The SSL key is named
You must upload the CA certificate to the BMC, and store the SSL certificate and SSL key in the same local directory for Docker volume mounting.
2 Generating a Container
To access the visualization backends, run the following image command to append port bindings and volume mounts to your container instance creation command for the generated openubmc/xx.yy image. Failing to do so will cause port connection errors and communication failures between the BMC and the visualization
docker run \
-p <BMC_Studio_service_port>:10000 \
-p <qemu_ssh_external_service_port>:<qemu_ssh_service_port> \
-p <zipkin_external_service_port>:9411/tcp \
-p <otelcol_external_service_port>:4318/tcp \
-p <prometheus_external_service_port>:49092/tcp \
-p <grafana_external_service_port>:3000/tcp \
...
-d --mount type=bind,source=/root/workspace,target=/home/workspace \
--mount type=bind,source=<Certificate_storage_path>,target=/root/workspace/observability/collector-contrib/cert \
--restart=always --name openubmc openubmc/xx.yy
You must configure the following four mandatory ports for the visualization backends:
- Port
9411is the default port for Zipkin. We recommend settingzipkin_external_service_portto9411or another available port. - Port
4318is the default port forotelcol. We recommend settingotelcol_external_service_portto4318or another available port. - Port
49092is the default port for Prometheus. We recommend settingprometheus_external_service_portto49092or another available port. - Port
3000is the default port for Grafana. We recommend settinggrafana_external_service_portto3000or another available port.
Certificate_storage_path specifies the path for storing the certificates and keys required by the visualization backends. Replace this with your actual SSL certificate and SSL key paths prepared in step 1. /root/workspace/observability/collector-contrib/cert is the path for the otelcol in the image to read certificate files. Do not modify this path.
3 Running the Deployment Script
After entering the container, perform the following steps:
-
- Run the
su rootcommand to switch to root user.
- Run the
-
- Run the
cd /root/workspace/observabilitycommand to go to the directory integrated with the visualization backends.
- Run the
-
- Run the
bash observability.sh startcommand to start visualization backends.
- Run the
-
- Generally, you can proceed directly to step 5 after step 3 is complete. However, if
Password for the [elastic] user successfully reset.is not displayed in the command output, the Elasticsearch password reset failed. In this case, manually runexpect /root/workspace/observability/reset_elastic_password.expagain to reset the Elasticsearch password to the default value.
- Generally, you can proceed directly to step 5 after step 3 is complete. However, if
-
- After the preceding steps are complete, access the Grafana external service port (for example,
127.0.0.1:3000) to access the Grafana terminal. Use the defaultusername admin and password adminfor your first login.
- After the preceding steps are complete, access the Grafana external service port (for example,
-
- You can also access the Zipkin terminal via its external service port (for example,
127.0.0.1:9411) to query tracing data, or access the Prometheus terminal via its external service port (for example,127.0.0.1:49092) to query metric data.
- You can also access the Zipkin terminal via its external service port (for example,