How To Prep Gentoo 2008.0 For A PowerPC NAS Device
From NAS-Central Main Wiki
This how to is a high level overview on preparing a Gentoo image for use on a specific PowerPC based NAS device and includes some scripts and tips on setting up your image cleanly for other people to use and information on how to more easily comply with relevant open source licenses.
Pre-Requisites
This is pretty simple if you already have the following dependencies:
- A working kernel for your device
- A method of booting your custom kernel
- Any supplementary utilities required for LEDs/buttons/fan control
- An OS you can prep your distro on your device with, eg foonas-em or EM mode on Buffalo Linkstations
Kernel Support
You need a recent vanilla-as-possible kernel that supports arch/powerpc.
Boot-Loader Configuration
You need to be able to load and boot a kernel from somewhere. Check that the boot-loader supplied by your manufacturer can boot your custom firmware from a location (e.g. flash or a hard disk if this is supported) and that you can configure the boot-loader to do this each time without manual interaction over net-console, serial port or other boot-loader access method.
Boot-loaders for PowerPC NAS devices include:
Supplementary Utilities
These are optional however can be critical for things like fan control for your device. In addition buttons and some of the LEDs on your device may require a script or daemon installed to function correctly, or at all. You should investigate the requirements and availability of these utilities for your device.
A good example of such a utility is ppc-evtd (or avr-evtd as it is also known) which provides a daemon for PowerPC based Kurobox and Linkstations that handles fan control, button events, LEDs and more.
If such a utility does not exist for your device you will almost certainly need to write a utility yourself as most devices will use different methods to accomplish this behavior (unless one already exists for the same manufacturer/product line), or extend an existing utility that has some kind of device abstraction built in already.
Firmware For OS Configuration
You will need an OS that runs out of flash or from a TFTP server that runs out of a RAM-disk for setting up Gentoo as you may be repartitioning the disk on your device. foonas-em or EM mode on Buffalo Linkstations are examples of this, it is possible your manufacturers firmware can do this also.
Initial Installation
Boot the OS that you will be using to prepare Gentoo on your device with and login to the box to begin the installation.
Partition And Format Your Hard Disk
In our examples we have SATA drives so our hard disk devices use sda device files. You may need to change our examples to hda depending on your configuration. Choose a sensible layout and sizes, for example:
- /dev/sda1 - 128MB for boot
- /dev/sda2 - 512MB for swap
- /dev/sda3 - Enough room for root to compile for system upgrades and addons, eg 20GB
- /dev/sda4 - The rest for /home where users should store all their data
Create this partition scheme with fdisk. You will need to choose an appropriate filesystem for each partition, in this example we will use ext2 for sda1, ext3 for sda3 and jfs for sda4:
mke2fs /dev/sda1 mkswap /dev/sda2 mke2fs -j /dev/sda3 mkfs.jfs /dev/sda4
Mount Your Partitions
In our example we mount on /mnt - you should determine if it is safe to mount here and if not change our examples accordingly:
swapon /dev/sda2 mount /dev/sda3 /mnt mkdir /mnt/boot mount /dev/sda1 /mnt/boot
Download And Extract Gentoo Files
First consult the Gentoo Mirrors page and select an appropriate mirror, then find the following files:
- stage3-ppc-2008.0.tar.bz2
- portage-2008.0.tar.bz2
The stage3 archive should be in a directory such as releases/ppc/2008.0/stages/ and the portage snapshot in a directory such as releases/snapshots/2008.0/ - wget these files to /mnt and extract them.
cd /mnt wget http://www.somemirror.org/sites/www.ibiblio.org/gentoo/releases/ppc/2008.0/stages/stage3-ppc-2008.0.tar.bz2 wget http://www.somemirror.org/sites/www.ibiblio.org/gentoo/releases/snapshots/2008.0/portage-2008.0.tar.bz2
tar may lack certain options in your OS so you may need to use bunzip2 provided by busybox to extract the files. Also you need to set the date:
date 030600162006 (MMDDhhmmYYYY) bunzip2 stage3-ppc-2008.0.tar.bz2 tar xf stage3-ppc-2008.0.tar bunzip2 portage-2008.0.tar.bz2 cd usr tar xf ../portage-2008.0.tar
Remember to remove the files afterwards:
cd / rm stage3-ppc-2008.0.tar portage-2008.0.tar.bz2
Configuration
Chroot Into Gentoo
To do the remainder of the configuration we chroot into the Gentoo installation. The mount command here is slightly different from the Gentoo guide to account for busybox.
cd / mount -t proc none /mnt/proc cp /etc/resolv.conf /mnt/etc/ chroot /mnt env-update && source /etc/profile
Set Your Timezone
As we are planning to supply this to users we set the timezone to UTC then ask our users to change it:
ln -s /usr/share/zoneinfo/UTC /etc/localtime
Create Hosts File And Setup Hostname
Again, we create a valid hostname (in this case gentoo-nas) and ask our users to change it. Users should also add domain name:
cd /etc echo "127.0.0.1 gentoo-nas localhost" > hosts sed -i -e 's/HOSTNAME.*/HOSTNAME="gentoo-nas"/' conf.d/hostname hostname gentoo-nas hostname -f
Install And Compile Kernel
You need to build a kernel for your device. Instructions to do this may be slightly different depending on the device that you are using so we assume that you know how to compile this yourself. Extract your kernel to /usr/src and create a symlink at /usr/src/linux that point to the sources you extracted.
PowerPC NAS devices typically ship with a customised version of the u-boot boot-loader (although it is possible it will use another) that require the mkimage utility from u-boots utilities as part of the kernel build process. There is a package in portage called u-boot-tools that provides this however you will have to create a portage overlay with this package in and add the ppc keyword to it to make it build.
If your device has u-boot it will fall into one of two categories, versions that support flat device tree (using dtb files as well as a kernel to boot) and those that do not. If you have one of the newer boot-loaders that supports this you will need to ensure to supply the dtb file provided by your build as well as the kernel.
Depending on the version of your kernel it may also be necessary to install and run the dtc utility separately to generate the dtb files from dts files, although in newer versions of the Linux kernel the dtc utility is included in the kernel sources and should be automatically used if you build your kernel correctly.
Note that you may need to supply the kernel separately to the distribution archive that you distribute, for example if your bootloader needs to load the kernel from flash your users will need to have this available separately. If this is the case be sure to copy it out before proceeding.
Kernel Support For Multiple Devices
In some cases it is possible to support multiple devices using the same kernel by supplying separate dtb files for each platform and including support for all these platforms in the kernel you are building. Where it is possible to do this it is recommended as you will be able to ultimately reach more users.
Also you can include a completely different kernel (or kernels) to support more platforms in your distribution.
Set Password
You should configure a root password and note it down to pass on to the people you are distributing the distribution to:
passwd
Configure fstab
We setup the /etc/fstab file to match our partition layout we created earlier:
# /etc/fstab: static file system information. # # noatime turns off atimes for increased performance (atimes normally aren't # needed; notail increases performance of ReiserFS (at the expense of storage # efficiency). It's safe to drop the noatime options if you want and to # switch between notail / tail freely. # # The root filesystem should have a pass number of either 0 or 1. # All other filesystems should have a pass number of 0 or greater than 1. # # See the manpage fstab(5) for more information. # # <fs> <mountpoint> <type> <opts> <dump/pass> # NOTE: If your BOOT partition is ReiserFS, add the notail option to opts. /dev/sda1 /boot ext2 noauto,noatime 1 2 /dev/sda3 / ext3 noatime 0 1 /dev/sda2 none swap sw 0 0 /dev/sda4 / jfs noatime 0 1 #/dev/cdrom /mnt/cdrom auto noauto,ro 0 0 #/dev/fd0 /mnt/floppy auto noauto 0 0 # glibc 2.2 and above expects tmpfs to be mounted at /dev/shm for # POSIX shared memory (shm_open, shm_unlink). # (tmpfs is a dynamically expandable/shrinkable ramdisk, and will # use almost no memory if not populated with files) shm /dev/shm tmpfs nodev,nosuid,noexec 0 0
Configure Networking
First we install a dhcp client so that after a user installs our distribution its networking is in a working state:
emerge dhcpcd
Set the first interface on the system to use dhcp, normally eth0 on most systems. Enter the following in /etc/conf.d/net:
config_eth0=( "dhcp" )
Following this check there is a symlink in /etc/init.d for this interface called net.eth0 and if not create it:
cd /etc/init.d/ ln -s net.lo net.eth0
Then enable this interface to start when the device boots:
rc-update add net.eth0 default
OpenSSH should already be installed from the stage 3 archive. Enable it to run when the box boots:
rc-update add sshd default
Configure Serial Port Access
Edit /etc/inittab and scroll down to the following lines:
# SERIAL CONSOLES #s0:12345:respawn:/sbin/agetty 9600 ttyS0 vt100 #s1:12345:respawn:/sbin/agetty 9600 ttyS1 vt100
Modify one that is closest to your config. In our example we have a serial port at /dev/ttyS0 at 115200 so we change this to the following:
# SERIAL CONSOLES s0:12345:respawn:/sbin/agetty 115200 ttyS0 vt100 #s1:12345:respawn:/sbin/agetty 9600 ttyS1 vt100
Install NAS Relevant Utilities
It saves your users compile time by installing the bare essentials for them, but do not impose your ideal configuration on them as Gentoo is all about choice. Firstly it is desirable to support a range of filesystems out the box:
emerge jfsutils xfsprogs reiserfsprogs
Also Linux RAID and LVM utilities are essential additions:
emerge device-mapper lvm2 mdadm
As users data is valuable to them hard disk smart monitoring should also be included:
emerge smartmontools
Install and enable network time support to help resolve time/clock issues:
emerge ntp rc-update add ntpd default
We will leave the rest of the packages to the users choice.
Install Supplementary Utilities For Your Device
As described above it is probably necessary to install some kind of script or daemon to manage button events, LEDs, fan control and other things. You should install these now and configure them to run when the device boots. If possible create a gentoo build file for this in a portage overlay for the device.
Steps We Skipped
We missed a few steps from the standard stage 3 PowerPC Gentoo installation guide on purpose as we expect our users to set these up themselves. They are:
- Configuring the correct timezone - we leave this set to UTC for our users to configure
- Configure /etc/conf.d/clock - see previous
- Installing cron/syslog - as there are options for this in Gentoo we leave this to the users choice
- Configuring the bootloader - this is platform specific and you need to determine and document this for your users
- Editing various config files - /etc/rc.conf, /etc/conf.d/rc and /etc/conf.d/keymap should be reviewed by users
- Setting a domain name - Users should review this and the hostname
- Configuring a local portage mirror - This will speed updates up for users, they need to configure this
Testing The Distribution
Backup Your Work
Before we boot the OS to test it we are going to back it up so that we can revert to it later. Exit the chroot, unmount proc and compress your work. In our config we lack the z option for tar so we have to compensate for that. Also we remove some leftover files we created while doing the installation:
exit cd /mnt umount /mnt/proc rm -f root/.bash_history usr/portage/distfiles/* tar cf gentoo-postconf-backup.tar bin boot dev etc home lib mnt opt proc root sbin sys tmp usr var cd / umount /mnt
Boot Gentoo
You should monitor the boot log in full from the moment the kernel starts ideally using a serial port. Configure your boot-loader to load your kernel (flashing it if necessary) and set the root kernel parameter to the partition you configured earlier. Watch for any errors - hopefully it should be a clean boot!
Reboot To Maintenance Firmware
Should you need to revert to your backup to make modifications boot your maintenance firmware and carry out the following steps to revert:
mount /dev/sda3 /mnt cd /mnt rm -rf bin boot dev etc home lib mnt opt proc root sbin sys tmp usr var tar xf gentoo-postconf-backup.tar
Now go back to the chroot step and carry this out again (including mounting proc) and make the modifications you need. Following this umount proc and backup your distribution and test it out again!
Comply With The GPL
Overview
This is an important step if you are distributing a Linux based operating system as you are under a legal obligation to provide the sources and other associated items that you used to create the distribution with, and also the sources to the binaries that you did not create but are already provided in the stage 3 Gentoo archive used at the beginning of the installation. In addition you are also obliged to provide a copy of the GPL with the OS you are distributing.
Please read the GPL as you are required to conform to it!
Method
Fortunately there are utilities available to make this easy, and with Gentoo being a source based meta-distribution all of the sources are readily available to download. Start by booting your device and installing the gentoolkit package:
emerge gentoolkit equery list
The equery list command should list out all the packages that are installed on your system. This is useful information, however we need the output in a format that we can easily pass to another utility to download the sources with:
equery list | cut -d] -f 2 | cut -d/ -f 2 | grep -v installed\ packages
You will need to remove the version numbers from the end of the output and add a trailing slash, then run the following command and add the packages to the end:
emerge --fetchonly <packages>
Following completion of this command you should now have all the sources for your distribution in /usr/portage/distfiles - you should upload these along with the stage 3 archive and the portage snapshot you used to build the distribution with in addition to a copy of the GPL.
Distribute Your Operating System
Hosting
NAS-Central will host Linux distributions for NAS devices that comply with the GPL. Please see the NAS-Central general forum for more information on how to request upload access to do this.
Uploading Files
Ensure to upload:
- The GPL sources in full
- The stage 3 archive and portage snapshots used in your build
- A separate kernel if necessary
- Your distribution!
Documentation
Ensure to document all installation and post installation steps necessary for your users to use your distribution in the relevant part of the NAS-Central Portal - start with the steps that we skipped above, remember to include a password change and good luck with your distribution!
