2 title: Hacking on systemd
5 SPDX-License-Identifier: LGPL-2.1-or-later
10 We welcome all contributions to systemd. If you notice a bug or a missing
11 feature, please feel invited to fix it, and submit your work as a
12 [GitHub Pull Request (PR)](https://github.com/systemd/systemd/pull/new).
14 Please make sure to follow our [Coding Style](CODING_STYLE.md) when submitting
15 patches. Also have a look at our [Contribution Guidelines](CONTRIBUTING.md).
17 When adding new functionality, tests should be added. For shared functionality
18 (in `src/basic/` and `src/shared/`) unit tests should be sufficient. The general
19 policy is to keep tests in matching files underneath `src/test/`,
20 e.g. `src/test/test-path-util.c` contains tests for any functions in
21 `src/basic/path-util.c`. If adding a new source file, consider adding a matching
22 test executable. For features at a higher level, tests in `src/test/` are very
23 strongly recommended. If that is not possible, integration tests in `test/` are
26 Please also have a look at our list of [code quality tools](CODE_QUALITY.md) we
27 have setup for systemd, to ensure our codebase stays in good shape.
29 Please always test your work before submitting a PR. For many of the components
30 of systemd testing is straightforward as you can simply compile systemd and
31 run the relevant tool from the build directory.
33 For some components (most importantly, systemd/PID 1 itself) this is not
34 possible, however. In order to simplify testing for cases like this we provide
35 a set of `mkosi` build files directly in the source tree.
36 [mkosi](https://github.com/systemd/mkosi) is a tool for building clean OS images
37 from an upstream distribution in combination with a fresh build of the project
38 in the local working directory. To make use of this, please install `mkosi` v19
39 or newer using your distribution's package manager or from the
40 [GitHub repository](https://github.com/systemd/mkosi). `mkosi` will build an
41 image for the host distro by default. First, run `mkosi genkey` to generate a key
42 and certificate to be used for secure boot and verity signing. After that is done,
43 it is sufficient to type `mkosi` in the systemd project directory to generate a disk
44 image you can boot either in `systemd-nspawn` or in a UEFI-capable VM:
47 $ sudo mkosi boot # nspawn still needs sudo for now
56 Every time you rerun the `mkosi` command a fresh image is built, incorporating
57 all current changes you made to the project tree.
59 By default a directory image is built. This requires `virtiofsd` to be installed
60 on the host. To build a disk image instead which does not require `virtiofsd`,
61 add the following to `mkosi.local.conf`:
68 To boot in UEFI mode instead of using QEMU's direct kernel boot, add the following
69 to `mkosi.local.conf`:
76 Putting this all together, here's a series of commands for preparing a patch
80 $ git clone https://github.com/systemd/mkosi.git # If mkosi v19 or newer is not packaged by your distribution
81 $ ln -s $PWD/mkosi/bin/mkosi /usr/local/bin/mkosi # If mkosi v19 or newer is not packaged by your distribution
82 $ git clone https://github.com/systemd/systemd.git
84 $ git checkout -b <BRANCH> # where BRANCH is the name of the branch
85 $ vim src/core/main.c # or wherever you'd like to make your changes
86 $ mkosi -f qemu # (re-)build and boot up the test image in qemu
87 $ git add -p # interactively put together your patch
88 $ git commit # commit it
89 $ git push -u <REMOTE> # where REMOTE is your "fork" on GitHub
92 And after that, head over to your repo on GitHub and click "Compare & pull request"
94 If you want to do a local build without mkosi, most distributions also provide
95 very simple and convenient ways to install most development packages necessary
100 $ sudo dnf builddep systemd
102 $ sudo apt-get build-dep systemd
104 $ sudo pacman -S devtools
105 $ pkgctl repo clone --protocol=https systemd
110 After installing the development packages, systemd can be built from source as follows:
113 $ meson setup build <options>
115 $ meson test -C build
120 ## Templating engines in .in files
122 Some source files are generated during build. We use two templating engines:
123 * meson's `configure_file()` directive uses syntax with `@VARIABLE@`.
126 [Meson docs for `configure_file()`](https://mesonbuild.com/Reference-manual.html#configure_file)
130 * most files are rendered using jinja2, with `{{VARIABLE}}` and `{% if … %}`,
131 `{% elif … %}`, `{% else … %}`, `{% endif … %}` blocks. `{# … #}` is a
132 jinja2 comment, i.e. that block will not be visible in the rendered
133 output. `{% raw %} … `{% endraw %}`{{ '{' }}{{ '% endraw %' }}}` creates a block
134 where jinja2 syntax is not interpreted.
137 [Jinja Template Designer Documentation](https://jinja2docs.readthedocs.io/en/stable/templates.html#synopsis)
140 Please note that files for both template engines use the `.in` extension.
142 ## Developer and release modes
144 In the default meson configuration (`-Dmode=developer`), certain checks are
145 enabled that are suitable when hacking on systemd (such as internal
146 documentation consistency checks). Those are not useful when compiling for
147 distribution and can be disabled by setting `-Dmode=release`.
149 ## Sanitizers in mkosi
151 See [Testing systemd using sanitizers](TESTING_WITH_SANITIZERS.md) for more information
152 on how to build with sanitizers enabled in mkosi.
156 systemd includes fuzzers in `src/fuzz/` that use libFuzzer and are automatically
157 run by [OSS-Fuzz](https://github.com/google/oss-fuzz) with sanitizers.
158 To add a fuzz target, create a new `src/fuzz/fuzz-foo.c` file with a `LLVMFuzzerTestOneInput`
159 function and add it to the list in `src/fuzz/meson.build`.
161 Whenever possible, a seed corpus and a dictionary should also be added with new
162 fuzz targets. The dictionary should be named `src/fuzz/fuzz-foo.dict` and the seed
163 corpus should be built and exported as `$OUT/fuzz-foo_seed_corpus.zip` in
166 The fuzzers can be built locally if you have libFuzzer installed by running
167 `tools/oss-fuzz.sh`, or by running:
170 CC=clang CXX=clang++ \
171 meson setup build-libfuzz -Dllvm-fuzz=true -Db_sanitize=address,undefined -Db_lundef=false \
172 -Dc_args='-fno-omit-frame-pointer -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION'
173 ninja -C build-libfuzz fuzzers
176 Each fuzzer then can be then run manually together with a directory containing
180 export UBSAN_OPTIONS=print_stacktrace=1:print_summary=1:halt_on_error=1
181 build-libfuzz/fuzz-varlink-idl test/fuzz/fuzz-varlink-idl/
184 Note: the `halt_on_error=1` UBSan option is especially important, otherwise
185 the fuzzer won't crash when undefined behavior is triggered.
187 You should also confirm that the fuzzers can be built and run using
188 [the OSS-Fuzz toolchain](https://google.github.io/oss-fuzz/advanced-topics/reproducing/#building-using-docker):
193 git clone --depth=1 https://github.com/google/oss-fuzz
196 for sanitizer in address undefined memory; do
197 for engine in libfuzzer afl honggfuzz; do
198 ./infra/helper.py build_fuzzers --sanitizer "$sanitizer" --engine "$engine" \
199 --clean systemd "$path_to_systemd"
201 ./infra/helper.py check_build --sanitizer "$sanitizer" --engine "$engine" \
202 -e ALLOWED_BROKEN_TARGETS_PERCENTAGE=0 systemd
206 ./infra/helper.py build_fuzzers --clean --architecture i386 systemd "$path_to_systemd"
207 ./infra/helper.py check_build --architecture i386 -e ALLOWED_BROKEN_TARGETS_PERCENTAGE=0 systemd
209 ./infra/helper.py build_fuzzers --clean --sanitizer coverage systemd "$path_to_systemd"
210 ./infra/helper.py coverage --no-corpus-download systemd
213 If you find a bug that impacts the security of systemd, please follow the
214 guidance in [CONTRIBUTING.md](CONTRIBUTING.md) on how to report a security vulnerability.
216 For more details on building fuzzers and integrating with OSS-Fuzz, visit:
218 - [Setting up a new project - OSS-Fuzz](https://google.github.io/oss-fuzz/getting-started/new-project-guide/)
219 - [Tutorials - OSS-Fuzz](https://google.github.io/oss-fuzz/reference/useful-links/#tutorials)
221 ## Debugging binaries that need to run as root in vscode
223 When trying to debug binaries that need to run as root, we need to do some custom configuration in vscode to
224 have it try to run the applications as root and to ask the user for the root password when trying to start
225 the binary. To achieve this, we'll use a custom debugger path which points to a script that starts `gdb` as
226 root using `pkexec`. pkexec will prompt the user for their root password via a graphical interface. This
227 guide assumes the C/C++ extension is used for debugging.
229 First, create a file `sgdb` in the root of the systemd repository with the following contents and make it
237 Then, open launch.json in vscode, and set `miDebuggerPath` to `${workspaceFolder}/sgdb` for the corresponding
238 debug configuration. Now, whenever you try to debug the application, vscode will try to start gdb as root via
239 pkexec which will prompt you for your password via a graphical interface. After entering your password,
240 vscode should be able to start debugging the application.
242 For more information on how to set up a debug configuration for C binaries, please refer to the official
243 vscode documentation [here](https://code.visualstudio.com/docs/cpp/launch-json-reference)
245 ## Debugging systemd with mkosi + vscode
247 To simplify debugging systemd when testing changes using mkosi, we're going to show how to attach
248 [VSCode](https://code.visualstudio.com/)'s debugger to an instance of systemd running in a mkosi image using
251 To allow VSCode's debugger to attach to systemd running in a mkosi image, we have to make sure it can access
252 the virtual machine spawned by mkosi where systemd is running. mkosi makes this possible via a handy SSH
253 option that makes the generated image accessible via SSH when booted. Thus you must build the image with
254 `mkosi --ssh`. The easiest way to set the option is to create a file `mkosi.local.conf` in the root of the
255 repository and add the following contents:
263 Also make sure that the SSH agent is running on your system and that you've added your SSH key to it with
264 `ssh-add`. Also make sure that `virtiofsd` is installed.
266 After rebuilding the image and booting it with `mkosi qemu`, you should now be able to connect to it by
267 running `mkosi ssh` from the same directory in another terminal window.
269 Now we need to configure VSCode. First, make sure the C/C++ extension is installed. If you're already using
270 a different extension for code completion and other IDE features for C in VSCode, make sure to disable the
271 corresponding parts of the C/C++ extension in your VSCode user settings by adding the following entries:
274 "C_Cpp.formatting": "Disabled",
275 "C_Cpp.intelliSenseEngine": "Disabled",
276 "C_Cpp.enhancedColorization": "Disabled",
277 "C_Cpp.suggestSnippets": false,
280 With the extension set up, we can create the launch.json file in the .vscode/ directory to tell the VSCode
281 debugger how to attach to the systemd instance running in our mkosi container/VM. Create the file, and possibly
282 the directory, and add the following contents:
290 "program": "/usr/lib/systemd/systemd",
291 "processId": "${command:pickRemoteProcess}",
295 "pipeProgram": "mkosi",
298 "/path/to/systemd/repo/directory/on/host/system/",
301 "debuggerPath": "/usr/bin/gdb"
305 "/root/src/systemd": {
306 "editorPath": "${workspaceFolder}",
307 "useForBreakpoints": false
315 Now that the debugger knows how to connect to our process in the container/VM and we've set up the necessary
316 source mappings, go to the "Run and Debug" window and run the "systemd" debug configuration. If everything
317 goes well, the debugger should now be attached to the systemd instance running in the container/VM. You can
318 attach breakpoints from the editor and enjoy all the other features of VSCode's debugger.
320 To debug systemd components other than PID 1, set "program" to the full path of the component you want to
321 debug and set "processId" to "${command:pickProcess}". Now, when starting the debugger, VSCode will ask you
322 the PID of the process you want to debug. Run `systemctl show --property MainPID --value <component>` in the
323 container to figure out the PID and enter it when asked and VSCode will attach to that process instead.
325 ## Debugging systemd-boot
327 During boot, systemd-boot and the stub loader will output messages like
328 `systemd-boot@0x0A` and `systemd-stub@0x0B`, providing the base of the loaded
329 code. This location can then be used to attach to a QEMU session (provided it
330 was run with `-s`). See `debug-sd-boot.sh` script in the tools folder which
331 automates this processes.
333 If the debugger is too slow to attach to examine an early boot code passage,
334 the call to `DEFINE_EFI_MAIN_FUNCTION()` can be modified to enable waiting. As
335 soon as the debugger has control, we can then run `set variable wait = 0` or
336 `return` to continue. Once the debugger has attached, setting breakpoints will
339 To debug systemd-boot in an IDE such as VSCode we can use a launch configuration like this:
342 "name": "systemd-boot",
345 "program": "${workspaceFolder}/build/src/boot/efi/systemd-bootx64.efi",
346 "cwd": "${workspaceFolder}",
348 "miDebuggerServerAddress": ":1234",
350 { "text": "shell mkfifo /tmp/sdboot.{in,out}" },
351 { "text": "shell qemu-system-x86_64 [...] -s -serial pipe:/tmp/sdboot" },
352 { "text": "shell ${workspaceFolder}/tools/debug-sd-boot.sh ${workspaceFolder}/build/src/boot/efi/systemd-bootx64.efi /tmp/sdboot.out systemd-boot.gdb" },
353 { "text": "source /tmp/systemd-boot.gdb" },