Tiny Gentoo

What is this?
I've got a 64MB USB flash disk, and I wanted Gentoo on it, but to still have plenty of room for other files. Because there wasn't anything already out there, I figured it out for myself, and this is pretty much a HOWTO make a Tiny Gentoo (under 5MB) using and  (what the embedded guys use). Links to other (larger) projects and pages that were very helpful for me are at theSee Also section. What you need


 * USB flash disk or flash card (min. 8MB)
 * About 500MB free on your HDD (depends on how you decide to go on about things)
 * A motherboard/laptop that supports booting from a USB flash disk
 * Some free time

Getting started
Choose a mirror close to you ( http://www.gentoo.org/main/en/mirrors.xml ), then hop into experimental/x86/embedded/stages, if your arch is x86. Download the stage3 file or stage1 or 2 if you want to play around more than what is necessary.

Feel free to be creative with the file and folder names, I'm just using ones that will explain what they are for. Basically we're just following the Gentoo Handbook Chapter 5, but with a few differences, most of the stuff we don't need to do because we'll only be chrooting into it.

A more detailed guide for creating the chroot can be found here.

Entering the chroot
And what you'll need to repeat every time when entering the chroot:

If you're mounting+binding your portage and other directories over CIFS (gentoo minimal iso doesn't have NFS) and get a "Value too large for defined data type" error when listing directory, add nounix,noserverino to your CIFS mount options.

Workaround to "getgroups function not implemented" is here.

Basic setup inside the chroot
We do want all the symlinks for busybox, and ccache, and only minimal versions of packages that support that use flag.

The uclibc stages on the mirrors are quite old, so you will need to change the profile to a newer version. Emerge ccache first so that portage can use it for all the other packages. Then update all the packages, emerge the 2.6 kernel sources and copy the default bash login scripts to root's home directory. Since the current coreutils provides mktemp and the latter blocks the update of the former, mktemp needs to be unmerged first.

There is a current conflict between sys-devel/libtool-2.2.6b and sys-devel/automake-1.10, so upgrade automake and remove v1.10 prior to emerging ccache.

If you get sandbox violation errors when upgrading coreutils just do

If you get errors while running the ancient emerge against the new portage tree use the following work-around:

On your parent Gentoo system create a package containing a working portage:

You now have a package file at. Chroot back into the subsystem as explained above and to go to the root, type the following:

Now extract the working portage over the embedded system chroot by typing:

Finally you should emerge portage itself using the new emerge (from the parent system) to make sure everything is fine:

If fails, see. Copy /usr/include/netdb.h to /usr/include/netdb.h.orig.

Then add the following after line 403 in netdb.h:

After a successful emerge world you may want to emerge and run:

If this fails because it wants to emerge an old python that is no longer supported(?), run: to find out which version you have, and then unemerge all old versions by using:

After this, do: and try to revdep-rebuild again.

If the following fails on busybox, then first try to emerge uclibc, then retry emerging world.

If after the above sys-apps/busybox fails with error: '__NR_clock_gettime' undeclared you need to upgrade sys-libs/uclibc. For the current version (1.8.2 as well as 1.7.4) uclibc-0.9.29 is needed, which is not in portage. See for updated ebuilds.

Alternatively, to work around the busybox problem, you can do the following


 * 1) this will fail with the __NR_clock_gettime error


 * Deselect "BusyBox Settings"->"BusyBox Library Tuning"->"Use Clock Gettime"
 * Exit configuration

If sys-apps/busybox fails with error: 'struct stat' has no member named 'st_mtim' it is possible to disable nanosecond format using menuconfig.
 * Deselect "Coreutils"->"Support %[num]N nanosecond format specifier"
 * Exit configuration

And save .config after that as described above.

Everything that will finally be turned into an initramfs will be in /tinygentoo/. Using ROOT=/tinygentoo before emerge commands will emerge the packages into that directory. This way you do not need portage or gcc in there, but only the packages you really want.

Emerge the base packages
Emerge lines that do not have ROOT=/tinygentoo will be installed into the chroot so that it will be able to compile the other packages without errors. We do not add symlink to /etc/make.conf because that would interfere with later updating the baselayout-2, which will need to be unmasked first. See emerge --help if you're not sure what the options used do. Please note that at the time of writing, baselayout 2.0.0 is the most recent version. You can choose to unmask newer versions (and their dependencies) when needed.

Setting up users
chroot into /tinygentoo/ and change the root password.

Add a regular user:

Set the hostname
Replace TinyGentoo if you would like to use some other hostname. is read by, see.

For more help see Busybox Init Documentation

Writing fstab
The root filesystem will be mounted as ramfs by the kernel. The only downside to this is that unlike tmpfs it does not have a size limit, so writing a lot to / could fill up your ram. Anything that is on tmpfs uses nearly no ram when empty and grows when needed but wont use up all of the ram, leaving room for applications to run.

Feel free to be creative, just remember that flash doesnt like being written to lots and lots, so do not mount or  onto it. sda1 is the partiton on the USB stick that will contain the bootloader files, the kernel and the initrd. will be the partition that you see when in windows, and you can use it to store any settings/files from TinyGentoo too.

Make the two directories that do not yet exist:

Writing /init
This step is optional. Instead of having this file you could add init="/sbin/init" to the grub kernel line.

is the file that the kernel executes right after loading the content of the initramfs. If you are using initrd instead of initramfs, rename this file to linuxrc

Remember to make it executable:

If you would like to be able to use the same script with both initrd or initramfs, you can symlink one to.

Optional, but if you would like to change the timezone, edit /tinygentoo/etc/TZ. For example, echo UTC > /tinygentoo/etc/TZ.

Emerging the wanted packages into /tinygentoo
Choose what packages you want. esearch foo in your regular Gentoo to easily find out what the packages are. The examples will provide you with an installation that can browse the web (lynx), connect to IRC (scrollz), run and connect to SSH servers (dropbear) and screen, that I don't know how some people live without.

That's it for /tinygentoo. chroot back in if you want to get a feel for it. {{Note|1=If you try to emerge coreutils into you tinygentoo and it aborts with sandbox violations (confdir3) please check {{Bug|125701}}.

You have to set this before you try to emerge coreutils:

{{Root|1=export gl_cv_func_getcwd_path_max=yes}}

Kernel
In theory you could just use a kernel built outside the uClibc chroot, but that would get confusing.

Kernel configuration
Not very hard really, and because we will be using an initramfs image most things can be compiled as modules if you wish to do so. Disable everything that you don't want or need to keep the size of the kernel image down.

As a final touch, you may also need something else than the default us keymap for your future system. If you need it, you can build the proper keymap for your keyboard layout inside the kernel issuing the following command from within the directory:

An example for french layout:

Compiling the kernel
Now just:

If you go back to menuconfig and change things, clean out the old modules so there wont be any extra ones taking up space:

or if you don't want do the next step (coping modules) you can launch this command:

Copying the modules
We want all the modules inside the initrd, so they'll need to be copied there.

Packaging /tinygentoo
We want everything under to be turned into a single initramfs image. Don't forget to copy the kernel modules to before this step!

Cleaning up
Copy the files to some other place so you can easily restart if you mess up, then remove all the files you don't need or want.

If you want to see how much space its using:

Creating the initramfs image
To create the initramfs image we will use cpio to create an archive of the files that the kernel can understand, and gzip it to make it smaller.

Preparing the USB flash disk
Basically we just want one partiton for the TinyGentoo boot files, and one partiton for saving files that you want to keep even after a reboot, and that will also be accessable from Windows. Backing up the old data

Just in case you don't like it or just want to try it or.... something else, back up what you have got on your dongle (USB flash disk) right now. Make sure that you use the correct device, it might not be if you have other drives showing up as SCSI. Those could be a SATA hdd, a camera or an MP3 player. fdisk -l will show you what partitions are seen by linux.

Preferably do all the partitioning stuff outside the uClibc chroot, but you could do it from in there too if you've fallen in love with it :P

We'll just raw copy the whole disk. Note: sda is the whole disk, sda1 is only the first partition, it does not include the MBR/partiton table. Gzip it too to save space. 4K blocks to read to make it slightly faster, but its still slow..

Creating the partitions
Clear the partition table and use fdisk (or something else if you don't like fdisk) to create the partitions.

Change the size of the boot partition so that it will fit your kernel + initrd.img + 1-2MB, though you could make it larger if you would like to use it for other stuff too.

fdisk console

To make it bootable:

fdisk console

Formatting the partitions
There isn't really any good reason to use something other than ext2 for the boot partition. You may need to emerge dosfstools for vfat formatting support. The -F 32 makes it FAT32 to support longer filenames and stuff. Change label to what name you would like the partition to have.

Installing GRUB
If you do not yet have grub:

First you will need to copy the stages. e2fs_stage1_5 is optional, and you may delete it after grub has embedded it. Make sure you have mounted to be able to copy the files from there.

grub console

Alternative
In my case, I had to do use the following commands.

grub console

The difference being that I had to setup BOTH the MBR and the boot partition's MBR. Until I did this, my BIOS would not boot from the USB stick.

Writing menu.lst (for GRUB)
GRUB looks for menu.lst, not grub.conf, but you may make a symlink to grub.conf from menu.lst and then edit grub.conf.

Add init=/sbin/init to the kernel line if you do not have a linuxrc file.

Set vga=ask to get a prompt to be able to select the resolution for your console. With the ramdisk_size= option you can set how large you would like your / to be, in KB. Don't set it too high if because you will also need RAM for applications to run, but you've got to set it large enough for the uncompressed initrd.img and dynamic files that will be created. Note: If you get a blank screen after selecting the right kernel from the grub selector, try keep out vga=791 from the kernel line.

Copying the important files
Something you need to do to get it working..

BIOS Setup, Reboot and Enjoy!
Reboot, hit Del, F2 or whatever it is that you need to do to enter the BIOS configuration. Find the section where you can change the boot order, and select USB-HDD, USB-ZIP or something similar to have the highest priority. Save and exit, and reboot with the USB stick attached.

Where to from here?
If all goes well, you'll be in your shiny new TinyGentoo, that you will still need to learn to use though. You will probably want to write a script to get the net going and maybe something to save your settings.

TODO

 * udev and hotplug
 * xorg + wm and stuff
 * Getting sectors and cylinders right on the disk
 * Scripts and hopefully an ebuild to make life easier
 * Boot floppy to get boot the actual TinyGentoo for those whose BIOS's don't support booting directly from USB