How to build agent distribution packages¶

Intro¶

What are distribution packages ?¶

By "distribution package", we mean an artifact used by end users to install the Agent on their system. The format is OS-specific:

These distribution packages contain a binary of the Agent, along with any supporting libraries needed for the agent to function properly.

Omnibus¶

Agent packages for all the supported platforms are built using Omnibus.

Omnibus is best called indirectly, via dda commands. The main entrypoint is the omnibus.build invoke task, which you can run like this:

dda inv omnibus.build

This will probably not work out of the box though - see instructions below for more information.

Building for Linux: deb¶

Using the dev env¶

The developer environments we provide contain all the dependencies required for building Omnibus packages, along with extra tools and features that make local development easier. We recommend that you use them for all your development needs.

To build distribution packages in a developer environment:

1. Follow the dev env tutorial to install the required tools and familiarize yourself with the dev environments.
2. Make sure Docker is running on your system.
3. Start a developer environment, which will automatically pull the latest version of the container image: dda env dev start

4. Either:

   • Connect to a shell inside the dev container: dda env dev shell
   • Open an IDE window inside the container: dda env dev code
   • Run a single command inside the container: prefix the command in the next step with dda env dev run

5. Run the following command:

   dda inv -- -e omnibus.build
   

Once the process completes, the built artifacts will be available in the container under /omnibus/pkg.

mv /omnibus/pkg /root/repos/datadog-agent/bin

Using the build image¶

We provide a Docker image containing all the build dependencies required for building deb packages via Omnibus: datadog/agent-buildimages-linux.This image is the one used by CI, and as such it is quite bare-bones. The developer environments mentioned in the section above are based on this image.

docker build -t datadog-agent-buildimages:linux -f linux/Dockerfile .

1. Make sure Docker is running on your machine.
2. Navigate to the root folder of a clone of the datadog-agent repo.
3. Run the following command, which will create a container for the previously-mentioned image, and run the omnibus.build task inside.

   docker run
       -v "$PWD:/go/src/github.com/DataDog/datadog-agent"
       -v "/tmp/omnibus:/omnibus"
       -v "/tmp/opt/datadog-agent:/opt/datadog-agent"
       -v"/tmp/gems:/gems"
       --workdir=/go/src/github.com/DataDog/datadog-agent
       datadog/agent-buildimages-linux
       dda inv -- -e omnibus.build --base-dir=/omnibus --gem-path=/gems
   

Once the process completes, the built artifacts will be available on your host under /tmp/omnibus/pkg.

Building on the host (discouraged)¶

Running an Omnibus build will both create and install an Agent distribution package.

• The project will be built locally into a .tar.xz archive under omnibus/pkg.
• The project will be installed under /opt/datadog-agent. This is the same path where the Agent is installed on customer machines.

1. Follow the general local setup instructions
2. Make /opt world-readable
3. Run the following command:

   dda inv -- omnibus.build --base-dir=$HOME/.omnibus
   

The path you pass with the --base-dir option will be used as a working directory for the Omnibus build. Once the build completes, it will contain:

Building for Linux: rpm¶

Some extra dependencies are required for building rpm packages that are not yet included in the main datadog/agent-buildimages-linux build image.

A separate docker image containing these special dependencies is also available. This image, contrary to the main datadog/agent-buildimages-linux image, is not multi-arch - thus there are two flavors depending on the CPU architecture of the host machine:

• For x86_64/amd64: datadog/agent-buildimages-rpm_x64
• For arm64/aarch64: datadog/agent-buildimages-rpm_arm64

To build using these images, follow the same instructions as for deb packages, but replace datadog/agent-buildimages-linux with the appropriate flavor of the rpm image for your CPU platform. You can also attempt a host-based build, although this is heavily discouraged.

Building for MacOS¶

We do not currently support MacOS development environments or any container build image. You will therefore need to follow the host-based build instructions.

When running the build command, you might want to skip the signing step by adding the --skip-sign flag.

Building for Windows¶

First, mount / clone a checkout of the datadog-agent repo inside the container.

The recommended way to do this while developing manually is to bind-mount your host's checkout of the repo into the container.On the host, while inside the datadog-agent repo:

docker run -v "$(Get-Location):c:\mnt" <image>

You can then invoke one of the windows build scripts, available in tasks/winbuildscripts:

• Build-AgentPackages.ps1 is used for building the "main" Agent msi package
• Build-OmnibusTarge.ps1 is used for building all other Agent packages via Omnibus
• Build-InstallerPackages.ps1 is used for building the .exe installer for the Agent.

These scripts read a few environment variables, notably (non-exhaustive !):

• OMNIBUS_TARGET - usually set to main
• TARGET_ARCH - only x64 is supported at the moment

docker run -v "$(Get-Location):c:\mnt" -e OMNIBUS_TARGET=main -e TARGET_ARCH=x64 registry.ddbuild.io/ci/datadog-agent-buildimages/windows_ltsc2025_x64:v77240728-510448c3 powershell -C "c:\mnt\tasks\winbuildscripts\Build-AgentPackages.ps1 -BuildOutOfSource 1 -InstallDeps 1 -CheckGoVersion 1"

If the build succeeds, the build artifacts can be found under omnibus\pkg in the repo.