Eduardo Vasconcelos - Linux

Study notes on the Linux Security Module (LSM) kernel framework--Part 2

2026-06-25T00:00:00-03:00

This blog post is a continuation to my previous study notes about the inner workings of the LSM kernel framework. Previously, I've established an understanding of where LSMs are positioned in the kernel's call sequence that leads to accessing system resources, how LSMs initialize, define and register call hooks based on a static calls table data structure.

In this blog post, I aim at understanding how an LSM's codebase integrates into the kernel from a development standpoint, and how one should go about programming an LSM from the ground up. In order to achieve that, I'll look at the functioning of a specific LSM--namely Yama--, by establishing intuition about its threat model, then collecting practical evidence on how it changes the behavior of a live system, and finally moving to looking at its source code to understand its implementation. To conclude, I'll leverage the insights resulting from that exercise to program my own proof of concept LSM and boot into a kernel that loads it to hopefully bring it to life.

Why Yama?

Before we begin, I should like to clarify why I picked Yama as a case study over the other LSMs in the kernel's codebase. The answer to that is because Yama hits a sweet spot between complexity and simplicity. With less than 500 LOC, only four security hooks, and a very well defined threat model, Yama delivers plenty of material for analysis, but still without being overwhelming to analyze. That said, before we delve into Yama's codebase, let's get a glimpse at the problem that led to its development in first place.

The threat model that Yama addresses

As stated in the kernel's documentation for the Yama LSM:

"Yama is a Linux Security Module that collects system-wide DAC security protections that are not handled by the core kernel itself."

More specifically, Yama addresses a threat model where processes running under the same user UID may act maliciously toward each other. As obvious as that might read, such threat model has only emerged in the last few decades. In the early days of computing, processes belonging to the same user were considered equally trusted. Of course, that premise simply doesn't hold anymore, but what that entails is that historically--as naive as it may appear from a modern security engineering perspective--, certain aspects of operating systems were originally designed with that threat model in mind. Such is the case of the ptrace() syscall. From man:

"The ptrace() system call provides a means by which one process (the "tracer") may observe and control the execution of another process (the "tracee"), and examine and change the tracee's memory and registers. It is primarily used to implement breakpoint debugging and system call tracing."

From the description above, it's not hard to understand why uncontrolled access to ptrace() might be troublesome. If a malicious process were able to attach to another process through ptrace(), it would have full control not only over the tracee's data, but also over its execution flow, leading to full process compromise.

The way Yama addresses the threat model above is by establishing four so called "scope levels":

Scope level 0 is the default kernel policy where any process is able to ptrace() processes belonging to the same UID;
Scope level 1 allows parent processes to trace their children. Processes to whom tracees explicitly grant permission via prctl() and root are also allowed to ptrace() processes;
Scope level 2 restricts tracing to processes with capability CAP_SYS_PTRACE, such as root user processes; and
Scope level 3 disables tracing entirely, even to the root user.

When Yama is enabled, the scope level in which it is operating can be examined by issuing:

sysctl kernel.yama.ptrace_scope

Furthermore, it is possible to change Yama's scope level by issuing:

sudo sysctl -w kernel.yama.ptrace_scope=<scope level>

Where <scope level> is the desired Yama scope level.

How Yama changes the behavior of a live system

Before we delve into Yama's implementation internals, let's see how a live system behaves with respect to Yama's scope levels. To achieve that, we'll perform an anecdotal experiment. I've programmed a pair of proof of concept user space programs to help in this exercise:

In the GitHub repository linked above, program target.c implements the tracee; and
Program dump_mem.c implements the tracer. It attaches to target.c's process to actively dump part of its memory space--namely 64 words of its stack.

While the idea here is not to exercise the entirety of Yama's functionality and configuration, such programs should help us establish enough intuition about how Yama changes the behavior of a live system before we look at its source code. Program target.c is shown below:

#include <stdio.h>
#include <unistd.h>

void f(pid_t pid, char a, char b, char c) {
    printf("My PID is: %d (0x%x)\n", pid, pid);
    printf("a: %c\n", a);
    printf("b: %c\n", b);
    printf("c: %c\n", c);
    printf("Press any key to continue...\n");
    getchar();
}

int main(int argc, char *argv[])
{
    pid_t pid;
    char a, b, c;

    pid = getpid();
    a = 'a'; // 61
    b = 'b'; // 62
    c = 'c'; // 63

    f(pid, a, b, c);

    return 0;
}

By inspecting the code above, we see that target.c reads its own PID, then passes it as an argument, along with the characters 'a', 'b' and 'c', to function f(). In turn, f() prints all such values to stdout, then waits for the user to press a key before returning, leading to the program exiting.

In turn, dump_mem.c expects the tracee's PID as a command line argument, attaches to it while it is waiting for user input at getchar(), then does the following:

/* ... */

ptrace(PTRACE_GETREGS, pid, NULL, &regs);
sp = regs.rsp;

for (i = 0; i < 64; ++i) {
    off = sp + i * 8;
    word = ptrace(PTRACE_PEEKDATA, pid,
                  (void *) off, NULL);
    printf("%016lx: %016lx\n", off, word);
}

/* ... */

While usage details of ptrace() syscalls in user space are out of the scope of this blog post--please look at the corresponding man page for detail--, the code snippet above shows that dump_mem.c first retrieves the tracee's stack pointer, then dumps 64 words starting at the address in SP, namely the 64 topmost words of the tracee's stack. Since the tracee is blocked at getchar() while the tracer dumps memory words, function f()'s segment is dumped to stdout. The fact that the segment contains the sequence of characters from 'a' to 'c'--which translates to the sequence of integers from 61 to 63--is intentional to aid in spotting it amid dumped data, serving as evidence that we're indeed dumping the tracee's stack.

Let's first take a look at the scope level that is currently configured for Yama in our Arch Linux lab host. If we issue sysctl kernel.yama.ptrace_scope, here's what we'll see:

Indicating that the system is at scope level 1, meaning that only a tracee's parent, root processes, or processes to whom the tracee has explicitly granted PR_SET_PTRACER via prctl() should be able to attach to any given process for tracing. While we won't exhaust these possibilities here, let's see what happens when an unprivileged dump_mem.c process tries to attach to target.c's process. First, we run the target process:

The tracee prints its PID to stdout--i.e. 576, or 240 in hexadecimal notation--, along with the arguments to f(), and blocks at getchar(). That gives us a chance to run the tracer. First, let's run it unprivileged:

As expected, the tracer is unable to attach to the tracee. Let's run it again, this time with root's UID:

And the execution seems to succeed. Indeed, if we look at the output at /tmp/dump.txt by issuing cat /tmp/dump.txt | grep 616263, here's what we'll see:

Confirming that, indeed, we have dumped the tracee's stack. Not only that, we collected anecdotal evidence that Yama seems to behave--at least partially--as defined in its documentation at scope level 1. Let's move on to another scope level. If we change Yama's scope level to 0 and run the tracer process again, without root privilege:

We confirm that we've been able to dump the tracee's stack, now from an unprivileged tracer--just as expected. Yama's scope level 2 restricts tracing to processes with capability CAP_SYS_PTRACE. While CAP_SYS_PTRACE is inherent to root processes, scope level 2 differs from scope level 1 in that it only allows CAP_SYS_PTRACE processes to perform tracing. For simplicity's sake, we'll skip scope level 2 here, as the limitations inherent to our proof of concept programs would lead to observing system behavior identical to that of scope level 1 in scope level 2--succeeding under root's UID, failing otherwise. Distinguishing between scope levels 1 and 2 would require capability manipulation, which is out of the scope of the exercise herein. That said, let's move on to scope level 3, where tracing is disabled entirely:

NOTE: Please bear in mind that after changing Yama's scope level to 3, only a reboot will change it back to its original value at scope level 1 as scope level 3 is Yama's maximum security level, and sysctl calls are not allowed to change it.

As expected, now, not even root processes are able to attach to the tracee.

That concludes our anecdotal experiment. We've now established enough intuition about Yama's functioning and how it impacts the behavior of a live system, and we can now move on to studying the LSM's implementation at security/yama/.

A look at Yama's source code

In this section, we'll inspect part of the source code of the Yama LSM with the goal of understanding its implementation well enough to build our own proof of concept LSM later on.

First, let's take a look at Yama's Kconfig file at security/yama/Kconfig:

# SPDX-License-Identifier: GPL-2.0-only
config SECURITY_YAMA
    bool "Yama support"
    depends on SECURITY
    default n
    help
      This selects Yama, which extends DAC support with additional
      system-wide security settings beyond regular Linux discretionary
      access controls. Currently available is ptrace scope restriction.
      Like capabilities, this security module stacks with other LSMs.
      Further information can be found in
      Documentation/admin-guide/LSM/Yama.rst.

      If you are unsure how to answer this question, answer N.

Kconfig files follow the conventions established in the kernel's Kconfig language, and serve the purpose of defining the configuration interface for kernel features and modules prior to compilation.

What Yama's Kconfig file does is it defines a new configuration option, namely SECURITY_YAMA, of type bool, and input prompt "Yama support". The input prompt is the string that is displayed to the developer at compilation time. Such configuration option defaults to "n"--i.e. "no", meaning that it is disabled by default--, and depends on the SECURITY configuration. In turn, the SECURITY configuration is defined in the security subsystem's Kconfig file at security/Kconfig. Here's what it looks like:

# ...

config SECURITY
    bool "Enable different security models"
    depends on SYSFS
    depends on MULTIUSER
    help
      This allows you to choose different security modules to be
      configured into your kernel.

      If this option is not selected, the default Linux security
      model will be used.

      If you are unsure how to answer this question, answer N.

# ...

The help text in the snippet above makes things a lot clearer: in order for us to be able to use any given LSM, the security subsystem's SECURITY configuration must be enabled, which explains the dependency specified in Yama's Kconfig.

To conclude, Yama's Kconfig confirms what we've been discussing about Yama with respect to its scope, and adds that it stacks with other LSMs. In practice, this means that Yama can be used in conjunction with other minor LSMs deployed in a system.

Having understood Yama's configuration, let's now briefly visit its Makefile at /security/yama/Makefile:

# SPDX-License-Identifier: GPL-2.0-only
obj-$(CONFIG_SECURITY_YAMA) := yama.o

yama-y := yama_lsm.o

What this file does is it checks whether CONFIG_SECURITY_YAMA is enabled in the kernel's .config file at compilation time. If so, this results in the build system creating object file yama.o by linking yama_lsm.o--compiled from yama_lsm.c--into the resulting Yama LSM kernel module.

The last file in Yama's codebase is the module's source code itself at security/yama/yama_lsm.c. We'll now delve into it by breaking it into pieces to make it easier to analyze. The first thing that draws our attention when we open yama_lsm.c for inspection is a list of preprocessor directives specifying Yama's scope levels:

/* ... */ 

#define YAMA_SCOPE_DISABLED 0
#define YAMA_SCOPE_RELATIONAL   1
#define YAMA_SCOPE_CAPABILITY   2
#define YAMA_SCOPE_NO_ATTACH    3

static int ptrace_scope = YAMA_SCOPE_RELATIONAL;

/* ... */

Furthermore, in accordance with what we observed in our anecdotal experiment, we see that Yama defines its default scope level at scope level 1, namely YAMA_SCOPE_RELATIONAL. If we scroll further down into the file, we'll find a couple of familiar data structures, namely the definition of the LSM's ID and hook list, similar to the ones discussed in my previous blog post where I case studied AppArmor's hook registration routine:

/* ... */

static const struct lsm_id yama_lsmid = {
    .name = "yama",
    .id = LSM_ID_YAMA,
};

static struct security_hook_list yama_hooks[] __ro_after_init = {
    LSM_HOOK_INIT(ptrace_access_check, yama_ptrace_access_check),
    LSM_HOOK_INIT(ptrace_traceme, yama_ptrace_traceme),
    LSM_HOOK_INIT(task_prctl, yama_task_prctl),
    LSM_HOOK_INIT(task_free, yama_task_free),
};

/* ... */

From the code snippet above, it's interesting to note that Yama initializes a total of four hooks specified in the LSM interface, namely:

ptrace_access_check(): this hook is used to check whether a process should be allowed to trace a child process;
ptrace_traceme(): this hook is used to check whether the parent of the current process is allowed to trace it prior to having the child process grant the parent tracing permission;
task_prctl(): this hook is used to check if a prctl() operation should be allowed on the current process; and
task_free(): this hook is used to free a process' LSM blob.

Furthermore, if we git grep LSM_ID_YAMA, we'll find that the LSM's ID is defined at include/uapi/linux/lsm.h:

/* ... */

#define LSM_ID_YAMA     105

/* ... */

If we scroll further down, we'll find another mandatory code structure, namely a call to macro DEFINE_LSM, making the LSM framework recognize the Yama LSM by pointing to its ID and init function:

/* ... */

DEFINE_LSM(yama) = {
    .id = &yama_lsmid,
    .init = yama_init,
};

/* ... */

Speaking of Yama's init function, here's what it looks like:

/* ... */

static int __init yama_init(void)
{
    pr_info("Yama: becoming mindful.\n");
    security_add_hooks(yama_hooks, ARRAY_SIZE(yama_hooks), &yama_lsmid);
    yama_init_sysctl();
    return 0;
}

/* ... */

From the code snippet above, we see that all the init function does is it registers Yama's hook list by calling security_add_hooks()--again, I already examined this process while case studying AppArmor in my previous blog post about the kernel's LSM framework, so I won't get into the details here--, and initializes the LSM's sysctl interface with a call to yama_init_sysctl(). Thus, part of Yama's codebase deals with the LSM's sysctl administration interface, and part deals with the security hooks themselves.

We'll now focus on the latter and delve into one of Yama's hook definitions, namely yama_ptrace_access_check(), whose code I've reproduced below for convenience. What follows is an analysis of its inner workings:

/* ... */

static int yama_ptrace_access_check(struct task_struct *child,
                    unsigned int mode)
{
    int rc = 0;

    /* require ptrace target be a child of ptracer on attach */
    if (mode & PTRACE_MODE_ATTACH) {
        switch (ptrace_scope) {
        case YAMA_SCOPE_DISABLED:
            /* No additional restrictions. */
            break;
        case YAMA_SCOPE_RELATIONAL:
            rcu_read_lock();
            if (!pid_alive(child))
                rc = -EPERM;
            if (!rc && !task_is_descendant(current, child) &&
                !ptracer_exception_found(current, child) &&
                !ns_capable(__task_cred(child)->user_ns, CAP_SYS_PTRACE))
                rc = -EPERM;
            rcu_read_unlock();
            break;
        case YAMA_SCOPE_CAPABILITY:
            rcu_read_lock();
            if (!ns_capable(__task_cred(child)->user_ns, CAP_SYS_PTRACE))
                rc = -EPERM;
            rcu_read_unlock();
            break;
        case YAMA_SCOPE_NO_ATTACH:
        default:
            rc = -EPERM;
            break;
        }
    }

    if (rc && (mode & PTRACE_MODE_NOAUDIT) == 0)
        report_access("attach", child, current);

    return rc;
}

/* ... */

By inspecting the code snippet above, we see that yama_ptrace_access_check() expects two arguments, namely child, a struct of type struct task_struct defined at include/linux/sched.h, representing the process that the current process is trying to ptrace(), and an integer containing ORed PTRACE_MODE_* flags, defining the ptrace() access mode of the operation in question.

First, the function defines its return value, namely rc, whose value is initialized to 0, which translates to a permission grant. What follows is a check of whether the PTRACE_MODE_* flag contains a write operation, in which case the function switches ptrace_scope--i.e. Yama's current scope level--, branching to specific routines according to the scope level found.

At scope level 0--i.e. YAMA_SCOPE_DISABLED--, the case breaks and returns immediately. At scope level 3--i.e. YAMA_SCOPE_NO_ATTACH--, the function assigns rc to -EPERM, indicating that the hook reached a state of insufficient permission, then the case breaks and the function falls into a check of whether PTRACE_MODE_* does not contain PTRACE_MODE_NOAUDIT. Such flag is used in certain use cases to indicate that the access should not be added to audit logs. If it is not present, the function goes on to call report_access() to log the fact that the ptrace() syscall resulted in a failure to attach.

Now, let's look at the other cases. Scope level 1--i.e. YAMA_SCOPE_RELATIONAL--results in the following routine:

First, the function acquires the thread's RCU read lock, ensuring that the task data structures that it manipulates in the routine aren't deallocated prior to it exiting the critical region where it reads them;
Next, it checks to see whether the child process is not dead, and if it is, the function assigns rc to -EPERM, and the routine concludes with the release of the RCU read lock, with the case breaking and the aforementioned check regarding logging being performed;
In turn, if rc is still 0 at this point, the actual permission checks are performed, and if all of them fail, rc is assigned to -EPERM, the lock is released, the case breaks, and the very same check as before regarding logging is performed. Let's now step into the permission checks that this step actually entails.

The first permission check is !task_is_descendant(current, child). task_is_descendant() checks whether child is a descendant of current, returning 1 in case it is, and 0 otherwise. Thus, !task_is_descendant(current, child) resolves to 1 when child is not a descendant of current.

The second permission check is !ptracer_exception_found(current, child). ptracer_exception_found() checks whether current is an authorized tracer of child, either due to current belonging to the same thread group as child's parent or due to child having actively prctl()ed to grant current tracer permission, returning 1 in case current is an authorized tracer of child, and 0 otherwise. Thus, !ptracer_exception_found(current, child) resolves to 1 when current is not allowed to trace child.

Lastly, the third permission check is !ns_capable(__task_cred(child)->user_ns, CAP_SYS_PTRACE). ns_capable() is a function defined at kernel/capability.c that takes a struct of type struct user_namespace--containing data such as the respective task owner's UID and GID, among other security-related fields--, and checks whether the current process has a given capability in that namespace, returning 1 if so, and 0 otherwise. More specifically, the call herein takes the user namespace field of the child's task credentials--i.e. the security context of child--, and checks to see if the current process has CAP_SYS_PTRACE in said user namespace, in which case it should be allowed to trace child. Thus, !ns_capable(__task_cred(child)->user_ns, CAP_SYS_PTRACE) resolves to 1 when the current process does not have CAP_SYS_PTRACE in child's namespace.

To conclude, scope level 2--i.e. YAMA_SCOPE_CAPABILITY--leads to executing the same permission check discussed in the paragraph above.

All in all, we see that yama_ptrace_access_check() performs LSM context-specific checks regarding internal kernel data structures to take decisions on whether access to certain resources that the LSM aims at protecting should be allowed or not, resulting in the hook returning 0 when access should be granted, and -EPERM otherwise. The other hooks adopt the same behavior, and apart from the configuration and compilation infrastructures, and the sysctl interface that Yama exports, the core infrastructure of the LSM is entirely built around the hooks and their auxiliary functions, constituting the code that allows the LSM to make said access decisions on behalf of the kernel.

That understanding seems enough for us to dare building our own proof of concept LSM now. From this point onward, that's precisely what we'll do.

Building a proof of concept LSM

We'll now work towards building a proof of concept LSM that simply implements a given hook and prints kernel log messages whenever said hook is called. The intent here is to exercise the integration of an LSM into the kernel's codebase.

First off, we'll create a new diretory at security/poc/ and populate it with files Kconfig, Makefile, and poc.c. Next, we'll fill in Kconfig and Makefile based on what we learned from looking at Yama's codebase. Here's what our Kconfig looks like:

# SPDX-License-Identifier: GPL-2.0-only
config SECURITY_POC
    bool "PoC support"
    depends on SECURITY
    default n
    help
      This selects the PoC LSM.

And the module's Makefile:

# SPDX-License-Identifier: GPL-2.0-only
obj-$(CONFIG_SECURITY_POC) := poc.o

poc-y := poc.o

Next, we'll program the module itself by writing poc.c. We'll start by including basic LSM headers and code structures, namely the LSM's ID, init function, and macro definition:

// SPDX-License-Identifier: GPL-2.0-only

#include <linux/lsm_hooks.h>
#include <uapi/linux/lsm.h>

static const struct lsm_id poc_lsmid = {
    .name = "poc",
    .id = LSM_ID_POC,
};

static int __init poc_lsm_init(void)
{
    pr_info("PoC LSM active\n");
    return 0;
}

DEFINE_LSM(poc) = {
    .id = &poc_lsmid,
    .init = poc_lsm_init,
};

Of course, as we've seen, we must also define LSM_ID_POC in include/uapi/linux/lsm.h. Let's go ahead and add a new LSM ID at the end of the ID list and assign our PoC LSM the next available ID in the sequence:

/* ... */

#define LSM_ID_EVM      112
#define LSM_ID_IPE      113
#define LSM_ID_POC      114

/* ... */

In turn, let's define a hook. We'll have our PoC LSM define a single hook, namely file_open(), to have the kernel call our LSM everytime a file is opened. Let's now create our hook list containing that single hook and a hook implementation for it. We'll also add a call to security_add_hooks() to the LSM's init function in order for us to register our hook:

// SPDX-License-Identifier: GPL-2.0-only

#include <linux/lsm_hooks.h>
#include <uapi/linux/lsm.h>

static const struct lsm_id poc_lsmid = {
    .name = "poc",
    .id = LSM_ID_POC,
};

static int poc_file_open(struct file *file)
{
    pr_info("Entered PoC LSM file_info\n");

    /* Do something */

    pr_info("Exiting PoC LSM file_info\n");
    return 0;
}

static struct security_hook_list poc_lsm_hooks[] __ro_after_init = {
    LSM_HOOK_INIT(file_open, poc_file_open),
};

static int __init poc_lsm_init(void)
{
    security_add_hooks(poc_lsm_hooks, ARRAY_SIZE(poc_lsm_hooks),
               &poc_lsmid);
    pr_info("PoC LSM active\n");
    return 0;
}

DEFINE_LSM(poc) = {
    .id = &poc_lsmid,
    .init = poc_lsm_init,
};

NOTE: in the paragraphs that follow, we'll address some further changes that we'll need to make to the kernel's codebase before we're able to compile and boot into a kernel with our PoC LSM enabled. I had missed them in my initial exploration of Yama's codebase documented above, and I only understood my mistake after some additional rounds of trial and error.

As obvious as it may seem now, I had missed the need to change both the security subsystem's Kconfig file at security/Kconfig to source our own PoC LSM's Kconfig file, and its Makefile at security/Makefile to add the object file from our newly created security/poc/ security subsystem subdirectory.

That said, we must instruct the security subsystem's Kconfig file to source that of our own PoC module, and while we're at it, we'll also add our LSM to the lists of enabled LSMs in the default configurations section of security/Kconfig:

# ...

source "security/landlock/Kconfig"
source "security/ipe/Kconfig"
source "security/poc/Kconfig"

# ... 

config LSM
    string "Ordered list of enabled LSMs"
    depends on SECURITY
    default "landlock,lockdown,yama,loadpin,safesetid,smack,selinux,tomoyo,apparmor,ipe,bpf,poc" if DEFAULT_SECURITY_SMACK
    default "landlock,lockdown,yama,loadpin,safesetid,apparmor,selinux,smack,tomoyo,ipe,bpf,poc" if DEFAULT_SECURITY_APPARMOR
    default "landlock,lockdown,yama,loadpin,safesetid,tomoyo,ipe,bpf,poc" if DEFAULT_SECURITY_TOMOYO
    default "landlock,lockdown,yama,loadpin,safesetid,ipe,bpf,poc" if DEFAULT_SECURITY_DAC
    default "landlock,lockdown,yama,loadpin,safesetid,selinux,smack,tomoyo,apparmor,ipe,bpf,poc"
    help

# ...

Next, we must implement the change to security/Makefile, adding the object files from security/poc/:

# ...

obj-$(CONFIG_SECURITY_LANDLOCK)     += landlock/
obj-$(CONFIG_SECURITY_IPE)      += ipe/
obj-$(CONFIG_SECURITY_POC)      += poc/

# ...

After doing the above, we can finally cd into the repository's root and source Kconfig. Now, if we make menuconfig and look at the security subsystem's configuration submenu, here's what it looks like:

We can now activate our PoC module by toggling its option and adding it to the enabled LSM's list, whose value seems to have been obtained from our previous configuration:

Finally, we can save the configuration and proceed to compiling and installing the kernel as usual. After booting into the new kernel, if we look at the list of enabled LSMs, we'll see our PoC LSM listed. Furthermore, the kernel log displays the messages our LSM has been printing every time a file is opened, proving that the kernel is indeed calling the file_open() hook that our LSM registered:

Conclusion

This second part of my LSM study notes addressed the integration of a new LSM built from the ground up to the kernel's codebase. We looked at the threat model and the implementation of an already existing LSM, namely Yama, and by leveraging the knowledge that we acquired from inspecting its codebase, we've successfully built a proof of concept LSM and integrated it to the kernel's build system, allowing us to boot into a kernel that loads it and to inspect its functioning.

By changing the security subsystem to add our own proof of concept LSM, we've learned that extending ther kernel's security subsystem is within arm's reach of anyone willing to venture into navigating its codebase and persisting in making things work out. Not only that, it made me a lot more confident about my basic understanding of an LSM built into the Linux kernel, and it helped me consolidate some of my learnings from part 1 of this series.

I'm not sure where I'll go with respect to part 3 of this blog post series. I might further extend the proof of concept LSM defined herein to implement some actual policy enforcement by establishing an actual threat model for it to address. Additionally, one takeaway of exploring Yama's codebase was noticing the need to deeply understand the different kernel data structures that form the basis of the security checks that LSMs implement, and I might look into that next. Another possibility is further delving into the kernel's generic LSM infrastructure--there's a lot more to look at--while further case studying a major LSM such as AppArmor to see what actual LSM implementations look like. All in all, I'm not sure what my next step will be, but at least I've got some options mapped.

Happy hacking.

Cross-compiling the Linux kernel for ARM64 on the RPi using a QEMU x86_64 Arch Linux compilation host

2026-06-19T15:00:00-03:00

I've been tinkering with the RPi to build a toy example in the context of my PhD research in the last couple of days, trying to get a custom kernel to work on a Zero 2 W board--for those unfamiliar with it, here's a picture:

As much as Raspberry Pi's official documentation is very well organized and thorough about the theme of building a custom kernel for RPi boards, as I discussed in my blog post on setting up a kernel development environment, I've chosen Arch Linux as the base distro for my virtualized compilation host, and as the instructions in the official documentation target Debian-based distros--and seem to aim at physical compilation hosts--, I had to MacGyver my way to a functioning cross-compilation setup for the RPi using the virtualized Arch Linux-based setup that I already had. This blog post documents that procedure.

The cross-compilation scenario herein

Before we begin, it's important to understand that explanations involving cross-compilation scenarios might get rather convoluted to follow, so first of all, let's define our cross-compilation scenario clearly. The figure below shows the three systems involved in our scenario, and where we're positioned:

From the figure, it's easy to realize that three systems are involved in our cross-compilation scenario, namely: a physical host, which happens to be an x86_64 laptop running Arch Linux; a compilation host, which happens to be an x86_64 QEMU Arch Linux VM running on said physical host; and our target system, namely the physical ARM64 RPi Zero 2 W board. It so happens that the RPi board is connected to out lab network, so working from the physical host, we're able to SSH both into the compilation host VM and the RPi board.

Now, of course the RPi boots from a micro SD card containing its boot and root filesystems. In order for us to write to that micro SD card during kernel installation, we'll connect the card to our physical host, and we'll leverage QEMU's virtual filesystem functionality to mount the RPi's filesystem on the micro SD card to a mount point within the compilation host's filesystem. That will allow us to install kernel modules to the RPi's root filesytem.

Not only that, we'll leverage the fact that our physical host also has access to the micro SD card's mount point to scp the kernel image and device tree blobs from the compilation host to the RPi's boot filesystem through the physical host.

Those things we'll become clearer as we advance. For now, the important part is that we understand the different entities that constitute our cross-compilation scenario and their roles.

Installing the stock Raspberry Pi OS image

First off, we need a functioning RPi system as a starting point. I used the Raspberry Pi OS 64-bit stock image for the Zero 2 W board. In order to install the imager to the Arch Linux physical host, we need to issue:

sudo pacman -S rpi-imager

The process of flashing the stock OS is rather straightforward, but in my experience, it's best to configure the system during the flashing procedure. That will save us time later on when we'll setup the development environment, so it should payoff to setup Wi-Fi connectivity, SSH, and other configurations at this stage.

At least that's what I did, but of course, depending on one's lab infrastructure, one might want to do things differently. In my case, setting up Wi-Fi and SSH a priori was handy because I was able to SSH into the board from my laptop right away after installing the OS, without the need to hook it to peripherals. Alternatively, if one chooses to customize later on, one will be able to change system configurations via the raspi-config utilitary after logging into the RPi system some other way.

After the flashing procedure is done, we should be able to boot the RPi and SSH into it--of course, we'll need to check in our router what IP address has been assigned to it. Speaking of that, it might also be interesting to assign the RPi a static IP. That said, the system will boot into the stock kernel, as expected:

After booting the RPi to confirm that everything is okay, we can shut it down. We won't use it for now.

Compiling the kernel for the RPi Zero 2 W

After flashing the stock system, it's time to start the compilation VM on QEMU and prepare to compile the kernel for the Zero 2 W. Again, my previous blog post about setting up a kernel development environment shows how to setup a virtualized Arch Linux compilation host using QEMU.

As usual, we'll clone RPi's kernel by issuing:

git clone --depth=1 https://github.com/raspberrypi/linux linux-rpi

At this point, an important sidenote is that RPi's kernel lags behind the Linux kernel. RPi's kernel development team integrates Linux kernel changes into the RPi kernel only after LTS releases of the Linux kernel are made.

Having cloned the repository, it's time to install our cross-compilation toolchain. Luckily for us, since we're using our preexisting kernel compilation host as a base for our ARM64 cross-compilation host, we'll only need to install package aarch64-linux-gnu-gcc:

sudo pacman -S aarch64-linux-gnu-gcc

And that's it. We're ready to compile our own kernel for the Zero 2 W. What follows is a pretty standard kernel compilation procedure where we'll cd into the repository's directory, clean it to make sure we're not working with any reminiscent garbage, build our cross-compilation kernel config, and then proceed to compilation. An important caveat is that RPi's documentation specifically instructs the creation of env var KERNEL=kernel8, so we'll make sure to do that. Translating to commands, up until config file creation:

cd linux-rpi
make mrproper
KERNEL=kernel8
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2711_defconfig

Something important to notice here is that despite the fact that the RPi Zero 2 W board ships with Broadcom's BCM2710A1 SoC, the base kernel config we're using is that of Broadcom's BCM2711 SoC, namely the chip that ships with the RPi 4 family of boards.

We can finally proceed to compiling. This subject is out of the scope of this blog post, but notice I'm using ccache to optimize future compilation performance here, and one might also want to adjust the number of cores used in compilation according to the configuration of one's own compilation host VM. I used -j 7 here due to my own previous kernel compilation experience in the last few months. Using 7 cores--which translates to nproc + 1 in how my QEMU VM is configured--seems to hit the sweet spot between compilation host performance and physical host usability in my own lab setup, but there's a lot to be said about kernel compilation performance optimization, and I guess it's really on each of us to do the hard work and find our preferred configuration after some rounds of frustration:

ccache make -j 7 ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- Image modules dtbs

Compilation should complete without any issues, and after it's done, we can proceed to installing the newly compiled kernel in our stock system's filesystem.

Installing the newly compiled kernel in the stock system's filesystem

After compilation finishes, we'll go ahead and shutdown the compilation host, connect the RPi's micro SD card to the physical host, and mount both the RPi's root and boot filesystems as the root user--more on that shortly--in the physical host. Here, I used mount points /mnt/rootfs and /mnt/bootfs, respectively. Next, we'll restart the compilation host specifying our mount points as virtual filesystems that the compilation host will be able to access, by adding -virtfs flags to the startup command as follows:

qemu-system-x86_64 \
  # ...
  -virtfs local,path=/mnt/rootfs/,mount_tag=rootshare,security_model=mapped,id=rootfs_share \
  -virtfs local,path=/mnt/bootfs/,mount_tag=bootshare,security_model=mapped,id=bootfs_share

One possible matter of confusion here is which filesystem is root and which is boot after connecting the RPi's micro SD card to the physical host and looking at the output of lsblk. But of course, the boot filesystem is the smaller one, and the root filesystem is the bigger one. For instance, in the figure below, /boot is in sdb1, and / is in sdb2:

Another important observation is that since non-root UIDs between the systems in the cross-compilation scenario will almost certainly diverge, specifying security_model=mapped prevents us from falling into filesystem permission issues while writing to the root filesystem, which truly is owned by the RPi's root. That is why mounting the filesystems as root in the physical host matters.

In fact, our next step is to mount the filesystems--also as root--in the compilation host. Here, I also used mount points /mnt/rootfs and /mnt/bootfs:

mkdir /mnt/rootfs
mkdir /mnt/bootfs
mount -t 9p rootshare /mnt/rootfs
mount -t 9p bootshare /mnt/bootfs

Now, we can go ahead and install the compiled kernel modules to RPi's root filesystem. First, we'll cd into the repository:

cd /path/to/linux-rpi

Then, as root, we'll recreate that same env var that we had created before when we were compiling the kernel:

KERNEL=kernel8

Finally--still as root--, we can go ahead and install the modules to the RPi's root filesystem:

env PATH=$PATH make -j 7 ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- INSTALL_MOD_PATH=/mnt/rootfs modules_install

Next, we'll proceed to the physical host and scp device tree blobs from the compilation host to the RPi's boot filesystem. "And why is that? Why don't we cp device tree blobs from the repository directly into the boot filesystem? Didn't we just mount the RPi's entire filesystem in the compilation host, including /boot?"--one might ask.

And the answer to that has to do with the different filesystems used in the RPi's /boot and / partitions. The boot filesystem is FAT32, while the root filesystem is ext4. Because we're mapping UIDs between the physical host and the compilation host with QEMU virtual filesystem's security_model=mapped flag, and because UIDs are simply not present in FAT32, my hypothesis is that there's no way for our VM to infer that we're allowed to write to /mnt/bootfs, leading to "permission denied" errors whenever we try to write anything to /mnt/bootfs. While I suppose there might be a better solution to this in QEMU's -virtfs itself, I wasn't able to find one so far, hence why I resorted to the scp workaround narrated here.

That said, let's get back to our physical host and, as root, run the following commands. One should adapt them to suit one's own setup:

cd /mnt/bootfs/
cp kernel8.img kernel8.img.bak
scp -P port user@localhost:/path/to/linux-rpi/arch/arm64/boot/Image ./kernel8.img
scp -P port user@localhost:/path/to/linux-rpi/arch/arm64/boot/dts/broadcom/*.dtb ./
scp -P port user@localhost:/path/to/linux-rpi/arch/arm64/boot/dts/overlays/*.dtb* ./overlays/
scp -P port user@localhost:/path/to/linux-rpi/arch/arm64/boot/dts/overlays/README ./overlays/

Then, back to our compilation host, we umount RPi's filesystem by issuing (as root):

umount /mnt/rootfs
umount /mnt/bootfs

At this point, we can shutdown our compilation host. That will allow us to also umount RPi's filesystem from the physical host.

Booting into the newly compiled kernel

Now, we can go ahead and disconnect the RPi's micro SD card from the physical host, connect it back to the board's micro SD card slot, and hopefully boot into our newly compiled kernel.

Ta-da! The compilation timestamp Fri Jun 19 13:27:01 -03 2026 shows that we booted into our newly compiled kernel:

After enabling VNC via raspi-config and performing some basic regression testing, we can verify that we haven't destroyed anything: the system seems fully functional:

Conclusion

This blog post documented my approach to finding a viable workflow for cross-compiling the Linux kernel for the RPi Zero 2 W using my preexisting virtualized Arch Linux kernel compilation host running on QEMU. While the official RPi docs target Debian-based physical hosts, the steps herein show how to use a virtualized setup to achieve functional RPi kernel cross-compilation.

Nevertheless, if I had to do this at scale--which I might have to do for my research--, I reckon using a physical host will make automation a lot easier to achieve, not to mention less time intensive since I'll be cross-compiling the kernel directly on bare metal. A truly scalable approach would also likely include updating the board's kernel over the air, and I might have to think about that in the future.

Anyway, I'm happy with what this little toy example has taught me, and having cross-compiled for ARM64 for the first time was certainly an important step in my adventures in kernel development. That's all.

Happy hacking.

On Linux kernel synchronization

2026-06-16T04:00:00-03:00

From my practical work in kernel development so far, I realized that synchronization concerns are present in pretty much every single corner of kernel code. Hence, kernel synchronization is a topic that deserves special attention from kernel newbies like myself who want to build a working understanding of the Linux kernel and its inner workings. That realization led me to delve into kernel synchronization fundamentals in the last couple of weeks.

In this blog post, I summarize what I've learned about this subject so far, partly from Kaiwan N. Billimoria's Linux Kernel Programming book, partly from revisiting Andrew S. Tanenbaum's Operating Systems--Design and Implementation textbook (2 ed.), partly from reading kernel docs and other materials about the subject, and in large measure--and most importantly--from navigating the Linux kernel's codebase and programming C proofs of concept to actually see textbook materials and documentation claims come into life. First, we'll revisit some basic concepts of operating systems, then we'll gradually build on top of them to achieve an initial comprehension of Linux kernel synchronization mechanisms.

The trouble with multithreaded environments

Multithreading is greatly advantageous in terms of throughput, but it comes with the caveat that if threads are not correctly synchronized while working upon shared writeable data, this might result in a form of unpredictable outcome known as a data race (a.k.a. race condition).

I've crafted the figure below to help illustrate the issue:

In the figure above, two threads, namely thread 1 and thread 2, both read and write shared memory. Let's imagine that the shared memory contains a data structure that receives updates from both threads.

It is easy to imagine a troublesome scenario as follows: thread 1 reads the data structure from shared memory. Before it's done updating it, thread 2 does the same and reads the data structure from shared memory. Next, thread 1 finishes updating the data structure and writes it back to shared memory. Just after that happens, thread 2 does the same, which results in it blindly overwriting the update that thread 1 had just done, thus corrupting the data.

While I was studying Billimoria's text, I extrapolated the book's proposed exercises to program a proof of concept in user space, demonstrating a race similar to the one described above.

A formal definition of data race

As much as the anecdotal example above might serve the purpose of building some intuition, data races are such an important issue to be aware of that the Linux kernel documentation contains a very formal definition of when data races occur and what to look for in order to find them.

Billimoria points to that part of the documentation in his text, and I quote--from tools/memory-model/Documentation/explanation.txt:

"A "data race" occurs when there are two memory accesses such that:

they access the same location,

at least one of them is a store,

at least one of them is plain,

they occur on different CPUs (or in different threads on the same CPU), and

they execute concurrently.

In the literature, two accesses are said to "conflict" if they satisfy 1 and 2 above. We'll go a little farther and say that two accesses are "race candidates" if they satisfy 1 - 4. Thus, whether or not two race candidates actually do race in a given execution depends on whether they are concurrent."

It's important to realize that what the documentation refers to as a "plain" access is an ordinary access to memory performed without resorting to kernel macros aimed at guaranteeing atomicity.

The definition above is very unambiguous, and it implies that in order to address data races adequately, it is important to describe the concepts around them rather systematically. In the following sections, I attempt to do that by delving further into the concepts behind data race prevention mechanisms built into the Linux kernel. The first topic we'll look into is that of critical sections.

Critical sections

Billimoria defines a critical section as a section of code that fulfills these two conditions:

First, there is the possibility that the code will run in parallel; and
Second, the code changes writeable data.

From that definition, the author goes on to conclude that a critical section must run exclusively, sometimes even atomically. Now, running exclusively means that critical sections must run in a serialized fashion, so that no two threads ever run the same critical section at the same time. Running atomically means that critical sections must be allowed to finish uninterrupted before preemption of the running thread occurs. As we'll see, this is sometimes required, but not always.

In turn, Tanenbaum defines critical sections as the portions of a program that access shared memory. According to the author, no two processes must ever enter critical sections at the same time to prevent race conditions.

Both authors converge in saying that critical sections occur when concurrent code accesses shared data, and that in order to prevent them from causing trouble, we must come up with a way of guaranteeing exclusive execution. That leads us to discussing the topic of locks.

Locks

A lock is an entity that can be "owned" by running threads, with a guarantee that at any given point in time, only one single thread can own it.

Thus, a lock can be leveraged to protect a critical section by binding access to the critical section to lock ownership. Since a lock can be owned by only one single thread at any given point in time, critical section serialization is guaranteed, because threads must wait for their turn to own the lock before they are allowed to enter the critical section.

After the thread that owns the lock finishes executing the critical section, it releases the lock--i.e. it "unlocks" the critical section. Only then, the other threads--that have been waiting--, get a chance to acquire ownership of the lock. The next thread that succeeds at acquiring ownership of the lock is then allowed to enter the critical section, while all the others remain waiting. This process repeats until all threads have a chance to acquire ownership of the lock and enter the critical section.

To illustrate, let's get back to the previous anecdotal example and see how a conceptual lock could be used to address the data race that emerged from those two threads accessing shared memory concurrently.

Here's an updated version of the previous figure to account for lock usage:

In the figure above, thread 1 acquires ownership of the lock, then enters the critical section and proceeds with updating the data structure in shared memory. While thread 1 is at it, thread 2 tries to acquire ownership of the lock to enter the critical section, which is blocked, because thread 1 already owns the lock. Thread 2 must wait until thread 1 releases the lock before it gets a chance to acquire it and enter the critical section. After thread 1 finishes the critical section, it releases the lock--"unlock"--, and thread 2 succeeds at acquiring it. Thread 2 is now allowed to enter the critical section and update the data structure in shared memory. After it's done, it also releases the lock, "unlocking" the critical section.

We'll now begin to look at some actual realizations of locks built into the Linux kernel.

Historically, many approaches have been proposed to locking critical sections and solving the problem of data races. Tanenbaum's textbook is very thorough about them. While I strongly recommend anyone who's serious about learning systems programming to read through that portion of his text, in this blog post, I'll be a bit more pragmatic and focus specifically on the excerpts that build the theoretical foundations to the core synchronization mechanisms found in the kernel's modern API, while leveraging the practicality of Billimoria's text to further develop such ideas and contextualize them in terms of contemporary kernel development.

That said, bear with me for a brief exploration of a fundamental synchronization primitive--the semaphore. We'll build upon semaphores to discuss the first type of lock widely used in modern kernel development later on--the mutex.

The semaphore

Semaphores constitute a synchronization primitive invented in the 60s by Edsger Dijktra. In order to understand how semaphores work, let's look at a synchronization problem they help solve: the producer-consumer problem.

Imagine that two processes share a buffer. Process P, the producer, puts data into said buffer, while process C, the consumer, retrieves data from it. Process C can only ever retrieve data from the buffer if it is not empty, while process P can only ever put data into the buffer if it is not full. The figure below helps in visualizing this arrangement:

When process P tries to put data into the buffer to find that it is full, it goes to sleep. When a slot becomes available, process P is awaken. The same happens to process C when it tries to retrieve data from the buffer to find that it is empty. It goes to sleep, to be awaken when data becomes available. Each process checks whether the other is asleep and sends wake up signals accordingly.

Such setting is inherently racy. To illustrate, suppose that process P tries to put data into the buffer. It checks to see if the buffer is full, to find that it is, as illustrated in the figure below:

That results in process P going to sleep, but the scheduler says "Not so fast!": before process P has a chance to go to sleep, it is preempted, while process C is scheduled. Process C checks to see if there's data available for retrieval, to find that there is. So, it retrieves data from the buffer, and it so happens that the scheduler gives it enough processor time to empty the entire buffer:

Next, process C checks to see if process P should be sleeping, to find that it shouldn't--because there's now plenty of empty slots in the buffer--, resulting in it signaling process P to wake up. Then, it goes to sleep, because the buffer is empty. The trouble is since process P is not actually asleep, process C's wake up signal is lost:

Next, process P is scheduled. It resumes execution by going to sleep. At this point, both processes are asleep, and they will remain in that state indefinitely:

Semaphores introduce the idea of saving wake up signals for future use. This is done using an integer whose value is initialized to 0, but that can be incremented or decremented using the atomic operations up() and down(), respectively. down() checks if the value of the semaphore is greater than 0. If so, it decrements its value. If not, the process goes to sleep. In turn, up() increments the value of the semaphore. In case any processes were asleep on said semaphore, the system wakes one of them up and allows it to complete its down() operation, immediately decrementing the value of the semaphore, but resulting in having one less process asleep on it.

Concrete semaphore implementations must guarantee that the operations described above are atomic, and that no two processes ever access the semaphore at the same time. If such premises hold, it is possible to use 3 semaphores to solve the producer-consumer problem. Tanenbaum names them as follows:

Semaphore "full" keeps track of the number of slots in the buffer that are occupied;
Semaphore "empty" keeps track of the number of slots in the buffer that are free; and
Semaphore "mutual exclusion"--a.k.a. "mutex"--guarantees that processes P and C do not ever access the buffer at the same time. Semaphores of this kind are also referred to as "binary semaphores".

Initially, full's value is 0, and empty's value is equal to the total number of slots in the buffer. Mutex's value is 1, representing that no process is accessing the buffer. Whenever a process is about to access the buffer--hence entering the critical section--, it must first down() mutex.

Let's examine how full works. Whenever the consumer is about to retrieve data from the buffer, it calls down() on full. If the value of full is 0--meaning the buffer is empty--, this results in the consumer going to sleep on full, preventing it from proceeding while the buffer is empty. Whenever the producer calls up() on full--which happens when the producer exits the critical section, after putting data into the buffer--, the system wakes the consumer up and allows it to complete its down() operation. On the other hand, if the value of full is greater than 0, this results in the consumer being allowed to enter the critical section, accessing the buffer--which in turn is protected by mutex, as described below.

Conversely, empty works as follows: whenever the producer is about to put data into the buffer, it calls down() on empty. If the value of empty is 0, meaning there are no empty slots--i.e. the buffer is full--, this results in the producer going to sleep on empty, preventing it from proceeding while the buffer is full. Whenever the consumer calls up() on empty--which happens when the consumer exits the critical section, after retrieving data from the buffer--, the system wakes the producer up and allows it to complete its down() operation. On the other hand, if the value of empty is greater than 0, this results in the producer being allowed to enter the critical section, accessing the buffer--which in turn is protected by mutex, as described below.

Now, let's examine what happens when either process is about to enter the critical section and the other process is not inside of it. It's quite simple: the process calls down() on mutex, whose value becomes 0, effectively locking the critical section and allowing the process to access the buffer safely. Before it exits the critical section, it must call up() on mutex, restoring its value to 1, thus unlocking the critical section. Now, what happens when a process wants to enter the critical section, but the other process is inside of it? It calls down() on mutex. down() verifies that the value of mutex is already 0, which makes the process sleep on mutex. This results in mutex preventing concurrent accesses to the buffer, thus serializing critical section access.

The paragraphs above might be rather convoluted, and perhaps the best way to understand the solution they describe is to revisit them a couple of times while looking at the implementation's pseudocode with pen and paper at hand. The pseudocode below, adapted from Tanenbaum's text, presents the solution described above. If you're interested, I've also written a user space C program implementing Tanenbaum's solution for the producer-consumer problem.

semaphore mutex = 1;
semaphore empty = N; // N is the number of slots in the buffer
semaphore full = 0;

void producer()
{
    while(1) {
        down(&empty);
        down(&mutex);
        put_data(/* Data */);
        up(&mutex);
        up(&full);
    }
}

void consumer()
{
    while(1) {
        down(&full);
        down(&mutex);
        retrieve_data(&/* Data */);
        up(&mutex);
        up(&empty);
    }
}

Now that we've established an intuition about semaphores, we can finally look at some of the kernel's concrete lock implementations. The first type of lock that we'll delve into is the mutex, and it surely helps that we've just visited Tanenbaum's theoretical development on its inner workings by looking at the producer-consumer problem.

The mutex

In his text Generic Mutex Subsystem in the kernel docs, kernel maintainer Ingo Molnar defines mutexes as follows:

"In the Linux kernel, mutexes refer to a particular locking primitive that enforces serialization on shared memory systems, and not only to the generic term referring to "mutual exclusion" found in academia or similar theoretical text books. Mutexes are sleeping locks which behave similarly to binary semaphores, and were introduced in 2006 as an alternative to these."

If you're interested, I've programmed a proof of concept kernel module to demonstrate mutex utilization, including a forced race condition, but it's easy to summarize basic mutex usage in pseudocode as follows:

/* ... */

#include <linux/mutex.h> // Defines the mutex kernel API

/* ... */

DEFINE_MUTEX(/* Mutex name */); // DEFINE_MUTEX() defines and initializes an instance of mutex

/* ... */

mutex_lock(&/* Mutex name */); // Locks the critical section

/* Critical section */

mutex_unlock(&/* Mutex name */); // Unlocks the critical section

/* ... */

As much as things might look rather straightforward, here's what kernel development has really taught me so far: if you understand something, you haven't looked hard enough yet--look again. The truth is all sorts of caveats apply here. Here's a few that I've been able to map so far.

First, let us remember that after a thread succeeds at acquiring ownership of a mutex, further attempts to acquire it will block, which theoretically--as we've seen from studying Tanenbaum's text--should result in the blocked thread being put to sleep. The Linux kernel's implementation of mutex differs a bit from textbook material, though. Blocking results in the possibility--called the "slow path"--that blocked threads are put to sleep until the thread that owns the mutex exits the critical section and unlocks it, when the mutex becomes available again. This is the reason why Ingo Molnar refers to mutexes as "sleeping locks" in his text. But mind the word possibility here.

One alternative to the slow path, that happens when there are no threads whose priority is higher than that of the candidate thread ready to acquire the lock and enter the critical section, is the "mid path". This path to lock acquisition is based on the heuristic that the owner thread should release the lock soon, which justifies avoiding the slow path that would result in putting the candidate thread to sleep. When the mid path happens, the candidate thread enters a state in which it is said to "spin for lock acquisition"--what this entails will become clearer soon, when we delve into the topic of spinlocks. The performance gain that the mid path introduces in mutex implementation is very clear. As Ingo Molnar puts it in the aforementioned kernel docs text:

"By simply not interrupting a task and busy-waiting for a few cycles instead of immediately sleeping, the performance of this lock has been seen to significantly improve a number of workloads."

With all that said, it's easy to understand why Billimoria's text is emphatic about the fact that mutexes should only ever be used in scenarios where sleeping while waiting for lock release is possible. A consequence of that behavior is that mutexes introduce the potential need to fully switch the context of blocked threads off the processor and switch them back onto the processor after the mutex unlocks, which is inherently expensive.

Mutexes also fall short in efficiency with regards to their size, as they are among some of the largest locks in the kernel API, leading to more significant caching and memory footprints if compared to other locking mechanisms.

Despite their drawbacks, mutexes are still the default locking primitive for good reason. Ingo Molnar's guidance is clear:

"Unless the strict semantics of mutexes are unsuitable and/or the critical region prevents the lock from being shared, always prefer them to any other locking primitive."

Which means kernel newbies like myself can rest assured that mutexes are likely the locking mechanism of choice, unless the specific situation simply has special requirements that mutexes can't handle--e.g. because serialization is not necessary and would actually hurt performance, or because the critical section wouldn't allow multiple accesses anyway.

Having explored the mutex lock, let's now look at the next concrete implementation of lock in the Linux kernel API: the spinlock.

The spinlock

The spinlock is based on the concept of "spinning", which means having a thread "spin" for lock acquisition until it succeeds. In other words, using the spinlock means we'll have a thread perform busy waiting for the lock, essentially polling for it. Hence, differently from the mutex, the thread never sleeps, which makes the spinlock usable in contexts where sleeping is not an option.

Before we continue, in order to illustrate this concept, let's take a look at another theoretical excerpt of Tanenbaum's text where he defines an instruction called "Test and Set Lock", or TSL. TSL is an atomic instruction that reads the value of a shared variable, then sets its value to 1, while storing its previous value in a register. Since TSL is atomic, it can be leveraged to implement spinning for lock acquisition. Suppose that we have a variable--e.g. lock--which is used to protect the critical section of a program. When lock == 0, any thread can spin for lock acquisition and evetually succeed at acquiring it. When lock == 1, it means there's a thread actively accessing the critical section, and no other thread should be allowed to enter it. When a thread exits the critical section, it's expected to actively set the value of lock back to 0. The assembly pseudocode snippet below shows Tanenbaum's theoretical implementation of a spinlock leveraging the TSL instruction:

enter_crit_sec:
    tsl reg, lock ; Reads the value of lock to register, while setting the value of lock to 1
    cmp reg, #0 ; Checks to see if register == 0--i.e. if the previous value of lock was 0
    jne enter_crit_sec ; If the previous comparison failed--i.e. register != 0 => spin
    ret

leave_crit_sec:
    move lock, #0 ; Set the value of lock back to 0
    ret

The code snippet above makes it easy to see why it is said that busy waiting wastes processor time: whenever cmp reg, #0 fails, the code jumps back to enter_crit_sec, leading to the lock acquisition logic executing all over again, until it succeeds and the thread is allowed to enter the critical section. In fact, due to this very drawback, spinlocks should only ever be used in very short critical sections of the order of microseconds.

Having understood the fundamental concepts behind spinlocks, we can now get back to the kernel's implementation. We can summarize basic spinlock usage in pseudocode as follows:

/* ... */

#include <linux/spinlock.h> // Defines the spinlock kernel API

/* ... */

DEFINE_SPINLOCK(/* Spinlock name */); // DEFINE_SPINLOCK() defines and initializes an instance of spinlock

/* ... */

spin_lock(&/* Spinlock name */); // Locks the critical section--spinning for lock acquisition

/* Critical section */

spin_unlock(&/* Spinlock name */); // Unlocks the critical section

/* ... */

Instead of looking at a proof of concept implementation of spinlock usage, let's look at an excerpt of the AppArmor LSM that actively uses the spinlock API. That will allow us to unveil a very interesting aspect of the API while studying a real use case. Before delving into the analysis, one should know that AppArmor applies a caching strategy comprising of local per-CPU caches and a global cache shared across all CPUs. That strategy allows AppArmor to increase performance by minimizing taking code paths that would result in busy waiting for access to the global cache.

As much as a detailed look at the internals of such mechanism is out of the scope of this blog post, function aa_get_buffer(), defined in AppArmor's lsm.c, provides a rather interesting perspective to the spinlock API. Particularly, it illustrates the combined usage of spin_lock() and spin_trylock().

The spin_trylock() API tries to acquire a given lock, returning non-zero if it succeeds, and 0 otherwise. As we've seen, the spin_lock() API makes the thread spin for lock acquisition, effectively making it enter a state of busy waiting, thus wasting processor time. Because the spin_trylock() API does not necessarily result in entering busy waiting on failure, it allows the thread to do something else in case acquiring the lock fails.

The relevant portions of the aa_get_buffer() function are shown below, with my analysis included as inline comments:

char *aa_get_buffer(/* ... */)
{
    /* ... */

    /* 
     * **OMITTED**: first, the function tries the fast path 
     * without any locking, which would result in returning
     * a buffer from the local cache. This is always safe
     * because each CPU has its own instance of local cache.
     */

    /* ... */

    /*
     * If the above fails...
     */

    /*
     * Try to acquire the global cache lock:
     */
    if (!spin_trylock(&aa_buffers_lock)) {

        /* If the above fails, handle cache contention... */

        /* ... */

        /* ... then fallback to spinning for lock acquisition: */
        spin_lock(&aa_buffers_lock);
    }
retry:
    /*
     * At this point, it is important to realize that the lock has
     * necessarily been acquired, either by spin_trylock() or by
     * spin_lock() above. Next, check if a buffer can be taken from the
     * global cache. Supposing that the function has been called from
     * a non-atomic context (which would introduce further complexity),
     * this should only be allowed if the number of buffers cached
     * globally (buffer_count) is greater than the number of buffers
     * that should always be cached globally (reserve_count).
     */
    if (buffer_count > reserve_count || /* ... */ ) {

        /*
         * If the condition above holds, take a buffer from the
         * global cache, perform additional caching logic and...
         */

         /* ... */

        /* ... unlock the global cache... */
        spin_unlock(&aa_buffers_lock);
        return aa_buf->buffer; // ... before returning said buffer.
    }

    /* **OMITTED**: atomic context logic.  */

    /* ... */

    /* 
     * If buffer_count <= reserve_count, then this means that 
     * no buffer has been returned yet. First, release the lock:
     */
    spin_unlock(&aa_buffers_lock);

    /* **OMITTED**: atomic context logic.  */

    /* ... */

    /*
     * Since no locks are being held, it is now safe to allocate
     * memory for a new buffer:
     */
    aa_buf = kmalloc(aa_g_path_max, /* ... */);
    if (!aa_buf) { // If the allocation fails...
        if (try_again) {
            try_again = false;
            spin_lock(&aa_buffers_lock); // ... spin for the lock again...
            /*
             * ... and try once more. This seems to handle a race condition
             * between the time buffer availability has been checked--i.e.
             * buffer_count > reserve_count and buffer allocation:
             */
            goto retry;
        }
        pr_warn_once("AppArmor: Failed to allocate a memory buffer.\n");
        return NULL;
    }
    return aa_buf->buffer;
}

Hopefully, the case study above provided some insight into the nuances involved in using the spinlock API, and served the purpose of shedding light on the fact that as much as basic usage is rather straightforward, just as for the mutex API, there's a lot more to the spinlock API.

In that sense, it seems relevant to further stress the important caveat--which the snippet above makes very clear--that spinlocks should not be held across sleeping calls such as kmalloc(). In fact, trying to sleep while holding a spinlock results in an error. Billimoria shows an instance of this bug in his text, but I wanted to cause this error myself to actually see what happened in my development box, and I ended up programming yet another proof of concept in C to simulate the situation where a buggy module tries to hold a spinlock across a sleeping call. Here's the error message that showed up in dmesg after running it:

The error log says that the module tried "scheduling while atomic". If we follow the call trace that led to the error, we'll be able to make a bit more of sense out of it:

We see that our work() function called msleep()--ssleep() is a wrapper to msleep(), so the beginning of the call trace makes sense. In turn, msleep() calls schedule_timeout(), which finally calls schedule(), leading to the error. Ultimately, the trouble seems to be that the call sequence after ssleep() ends up resorting to the scheduler subsystem to make the thread sleep until the specified time has elapsed, which is simply not allowed due to the fact that the spinlock is held. In fact, that claim finds support in the explanation that kernel maintainer Jonathan Corbet gave about that matter in his article Atomic context and kernel API design in LWN.net:

"Kernel code generally runs in one of two fundamental contexts. Process context reigns when the kernel is running directly on behalf of a (usually) user-space process; the code which implements system calls is one example. When the kernel is running in process context, it is allowed to go to sleep if necessary. But when the kernel is running in atomic context, things like sleeping are not allowed. Code which handles hardware and software interrupts is one obvious example of atomic context.

There is more to it than that, though: any kernel function moves into atomic context the moment it acquires a spinlock. Given the way spinlocks are implemented, going to sleep while holding one would be a fatal error; if some other kernel function tried to acquire the same lock, the system would almost certainly deadlock forever."

That explains why the kernel treated and logged the excerpt as a bug. While the consequences in lab environment were mild, in real life, sleeping while a spinlock is held could lead to really drastic outcomes.

At this point, we have already built an initial working understanding of the most prominent kernel synchronization mechanisms, namely mutexes and spinlocks. Before wrapping up the discussion herein, let's turn our attention to what's perhaps the most insidious synchronization bug: the deadlock.

A few words on deadlocks

In this section, we'll try to reach an understanding of what deadlocks are by looking at Tanenbaum's text on the subject. Then, we'll try to understand how to prevent them in practice by looking at several kernel documentation resources that address the issue of deadlocks.

Tanenbaum defines a deadlock as a situation involving a set of processes where each process in the set is waiting for an event that can only be triggered by another process in the set. The figure below illustrates the issue:

In the figure, process 1 is waiting for process 2 to trigger some event. In turn, process 2 is also waiting for process 1 to trigger some event. This leads to a situation where both processes are unable to proceed due to depending on the other, configuring a deadlock. As much as the figure illustrates a situation consisting of a deadlock between two processes, more complex scenarios called "deadly embraces" comprising of multiple processes and/or locks might emerge--as explained by kernel hacker and ex-maintainer Rusty Russell in his Unreliable Guide To Locking.

Tanenbaum's text also presents Coffman's conditions, which resulted from the work of Edward Coffman published in 1971. These four conditions must all be simultaneously satisfied for a deadlock to occur:

Mutual exclusion--i.e. each resource can only be held by one process at a time;
Resource holding--i.e. each process is holding at least one resource and requesting to hold resources that are being held by other proceses;
No preemption--i.e. each process must voluntarily release the resource that it is holding; and
Circular wait--i.e. there must be a circular chain of processes waiting for resources that are being held by the next processes in the chain.

If all of Coffman's conditions are satisfied simultaneously, then there's a deadlock. If at least one of Coffman's conditions is not satisfied, then there's no deadlock.

Coffman's work was fundamental in developing deadlock prevention and recovery algorithms, and Tanenbaum's text is very thorough about the subject. In this blog post, though, I'll try to be a bit more pragmatic and explore the concrete guidelines that apply to deadlock prevention in the specific context of Linux kernel development. Nevertheless, Coffman's conditions provide rather useful guidance--especially to kernel newbies like myself--on what to aim for while developing and what to look for while debugging potential deadlocks.

That said, some general guidelines apply to deadlock prevention in the Linux kernel. First, lock ordering is very important, meaning locks should always be acquired in the same order across all threads. But why is that? This article provides a rather convincing counterexample, which I reproduce--adapted--here: suppose two threads, thread 1 and thread 2, must acquire locks eeny, meeny, miny, and moe. Thread 1 acquires locks eeny, meeny, and miny, then tries to acquire lock moe, but it blocks, because thread 2 had already acquired it. In the meantime, thread 2 acquires lock moe, then tries to acquire lock eeny, but it blocks, because thread 1 had already acquired it. Now, thread 1 is waiting for thread 2 to release lock moe, and thread 2 is waiting for thread 1 to release lock eeny: a deadlock. More specifically, a deadly embrace. If both threads tried to acquire the locks in the same order, this situation wouldn't have happened.

As much as the recommendation above seems to appear frequently in kernel deadlock prevention materials, Rusty Russell has a more pragmatic view on lock ordering, and I quote, from section 7.2. Preventing Deadlock in Unreliable Guide To Locking

"Textbooks will tell you that if you always lock in the same order, you will never get this kind of deadlock. Practice will tell you that this approach doesn't scale: when I create a new lock, I don't understand enough of the kernel to figure out where in the 5000 lock hierarchy it will fit."

That said, he goes on to provide a rule of thumb to guide lock development:

"The best locks are encapsulated: they never get exposed in headers, and are never held around calls to non-trivial functions outside the same file. You can read through this code and see that it will never deadlock, because it never tries to grab another lock while it has that one. People using your code don't even need to know you are using a lock."

That is also the view kernel maintainer Jonathan Corbet expressed in his article The kernel lock validator in LWN.net:

"[...] kernel developers try to define rules for the order in which locks should be acquired. But, in a system with many thousands of locks, defining a comprehensive set of rules is challenging at best, and enforcing them is even harder."

Thus, one should aim at simplicity with regards to locking. Locking mechanisms are already complex in themselves, and the simpler one is able to keep lock design, the better.

Several other aspects to be aware of in lock design include paying attention to the possibility of starvation--i.e. having a process wait indefinitely for a lock simply because the process holding it never releases it--, and trying to acquire the same lock a second time while still holding it, thus leading to a type of deadlock called "self-deadlock".

Finally, one should be aware of the Lockdep subsystem. Lockdep is a subsystem that is targetet at performing lock validation. It is enabled by configuration option CONFIG_PROVE_LOCKING, and it works by tracking lock classes in runtime, keeping a lock dependency graph in memory that is updated every time a lock is acquired. Whenever a buggy lock dependency is observed, Lockdep issues a warning message. I compiled a kernel for my development box with CONFIG_PROVE_LOCKING=y--while keeping default values to other Lockdep configuration options--to see what actual Lockdep messages look like, and after reinstalling the kernel and rerunning my buggy spinlock proof of concept against it, apart from the subsystem's data interface at /proc/lockdep*, I saw new log lines in dmesg, demonstrating that the subsystem was up and actively monitoring acquired locks in runtime:

The trouble with Lockdep is that it introduces non-negligible performance overheads, thus it should only be used for development/testing purposes, while remaining deactivated in production kernels. Nevertheless, it is surely an interesting tool to be aware of as it provides powerful practical validation to the rather complex exercise of developing adequate kernel locking.

Conclusion and where to go from here

In this blog post, we explored the issues associated with multithreading, defining data races and critical sections, then we moved on to establishing an intuition about the theoretical aspects of locks, and discussed the most prominent locks in the Linux kernel, namely mutexes and spinlocks. We looked at their use cases and drawbacks. Finally, we briefly discussed the topic of deadlocks.

To conclude, despite its length, I must stress that this blog post only provided an introductory discussion to the topic of kernel synchronization. There is much more to discuss regarding this topic, but for now, I'm satisfied. I feel that the last couple of weeks of delving into kernel synchronization have armed me with much stronger tools to perform kernel work involving locking primitives.

The next steps in my systems programming journey will probably be getting back to my LSM studies--I've got a very decent continuation idea in mind for part II of my blog post on LSM internals--, and looking at the memory management subsystem. While I'm at it, I'll also probaly consolidate a project idea in which I've been working for my PhD, and certainly look for further opportunities to contribute to upstream, which I haven't done in a while to concentrate on studying synchronization.

Happy hacking.

Study notes on the Linux Security Module (LSM) kernel framework--Part 1

2026-06-03T00:00:00-03:00

My journey in Linux systems programming has been advancing quite well, and during the last month or so, I've been really delving into the Linux Security Module (LSM) kernel framework, in an attempt to get a grasp of its inner workings and to prepare the ground for my studies on specific LSMs later on.

Even though I've been trying to focus on the framework itself, it's inevitable to look at LSM module implementations along the way, and I've been case studying AppArmor. In fact, I found a rather interesting bug in AppArmor's lsm.c along the way and patched it, so my studies resulted in the opportunity to submit a new patch to upstream, with another one in the oven. Another side effect was submitting a pedantic merge request to AppArmor's documentation.

What I realized is that LSM is a topic whose documentation is rather fragmented, and this blog post is an attempt to consolidate what I've learned so far from consuming a rather diverse range of documentation sources and navigating LSM sources in the kernel's codebase.

LSM's debut

In their paper Linux Security Module Framework, early LSM developers report that back in the 2001 Linux Kernel Summit, NSA presented their work in SELinux. Linus Torvalds accepted the need for an access control framework in the kernel, but he preferred to have security modules implemented as loadable kernel modules that could be easily exchanged, while remaining simple, efficient, and non-intrusive.

Major vs. minor LSM modules

The LSM framework distinguishes between two categories of LSM modules, namely major and minor. Major LSM modules implement full Mandatory Access Control (MAC) and are mutually exclusive, meaning one cannot run two major LSM modules at once--such as AppArmor and SELinux, for instance. In turn, minor LSM modules implement specific security features and can be stacked on top of each other.

Ordinary systems usually run one major LSM and a several minor ones. Loaded LSM modules can be listed by issuing:

cat /sys/kernel/security/lsm

Basic design

LSM was designed in such a way as to remain agnostic to the different approaches to access control that security modules implement. In order to achieve this, the LSM mediates access to the kernel's internal objects by interfacing with loaded LSM modules. The diagram below, extracted from the aforementioned Linux Security Module Framework paper, illustrates this concept.

The diagram shows that whenever a process in user space executes a syscall, it passes through the existing kernel logic, including DAC. Just before accessing the object that is the intended target of the syscall, an LSM hook makes a call to the LSM module asking whether it allows the access to proceed. In turn, the module responds either allowing or denying access to the object.

LSM hook definitions

Based on that description, it is easy to notice that hooks constitute a core element in the design of the LSM framework. In fact, an important component of the LSM is precisely the definition of its hook interface at include/linux/lsm_hook_defs.h.

For each hook, lsm_hook_defs.h invokes the macro LSM_HOOK, specifying the hook's return type, default value, name, and argument list. Take the following line, for instance:

LSM_HOOK(int, 0, file_open, struct file *file)

Here, LSM_HOOK defines hook file_open, whose return type is int with default value 0, and whose only argument is a pointer to struct file.

The static calls table

WARNING: things might get rather convoluted from this point onwards, but there's no way around it, really.

Each hook in lsm_hook_defs.h is added to a static calls table defined in security/security.c.

security.c includes include/linux/lsm_hooks.h (here), which in turn includes the aforementioned lsm_hook_defs.h, right at the definition of struct lsm_static_calls_table:

struct lsm_static_calls_table {
    #define LSM_HOOK(RET, DEFAULT, NAME, ...) \
        struct lsm_static_call NAME[MAX_LSM_COUNT];
    #include <linux/lsm_hook_defs.h>
    #undef LSM_HOOK
} __packed __randomize_layout;

We'll get back to that struct in a minute, but first, let's take a look at its realization in security.c:

struct lsm_static_calls_table
    static_calls_table __ro_after_init __aligned(sizeof(u64)) = {
#define INIT_LSM_STATIC_CALL(NUM, NAME)                 \
    (struct lsm_static_call) {                  \
        .key = &STATIC_CALL_KEY(LSM_STATIC_CALL(NAME, NUM)),    \
        .trampoline = LSM_HOOK_TRAMP(NAME, NUM),        \
        .active = &SECURITY_HOOK_ACTIVE_KEY(NAME, NUM),     \
    },
#define LSM_HOOK(RET, DEFAULT, NAME, ...)               \
    .NAME = {                           \
        LSM_DEFINE_UNROLL(INIT_LSM_STATIC_CALL, NAME)       \
    },
#include <linux/lsm_hook_defs.h>
#undef LSM_HOOK
#undef INIT_LSM_STATIC_CALL
    };

Now, the code above is certainly hard to grasp at first glance. In order to understand what on Earth is going on here, one needs to break it down and look at it one piece at a time.

As we've already seen, static_calls_table is of type struct lsm_static_calls_table, and the very first #define directive in that type expands each aforementioned LSM_HOOK from lsm_hook_defs.h into an array of struct lsm_static_call of size MAX_LSM_COUNT. Let's take a look at type struct lsm_static_call:

struct lsm_static_call {
    struct static_call_key *key;
    void *trampoline;
    struct security_hook_list *hl;
    struct static_key_false *active;
} __randomize_layout;

At this point in our introspection, we see that struct lsm_static_call is composed of:

A pointer to a static call key, which in turn essentially points to a target function (see include/linux/static_call_types.h for detail);
A pointer to what's called the trampoline function--i.e. an assembly function that provides a way of calling the function pointed to by the static call key, respecting architecture-specific calling conventions;
A pointer to the hook list to which this static call belongs, which in turn maps directly to a specific LSM (see include/linux/lsm_hooks.h for detail); and
A pointer to a struct that tracks whether the static call is active or not--i.e. whether it's been activated by the LSM to which it belongs (see include/linux/jump_label.h for detail).

Finally annotation __randomize_layout serves the purpose of randomizing the struct's layout for security.

After establishing this intuition about struct lsm_static_call, we can go back to lsm_static_calls_table. I've repeated the corresponding code below for convenience:

struct lsm_static_calls_table {
    #define LSM_HOOK(RET, DEFAULT, NAME, ...) \
        struct lsm_static_call NAME[MAX_LSM_COUNT];
    #include <linux/lsm_hook_defs.h>
    #undef LSM_HOOK
} __packed __randomize_layout;

So essentially, if the hooks in lsm_hook_defs.h were named "eeny", "meeny", "miny", and "moe", struct lsm_static_calls_table would expand into something like:

struct lsm_static_calls_table {
    struct lsm_static_call eeny[MAX_LSM_COUNT],
    struct lsm_static_call meeny[MAX_LSM_COUNT],
    struct lsm_static_call miny[MAX_LSM_COUNT],
    struct lsm_static_call moe[MAX_LSM_COUNT]
}

Hence, each hook names a static calls array. With that in mind, let's get back to the realization of struct lsm_static_calls_table in security.c--also repeated below for convenience--, and analyze what code the preprocessor actually generates:

struct lsm_static_calls_table
    static_calls_table __ro_after_init __aligned(sizeof(u64)) = {
#define INIT_LSM_STATIC_CALL(NUM, NAME)                 \
    (struct lsm_static_call) {                  \
        .key = &STATIC_CALL_KEY(LSM_STATIC_CALL(NAME, NUM)),    \
        .trampoline = LSM_HOOK_TRAMP(NAME, NUM),        \
        .active = &SECURITY_HOOK_ACTIVE_KEY(NAME, NUM),     \
    },
#define LSM_HOOK(RET, DEFAULT, NAME, ...)               \
    .NAME = {                           \
        LSM_DEFINE_UNROLL(INIT_LSM_STATIC_CALL, NAME)       \
    },
#include <linux/lsm_hook_defs.h>
#undef LSM_HOOK
#undef INIT_LSM_STATIC_CALL
    };

Here, __ro_after_init is a kernel self-protection annotation that serves the purpose of marking static_calls_table as read only after initialization, meaning that it will live in the kernel's read only data section at .ro-data instead of .data, benefiting from the kernel's strict memory permissions and preventing the struct from being written, resulting in potential tampering with LSM execution flow. In turn, __aligned(sizeof(u64)) serves the purpose of preventing unaligned access to the table, which may result in faults in some architectures.

The second #define directive expands the hooks defined in lsm_hook_defs.h to initialize the static calls array for each hook. It leverages another code generation mechanism to do that, namely LSM_DEFINE_UNROLL. Here's its definition:

#define LSM_DEFINE_UNROLL(M, ...) UNROLL(MAX_LSM_COUNT, M, __VA_ARGS__)

Now, what that macro does is it takes macro M and expands it MAX_LSM_COUNT times. Combining that with the first #define directive that defines INIT_LSM_STATIC_CALL means that each hook "eeny" in lsm_hook_defs.h, will expand into an array like:

.eeny {
    struct lsm_static_call { /* ... */ }, /* 0 */
    struct lsm_static_call { /* ... */ }, /* 1 */
    ...
    struct lsm_static_call { /* ... */ } /* MAX_LSM_COUNT - 1 */
}

Of course, each struct lsm_static_call is populated accordingly, and it shall have its fields updated at kernel initialization later on, when each LSM module has the opportunity to register its hooks. The following section documents this process.

Hook registration

If we look at LSM initialization at security_init(), we'll find the following code:

int __init security_init(void)
{

    /* ... */

    cnt = 0;
    lsm_order_for_each(lsm) {
        /* skip the "early" LSMs as they have already been setup */
        if (cnt++ < lsm_count_early)
            continue;
        lsm_init_single(*lsm);
    }

    return 0;
}

And if we step into lsm_init_single():

static void __init lsm_init_single(struct lsm_info *lsm)
{
    /* ... */

    ret = lsm->init();

    /* ... */
}

So, what's happening here is that the kernel is calling each LSM's init() function in order to initialize it.

Next, we'll try to understand what exactly the init() function of an LSM module does in order to register hooks, by looking at AppArmor's initialization.

LSM initialization: a case study of AppArmor

AppArmor's initialization is at security/apparmor/lsm.c. Here's what we'll find more or less half way through the module's init function:

static int __init apparmor_init(void)
{
    /* ... */

    security_add_hooks(apparmor_hooks, ARRAY_SIZE(apparmor_hooks),
                &apparmor_lsmid);

    /* ... */
}

The function calls security_add_hooks(), providing apparmor_hooks--AppArmor's hook list--, along with the size of said hook list and AppArmor's LSM ID.

apparmor_hooks is defined as:

static struct security_hook_list apparmor_hooks[] __ro_after_init = {
    LSM_HOOK_INIT(ptrace_access_check, apparmor_ptrace_access_check),
    LSM_HOOK_INIT(ptrace_traceme, apparmor_ptrace_traceme),
    LSM_HOOK_INIT(capget, apparmor_capget),
    LSM_HOOK_INIT(capable, apparmor_capable),

    LSM_HOOK_INIT(move_mount, apparmor_move_mount),
    LSM_HOOK_INIT(sb_mount, apparmor_sb_mount),
    LSM_HOOK_INIT(sb_umount, apparmor_sb_umount),
    LSM_HOOK_INIT(sb_pivotroot, apparmor_sb_pivotroot),

    /* ... */

Which translates to an array of mappings of type struct security_hook_list, each mapping an LSM hook to an AppArmor implementation of that hook. The definition of struct security_hook_list is as follows:

struct security_hook_list {
    struct lsm_static_call *scalls;
    union security_list_options hook;
    const struct lsm_id *lsmid;
} __randomize_layout;

The struct contains a list of static calls as scalls--you might want to revisit the definition of struct lsm_static_call--, a union of type union security_list_options, and a pointer to the LSM's ID.

If we introspect into security_list_options, here's what we'll find:

union security_list_options {
    #define LSM_HOOK(RET, DEFAULT, NAME, ...) RET (*NAME)(__VA_ARGS__);
    #include "lsm_hook_defs.h"
    #undef LSM_HOOK
    void *lsm_func_addr;
};

Thus, the union expands the definitions of LSM_HOOK from lsm_hook_defs.h into a list of function pointers to each LSM hook. In turn, macro LSM_HOOK_INIT translates to:

#define LSM_HOOK_INIT(NAME, HOOK)           \
    {                       \
        .scalls = static_calls_table.NAME,  \
        .hook = { .NAME = HOOK }        \
    }

Namely, it initializes struct security_hook_list.scalls with a pointer to the array in static_calls_table that corresponds to the LSM hook, and struct security_hook_list.security_list_options.hook's field corresponding to the name of the given LSM hook with a pointer to AppArmor's implementation of the hook.

Putting it all together, this results in apparmor_hooks expanding into something like:

apparmor_hooks = {
    struct security_hook_list {
        .scalls = static_calls_table.lsm_hook_0,
        .hook = { .lsm_hook_0 = .apparmor_hook_0 },
        .lsmid = /* ... */
    },
    struct security_hook_list {
        .scalls = static_calls_table.lsm_hook_1,
        .hook = { .lsm_hook_1 = .apparmor_hook_1 },
        .lsmid = /* ... */
    },

    /* ... */
}

Hence, each slot in apparmor_hooks keeps a reference to a specific LSM hook's array in static_calls_table, along with the mapping of said LSM hook to AppArmor's implementation.

The final steps of hook registration

After looking at AppArmor's initialization to understand what the data structure provided as an argument to security_add_hooks() looks like, we can resume our analysis of LSM hook registration by finally stepping into that function:

void __init security_add_hooks(struct security_hook_list *hooks, int count,
                   const struct lsm_id *lsmid)
{
    int i;

    for (i = 0; i < count; i++) {
        hooks[i].lsmid = lsmid;
        if (lsm_static_call_init(&hooks[i]))
            panic("exhausted LSM callback slots with LSM %s\n",
                  lsmid->name);
    }
}

We see that security_add_hooks iterates through the security hook list initializing the static calls of the given LSM, which if you'll remember were supposed to be updated at kernel initialization--i.e. precisely where we are at this point.

Let's get deeper into our introspection and step into lsm_static_call_init():

static int __init lsm_static_call_init(struct security_hook_list *hl)
{
    struct lsm_static_call *scall = hl->scalls;
    int i;

    for (i = 0; i < MAX_LSM_COUNT; i++) {
        /* Update the first static call that is not used yet */
        if (!scall->hl) {
            __static_call_update(scall->key, scall->trampoline,
                         hl->hook.lsm_func_addr);
            scall->hl = hl;
            static_branch_enable(scall->active);
            return 0;
        }
        scall++;
    }

    return -ENOSPC;
}

At this stage, the function locates the first empty slot in the static_calls_table array corresponding to the LSM hook being registered, and then updates that slot by associating it with the LSM module's implementation of the hook.

This way, the LSM should be able to query the LSM module that registered that hook for access approval.

Conclusion

Wrapping up this first part of my study notes on LSM, I'll say that I'm happy with what I've learned so far.

I've only scratched the surface of the LSM framework, but the elegantly simple inner workings I've touched so far have already proven to be a masterpiece in software engineering, from its solid design principles to the intricante relationship between its static calls table and its hook registration routines. Every layer of it has deepened my appreciation for Linux.

But again, I've only scratched the surface. There's so much more to learn about LSM, and I still want to go deeper into AppArmor and then SELinux. This rabbit hole goes much deeper than what I initially envisioned, but I'm eager to dive in.

When I post Part 2 of these study notes, I hope to have more kernel patches to share and a much deeper understanding of the LSM to offer.

Happy hacking.

How I became a contributor to the Linux kernel

2026-04-29T20:07:00-03:00

After finishing Linux Foundation's course on kernel development (LFD103), I was feeling ready and eager to make my first contribution to the Linux kernel. The entire process from starting LFD103 and having my first patch accepted into upstream took me two weeks. This post provides insight on what my first patch was about and describes the submission process.

IMPORTANT: the timespan to my first accepted patch was relatively short, but I didn't start from zero: I already had some 15 years or experience with Linux both as a hobby and as a professional tool--including the experience of compiling Linux From Scratch--, considerable programming experience in C, and almost 10 years of experience in security engineering. Due to this background, I was able to go from no experience in kernel development to an accepted patch relatively faster than average, so my debut as a kernel newbie may differ from that of most people.

Patch no. 1

As a first exercise of what I had learned in LFD103, I decided to make a very simple and unrisky contribution to the DRM subsystem, namely fixing a comment. I've prepared a patch and sent it on April 24, 2026. Here's the link to it on the kernel archives:

https://lore.kernel.org/all/20260424140515.2019-1-eduardo@eduardovasconcelos.com/.

There was a typo on a word, and my patch fixed it. After a while, I noticed that I had made a mistake: I had forgotten to apply column limiting both to my commit subject and to my commit message! Kernel contribution guidelines take formatting very seriously, and as much as I knew from browsing lore.kernel.org that mistakes like these might even go unnoticed, I wanted to make sure to follow the entire submission process accordingly, so I decided to submit a second version of my patch.

Patch no. 1 v2

Subsequent versions of patches must follow specific submission guidelines. After fixing some Emacs line wrapping rules to make sure my commit would be formatted accordingly this time--FIY I was a Vim user for more than a decade before converting, but that's another story--, I have prepared and tagged my patch as v2, and sent it the same day, on April 24, 2026:

https://lore.kernel.org/all/20260424183630.3764-1-eduardo@eduardovasconcelos.com/

This process--and the fact that I made a submission mistake and had to send a second version of my patch--gave me a good understanding of the submission process, and made me a lot more confident about it. I felt ready to look for opportunities to contribute with some actual code changes.

Patch no. 2

LFD103 discusses kernel compilation and the patch submission process, but it doesn't teach you about any kernel drivers or subsystems, so submitting patches consisting of substantial changes to kernel code was a no-no.

That's why I decided to look at a simpler driver for a piece of hardware I'm very much passionate about: thinkpad_acpi. This driver is under /drivers/platform/x86/lenovo/thinkpad_acpi.c, and it interfaces with general IBM/Lenovo ThinkPad HW. Among other things, it controls hotkey events, battery charging, LED activation, lid closing events, etc. What's nice about this driver is that since I own two ThinkPads and my wife owns another one, I had plenty of real HW available to test any changes that I made.

So I decided to look for opportunities to submit code improvements to this driver. After some code reviewing, I found one: there was an unneeded goto statement in the hotkey polling routine, namely hotkey_kthread(): the routine had a single exit location, with no cleanup code preceding its return statement, but it still performed a goto jump to its only exit location, introducing unneeded control flow logic in disaccordance with the Linux kernel coding style, that explicitly mandates otherwise.

I refactored the routine's exit, compiled and installed the kernel with the change on my old ThinkPad T420si, and after confirming that everything was working as expected, I submitted the patch on the ungodly hour of 3:40 a.m. on April 25, 2026:

https://lore.kernel.org/all/20260425063936.9360-1-eduardo@eduardovasconcelos.com/

Patch no. 2 accepted

Mark Pearson acknowledged my submission and applied his revision tag to it a few hours later, at 9:49 a.m.:

https://lore.kernel.org/all/16d45e47-8234-4983-84d4-91b66c5a67db@app.fastmail.com/

Patch no. 2 applied

Maintainer Ilpo Järvinen reported that he had applied my patch to his next tree on April 28, 2026:

https://lore.kernel.org/all/177739236303.10973.18101852287173259208.b4-ty@linux.intel.com/

Patch no. 1 accepted

In the meantime, my initial patch to the DRM subsystem had also been reviewed by maintainer Thomas Zimmermann, who applied his revision tag to it:

https://lore.kernel.org/all/23bd7123-f22e-4ab2-b3f0-03833e25bf7d@suse.de/

Next steps

This exercise of submitting a couple of patches gave me an initial grasp at the contribution process. None of the reviewers pointed out any mistakes or inconsistencies on my initial patches, so I assume that I have understood the submission process and the documentation that I read so far sufficiently well. Under such circumstances, I felt ready to transition towards studying the kernel more deeply as a preparation to tackle more substantial contributions.

That is why I have pivoted to studying the Linux kernel architecture and some of its main subsystems. I'm currently working on Kaiwan N. Billimoria's Linux Kernel Programming book--currently doing module development--, and in the near future, I intend to leverage my experience as a security engineer to specialize in kernel security. It feels like a natural path to take. So after I develop an initial broad understanding of the kernel, I intend to narrow down to AppArmor, then pivot to SELinux, and gradually work towards a broader understanding of LSM.

Linux kernel development setup in Arch Linux

2026-04-22T19:00:00-03:00

I've been working on Linux Foundation's kernel development course (LFD103), and I have chosen a virtual Arch box running on QEMU on top of a physical Arch host as my kernel development machine.

LFD103 recommends using either Ubuntu or Debian for course work, but I wanted to use Arch anyway, and--to no surprise--I have found that Arch Linux is not as straightforward to setup as the recommended distros. kernel.org recommends a few dependencies that aren't even packaged for Arch and must be built manually. Furthermore, configuring GRUB to boot a newly compiled kernel is not as straightforward either.

In the end, I have succeeded in compiling a kernel image from upstream and booting it using my Arch setup, but not without having to overcome some hardship first. The post herein aims at documenting this process. It assumes prior knowledge in Arch Linux installation and some knowledge in Linux virtualization and general system administration.

Partitioniong and installation

It's no surprise one must save extra space in /boot to pursue kernel development. LFD103 recommends saving at least 3 GiB. I went with 4 GiB, saved another 4 GiB for swapping, and left 40 GiB for my root filesystem, totalling 48 GiB for my virtual drive.

I opted for a minimal Arch installation, with emacs and openssh as extra packages. I also enabled root and created a sudoer user.

SSH setup

I've then configured an SSH server to allow me to access the development machine from my host system.

Packaged development dependencies

After logging in through SSH and configuring ~/.emacs to suit my preferences, I've proceeded to installing packages needed for development.

IMPORTANT: As much as not all dependencies are necessary on all systems, this post covers the installation of all tools listed under kernel.org's minimal requirements list.

The first step is to install basic development dependencies. LFD103 points to the Ubuntu ones, but these won't do it for Arch. Some Arch dependencies are packaged or named differently, and some others aren't even packaged and must be installed manually from AUR. The installation commands herein are the result of translating suggested Ubuntu dependency installation steps to Arch:

First, one must issue:

sudo pacman -S base-devel git cscope ncurses openssl bison flex

And then:

sudo pacman -S pahole jfsutils xfsprogs squashfs-tools btrfs-progs quota-tools ppp nfs-utils udev grub python3 bc python-sphinx ccache wget

That installs most development dependencies, but one in particular, namely udev, won't work as expected unless we link it to /usr/bin/udevd:

sudo ln -s /lib/systemd/systemd-udevd /usr/bin/udevd

Unpackaged dependencies

Some kernel development dependencies are not packaged for Arch, however they're available on AUR and one may install them from there.

The first one is pcmciautils:

wget https://aur.archlinux.org/cgit/aur.git/snapshot/pcmciautils.tar.gz

After downloading the snapshot, one may proceed to the standard AUR build and installation procedure, but first, we must satisfy yet another build dependency:

sudo pacman -S sysfsutils

Then build and install the AUR package normally.

The next unpackaged dependency we'll need is mcelog:

wget https://aur.archlinux.org/cgit/aur.git/snapshot/mcelog.tar.gz

Standard AUR build and installation procedures should work without any issues.

Checking minimal requirements against kernel.org

At this point, the system should be good to go, but it's a good idea to check minimal requirements against the dependencies in kernel.org to make sure installed versions satisfy the requirements.

If everything is okay, one may proceed to compiling the kernel. This matter exceeds the scope of the post herein, but if all steps above were executed accordingly, one should be able to compile and boot the upstream kernel without any issues. Here's a screenshot of a successful boot with an image I've compiled from linux-stable--7.0.1 as of the time of writing on April 22, 2026:

Happy hacking.

[pt-BR] Compilando Linux From Scratch (LFS)

2026-04-04T18:00:00-03:00

"Playfully doing something difficult, whether useful or not, that is hacking."

-- Richard Stallman, On Hacking

Ao longo das últimas semanas, em detrimento dos devidos sono e asseio, trabalhei, pela primeira vez, na compilação do meu próprio sistema Linux. Usei como guia o livro Linux From Scratch: Version 13.0-systemd, publicado pelo projeto homônimo, Linux From Scratch. Os processos de compilação e configuração básica já estão finalizados. Obtive um sistema LFS plenamente funcional, em dual boot com o host virtual Arch que utilizei para compilá-lo.

Eu uso--e amo--Linux há cerca de 15 anos. Comecei pelo Ubuntu 8.04 LTS "Hardy Heron", em meados de 2010. Desde então, não parei mais: já tive a minha parcela de distro hopping; converti algumas pessoas e ajudei outras tantas a instalarem ou configurarem Linux; instalei e administrei servidores Linux críticos no meu primeiro emprego formal, como sysadmin; venho usando Linux como ferramenta de trabalho há anos, como engenheiro de segurança; e a minha computação pessoal, como não poderia deixar de ser, é completamente baseada em Linux. Atualmente, o meu amado daily driver é um ThinkPad T480--usado--com Arch, btw. No entanto, até hoje, uma das peças faltantes na minha trajetória era compilar o meu próprio sistema Linux. Esse já era um sonho de longa data. Há pouco, ele foi realizado.

Em um primeiro momento, esse exercício pode até parecer algo muito difícil de ser cumprido, mas a verdade é que compilar LFS é muito mais simples do que parece, dada a devida assiduidade no uso de Linux, e o grande "plot twist" é que esse processo serviu para revelar muita, mas muita coisa sobre Linux que eu simplesmente não sei. Vejo que compilar o meu próprio sistema pela primeira vez foi apenas o início da fase de desconstrução em um processo de aprendizado que, estou certo, ainda vai durar muito tempo.

Sem mais delongas, a seguir, relato humildemente como foi a minha experiência de compilar Linux From Scratch.

Para quem é o desafio de compilar Linux From Scratch?

Eu não diria que seria impossível que uma pessoa que tivesse apenas iniciado a sua trajetória com Linux conseguisse compilar o seu próprio sistema Linux com base no Linux From Scratch, mas esse processo seria extremamente demorado, trabalhoso e frustrante, demandaria uma força de vontade e uma paciência muito grandes, e seria possível que o tempo investido nisso fosse mais bem aproveitado se essa pessoa se dedicasse a aprender assuntos mais básicos, adquirindo pelo menos alguns anos de experiência com Linux como daily driver antes de atacar esse projeto.

Não se engane: apesar de o livro ser muito detalhado, ele assume certos conhecimentos a priori, de forma que compilar Linux From Scratch demanda bastante afinidade com o terminal e conhecimento prático sobre particionamento, sistemas de arquivos, permissões e builds a partir de código-fonte, dentre outros assuntos.

O livro deixa muita coisa a cargo do leitor, e eu diria que conhecimento prático de Linux--que me parece que só pode ser adquirido ao longo de um tempo razoável de daily driving--é fundamental para o sucesso de certos procedimentos de compilação e até mesmo de setup. Ter afinidade com virtualização de sistemas Linux, por exemplo, me parece algo particularmente interessante, por simplificar--muito--o setup do host de compilação. Sem falar que colocar o sistema de pé depois da compilação é praticamente por sua conta: o livro fala muito pouco sobre configurações de boot, até porque estas dependem muito do host que você tiver escolhido, do uso ou não de dual boot e/ou das características da máquina em que você for colocar o LFS de pé.

Instalação do host

Eu optei por utilizar uma máquina virtual Arch como host de compilação, usando o QEMU em uma máquina Arch física como virtualizador. O primeiro passo foi criar um disco virtual para o host. Usei o qemu-img para isso:

qemu-img create -f qcow2 arch.qcow2 24G

24 GB me pareceram razoáveis diante da documentação suplementar do LFS sobre particionamento. Em seguida, iniciei a VM com:

qemu-system-x86_64 -cdrom archlinux-2026.03.01-x86_64.iso -boot order=d -drive file=arch.qcow2,format=qcow2 -m 8G

Não cabe cobrir todo o processo de instalação do Arch aqui, mas eu particionei o disco virtual da seguinte forma:

Quanto ao tipo de instalação do Arch, optei por Minimal. Também incluí os pacotes openssh e vim. De uma próxima vez que for compilar LFS, também vou incluir wget e, possivelmente, trocar o Vim pelo Nano, por uma questão de manter a simplicidade. Como constatei depois, as necessidades de edição para compilar LFS são bastante básicas. Além disso, criei um usuário e fiz dele sudoer. Teria sido interessante, ainda, já instalar os pacotes das dependências de compilação do LFS para o host durante a instalação do Arch. Como não fiz isso, precisei instalá-las mais adiante.

Finalizada a instalação, deliguei e reiniciei a VM com:

qemu-system-x86_64 -boot order=d -drive file=arch.qcow2,format=qcow2 -m 8G

Seria interessante já ter utilizado -smp 4 aqui para iniciar o host com 4 processadores. Eu acabei não fazendo isso e precisando desligar a VM para reiniciá-la com essa configuração mais adiante, no meio do processo, o que resultou em ter de refazer parte do setup de compilação no host, conforme a seção 2.3 e o final do capítulo 7 do livro discutem.

Configuração do SSH

Após acessar a VM via VNC, segui com a configuração de SSH para que eu pudesse ter um terminal mais bem servido de features para trabalhar durante a compilação. Eu diria que esse passo é quase imprescindível ao optar por compilar LFS em ambiente virtualizado. Poder colar comandos copiados da versão HTML do livro em uma sessão de SSH entre a sua máquina física e o host de compilação me parece ser a maneira mais segura de seguir os passos do livro, por evitar problemas relacionados a erros de digitação ao reproduzir comandos em um terminal em que você não consegue copiar e colar, além de possíveis inconsistências ao copiar comandos a partir da versão PDF do livro.

No Arch--com o openssh devidamente instalado--, configurar SSH consiste em editar /etc/ssh/sshd_config. É uma boa ideia fazer um backup desse arquivo antes. É preciso descomentar:

Port 22
AddressFamily any
ListenAddress 0.0.0.0
ListenAddress ::

Além de incluir:

AllowUsers <usuário>

Onde <usuário> é o usuário que você criou durante a instalação do Arch. Depois disso, reiniciei o sshd e verifiquei se estava tudo certo com:

sudo systemctl start sshd.service
sudo systemctl status sshd.service

Por fim, configurei o serviço para iniciar automaticamente com:

sudo systemctl enable sshd.service

Feito isso, desliguei e voltei a iniciar o host de compilação, redirecionando a porta 60022 da minha máquina física para a porta 22 da VM:

qemu-system-x86_64 -boot order=d -drive file=arch.qcow2,format=qcow2 -m 8G -nic user,hostfwd=tcp::60022-:22

Com isso, pude conectar à VM usando SSH e trabalhar de maneira muito mais simples. A essa altura, fiz a instalação das dependências previstas na seção 2.2 do livro. Como já mencionei, de uma próxima fez, farei a instalação destas durante a instalação do Arch para poder pular esse passo.

Partição de LFS

Criei um segundo disco virtual de 24 GB com o qemu-img. Em seguida, desliguei e voltei a iniciar a VM, dessa vez com os dois discos:

qemu-system-x86_64 -boot order=d -drive file=arch.qcow2,format=qcow2 -drive file=lfs.qcow2,format=qcow2 -m 8G -nic user,hostfwd=tcp::60022-:22

Pude confirmar que o segundo disco estava disponível com lsblk:

NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
fd0      2:0    1    4K  0 disk 
sda      8:0    0   24G  0 disk 
├─sda1   8:1    0  200M  0 part /boot
├─sda2   8:2    0    2G  0 part 
└─sda3   8:3    0 21.8G  0 part /
sdb      8:16   0   24G  0 disk 
sr0     11:0    1 1024M  0 rom  
zram0  253:0    0    4G  0 disk [SWAP]

O próximo passo foi formatá-lo:

sudo mkfs -v -t ext4 /dev/sdb

Em seguida, pude seguir com a definição de $LFS, a partir da seção 2.6, e seguir as instruções de compilação e configuração, até o começo do capítulo 10. Essa foi a parte mais difícil do processo, em grande medida por ser muito repetitiva, e levei algo como duas semanas para concluí-la, mas é preciso levar em consideração que eu havia iniciado o host com um processador só. A certa altura, eu o reiniciei com 4 processadores para melhorar em alguns pontos percentuais a minha qualidade de vida. Esse tempo poderia ter sido menor se eu o tivesse iniciado com 4 processadores desde o começo. Além disso, eu não me dediquei em tempo integral, mas apenas no tempo livre, especialmente à noite e nos finais de semana. Ademais, como eu executei todos os testes, a compilação de alguns pacotes, como o GCC, foi particularmente demorada.

/etc/fstab

Finalizada a compilação dos pacotes, segui aos últimos passos da instalação. A seção 10.2 discute a criação de /etc/fstab. Dadas as características do meu setup, o meu arquivo ficou assim:

bash-5.3# cat /mnt/lfs/etc/fstab 
# Begin /etc/fstab

# file system  mount-point  type     options             dump  fsck
#                                                              order

/dev/sda1     /boot        ext4     defaults            0     2 
/dev/sdb      /            ext4     defaults            1     1
/dev/sda2     swap         swap     pri=1               0     0

# End /etc/fstab

Compilação e instalação do kernel

A compilação do kernel foi mais simples e, sobretudo, mais rápida do que eu imaginava. Chequei os parâmetros de compilação duas vezes. O processo se deu sem intercorrências e durou menos de uma noite--iniciei a compilação por volta das 20h30 e, às 6h00 do outro dia, ela já havia finalizado. Como o meu plano era manter o LFS em dual boot com o host Arch, montei a partição de boot e copiei a imagem compilada do kernel para ela--no meu caso, a imagem x86_64 vmlinuz-6.18.10-lfs-13.0-systemd:

bash-5.3# ls /boot/vmlinuz-6.18.10-lfs-13.0-systemd 
/boot/vmlinuz-6.18.10-lfs-13.0-systemd

Configuração do GRUB

Finalmente, alterei as configurações do GRUB. Optei por adicionar a entrada de menu do GRUB do LFS no grub.cfg criado pelo próprio Arch, em uma seção destinada especificamente a personalizações. Apesar de ser fácil gerar um novo arquivo de configuração do GRUB com o host Arch caso o original seja corrompido, é uma boa ideia fazer um backup desse arquivo antes de editá-lo:

### BEGIN /etc/grub.d/40_custom ###
# This file provides an easy way to add custom menu entries.  Simply type the
# menu entries you want to add after this comment.  Be careful not to change
# the 'exec tail' line above.

insmod part_msdos
insmod ext2
set root='hd0,msdos1'
set gfxpayload=1024x768x32
menuentry "GNU/Linux, Linux 6.18.10-lfs-13.0-systemd" {
    linux   /vmlinuz-6.18.10-lfs-13.0-systemd root=/dev/sdb ro
}
### END /etc/grub.d/40_custom ###

Note-se que o processo de atualização do GRUB conforme documentado na Wiki do Arch--i.e. usando grub-mkconfig, mesmo com GRUB_DISABLE_OS_PROBER=false--não funciona aqui. É preciso atualizar o GRUB manualmente, conforme o próprio livro previne, no final da seção 10.4.4.

Boot

Após algumas iterações de reescrita do grub.cfg, voilà!

Registro na base de usuários do LFS

Depois de finalmente colocar o sistema de pé, decidi registrar o meu nome na base de usuários do LFS. Sou o usuário número 32222--de quebra, fiquei com um identificador super fácil de lembrar:

E agora?

Eu não poderia estar mais satisfeito. Pus em prática um anseio de longa data. Além disso, não apenas obtive um sistema funcional, mas também aprendi várias coisas e descobri outras tantas que eu ainda preciso aprender sobre Linux.

Isso me leva a concluir que eu preciso refazer esse exercício de compilar LFS. Tão logo tenha acabado de "curtir" a minha primeira instalação e descansado um pouco--este relato pode não deixar transparecer, mas o projeto aqui descrito é bastante cansativo--, vou reiniciar o processo, do zero.

Isso vai me permitir olhar com mais calma e maturidade para alguns aspectos do processo de compilação que ainda não estão completamente claros para mim, em especial a teoria por trás de cross compiling, além de modificar o código de alguns pacotes e experimentar com alguns parâmetros de compilação. Antes, porém, planejo fazer algumas rodadas de experimentação com o sistema funcional que eu já tenho, além de portá-lo para uma máquina física. A vítima vai ser um ThinkPad T420si--usado--velho de guerra.

É isso. Estando o leitor munido do significado de "hacking", enunciado no começo deste relato, eu me despeço:

Happy hacking, and may Linux be with you.