Menu Close

Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 4. Additional toolsets for development

4.1. Using GCC Toolset

4.1.1. What is GCC Toolset

Red Hat Enterprise Linux 8 introduces GCC Toolset, an Application Stream containing more up-to-date versions of development and performance analysis tools. GCC Toolset is similar to Red Hat Developer Toolset for RHEL 7.

GCC Toolset is available as an Application Stream in the form of a software collection in the AppStream repository. GCC Toolset is fully supported under Red Hat Enterprise Linux Subscription Level Agreements, is functionally complete, and is intended for production use. Applications and libraries provided by GCC Toolset do not replace the Red Hat Enterprise Linux system versions, do not override them, and do not automatically become default or preferred choices. Using a framework called software collections, an additional set of developer tools is installed into the /opt/ directory and is explicitly enabled by the user on demand using the scl utility. Unless noted otherwise for specific tools or features, GCC Toolset is available for all architectures supported by Red Hat Enterprise Linux.

4.1.2. Installing GCC Toolset

Installing GCC Toolset on a system installs the main tools and all necessary dependencies. Note that some parts of the toolset are not installed by default and must be installed separately.

Procedure

  • To install GCC Toolset version N:

    # yum install gcc-toolset-N

4.1.3. Installing individual packages from GCC Toolset

To install only certain tools from GCC Toolset instead of the whole toolset, list the available packages and install the selected ones with the yum package management tool. This procedure is useful also for packages that are not installed by default with the toolset.

Procedure

  1. List the packages available in GCC Toolset version N:

    $ yum list available gcc-toolset-N-\*
  2. To install any of these packages:

    # yum install package_name

    Replace package_name with a space-separated list of packages to install. For example, to install the gcc-toolset-9-gdb-gdbserver and gcc-toolset-9-gdb-doc packages:

    # yum install gcc-toolset-9-gdb-gdbserver gcc-toolset-9-gdb-doc

4.1.4. Uninstalling GCC Toolset

To remove GCC Toolset from your system, uninstall it using the yum package management tool.

Procedure

  • To uninstall GCC Toolset version N:

    # yum remove gcc-toolset-N\*

4.1.5. Running a tool from GCC Toolset

To run a tool from GCC Toolset, use the scl utility.

Procedure

  • To run a tool from GCC Toolset version N:

    $ scl enable gcc-toolset-N tool

4.1.6. Running a shell session with GCC Toolset

GCC Toolset allows running a shell session where the GCC Toolset tool versions are used instead of system versions of these tools, without explicitly using the scl command. This is useful when you need to interactively start the tools many times, such as when setting up or testing a development setup.

Procedure

  • To run a shell session where tool versions from GCC Toolset version N override system versions of these tools:

    $ scl enable gcc-toolset-N bash

4.2. GCC Toolset 9

This chapter provides information specific to GCC Toolset version 9 and the tools contained in this version.

4.2.1. Tools and versions provided by GCC Toolset 9

GCC Toolset 9 provides the following tools and versions:

Table 4.1. Tool versions in GCC Toolset 9

NameVersionDescription

GCC

9.2.1

A portable compiler suite with support for C, C++, and Fortran.

GDB

8.3

A command-line debugger for programs written in C, C++, and Fortran.

Valgrind

3.15.0

An instrumentation framework and a number of tools to profile applications in order to detect memory errors, identify memory management problems, and report any use of improper arguments in system calls.

SystemTap

4.1

A tracing and probing tool to monitor the activities of the entire system without the need to instrument, recompile, install, and reboot.

Dyninst

10.1.0

A library for instrumenting and working with user-space executables during their execution.

binutils

2.32

A collection of binary tools and other utilities to inspect and manipulate object files and binaries.

elfutils

0.176

A collection of binary tools and other utilities to inspect and manipulate ELF files.

dwz

0.12

A tool to optimize DWARF debugging information contained in ELF shared libraries and ELF executables for size.

make

4.2.1

A dependency-tracking build automation tool.

strace

5.1

A debugging tool to monitor system calls that a program uses and signals it receives.

ltrace

0.7.91

A debugging tool to display calls to dynamic libraries that a program makes. It can also monitor system calls executed by programs.

annobin

9.08

A build security checking tool.

4.2.2. C++ compatibility in GCC Toolset 9

Important

The compatibility information presented here apply only to the GCC from GCC Toolset 9.

The GCC compiler in GCC Toolset can use the following C++ standards:

C++14

This is the default language standard setting for GCC Toolset 9, with GNU extensions, equivalent to explicitly using option -std=gnu++14.

Using the C++14 language version is supported when all C++ objects compiled with the respective flag have been built using GCC version 6 or later.

C++11

This language standard is available in GCC Toolset 9.

Using the C++11 language version is supported when all C++ objects compiled with the respective flag have been built using GCC version 5 or later.

C++98
This language standard is available in GCC Toolset 9. Binaries, shared libraries and objects built using this standard can be freely mixed regardless of being built with GCC from GCC Toolset, Red Hat Developer Toolset, and RHEL 5, 6, 7 and 8.
C++17, C++2a
These language standards are available in GCC Toolset 9 only as an experimental, unstable, and unsupported capability. Additionally, compatibility of objects, binary files, and libraries built using these standards cannot be guaranteed.

All of the language standards are available in both the standard compliant variant or with GNU extensions.

When mixing objects built with GCC Toolset with those built with the RHEL toolchain (particularly .o or .a files), GCC Toolset toolchain should be used for any linkage. This ensures any newer library features provided only by GCC Toolset are resolved at link time.

4.2.3. Specifics of GCC in GCC Toolset 9

Static linking of libraries

Certain more recent library features are statically linked into applications built with GCC Toolset to support execution on multiple versions of Red Hat Enterprise Linux. This creates an additional minor security risk as standard Red Hat Enterprise Linux errata do not change this code. If the need arises for developers to rebuild their applications due to this risk, Red Hat will communicate this using a security erratum.

Important

Because of this additional security risk, developers are strongly advised not to statically link their entire application for the same reasons.

Specify libraries after object files when linking

In GCC Toolset, libraries are linked using linker scripts which might specify some symbols through static archives. This is required to ensure compatibility with multiple versions of Red Hat Enterprise Linux. However, the linker scripts use the names of the respective shared object files. As a consequence, the linker uses different symbol handling rules than expected, and does not recognize symbols required by object files when the option adding the library is specified before options specifying the object files:

$ scl enable gcc-toolset-9 'gcc -lsomelib objfile.o'

Using a library from GCC Toolset in this manner results in the linker error message undefined reference to symbol. To prevent this problem, follow the standard linking practice and specify the option adding the library after the options specifying the object files:

$ scl enable gcc-toolset-9 'gcc objfile.o -lsomelib'

Note that this recommendation also applies when using the base Red Hat Enterprise Linux version of GCC.

4.2.4. Specifics of binutils in GCC Toolset 9

Static linking of libraries

Certain more recent library features are statically linked into applications built with GCC Toolset to support execution on multiple versions of Red Hat Enterprise Linux. This creates an additional minor security risk as standard Red Hat Enterprise Linux errata do not change this code. If the need arises for developers to rebuild their applications due to this risk, Red Hat will communicate this using a security erratum.

Important

Because of this additional security risk, developers are strongly advised not to statically link their entire application for the same reasons.

Specify libraries after object files when linking

In GCC Toolset, libraries are linked using linker scripts which might specify some symbols through static archives. This is required to ensure compatibility with multiple versions of Red Hat Enterprise Linux. However, the linker scripts use the names of the respective shared object files. As a consequence, the linker uses different symbol handling rules than expected, and does not recognize symbols required by object files when the option adding the library is specified before options specifying the object files:

$ scl enable gcc-toolset-9 'ld -lsomelib objfile.o'

Using a library from GCC Toolset in this manner results in the linker error message undefined reference to symbol. To prevent this problem, follow the standard linking practice, and specify the option adding the library after the options specifying the object files:

$ scl enable gcc-toolset-9 'ld objfile.o -lsomelib'

Note that this recommendation also applies when using the base Red Hat Enterprise Linux version of binutils.

4.3. GCC Toolset 10

This chapter provides information specific to GCC Toolset version 10 and the tools contained in this version.

4.3.1. Tools and versions provided by GCC Toolset 10

GCC Toolset 10 provides the following tools and versions:

Table 4.2. Tool versions in GCC Toolset 10

NameVersionDescription

GCC

10.2.1

A portable compiler suite with support for C, C++, and Fortran.

GDB

9.2

A command-line debugger for programs written in C, C++, and Fortran.

Valgrind

3.16.0

An instrumentation framework and a number of tools to profile applications in order to detect memory errors, identify memory management problems, and report any use of improper arguments in system calls.

SystemTap

4.4

A tracing and probing tool to monitor the activities of the entire system without the need to instrument, recompile, install, and reboot.

Dyninst

10.2.1

A library for instrumenting and working with user-space executables during their execution.

binutils

2.35

A collection of binary tools and other utilities to inspect and manipulate object files and binaries.

elfutils

0.182

A collection of binary tools and other utilities to inspect and manipulate ELF files.

dwz

0.12

A tool to optimize DWARF debugging information contained in ELF shared libraries and ELF executables for size.

make

4.2.1

A dependency-tracking build automation tool.

strace

5.7

A debugging tool to monitor system calls that a program uses and signals it receives.

ltrace

0.7.91

A debugging tool to display calls to dynamic libraries that a program makes. It can also monitor system calls executed by programs.

annobin

9.29

A build security checking tool.

4.3.2. C++ compatibility in GCC Toolset 10

Important

The compatibility information presented here apply only to the GCC from GCC Toolset 10.

The GCC compiler in GCC Toolset can use the following C++ standards:

C++14

This is the default language standard setting for GCC Toolset 10, with GNU extensions, equivalent to explicitly using option -std=gnu++14.

Using the C++14 language version is supported when all C++ objects compiled with the respective flag have been built using GCC version 6 or later.

C++11

This language standard is available in GCC Toolset 10.

Using the C++11 language version is supported when all C++ objects compiled with the respective flag have been built using GCC version 5 or later.

C++98
This language standard is available in GCC Toolset 10. Binaries, shared libraries and objects built using this standard can be freely mixed regardless of being built with GCC from GCC Toolset, Red Hat Developer Toolset, and RHEL 5, 6, 7 and 8.
C++17
This language standard is available in GCC Toolset 10.
C++20
This language standard is available in GCC Toolset 10 only as an experimental, unstable, and unsupported capability. Additionally, compatibility of objects, binary files, and libraries built using this standard cannot be guaranteed.

All of the language standards are available in both the standard compliant variant or with GNU extensions.

When mixing objects built with GCC Toolset with those built with the RHEL toolchain (particularly .o or .a files), GCC Toolset toolchain should be used for any linkage. This ensures any newer library features provided only by GCC Toolset are resolved at link time.

4.3.3. Specifics of GCC in GCC Toolset 10

Static linking of libraries

Certain more recent library features are statically linked into applications built with GCC Toolset to support execution on multiple versions of Red Hat Enterprise Linux. This creates an additional minor security risk as standard Red Hat Enterprise Linux errata do not change this code. If the need arises for developers to rebuild their applications due to this risk, Red Hat will communicate this using a security erratum.

Important

Because of this additional security risk, developers are strongly advised not to statically link their entire application for the same reasons.

Specify libraries after object files when linking

In GCC Toolset, libraries are linked using linker scripts which might specify some symbols through static archives. This is required to ensure compatibility with multiple versions of Red Hat Enterprise Linux. However, the linker scripts use the names of the respective shared object files. As a consequence, the linker uses different symbol handling rules than expected, and does not recognize symbols required by object files when the option adding the library is specified before options specifying the object files:

$ scl enable gcc-toolset-10 'gcc -lsomelib objfile.o'

Using a library from GCC Toolset in this manner results in the linker error message undefined reference to symbol. To prevent this problem, follow the standard linking practice and specify the option adding the library after the options specifying the object files:

$ scl enable gcc-toolset-10 'gcc objfile.o -lsomelib'

Note that this recommendation also applies when using the base Red Hat Enterprise Linux version of GCC.

4.3.4. Specifics of binutils in GCC Toolset 10

Static linking of libraries

Certain more recent library features are statically linked into applications built with GCC Toolset to support execution on multiple versions of Red Hat Enterprise Linux. This creates an additional minor security risk as standard Red Hat Enterprise Linux errata do not change this code. If the need arises for developers to rebuild their applications due to this risk, Red Hat will communicate this using a security erratum.

Important

Because of this additional security risk, developers are strongly advised not to statically link their entire application for the same reasons.

Specify libraries after object files when linking

In GCC Toolset, libraries are linked using linker scripts which might specify some symbols through static archives. This is required to ensure compatibility with multiple versions of Red Hat Enterprise Linux. However, the linker scripts use the names of the respective shared object files. As a consequence, the linker uses different symbol handling rules than expected, and does not recognize symbols required by object files when the option adding the library is specified before options specifying the object files:

$ scl enable gcc-toolset-10 'ld -lsomelib objfile.o'

Using a library from GCC Toolset in this manner results in the linker error message undefined reference to symbol. To prevent this problem, follow the standard linking practice, and specify the option adding the library after the options specifying the object files:

$ scl enable gcc-toolset-10 'ld objfile.o -lsomelib'

Note that this recommendation also applies when using the base Red Hat Enterprise Linux version of binutils.

4.4. GCC Toolset 11

This chapter provides information specific to GCC Toolset version 11 and the tools contained in this version.

4.4.1. Tools and versions provided by GCC Toolset 11

GCC Toolset 11 provides the following tools and versions:

Table 4.3. Tool versions in GCC Toolset 11

NameVersionDescription

GCC

11.2.1

A portable compiler suite with support for C, C++, and Fortran.

GDB

10.2

A command-line debugger for programs written in C, C++, and Fortran.

Valgrind

3.17.0

An instrumentation framework and a number of tools to profile applications in order to detect memory errors, identify memory management problems, and report any use of improper arguments in system calls.

SystemTap

4.5

A tracing and probing tool to monitor the activities of the entire system without the need to instrument, recompile, install, and reboot.

Dyninst

11.0.0

A library for instrumenting and working with user-space executables during their execution.

binutils

2.36.1

A collection of binary tools and other utilities to inspect and manipulate object files and binaries.

elfutils

0.185

A collection of binary tools and other utilities to inspect and manipulate ELF files.

dwz

0.14

A tool to optimize DWARF debugging information contained in ELF shared libraries and ELF executables for size.

make

4.3

A dependency-tracking build automation tool.

strace

5.13

A debugging tool to monitor system calls that a program uses and signals it receives.

ltrace

0.7.91

A debugging tool to display calls to dynamic libraries that a program makes. It can also monitor system calls executed by programs.

annobin

10.23

A build security checking tool.

4.4.2. C++ compatibility in GCC Toolset 11

Important

The compatibility information presented here apply only to the GCC from GCC Toolset 11.

The GCC compiler in GCC Toolset can use the following C++ standards:

C++14

This language standard is available in GCC Toolset 11.

Using the C++14 language version is supported when all C++ objects compiled with the respective flag have been built using GCC version 6 or later.

C++11

This language standard is available in GCC Toolset 11.

Using the C++11 language version is supported when all C++ objects compiled with the respective flag have been built using GCC version 5 or later.

C++98
This language standard is available in GCC Toolset 11. Binaries, shared libraries and objects built using this standard can be freely mixed regardless of being built with GCC from GCC Toolset, Red Hat Developer Toolset, and RHEL 5, 6, 7 and 8.
C++17

This language standard is available in GCC Toolset 11.

This is the default language standard setting for GCC Toolset 11, with GNU extensions, equivalent to explicitly using option -std=gnu++17.

Using the C++17 language version is supported when all C++ objects compiled with the respective flag have been built using GCC version 10 or later.

C++20 and C++23

This language standard is available in GCC Toolset 11 only as an experimental, unstable, and unsupported capability. Additionally, compatibility of objects, binary files, and libraries built using this standard cannot be guaranteed.

To enable C++20 support, add the command-line option -std=c++20 to your g++ command line.

To enable C++23 support, add the command-line option -std=c++2b to your g++ command line.

All of the language standards are available in both the standard compliant variant or with GNU extensions.

When mixing objects built with GCC Toolset with those built with the RHEL toolchain (particularly .o or .a files), GCC Toolset toolchain should be used for any linkage. This ensures any newer library features provided only by GCC Toolset are resolved at link time.

4.4.3. Specifics of GCC in GCC Toolset 11

Static linking of libraries

Certain more recent library features are statically linked into applications built with GCC Toolset to support execution on multiple versions of Red Hat Enterprise Linux. This creates an additional minor security risk as standard Red Hat Enterprise Linux errata do not change this code. If the need arises for developers to rebuild their applications due to this risk, Red Hat will communicate this using a security erratum.

Important

Because of this additional security risk, developers are strongly advised not to statically link their entire application for the same reasons.

Specify libraries after object files when linking

In GCC Toolset, libraries are linked using linker scripts which might specify some symbols through static archives. This is required to ensure compatibility with multiple versions of Red Hat Enterprise Linux. However, the linker scripts use the names of the respective shared object files. As a consequence, the linker uses different symbol handling rules than expected, and does not recognize symbols required by object files when the option adding the library is specified before options specifying the object files:

$ scl enable gcc-toolset-11 'gcc -lsomelib objfile.o'

Using a library from GCC Toolset in this manner results in the linker error message undefined reference to symbol. To prevent this problem, follow the standard linking practice and specify the option adding the library after the options specifying the object files:

$ scl enable gcc-toolset-11 'gcc objfile.o -lsomelib'

Note that this recommendation also applies when using the base Red Hat Enterprise Linux version of GCC.

4.4.4. Specifics of binutils in GCC Toolset 11

Static linking of libraries

Certain more recent library features are statically linked into applications built with GCC Toolset to support execution on multiple versions of Red Hat Enterprise Linux. This creates an additional minor security risk as standard Red Hat Enterprise Linux errata do not change this code. If the need arises for developers to rebuild their applications due to this risk, Red Hat will communicate this using a security erratum.

Important

Because of this additional security risk, developers are strongly advised not to statically link their entire application for the same reasons.

Specify libraries after object files when linking

In GCC Toolset, libraries are linked using linker scripts which might specify some symbols through static archives. This is required to ensure compatibility with multiple versions of Red Hat Enterprise Linux. However, the linker scripts use the names of the respective shared object files. As a consequence, the linker uses different symbol handling rules than expected, and does not recognize symbols required by object files when the option adding the library is specified before options specifying the object files:

$ scl enable gcc-toolset-11 'ld -lsomelib objfile.o'

Using a library from GCC Toolset in this manner results in the linker error message undefined reference to symbol. To prevent this problem, follow the standard linking practice, and specify the option adding the library after the options specifying the object files:

$ scl enable gcc-toolset-11 'ld objfile.o -lsomelib'

Note that this recommendation also applies when using the base Red Hat Enterprise Linux version of binutils.

4.5. Using the GCC Toolset container images

Only the GCC Toolset 11 container images are supported. Container images of earlier GCC Toolset versions are deprecated.

The GCC Toolset 11 components are available in the two container images:

  • GCC Toolset 11 Toolchain
  • GCC Toolset 11 Perftools

The GCC Toolset container images are based on the rhel8 base image and are available for all architectures supported by RHEL 8:

  • AMD and Intel 64-bit architectures
  • The 64-bit ARM architecture
  • IBM Power Systems, Little Endian
  • 64-bit IBM Z

4.5.1. GCC Toolset container images contents

Tools versions provided in the GCC Toolset 11 container images match the GCC Toolset 11 components versions.

The GCC Toolset 11 Toolchain contents

The rhel8/gcc-toolset-11-toolchain image provides the GCC compiler, the GDB debugger, and other development-related tools. The container image consists of the following components:

ComponentPackage

gcc

gcc-toolset-11-gcc

g++

gcc-toolset-11-gcc-c++

gfortran

gcc-toolset-11-gcc-gfortran

gdb

gcc-toolset-11-gdb

The GCC Toolset 11 Perftools contents

The rhel8/gcc-toolset-11-perftools image provides a number of tools for debugging, performance monitoring, and further analysis of the applications. The container image consists of the following components:

ComponentPackage

Valgrind

gcc-toolset-11-valgrind

SystemTap

gcc-toolset-11-systemtap

Dyninst

gcc-toolset-11-dyninst

elfutils

gcc-toolset-11-elfutils

Additional resources

4.5.2. Accessing and running the GCC Toolset container images

The following section describes how to access and run the GCC Toolset container images.

Prerequisites

  • Podman is installed.

Procedure

  1. Access the Red Hat Container Registry using your Customer Portal credentials:

    $ podman login registry.redhat.io
    Username: username
    Password: ********
  2. Pull a container image you require by running a relevant command as root:

    # podman pull registry.redhat.io/rhel8/gcc-toolset-11-toolchain
    # podman pull registry.redhat.io/rhel8/gcc-toolset-11-perftools
    Note

    On RHEL 8.1 and later versions, you can set up your system to work with containers as a non-root user. For details, see Setting up rootless containers.

  3. Optional: Check that pulling was successful by running a command that lists all container images on your local system:

    # podman images
  4. Run a container by launching a bash shell inside a container:

    # podman run -it image_name /bin/bash

    The -i option creates an interactive session; without this option the shell opens and instantly exits.

    The -t option opens a terminal session; without this option you cannot type anything to the shell.

Additional resources

4.5.3. Example: Using the GCC Toolset 11 Toolchain container image

This example shows how to pull and start using the GCC Toolset 11 Toolchain container image.

Prerequisites

  • Podman is installed.

Procedure

  1. Access the Red Hat Container Registry using your Customer Portal credentials:

    $ podman login registry.redhat.io
    Username: username
    Password: ********
  2. Pull the container image as root:

    # podman pull registry.redhat.io/rhel8/gcc-toolset-11-toolchain
  3. Launch the container image with an interactive shell as root:

    # podman run -it registry.redhat.io/rhel8/gcc-toolset-11-toolchain /bin/bash
  4. Run the GCC Toolset tools as expected. For example, to verify the gcc compiler version, run:

    bash-4.4$ gcc -v
    ...
    gcc version 10.2.1 20200804 (Red Hat 10.2.1-2) (GCC)
  5. To list all packages provided in the container, run:

    bash-4.4$ rpm -qa

4.5.4. Using SystemTap from the GCC Toolset 11 Perftools container image

The SystemTap tool is distributed in the GCC Toolset 11 Perftools container image. To use this tool, follow the steps listed below.

Prerequisites

  • The GCC Toolset 11 Perftools container image is pulled.

Procedure

  1. Run the image with super-user privileges:

    $ podman run -u root -it --privileged --ipc=host --net=host --pid=host registry.redhat.io/rhel8/gcc-toolset-11-perftools /bin/bash

    To learn more about super privileged containers, see Running super privileged containers.

  2. Install the required kernel packages in the container:

    1. Using stap-prep:

      # stap-prep
    2. If that fails, install the following packages manually:

      • kernel
      • kernel-devel
      • kernel-debuginfo

        Important

        The version and release numbers of the above-mentioned kernel packages must match the version and release numbers of the kernel running on the host system.

        • To check the version and release numbers of the host system kernel, run:

          $ uname -r
          4.18.0-193.el8.x86_64
        • To install matching versions of the packages, run the package installation command with the uname command output. For example:

          # yum install kernel-devel-$(uname -r)
        • To install the kernel-debuginfo package, first enable the debug repository by running the following command as root:

          # subscription-manager repos --enable=rhel-8-for-x86_64-baseos-debug-rpms

        To learn more about installing debuginfo packages on RHEL systems, see How can I download or install debuginfo packages for RHEL systems?

  3. Optional: To avoid repeating these steps and reuse this preconfigured container in the future, consider saving it by running:

    $ podman commit new-container-image-name

4.6. Compiler toolsets

RHEL 8 provides the following compiler toolsets as Application Streams:

  • LLVM Toolset provides the LLVM compiler infrastructure framework, the Clang compiler for the C and C++ languages, the LLDB debugger, and related tools for code analysis.
  • Rust Toolset provides the Rust programming language compiler rustc, the cargo build tool and dependency manager, the cargo-vendor plugin, and required libraries.
  • Go Toolset provides the Go programming language tools and libraries. Go is alternatively known as golang.

For more details and information on usage, see the compiler toolsets user guides on the Red Hat Developer Tools page.

4.7. The Annobin project

The Annobin project is an implementation of the Watermark specification project. Watermark specification project intends to add markers to Executable and Linkable Format (ELF) objects to determine their properties. The Annobin project consists of the annobin plugin and the annockeck program.

The annobin plugin scans the GNU Compiler Collection (GCC) command line, the compilation state, and the compilation process, and generates the ELF notes. The ELF notes record how the binary was built and provide information for the annocheck program to perform security hardening checks.

The security hardening checker is part of the annocheck program and is enabled by default. It checks the binary files to determine whether the program was built with necessary security hardening options and compiled correctly. annocheck is able to recursively scan directories, archives, and RPM packages for ELF object files.

Note

The files must be in ELF format. annocheck does not handle any other binary file types.

The following section describes how to:

  • Use the annobin plugin
  • Use the annocheck program
  • Remove redundant annobin notes

4.7.1. Using the annobin plugin

The following section describes how to:

  • Enable the annobin plugin
  • Pass options to the annobin plugin

4.7.1.1. Enabling the annobin plugin

The following section describes how to enable the annobin plugin via gcc and via clang.

Procedure

  • To enable the annobin plugin with gcc, use:

    $ gcc -fplugin=annobin
    • If gcc does not find the annobin plugin, use:

      $ gcc -iplugindir=/path/to/directory/containing/annobin/

      Replace /path/to/directory/containing/annobin/ with the absolute path to the directory that contains annobin.

    • To find the directory containing the annobin plugin, use:

      $ gcc --print-file-name=plugin
  • To enable the annobin plugin with clang, use:

    $ clang -fplugin=/path/to/directory/containing/annobin/

    Replace /path/to/directory/containing/annobin/ with the absolute path to the directory that contains annobin.

4.7.1.2. Passing options to the annobin plugin

The following section describes how to pass options to the annobin plugin via gcc and via clang.

Procedure

  • To pass options to the annobin plugin with gcc, use:

    $ gcc -fplugin=annobin -fplugin-arg-annobin-option file-name

    Replace option with the annobin command line arguments and replace file-name with the name of the file.

    Example

    • To display additional details about what annobin it is doing, use:

      $ gcc -fplugin=annobin -fplugin-arg-annobin-verbose file-name

      Replace file-name with the name of the file.

  • To pass options to the annobin plugin with clang, use:

    $ clang -fplugin=/path/to/directory/containing/annobin/ -Xclang -plugin-arg-annobin -Xclang option file-name

    Replace option with the annobin command line arguments and replace /path/to/directory/containing/annobin/ with the absolute path to the directory containing annobin.

    Example

    • To display additional details about what annobin it is doing, use:

      $ clang -fplugin=/usr/lib64/clang/10/lib/annobin.so -Xclang -plugin-arg-annobin -Xclang verbose file-name

      Replace file-name with the name of the file.

4.7.2. Using the annocheck program

The following section describes how to use annocheck to examine:

  • Files
  • Directories
  • RPM packages
  • annocheck extra tools
Note

annocheck recursively scans directories, archives, and RPM packages for ELF object files. The files have to be in the ELF format. annocheck does not handle any other binary file types.

4.7.2.1. Using annocheck to examine files

The following section describes how to examine ELF files using annocheck.

Procedure

  • To examine a file, use:

    $ annocheck file-name

    Replace file-name with the name of a file.

Note

The files must be in ELF format. annocheck does not handle any other binary file types. annocheck processes static libraries that contain ELF object files.

Additional information

  • For more information about annocheck and possible command line options, see the annocheck man page.

4.7.2.2. Using annocheck to examine directories

The following section describes how to examine ELF files in a directory using annocheck.

Procedure

  • To scan a directory, use:

    $ annocheck directory-name

    Replace directory-name with the name of a directory. annocheck automatically examines the contents of the directory, its sub-directories, and any archives and RPM packages within the directory.

Note

annocheck only looks for ELF files. Other file types are ignored.

Additional information

  • For more information about annocheck and possible command line options, see the annocheck man page.

4.7.2.3. Using annocheck to examine RPM packages

The following section describes how to examine ELF files in an RPM package using annocheck.

Procedure

  • To scan an RPM package, use:

    $ annocheck rpm-package-name

    Replace rpm-package-name with the name of an RPM package. annocheck recursively scans all the ELF files inside the RPM package.

Note

annocheck only looks for ELF files. Other file types are ignored.

  • To scan an RPM package with provided debug info RPM, use:

    $ annocheck rpm-package-name --debug-rpm debuginfo-rpm

    Replace rpm-package-name with the name of an RPM package, and debuginfo-rpm with the name of a debug info RPM associated with the binary RPM.

Additional information

  • For more information about annocheck and possible command line options, see the annocheck man page.

4.7.2.4. Using annocheck extra tools

annocheck includes multiple tools for examining binary files. You can enable these tools with the command-line options.

The following section describes how to enable the:

  • built-by tool
  • notes tool
  • section-size tool

You can enable multiple tools at the same time.

Note

The hardening checker is enabled by default.

4.7.2.4.1. Enabling the built-by tool

You can use the annocheck built-by tool to find the name of the compiler that built the binary file.

Procedure

  • To enable the built-by tool, use:

    $ annocheck --enable-built-by

Additional information

  • For more information about the built-by tool, see the --help command-line option.
4.7.2.4.2. Enabling the notes tool

You can use the annocheck notes tool to display the notes stored inside a binary file created by the annobin plugin.

Procedure

  • To enable the notes tool, use:

    $ annocheck --enable-notes

    The notes are displayed in a sequence sorted by the address range.

Additional information

  • For more information about the notes tool, see the --help command-line option.
4.7.2.4.3. Enabling the section-size tool

You can use the annocheck section-size tool display the size of the named sections.

Procedure

  • To enable the section-size tool, use:

    $ annocheck --section-size=name

    Replace name with the name of the named section. The output is restricted to specific sections. A cumulative result is produced at the end.

Additional information

  • For more information about the section-size tool, see the --help command-line option.
4.7.2.4.4. Hardening checker basics

The hardening checker is enabled by default. You can disable the hardening checker with the --disable-hardened command-line option.

4.7.2.4.4.1. Hardening checker options

The annocheck program checks the following options:

  • Lazy binding is disabled using the -z now linker option.
  • The program does not have a stack in an executable region of memory.
  • The relocations for the GOT table are set to read only.
  • No program segment has all three of the read, write and execute permission bits set.
  • There are no relocations against executable code.
  • The runpath information for locating shared libraries at runtime includes only directories rooted at /usr.
  • The program was compiled with annobin notes enabled.
  • The program was compiled with the -fstack-protector-strong option enabled.
  • The program was compiled with -D_FORTIFY_SOURCE=2.
  • The program was compiled with -D_GLIBCXX_ASSERTIONS.
  • The program was compiled with -fexceptions enabled.
  • The program was compiled with -fstack-clash-protection enabled.
  • The program was compiled at -O2 or higher.
  • The program does not have any relocations held in a writeable.
  • Dynamic executables have a dynamic segment.
  • Shared libraries were compiled with -fPIC or -fPIE.
  • Dynamic executables were compiled with -fPIE and linked with -pie.
  • If available, the -fcf-protection=full option was used.
  • If available, the -mbranch-protection option was used.
  • If available, the -mstackrealign option was used.
4.7.2.4.4.2. Disabling the hardening checker

The following section describes how to disable the hardening checker.

Procedure

  • To scan the notes in a file without the hardening checker, use:

    $ annocheck --enable-notes --disable-hardened file-name

    Replace file-name with the name of a file.

4.7.3. Removing redundant annobin notes

Using annobin increases the size of binaries. To reduce the size of the binaries compiled with annobin you can remove redundant annobin notes. To remove the redundant annobin notes use the objcopy program, which is a part of the binutils package.

Procedure

  • To remove the redundant annobin notes, use:

      $ objcopy --merge-notes file-name

    Replace file-name with the name of the file.