Kernel Command Line Parameters (aka Boot Options)

Kernel command line parameters are parameters that you pass on to the Fatdog64 during the boot process. They are also known as "boot options". Some of these parameters are understood by the Linux kernel, some are understood by Fatdog64 system scripts. They influence how Fatdog64 brings the system up and operates, they also control how the Linux kernel behaves. There are so many parameters (especially for Linux kernel), this page will only address some of the most important ones.

Applying Parameters

These parameters must be passed on to Fatdog64 before the system boots up, during boot-loading stage. Boot loaders can be configured to pause and ask for parameters during boot up (like the one in Fatdog64 Live CD/DVD), or you can put it in the configuration file.

For example, with Fatdog64 Live CD/DVD, it will display Fatdog64 logo and pause for 5 seconds for you to key in any parameters. Here, you can enter the parameters like this:

boot: fatdog paramA paramB ...
where "boot:" is the boot prompt displayed by the boot loader, "fatdog" is the operating system label understood by the bootloader (it has to be "fatdog" for Fatdog64 Live CD/DVD), and "paramA", "paramB" etc are the parameters. If nothing is typed for 5 seconds, the system will continue to boot-up with default parameters.

If you use GRUB, the parameters are passed on the kernel line. For example: 

title Fatdog64
root (hd0,0)
kernel /vmlinuz paramA paramB
initrd /initrd

If you use syslinux and its friends, the parameters are passed on the append line. For example: 

label fatdog
kernel vmlinuz
initrd initrd
append paramA paramB

Note 1: parameters are case sensitive. Most of them are in lower case, so if you specify them in upper case (capital letters), it won't work. Also remember that all parameters cannot include space or colon.

Note 2: For Windows users - the word module in Linux terms is roughly equivalent to what you usually know as drivers in Windows.


Commonly Used Parameters

These are the commonly used parameters to tune system operation or to troubleshoot issues.

Fatdog64 Parameters

waitdev

"wait for device" - this instructs Fatdog64 to delay boot process by a few more seconds, so that save devices have time to settle and be ready - so that they can be accessed (and the savefile can be read off them). By default, Fatdog64 boots as fast as it can. You need this if your save device is not recognised during boot - the easiest symptom is that you have a savefile but Fatdog does not use it. Thist mostly happens for USB devices. My computer for example requires at least 3 seconds for flash drives to be recognised; delays of up to 5 seconds is not uncommon. Some slower devices may need even longer time.

The syntax is: waitdev=n, where n is the number of seconds to wait.

On Fatdog64 720 onward, the syntax is waitdev=n[:n[:n[...]]] where each number represents the number of seconds to wait, for each "wait points". In 720, there are two "wait points", one is at early boot before basesfs/savefile is loaded (this is the same as the original waitdev), and the second one is in rc.sysinit, before pkeys is processed and before Xorg is loaded. The two wait points is independent, you can specify one without another. For example, if only want to wait for 3 seconds at the second wait point, you can specify it like this: waitdev=:5 (the colon is not a typo).

Control searching of possible savefiles in subdirectories. This parameter tells the boot process "at which subdirectory level in a given path, searching for savefiles is to end". If n is not specified it defaults to 1. Fatdog will search for fd64save* (or whatever filename you specify in the savefile parameter) starting in the directory you specified there too (default is root directory).

If, for example, you want it to search in subdirectories up to 3-level deep, specifiy search=3 instead. If more than one savefile matching the pattern if found, they will be listed and you will be asked to choose the one to use.

Search is only performed when savefile specifies a location of local or usb. Other location types do not perform searching regardless of this parameter. We generally recommend not to depend on this parameter on as searching slows down the boot process; it is always better to specify the exact location of the savefile (using device / uuid / label locations) if possible.

autoswap

(Fatdog64 803 onwards): Detect and use all existing swap partitions. It detects and uses only swap partitions, not swap files.

blacklist

Prevent named list of modules (drivers) to be loaded. Use this if the system cannot start-up due to suspected bad modules. The syntax is: blacklist=module1,module2,module3 and so on. Note: separate module names by comma, and there is no space in between.

pfix=xorgwizard

Launch xorgwizard automatically to select the driver, screen resolution, and bit depth before you start the desktop. This option only has effect if you choose autologin or console login, it is ignored when graphical login manager is in effect.

pfix=nox

Do not automatically start X server and graphical desktop after login. You can always start it manually later by running the command xwin from console.

pkeys

Set the keyboard layout and console font you want to use for the Linux console. Default is US keyboard (pkeys=us), with whatever font the system has. You can change that here. Only restricted options are available:

Specify it like this: pkeys=br to enable Brazilian keyboard.

Note that once you go to the graphical desktop, you need to set it separately using Keyboard Localization from the Control Panel.

dofsck

Perform filesystem check on filesystems that will be used by savefile and basesfs, before they are used. It will check both the physical partitions as well as the savefile. Only ext2/3/4 and FAT filesystems will be checked.




Linux Kernel Parameters

nomodeset

This is a kernel boot option that tells the kernel not to enable kernel mode setting (KMS). Video support is usually a combination of a drm kernel driver and a Xorg driver working together. KMS is used with Intel, Nouveau, and Radeon kernel modules. KMS is required for Intel and Nouveau, and optional for Radeon (although, with different features).

If you want to use the vesa Xorg driver, and you have hardware that uses the Intel, Nouveau, or Radeon kernel modules, you may need to boot with nomodeset, or blacklist the matching module, or just delete the module. The modules will be found in /lib/modules/«Kernel-Version»/kernel/drivers/gpu/drm/.

See also here.

video

This kernel boot options tells the kernel KMS driver on what resolution and/or frequency to use. For this to work, KMS must not be disabled (see above). The format of the option is as follows:

video=conn:res[M][R][-bpp][@refresh][i][m][eDd]

This option can be specified multiple times, one for each different connection name - so you can have on settings for VGA, one for HDMI, etc.

Note: This is a generic parameter used to set framebuffer display resolution. It can also be used for non-KMS drivers too. That is not discussed here because it is irrelevant, for further reference you can refer to Linux Kernel Framebuffer Documentation.

pci=nocrs

Discard pci ACPI information. May fix boot problems.

pci=noacpi

Do not use ACPI for PCI bus management. May fix boot problems.

acpi=off

Do not use ACPI. Note that modern systems probably will not boot if this parameter is specified.

loglevel=n

Verbosity of kernel boot-up message. n is between 0 to 7. loglevel=0 means don't print anything, loglevel=7 means print any single details. Default is n=3.

More Linux kernel parameters can be found here.


Advanced Parameters

Advanced parameters are used to fine-tune system operation at a deeper level. Once you are familiar with Fatdog64 basic operation, we recommend you to read this section. At least, read the savefile parameter - it is the most useful.

savefile

This parameter tells Fatdog64 where to find the savefile. It can be specified in three different ways:

You can choose layer from one of the following: location is split into parts - the first part is always the "command" - you have to type this as is, and the remaining parts are the "options". Here is the list of commands and their respective options.

All commands that specify a savefile path, with exception of multi, also accept a directory. If a directory is specified, the sessions will be saved into that directory (="save directory") instead of a savefile. It works if the filesystem the partition is on is ext2/3/4, for others success rate varies. The directory must already exist - Fatdog will not create and use one if it doesn't. You can use the entire partition by specifying "/" as the save directory - this would be identical to "save to partition" under Puppy Linux. (Note: Under previous version of Fatdog (Fatdog 600 and 610), the same thing is accomplished using "+" to save to partition. This is no longer supported).

Savefile can be encrypted (but not "save directory" - you can encrypt the underlying partition of save directory however). This is done by having the filename contains _crypt_, e.g. fd64save_crypt_me.ext4. This is separate and different from the :crypt option, which says that the device/partition where the savefile is, is encrypted. You can also specify _dmcrypt_, which tells Fatdog64 to access the savefile using dm-crypt (LUKS) instead of cryptoloop which is used if you use _crypt_.
As of version 811, Fatdog64 can detect LUKS encrypted savefiles automatically, so _dmcrypt_ doesn't have to be a part of the filename anymore.

You can use a keyfile to decrypt the LUKS partition - see the key{n} parameter below.

The default settings for savefile if you don't specify anything is savefile=direct:local. This approximates the behaviour of previous version of Fatdog (and Puppy Linux).

Some examples:

btrfscompress=[zlib|lzo|zstd]

This is an optional boot parameter that tells Fatdog64 to enable compression on btrfs-formatted savefile. Both zlib and zstd (the latter since kernel v5.1) can have an optional compression level, zlib 1-9 and zstd 1-15, e.g.: "btrfscompress=zlib:5". Note that if you use this parameter, the specified compression will be enabled on all btrfs devices mounted by init.

key{n}

The actual name of the parameter is actually key1, key2, key3, etc. These parameters specifies the location of keyfile used for decrypting LUKS partition or savefile. Each decryption "consumes" one key, e.g. if you put an encrypted savefile on encrypted partition, you will need to provide two keys (one for decrypting the partition, one for decrypting the savefile). The keys must be in sequential order without any gaps.

The parameter is specified as follows: key{n}=[wait:]type:id:path:[crypt]. Type can be device, label, or uuid, while id varies depending on the type.

For device, id is device id (e.g. sdb3), for label, it is the volume label of the device, and for uuid it obviously give the uuid of the device.

path gives the actual path to the keyfile, on the given device.

wait is an optional parameter that specifies that the system should give you a prompt to plugin a removable device (e.g. USB flash drive) before attempting to load the key from that device. This enables you to boot a system without the removable device plugged in, and only plug it at the time you want to load the key, and the remove it again.

crypt is an optional parameter that specifies that the device that holds the keyfile is encrypted. You can use either crypt or dmcrypt. You have to use passphrase to unlock this, you can't use another "key{n}" parameter to unlock a partition that holds another key.

The complete list of options for key{n} is:

If you specify ask, you will be asked to enter the details at boot time.

net

This parameter tells Fatdog64 to start network as early as possible, during boot time, so that it can be used to load basesfs and savefile from network locations (cifs and nbd). It also automatically enables coldplug parameter. It can be specified in two different ways:

The wait parameter (available from Fatdog 810 onwards) is optional. It just tells Fatdog to pause (requires the user to press Enter key) before the net is processed. This may be useful in case you boot from USB and you want to un-mount the USB before you are connected to network, for example.

The supported types are as follows: The device-settings depends on which types are used. The ip-address-settings determines whether you want to use dhcp or static IP address. It is optional, if you don't specify it, dhcp will be used.

basesfs

This parameter tells Fatdog64 where to find the basesfs file (fd64.sfs). It can be specified in three different ways:

option can be one of the following; they provide the same functionality as base2ram parameter (and takes precedence over it).
For details on location, please refer to the savefile here. They are mostly identical, except from Fatdog64 902 onwards, basesfs also supports the additional location type: findimg.

findimg:image-path:path
This is the path to load a basesfs that is located inside an image file, such as an ISO file (or other image type).

Notes:

base2ram=yes

This instructs Fatdog to load the basesfs into RAM. By default, basesfs is contained within the initrd itself ("humongous initrd") and is automatically to loaded to RAM; but if you use external basesfs, they are not, except when this parameter is used. This parameter is deprecated, use basesfs's direct/ram options instead.

base2ram=expand

This instructs Fatdog to uncompress the basesfs into RAM. This will work whether the basesfs is internal (in initrd) or external. Since it uses RAM to keep the uncompressed version of the basesfs, using this option implies base2ram=yes. This parameter is deprecated, use basesfs options instead.

extrasfs

This parameter tells Fatdog64 to pre-load additional SFS files right before the system starts. These SFS files are loaded after the the union filesystem has been setup, and after /etc/fstab has been processed. SFS loaded this way are not kept in permanent record, however they can be un-loaded just like others using System SFS Loader.

You can load multiple SFS-es here, separating them by comma (spaces not allowed in the names):
For details on location, please refer to the savefile here. They are identical, although for now, only device, label, uuid, local, and usb are supported, the rest do not (they will be implemented if there is popular demand for them). Alternatively, you can also specify just a fully qualified path name, to a device that has been mounted earlier in /etc/fstab. "/mnt/home" is popular. The path can be anything, it can even point to a raw device (/dev/sdb) if relevant.

Location can also be prefixed with ram which means that the given SFS will be loaded to RAM (and thus will not hog the device it is loaded from). For consistency, you can also prefix it with direct although it will do nothing.

Example: extrasfs=/mnt/home/s1.sfs,ram:/mnt/home/s2.sfs,device:sdb:/path/to/s3.sfs,/dev/sdc

The last specification will load the entire partition of /dev/sdc as an SFS.

mergeinitrd{n}

(From Fatdog 720 onwards). The actual name of the parameter is actually mergeinitrd1, mergeinitrd2, mergeinitrd3, etc. These parameters specifies the location of additional initrd which will be loaded and merged during boot process, before basesfs is processed. The main motivation for this function is to have a small initrd, merge with a huge-initrd and obtain the basesfs from that huge-initrd without having to do anything extra. Or it can be used to extend or enhance Fatdog's main initrd with additional / extra functions, that reside in an external/optional initrd.

The parameter is specified as follows: mergeinitrd{n}=[wait:]location:path:[crypt]:[init-func]. For the details on location, please refer to basesfs parameter. This parameter only supports location types of device, label, uuid, local and usb and findimg; it does not support cifs, nbd, and others.

path gives the actual path to the initrd to be merged, on the given device.

wait is an optional parameter that specifies that the system should give you a prompt to plugin a removable device (e.g. USB flash drive) before attempting to load the initrd from that device. This enables you to boot a system without the removable device plugged in, and only plug it at the time you want to load the additional initrd, and the remove it again.

crypt is an optional parameter that specifies that the device that holds the initrd is encrypted. You can use either crypt or dmcrypt.

init-func is an optional parameter that specifies the initialisation function that will be executed as soon as the merge is done. This function is sourced by the main init function, and therefore cannot fail and cannot exist. It must return once the initialisation is done.

The complete list of options for mergeinitrd{n} is:

If you specify ask, you will be asked to enter the details at boot time.

withlvm

This tells Fatdog to enable its LVM support. When LVM is enabled, Fatdog64 will recognise LVM partitions and can load savefile / basesfs from these partitions.

If a specific configuration is needed, use mergeinitrd boot option to merge and add /etc/lvm/lvm.conf during the boot process. Note that if you do so, please remember that the content of this file is not carried over to the running OS.

withmdadm

This tells Fatdog to enable its mdadm (Linux software RAID) support. When mdadm is enabled, Fatdog64 will recognise mdadm partitions and can load savefile / basesfs from these partitions. Note: mdadm is for Linux software RAID, not for FakeRAID. At the time of writing FakeRAID is not supported at boot time, although they can be accessed after boot by installing the dmraid package.

If a specific configuration is needed, use mergeinitrd boot option to merge and add /etc/mdadm.conf during the boot process. Note that if you do so, please remember that the content of this file is not carried over to the running OS.

posixovl

This tells Fatdog to use posixovl when loading non-POSIX filesystems for use as savedir or savefile. Currently this affects only CIFS and FAT/VFAT filesystems. When this is specified, you can use CIFS or FAT filesystem for save-directory with all features you expect from a POSIX filesystem (file ownership, file-mode, symlinks, hardlinks, etc).

Notes: Due to limitation of FAT and CIFS, you must always use the RAM layer when using these as save-directory; and this is enforced by Fatdog. Also, since posixovl runs in user-space, don't expect great performance. You don't need posixovl to use NTFS as save-directory, as recent versions of ntfs-3g included in Fatdog already support POSIX features directly on top of NTFS (except when you use ntfsnoperm parameter, see below).

ntfsnoperm

(From Fatdog 811 onwards) When mounting NTFS (either for savefile usage or by clicking on the drive icon), Fatdog by default uses the full NTFS permission system to map it to the POSIX permission. This enables files and directories in NTFS partition to behave as if they are located in POSIX filesystem (like ext3/ext4). One of the benefit of this, is that you can have savedir on an NTFS partition.

However, this assumes that you do not share this NTFS partition with Windows, because Fatdog will setup an NTFS permission that Windows don't understand (from Windows, the files and directories will be seen as owned by a foreign user). It is possible to map the the Fatdog NTFS user to Windows NTFS user, but the process is a little complicated. You can also choose not to map it, but each time you access these files and directories, you will have to assign yourself access to it.

If this is too troublesome, it is possible to tell Fatdog not to use the the full permission mapping and instead just use the usual uid/guid mapping (which means that all files/directories in the NTFS permission will be owned by a particular uid/guid - as specified in the Fatdog Event Manager). This is what ntfsnoperm parameter is for. Of course, when you do this, then you no longer can use savedir on NTFS. You can, however, always use savefile on an NTFS - with or without this parameter.


Advanced Troubleshooting / Debug Parameters

These parameters are listed here for completeness. Do not use them you understand what you are doing, or unless you are asked to for troubleshooting purposes. Some of them are harmless but others can cause improper functioning of Fatdog64.

coldplug

Do hardware detection and driver/module loading as early as possible at boot-time. This option is automatically enabled if you use the net parameter - it is required to load the network drives (modules) before network can be started.

loadmodules

This parameter is the opposite of blacklist. It tells Fatdog64 to load specific modules that are not automatically loaded, probably because it is not detected or because it has a conflict with others modules. Originally meant to load modules required to access save devices (the device where the savefiles are located), this command can actually load any modules. (coldplug is now the better and preferred choice to load modules required for accessing savefile, though it may take slightly longer to complete).

The syntax is: loadmodules=module1,module2,module3 and so on.

Note: separate module names by comma, and there is no space in between. If the modules are not required during boot time, don't use this parameter. Put the module names in /etc/modules (one line at a time), or load the manually by adding the appropriate command to /etc/rc.d/rc.local instead.

Note: loadmodules takes precedence over blacklist. If both loadmodules and coldplug are specified, in Fatdog64 900, modules specified in loadmodules are loaded before coldplug is executed. In earlier Fatdogs, modules are loaded after coldplug is executed.

keepvar

/var and /usr/local/var are places where system usually keep logging messages and other run-time variables. Without proper management, they can grown indefinitely big. Fatdog64 handles this by deleting all files inside them during system start-up. But sometimes the log files contains valuable messages that you want to review (especially if you have a crash), so this parameter tells Fatdog64 to "keep the files in /var" directory.

earlyshell

Get a shell as soon as it is possible to do so. You will be running in busybox environment at the beginning of the init process, just after modules have been loaded (after loadmodules/coldplug are processed), but before anything else have been done. Only /dev, /proc, and /sys are mounted. This is in contrast with earlier Fatdog / Puppy Linux "pfix=rdsh", which launches the shell after the stackable filesystem has been constructed (see below). Type "exit" to continue system startup.

Note: The shell you are running is not PID 1, you cannot switch_root inside it.

lateshell

Get a shell just after the stackable filesystem has been setup. This enables you to modify the root-to-be filesystem, for example during troubleshooting. The root-to-be filesystem is located at /aufs/new_root. You will still be running in busybox environment, in the very final stages of init process. After this, the system to switch the root to the stackable filesystem. This option is roughly equivalent to Puppy Linux "pfix=rdsh" boot option. Type "exit" to continue system startup.

Note: The shell you are running is not PID 1, you cannot switch_root inside it.

bbshell

Just like earlyshell and lateshell, except that you get the shell just before the basesfs parameter is processed. Only useful if you know what you are doing. (bbshell = before-basesfs-shell).

bbhook=/path/to/file

Source /path/to/file just before basesfs parameter is processed. (bbhook = before-basesfs-hook). bbhook is processed before bbshell. Only useful if you know what you are doing.

showerr

Show verbose error messages on screen during system boot-up. It is normal to see a lot of error messages, but most of them are harmless (or meaningless). When this option is not used, these messages are redirected to /dev/initrd.err.

debuginitrd

Trace execution of initrd. Output is shown to screen or saved to a file depending on showerr setting above.

DRV_DEBUG

Show the summary of modaliases processed. Use DRV_DEBUG=verbose to display all the modaliases as they are being processed. This parameter only has effect when coldplug is being used.

DRV_WAIT=n

Hardware detection (coldplug) is done twice (at least); n specifies how many seconds to wait between each round. The default is zero. This parameter only has effect when coldplug is being used.