Documentation - Turtle Kevux - Booting and Running
Author: Kevin Day
Description: Turtle Kevux Documentation describing booting and running the system.
Keywords: Kevin Day, Kevux, FLL, Featureless, Linux, Library, Distribution, Open-Source, Turtle, Documentation

# Booting and Running

## Booting Live System

This tutorial is assuming that you have either a live-usb or a live-cdrom.
In order to boot the Live system you need to have your computer boot the device by rebooting the computer.
While booting your machine, you may have to press a key to select boot options or something of similar meaning.
Note: live-usb's cannot be directly booted to on most machines that only support usb 1.1 or less.
To boot a live-usb on a usb 1.1 system, you will need a live cdrom that contains the appropriate grub.
Available Boot Options:
`Install Kevux System
Boot Live System - Run From Memory
Boot Live System - Run From CD-Rom
Maintenance Mode
Check Memory
`

- Install Kevux System:
  This boots to a live install system that runs either from memory or from the cdrom.
  The installation system is called KiWI and includes documentation on how to install the system.
- Boot Live System - Run From Memory:
  This is the default boot option.
  This boot process will copy the compressed system into ram and run itself from ram.
  This boot process requires 384MB to 512MB of System Ram for the "everything" build.
  To calculate how much memory your particular build will require add the files sizes of the following files:
  - bin.sfs
  - lib.sfs
  - sbin.sfs
  - share.sfs
  - home.sfs
  - etc.sfs
  Once these file sizes are added up, add 70MB (for approximate runtime memory usage) to the results.
  Round the results to the nearest memory size; usually one of the following: 4, 8, 16, 32, 64, 96, 128, 192, 256, 384, 512, 768, 1024, 1536, 2048
  This boot option will take some amount of time, ~20 seconds, to copy itself into memory.
  Once the system is booted, the cdrom or usb may be removed without causing any problems.
  Once the system is booted, most/all programs start instantly or within the first 1 to 6 seconds of waiting.
- Boot Live System - Run From CD-Rom:
  This is the least flexible boot option.
  This will not copy itself into memory, saving boot time by not having to copy itself into memory.
  The downside is that much more time is lost because the system has to read the device every single time something is needed, slowing the execution process significantly.
  This boot process requires 64MB to 128MB or System Ram for the "everything" build.
  Once the system is booted, the cdrom or usb must NOT be removed or problems will occur.
  Once the system is booted, most programs will start within the 5 to 30 seconds.
- Maintenance Mode:
  This will immediately drop to the initrd bash environment.
  This allows you to manually and safely run fsck or similar commands for a particular system.
  When any of the boot options above fail, you will always be dropped into this mode.
  This is especially useful when the rootfs doesn't exist, the kernel will not lockup and you can still hit control+alt+delete
- Check Memory:
  This will start a dedicated memory tester.
  Run this for a few hours to give a decently thorough memory check.
  Reboot the machine to get out of this mode.

Advanced Kevux-Specific Boot Options

- finalroot=
  Specifies the what root device partition is to be used before starting the system.
  Unlike the standard root=, finalroot= allows for any device naming system that the mount command can use.
  The primary use of finalroot= is to boot to a device by name and not by the device's physical number.
  This is especially useful for livecd's, liveusb's, and other dynamic systems.
  Do not use root= to boot a root filesystem, if you are using a kevux initrd.
  The root= option tells the kernel to load the initrd as the first rootfs.
- finalinit=
  Specifies what the init program is to be called after switching to the finalroot.
  Do not use init= to specify the init program, if you are using a kevux initrd.
  The init= option tells the kernel to load the initrd specific init program.
- subroot=
  Allows one to load a rootfs from a specific folder inside of the finalroot device.
  This should allow one to have multiple rootfs's on a single partition.
  This can be useful for having different versions of the same system on a single partition without having any conflicts.
  Because the system will be running from withing the subroot, the final system will not be able to directly see any of the other subroots or the / of the actual partition.
- maintenance
  This tells the initrd to immediately drop to the initrd's /bin/bash.
  This normally loads the maintenance initrd.
- settings=
  This specifies a device that contains additional settings information in the same way finalroot= specifies a device.
  The additional settings information currently only supports encrypted boot settings.
  In the future, this is expected to be expanded and will also be used to perform network booting.
  All settings data is expected to be stored in the /boot/settings/ directory within the settings device.
- settingsname=
  The settings name represent a sub-directory within the /boot/settings/ directory.
  This allows for having multiple different settings data on a single settings device without conflicts.
  For example, lets say you have two sub-directories called: encrypted and network.
  By specifying the settingsname=network would mean that the network boot settings would be processed.
  By specifying the settingsname=encrypted would mean that the encrypted boot settings would be processed.
  If not settings name is passed, then the default is to use the files found within the /boot/settings/ directory and not some sub-directory.
- settingscdromsearch=
  This is identical to the cdromsearch= option explained below but only for finding the settings device.
- settingsmmcsearch=
  This is identical to the mmcsearch= option explained below but only for finding the settings device.
- runlevel=
  Use this to execute a specific set of init instructions during system boot.
  These instructions are defined in /etc/initng/runlevel/.
  The default runlevel is called: /etc/initng/runlevel/default.runlevel.
  The KiWI installer uses the runlevel called: /etc/initng/runlevel/kiwi.runlevel.
  Example:
  If you wish to boot to a runlevel called single (/etc/initng/runlevel/single.runlevel), you would use the boot command: runlevel=single.
- squashboot=
  This tells the initrd to execute the live_init script using the squash compressed files.
  When this is specified, the finalroot= option is expected to be the partition, cdrom, or some device where the squash files are located.
  The squash files are expected to be in the directory /boot/live/ of the finalroot device.
  There are the following parameters available:
  - device - this means run the squash files directly from the finalroot device
  - memory - this means copy the squash files into memory and run from memory
  - extract - this means extract the squash files into memory and run from memory
  The live_init defines an entirely new set of options explicitly useful for booting a livecdrom, a liveusb, or any system compressed into squash files
  Squash Specific Boot Options
  - squashpath=
    Specify a subdirectory or path on the finalroot= device that contains the squash files.
    This applies to both squashboot and squishboot boot modes.
  - filesystemlimit=
    Specify a hard limit on how large the memory filesystem will be.
    By default, no limit is set.
    The Boot Live System - Run From Memory (uncompressed) boot option does set a size limit that is over a 1GB
  - etcdevice=
    Specify the physical partition that contains the etc directory.
    This will be mounted to the /etc directory of the finalroot system.
    For using an ecrypted partition, this should be set to something like: `etcdevice=/dev/mapper/etc`
  - homedevice=
    Specify the physical partition that contains the home directory.
    This will be mounted to the /home directory of the finalroot system.
    For using an ecrypted partition, this should be set to something like: `homedevice=/dev/mapper/home`
  - vardevice=
    Specify the physical partition that contains the var directory.
    This will be mounted to the /var directory of the finalroot system.
    For using an ecrypted partition, this should be set to something like: `vardevice=/dev/mapper/var`
  - tmpdevice=
    Specify the physical partition that contains the tmp directory.
    This will be mounted to the /tmp directory of the finalroot system.
    For using an ecrypted partition, this should be set to something like: `tmpdevice=/dev/mapper/tmp`
  - xorg=
    Manually specify whether or not xorg should be started on boot.
    Whether or not this works is explicitly dependent on whether or not any of the boot terminals are set to auto-start.
    The default action is to auto-start a terminal on tty1 and that terminal will start xorg.
    There are the following parameters available:
    - yes - this means to start xorg if terminal auto-start is enabled on the system. (this is the default)
    - no - this means do not start xorg if terminal auto-start is enabled on the system and therefore only a terminal is started.
  - share=
    Specify whether or not to make the share available on a live system.
    For the squashinit=extract and squashinit=memory commands, more memory than normal is needed to cope with the additional space needed for the share.
    There are the following parameters available:
    - yes - this means to include the share.sfs file when booting the live system. (this is the default)
    - no - this means to not include the share.sfs file when booting the live system, saving memory.
  - toolchain=
    Specify whether or not to make the toolchain available on a live system.
    For the squashinit=extract and squashinit=memory commands, more memory than normal is needed to cope with the additional space needed for the toolchain.
    Use this for compilation software such as gcc.
    There are the following parameters available:
    - yes - this means to include the toolchain.sfs file when booting the live system.
    - no - this means to not include the toolchain.sfs file when booting the live system, saving memory. (this is the default)
  - documentation=
    Specify whether or not to make the documentation available on a live system.
    For the squashinit=extract and squashinit=memory commands, more memory than normal is needed to cope with the additional space needed for the documentation.
    There are the following parameters available:
    - yes - this means to include the documentation.sfs file when booting the live system.
    - no - this means to not include the documentation.sfs file when booting the live system, saving memory. (this is the default)
  - package=
    Specify whether or not to make the package available on a live system.
    For the squashinit=extract and squashinit=memory commands, more memory than normal is needed to cope with the additional space needed for the package.
    Use this for package management (installing and uninstalling software).
    There are the following parameters available:
    - yes - this means to include the package.sfs file when booting the live system.
    - no - this means to not include the package.sfs file when booting the live system, saving memory. (this is the default)
  - python=
    Specify whether or not to make the python available on a live system.
    For the squashinit=extract and squashinit=memory commands, more memory than normal is needed to cope with the additional space needed for the python.
    There are the following parameters available:
    - yes - this means to include the python.sfs file when booting the live system.
    - no - this means to not include the python.sfs file when booting the live system, saving memory. (this is the default)
  - perl=
    Specify whether or not to make the perl available on a live system.
    For the squashinit=extract and squashinit=memory commands, more memory than normal is needed to cope with the additional space needed for the perl.
    There are the following parameters available:
    - yes - this means to include the perl.sfs file when booting the live system.
    - no - this means to not include the perl.sfs file when booting the live system, saving memory. (this is the default)
  - install=
    Specify whether or not to make the installation files available on a live system so that installation may properly function.
    You should also specify runlevel=kiwi to boot to the installation program.
    There are the following parameters available:
    - kiwi - this means that the squash installation files are at the /boot/live directory of the final root device. (this is the default)
    - /path/to/installation/directory - this means that the installation squash files are the specified path of the final root device. (this must begin with a leading slash)
  NOTE: Nothing can be written to the primary system files when squashinit=device and squashboot=memory are used.
  NOTE: When squashboot=extract is used, these files can be written to, but will be lost during reboots.
- squishboot=
  This is a hybrid between booting with squashboot and normal boot.
  Instead of running the entire system from squash files, only the primary binaries /bin, /sbin, /lib, and /toolchain are mounted via squash.
  Everything else is expected to be on the final root fs, already extracted.
  This allows for having compressed binaries on a small device while maintaining normal write behavior for most things.
  This method requires much less ram than squashboot.
  The squash files are expected to be in /live/boot/ of the final root system by default.
  Most of the additionaly squashboot options are supported and are renamed from squash to squish accordingly.
  For parameter conflict resolution, squishboot will override squashboot.
  This is particularly useful for embedded devices and the OLPC-XO.

## What Should Happen

When all things work correctly, you should end up sitting on an XFCE desktop screen with a backgroup picture of a stream in a forest.
This is the default desktop environment and the default layout.
Enjoy.
If you do not want a graphical display to appear on system startup, then you can append xorg=no as a kernel boot parameter.

## Something Went Wrong

Unfortunately, not all things work all of the time.
Whenever something goes wrong with the boot process, you will get stuck with a login prompt.
In order to Login, see Logging In Below.
Okay, so the system started up but you are not sitting in a graphical XFCE desktop with the kevux logo in the background.
In this situation, the most probably cause is that the Xorg (and therefore XFCE) failed to start.
The most common cause of this is a video card problem.
To fix this problem, you will need to manually tell xorg to use your particular video card or use vesa.
WARNING: This may require some moderate to advanced knowledge of the linux command line and understanding of what your video card specifically is.
If the system is not responding then you may need to be able to boot the system without xorg, so add the xorg=no boot parameter in the grub config at boot time.
Once you find a way to login you need to edit the /etc/X11/xorg.conf file to work with your appropriate video card.
To add your video card to the xorg.conf file, scroll to the bottom of that file looking for the part that begins with Section "Device"
Inside of this section, look for the part that begins with #Driver
Uncomment this line by removing the leading #.
On the same line, to the immediate right, you should see something text surrounded in double quotes.
Replace that text with the appropriate video card driver name.
If you do not know the proper driver then you will have to do some researching or asking for assistance as determining this is advanced and may be complex.
You may be able to identify your video card by running the command lspci and looking for a line that has VGA Compatible controller or Display controller.
For the actual login process, see the Logging In below.
If all else fails and you still cannot get into the system, try booting into maintenance mode by passing the grub command line option: maintenance.
However, using maintenance mode almost definitely requires advanced to expert knowledge.

## Logging In

The login screen is pretty straight-forward.
Just type in your username and you will be prompted for a password.
The default username is turtle
The default password is kevux\
Do not forget the trailing slash: \

Immediately following a successful login, you will be prompted for the particular type of login.
Login Types:
Terminal - Drop to a Terminal (Console).
Webbrowser - Drop to a command-line webbrowser (Console).
Xorg - Start Xorg (Graphical Display) using the manager defined in ~/.xinitrc (This is the default).

If you selected Terminal, then you will see a login prompt where you can type in any console commands you desire.
This console environment uses the bash shell.

## Virtual Machines

Running Kevux on a virtual machine is pretty straight-foward and therefore only known issues will be listed here.
Physical Address Extension, aka PAE, is used by this system.
If the virtual machine does not have PAE, support enabled, then the system will not boot.
Hardware Virtualization features such as VT-z/AMD-V, are know to prevent GRUB from booting properly.
If for any reason your system does not boot, try disabling VT-z/AMD-V, support.