+ |-- grml/
+ | |-- filesystem.module [module specifying which squashfs should be used for grml]
+ | `-- grml.squashfs [squashfs file for grml]
+ |-- grml-medium/
+ | |-- filesystem.module [module specifying which squashfs should be used for grml-medium]
+ | `-- grml-medium.squashfs [squashfs file for grml-medium]
+ |-- grml-small/
+ | |-- filesystem.module [module specifying which squashfs should be used for grml-medium]
+ | `-- grml-small.squashfs [squashfs file for grml-small]
+ `-- ...
+
+Grabbing the source
+~~~~~~~~~~~~~~~~~~~
+
+ % git clone git://git.grml.org/grml2usb.git
+
+Developers Debugging Hints
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To play with grml2usb you can avoid using a real device via a loopback file
+setup, like:
+
+ # dd if=/dev/zero of=~/loopback bs=1M count=100 # adjust size to your needs
+ # losetup /dev/loop1 ~/loopback
+
+Then create according partitions either running for example:
+
+ # echo -en "n\np\n1\n\n\nt\n6\na\n1\n w\n" | fdisk /dev/loop1
+
+or:
+
+ # parted /dev/loop1 -s "mkpart primary fat16 0 -1s mkfs 1 fat16"
+
+Finally create a filesystem and execute grml2usb as needed:
+
+ # mkfs.vfat /dev/loop1
+ # grml2usb --bootloader-only /grml/isos/grml-small_2008.11.iso /dev/loop1
+
+Performance tracing
+~~~~~~~~~~~~~~~~~~~
+
+ # blktrace -d /dev/sdb -o - | blkparse -i -
+ # grml2usb grml_2008.11.iso /dev/sdb1
+
+[[X6]]
+Troubleshooting and Pitfalls when booting
+-----------------------------------------
+
+Here is a list of common error messages from BIOS/bootloader when trying to boot
+from USB.
+
+///////////////////////////////////////////////////////////
+TODO: better list type for the error message / reason part?
+See http://www.methods.co.nz/asciidoc/userguide.html
+///////////////////////////////////////////////////////////
+
+[horizontal]
+*Error message*:: ran out of input data. System halted
+
+*Reason*:: Everything OK, except for the filesystem used on your usb device. So
+instead of fat16 you are using for example fat32. Fix: use the appropriate
+filesystem (fat16 for usb pens usually). The Bootsplash might be displayed, the
+kernel loads but you very soon get the error message.
+
+*Error message*:: Invalid operating system
+
+*Reason*:: the partition layout is not ok. Very probably there's no primary
+ partition (/dev/sdX{1..4}) or none has the flag 'bootable' set.
+
+*Error message*:: No operating system found.
+
+*Reason*:: you forgot to set the boot-flag on the partition. Or there really isn't
+any operating system at all. :)
+
+*Error message*:: kernel-panic: unable to mount root-fs...
+
+*Reason*:: Kernel boots but fails to find the root filesystem. The root=
+argument in your kernel commandline is pointing to the wrong device. Adjust
+root=..., consider using root=UUID=....
+
+*Error message*:: Could not find kernel image: ...
+
+*Reason*:: either a broken isolinux/syslinux version or a broken BIOS. Check out
+whether the vendor provides a BIOS update or if using bootloader grub instead of
+isolinux/syslinux fixes the problem.
+
+Frequently Asked Questions (FAQ)
+--------------------------------
+
+What's the difference between grml2hd and grml2usb?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+grml2hd installs a running grml system to a harddisk. When rebooting the
+harddisk installation can be modified and changes will find their way to the
+harddisk immediately. grml2usb copies just the compressed chroot filesystem
+(being the squashfs file), some further informational files and a bootloader to
+your device. This way you don't need as much space as with a harddisk
+installation (just a USB device with >=ISO size) and when rebooting the system
+your changes will be lost (even though a persistent root feature is
+work-in-progress). Think of using a better CD version: booting is (usually)
+faster, you don't need to burn a new CD when a new ISO version arrives (just
+install the new ISO using grml2usb) and you can carry additional files on a
+writable medium with yourself.
+
+Why is there a menu.lst and a grub.cfg inside /boot/grub/?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+grml2usb supports grub version 1 (grub1) as well as grub version 2 (grub2).
+Whereas grub1 uses menu.lst the new version grub2 needs grub.cfg.
+Providing both files allows grml2usb to install grub on the target device
+no matter which grub version is available on the host where grml2usb is
+executed on.
+
+grub-install fails with 'The file ../boot/grub/stage1 not read correctly"?!
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Check whether the partition has the right partition type. For example do NOT use
+FAT16 (partition type 6) when using a ext3 filesystem on the partition but
+instead use the correct partition type ('83' - Linux) then.
+
+Why do I have to use a FAT16 filesystem?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You have to use a FAT16 filesystem only if you consider using syslinux, Syslinux
+(currently) does not support any other filesystems. If you want to use another
+filesystem (like ext2/3) just don't use syslinux (drop the --syslinux option)
+but use the default bootloader (grub) instead.
+
+I think I've got a really cool idea!
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Great! Please check out
+link:http://git.grml.org/?p=grml2usb.git;a=blob;f=TODO;hb=HEAD[the TODO file].
+Feel free to <<X7,report your wishes to the author>>. Patches highly
+appreciated.
+
+I've problems with booting from USB.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Check out <<X6,Troubleshooting and Pitfalls when booting>>.
+
+I've found a bug!
+~~~~~~~~~~~~~~~~~
+
+Please <<X7,report it to the author>>. Please provide usage examples and output
+of your grml2usb commandline (consider using the "--verbose" option).
projects / grml2usb.git / blobdiff