aboutsummaryrefslogtreecommitdiff
blob: 74729bee064a77daccfc112406fc247f2674e756 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
GENKERNEL(8)
============
:man source:   genkernel {genkernelversion}
:man manual:   genkernel {genkernelversion}


NAME
----
genkernel - the Gentoo Linux automatic kernel compiler.


SYNOPSIS
--------
*genkernel* [options...] action


INTRODUCTION
------------
Genkernel is designed to allow users who are not previously used to
compiling a kernel to use a similar setup to that one that is used on
the Gentoo LiveCDs which auto-detects your hardware.

Some users may also be interested in using genkernel for hardware which
requires initialization and a working kernel before it can be booted
because genkernel also automatically compiles your kernel modules,
allowing hardware which needs to be loaded with module parameters to be
used.


USAGE
-----
All that is needed to run genkernel is just `genkernel` with an
action and any flags you might need:

------------------------------------------
# genkernel --menuconfig --no-clean --no-install all
------------------------------------------

This would produce a kernel, asking you what how to configure it to
your desire, leaving alone any existing compiled object files, but not
installing anything.


ACTIONS
-------
An action tells genkernel what you want it to do  -  the following
actions are supported:

*all*::
    Build all steps - the kernel, modules, and the ramdisk.
*bzImage*::
    Build only the kernel.
*initramfs*::
    Build only the ramdisk/initramfs.
*kernel*::
    Build only the kernel and the modules.
*ramdisk*::
    Build only the ramdisk/initramfs.


OPTIONS
-------
Genkernel supports the following options which alter its behaviour.
Certain options have *--no-* variants which do the opposite thing.
You can specify your options in any order.


CONFIGURATION OPTIONS
~~~~~~~~~~~~~~~~~~~~~
*--config*=<file>::
    Genkernel configuration file to use.


DEBUGGING OPTIONS
~~~~~~~~~~~~~~~~~
*--loglevel*=<0-5>::
    This controls the out verbosity level of genkernel output - if
    this is set to 0, minimal debugging is done; if this is set to 5
    as much output as possible is given.

*--logfile*=<outfile>::
    This outputs debugging data to the file <outfile>. By default
    this is '/var/log/genkernel.log'.

*--*[*no-*]*color*::
    Turns on, or off, output in color using escape sequences.

*--*[*no-*]*cleanup*::
    Turns on or off the full post-run cleanup for debug purposes.


KERNEL CONFIGURATION
~~~~~~~~~~~~~~~~~~~~
*--*[*no-*]*menuconfig*::
    Runs, or does not run "make menuconfig" after running "make oldconfig".

*--*[*no-*]*nconfig*::
    Runs, or does not run "make nconfig" after running "make oldconfig".

*--*[*no-*]*gconfig*::
    Runs, or does not run "make gconfig" after "make oldconfig".

*--*[*no-*]*xconfig*::
    Runs, or does not run "make xconfig" after "make oldconfig".

*--*[*no-*]*save-config*::
    Saves, or does not save the kernel configuration to '/etc/kernels'
    if the kernel is successfully compiled.

*--*[*no-*]*bcache*::
    Adds, or skip adding block layer cache (bcache) support to kernel
    configuration.

*--*[*no-*]*hyperv*::
    Adds, or skip adding Microsoft Hyper-V support to kernel configuration.

*--microcode*[=<all|amd|intel>]::
    Adds early microcode loading support for all, only AMD or Intel processors
    to kernel configuration.

*--no-microcode*::
    Do not add early microcode loading support to kernel configuration.

*--*[*no-*]*virtio*::
    Adds, or skip adding VirtIO support to kernel configuration.

*--kernel-append-localversion*=<...>::
    Appends value to genkernel's *KERNEL_LOCALVERSION* option (see below).
    The idea is to use this option to allow to easily build a new revision
    with own kernel binary, initramfs and modules directory without losing
    default *KERNEL_LOCALVERSION* value.

*--kernel-localversion*=<...>::
Set kernel option *LOCALVERSION*. Use special value *UNSET* to
unset any already set *LOCALVERSION*. The following placeholders are
available:
+
[horizontal]
*%%ARCH%%*:::
Will be replaced with genkernel arch value, for example 'x86_64'.

+
*LOCALVERSION* is only allowed to contain characters like 'a-z' or 'A-Z',
'0-9', '_', '.' and '-'.
+
By default, *LOCALVERSION* will be set to '-%%ARCH%%'.


KERNEL COMPILATION
~~~~~~~~~~~~~~~~~~
*--*[*no-*]*clean*::
    Runs, or does not run, "make clean" before compilation  -  this
    erases any compiled object files in the kernel source tree but
    does not have an impact on the kernel configuration.  Specifying
    *--no-clean* implies *--no-mrproper*.

*--*[*no-*]*mrproper*::
    Runs, or does not run, "make mrproper" before compilation - this
    erases both any compiled object files in the kernel source tree
    as well as the kernel configuration.

*--*[*no-*]*install*::
    Installs,  or does not install the kernel to '/boot' after building.
    The default is  *--install*.   If MOUNTBOOT is set in
    '/etc/genkernel.conf'  then '/boot' will be automatically mounted if
    it is not already mounted before the ramdisk and kernel images
    are copied over.

*--*[*no-*]*symlink*::
Manages,  or does not manage, symlinks in '/boot' like the manual
kernel "make install" process does. A 'kernel' (or, depending on
options, 'kernelz') symlink will link to the most recently built
kernel image and a 'kernel.old' (or 'kernelz.old') symlink will link
to the second most recently built image, if one exists. Similar
symlinks (with and without '.old' suffix) are managed for initramfs and
System.map. The corresponding work products (i.e., the actual kernel
and initramfs images, and System.map) are also managed accordingly.
+
The symlink name can be controlled via *--kernel-symlink-name* and/or
*--initramfs-symlink-name* option.

NOTE: Specifying *--symlink* does nothing unless *--install* is also
specified.

*--*[*no-*]*oldconfig*::
    Runs, or does not run, "make oldconfig" before compilation.  Specifying
    *--oldconfig* implies *--no-clean*.

*--*[*no-*]*splash*::
    Installs, or not, framebuffer splash support into initramfs.

*--*[*no-*]*ramdisk-modules*::
    Copies or does not copy configured modules to the ramdisk.

*--*[*no-*]*all-ramdisk-modules*::
    Copies or does not copy all kernel modules to the initrd.

*--*[*no-*]*module-rebuild*::
    Runs, or does not run "emerge --ignore-default-opts --buildpkg=n --usepkg=n --quiet-build=y @module-rebuild"
    to build out-of-tree modules when possible, i.e. when non-static
    kernel and modules will be build, installed,
    *--kernel-modules-prefix* is not set, '/var/lib/module-rebuild/moduledb' exists
    and is not empty.

NOTE: Command can be customized using '--module-rebuild-cmd' command-line
argument or 'MODULEREBUILD_CMD' in '/etc/genkernel.conf'.

*--module-rebuild-cmd*=<...>::
    Overwrite default *--module-rebuild* command.

*--callback*=<...>::
    Run the specified arguments in the current environment after the
    kernel and modules have been compiled.

*--*[*no-*]*static*::
    Builds, or does not build a monolithic kernel without any modules on
    any initial ramdisks.


KERNEL LOCATIONS
~~~~~~~~~~~~~~~~
*--kerneldir*=<dir>::
    This specifies the location of the kernel sources;  the default
    is '/usr/src/linux'.

*--kernel-config*=<file|default>::
    This specifies a kernel configuration file to use for compilation;
    by default genkernel uses the config from the previous
    build of the same kernel version or a default kernel config if
    there isn't a previous config.
    Use the special value 'default' to force usage of default kernel
    config.

*--kernel-modules-prefix*=<dir>::
    Prefix to kernel module destination, modules will be installed in
    '<prefix>/lib/modules'.


LOW-LEVEL COMPILATION OPTIONS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*--cross-compile*=<target triplet>::
    Target triple (i.e. aarch64-linux-gnu) to build for. Only needed
    when the system running genkernel has a different architecture like
    the system which should boot the created kernel/initramfs.

*--kernel-as*=<assembler>::
    Assembler to use for the kernel compilation.

*--kernel-cc*=<compiler>::
    Compiler to use for the kernel compilation (e.g. distcc).

*--kernel-ld*=<linker>::
    Linker to use for the kernel compilation.

*--kernel-make*=<makeprg>::
    GNU Make to use for the kernel compilation.

*--kernel-target*=<t>::
    Override default make target (bzImage), note that values
    like *--kernel-target=* are also valid (useful for Xen
    based kernel sources).

*--kernel-binary*=<path>::
    Override default kernel binary path (arch/foo/boot/bar).

*--kernel-outputdir*=<path>::
    Save output files outside the source tree. This should be used rather than
    KBUILD_OUTPUT when you wish to place kernel objects outside of the source
    tree (eg because cannot write to that directory as the user genkernel is
    running as).

*--utils-as*=<assembler>::
    Assembler to use for utilities.

*--utils-cflags*=<cflags>::
    C compiler flags used to compile utilities.

*--utils-cc*=<compiler>::
    C Compiler to use for utilities.

*--utils-cxx*=<compiler>::
    C++ Compiler to use for utilities.

*--utils-ld*=<linker>::
    Linker to use for utilities.

*--utils-make*=<makeprog>::
    GNU Make to use for utilities.

*--makeopts*=<makeopts>::
    GNU Make options such as -j2, etc.

*--*[*no-*]*mountboot*::
    Mount, or not, BOOTDIR automatically if mountable.

*--bootdir*=<dir>::
    Set the location of the boot-directory, default is '/boot'.

*--modprobedir*=<dir>::
    Set the location of the modprobe.d-directory, default is '/etc/modprobe.d'.

*--*[*no-*]*nice*[=<niceness>]::
    Runs the kernel make at the default niceness (reduction in priority) of
    10, or in the case of *--no-nice*, runs the kernel make at normal priority.


INITIALIZATION
~~~~~~~~~~~~~~
*--splash*=<theme>::
    Enable framebuffer splash using <theme>.

*--splash-res*=<resolutions>::
    Select gensplash resolutions to include.

*--*[*no-*]*splash*=<theme>::
    If the extra argument is specified,  splash is forced using
    <theme>  rather than the default theme specified in your splash
    configuration. If *--no-splash* is specified, then splash is disabled.

*--do-keymap-auto*::
    Force keymap selection at boot.

*--*[*no-*]*keymap*::
    Enables or disables keymap selection at boot.

*--*[*no-*]*lvm*::
    Includes or excludes LVM support.
    When enabled, this will compile LVM for you.

*--*[*no-*]*mdadm*::
    Includes or excludes mdadm support.
    When enabled, this will compile mdadm for you.

*--mdadm-config*=<file>::
    Use <file> as configfile for MDADM.
    By default the ramdisk will be built *without* an 'mdadm.conf' and
    will auto-detect arrays during boot-up.

*--*[*no-*]*microcode-initramfs*::
    Prepends, or do not prepend ucode(s) to the initramfs.
    But only when kernel configuration does support early microcode loading.
    See *--microcode* option to auto-update kernel configuration.

NOTE: Embedding microcode updates into initramfs is *deprecated* when
system is able to load multiple initramfs.

*--*[*no-*]*dmraid*::
    Includes or excludes DMRAID support.
    When enabled, this will compile dmraid for you.

*--*[*no-*]*nfs*::
    Includes or excludes NFS support.

*--*[*no-*]*e2fsprogs*::
    Includes or excludes e2fsprogs.
    When enabled, this will compile e2fsprogs for you.

*--*[*no-*]*xfsprogs*::
    Includes or excludes xfsprogs.
    When enabled, this will compile xfsprogs for you.

*--*[*no-*]*zfs*::
    Includes or excludes ZFS support.

*--*[*no-*]*btrfs*::
    Includes or excludes Btrfs support.
    When enabled, this will compile btrfs-progs for you.

*--*[*no-*]*multipath*::
    Includes or excludes Multipath support.
    When enabled, this will compile multipath-tools for you.

*--*[*no-*]*iscsi*::
    Includes or excludes iSCSI support.
    When enabled, this will compile open-iscsi for you.

*--*[*no-*]*sandbox*::
    Enables or disables sandbox-ing when building initramfs.

*--*[*no-*]*ssh*::
    Includes or excludes SSH (dropbear) support for remote LUKS keys.
    When enabled, this will compile dropbear for you.

*--ssh-authorized-keys-file*=<file>::
    Specifies a user created authorized_keys file. By default genkernel
    will use '/etc/dropbear/authorized_keys'.

*--ssh-host-keys*=<create|create-from-host|runtime>::
    When set to *create*, which is the default value, genkernel will embed
    SSH host keys from '/etc/dropbear' and will create those keys when missing.
    When set to *create-from-host*, genkernel will embed SSH host keys from
    '/etc/dropbear' but will create those keys from '/etc/ssh' when missing
    (not recommended for security reasons).
    When set to *runtime*, genkernel will not embed any SSH host key in
    initramfs and dropbear will generate needed host key at runtime (`dropbear -R`).

*--boot-font*=<current|<file>|none>::
    When set to *current*, genkernel will use "setfont" to dump and embed
    current active console font into initramfs.
    When set to a *PC Screen Font file*, genkernel will embed that font
    into initramfs.
    When set to *none*, genkernel will not embed any font file in initramfs.
    In case a font was embedded into initramfs, genkernel will load that
    font early on boot. See *gk.bootfont.disabled* kernel parameter for
    disabling that feature at runtime.

*--bootloader*=<grub|grub2>::
    Add new kernel to GRUB or GRUB2 configuration.

*--linuxrc*=<file>::
    Use <file> for the linuxrc instead of the genkernel linuxrc.

*--busybox-config*=<file>::
    Specifies a user created busybox config.

*--genzimage*::
    Make and install kernelz image from 'arch/powerpc/boot/zImage.initrd'.

*--*[*no-*]*luks*::
    Includes or excludes LUKS support.
    When enabled, this will compile cryptsetup for you.

*--*[*no-*]*gpg*::
    Includes or excludes support for GnuPG 1.x, the portable standalone branch
    of GnuPG. A key can be made from
    `gpg --symmetric -o /path/to/LUKS-key.gpg /path/to/LUKS-key` .
    After that, re-point the *root_key* argument to the new .gpg file.

*--*[*no-*]*b2sum*::
    Includes or excludes b2sum in the initramfs.
    When enabled, this will compile coreutils' b2sum for you.

*--*[*no-*]*busybox*::
    Includes or excludes busybox in the initramfs.
    When enabled, this will compile busybox for you.

*--*[*no-*]*unionfs*::
    Includes or excludes support for unionfs.
    When enabled, this will compile unionfs-fuse for you.

*--*[*no-*]*netboot*::
    Creates or does not create a self-contained env in the initramfs.

*--real-root*=<foo>::
    Specify a default for *real_root*= kernel option which will be
    embedded into initramfs.


INTERNALS
~~~~~~~~~
*--cachedir*=<dir>::
    Override the default cache location.

*--check-free-disk-space-bootdir*=<MB>::
    When set to a non-zero value, genkernel will check early on start for
    specified amount of free disk space in megabyte in *BOOTDIR*.

*--check-free-disk-space-kerneloutputdir*=<MB>::
    When set to a non-zero value, genkernel will check early on start for
    specified amount of free disk space in megabyte in *KERNEL_OUTPUTDIR*.

*--*[*no-*]*clear-cachedir*::
    Clears or skips clearing all files in cache location on genkernel start.

*--tmpdir*=<dir>::
    Sets genkernel's temporary working directory to <dir>. By default, a
    directory below '/var/tmp/genkernel' will be used.

*--*[*no-*]*postclear*::
    Clears or skips clearing all tmp files and caches after genkernel has run.


OUTPUT SETTINGS
~~~~~~~~~~~~~~~
*--initramfs-filename*=<...>::
Set initramfs filename which will be used when initramfs will be installed
into *BOOTDIR* (implies *--install* option). Please see
*--kernel-filename* option for available placeholders and restrictions.
+
By default, initramfs filename will be set to 'initramfs-%%KV%%.img'.

*--initramfs-symlink-name*=<...>::
Set initramfs symlink name which will be used when initramfs will be
installed into *BOOTDIR* (implies *--install* option) and *--symlink*
option is given. Please see *--kernel-filename* option for available
placeholders and restrictions.
+
By default, initramfs symlink name will be set to 'initramfs'.

NOTE: Initramfs filename and initramfs symlink name must be different.

*--minkernpackage*=<file>::
Archive file created using tar containing kernel and initramfs.

NOTE: No modules outside of the initramfs will be included!

*--modulespackage*=<archive>::
    Archive file created using tar containing modules after the callbacks
    have run.

*--kerncache*=<archive>::
    Archive file created using tar containing kernel binary, content of
    '/lib/modules' and the kernel config after the callbacks have run.

*--kernel-config-filename*=<...>::
Set the kernel config filename used by *--save-config*. Please see
*--kernel-filename* option for available placeholders and restrictions.
+
By default, kernel config filename will be set to 'kernel-config-%%KV%%'.

*--kernel-filename*=<...>::
Set kernel filename which will be used when kernel will be installed
into *BOOTDIR* (implies *--install* option). The following placeholders
are available:
+
[horizontal]
*%%ARCH%%*:::
Will be replaced with genkernel arch value, for example 'x86_64'.
*%%KV%%*:::
Will be replaced with kernel version, for example '5.2.3-gentoo'.

+
Kernel filename is only allowed to contain characters like 'a-z' or 'A-Z',
'0-9', '_', '.' and '-'.
+
By default, kernel name will be set to 'vmlinuz-%%KV%%'.

NOTE: When setting a custom kernel name make sure that your bootloader and
tools like *kexec* when used are recognizing your custom kernel name.

*--*[*no-*]*kernel-sources*::
    This option is only valid if kerncache is defined If there is a
    valid kerncache no checks will be made against a kernel source
    tree.

*--kernel-symlink-name*=<...>::
Set kernel symlink name which will be used when kernel will be installed
into *BOOTDIR* (implies *--install* option) and *--symlink* option is
given. Please see *--kernel-filename* option for available placeholders
and restrictions.
+
By default, kernel symlink name will be set to 'kernel'.

NOTE: Kernel filename and kernel symlink name must be different.

*--systemmap-filename*=<...>::
Set System.map filename which will be used when kernel will be installed
into *BOOTDIR* (implies *--install* option). Please see
*--kernel-filename* option for available placeholders and restrictions.
+
By default, System.map filename will be set to 'System.map-%%KV%%'.

*--systemmap-symlink-name*=<...>::
Set System.map symlink name which will be used when kernel will be
installed into *BOOTDIR* (implies *--install* option) and *--symlink*
option is given. Please see *--kernel-filename* option for available
placeholders and restrictions.
+
By default, System.map symlink name will be set to 'System.map'.

NOTE: System.map filename and System.map symlink name must be different.

*--initramfs-overlay*=<dir>::
    Directory structure to include in the initramfs, only available
    on >=2.6 kernels.

*--*[*no-*]*firmware*::
    Enable or disables copying of firmware into initramfs.

*--firmware-dir*=<dir>::
    Specify directory to copy firmware from (defaults to '/lib/firmware').

*--firmware-files*=<files>::
    Specifies specific firmware files to copy. This overrides *--firmware-dir*.
    For multiple files, separate the filenames with a comma.

*--*[*no-*]*firmware-install*::
    Enable or disables installation of firmware onto root filesystem.
    Please note this is deprecated, and installing
    *sys-kernel/linux-firmware* should be preferred instead.

*--*[*no-*]*integrated-initramfs*::
    Builds or does not build the generated initramfs into the kernel instead
    of keeping it as a separate file.

*--*[*no-*]*wrap-initrd*::
    Wrap initramfs using mkimage for u-boot boots. Please note that only
    certain compression types are supported by mkimage (see manpage).

*--*[*no-*]*compress-initramfs*::
    Compresses or does not compress the generated initramfs.

*--*[*no-*]*compress-initrd*::
    Deprecated alias for *--*[*no-*]*compress-initramfs*.

*--compress-initramfs-type*=<arg>::
    Compression type for initramfs (best, bzip2, fastest, gzip, lz4, lzma,
    lza, xz, zstd).
+
*best* will select the algorithm providing best compression
from those selected in your kernel configuration.
+
*fastest* will select the algorithm providing fastest decompression
from those selected in your kernel configuration.

*--strip*=<all|kernel|modules|none>::
    Strip debug symbols from none, all, installed kernel (obsolete) or
    modules (default).

*--no-strip*::
    Alias for *--strip=none*.


RAMDISK/INITRAMFS OPTIONS
-------------------------
The following options are some of those available to be passed as kernel
parameters from the bootloader. Genkernel will not handle this
operation, please refer to your bootloader documentation for a more
complete description of each.

This listing is intended to cover most of the options recognized by the
ramdisk/initramfs scripts, as well as some of the common options
recognized by the kernel itself.

*root*=<...>::
    Specifies the device node of the root filesystem to mount.

*real_root*=<...>::
    Legacy kernel parameter from kernel-2.4 initrd.
    Does the same as *root*=, which should be used in its place.

*crypt_root*=<...>::
    This specifies the device encrypted by LUKS, which contains the
    root filesystem to mount.

*crypt_root_options*=<...>::
    This specifies additional options, which should get passed to
    cryptsetup when opening root volume. Can be specified multiple
    times or separate multiple options with a comma.

*crypt_swap*=<...>::
    This specifies the swap device encrypted by LUKS.

*crypt_swap_options*=<...>::
    This specifies additional options, which should get passed to
    cryptsetup when opening swap volume. Can be specified multiple
    times or separate multiple options with a comma.

*root_key*=<...>::
    In case your root is encrypted with a key, you can use a device
    like a  usb pen to store the key.  This value should be the key
    path relative to the mount point.

*root_keydev*=<...>::
    If necessary provide the name of the device that carries the
    root_key.   If unset while using root_key, it will automatically
    look for the device in every boot.

*root_keydev_fstype*=<...>::
    Used filesystem for *root_keydev*. See *rootfstype* for more details.

*root_trim*=(yes|no)::
    Enables TRIM support for a LUKS-based root device.  Only useful
    with SSD setups.  Have a look at 'https://en.wikipedia.org/wiki/TRIM'
    for more information.

*swap_key*=<...>::
    Same as root_key for swap.

*swap_keydev*=<...>::
    Same as root_keydev for swap.

*swap_keydev_fstype*=<...>::
    Used filesystem for *swap_keydev*. See *rootfstype* for more details.

*crypt_silent*::
    Set this to silent all the output related to the cryptographic
    software,  and in case your encrypted device isn't open with the
    key, it opens a shell in the initrd quietly.

*dodmraid*[=<...>]::
    Activate Device-Mapper RAID and (optionally) pass arguments to it.

*init*=<...>::
    Override location of init script, default is "/sbin/init".

*real_init*=<...>::
    Legacy kernel parameter from kernel-2.4 initrd.
    Does the same as *init*=, which should be used in its place.

*init_opts*=<...>::
    Passes arguments to init on bootup.

*scandelay*[=<...>]::
    Pauses for 10 seconds before running devfsd if no argument is
    specified; otherwise pauses for the number of specified seconds.

*rootdelay*[=<...>]::
*rootwait*[=<...>]::
    Pauses for up to 3 seconds (or specified number of seconds) while
    waiting for root device to appear during initramfs root scanning.

*ip*=<dhcp,addr/cidr>::
    Normally used to tell the kernel that it should start a network
    interface which can be specified using *gk.net.iface* kernel parameter.
    By default, dhcp will be used. You can set a specific IP address using
    addr/CIDR notation, i.e. '1.2.3.4/24'.

*gk.net.dhcp.retries*=<...>::
    By default we will send up to 3 DHCP discovery requests.

*gk.net.iface*=<interface,macaddr>::
    By default we will use the interface named eth0. Use this kernel
    parameter to specify another interface. You can also specify a MAC
    address (00:00:00:00:00:00 format) instead of an interface name.

*gk.net.gw*=<...>::
    Optional gateway. If *ip* is set to dhcp, this kernel parameter will
    be ignored.

*gk.net.routes*=<...>::
    Optional additional routes. If *ip* is set to dhcp, this kernel
    parameter will be ignored.

*gk.net.timeout.dad*=<...>::
    By default we will wait up to 10 seconds for IPv6's DAD to complete.
    At the moment, we only wait for DAD while bringing down an interface
    to prevent a race condition.

*gk.net.timeout.deconfiguration*=<...>::
    By default we will wait up to 10 seconds while bringing down an
    interface to prevent a race condition.

*gk.net.timeout.dhcp*=<...>::
    By default we will wait up to 10 seconds for a DHCP server reply.

*gk.net.timeout.interface*=<...>::
    By default we will wait up to 10 seconds for interface to show up.

*gk.udev.debug*=<...>::
    This boolean option allows you to run udevd in debug mode. Output
    will be logged to '/run/initramfs/udevd.log'.

*gk.udev.timeout*=<...>::
    By default we will wait up to 120 seconds (UDEV default) for
    UDEV event queue to become empty.

*gk.preserverun.disabled*=<...>::
    By default, *switch_root* will preserve and move already mounted '/run'
    to *newroot*. This boolean option allows you to disable preserving of
    '/run', which is maybe required for SELinux due to missing labeling
    support in genkernel.

*gk.prompt.timeout*=<...>::
By default a prompt within genkernel initramfs like shown when set
*root* could not be found will never timeout. Use this option to set
a timeout.

NOTE: When *dosshd* is used, *gk.prompt.timeout* will be set to 30 seconds
when not set. This will allow remote user to provide answer through
*GK_PROMPT_FILE* which is set to '/tmp/current_prompt' by default.

*dosshd*::
    Will bring up an interface and start a SSH daemon within initramfs
    allowing to remotely unlock encrypted devices or just for debugging
    purpose. See *ip* option for how to configure network.

*gk.sshd.port*=<...>::
    By default, sshd will listen on port 22.

*gk.sshd.wait*=<...>::
    Wait X seconds after setting up sshd, useful when you want to login
    (and thus pause boot process) before booting real system.

*nfsroot*=<...>::
    If present,  the initrd will try to mount a livecd from that
    location. Otherwise the location will be deduced from the DCHP
    request (option root-path).

*dolvm*::
    Activate LVM volumes on bootup.

*lvmraid*=<...>::
    Specify RAID devices to set up before the activation of LVM volumes.
    Implies option *dolvm*.

*domdadm*::
    Scan for RAID arrays on bootup.

*dozfs*[=cache,force]::
    Scan for bootable ZFS pools on bootup. Optionally use cachefile or force import if
    necessary or perform both actions.

*domultipath*::
    Activate Multipath on bootup.

*doscsi*::
    Activate SCSI devices on bootup, necessary when SCSI support is
    compiled as modules and you're using SCSI or SATA devices.

*keymap*='MAP'::
    Set keymap to 'MAP', e.g. *keymap*=de.
    For valid values of 'MAP' please see
    '/usr/share/genkernel/defaults/keymaps/'.

*dokeymap*::
    Use keymap.  Usage of *keymap*= implies this option, already.

*rootfstype*=<...>::
    Specify the file system type to mount the real root filesystem as.
    This can be useful when support for ext2/ext3/ext4 are
    in competition or used filesystem was not built into kernel.
    Default is "auto".

*docache*::
*nocache*::
    Enables/disables caching of CD contents in RAM.

*subdir*=<...>::
    switch_root into "<CHROOT>/<SUBDIR>" instead of "<CHROOT>/".
    <CHROOT> is "/newroot" (or "/union") usually.

*quiet_genkernel*::
    Do not print anything but error and warning messages during
    the execution of the initramfs init scripts.

*quiet*::
    Implies *quiet_genkernel*, but also recognized by the kernel to
    suppress kernel messages.

*debug*::
    Drop into a debug shell early in the process.

*gk.bootfont.disabled*=<...>::
    By default, if a bootfont is embedded within initramfs, genkernel
    will load that font. This boolean option allows you to disable
    loading of the user embedded bootfont.

*gk.hw.load-all*=<...>::
    By default, genkernel loads various module groups (nvme, sata,
    scsi, pata, usb...) until block device specified in *root* parameter
    becomes available. This boolean option allows you to force
    loading of all module groups regardless whether root device is
    already available.

*gk.hw.use-modules_load*=<...>::
    By default, genkernel relies on UDEV's capability to load required
    kernel modules. This boolean option allows you to force old module
    loading depending on modules_load file until *root* device becomes
    available.

*gk.log.disabled*=<...>::
    By default, any shown message and external command calls will be logged
    to '/run/initramfs/init.log'. This boolean option allows you to
    disable logging for some reason.

*gk.userinteraction.disabled*=<...>::
By default, genkernel will prompt on errors. In case this is not wanted
or desired, e.g. for a kiosk system, this boolean option will disable
any prompting, including the rescue shell.

NOTE: Because no user interaction is possible when this option is set,
system will automatically reboot on error after a timeout.

*noload*=<...>::
List of modules to skip loading.
Separate using commas or spaces.

NOTE: This option has only an effect when *gk.hw.use-modules_load* is
enabled.

*doload*=<...>::
    List of modules which should always be loaded.

*domodules*::
*nomodules*::
    Enables/disables loading of modules in general.

*CONSOLE*=<...>::
*console*=<...>::
    Override location of console, default is "/dev/console".

*part*[=<0,1>]::
*partitionable*::
    Enable/Disable partitionable RAIDs (metadata 0.x) during auto-run.
    Standalone *part* and *partitionable* keywords for kernel compatability.

*iscsi_initiatorname*=<...>::
*iscsi_target*=<...>::
*iscsi_tgpt*=<...>::
*iscsi_address*=<...>::
*iscsi_port*=<...>::
*iscsi_username*=<...>::
*iscsi_password*=<...>::
*iscsi_username_in*=<...>::
*iscsi_password_in*=<...>::
*iscsi_debug*=<...>::
*iscsi_noibft*::
    Specify iSCSI parameters.

*unionfs*::
*nounionfs*::
    Enables/disables UnionFS.

*aufs*::
    Enables support for AUFS (if available in the kernel).

*aufs.modules*=<...>::
    Use an alternate location for filesystem overlays to be added on top of
    the livecd and below the writable tmpfs.  Default is /modules/.

*overlayfs*::
    Enables support for Overlayfs (if available in the kernel).

*overlayfs.modules*=<...>::
    Use an alternate location for filesystem overlays to be added on top of
    the livecd and below the writable tmpfs.  Default is /modules/

*rootflags*=<...>::
    Additional flags to mount the real root system with.
    For example *rootflags*=noatime would make "-o ro,noatime".

*real_rootflags*=<...>::
    Legacy kernel parameter from kernel-2.4 initrd.
    Does the same as *rootflags*=, which should be used in its place.

*real_resume*=<...>::
*resume*=<...>::
*noresume*::
    *noresume* disables any default resume parameters. *resume* and
    *real_resume* specify a device via LABEL or UUID to use for for loading a
    TuxOnICE, SWSUSP or Suspend2 resume image.

*cdroot*[=<...>]::
*cdroot_type*=<...>::
*cdroot_marker*=<...>::
    Used for LiveCDs. *cdroot* without arguments will cause the initramfs to
    scan all devices for a LiveCD. An argument to *cdroot* will cause it to
    scan only that device. A LiveCD is any device containing a file with the
    name & Path of *cdroot_marker* (default of "/livecd"). *cdroot_type*
    (default of "auto") is the filesystem type to use while mounting devices
    to check. On success, the LiveCD will be mounted at $CDROOT_PATH.

*loop*=<...>::
*looptype*=<...>::
    Used for LiveCDs. After mounting the LiveCD or ISO, look for a file at
    *loop*=path to use as a loopback image for the main type. Mount it with
    filesystem type *looptype*. Possible values for *looptype*: normal,
    squashfs, gcloop, zisofs, noloop, sgimips. If *looptype* is not specified,
    a guess is made, based on the name or extension of *loop*.

*isoboot*=<...>::
    Loop-mount an ISO file from the boot device to get the filesystem image.
    Useful with chain-loading environments and USB keys.

initramfs.mounts
----------------
By default, genkernel's initramfs will only mount *root* device. But
sometimes additional mounts are required before initramfs can switch to
real root (for example on systems with a seperate '/usr' mount).

Therefore genkernel package contains '/etc/initramfs.mounts' file which
will allow you to specify additional mounts which should be mounted before
initramfs will switch to real root.

NOTE: This file will not be included in initramfs. Instead, booted initramfs
will check for this file on specified *root* device.

NETBOOTING
----------
The initrd scripts have limited support for network booting.   This is
activated if the *ip*=<...> kernel parameter was given. Please refer to
the genkernel guide at 'https://wiki.gentoo.org/wiki/Genkernel' for more
information.

The initrd scripts will extract any *.tar.gz files found in the '/add'
directory of the livecd into the root filesystem during boot. This way
it is easy to extend a netbooted LiveCD i.e. add custom tools, or other
kernel modules.


REPORTING BUGS
--------------
If you believe you have found a bug in the genkernel scripts,  then
please file a bug on the Gentoo Linux Bugzilla against product
"Gentoo Hosted Projects" component "genkernel", i.e. at
'https://bugs.gentoo.org/enter_bug.cgi?product=Gentoo%20Hosted%20Projects&component=genkernel'.

If you're somewhat unsure if you hit a bug or not, file a bug an we'll find out together.
For general questions the is the gentoo-genkernel mailing list.  You can join the list
by sending empty mail to 'gentoo-genkernel+subscribe@lists.gentoo.org'.

We cannot assist you with kernel compilation failures unless they are
caused by a genkernel bug.

Kernel issues for Gentoo-supported kernels, including compilation failures
should go to 'https://bugs.gentoo.org/' and should be assigned to 'kernel@gentoo.org'.

Please check if an existing bug documents the same issue before opening
a new bug. Issues for kernel sources not supported by Gentoo should go
to their relevant authors.


AUTHORS
-------
- Tim Yamin <plasmaroo@gentoo.org>
- Eric Edgar <rocket@gentoo.org>
- Chris Gianelloni <wolf31o2@gentoo.org>
- Sebastian Pipping <sebastian@pipping.org>
- Robin H. Johnson <robbat2@gentoo.org>
- Thomas Deutschmann <whissi@gentoo.org>
- NFS Support by Thomas Seiler <thseiler@gmail.com>
- GnuPG 1.x integration by dacook <schism@subverted.org>
- MDADM integration by Matthias Dahl <ua_bugz_gentoo@mortal-soul.de>
- ZFS integration by Richard Yao <ryao@cs.stonybrook.edu>
- AUFS/Overlayfs by Zero_Chaos <zerochaos@gentoo.org> and likewhoa


SEE ALSO
--------
'/etc/initramfs.mounts' - additional required mounts before switching to real root

'/etc/genkernel.conf' - genkernel configuration file

// vim: ft=asciidoc et tw=72 sts=4 ts=4 :