X-Git-Url: https://git.grml.org/?p=grml2usb.git;a=blobdiff_plain;f=grml2usb.8.txt;h=bf22fa8afc6c3ddde244db68d76290aa7990906f;hp=40e6fa8a96cc09b24a63085aa9dabac062642b5d;hb=61678a9511f8fbedc4389b45d87a272174bd7a13;hpb=fab3d15949833fa969fe376e8b0a4050ade42013 diff --git a/grml2usb.8.txt b/grml2usb.8.txt index 40e6fa8..bf22fa8 100644 --- a/grml2usb.8.txt +++ b/grml2usb.8.txt @@ -17,13 +17,19 @@ Introduction ------------ grml2usb installs grml on a given partition of your usb device and makes it -bootable. - -grml2usb provides multi-iso support, meaning you can specify several grml ISOs -on the command line at once and select the grml flavour you would like to boot -on the bootbrompt then. Notice that the default ISO (that's when pressing just -enter on the bootprompt or wait until the timeout matches) will be the *first* -one specified on the grml2usb command line. +bootable. It provides multi-iso support, meaning you can specify several grml +ISOs on the command line at once and select the grml flavour you would like to +boot on the bootbrompt then. Note that the *first* ISO specified on the grml2usb +command line will become the default one (that's the one that will boot when +just pressing enter on the bootprompt or wait until the boot timeout matches). + +[IMPORTANT] +By default a compatible master boot record (MBR) is installed on the device +(being for example /dev/sdb when executing 'grml2usb grml.iso /dev/sdb1') +and grub is being used as default bootloader. Avoid installation of the +default MBR using the --skip-mbr option or if you encounter any problems +with the default MBR consider using --syslinux-mbr instead. If bootloader +grub doesn't work for you check out the --syslinux option. Options ------- @@ -44,7 +50,9 @@ Use specified bootoptions as default. *--bootloader-only*:: -Do *not* copy files but instead just install a bootloader. +Do *not* copy files but instead just install a bootloader. Note that the boot +addons are copied to /boot/addons at this stage as well. If you want to skip +copying the boot addons consider using the --skip-addons option. *--copy-only*:: @@ -65,10 +73,6 @@ Format specified partition with FAT16. Force any (possible dangerous) actions requiring manual interaction (like --fat16). - *--grub*:: - -Install grub bootloader instead of syslinux. [Notice: not implemented yet.] - *--help*:: Display usage information and exit. @@ -85,14 +89,20 @@ Install specified kernel instead of the default. You might want to specify option *--initrd* as well. (Be aware when using multiboot setup.) [Notice: not implemented yet.] - *--lilo=...*:: + *--lilo-binary=...*:: -Use specified lilo executable to for installing master boot record (MBR) -instead of the default, being /usr/share/grml2usb/lilo/lilo.static. +Use specified lilo executable for installing master boot record (MBR) when using +the --syslinux-mbr option. By default any system wide (from $PATH) lilo +executable is taken. If there can not be find any lilo executable the +statically compiled version of the grml2usb Debian package (see +/usr/share/grml2usb/lilo/lilo.static.[amd64|i386]) is taken. - *--mbr*:: + *--mbr-manager=...*:: -Install a default master boot record (MBR) on the device. +Install master boot record (MBR) with integrated boot manager, providing a +simple selection for specifying the device for booting from. This options is +available only when using the default MBR and won't work if using the +--syslinux-mbr option. *--quiet*:: @@ -102,6 +112,23 @@ Do not output anything but just errors on console. Do not install /boot/addons/ files (like dos, grub, memdisk,...). + *--skip-mbr*:: + +Do not touch/install the master boot record (MBR). + + *--syslinux*:: + +Install syslinux bootloader instead of the default (being grub). + + *--syslinux-mbr*:: + +Install syslinux master boot record (MBR) instead of the default one. By +default a very compatible MBR is installed, if you encounter any problems +with it you can try using the syslinux MBR instead. If that works for you please +<> so we can adjust our default MBR accordingly. +Note: When using the --syslinux-mbr option lilo is executed before the MBR +is installed so the according partitions are set active. + *--squashfs=*:: Install specified squashfs file instead of the default. @@ -128,20 +155,20 @@ Directory layout on usb device boot/ -> |-- addons/ - | |-- allinone.img - | |-- balder10.imz - | |-- chain.c32 - | |-- memdisk - | `-- menu.c32 + | |-- allinone.img [grub - all in one image] + | |-- bsd4grml/ [MirBSD] + | |-- balder10.imz [FreeDOS] + | |-- memdisk [chainloading helper] + | |-- memtest [memtest86+] |-- release/ | |-- grml/ - | | |-- linux26 - | | |-- initrd.gz + | | |-- linux26 [Kernel] + | | |-- initrd.gz [initramfs] | |-- grml64 - | | |-- linux26 - | | |-- initrd.gz + | | |-- linux26 [Kernel] + | | |-- initrd.gz [initramfs] | |-- grml-medium - | | |-- linux26 + | | |-- linux26 [...] | | |-- initrd.gz | |-- grml64-medium | | |-- linux26 @@ -153,14 +180,15 @@ Directory layout on usb device | |-- linux26 | |-- initrd.gz |-- grub/ - | |-- menu.lst - | |-- splash.xpm.gz - | `-- stage2_eltorito + | |-- grml.png [splash screen for grub2] + | |-- grub.cfg [configuration file for grub2] + | |-- menu.lst [configuration file for grub1] + | |-- splash.xpm.gz [splash screen for grub1] `-- syslinux/ - |-- boot.msg - |-- f1 - |-- f2 - |-- f3 + |-- boot.msg [boot splash for syslinux] + |-- f1 [screen when pressing f1] + |-- f2 [screen when pressing f2] + |-- f3 [...] |-- f4 |-- f5 |-- f6 @@ -168,17 +196,17 @@ Directory layout on usb device |-- f8 |-- f9 |-- f10 - |-- logo.16 - `-- syslinux.cfg + |-- logo.16 [graphical part of boot splash] + `-- syslinux.cfg [configuration file for syslinux] grml/ - |-- grml2usb.txt - |-- grml-cheatcodes.txt - |-- grml-version.txt - |-- LICENSE.txt - |-- md5sums - |-- README.txt - `-- web/ + |-- grml2usb.txt [not yet implemented] + |-- grml-cheatcodes.txt [list of bootoptions for grml] + |-- grml-version.txt [file containing information about grml-version] + |-- LICENSE.txt [license information] + |-- md5sums [md5sums of original ISO] + |-- README.txt [informational text] + `-- web/ [browser related files] |-- index.html |-- style.css `-- images/ @@ -188,11 +216,11 @@ Directory layout on usb device `-- logo.png live/ - |-- filesystem.module - |-- grml.squashfs - |-- grml-medium.module - |-- grml-medium.squashfs - |-- grml-small.module + |-- filesystem.module [file specifying which squashfs should be used by default] + |-- grml.squashfs [squashfs file] + |-- grml-medium.module [module specifying which squashfs should be used for grml-medium] + |-- grml-medium.squashfs [squashfs file for grml-medium] + |-- grml-small.module [...] |-- grml-small.squashfs |-- grml64.module |-- grml64.squashfs @@ -204,7 +232,7 @@ Directory layout on usb device Grabbing the source ~~~~~~~~~~~~~~~~~~~ - git clone git://git.grml.org/grml2usb.git + % git clone git://git.grml.org/grml2usb.git Developers Debugging Hints ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -212,22 +240,120 @@ 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 + # 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\n t \n 6\n a\n1\n w\n" | fdisk /dev/loop1 + # 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" + # 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 --mbr /grml/isos/grml-small_2008.11.iso /dev/loop1 + # 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. + +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! +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please <>. Or even better: send us a patch. :) + +I've problems with booting from USB. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Check out <>. + +I've found a bug! +~~~~~~~~~~~~~~~~~ + +Please <>. Please provide usage examples and output +of your grml2usb commandline (consider using the "--verbose" option). Usage examples -------------- @@ -244,15 +370,15 @@ bootprompt, for grml64 use "grml64" and so on... The *first* specified ISO is the one being the default (when just pressing enter or waiting until the timeout is reached). - # grml2usb --fat16 --mbr /home/grml/grml_2008.11.iso /dev/sdb1 + # grml2usb --fat16 /home/grml/grml_2008.11.iso /dev/sdb1 -Install specified ISO on device /dev/sdb1, install MBR on /dev/sdb and -format partition /dev/sdb1 with FAT16 filesystem. +Install specified ISO on device /dev/sdb1 and format partition /dev/sdb1 with +FAT16 filesystem. - # grml2usb --grub /home/grml/grml_2008.11.iso /dev/sdb1 + # grml2usb --syslinux /home/grml/grml_2008.11.iso /dev/sdb1 -Install specified ISO on device /dev/sdb1 and use Grub as bootloader -(instead of syslinux being the default). +Install specified ISO on device /dev/sdb1 and use syslinux as bootloader +(instead of grub being the default). # grml2usb --kernel=/boot/vmlinuz-2.6.28-grml --initrd=/boot/initrd.img-2.6.28-grml \ /home/grml/grml_2008.11.iso /dev/sdb1 @@ -271,10 +397,17 @@ file instead of the one provided by the ISO. Install specified ISO on device /dev/sdb1 and use "lang=de ssh=mysecret" as default bootoptions. +Online Ressources +----------------- + +Check out the link:http://grml.org/grml2usb/[grml2usb webpage] and the +link:http://git.grml.org/?p=grml2usb.git[grml2usb git repository]. + Bugs ---- -Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes link:http://grml.org/contact/[to the grml-team]. +Please report feedback, bugreports and wishes <>. +[[X7]] Author ------ Michael Prokop