r866 - html/trunk/livecd

jhuntwork at linuxfromscratch.org jhuntwork at linuxfromscratch.org
Sat Apr 14 21:34:09 PDT 2007

Author: jhuntwork
Date: 2007-04-14 22:34:08 -0600 (Sat, 14 Apr 2007)
New Revision: 866

Removed outdated 'LiveCD Documentation' and replaced with information from the current README from 6.2-5

Modified: html/trunk/livecd/documentation.html
--- html/trunk/livecd/documentation.html	2007-04-15 03:12:24 UTC (rev 865)
+++ html/trunk/livecd/documentation.html	2007-04-15 04:34:08 UTC (rev 866)
@@ -3,80 +3,319 @@
 <!--#include virtual="menu.html" -->
     <div class="main">
      <h1>LFS LiveCD Documentation</h1>
-     <h2>Introduction</h2>
-	<p>The main purpose of this page is to document the process of making the official LFS livecd. Specifically,
-           how it differs from previous cds produced from existing <a href="../hints/whatarehints.html">LFS hints</a>. The notes here will deal
-	   mostly with the x86 cd, as the ppc cd is a bit different in some areas and is still under development.
-	   This page should not be considered a full hint, although it may progress to that point in the future.</p>
+       <p>Documentation for version x86-6.2-5 of the official Linux From Scratch LiveCD.</p>
+       <h2>Packages</h2>
+         <p>Available packages on this CD for your use:</p>
+         <ul>
+          <li>Xorg (X Window System Environment)</li>
+          <li>Window Managers
+             <ul> <li>xfce </li></ul>
+          </li>
+          <li>Web Tools
+	    <ul>
+		<li>wget (command line file retriever)</li>
+		<li>curl (command line file retriever)</li>
+		<li>lynx (text web browser)</li>
+		<li>w3m (text web browser)</li>
+		<li>irssi (console irc client, unstable version)</li>
+		<li>mozilla (graphical web browser, mail and news reader and irc client)</li>
+		<li>xchat (x-based irc client)</li>
+		<li>GAIM (multiprotocol x-based chat client)</li>
+		<li>msmtp (SMTP client for use with mutt and tin)</li>
+		<li>mutt (console mail and news reader)</li>
+		<li>tin (console news reader)</li>
+	    </ul></li>
+	  <li>Text Editors
+	   <ul>
+		<li>vim</li>
+		<li>nano (unstable version)</li>
+		<li>joe</li>
+	   </ul></li>
+	  <li>Network Tools
+            <ul>
+		<li>SSH server & client</li>
+		<li>NFS server & client</li>
+		<li>Samba (client only)</li>
+		<li>Subversion</li>
+		<li>cvs</li>
+		<li>pppd</li>
+		<li>rp-pppoe</li>
+		<li>dhcpcd</li>
+		<li>ncftp</li>
+		<li>traceroute</li>
+		<li>rsync</li>
+	    </ul></li>
+	  <li>Filesystem Programs
+	    <ul>
+		<li>e2fsprogs</li>
+		<li>reiserfsprogs</li>
+		<li>reiser4progs</li>
+		<li>xfsprogs</li>
+		<li>dosfstools</li>
+		<li>ntfsprogs</li>
+	    </ul></li>
+	  <li>Debugging Programs
+	    <ul><li>strace</li></ul></li>
+	  <li>Boot Loaders
+	    <ul>
+		<li>grub</li>
+		<li>lilo</li>
+	    </ul></li>
+	  <li>Other Programs
+	    <ul>
+		<li>distcc</li>
+		<li>gpm (console mouse)</li>
+		<li>pciutils</li>
+		<li>mdadm</li>
+		<li>LVM2</li>
+		<li>dmraid</li>
+		<li>hdparm</li>
+		<li>parted</li>
+		<li>xlockmore</li>
+		<li>jhalfs (A tool for extracting commands from the Linux From Scratch book and automating the build. NOTE: This tool is designed for LFS developers; Support for those not experienced with building LFS manually is not guaranteed.)</li>
+	     </ul></li>
+	  </ul>
+	<h2>Iportant Note About the Kernel</h2>
+          <p>The original LFS book recommends using "the latest available 2.6.16.x kernel
+	     version" and gives a link to linux- However, at the time of the
+	     release of this CD, the latest linux-2.6.16.x version is For the
+	     convenience of jhalfs users, the LFS book on this CD has been patched
+	     to include this kernel version.
+	  </p>
+         <p>Further kernel updates may be available in the form of compressed incremental
+	    patches from <a href="http://www.kernel.org/pub/linux/kernel/v2.6/incr/">http://www.kernel.org/pub/linux/kernel/v2.6/incr/</a>.
+	    It is recommended that you apply them.</p>
-	<p>The process of making an LFS livecd is actually fairly straightforward. I've broken it down into six basic steps:</p>
-	  <ol>
-	    <li>Build a base LFS system according to the usual <a href="../lfs/view/stable/">procedure</a>.</li>
-	    <li>Add wanted additional packages with the help of <a href="../blfs/">BLFS</a>.</li>
-	    <li>Modify your bootscripts and tweak system settings to meet your needs.</li>
-	    <li>Create an initial script/program that will set up your special environment.</li>
-	    <li>Configure your bootloader.</li>
-	    <li>Package it all up into an iso.</li>
-	  </ol>
-	<p>Of course, that is simplifying it a bit, but you get the idea. The official cd uses two new concepts that are not,
-	   to my knowledge, included in any of the hints. They are: Squashfs and Initramfs. These two technologies are central to what
-	   makes the official LFS cd work.</p>
-      <h2>Squashfs</h2>
-	<p>Project homepage: <a href="http://squashfs.sourceforge.net">http://squashfs.sourceforge.net</a></p>
-	<p>Squashfs is a compressed read-only filesystem for Linux. It is mounted as a loop device and files are uncompressed
-	   and read from the squashfs archive as they are needed. I've seen squashfs produce nearly 50% compression.
-	   Needless to say, squashfs is what allows me to pack so many packages onto the cd. The documentation for squashfs is
-	   pretty good and it is easy to get yourself up and running with it. Using it basically amounts to patching your kernel
-	   to support the squashfs filesystem and creating squashfs archives. From the top of the lfs partition, what will
-	   become the iso, I ran these commands:</p>
-	<div class="cmd">
-	  <p>mksquashfs usr usr_sqfs</p>
-	  <p>mksquashfs opt opt_sqfs</p>
-	</div>
-	<p>That creates two squashfs archives containing all of the usr and opt directories from your new LFS system. The /usr
-	   directory will by far be your largest after building LFS according to the book. You can now delete (or better yet,
-	   move to a safe location) the /usr and /opt directories from the lfs partiton. You will also need to add a bootscript
-	   that mounts those directories early on in the boot process.  You would mount them like this:</p>
-	<div class="cmd">
-	  <p>mount usr_sqfs /usr -o loop</p>
-	  <p>mount opt_sqfs /opt -o loop</p>
-	</div>
-      <h2>Initramfs</h2>
-	<p>As you know, a cdrom is read-only. That presents a bit of a challenge for producing a working Linux system
-	   based entirely on a cd. You need <em>some</em> writable directories to be able to do anything. If you are
-	   already familiar with creating live cds you know that one of the best ways to solve this problem is to use
-	   ramdisks and mount them to your tree.  Often, this was done using a script called linuxrc that the kernel
-	   would invoke after it scans your hardware. To get everything exactly as we wanted, we would have to chroot
-	   and pivot_root and all sorts of other little tricks.</p>
-	<p>With the 2.6 kernels initramfs becomes available. The documentation for initramfs is a little scarce, but it
-	   basically boils down to a replacement for initrd.  It's a filesystem that is compiled into the kernel itself
-	   and should contain at the root level a file called 'init'.  The kernel will mount your initramfs image to / in 
-	   RAM and when it is finished probing your hardware it will look for init and run it.  The init should contain
-	   instructions for setting up your custom environment.</p>
-	<p>The LFS LiveCD uses a C file for init. It sets up your directory structure under /, finds and mounts
-	   the LFS LiveCD, makes essential symlinks to read-only directories on the cd and starts udev to create
-           device nodes for the system.  Finally, it passes control over to sysvinit to finish the boot process.</p>
-	<p>You can view the init file here: <a href="http://wiki.linuxfromscratch.org/livecd/browser/trunk/initramfs/init.c?rev=1387&format=txt">init.c</a></p>
-	<p>If you wish to build the entire initramfs for inclusion in your custom kernel, you can do so like this
-	   (Note: these commands assume you have subversion and cpio installed. If you don't you can build them according to
-	   the instructions in BLFS):</p>
-	<div class="cmd">
-	  <p>svn co svn://svn.linuxfromscratch.org/livecd/trunk/initramfs/</p>
-	  <p>cd initramfs</p>
-	  <p>make</p>
-	</div>
-	<p>Now you will want to copy the new initramfs over to your kernel source to be included in the kernel image.</p>
-	<div class="cmd">
-	  <p>cp initramfs_data.cpio.gz [path_to_kernel_source]/usr/</p>
-	  <p>touch [path_to_kernel_source]/usr/initramfs_data.cpio.gz</p>
-	</div>
-	<p>Now when you make your kernel, the new initramfs will be included in the image. If you use the official
-	   init.c as I've shown above, be sure to create a file named 'LFS' in the root of your iso tree like so:</p>
-	<div class="cmd">
-	  <p>echo "LFS-6.0-LIVECD" > LFS</p>
-	</div>
-	<p>This is necessary because the init looks for that file containing that string to ensure that it has found
-	   the correct cd drive (the one that contains the livecd) before it mounts the cdrom.</p>
+	<h2>Configuring a Network Connection</h2>
+	  <p>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
+	   <b>net-setup</b> command.</p>
+	<h2>Configuring Xorg</h2>
+	  <p>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:</p>
+	<ul><li>ATI Radeon X1000 or higher (needs the "vesa" driver)</li></ul>
+	<p>In such cases, you have to edit the /etc/X11/xorg.conf file manually, using
+	  vim, joe or nano:</p>
+	<p>1.  In Section "Device", specify the driver for your video card, e.g.:
+	  <div class="cmd"><pre>
+  Section "Device"
+        Identifier      "Generic Video Card"
+        Driver          "vesa"
+  EndSection</pre></div>
+	<p>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 at 85Hz:
+	</p>
+	  <div class="cmd"><pre>  $ gtf 1280 1024 85</pre></div>
+	<p>Note: you must specify the refresh rate of 60 Hz for LCD monitors.</p>
+	<p>Then look at the output:</p>
+	<div class="cmd"><pre>
+  # 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</pre></div>
+	<p>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:</p>
+<div class="cmd"><pre>
+  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</pre></div>
+	<p>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.</p>
+	<p>When you are finished editing /etc/X11/xorg.conf, run startx.</p>
+	<h2>Customizing the CD Contents</h2>
+	<p>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 in the <b>/root/lfscd-remastering-howto.txt</b> file.</p>
+	<h2>Auto-sshd</h2>
+	<p>It is possible to start the sshd daemon automatically upon boot. To do that,
+	  you have to customize the CD. Create the following files:</p>
+	<dl>
+	 <dt>/.autosshd</dt>
+    	   <dd>This is the file that indicates that the sshd daemon should be started automatically. It should be empty.</dd>
+	 <dt>/root/.ssh/authorized_keys</dt>
+    	   <dd>Add your public key to that file in order to be able to log in. Alternatively, modify /etc/shadow.</dd>
+	 <dt>/etc/shadow</dt>
+	   <dd>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.</dd>
+	 <dt>/etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key</dt>
+    	   <dd>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.</dd>
+	 <dt>etc/sysconfig/network-devices/ifconfig.eth0</dt>
+   	   <dd>Configure a known static IP address there, as described in the LFS book,
+	    section "7.12. Configuring the network Script".</dd>
+	</dl>
+	<h2>Internationalization</h2>
+	<p>It is possible to specify the locale using the bootloader prompt, like this:</p>
+	<div class="cmd"><pre>  linux LANG=es_ES at euro</pre></div>
+	<p>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:</p>
+  	  <p><b>KEYMAP:</b> specifies the console keymap(s) to load (actually the arguments to
+  	  the "loadkeys" program separated by the "+" sign), e.g:</p>
+	  <div class="cmd"><pre>  KEYMAP=es+euro1</pre></div>
+  	  <p><b>LEGACY_CHARSET:</b> 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.
+  	  This parameter is not used in non-UTF-8 locales.
+  	  E.g.:</p>
+	  <div class="cmd"><pre>  LEGACY_CHARSET=iso-8859-15</pre></div>
+	  <p><b>FONT:</b> specifies the screen font to set (actually, the arguments to the
+  	  "setfont" program separated by the "+" sign), e.g:
+	  </p>
+	  <div class="cmd"><pre>  FONT=LatArCyrHeb-16+-m+8859-15</pre></div>
+  	  <p><b>XKEYMAP:</b> the keymap to use with X window system, e.g.:</p>
+	  <div class="cmd"><pre>  XKEYMAP=us</pre></div>
+	<p>Alternatively, these items can be configured interactively using dialog-based
+	  interface if the locale is not specified on the boot prompt.</p>
+	<p>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.</p>
+	<p>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).</p>
+	<p>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.</p>
+	<p>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:</p>
+	<ul>
+    	 <li>15" => 1024x768</li>
+    	 <li>17" => 1024x768</li>
+    	 <li>19" => 1280x1024</li>
+	 <li>20" => 1280x1024</li>
+	</ul>
+	<p>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.</p>
+	<h2>Braille Display Support</h2>
+	<p>The LiveCD includes the <b>brltty</b> program that allows a blind person to read
+	   the contents of Linux text console on a Braille display. In order to
+	   activate it:</p>
+	<ul>
+	  <li>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.</li>
+	  <li>After the second beep, type:</li>
+	</ul>
+	<div class="cmd"><pre>  linux brltty=eu,ttyS0</pre></div>
+	<p>This example assumes that the EuroBraille device is connected to the
+	first serial port. For other device types, the brltty parameter will
+	be different.</p>
+	<p>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.</p>
+	<p>Known non-working cases:</p>
+	<ul>
+	 <li>All CP1251-based locales (no CP1251 Braille table in brltty)
+	 </li>
+	 <li>zh_TW (configuration instructions available in Chinese only)
+	 </li>
+	 <li>All other Chinese, Japanese and Korean locales (no support in brltty)
+	 </li>
+	</ul>
+	<p>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 at linuxfromscratch.org.
+	</p>
+	<h2>Resuming a LFS Build</h2>
+	<p>There is a hint "How to resume your work after a break at different
+	LFS stages" available at:
+	<a href="http://www.linuxfromscratch.org/hints/downloads/files/stages-stop-and-resume.txt">
+	http://www.linuxfromscratch.org/hints/downloads/files/stages-stop-and-resume.txt</a>
+	Instructions from there should work on this CD, however, there is a simpler
+	(but highly experimental) method described below.</p>
+	<p>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.
+	  </p>
+	<p>Pass "resume=/dev/hda2" as one of the kernel arguments when booting this CD.
+   	I.e., the complete boot line may look as:</p>
+	<div class="cmd"><pre>  linux LANG=ru_RU.UTF-8 TZ=Asia/Yekaterinburg resume=/dev/hda2</pre></div>
+	<p>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.</p>
+	<p>4.  If you use X window system, take the following into account:</p>
+	  <ul><li>Users of old S3 video cards should uncomment the "EnableVbetool" line
+    	    in the /etc/hibernate/common.conf file.</li>
+   	   <li>Hibernation is incompatible with the proprietary "nvidia" driver.</li>
+	  </ul>
+	<p>5.  Follow the book as your time permits.</p>
+	<p>6.  When your time runs out, execute the <b>hibernate</b> 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.</p>
+	<p><em>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
+	<p>7.  The computer will save its state to your swap partition and power down.
+   	 This CD will remain in the drive.</p>
+	<p>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.</p>
+	<p>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.</p>
+	<p>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:</p>
+<div class="cmd"><pre>
+  # 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
+	<p>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.</p>
+	<p>On the second boot (i.e., after hibernating), this "echo" command will restore
+	the computer state from the swap device.</p>
+	<h2>Automating a LFS Build</h2>
+	<p>This CD comes with the <b>jhalfs</b> tool that allows extracting commands from the
+	XML version of the LFS, HLFS or CLFS book into Makefiles and shell scripts. You can find
+	the jhalfs installation in the home directory of the "jhalfs" user, and the
+	XML LFS book is in /usr/share/LFS-BOOK-6.2-XML. In order to use jhalfs, you
+	have to:</p>
+	<ul>
+	 <li>create a directory for your future LFS system and mount a partition there</li>
+	 <li>change the ownership of that directory to the "jhalfs" user</li>
+	 <li>run "su - jhalfs" in order to become that user</li>
+	 <li>as user "jhalfs", follow the instructions in the jhalfs README file</li>
+	</ul>
+	<p>Note that this user already has the required sudo access.</p>
+	<h2>Thanks</h2>
+	<p>Many thanks to all whose suggestions, support and hard work have helped create
+	this CD.</p>
 <!--#include virtual="/common/footer.html" -->

More information about the website mailing list