Understanding how to use dracut is critical for kernel upgrades, troubleshooting boot issues, disk migration, encryption, and even kernel debugging.

Introduction: What is dracut?

dracut is a powerful tool used in Fedora, RHEL, and other distributions to create and manage initramfs images—the initial RAM filesystem used during system boot. Unlike older tools like mkinitrd, dracut uses a modular approach, allowing you to build minimal or specialized initramfs tailored to your system.

Installing dracut (if not already available)

dracut comes pre-installed in Fedora and RHEL. If it is missing, install it with:

$ sudo dnf install dracut

Verify the version:

$ dracut --version

Basic usage

Regenerate the current initramfs

$ sudo dracut --force

This regenerates the initramfs for the currently running kernel.

Generate initramfs for a specific kernel

$ sudo dracut --force /boot/initramfs-$(uname -r).img $(uname -r)

Or Manually!

$ sudo dracut --force
$ sudo dracut --force /boot/initramfs-5.14.0-327.el9.x86_64.img 5.14.0-327.el9.x86_64

Understanding key dracut options (with examples)

–force

Force regeneration even if the file already exists:

$ sudo dracut --force

–kver <kernel-version>

Generate initramfs for a specific kernel:

$ sudo dracut --force --kver 5.14.0-327.el9.x86_64

–add <module> / –omit <module>

Include or exclude specific modules (e.g., lvm, crypt, network).

Include LVM module only:

$ sudo dracut --force --add lvm

Omit network module:

$ sudo dracut --force --omit network

–no-hostonly

Build a generic initramfs that boots on any compatible machine:

$ sudo dracut --force --no-hostonly

–hostonly

Create a host-specific image for minimal size:

$ sudo dracut --force --hostonly

–print-cmdline

Show the kernel command line:

$ dracut --print-cmdline

–list-modules

List all available dracut modules:

$ dracut --list-modules

–add-drivers “driver1 driver2”

Include specific drivers:

$ sudo dracut --add-drivers "nvme ahci" --force

Test cases and real-world scenarios

1. LVM root disk fails to boot after migration

$ sudo dracut --force --add lvm --hostonly

2. Initramfs too large

Shrink it by omitting unused modules:

$ sudo dracut --force --omit network --omit plymouth

3. Generic initramfs for provisioning

$ sudo dracut --force --no-hostonly --add network --add nfs

4. Rebuild initramfs for rollback kernel

$ sudo dracut --force /boot/initramfs-5.14.0-362.el9.x86_64.img 5.14.0-362.el9.x86_64

Advanced use: Debugging and analysis

Enable verbose output:

$ sudo dracut -v --force

Enter the dracut shell if boot fails:

Use rd.break in the GRUB kernel line.

Where is dracut configuration stored?

There are two locations where configuration setting may occur.

The global settings location is at:

/etc/dracut.conf

and the drop-in location is at:

/etc/dracut.conf.d/*.conf

Example using the drop-in location:

$ cat /etc/dracut.conf.d/custom.conf

The contents might appear as follows for omitting and adding modules:

omit_dracutmodules+=" plymouth network "
add_dracutmodules+=" crypt lvm "

Note: Always include a space at the beginning and end of the value when using += in these configuration files. These files are sourced as Bash scripts, so

add_dracutmodules+=" crypt lvm "

ensures proper spacing when multiple config files are concatenated. Without the spaces, the resulting string could concatenate improperly (e.g., mod2mod3) and cause module loading failures.

Deep dive: /usr/lib/dracut/modules.d/ – the heart of dracut

The directory /usr/lib/dracut/modules.d includes all module definitions. Each contains:

• A module-setup.sh script
• Supporting scripts and binaries
• Udev rules, hooks, and configs

List the modules using the following command:

$ ls /usr/lib/dracut/modules.d/

Example output:

01fips/ 30crypt/ 45ifcfg/ 90lvm/ 95resume/
02systemd/ 40network/ 50drm/ 91crypt-gpg/ 98selinux/

Inspect specific module content (module-setup.sh, in this example) using this:

$ cat /usr/lib/dracut/modules.d/90lvm/module-setup.sh

You can also create custom modules at this location for specialized logic.

Final thoughts

dracut is more than a utility—it’s your boot-time engineer. From creating lightweight images to resolving boot failures, it offers unparalleled flexibility.

Explore man dracut, read through /usr/lib/dracut/modules.d/, and start customizing.

This article is dedicated to my wife, Rupali Suraj Patil, for her continuous support and encouragement.

Performance Co-Pilot (PCP) is a robust framework for collecting, monitoring, and analyzing system performance metrics. Available in the repos for Fedora and RHEL, it allows administrators to gather a wide array of data with minimal configuration. This guide walks you through tuning PCP’s pmlogger service to better fit your needs—whether you’re debugging performance issues or running on constrained hardware.

Is the default setup of PCP right for your use case? Often, it’s not. While PCP’s defaults strike a balance between data granularity and overhead, production workloads vary widely. Later in this article, two scenarios will be used to demonstrate some useful configurations.

Prerequisites: Getting PCP up and running

First, install the PCP packages:

$ sudo dnf install pcp pcp-system-tools

Then enable and start the core services:

$ sudo systemctl enable --now pmcd.service
$ sudo systemctl enable --now pmlogger.service

Verify both services are running:

$ systemctl status pmcd pmlogger

Understanding pmlogger and its configuration

PCP consists of two main components:

• pmcd: collects live performance metrics from various agents.
• pmlogger: archives these metrics over time for analysis.

The behavior of pmlogger is controlled by files in /etc/pcp/pmlogger/control.d/. The most relevant is local, which contains command-line options for how logging should behave.

Sample configuration:

$ cat /etc/pcp/pmlogger/control.d/local

You’ll see a line like:

localhost y y /usr/bin/pmlogger -h localhost ... -t 10s -m note

The -t 10s flag defines the logging interval—every 10 seconds in this case.

Scenario 1: High-frequency monitoring for deep analysis

Use case: Debugging a transient issue on a production server.
Goal: Change the logging interval from 10 seconds to 1 second.

Edit the file (nano editor used in the examples, please use your editor of choice):

$ sudo nano /etc/pcp/pmlogger/control.d/local

Change -t 10s to -t 1s.

Restart the logger:

$ sudo systemctl restart pmlogger.service

Verify:

$ ps aux | grep '[p]mlogger -h localhost'
$ pminfo -f

Expected output snippet:

records: 10, interval: 0:00:01.000

Scenario 2: Lightweight monitoring for constrained systems

Use case: Monitoring on a small VM or IoT device.
Goal: Change the logging interval to once every 60 seconds.

Edit the same file:

$ sudo nano /etc/pcp/pmlogger/control.d/local

Change -t 10s to -t 60s.

Restart the logger:

$ sudo systemctl restart pmlogger.service

Confirm:

$ ps aux | grep '[p]mlogger -h localhost'
$ pminfo -f

Expected output:

records: 3, interval: 0:01:00.000

Managing data retention: logs, size, and cleanup

PCP archives are rotated daily by a cron-like service. Configuration lives in:

$ cat /etc/sysconfig/pmlogger

Default values:

PCP_MAX_LOG_SIZE=100
PCP_MAX_LOG_VERSIONS=14

• PCP_MAX_LOG_SIZE: total archive size (in MB).
• PCP_MAX_LOG_VERSIONS: number of daily logs to keep.

Goal: Keep logs for 30 days.

Edit the file:

$ sudo nano /etc/sysconfig/pmlogger

Change:

PCP_MAX_LOG_VERSIONS=30

No service restart is required. Changes apply during the next cleanup cycle.

Final thoughts

PCP is a flexible powerhouse. With just a few changes, you can transform it from a general-purpose monitor into a specialized tool tailored to your workload. Whether you need precision diagnostics or long-term resource tracking, tuning pmlogger gives you control and confidence.

So go ahead—open that config file and start customizing your system’s performance story.

Note: This article is dedicated to my wife, Rupali Suraj Patil, who inspires me every day.

This article will describe the content and structure of the sosreport output. The aim is to improve its usefullness through a better understanding of its contents.

What is sosreport?

sosreport is a powerful command-line utility available on Fedora, Red Hat Enterprise Linux (RHEL), CentOS, and other RHEL-based systems to collect a comprehensive snapshot of the system’s configuration, logs, services, and state. The primary use is for diagnosing issues, especially during support cases with Red Hat or other vendors.

When executed, sosreport runs a series of modular plugins that collect relevant data from various subsystems like networking, storage, SELinux, Docker, and more. The resulting report is packaged into a compressed tarball, which can be securely shared with support teams to expedite troubleshooting.

In essence, sosreport acts as a black box recorder for Linux — capturing everything from system logs and kernel messages to active configurations and command outputs — helping support engineers trace problems without needing direct access to the system.

How to Generate a sosreport

To use sosreport on Fedora, RHEL, or CentOS, run the following command as root or with sudo:

sudo sosreport

This command collects system configuration, logs, and command outputs using various plugins. After a few minutes, it generates a compressed tarball in /var/tmp/ (or a similar location), typically named like:

sosreport-hostname-20250623-123456.tar.xz

You may be prompted to enter a case ID or other metadata, depending on your system configuration or support workflow.

The sosreport generated tarball contains a detailed snapshot of the system’s health and configuration. It has a well-organized structure which reflects the data collected from the myriad Linux subsystems.

Exploring sosreport output is challenging due to the sheer volume of logs, configuration files, and system command outputs it contains. However, understanding its layout is key for support engineers and sysadmins to quickly locate and interpret crucial diagnostic information.

sosreport directory layout

When the tarball is unpacked, the directory structure typically resembles this:

.
├── ./boot
├── ./etc
├── ./lib -> usr/lib
├── ./opt
├── ./proc
├── ./run
├── ./sos_commands
├── ./sos_logs
├── ./sos_reports
├── ./sos_strings
├── ./sys
├── ./usr
├── ./var
└── ./EXTRAS

CORE Breakdown:

• Most directories mimic a standard Linux root filesystem and primarily contain configuration files.
• The directories that don’t appear in a regular root filesystem include:
  • sos_command
  • sos_logs
  • sos_reports
  • sos_strings
  • EXTRAS

Key directories in detail

sos_commands/

This contains output from commands executed by each plugin. Its structure is plugin-specific:

./sos_commands/
├── apparmor/
├── docker/
├── memory/
├── networkmanager/
├── process/
│ ├── lsof_M_-n_-l_-c
│ ├── pidstat_-p_ALL_-rudvwsRU_--human_-h
│ ├── ps_auxwwwm
│ └── pstree_-lp

Each file name matches the Linux command used, with all options. The contents are the actual command output, making the plugin behavior transparent.

sos_reports/

This directory contains multiple formats that index and summarize the entire sosreport:

• sos.json: A machine-readable index of all collected files and commands.
• manifest.json: Describes how sosreport executed – timestamps, plugins used, obfuscation done, errors, etc.
• HTML output for easy browsing via browser.

sos_logs/

Contains logs from the execution of sosreport itself.

• sos.log: Primary log file that highlights any errors or issues during data collection.

sos_strings/

• Contains journal logs for up to 30 days, extracted using journalctl
• Can be quite large, especially on heavily used systems
• Structured into subdirectories like logs/ or networkmanager/

EXTRAS/

This is not a default part of an sosreport. It is created by the sos_extras plugin and used to collect any custom user-defined files.

Why this layout matters

• Speed: Logical grouping of directories help engineers drill down without manually parsing GigaBytes of log files.
• Traceability: Knowing where each file came from and what command produced it enhances reproducibility.
• Automation: Tools like soscleaner or sos-analyzer rely on this structure for automated diagnostics.

Final thoughts

While sosreport is a powerful diagnostic tool, its effectiveness hinges on understanding its structure. With familiarity, engineers can isolate root causes of failures, uncover misconfigurations, and collaborate more efficiently with support teams. If you haven’t yet opened one up manually, try it — there’s a lot to learn from the insides!

This is my first Fedora Magazine article, dedicated to my wife Rupali Suraj Patil — my constant source of inspiration.

In this fifth article of the “System insights with command-line tools” series we explore free and vmstat, two small utilities that reveal a surprising amount about your Linux system’s health. free gives you an instant snapshot of how RAM and swap are being used. vmstat (the virtual memory statistics reporter) reports a real-time view of memory, CPU, and I/O activity.

By the end of this article you will be able to translate buffers and cache into “breathing room”, read the mysterious available column with confidence, and spot memory leaks or I/O saturation.

A quick tour of free

Basic usage

$ free -h
       total    used    free   shared  buff/cache  available
Mem:    23Gi    14Gi   575Mi    3,3Gi        12Gi      8,8Gi
Swap:  8,0Gi   6,6Gi   1,4Gi

free parses /proc/meminfo and prints totals for physical memory and swap, along with kernel buffers and cache. Use -h for human-readable units, -s 1 to refresh every second, and -c N to stop after N samples which is handy to get a trend when doing something in parallel. For example, free -s 60 -c 1440 gives a 24-hour CSV-friendly record without installing extra monitoring daemons.

Free memory refers to RAM that is entirely unoccupied. It isn’t being used by any process or for caching. On server systems, I tend to view this as wasted since unused memory isn’t contributing to performance. Ideally, after a system has been running for some time, this number should remain low.

Available memory, on the other hand, represents an estimate of how much memory can be used by new or running processes without resorting to swap. It includes free memory plus parts of the cache and buffers that the system can reclaim quickly if needed.

In essence, the distinction in Linux lies here: free memory is idle and unused, while available memory includes both truly free space and memory that can be readily freed up to keep the system responsive without swapping. It is not a problem to have a low free memory, available memory is usually what to be concerned about.

A healthy system might even show used ≈ total yet available remains large; that mostly reflects cache at work. Fedora’s kernel will automatically drop clean cache pages whenever an application needs the space, so cached memory is not wasted. Think of it as a working set that just hasn’t been reassigned yet.

Spotting problems with free

• Rapidly shrinking available combined with rising swap used indicates real memory pressure.
• Large swap-in/out spikes point to thrashing workloads or runaway memory consumers.

vmstat – Report virtual memory statistics

vmstat (virtual memory statistics) displays processes, memory, paging, block-I/O, interrupts, context switches, and CPU utilization in a single line. Run it with an interval and count to watch trends (output shown below has been split into three sections for better readability):

$ vmstat 1 3
procs -----------memory----------     
 r  b   swpd   free   buff  cache     
 2  0 7102404 1392528     36 12335148 
 0  0 7102404 1392560     36 12335188 
 0  0 7102404 1373640     36 12349928 

 ---swap-- -----io---- 
  si   so    bi    bo  
   8   21   130   724  
   0    0     0     0  
   0    0     8    48  

 -system-- -------cpu-------
 in     cs us sy id wa st gu
 2851   19 15  7 77  0  0  0
 5779 7246 14 10 77  0  0  0
 5141 6525 12  9 79  0  0  0

Anatomy of the output

From the vmstat(8) manpage:

Procs
    r: The number of runnable processes (running or waiting
       for run time).
    b: The number of processes blocked waiting for I/O to
       complete.

Memory
    These are affected by the --unit option.
    swpd: the amount of swap memory used.
    free: the amount of idle memory.
    buff: the amount of memory used as buffers.
    cache: the amount of memory used as cache.
    inact: the amount of inactive memory.  (-a option)
    active: the amount of active memory.  (-a option)

Swap
    These are affected by the --unit option.
    si: Amount of memory swapped in from disk (/s).
    so: Amount of memory swapped to disk (/s).

IO
    bi: Kibibyte received from a block device (KiB/s).
    bo: Kibibyte sent to a block device (KiB/s).

System
    in: The number of interrupts per second, including
        the clock.
    cs: The number of context switches per second.

CPU
    These are percentages of total CPU time.
    us: Time spent running non-kernel code.  (user time,
        including nice time)
    sy: Time spent running kernel code.  (system time)
    id: Time spent idle.  Prior to Linux 2.5.41, this
        includes IO-wait time.
    wa: Time spent waiting for IO.  Prior to Linux 2.5.41,
        included in idle.
    st: Time stolen from a virtual machine.  Prior to
        Linux 2.6.11, unknown.
    gu: Time spent running KVM guest code (guest time,
        including guest nice).

Practical diagnostics

Section	Key Fields	What to watch
Procs	r (run-queue), b (blocked)	r > CPU cores = contention
Memory	swpd, free, buff, cache	Rising swpd with falling free = pressure
Swap	si, so	Non-zero so means the kernel is swapping out
IO	bi, bo	High bo + high wa hints at write-heavy workloads
System	in, cs	Sudden spikes may indicate interrupt storms
CPU	us, sy, id, wa, st	High wa (I/O wait) = storage bottleneck

Catching a memory leak

Run vmstat 500 in one terminal while your suspect application runs in another. If free keeps falling and si/so climb over successive samples, physical RAM is being exhausted and the kernel starts swapping, which is classic leak behavior.

Finding I/O saturation

When wa (CPU wait) and bo (blocks out) soar while r remains modest, the CPU is idle but stuck waiting for the disk. Consider adding faster storage or tuning I/O scheduler parameters.

Detecting CPU over-commit

A sustained r that is double the number of logical cores with low wa and plenty of free means CPU is the bottleneck, not memory or I/O. Use top or htop to locate the busiest processes, or scale out workloads accordingly.

Conclusion

Mastering free and vmstat gives you a lens into memory usage, swap activity, I/O latency, and CPU load. For everyday debugging: start with free to check if your system is truly out of memory, then use vmstat to reveal the reason, whether it’s memory leaks, disk bottlenecks, or CPU saturation.

Stay tuned for the next piece in our “System insights with command-line tools” series and happy Fedora troubleshooting!

This is my recap of Flock to Fedora 2025, streamed live from Kenya! I would really like to thank the amazing team – speakers, volunteers as well, who made FLOCK possible this year! 

This recap is from a virtual attendee’s viewpoint, tuning in live from Kenya for June 5–6. Massive appreciation to everyone behind the scenes!

Day 1: Big Announcements, Bold Ideas

“10 years in the making,” as Justin W. put it – this year’s Flock kicked off with energy. The central track brought everyone together for keynotes and deep conversations on Fedora’s future.

The day opened with reflections from Matthew Miller former Fedora Project Leader (FPL), who spoke candidly about the passion and challenges of the role – even nearly missing his daughter’s graduation! He handed the baton to the new FPL, Jef Spaleta, who stepped on stage with a vision.

Jef Spaleta laid out Fedora’s Strategy 2028 with a focus on mentorship, contributor growth, and aligning community efforts. He emphasized the need to support people better, build transparent processes, and push forward with long-term thinking.

You can check the video: Flock 2025 The FPL Exchange.

Panel: What comes next?

A lot was said, I can’t really recount it all. 

The “Big Elephant” – AI – was among the topics in the room, plus others. 

One community member asked: “What’s the plan for those greying folks who’ve contributed for years – how do we keep them engaged?” That led to an eye-opening chat about FESCo nominations. Turns out, you don’t have to be a genius to participate. You just have to show up, say something, even if it’s “I didn’t have time to review.” It’s about honesty and growth. Not perfection. (Whew!)

And yes – apparently, it was the same Friends (Friends of Fedora) who got elected every time, or maybe people don’t really know how that works? Now, should we expect a guide on that? Many would need it I guess. Let’s push them for it. Bookmark that.

PS: You can watch all this goodness on YouTube. Trust me, it’s worth it.

Sponsor time… And a Milo break

During the break, while the stream showed sponsor slides (thank you, sponsors – you keep the lights on!), I took a real break. Picture this:

Fresh hot milk (fresh of course, never told you I used to milk cows when I was a kid) + Milo + a tiny bit of sugar = Happiness.  (sugar in Milo!  That’s crazy!!  Milo is mostly sugar (MatH)

So, take a breather …. Oh I mean take a break `cause we’re not yet halfway through our article.

Welcome back from your break! I know you didn’t really take a break; I was just humoring you.

Yes, my Flock snack game was elite.

Back to Tech: Forgejo & Fedora Gaming?!

Otto Richter from Codeberg walked us through why Fedora moved to Forgejo for hosting – and what Codeberg is all about (all the goodies it has). He even gave a quick demo, plus a bonus pronunciation lesson. You can find the slides to the talk here on Pretalx.

Then came a surprise: Fedora’s Downstream Gaming Variant! 

Noel Miller and Antheas from the Bazzite team introduced their work on making a variant of Fedora that is more gaming-friendly. I hadn’t even heard of Bazzite before this. Maybe I should try it? Yes, sometime. If you play games and love Fedora, these folks want you – whether you’re a dev, tester, or gamer who just clicks buttons and wins.

After lunch: SIGs, Mentorship, and Inspiration

After lunch sessions split across rooms. I tried to be in two rooms at once (classic virtual problem ). I joined the Topaz Room for the Fedora Join SIG session. 

I’m actually a member of the Join SIG, so it felt like home. Our job? Help newcomers feel welcome, direct them to the right teams, and support their journey into Fedora. It’s possibly the easiest SIG to “join”—”if you hang around, you’re one of us.” That was simple, true and beautiful. Thanks to Ankur and AkashDeep Dhar, and yet another Friend who helped with the slides that didn’t make it – Mat H (theprogram). 

But we need your help, we need you to help us help newcomers navigate the community and find their place in. There’re probably a few helping out!

Fedora Docs: Where words matter

Somewhere between hopping between Topaz and Opal rooms, I landed in one of my favorite sessions – Fedora Documentation. 

Stay there: 

Here’s a spoiler alert: I’m hosting a Fedora Docs Hands-On Virtual Workshop this June 21, 2025!

Yep, mark your calendars! You can accept the invite here, also say hi in the discourse channel and let this be engaging (would love to hear from you, really).

We often forget that docs aren’t “extra.” They are the user’s first experience, the contributor’s first clue, and often the only map through the maze. And Fedora takes this seriously.

Later, in the Opal Room, I caught talks on mentorship programs like GSoC and Outreachy, led by Sumantro M. and Fernando. 

And yes – drumroll please – this was especially meaningful for me – I’m currently an Outreachy Intern (June–August 2025)! 

One standout talk: “Open Source Mentorship: Crafting Community Leaders” by Nikita Tripathi (an Outreachy alum still contributing to Fedora) and Samyak Jain. The session explored what mentorship is and isn’t – not just teaching, but growing together. As Samyak Jain shared: “Communities thrive on engagement. Your voice matters.”

Wrapping up Day 2: Scaling, Designing, and… T-shirts?

Quick Hits (a.k.a. Can’t-Miss Moments)

Before logging off, I caught “Scaling Fedora Ready through Community Contributions” by Roseline Bassey, presented by Justin W. The talk highlighted how Fedora Ready can grow through community testers, reviewers, and ambassadors, helping users find hardware that works well with Fedora.

Quick talks followed:
“The Role of Designers in Open Source” by Smera, reminding us that design matters just as much as code. Let them be there at the beginning of the research project
“How Do You Open Source a T-shirt?” by Troy Dawson. This was a cool one, cool shirts. And yes, I’m still thinking about it.

Both were refreshing takes on open source beyond code.

If you’re curious about the “hidden rooms” I missed or the full Day 2 content, check out the recordings on YouTube and the checklist on Pretalx. There’s only so much a human can digest in 48 hours – even with Milo

Before we Recap… Have you filled the Fedora contributor & user survey?

If you haven’t already, please take a moment to fill out the Fedora Contributor and User Survey. Your feedback helps shape the future of the Fedora Project.

Okay, let’s close now.

Final thoughts

Flock (2025 edition!) reminded me that Fedora is more than software. It’s people, mentorship, storytelling, experimentation, and community care. I’m glad I could stream the experience and share it – I’m hoping to join the next FLOCK. 

As a remote attendee, I felt seen, included, and inspired. (Inclusion)

Looking forward to more conversations and continued impact.

Your Friend in Open Source, Cornelius – Open Source Freedom Fighter

Among the many details developers juggle, software licensing is often treated as an afterthought. We know we need it. However, faced with choosing the right license, tracking inherited code, and keeping things consistent, license management can feel like a bureaucratic burden.

Licensing is what makes the REUSE project, maintained by the Free Software Foundation Europe (FSFE), such an interesting and important effort. It does not try to replace the legal work involved in choosing a license or deciphering obligations. Instead, REUSE focuses on the mechanics of software licensing. It addresses how we communicate licensing clearly, unambiguously, and reliably in the code itself. REUSE has been adopted by a lot of projects already. These include SAP, Nextcloud and numerous Ansible community roles and collections.

I recently went down the licensing and supply chain rabbit hole myself. I had to figure out how to apply it to open source projects I work on and explain it to others. Thus, I had the unique experience of learning it from scratch while also teaching it. That process gave me insight into what makes REUSE helpful. I learned where the roadblocks are, and how you can start using it in your own open source work. So this article aims to give additional reasoning and insights for every day usage beyond the scope of a quick start tutorial.

Why licensing still feels broken

If you’ve ever tried to make sense of licensing in a codebase with contributions from half a dozen sources, or tried to package software only to find ambiguous or conflicting license declarations, you’ve seen the brokenness first hand. It’s a common pain point.

You start coding. A LICENSE file goes in the root. Maybe it’s MIT, maybe Apache 2.0, maybe GPLv3-or-later. We figure that’s enough. For the most part, tools like Licensee (which Github uses) will scan that file and report the project as single-licensed under whatever it finds.

But that is only part of the picture.

Real-world projects grow messy over time. Files come in from various places. Pull requests, upstream forks, old backups. Someone pastes in a script from Stack Overflow. Someone else uploads a code generator output. Over time, the repository becomes a tangle of files with unclear origins. The top-level LICENSE file can’t speak for all of it any more. But the tools like licensee don’t know that, and often neither do the maintainers.

If you provide code without clear licensing information, you make it hard for the open source ecosystem to collaborate with or consume your work. Unfortunately, approaches to automatic license detection can’t deliver the needed certainty. They rely on fuzzy matching, heuristics, and assumptions (like there is “one license for the project”). This just does not cut it when legal clarity is required. Automatic license heuristics are complicated and will never deliver reliable results for all the possible use cases.

FSFE REUSE to the rescue

Rather than trying to detect or infer licensing, REUSE asks developers to be explicit in a machine-readable, auditable way:

1. There has to be a text copy of every used license below a LICENSES/ directory¹ in the root of the project.
2. Each file in your project must have machine-readable copyright and licensing information associated with it.

Again: This matters. It means anyone—an auditor, a packager, a contributor, or a compliance team—can look at any file in your repository and immediately understand its legal status. There is no guessing, no cross-referencing, no “well maybe this falls under the MIT license because the rest of the project does.” It’s explicit. It’s standardized. And it is quickly lintable which is great for teams with Continuous Integration.

Following REUSE, adding machine-readable copyright and licensing information can be done in the following ways:

• Comment headers or <filename>.license for uncommentable files.
• REUSE.toml, a machine-readable copyright file to address file and directory names. This is especially handy to define:
  • a default license for your project.
  • deviant licenses for third party artefacts residing in a sub-directory.

REUSE backs up its specification with a simple, focused, reuse command-line tool. This makes adoption relatively painless (even though all can also be done manually). REUSE fits nicely into the ecosystem, especially by relying on Software Package Data Exchange (SPDX) and SPDX license identifiers.

Usage

The official REUSE tutorial and the tool usage section is really good so I will just reproduce a quick start here:

1. Put your licenses in the LICENSES/ directory.
   
2. Add a comment header to each file that says something like
   
   SPDX-License-Identifier: GPL-3.0-or-later
   SPDX-FileCopyrightText: $YEAR $NAME
   
   You can be flexible with the format, just make sure that the line starts with “SPDX-License-Identifier:“ and/or “SPDX-FileCopyrightText:“
   

Comment headers

REUSE, and many organizations like GNU, recommend including license header comments in source files as it helps to prevent confusion or errors. So even if the REUSE.toml copyright file exists as the central place for licensing information, sometimes files get copied or forked into new projects and third parties might not have a well organized repository bureaucracy. Without a statement about what their license is, moving single files into another context might eliminate all trace of that information.

Example of a header comment:

# SPDX-FileCopyrightText: Andreas Haerter, ACME Corp (https://example.com)
# SPDX-License-Identifier: CC-BY-SA-4.0

One with dual-licensing:

/*
  SPDX-FileCopyrightText: Jane Doe <j.doe@example.com>
  SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
*/

REUSE.toml

You might come to the conclusion that to skip adding headers to every file and only using a REUSE.toml is better for your project … fair enough and that will still be compliant. It is also possible to bulk-license whole directories using this technique. The file format is specified, but a simple example helps to get started:

version = 1
SPDX-PackageName = "Foo bar project"
SPDX-PackageDownloadLocation = "https://git.example.com/foobar"
SPDX-PackageSupplier = "ACME Inc. (https://example.com)"

[[annotations]]
path = "**"
precedence = "closest"
SPDX-FileCopyrightText = "ACME Inc."
SPDX-License-Identifier = "LGPL-2.1-or-later"

Verification

Now verify your work using reuse lint:

$ reuse lint
[...]
Congratulations! Your project is compliant with version 3.4 of the REUSE Specification :-)

Demo

The FSFE created a small screencast², which follows the tutorial, making the REUSE example repository compliant:

Tips and tricks

Needed vocabulary when you start learning or teaching

To follow documentation and communication in the licensing space, it is important to know about the meaning of:

• Software Package Data Exchange (SPDX) and SPDX license identifiers: A standard for identifying licenses using short, consistent identifiers (like MIT or GPL-3.0-only). It simplifies license tracking and automation.
  
• Software Bill of Materials (SBOM): A structured list of all software components and their licenses in a project. It helps with transparency, security audits, and legal compliance.
  
• Copyleft (license): A type of open source license that ensures derivative works remain under the same license. It protects user freedoms by requiring shared modifications. The GPL is a well-known example.
  
• Permissive (license): A license that allows code to be reused with minimal conditions, including in proprietary software, without giving back modifications. Common examples include MIT, BSD, and Apache 2.0.
  
• TOML: A configuration file format. REUSE.toml (a machine-readable file in your project’s root directory) uses it to declare licensing information based on filename patterns.
  
• DEP5: A machine-readable debian/copyright file which was used before REUSE.toml. DEP5, while still supported, has been deprecated since the introduction of REUSE.toml. This is important to know when hitting older documentation or tutorials.

My personal killer feature: Additional comments in REUSE.toml

It might sound trivial, but it was always cumbersome for me to keep track of the originally used download URLs and other common data around simple third-party files, like “this small icon there“. From my point of view, the RESUE.toml file is the ideal place to keep additional data on third party files by using SPDX-FileComment without cluttering the repository or the end-user documentation. If there is at least one example, in my experience, maintaining source information and reasoning for third-party files is quickly adopted even in teams without many regulations:

Example 1: REUSE.toml with sections tracking the original download URLs or notes

[...]
[[annotations]]
path = "assets/images/window.svg"
precedence = "closest"
SPDX-FileCopyrightText = "2022 Refactoring UI Inc."
SPDX-License-Identifier = "MIT"
SPDX-FileComment = "https://github.com/tailwindlabs/heroicons/blob/master/optimized/24/outline/window.svg"

[[annotations]]
path = ["extensions/Find-WindowHandle.ps1", "extensions/Helper.ps1"]
precedence = "closest"
SPDX-FileCopyrightText = "2018 Grégoire Geis (https://github.com/71/Focus-Window/)"
SPDX-License-Identifier = "MIT"
SPDX-FileComment = "Slightly adapted for this project by foundata GmbH (https://foundata.com)"
[...]

Example 2: The REUSE.toml from SAP/openui5 which uses the file patterns and comments to keep track of single files copied from other projects:

[...]
[[annotations]]
path = "src/sap.ui.integration/test/sap/ui/integration/demokit/cardExplorer/webapp/thirdparty/CfWorkerJsonSchemaValidator.js"
precedence = "aggregate"
SPDX-FileCopyrightText = "2020 Jeremy Danyow"
SPDX-License-Identifier = "MIT"
SPDX-FileComment = "these files belong to: @cfworker/json-schema"

# Library: sap.ui.webc.common:
[[annotations]]
path = [
    "src/sap.ui.webc.common/src/sap/ui/webc/common/thirdparty/base/**",
    "src/sap.ui.webc.common/src/sap/ui/webc/common/thirdparty/theming/**",
    "src/sap.ui.webc.common/src/sap/ui/webc/common/thirdparty/localization/**",
    "src/sap.ui.webc.common/src/sap/ui/webc/common/thirdparty/icons/**",
    "src/sap.ui.webc.common/src/sap/ui/webc/common/thirdparty/icons-tnt/**",
    "src/sap.ui.webc.common/src/sap/ui/webc/common/thirdparty/icons-business-suite/**"
]
precedence = "aggregate"
SPDX-FileCopyrightText = "SAP"
SPDX-License-Identifier = "Apache-2.0"
SPDX-FileComment = "these files belong to: UI5 Web Components"
[...]

README section template about licensing and copyright for humans

I find it useful to have a generic, easy to adapt text snippet for the README.md or a comparable central place which is easy for humans to notice and read. I created and use the following template, taking advantage of the existing REUSE information to make the section basically maintenance free without being useless:

## Licensing, copyright

<!--REUSE-IgnoreStart-->
Copyright (c) YYYY, ACME Inc.

This project is licensed under the GNU General Public License v3.0 or later (SPDX-License-Identifier: `GPL-3.0-or-later`), see [`LICENSES/GPL-3.0-or-later.txt`](LICENSES/GPL-3.0-or-later.txt) for the full text.

The [`REUSE.toml`](REUSE.toml) file provides detailed licensing and copyright information in a human- and machine-readable format. This includes parts that may be subject to different licensing or usage terms, such as third-party components. The repository conforms to the [REUSE specification](https://reuse.software/spec/). You can use [`reuse spdx`](https://reuse.readthedocs.io/en/latest/readme.html#cli) to create a [SPDX software bill of materials (SBOM)](https://en.wikipedia.org/wiki/Software_Package_Data_Exchange).
<!--REUSE-IgnoreEnd-->

Replace YYYY with the year of the first release or code contribution and adapt the mentioned license, filenames and links as needed. The HTML comments prevent REUSE linting errors when e.g. listing multiple licenses.

The wording is already pointing to the copyright file (REUSE.toml) and mentions that parts of the project might be subject to different licensing than the main one. If this is not good enough, feel free to adapt the wording of the main “licensed under” sentence to highlight the main licensing rules without the need to maintain every single bit outside of the copyright file. Examples (adapt as needed):

The project is dual-licensed under the

* GNU General Public License v3.0 or later (SPDX-License-Identifier: `GPL-3.0-or-later`), see [`LICENSES/GPL-3.0-or-later.txt`](./LICENSES/GPL-3.0-or-later.txt) for the full text.
* Apache License 2.0 (SPDX-License-Identifier: `Apache-2.0`), see [`LICENSES/Apache-2.0.txt`](./LICENSES/Apache-2.0.txt) for the full text.

[... usual template follows ...]

License detection on Github or Gitlab

If you follow REUSE, you will notice that Github and Gitlab are no longer able to detect licensing information for your repository.

Even if automatic licensing is broken by design for the reasons outlined above, it is understood that it would be nice if all the broken license detection tools spit out something, even unreliable but working, for indexes and searches (for the sole reason of not having a disadvantage if inexperienced users are searching for projects and filter by often broken meta data).

If you need this, put the stated “license with the highest freedom protections” just for search-indexes and GitHub in a LICENSE or COPYING file in the root directory of your project:

1. GitHub uses Licensee to attempt to identify the license of a project and Licensee does not support the REUSE specification.
   
2. A workaround to fix the automatic license detection of GitHub and others is to place an additional LICENSE or COPYING file in the root directory of your project. This is allowable by REUSE. These files are explicitly ignored by the toolset and do not need an additional .license file or header.
   
3. If you want to prevent a duplication of License texts, beware of another issue with Licensee: You can place a symlink at LICENSES/<your license>.txt pointing to the LICENSE or COPYING file in the project’s root directory. reuse lint will follow that link. Licensee sadly does not even support symlinks, so a more logical symlink from LICENSE or COPYING pointing to LICENSES/<your license>.txt is not solving the issue. I therefore recommend a real copy instead of a symlink to keep things accessible when using the workaround.

I, for myself, would use this workaround only if a single license is used for all of the project’s files. This would prevent misunderstandings or conflicts and simply ignore GitHub’s limited behavior in all other cases.

Years in copyright texts

This is not exactly a REUSE topic but I noticed it is discussed quite a lot when a project starts adopting REUSE. IANAL, but it is not necessary to update the copyright year since the main legal intention is to state the year of the first public release or code contribution. But it is common to do so anyway, especially since it shows third parties that a project is still alive.

I usually propose the following which might also be a useful technique for your project:

• Update the copyright data but maintain the copyright year only at central places like a project’s README.md reduce the maintenance effort.
  
• Simply add each year with a release or updates separated by commas. You can use a timespan (yearX-yearY) for multiple subsequent years.
  
• Example:
  • The first release and copyright statement was Copyright (c) 2013.
  • There were releases or updates in several but not all years afterwards:
    • 2023 → Copyright (c) 2013, 2015, 2018-2021, 2023.
    • 2015 → Copyright (c) 2013, 2015.
    • 2018 → Copyright (c) 2013, 2015, 2018.
    • 2019 → Copyright (c) 2013, 2015, 2018, 2019.
    • 2020 → Copyright (c) 2013, 2015, 2018-2020.
    • 2021 → Copyright (c) 2013, 2015, 2018-2021.

Conclusion

Licensing clarity is needed for sustainable collaboration in open source. The REUSE specification doesn’t try to replace legal frameworks or licensing decisions, but it makes the messy practicalities of license management predictable, explicit, and automatable.

Adopting REUSE can feel like extra effort at first, especially for existing codebases. But once in place, it pays off by making your project easier to understand, maintain, package, and … reuse… . REUSE helps you express the legal structure of your project in a way that machines and humans can agree on. And that’s worth a lot.

1. Using the LICENSES/ directory is also recmmended by the CII best practices, and implemented by the Linux Kernel. ︎
2. Source: https://download.fsfe.org/videos/reuse/screencasts/reuse-tool.gif, Copyright © 2001-2025 Free Software Foundation Europe, Verbatim copying and distribution is permitted in any medium, provided this notice is preserved. ︎

The kernel team is working on final integration for Linux kernel 6.15. This version was just recently released, and will arrive soon in Fedora Linux. As a result, the Fedora Linux kernel and QA teams have organized a test week from Sunday, June 08, 2025 to Sunday, June 15, 2025. The wiki page in this article contains links to the test images you’ll need to participate. Please continue reading for details.

How does a test week work?

A test week is an event where anyone can help ensure changes in Fedora Linux work well in an upcoming release. Fedora community members often participate, and the public is welcome at these events. If you’ve never contributed before, this is a perfect way to get started.

To contribute, you only need to be able to do the following things:

• Download test materials, which include some large files
• Read and follow directions step by step

The wiki page for the kernel test week has a lot of good information on what and how to test. After you’ve done some testing, you can log your results in the test week web application. If you’re available on or around the days of the event, please do some testing and report your results. We have a document which provides all the necessary steps.

Happy testing, and we hope to see you on one of the test days.

As a Python developer you work hard to ensure code works correctly across different Python versions. You have to test against Python 3.11, 3.12, 3.13 and beyond, it can be tedious. But what if your continuous integration (CI) pipeline could handle it automatically? This is where GitHub Actions and tox come in – a powerful combo for seamless CI and multi-version testing.

Introduction

Imagine you are a developer for a small real estate company, racing against the clock to deliver a groundbreaking fizz-buzz feature on the company’s python app. You make a last minute fix and commit. After testing locally, you merge with confidence, push to GitHub, and ship. Then disaster strikes, the change breaks an existing feature and the new feature you added does not work. Management is furious, and the only excuse you could give is “it worked on my machine”.

If only you had set up GitHub Actions for continuous integration (CI), you could have made sure it worked on different versions of Python.

In this article, you will learn how to set up GitHub Actions to manage continuous integration for your Python projects. You will also learn how to test your code on different versions of Python using tox on Fedora.

Prerequisites

• GitHub Account
• Fedora, CentOS, or RHEL server. This guide uses Fedora 41 server edition. Fedora, CentOS, and RHEL servers are interchangeable.
• A user account with sudo privileges on the server.
• Command line competency.
• Python 3.13 environment, with poetry, tox, and pytest packages installed.

What is Continuous Integration?

Continuous Integration (CI) is a practice where you merge your code to the repository several times a day. CI reduces software defects, because every time you push a change to the repository it is verified by automated tests and built. Generally, CI refers to the server part of the build process, where you run unit tests and build your application. However, it can also be done locally. To carry out CI, you define a build pipeline using YAML. The build pipeline runs a set of automated tools for unit tests, security checks, document generation, or code quality checks.

Why use CI?

Central to CI is code stability. By running unit tests on your code whenever you make a change, you are confident that those changes do not cause software defects in your codebase. This way, you know, your code is stable; commit after commit.

There are two important aspects of CI that ensure code stability:

1. CI checks that code compiles or builds successfully.
2. CI checks that all unit tests pass successfully.

What is Tox?

Tox, is a tool that automates Python unit tests in multiple Python environments. According to tox documentation, you can use tox for:

• checking your package builds and installs correctly under different environments
• Running your tests in each of the environments with the test tool of choice
• As a frontend to continuous integration servers

What are GitHub Actions?

GitHub Actions is a feature on Github.com that serves as an automation engine for CI.  It allows you to automate tasks directly within your GitHub repository using workflows.

To use GitHub Actions effectively, you need to understand how the system works using a top-down approach.

An event is a specified activity that triggers a workflow. An activity may occur when a commit is pushed or a pull request is made. In this tutorial, an event occurs when you push a commit to your GitHub repository.

A workflow is an automated process which runs when an event occurs. It defines how code is tested, built or compiled using actions. A YAML file defines the steps in the workflow and exists in the .github/workflows directory of your repository.

A job runs actions you specify. While there are no limits on the number of actions you can run in a job, there is a maximum execution time of 6 hours. Jobs are executed in runners (containers or virtual machines). You can choose Linux, Windows, or macOS runners to run your CI jobs.

An action is the smallest building block of a workflow. According to GitHub documentation; “an action is a custom application for the GitHub Actions platform that performs a complex but frequently repeated task”. You can write custom actions as Node.js scripts or use those in the GitHub marketplace.

Test a Python project

This python project is for a calculator with functions for adding and multiplying numbers only. You will use pytest and tox to test the code using Python 3.12, and 3.13. You will also push the code to GitHub, and use GitHub Actions for CI.

HEAD’s UP: Remember, GitHub Actions uses runners for CI jobs, and runners can be Windows, Ubuntu or macOS? Did you notice, Fedora is not on the list?

Checkout, out this repository on GitHub. It contains working code for the calculator, tests, and a workflow for this tutorial. It uses the tox-github-action from Fedora Python to run tests in CI. The tests are run in a Fedora container, which is hosted in an Ubuntu runner.

This is the file structure you will work with;

Step 1: Write the Code

Here is the calculator code at /ciwithfedora/calculator.py

def add(a, b):
   """Returns the sum of two numbers."""
   return a + b

def multiply(a, b):
   """Returns the product of two numbers."""
   return a * b

Step 2: Write unit tests

Here is the unit test code at /ciwithfedora/test_calculator.py

import pytest
from calculator import add, multiply

# Test cases for add function
def test_add_positive_numbers():
   assert add(2, 3) == 5

def test_add_negative_numbers():
   assert add(-1, -1) == -2

def test_add_zero():
   assert add(0, 5) == 5
   assert add(5, 0) == 5

def test_add_mixed_signs():
   assert add(-1, 3) == 2
   assert add(3, -1) == 2

# Test cases for multiply function
def test_multiply_positive_numbers():
   assert multiply(2, 3) == 6

def test_multiply_with_zero():
   assert multiply(0, 5) == 0
   assert multiply(5, 0) == 0

def test_multiply_negative_numbers():
   assert multiply(-2, -3) == 6

def test_multiply_mixed_signs():
   assert multiply(-2, 3) == -6
   assert multiply(2, -3) == -6

Step 3: Manage Dependencies with Poetry

3.1 Poetry configuration:

Here is the poetry configuration code at ./pyproject.toml

[tool.poetry]
name = "ciwithfedora"
version = "0.1.0"
description = "Python CI on Fedora with GitHub Actions. Tutorial article for Fedoramagazine.org."
authors = [""]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"

[tool.poetry.group.dev.dependencies]
tox = "^4.26.0"
pytest = "^8.3.5"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

3.2 Install the dependencies

$ poetry install

Step 4. Configure tox to run tests in different Python environments

Here is the tox configuration code at ./tox.ini

[tox]
envlist = py313, py312

[testenv]
allowlist_externals = poetry
commands_pre =
   poetry install --no-interaction --no-root
commands =
   poetry run pytest

Step 5. Run tests

5.1 Run unit tests with pytests

$ poetry run pytest -v

5.2 Run unit tests with tox in different Python environments

$ poetry run tox

Step 6. Automate tests with GitHub Actions

The workflow file is located at .github/workflows/workflow.py/

Here is the code;

name: Python Tests 

on:
  push:
    branches: [ dev ]

jobs:
  tox_test:
    name: Tox test
    steps:
    - uses: actions/checkout@v4
    - name: Run tox tests
      id: test

      uses: fedora-python/tox-github-action@main
      with:
        tox_env: py313,py312
        dnf_install: poetry

    runs-on: ubuntu-latest

Step 7. Push project to GitHub to trigger CI

$ git push

You can click on the actions tab on your GitHub repo to see CI in progress.