================================================
 FILL_IN_CD_DISTRIBUTION_HERE Kevux Mini CD-ROM
 ----------------------------------------------
   System Type:  FILL_IN_SYSTEM_TYPE_HERE
   Version:      FILL_IN_VERSION_HERE
   Date:         FILL_IN_DATE_HERE 
================================================

-----
ABOUT
-----
  By default, there are three CD-ROM/DVD-ROM images created by the tkis project as of tkis-0.5.1
  1) mini  -  contains an aggressively compressed standard system that boots and runs off the cd-rom
  2) live  -  contains a standard system that boots and runs off the cd-rom
  3) dvd   -  contains a complete system, tkis scripts, and tkis archive that boots and runs off the cd-rom


--------
CONTENTS
--------
  TOP LEVEL STRUCTURE
  ===================
  /boot/           -  This directory stores all of the files necessary to ensure that the cd can boot and allow the usb system to boot onto old hardware that does not support USB booting.
  /documentation/  -  Contains HTML documentation that explains the basics of installing and setting up the system. (Also contains some older text-based notes)

  BOOT LEVEL STRUCTURE
  ====================
  /catalog                       -  Used/Required by bootable cd specifications (otherwise useless).
  /grub/                         -  Grub program used by the cd to perform all booting.  Most relevant file is menu.lst which designates how and what to boot.
  /turtle-?.linux                -  The linux kernel used
  /turtle-simple-?.initrd        -  The initrd used for normal booting
  /live/                         -  Directory that contains all system files (compressed)
  /olpc.fth                      -  One Laptop Per Child example/default boot file used to boot Turtle Kevux on an olpc

  BOOT/GRUB LEVEL STRUCTURE
  =========================
  /e2fs_stage1_5      -  Used to boot the standard ext2/ext3 linux filesystems
  /fat_stage1_5       -  Used to boot to the standard windows/dos fat filesystems
  /ffs_stage1_5       -  Used to boot flash filesystems
  /iso9660_stage1_5   -  Used to boot cd-rom images (such as this one)
  /jfs_stage1_5       -  Used to boot journalized filesystems
  /menu.lst           -  This is the file that designates how to boot and what to boot, modifify this file during remastering
  /minix_stage1_5     -  Used to boot minix filsystems
  /reiserfs_stage1_5  -  Used to boot reiserfs filesystems
  /stage1             -  Required to boot at all
  /stage2             -  Required to boot at all
  /ufs2_stage1_5      -  Used to boot ufs2 filesystems
  /vstatfs_stage1_5   -  Used to boot vstatfs filesystems
  /xfs_stage1_5       -  Used to boot xfs filesystems

  BOOT/LIVE LEVEL STRUCTURE
  ======================
  /bin.sfs            -  Compressed archive of all files within this directory of the system
  /boot.sfs           -  Compressed archive of all files within this directory of the system
  /dev.sfs            -  Compressed archive of all files within this directory of the system
  /etc.sfs            -  Compressed archive of all files within this directory of the system
  /home.sfs           -  Compressed archive of all files within this directory of the system
  /lib.sfs            -  Compressed archive of all files within this directory of the system
  /sbin.sfs           -  Compressed archive of all files within this directory of the system
  /share.sfs          -  Compressed archive of all files within this directory of the system
  /var.sfs            -  Compressed archive of all files within this directory of the system
  /checksum.sfs       -  Compressed archive of all files within this directory of the system
  /firmware.sfs       -  Compressed archive of all files within this directory of the system
  /2.6.?-?-?.modules  -  Compressed kernel modules, example: 2.6.36-desktop-pc.modules


------------------
POTENTIAL PROBLEMS
------------------
  1) Not all machines have CD-ROM boot enabled by default, you may have to go to the bios (if it is not passworded) and tell it to boot the cd-rom before anything else
  2) There are some very poorly designed bioses out there that will not boot this cd-rom
  3) This is untested against a Macintosh, due to possible architecture differences or not having a bios


-----------
REMASTERING
-----------
  Okay, so one of the biggest problems with livecd's is that they cannot be easily updated in order to allow for future changes that always happen.
  The most common of these would be to update to a newer kernel that is to be used on the target system.
  This will help explain how to do this yourself with tools from the turtle kevux system.

  Before we begin, this example/tutorial will assume that the following are true:
  -  Your current directory is your home directiory: $HOME
    - If not and you are in a gui (such as XFCE or DWM), bring up an xterminal (xterm).
    - If a "Run" or "Run Program" is available, this can be used to pull up an xterminal by specifing 'xterm' without the quotes as the command to run.
    - Once you have a terminal, go to the home directoy by either running the command 'cd' or the command 'cd $HOME' without the quotes.
  - Your CD-ROM image is mounted on '/mnt/cdrom0/', this will be referred to as $CD_MOUNT_POINT
    - If you already have the files on the system somewhere and know how to use/get/move them as needed, this is also fine.
    - If you wish, you can tell your shell to use /mnt/cdrom0/ as $CD_MOUNT_POINT by entering the following without the quotes: 'export CD_MOUNT_POINT=/mnt/cdrom0'
  
  Now, to make note of all of the required files
  - The /boot/grub/ directory and all of its contents are required as far as you need to be concerned
  - The /boot/grub/menu.lst file will need to be modified with some editor at some point to reflect whatever changes you made 
  - The /boot/catalog file is required must be created by you and not copied
  - The kernel files for whatever linux kernels you wish to boot are required (such as /boot/turtle-desktop-pc.linux and /boot/turtle-desktop-pc.config)

  All other file present are not required

  Now, copy all files from the existing cdrom that is to be remastered:
  - cp -vR $CD_MOUNT_POINT/ new_cdrom

  Delete the catalog file as it should not be copied, but was auto-copied by the previous command for simplicity purposes:
  - rm -v new_cdrom/boot/catalog

  Create a new (empty) catalog file:
  - touch new_cdrom/boot/catalog

  If you wish to add/remove any files to the new cdrom that is to be created, do so now
  For example, if the purpose of this remaster was to add a new linux kernel to boot, where $KSOURCE represents the location of the source code where you compiled the new linux kernel and that new kernel happened to be linux-2.6.36:
  - cp -v $KSOURCE/arch/x86/boot/bzImage new_cdrom/boot/turtle-2.6.36-desktop-pc.linux
  - cp -v $KSOURCE/.config new_cdrom/boot/turtle-2.6.36-desktop-pc.config

  In the above example, a new kernel was added, if desired, the old linux kernel files could be safely removed.
  When a new kernel was added you will need to modify the menu.lst file mentioned a few places above.
  Read the exist menu.lst file to learn some details, but heres a sum of some important notes.

  - Example:
  title Turtle Kevux FILL_IN_VERSION_HERE
    root (cd)
    kernel /boot/turtle-desktop-pc.linux quiet cdromsearch=require squashboot=memory finalroot=LABEL=Turtle-FILL_IN_VERSION_HERE-live
    initrd /boot/turtle-simple-x86.initrd
    boot

  - In the example above:
    - 'root (cd)' means use the cdrom device to find all of the files mentioned (namely /boot/turtle-desktop-pc.linux).
    - 'kernel /boot/turtle-desktop-pc.linux' means use that specific kernel
    - 'cdromsearch=require' means to only attempt to boot to the cdrom, otherwise fail
    - 'squashboot=memory' means to boot using the compressed system images found on the cd-rom and run from memory and not the cdrom, this way you can eject the cd once the system is running
    - 'finalroot=LABEL=Turtle-FILL_IN_VERSION_HERE-live' is the name of the cdrom to boot to so that the bootloader can find the correct cdrom
    - 'quiet' means don't print extra stuff to the screen, usually for debugging, this slows boot a little
    - 'initrd' specifies the compressed init filesystem used to boot the system
    - 'boot' this causes all of the values processed above to be used to begin booting the system

  Once you have added/modified/removed all the files you wished to, you need to make the cdrom image:
  - cd new_cdrom/
  - xorrisofs -no-emul-boot -boot-load-size 4 -boot-info-table -r -joliet-long -l -iso-level 4 -f -c boot/catalog -b boot/grub/iso9660_stage1_5 -o ../new_cdrom.iso -V "TurtleFILL_IN_VERSION_HERElive" .

  The image should be ready, now you can burn it.
  Before you burn it, however, make sure that you have a writeable blank cd-rom in a cdrw drive, if this is where the old cdrom is, make sure to unmount and eject the old cdrom.
  - cd $HOME
  - cdrskin -v -eject new_cdrom.iso

  Once this sucessfully burns, you can remove all the unecessary files:
  - rm -Rf new_cdrom/
  - rm -f new_cdrom.iso

  If you want to keep the new_cdrom.iso, then don't delete it :)


----------------
COPYING A SYSTEM
----------------
   Lets say that you have a system mounted on /mnt/sda4 and want to copy it to another partition, mounted on /mnt/sda2.
   A simple recursive copy would work for most systems; however, there are permissions that are important to preserve.

   -a
     This is the command used to ensure all file properties are preserved.
     Failure to do so will cause Xorg, xterm, su, mount, and many other programs that need sticky bit from working.

   -P
     This ensures that symbolic links get copied and not the files they point to
     Failure to do so could result in duplication of data

   To safely copy from /mnt/sda4 to /mnt/sda2, one will need a command like the following:
     cp -a -P -R /mnt/sda4/* /mnt/sda2/

   WARNING: the default kevux system has special filesystem permissions on the '/' directory, these are not copied from the one partition to the other with the above command
     Instead, you need to check the permissions of the directory '/mnt/sda4/' while the partition is mounted there, and mimik those permissions on /mnt/sda2/
     One of the commands would be: chmod o-rw /mnt/sda2/
     At the time of this writing, the group with the name 'root' has a numerical id of '13' (see: /etc/group).
     With this in mind, the group permissions can be set as follows: chgrp 13 /mnt/sda2/


-------------------
EXTRACTING A SYSTEM
-------------------
   Lets say you wanted to extract the pre-compressed system present on this cdrom.

   To automatically extract the entire system files:
     extract_system -s /path_to_file_to_extract/ -d /destination_to_extract_to

   To manually extract individual squash files:
     cd /desired_path_to_extract_to/
     unsquashfs /path_to_file_to_extract/some_file.sfs
     mv -v squashfs-root some_file 
