2 title: Hacking on systemd
5 SPDX-License-Identifier: LGPL-2.1-or-later
10 We welcome all contributions to systemd.
11 If you notice a bug or a missing 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) when submitting patches.
15 Also have a look at our [Contribution Guidelines](/CONTRIBUTING).
17 When adding new functionality, tests should be added.
18 For shared functionality (in `src/basic/` and `src/shared/`) unit tests should be sufficient.
19 The general 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 `src/basic/path-util.c`.
21 If adding a new source file, consider adding a matching test executable.
22 For features at a higher level, tests in `src/test/` are very strongly recommended.
23 If that is not possible, integration tests in `test/` are encouraged.
26 $ git config submodule.recurse true
27 $ git config fetch.recurseSubmodules on-demand
28 $ git config push.recurseSubmodules no
29 $ cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
30 $ cp tools/git-post-rewrite-hook.sh .git/hooks/post-rewrite
33 Please always test your work before submitting a PR.
34 For many of the components of systemd testing is straightforward as you can simply compile systemd and run the relevant tool from the build directory.
36 For some components (most importantly, systemd/PID 1 itself) this is not possible, however.
37 In order to simplify testing for cases like this we provide a set of `mkosi` config files directly in the source tree.
38 [mkosi](https://mkosi.systemd.io/)
39 is a tool for building clean OS images from an upstream distribution in combination with a fresh build of the project in the local working directory.
40 To make use of this, please install `mkosi` v19 or newer using your distribution's package manager or from the
41 [GitHub repository](https://github.com/systemd/mkosi).
42 `mkosi` will build an image for the host distro by default.
43 First, run `mkosi genkey` to generate a key and certificate to be used for secure boot and verity signing.
44 After that is done, it is sufficient to type `mkosi` in the systemd project directory to generate a disk 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,
57 incorporating all current changes you made to the project tree.
59 By default a directory image is built.
60 This requires `virtiofsd` to be installed on the host.
61 To build a disk image instead which does not require `virtiofsd`, add the following to `mkosi.local.conf`:
68 To boot in UEFI mode instead of using QEMU's direct kernel boot, add the following to `mkosi.local.conf`:
75 To avoid having to build a new image all the time when iterating on a patch,
76 add the following to `mkosi.local.conf`:
80 RuntimeBuildSources=yes
83 After enabling this setting, the source and build directories will be mounted to
84 `/work/src` and `/work/build` respectively when booting the image as a container
85 or virtual machine. To build the latest changes and re-install, run
86 `meson install -C /work/build --only-changed` in the container or virtual machine
87 and optionally restart the daemon(s) you're working on using
88 `systemctl restart <units>` or `systemctl daemon-reexec` if you're working on pid1
89 or `systemctl soft-reboot` to restart everything.
91 Putting this all together, here's a series of commands for preparing a patch for systemd:
94 $ git clone https://github.com/systemd/mkosi.git # If mkosi v19 or newer is not packaged by your distribution
95 $ ln -s $PWD/mkosi/bin/mkosi /usr/local/bin/mkosi # If mkosi v19 or newer is not packaged by your distribution
96 $ git clone https://github.com/systemd/systemd.git
98 $ git checkout -b <BRANCH> # where BRANCH is the name of the branch
99 $ vim src/core/main.c # or wherever you'd like to make your changes
100 $ mkosi -f qemu # (re-)build and boot up the test image in qemu
101 $ git add -p # interactively put together your patch
102 $ git commit # commit it
103 $ git push -u <REMOTE> # where REMOTE is your "fork" on GitHub
106 And after that, head over to your repo on GitHub and click "Compare & pull request"
108 If you want to do a local build without mkosi,
109 most distributions also provide very simple and convenient ways to install most development packages necessary to build systemd:
113 $ sudo dnf builddep systemd
115 $ sudo apt-get build-dep systemd
117 $ sudo pacman -S devtools
118 $ pkgctl repo clone --protocol=https systemd
123 After installing the development packages, systemd can be built from source as follows:
126 $ meson setup build <options>
128 $ meson test -C build
133 ## Templating engines in .in files
135 Some source files are generated during build. We use two templating engines:
136 * meson's `configure_file()` directive uses syntax with `@VARIABLE@`.
138 See the [Meson docs for `configure_file()`](https://mesonbuild.com/Reference-manual.html#configure_file) for details.
141 * most files are rendered using jinja2, with `{{VARIABLE}}` and `{% if … %}`,
142 `{% elif … %}`, `{% else … %}`, `{% endif … %}` blocks. `{# … #}` is a jinja2 comment,
143 i.e. that block will not be visible in the rendered output.
144 `{% raw %} … `{% endraw %}`{{ '{' }}{{ '% endraw %' }}}` creates a block where jinja2 syntax is not interpreted.
146 See the [Jinja Template Designer Documentation](https://jinja.palletsprojects.com/en/3.1.x/templates/#synopsis) for details.
148 Please note that files for both template engines use the `.in` extension.
150 ## Developer and release modes
152 In the default meson configuration (`-Dmode=developer`),
153 certain checks are enabled that are suitable when hacking on systemd (such as internal documentation consistency checks).
154 Those are not useful when compiling for distribution and can be disabled by setting `-Dmode=release`.
156 ## Sanitizers in mkosi
158 See [Testing systemd using sanitizers](/TESTING_WITH_SANITIZERS) for more information on how to build with sanitizers enabled in mkosi.
162 systemd includes fuzzers in `src/fuzz/` that use libFuzzer and are automatically run by [OSS-Fuzz](https://github.com/google/oss-fuzz) with sanitizers.
163 To add a fuzz target, create a new `src/fuzz/fuzz-foo.c` file with a `LLVMFuzzerTestOneInput` function and add it to the list in `src/fuzz/meson.build`.
165 Whenever possible, a seed corpus and a dictionary should also be added with new fuzz targets.
166 The dictionary should be named `src/fuzz/fuzz-foo.dict` and the seed corpus should be built and exported as `$OUT/fuzz-foo_seed_corpus.zip` in `tools/oss-fuzz.sh`.
168 The fuzzers can be built locally if you have libFuzzer installed by running `tools/oss-fuzz.sh`, or by running:
171 CC=clang CXX=clang++ \
172 meson setup build-libfuzz -Dllvm-fuzz=true -Db_sanitize=address,undefined -Db_lundef=false \
173 -Dc_args='-fno-omit-frame-pointer -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION'
174 ninja -C build-libfuzz fuzzers
177 Each fuzzer then can be then run manually together with a directory containing the initial corpus:
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,
185 otherwise 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,
214 please follow the guidance in [CONTRIBUTING.md](/CONTRIBUTING) 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,
224 we need to do some custom configuration in vscode to have it try to run the applications as root and to ask the user for the root password when trying to start the binary.
225 To achieve this, we'll use a custom debugger path which points to a script that starts `gdb` as root using `pkexec`.
226 pkexec will prompt the user for their root password via a graphical interface.
227 This 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 executable:
236 Then, open launch.json in vscode, and set `miDebuggerPath` to `${workspaceFolder}/sgdb` for the corresponding debug configuration.
237 Now, whenever you try to debug the application, vscode will try to start gdb as root via pkexec which will prompt you for your password via a graphical interface.
238 After entering your password, vscode should be able to start debugging the application.
240 For more information on how to set up a debug configuration for C binaries,
241 please refer to the official vscode documentation [here](https://code.visualstudio.com/docs/cpp/launch-json-reference)
243 ## Debugging systemd with mkosi + vscode
245 To simplify debugging systemd when testing changes using mkosi, we're going to show how to attach [VSCode](https://code.visualstudio.com/)'s debugger to an instance of systemd running in a mkosi image using QEMU.
247 To allow VSCode's debugger to attach to systemd running in a mkosi image,
248 we have to make sure it can access the virtual machine spawned by mkosi where systemd is running.
249 After booting the image with `mkosi qemu`,
250 you should now be able to connect to it by running `mkosi ssh` from the same directory in another terminal window.
252 Now we need to configure VSCode.
253 First, make sure the C/C++ extension is installed.
254 If you're already using a different extension for code completion and other IDE features for C in VSCode,
255 make sure to disable the corresponding parts of the C/C++ extension in your VSCode user settings by adding the following entries:
258 "C_Cpp.formatting": "Disabled",
259 "C_Cpp.intelliSenseEngine": "Disabled",
260 "C_Cpp.enhancedColorization": "Disabled",
261 "C_Cpp.suggestSnippets": false,
264 With the extension set up,
265 we can create the launch.json file in the .vscode/ directory to tell the VSCode debugger how to attach to the systemd instance running in our mkosi container/VM.
266 Create the file, and possibly the directory, and add the following contents:
274 "program": "/usr/lib/systemd/systemd",
275 "processId": "${command:pickRemoteProcess}",
279 "pipeProgram": "mkosi",
280 "pipeArgs": ["-C", "${workspaceFolder}", "ssh"],
281 "debuggerPath": "/usr/bin/gdb"
286 "editorPath": "${workspaceFolder}",
287 "useForBreakpoints": false
295 Now that the debugger knows how to connect to our process in the container/VM and we've set up the necessary source mappings,
296 go to the "Run and Debug" window and run the "systemd" debug configuration.
297 If everything goes well, the debugger should now be attached to the systemd instance running in the container/VM.
298 You can attach breakpoints from the editor and enjoy all the other features of VSCode's debugger.
300 To debug systemd components other than PID 1,
301 set "program" to the full path of the component you want to debug and set "processId" to "${command:pickProcess}".
302 Now, when starting the debugger, VSCode will ask you the PID of the process you want to debug.
303 Run `systemctl show --property MainPID --value <component>`
304 in the container to figure out the PID and enter it when asked and VSCode will attach to that process instead.
306 ## Debugging systemd-boot
308 During boot, systemd-boot and the stub loader will output messages like `systemd-boot@0x0A` and `systemd-stub@0x0B`,
309 providing the base of the loaded code.
310 This location can then be used to attach to a QEMU session (provided it was run with `-s`).
311 See `debug-sd-boot.sh` script in the tools folder which automates this processes.
313 If the debugger is too slow to attach to examine an early boot code passage,
314 the call to `DEFINE_EFI_MAIN_FUNCTION()` can be modified to enable waiting.
315 As soon as the debugger has control, we can then run `set variable wait = 0` or `return` to continue.
316 Once the debugger has attached, setting breakpoints will work like usual.
318 To debug systemd-boot in an IDE such as VSCode we can use a launch configuration like this:
321 "name": "systemd-boot",
324 "program": "${workspaceFolder}/build/src/boot/efi/systemd-bootx64.efi",
325 "cwd": "${workspaceFolder}",
327 "miDebuggerServerAddress": ":1234",
329 { "text": "shell mkfifo /tmp/sdboot.{in,out}" },
330 { "text": "shell qemu-system-x86_64 [...] -s -serial pipe:/tmp/sdboot" },
331 { "text": "shell ${workspaceFolder}/tools/debug-sd-boot.sh ${workspaceFolder}/build/src/boot/efi/systemd-bootx64.efi /tmp/sdboot.out systemd-boot.gdb" },
332 { "text": "source /tmp/systemd-boot.gdb" },