------------
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
-------
*--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*::
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.
+//////////////////////////////////////////////////////////////////////////
*--initrd=...*::
Install specified initrd instead of the default. You might want to specify
option *--kernel* as well. (Be aware when using multiboot setup.)
[Notice: not implemented yet.]
+//////////////////////////////////////////////////////////////////////////
+//////////////////////////////////////////////////////////////////////////
*--kernel=...*::
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*::
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
+<<X7,let us know>> 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.
[Notice: not implemented yet.]
+//////////////////////////////////////////////////////////////////////////
+//////////////////////////////////////////////////////////////////////////
*--uninstall*::
Uninstall grml ISO files.
[Notice: not implemented yet.]
+//////////////////////////////////////////////////////////////////////////
*-v*, *--version*::
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
| |-- 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
|-- 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/
`-- logo.png
live/
- |-- filesystem.module
- |-- grml.squashfs
- |-- grml-medium.module
- |-- grml-medium.squashfs
- |-- grml-small.module
- |-- grml-small.squashfs
- |-- grml64.module
- |-- grml64.squashfs
- |-- grml64-medium.module
- |-- grml64-medium.squashfs
- |-- grml64-small.module
- `-- grml64-small.squashfs
+ |-- 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
+ % 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
+ # 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.
+
+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).
Usage examples
--------------
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
# grml2usb --squashfs=/grml/grml-live/grml_cd/live/grml.squashfs \
/home/grml/grml_2008.11.iso /dev/sdb1
+/////////////////////////////////////////////////////////////////
Install specified ISO on device /dev/sdb1 but use given squashfs
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,to the author>>.
+[[X7]]
Author
------
Michael Prokop <mika@grml.org>
projects / grml2usb.git / blobdiff