config/README
=============

Configuration sequence
----------------------

Files in this directory determine the build-time configuration of
kboot.

When kboot starts, it can copy fresh versions of kboot.conf, fstab,
and hosts from the host's root file system. Whether it should do
so is asked during the configuration dialogue at build time. This
automatic update can also be disabled by passing the boot parameter
kboot=local to the kernel that runs kboot.

Not that kboot=local does not affect any explicitly named files,
such as in "message" or "authorized_keys".


Files in this directory
-----------------------

Please place the following files into this directory:

kernel-config (required)

  The .config file of a 2.6.13.1 Linux kernel that boots on the machine(s)
  kboot will run on. All features and drivers that kboot will use must be
  enabled in this kernel. Any features or drivers that kboot will
  certainly not use should be disabled. E.g., if you don't intend to
  access a network from kboot, you should disable networking.

  The kernel must not use modules.

fstab (optional)

  /etc/fstab file from the system on which kboot will boot. If this file
  is absent, kboot will not be able to automatically mount parts of the
  file system hierarchy.

  If kboot is being built on a machine different from the one from which
  fstab originates, entries that reference a UUID or a label instead a
  device (e.g., LABEL=/) should be manually converted to use only
  explicit device names.

hosts (optional)

  An /etc/hosts file containing some or all of the hosts kboot will
  access over the network. This file is optional if a name server is
  available, if only numeric addresses will be used, or if networking
  isn't used at all.

passwd (optional)

  /etc/passwd file with users who are permitted acess to the kboot
  environment through SSH. This file must contain the encrypted
  passwords of users who are allowed password-based login. All
  users must have uid 0.

authorized_keys (optional)

  Public keys of users who are permitted access to the kboot
  environment through SSH. Users whose public keys are not
  recorded in this file need to login to the kboot environment
  with a password.

  Use of this file can be overridden with the authorized_keys
  configuration variable.

ssh_host_rsa_key (optional)
ssh_host_dsa_key (optional)
dropbear_rsa_host_key (optional)
dropbear_dss_host_key (optional)

  Private hosts keys the kboot environment uses to identify itself.
  If none of these files exists, the configuration process can
  optionally copy the host keys from the build host.

  Be warned that, if using a local copy,  your host keys are only as
  safe as the kboot initramfs !

  kboot can also copy the host keys from the booted environment at
  run time. If no other source is available, kboot will, in a final
  act of desperation, generate its own keys.

kboot.conf (optional)

  Configuration file for kboot. kboot will work without this, but
  may require more typing at the boot prompt. Its content is
  described below.

message (optional)

  Banner message to display when kboot starts. This file is simply
  cat'ed to the console, so it may contain control sequences.

  Note that this file is ignored if the configuration variable
  "message" is set.

answers (optional, machine-generated)

  Answers received to questions during the configuration process.
  If this file is removed, "make config" will ask the same
  questions again.

*.bkeymap (optional)

  The binary keymap to load on the console, see the section
  "Keyboard configuration" in ../README

If any of the files in config/ is changed, run "make config" to
propagate the change, and "make" to rebuild anything that needs
updating. (Usually, at least the file kboot-root.cpio.gz will
change.)


kboot.conf
----------

When the kboot shell starts, it looks for a file kboot.conf, which
contains variable assignments. The syntax is the same as in shell
scripts. (In fact, kboot.conf is a shell script.) The following
variables have a special meaning:

authorized_keys=<path_to_file>
  File containing SSH keys authorized for passwordless access to
  the kboot environment.

  Example: authorized_keys=/root/.ssh/authorized_keys2

default=<command>
  Command to execute on timeout or if the user enters an empty
  line.

delay=<seconds>
  Like "timeout" (see below), but only applies to the very first
  keystroke. If not set, "delay" defaults to the value of
  "timeout".

  Shift and dead keys do not count as keystrokes, as far as
  "delay" is concerned.

  Delay has no effect on sessions initiated through SSH. Also,
  "default" must be set for "delay" to work.

initrd=<path_to_file>
  Initial RAM disk that is loaded by default. This can also be set
  per kernel by passing the initrd=<path_to_file> boot parameter.

message=<path_to_file>
  Message to be shown when kboot starts. Setting this variable
  overrides the default of showing config/message (if present at
  build time).

mount_rw=true
  Mount file systems read-write. By default, kboot mounts file
  systems read-only.

restricted=true
  Allows only booting of pre-defined items (note that this isn't
  really secure yet).

root=<device>
  Root device the kernel selects by default. This can also be set
  per kernel by passing the root=<device> boot parameter. If using
  the form /dev/<name>, this variable can also serve as a fallback
  if /etc/fstab does not contain a valid entry for the root file
  system.

timeout=<seconds>
  Time out after that many seconds without user input. Also
  editing the command line (without pressing [Enter]) counts
  as input.

  "timeout" does not work (and yields a warning) if "default" is
  not also set.

Any other variables define a command line, which is expanded when
the variable name (which we then call a "label") is entered as a
command at the kboot prompt. Example:

b26131="/boot/bzImage.b26131 root=/dev/sda7"

causes the input

b26131 init=/bin/sh

to be expanded to

/boot/bzImage.b26131 root=/dev/sda7 init=/bin/sh
