Configuration Directives

This is a documentation of all configuration directives.

global

The following block directives may appear in the unnamed global scope:

Block Description
module See module.
kernel See kernel.
initramfs See initramfs.
build See build.
install See install.

Additionally the following statements may be used:

include_module

include_module <path>

Arguments:

path: The path to the .conf file

Include module definitions from a single file. Path can be absolute, or relative to the current working directory when executing the script. Using absolute paths is recommended, but relative paths can be beneficial when testing different configurations. All module files should end with the .conf extension.

Example:

include_module "/usr/share/autokernel/modules.d/security.conf";

include_module_dir

include_module_dir <path>

Arguments:

path: The path to the directory with .conf files

Include module definitions from all .conf files in the given folder. Path can be absolute or relative.

Example:

include_module_dir "/etc/autokernel/modules.d";

module

module <name> { ... }

Arguments:

name The module name

Defines a new module. Definition order is not important. Modules can be included in other modules to provide a level of encapsulation for different tasks. See Concepts → Modules and Concepts → Pinning symbol values for more information.

Example:

module example {
    use example_dep;

    set EXAMPLE y;
}

if

module :: if <expr> { ... } [else if <expr> { ... }]... [else <expr> { ... }]

Arguments:

expr Expressions

Guards statements with the given expressions.

Example:

module example {
    if X86 {
        # X86 is set
    } else if $env[CC] == "gcc" {
        # env var CC is "gcc"
    }

    if $env[HOSTNAME:""] {
        # env var HOSTNAME is set
    } else {
        # env var HOSTNAME is empty or unset
    }
}

use

module :: use <modules>... [if <cexpr>]

Arguments:

modules A list of modules to include
cexpr Attached condition

Include one or multiple a modules at this point. Referenced modules do not need to be defined before usage, as definition order is not important.

If a module has already been included before, it will be skipped. Modules will be included in the order they are encountered in use statements. Due to skipping, cyclic and duplicate inclusions are impossible. This statement may occurr multiple times.

Example:

module example {
    use foo;
    use other_example module_three;
}

set

module :: [try] set <symbol> [value] [if <cexpr>]

Arguments:

symbol Kernel symbol name, the CONFIG_ prefix is optional but discouraged.
value The new value for the symbol (or y by default)
cexpr Attached condition

Sets the value of a symbol. Omitting the value will default to setting the symbol to y. Prefixing symbol names with CONFIG_ is allowed, but considered bad style.

Valid values for tristate symbols are y (yes), m (as module) and n (no). Symbols are always assigned by string, but restrictions for type conversion apply (e.g. integer symbols will only take valid integers).

Variables can be set to environment variables by using the same syntax as described in Special variables.

If the statement is prefixed with try, it will only be executed if the value is not already pinned, and the assignment will also not cause the value to be pinned. Useful to set a new default value for a symbol but still allowing the user to change it.

Repeated assignments of the same symbol are valid, as long as the same value is assigned each time, or the assignment uses the try set. Conflicts will cause hard errors.

Example:

module example {
    # Enable WIREGUARD if kernel version is at least 5.6
    set WIREGUARD y if $kernel_version >= 5.6;
    # Build KVM as module
    set KVM m;

    # Set a hex symbol
    set MAGIC_SYSRQ_DEFAULT_ENABLE 0x1;
    # Set an integer symbol
    set DEFAULT_MMAP_MIN_ADDR 65536;

    # Set a string symbol
    set DEFAULT_HOSTNAME "my_host";
    # Set to an environment variable, throws an error if unset
    set DEFAULT_HOSTNAME $env[HOSTNAME];
    # Set to an environment variable, or uses the default value if unset
    set DEFAULT_HOSTNAME $env[HOSTNAME:"(none)"];

    # Try to set MODULES, if it isn't pinned already
    try set MODULES n;
}

merge

module :: merge <path> [if <cexpr>]

Arguments:

path The path to the kconf file
cexpr Attached condition

Variables:

Allowed in path. See Common variables.

Merges an external kernel configuration file. This can be a whole .config file or just a collection of random symbol assignments (as it is the case for the defconfig files). All merged values will count as implicit changes (no pinning). They will trigger conflicts if a variable is already pinned.

Warning

Because of the implicit nature, the merge statement should only be used to include default values, and not to externalize parts of the config.

Example:

module example {
    # Merge the x86_64 defconfig file
    merge "{KERNEL_DIR}/arch/x86/configs/x86_64_defconfig";
}

assert

module :: assert <aexpr> [: <quoted_message>] [if <cexpr>]

Arguments:

aexpr Expression to assert
quoted_message An error message to display in case the assertion fails
cexpr Attached condition

Asserts that a given expression evaluates to true, otherwise causes an error and optionally prints the given error message.

Example:

module example {
    # Assert that WIREGUARD is enabled if the kernel version is at least 5.6
    assert $kernel_version >= 5.6 and WIREGUARD :
        "Refusing to compile a 5.6 kernel without wireguard";
}

add_cmdline

module :: add_cmdline <quoted_args>... [if <cexpr>]

Arguments:

quoted_args A list of strings to append to CMDLINE
cexpr Attached condition

Adds the given parameters to the kernel commandline. Quotation is required. This will automatically set the CMDLINE symbol to the resulting string and enable the builtin commandline via CMDLINE_BOOL.

Example:

module example {
    # Adds the two strings to the builtin command line.
    add_cmdline "page_alloc.shuffle=1" "second_param";
}

kernel

kernel { ... }

A block for kernel related options. Multiple appearances of this block will be merged. The kernel block is also a module block. It represents the main module which is included by autokernel.

Example:

kernel {
    use hardening;
    use my_module;
}

initramfs

initramfs { ... }

A block for initramfs related options. Multiple appearances of this block will be merged.

Example:

initramfs {
    enabled true;
    builtin true;
}

enabled

initramfs :: enabled <bool>

Arguments:

bool A boolean value

Default: false

Enables or disables building an initramfs. When using autokernel to build the kernel.

Example:

# Enable the initramfs
enabled true;

builtin

initramfs :: builtin <bool>

Arguments:

bool A boolean value

Default: false

This will determine if the initramfs will be integrated into the kernel. It will cause an automatic second kernel build pass, to first allow the initramfs to include any modules for the newly built kernel, and secondly to pack the initramfs into the kernel. The second build will not require any rebuilds of previously compiled components, and should thus be quick.

Example:

# Use a builtin initramfs
builtin true;

build_command

initramfs :: build_command <exe> [<args>...]

Arguments:

exe The command to execute
args parameters to the command

Default: None

Variables:

Allowed in exe and args.

  • Any of the Common variables

  • {MODULES_PREFIX}

    A directory which contains all installed modules. This means the subdirectory {MODULES_PREFIX}/lib/modules exists and can be used by the initramfs generator to include compiled modules for the new kernel.

  • {INITRAMFS_OUTPUT}

    The desired output file for the initramfs. If your generator doesn’t support this, you can specify an alternate location with build_output.

Specifies the command used to build the initramfs. The resulting initramfs should directly be placed at {INITRAMFS_OUTPUT}. If your generator does not support this, you can fallback to the build_output statement to specify where the finished initramfs will be.

Note

Each string in <args> is a separate argument to the command, and arguments will never be interpreted or split on spaces. If you need more logic here, please execute a wrapper script to do so.

This statement is required, if the initramfs is enabled.

Example:

Building an initramfs with dracut
# You can use a command like this to build an initramfs with dracut
build_command "dracut"
    "--conf"          "/dev/null" # Disables external configuration
    "--confdir"       "/dev/null" # Disables external configuration
    "--kmoddir"       "{MODULES_PREFIX}/lib/modules/{KERNEL_VERSION}"
    "--kver"          "{KERNEL_VERSION}"
    "--no-compress"   # Only if the initramfs is to be integrated into the kernel
    "--no-hostonly"
    "--ro-mnt"
    "--add"           "bash crypt crypt-gpg"
    "--force"         # Overwrite existing files
    "{INITRAMFS_OUTPUT}";
Building an initramfs with genkernel
# You can use a command like this to build an initramfs with genkernel
build_command "genkernel"
    "--module-prefix=${MODULES_PREFIX}"
    "--cachedir=/tmp/genkernel/cache"
    "--tmpdir=/tmp/genkernel"
    "--logfile=/tmp/genkernel/genkernel.log"
    "--kerneldir={KERNEL_DIR}"
    "--no-install"
    "--no-mountboot"
    "--no-compress-initramfs"
    "--no-ramdisk-modules"
    "--luks"
    "--gpg"
    "initramfs";
build_output "/tmp/genkernel/initramfs-{UNAME_ARCH}-{KERNEL_VERSION}";

build_output

initramfs :: build_output <path>

Arguments:

path The path where the finished initramfs will be

Default: None

Variables:

Same as for build_command.

Optional. Specifies where the output from the initramfs build command will be. You do not need to specify this, if your generator placed the initramfs at location given via {INITRAMFS_OUTPUT}.

build

build { ... }

A block for build related options. Multiple appearances of this block will be merged.

Example:

build {
    umask 0077;
}

umask

build :: umask <value>

Arguments:

value Octal umask value to use

Default: 0077

Specifies the umask used while building the kernel and the initramfs.

Note

If you are tempted to set this to 022 (allow read for others), you should probably rethink your build process. This can expose valuable information about your kernel to other users and renders some hardening methods useless.

Example:

build {
    # Set umask to 0027.
    umask 0027;
}

hooks

build :: hooks { ... }

Default: None

See hooks for more information. Specifies hooks for the build phase.

Example:

build {
    hooks {
        pre "echo" "pre-build";
    }
}

install

install { ... }

A block for options related to target installation. Multiple appearances of this block will be merged.

Example:

install {
    # Disable initramfs installation
    target_initramfs false;
}

umask

install :: umask <value>

Arguments:

value Octal umask value to use

Default: 0077

Specifies the umask used while installing files.

Example:

install {
    # Set umask to 0027.
    umask 0027;
}

assert_mounted

install :: assert_mounted <path>

Arguments:

path The directory to assert is mounted

Asserts that the given directory is a mountpoint. Otherwise, autokernel will abort installation.

Example:

install {
    # Abort installation if /boot is not mounted
    assert_mounted "/boot";
}

mount

install :: mount <path>

Arguments:

path The directory to mount

Temporarily mounts the given directory. Will be unmounted after installation, in case it had to be mounted. Requires an fstab entry for the directory. Autokernel will abort if the directory could not be mounted. If you use this, an additional assert_mounted entry is unnecessary.

Example:

install {
    # Mount /boot before installation
    mount "/boot";
}

modules_prefix

install :: modules_prefix <path>

Arguments:

path The prefix path for make modules_install

Default: /

Variables:

Allowed in path. See Common variables.

The prefix path for make modules_install. This must an absolute path. Installation can be disabled by setting this to a false boolean value.

Example:

install {
    # Install into '/' (default)
    modules_prefix "/";

    # Disable installing modules
    modules_prefix false;
}

target_dir

install :: target_dir <path>

Arguments:

path The target directory when installing files

Default: /boot

Variables:

Allowed in path. See Common variables.

The target installation directory. All other target_* statements will be relative to this directory. Must be an absolute path.

Example:

install {
    # Proper target directory for an efi partition mounted in /boot/efi
    target_dir "/boot/efi/EFI";
}

target_kernel

install :: target_kernel <path>

Arguments:

path The kernel target path

Default: bzImage-{KERNEL_VERSION}

Variables:

Allowed in path. See Common variables.

The target path for the kernel image. This is relative to target_dir, but may also be an absolute path if desired. Installation can be disabled by setting this to a false boolean value.

Example:

install {
    # Don't include version number and use .efi suffix
    target_kernel "bzImage.efi";
    # Disable installing the kernel image
    target_kernel false;
}

target_config

install :: target_config <path>

Arguments:

path The config target path

Default: config-{KERNEL_VERSION}

Variables:

Allowed in path. See Common variables.

The target path for a backup of the generated config. This is relative to target_dir, but may also be an absolute path if desired. Installation can be disabled by setting this to a false boolean value.

Example:

install {
    # Disable installing the config
    target_config false;
}

target_initramfs

install :: target_initramfs <path>

Arguments:

path The initramfs target path

Default: initramfs-{KERNEL_VERSION}.cpio

Variables:

Allowed in path. See Common variables.

The target path for the initramfs image. This is relative to target_dir, but may also be an absolute path if desired. Installation can be disabled by setting this to a false boolean value. This option only has an effect if the initramfs is enabled.

Example:

install {
    # Disable installing the initramfs image
    target_initramfs false;
}

keep_old

install :: keep_old <number>

Arguments:

number Number of old builds to keep

Default: -1 (disable purging)

Automatic purging of old files. Determines the amount of old installed files to keep. Only has an effect on target_dir and target_* if {KERNEL_VERSION} is used in the path. A negative value like -1 disables purging completely, which is the default.

Warning

Purging is done immediately after installing a file. The {KERNEL_VERSION} token will be replaced in all paths with a semver wildcard. All matching paths older than the given amount of builds will be removed.

Example:

install {
    # Keep previous two builds, purge the rest
    keep_old 2;
}

hooks

install :: hooks { ... }

Default: None

See hooks for more information. Specifies hooks for the install phase.

Example:

install {
    hooks {
        pre "echo" "pre-install";
    }
}

hooks

hooks { ... }

A block for hooks. Multiple appearances of this block will be merged. Specifies pre and post hooks for the phase in which the block is included.

Example:

hooks {
    pre  "echo" "pre-hook";
    post "echo" "post-hook";
}

pre

hooks :: pre <exe> [<args>...]

Arguments:

exe The command to execute
args parameters to the command

Default: None

Variables:

Allowed in exe and args. See Common variables.

Optional. Defines a pre hook. If the hook returns an unsuccessful exit code, autokernel will abort.

Note

Each string in <args> is a separate argument to the command, and arguments will never be interpreted or split on spaces. If you need more logic here, please execute a wrapper script to do so.

Example:

hooks {
    pre "echo" "pre-hook";
}

post

hooks :: post <exe> [<args>...]

Arguments:

exe The command to execute
args parameters to the command

Default: None

Variables:

Allowed in exe and args. See Common variables.

Optional. Defines a post hook. If the hook returns an unsuccessful exit code, autokernel will abort.

Note

Each string in <args> is a separate argument to the command, and arguments will never be interpreted or split on spaces. If you need more logic here, please execute a wrapper script to do so.

Example:

hooks {
    post "echo" "post-hook";
}