buildkernel.conf.5

.TH BUILDKERNEL 5 "Version 1.0.37: July 2020"
.SH NAME
buildkernel.conf \- a configuration file for \fBbuildkernel\fR(8)
.SH SYNOPSIS
.B /etc/buildkernel.conf
.SH DESCRIPTION
This file is used to define various variables and functions
that are used by the \fBbuildkernel\fR(8)
script. You \fImust\fR specify at least the \fBEFIPARTUUID\fR and
\fBCRYPTPARTUUID\fR variables for \fBbuildkernel\fR(8) to be able to work properly;
others are optional (see below for defaults).

This file will be sourced into a \fBbash\fR(1) context, so normal \fBbash\fR(1) rules for
variable definition, comments etc. apply.

If \fBbuildkernel\fR(8) is installed using the standard \fBinstall.sh\fR script,
then the installer will attempt to infer sensible values for \fBEFIPARTUUID\fR
and \fBCRYPTPARTUUID\fR, and their definitions will already be present, uncommented, in
\fB/etc/buildkernel.conf\fR on first use. However, even in this case, you should
take care to verify that they are correct.

You can also run \fBbuildkernel --easy-setup\fR to make changes to this file
in a structured manner; doing so is recommended when starting out,
to avoid obvious errors.
.SH VARIABLES
The following variables are mandatory and \fImust\fR be set in 
\fB/etc/buildkernel.conf\fR, or \fBbuildkernel\fR(8)
will not function properly:
.RS
.TP
.BR EFIPARTUUID
This \fImust\fR be set to the partition UUID of your EFI system partition.
It will generally be on a removable USB key, but a partition on a fixed drive
can also be specified.
.br
.TP
.BR CRYPTPARTUUID
This \fImust\fR be set to the partition UUID of the \fBLUKS\fR partition on your fixed
drive, which contains a set of \fBlvm\fR logical volumes (for root, home and swap
directories).

\fBbuildkernel\fR assumes that the \fBLUKS\fR partition is secured with by a
\fBgpg\fR(1) encrypted keyfile. At boot, you are prompted to enter the
passphrase for this file. Because both the keyfile, and a passphrase to unlock
it, are required, dual-factor security is obtained.

Also, please note that it is assumed that your \fBLUKS\fR filesystem exists on the
partition of a GPT-formatted drive; if this is \fInot\fR the case (for example, if
you have your \fBLUKS\fR filesystem on an MBR partition, or if you have luksFormat-ed
a top-level drive, rather than a partition within it), then you should instead
set the \fBLUKS\fR path directly, via the
\fBCRYPTPATHMAP\fR variable (see below).
(Most users will \fInot\fR need to do this, however.)
.RE

The following variables are optional, and \fImay\fR be set 
in \fB/etc/buildkernel.conf\fR if their defaults
are not suitable for your system:
.RS
.TP
.BR CRYPTPATHMAP
If, for some reason, your LUKS filesystem does \fInot\fR exist on a GPT
partition, then you can uncomment this variable, and set it to
the correct path directly (where possible, use \fI/dev/disk/by-uuid/<...>\fR
as the value). This feature is provided as a convenience only; most users should
not need to use it (and so should leave the \fBCRYPTPATHMAP\fR variable
commented out).
.br
.TP
.BR KEYFILEPARTUUID
This should be set to the partition UUID of the partition containing your
\fBgpg\fR(1)-encrypted keyfile, used to unlock the \fBLUKS\fR partition (see
above). The file should be called \fIluks-key.gpg\fR, and be stored in the top-level
directory of this partition. If unspecified, \fBKEYFILEPARTUUID=EFIPARTUUID\fR will
be assumed (i.e., that you have a single USB key holding both the EFI stub kernel and
the encrypted keyfile).
.br
.TP
.BR LUKSKEYFILE
If you wish to rely only on the fallback passphrase (assuming you have set
one up) and no keyfile, set this to the empty string (in which case,
\fBKEYFILEPARTUUID\fR will be ignored) (and no static \fBgpg\fR(1)
will be built into the initramfs). Defaults to \fBluks-key.gpg\fR if
unset.
.br
.TP
.BR LINUXBUILDDIR
By default, \fBbuildkernel\fR(8) will build the kernel in \fI/usr/src/linux\fR.
If \fBLINUXBUILDDIR\fR is specified however, \fBbuildkernel\fR(8) will instead
delete the contents of \fBLINUXBUILDDIR\fI/buildkernel\fR, then copy the
contents of \fI/usr/src/linux\fR there. This can be useful for sparing
write cycles if \fI/usr/src/linux\fR is located on a SSD and the specified
directory lies e.g. on tmpfs.

For example, you may consider setting \fBLINUXBUILDDIR\fR="\fI/var/tmp\fR"
(the kernel will then be built in \fI/var/tmp/buildkernel\fR).

Please note that if the kernel's \fI.config\fR file is modified
during the build, and you have specified a \fBLINUXBUILDDIR\fR, then it is
only the \fI.config\fR in the \fBLINUXBUILDDIR\fI/buildkernel\fR directory
that is affected; the \fI.config\fR in \fI/usr/src/linux\fR (if any) will
be unchanged.
.br
.TP
.BR ADDITIONALKERNELCMDS
If you wish to pass any additional command line parameters in the kernel boot
line (either for attention of the kernel itself, or for \fBgenkernel\fR(8)'s
\fBinit\fR(8) script), you can specify them here. All of the important values
for booting will be set by \fBbuildkernel\fR, so this defaults to an empty
string if not set.

One parameter you may wish to consider here is "root_trim=yes"; this will
enable TRIM support on the encrypted LUKS partition (turned off by default).
.br
.TP
.BR ADDITIONALGENKERNELOPTS
By default, \fBgenkernel\fR(8) will be instructed by \fBbuildkernel\fR(8) to
include all firmware and kernel modules into the initramfs; if you do not want
this (for example, to minimize the size of your final kernel), or if you would
rather manage the settings explicitly via \fI/etc/genkernel.conf\fR, specify
the the desired options (which may be simply an empty string) here.

\fBCaution\fR - choosing not to include the firmware or kernel modules may cause
boot issues on some systems.
.br
.TP
.BR KEYMAP
This variable specifies the keymap to be used in early userspace (that is, when
the initramfs-based system is prompting you for a passphrase to unlock the
\fBgpg\fR(1)-encrypted keyfile). It is \fInot\fR a standard locale keymap string,
but rather one recognized by the \fI/usr/share/genkernel/defaults/initrd.d/00-keymaps.sh\fR
script. If not specified here, \fBKEYMAP="us"\fR will be assumed.
.br
.TP
.BR PLYMOUTHTHEME
If you want to use the graphical boot splash manager \fBplymouth\fR(8), specify
a theme here (for example, \fB"fade-in"\fR), and it will automatically be used
at boot (this will also imply the additional kernel command line options of
\fB"quiet splash"\fR, and turn off the early 'penguins' display). The default
is for this variable to be set to the empty string, implying a textual boot console.
.br
.TP
.BR EFIBOOTFILE
This is the file to which the EFI-stub kernel will be saved, and it defaults to
\fIbootx64.efi\fR, which is the 'magic' name most UEFI BIOSes will look for.
If you are on a system that expects \fIonly\fR a Microsoft boot loader, you
may have to change this to \fIbootmgfw.efi\fR.

Most users will not need to override the default.
.br
.TP
.BR EFIBOOTDIR
This is the directory (under the EFI system partition root) in which the EFI-stub
kernel will be saved. It defaults to \fI/EFI/Boot\fR, 
which is the 'magic' path that most UEFI BIOSes will search. 
If you are on a system that
expects \fIonly\fR a Microsoft boot loader, you may have to change this path to
\fI/EFI/Microsoft/Boot\fR.

Most users will not need to override the default.
.br
.TP
.BR INITSYSTEM
If you are targeting \fBOpenRC\fR(8) (rather than \fBsystemd\fR(1)) boot,
uncomment this variable, 
and set it to \fB"openrc"\fR (the capitalization is unimportant).
If left commented out, a value of \fB"systemd"\fR will be assumed.

Most users will not need to override the default.
.br
.TP
.BR CREATEEFIBOOT
When set to \fB0\fR the \fBbuildkernel\fR script will \fInot\fR
create or modify EFI boot
settings in NVRAM (if left unset, a value of \fB1\fR will be assumed).
Set to \fB0\fR only if you have your own EFI bootloader,
or want to insert appropriate EFI boot settings manually.

Most users will not need to override the default.
.br
.TP
.BR COMPRESSINITRAMFS
When set to \fB0\fR the \fBbuildkernel\fR script will \fInot\fR
intruct the kernel to XZ compress its integral initrams (the default
behaviour prior to version 1.0.30); doing so may cause boot
issues on certain systems with modest RAM.

Most users will not need to override the default.
.br
.TP
.BR CMDLINE_ROOTFSTYPE
If you wish to explicitly specify your root filesystem's type, do so
via this variable. Otherwise, \fBbuildkernel\fR will attempt to
automatically detect the filesystem type of \fBCMDLINE_REAL_ROOT\fR
(falling back to \fBext4\fR, in case of error).

Most users will not need to override the default.
.br
.TP
.BR KERNEL_SIGNING_CERT
If you sign your kernel modules, set this to the path for the signing
certificate so that your external modules are signed after being built.
Setting to \fBauto\fR uses the kernel's automatically generated signing
certificate if you have configured it to generate it.

By default this is not set and causes external modules to not be signed.
Requires that the \fBKERNEL_SIGNING_KEY\fR variable is set.
.br
.TP
.BR KERNEL_SIGNING_KEY
If you sign your kernel modules, set this to the path for the signing key so
that your external modules are signed after being built. Setting to \fBauto\fR
uses the kernel's automatically generated signing key if you have configured it
to generate it.

By default this is not set and causes external modules to not be signed.
Requires that the \fBKERNEL_SIGNING_CERT\fR variable is set.
.br
.TP
.BR DISABLE_SUSPEND
If you wish to disable suspend, set this to \fB1\fR. This is set to
\fB0\fR (Suspend enabled) by default.
.br
.TP
.BR DISABLE_HIBERNATION
If you wish to disable hibernation, set this to \fB1\fR. This is set to
\fB0\fR (Hibernation enabled) by default.
.br
.TP
.BR DISABLE_LVM
If your configuration doesn't use LVM, set this to \fB1\fR. This is set to
\fB0\fR (LVM enabled) by default.

.RE
.SH FUNCTIONS
The following hook functions \fImay\fR be specified in \fB/etc/buildkernel.conf\fR if
you need to modify \fBbuildkernel\fR(8)'s behaviour: by default they are unset.
Most users will not need to define these functions.
.RS
.TP
.BR user_conform_config_file
Define this hook function if you need to conform (modify the contents of) the
kernel \fI/usr/src/linux/.config\fR file. Note that you should only really need
to do this to override a setting forced by \fBbuildkernel\fR(8) itself; otherwise
changes made using \fBmake menuconfig\fR are persisted (and this is the
preferred way to change the configuration).
.br
.TP
.BR user_modify_initramfs
Define this hook function if you need to modify the initramfs during the
\fBbuildkernel\fR(8) process. Upon entry, the \fBcpio\fR(1L) archive will
already have been unpacked into \fI/boot/initramfs/\fR, and it is to this
unpacked image that you should apply any changes. The contents of
\fI/boot/initramfs/\fR will be repacked again automatically for you upon
function exit.
.RE
.SH COPYRIGHT
.nf
Copyright \(co 2014-2020 sakaki
License GPLv3+ (GNU GPL version 3 or later)
<http://gnu.org/licenses/gpl.html>

This is free software, you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.fi
.SH AUTHORS
sakaki \(em send bug reports or comments to <sakaki@deciban.com>
.SH "SEE ALSO"
.BR bash (1),
.BR cpio (1L),
.BR gpg (1),
.BR systemd (1),
.BR cryptsetup (8),
.BR genkernel (8),
.BR init (8),
.BR lvm (8),
.BR plymouth (8),
.BR openrc (8),
.BR portage (5).