root/tags/6.2-1/doc/README

This is version [version] of the official Linux From Scratch LiveCD.

PACKAGES
===========================
Available packages on this CD for your use:

Xorg (X Window System Environment)

Window Managers
* xfce 

Web Tools
* wget (command line file retriever)
* curl (command line file retriever)
* lynx (text web browser)
* w3m (text web browser)
* irssi (console irc client, unstable version)
* mozilla (graphical web browser, mail and news reader and irc client)
* xchat (x-based irc client)
* GAIM (multiprotocol x-based chat client)
* msmtp (SMTP client for use with mutt and tin)
* mutt (console mail and news reader)
* tin (console news reader)

Text Editors
* vim
* nano (unstable version)
* joe

Network Tools
* SSH server & client
* NFS server & client
* Samba (client only)
* Subversion
* cvs
* pppd
* rp-pppoe
* dhcpcd
* ncftp
* traceroute
* rsync

Filesystem Programs
* e2fsprogs
* reiserfsprogs
* reiser4progs
* xfsprogs

Debugging Programs
* strace

Boot Loaders (only those applicable to the arch of the LiveCD)
* grub, lilo, yaboot

Other Programs
* distcc
* gpm (console mouse)
* pciutils
* mdadm
* LVM2
* dmraid
* hdparm
* xlockmore

jhalfs
(A tool for extracting commands from the Linux From Scratch book and creating
Makefiles that can download, check and build each LFS package for you.)

CONFIGURING NET CONNECTION
===========================
The LiveCD attempts to detect the network cards present in the system.
On each detected network card, dhcpcd is automatically started in the
background. If it is not correct to acquire the network settings via DHCP
in your location, or if you want to use dialup or GPRS connection, run the
"net-setup" command.

CONFIGURING X
===========================
The LiveCD attempts to configure X for your video card automatically. The
process may fail if you have more than one video card, if your video card
doesn't support 24-bit color depth, or if your monitor is not Plug-n-Play
compatible (in other words, doesn't tell its characteristics to Xorg via DDC).
Also, in the following cases, the autodetection process is known to suggest
a non-working driver even for 2D graphics:

    * ATI Radeon X1000 or higher (needs "vesa" or proprietary "fglrx" driver)
    * Any NVIDIA card with the monitor connected to the DVI output (needs
      "vesa" or proprietary "nvidia" driver).

In such cases, you have to edit the /etc/X11/xorg.conf file manually, using
vim, joe or nano.

1) In Section "Device", specify the driver for your video card, e.g.:

Section "Device"
        Identifier      "Generic Video Card"
        Driver          "ati"
EndSection

Installers of proprietary video drivers are available in /lfs-sources as *.run
files. IMPORTANT: in order to avoid wasting RAM by the device mapper,
change the current directory to /dev/shm before installing these drivers.

2) In Section "Monitor", specify the allowed frequency ranges for your
monitor. If unsure, consult the manual that came with your monitor. If
such information is not there, but you know a working resolution and refresh
rate, run the "gtf" command. E.g., if your monitor can handle 1280x1024@85Hz:

$ gtf 1280 1024 85

Note: you must specify the refresh rate of 60 Hz for LCD monitors.

Then look at the output:

# 1280x1024 @ 85.00 Hz (GTF) hsync: 91.38 kHz; pclk: 159.36 MHz
Modeline "1280x1024_85.00"  159.36  1280 1376 1512 1744  1024 1025 1028 1075 -HSync +Vsync

Put the synchronization ranges that contain the printed values. For the above
example, this means that the following information should be added in the
"Monitor" section:

Section "Monitor"
        Identifier      "Generic Monitor"
        Option          "DPMS"
        HorizSync       30-92   # because gtf said "hsync: 91.38 kHz"
        VertRefresh     56-86   # because a 85 Hz mode has been requested
        # the Modeline may also be pasted here
EndSection

3) In the Section "Screen", change the DefaultDepth and add the "Modes"
line to SubSection "Display" with the proper color depth. If you added custom
Modelines, you have to specify them exactly as defined, i.e. "1280x1024_85.00"
in the example above. The built-in Modelines have names similar to "1024x768",
without explicit specification of the refresh rate.

When you are finished editing /etc/X11/xorg.conf, run startx.

CUSTOMIZING THE CD CONTENTS
===========================
It is possible to burn a customized version of the official Linux From
Scratch LiveCD, with your own files added. To do that, follow the
instructions below.

* Burn the official CD in multi session mode:
    cdrecord dev=/dev/cdrom -v -multi -tao lfslivecd-[version].iso

* Prepare a directory with the files you want to add, delete or change:
    mkdir second-session && cd second-session
    vim path/to/new-file
    vim path/to/file-to-be-changed
    echo path/to/file1-to-be-deleted >.delete
    echo path/to/file2-to-be-deleted >>.delete
    cd ..

* Make an image contatining those files:
    mkisofs -l -M lfslivecd-[version].iso \
        -C `cdrecord -msinfo dev=/dev/cdrom` \
        -R -o second-session.iso second-session

* Append the image you just created to the official Linux From Scratch
  LiveCD:
    cdrecord dev=/dev/cdrom -v -multi -tao second-session.iso


AUTOSSHD
============================
It is possible to start the sshd daemon automatically upon boot. To do that,
you have to customize the CD as described above. Add the following files:

* /.autosshd
    This is the file that indicates that the sshd daemon should be
    started automatically. It should be empty.

* /root/.ssh/authorized_keys
    Add your public key to that file in order to be able to log in.
    Alternatively, modify /etc/shadow.

* /etc/shadow
    Edit this file if you want to allow root to login using a password via
    ssh. It is more secure to use public key based authentication instead.

* /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key
    Create those files as described in the ssh-keygen(1) manual page. If you
    don't do that, random host keys will be generated for you automatically
    during the boot process. This is less secure, because you can't verify
    them.

* /etc/sysconfig/network-devices/ifconfig.eth0
    Configure a known static IP address there, as described in the LFS book,
    section "7.12. Configuring the network Script".

* /etc/udev/rules.d/50-network.rules
    Create an empty file in order to prevent udev from running dhcpcd.

INTERNATIONALIZATION
============================
It is possible to specify the locale using the bootloader prompt, like this:

  linux LANG=es_ES@euro

The CD tries to guess the proper screen font and keymap based on this
information. If the guess is wrong, you can override it by adding the
following parameters:

  KEYMAP: specifies the console keymap(s) to load (actually the arguments to
  the "loadkeys" program separated by the "+" sign), e.g: KEYMAP=es+euro1

  LEGACY_CHARSET: sometimes a ready-made UTF-8 keymap is not available and
  must be obtained by converting an existing keymap from this charset to UTF-8.
  E.g.: LEGACY_CHARSET=iso-8859-15
  This parameter is not used in non-UTF-8 locales.

  FONT: specifies the screen font to set (actually, the arguments to the
  "setfont" program separated by the "+" sign), e.g:
  FONT=LatArCyrHeb-16+-m+8859-15

  XKEYMAP: the keymap to use with X window system, e.g. XKEYMAP=us

Alternatively, these items can be configured interactively using dialog-based
interface if the locale is not specified on the boot prompt.

For some locales (e.g. lv_LV.ISO-8859-13) there is no valid console keymap,
but there is a keymap for X. In this case, the only solution is to use X.

While this CD configures the LANG environment variable, console font and
keymap for you, it's your responsibility to configure other locale-dependent
parameters manually. You may want to configure character sets for SAMBA in
/etc/samba/smb.conf, and to explicitly specify the "iocharset" and "codepage"
options when mounting filesystems with Windows origin (e.g., vfat and isofs).

The CD contains TrueType fonts that cover the orthography of most of European
and some Asian languages. No additional configuration is required in order to
use these fonts.

Use of this LiveCD with Chinese, Japanese or Korean language requires that
your monitor has at least 80 pixels per inch in order for hieroglyphs to
be recognizable (i.e., at least 12 pixels high). This means the following
minimum resolution:

    15" => 1024x768
    17" => 1024x768
    19" => 1280x1024
    20" => 1280x1024

If your monitor cannot handle such resolution, edit the
/etc/X11/xinit/xserverrc file with vim, nano or joe, and add the -dpi 94
parameter to the X server command line there.

BRAILLE DISPLAY SUPPORT
===========================
The LiveCD includes the "brltty" program that allows a blind person to read
the contents of Linux text console on a Braille display. In order to
activate it:

* Insert the CD into the drive, reboot the computer. The BIOS will produce
  a beep, indicating successful power-on self-testing. Then it will load
  the boot loader from the CD, and the boot loader will produce a second beep.
* After the second beep, type:

linux brltty=eu,ttyS0

  This example assumes that the EuroBraille device is connected to the
  first serial port. For other device types, the brltty parameter will
  be different.

Note: in some locales, brltty displays incorrect Braille patterns. This is
related to the fact that Braille tables in brltty are indexed with
encoding-dependent byte representing the character. Such representation
becomes invalid when another encoding for the same language is used.
E.g., that's why the "ru" table (designed for KOI8-R encoding) produces
wrong result in the ru_RU.CP1251 locale.

Known non-working cases:
    All CP1251-based locales (no CP1251 Braille table in brltty)
    zh_TW (configuration instructions available in Chinese only)
    All other Chinese, Japanese and Korean locales (no support in brltty)

If brltty displays incorrect Braille patterns displays incorrect Braille
patterns in your locale, please revert to the en_US locale, thus avoiding
the use of non-ASCII characters. If you know how to fix this problem
for your locale, mail this information to livecd@linuxfromscratch.org.

RESUMING THE BUILD
===========================
There is a hint "How to resume your work after a break at different
LFS stages" available at:

http://www.linuxfromscratch.org/hints/downloads/files/stages-stop-and-resume.txt

Instructions from there should work on this CD, however, there is a simpler
(but highly experimental) method described below.

1) Make sure you have (or are planning to create) a swap partition not used
   by other Linux systems installed on your hard drive. The text below assumes
   that /dev/hda2 is your (existing or planned) swap partition.

2) Pass "resume=/dev/hda2" as one of the kernel arguments when booting this CD.
   I.e., the complete boot line may look as:
   linux LANG=ru_RU.UTF-8 TZ=Asia/Yekaterinburg resume=/dev/hda2

3) In chapter 2, the book tells you to create (if you didn't do it already),
   format that partition with mkswap, and activate it with swapon. Follow the
   instructions in the book.

4) If you use X window system, take the following into account:
   * Users of old S3 video cards should uncomment the "EnableVbetool" line
     in the /etc/hibernate/common.conf file.
   * Hibernation is incompatible with the proprietary "nvidia" driver.

5) Follow the book as your time permits.

6) When your time runs out, execute the "hibernate" command as root. It is not
   necessary to stop the compilation, but running this command during a
   testsuite may lead to failures that would not occur otherwise.

NOTE: you must unmount all USB flash drives and all partitions used by other
operating systems installed on your computer before hibernating! Don't
attempt to mount partitions used by a hibernated system from other systems
(even read-only, because there is no true read-only mount on journaled
filesystems)!

7) The computer will save its state to your swap partition and power down.
   This CD will remain in the drive.

8) When you are ready to resume the build, boot this CD again and pass exactly
   the same "vga=..." and "resume=..." arguments that you used earlier.

9) The computer will load its state from the swap partition and behave as if
   you didn't power it off at all (except breaking all network connections).
   The build will automatically continue.

The procedure is a bit more complicated if your swap is on a LVM volume
or on software RAID. In this case, instead of passing the resume=... argument,
you should boot the CD as usual and make actions needed for the kernel to see
the swap device (for LVM, that's "vgchange -ay"). After doing that, note
the major and minor device number for that device (assigning persistent numbers
is highly recommended), and echo them to /sys/power/resume. E.g., for LVM:

# ls -lL /dev/myvg/swap
brw------- 1 root root 254, 3 2006-07-10 17:51 /dev/myvg/swap
# echo 254:3 >/sys/power/resume

In the case of the first boot, this will print an error, but store the device
numbers to be used for hibernation. Ignore the error and hibernate when needed.

On the second boot (i.e., after hibernating), this "echo" command will restore
the computer state from the swap device.

THANKS
===========================
Many thanks to all whose suggestions, support and hard work have helped create
this CD.