whiite-linux-installer: A simple installer for a whiite-linux system
The whiite-linux installer is a special gc-linux kernel image that can be used to prepare and install a whiite-linux system into a compatible SD card using your Nintendo Wii videoconsole.
The whiite-linux installer kernel runs natively on the Nintendo Wii. Once booted, the installer displays a series of text-based dialogs which can be interacted with the help of a USB keyboard.
The installer requires two files, in a specific format, available from a USB storage device:
- a filesystem tarball
- and a kernel tarball
If these files are successfully located, the installer checks for a valid SD card and, once the user agrees, it re-partitions the card as needed by the whiite-linux system and as indicated by the user.
As a result of a successfull installation process, the SD card used will contain a FAT filesystem compatible with The Homebrew Channel on the first partition and a Linux ext3 filesystem on its second partition. The Linux filesystem, together with a compatible kernel, can be used to turn a Nintendo Wii into a fully functional PowerPC Linux system on the cheap.
The following sections explain how to get a whiite-linux system installed into an empty SD card of your choice using the whiite-linux installer.
DISCLAIMER: THE whiite-linux INSTALLER ERASES THE CONTENTS OF YOUR SD CARD. BACKUP THE DATA ON THE SD CARD BEFORE CONTINUING IF YOU WISH TO PRESERVE ANY INFORMATION.
The use of the whiite-linux installer has the following requirements:
- a USB keyboard
- a USB storage device (USB disk, USB stick, USB card reader, etc.)
- a SD card (512 MB minimum, 2 GB or larger recommended)
- http://downloads.sf.net/gc-linux/whiite-linux-installer-BETA1.tar.bz2 (the installer kernel package)
- http://downloads.sf.net/gc-linux/whiite-linux-bundle-0.1_2.6.27b.tar (a compatible bundle package, this one installs the original whiite-linux 0.1 distro with the 2.6.27b kernel)
- A "bootloader", like the Twilight Hack or the Homebrew Channel.
The USB storage device will be used to make the bundle package contents available to the installer.
The SD card will be used to install the whiite-linux system on it.
Preparations (using a Linux operating system)
Untar the bundle package into the USB storage device
- Mount your USB storage device, using whatever method you usually use. (You only need to mount it manually if your Linux distribution doesn't automount it).
For example (assuming /dev/sdx1 is an useable partition within your USB storage device):
$ sudo mkdir -p /media/usb_disk $ sudo mount /dev/sdx1 /media/usb_disk
- Untar the bundle package into the USB storage device.
$ sudo tar -C /media/usb_disk -xvf /tmp/downloads/whiite-linux-bundle-0.1_2.6.27b.tar -o
- Unmount the USB storage device.
$ sudo umount /media/usb_disk
Untar the compressed installer kernel package
The archive boot.elf within the installer kernel package contains the whiite-linux installer kernel image.
- (Option A) Untar the installer kernel package into a directory within your PC if you plan to launch the installer using wiiload (or similar).
$ cd /home/isobel $ tar -xjvf /tmp/downloads/whiite-linux-installer-BETA1.tar.bz2
- (Option B) Untar the installer kernel package into the SD card used by your "bootloader".
For example (assuming /dev/sdy1 is the FAT partition of your SD card used with the Homebrew Channel):
$ sudo mkdir -p /media/boot $ sudo mount /dev/sdy1 /media/boot $ sudo tar -C /media/boot -xjvf /tmp/downloads/whiite-linux-installer-BETA1.tar.bz2 -o $ sudo umount /media/boot
Preparations (using a Windows operating system)
1)Download the bundle package.
2)Double Click on "My Computer"
3)Find your Flash Memory Device,and open it by doubleclick.
4)Open the bundle package by your favorite app.
5)Open the folder called "whiite-linux-bundle ... "
6)Extract files in folder into the root of your Flash Memory Device.
Launching the installer
- Insert the USB storage device into one of the two USB ports available at the rear of the Nintendo Wii.
The USB storage device should contain the bundle package contents untarred as per the previous section.
- Connect the USB keyboard to the remaining USB port of the Nintendo Wii.
- Power on your Nintendo Wii videoconsole.
- Load your "bootloader" of choice.
- Boot the whiite-linux installer kernel image (i.e. the boot.elf file contained within the installer kernel package).
- (Option A) From your PC using wiiload + The Homebrew Channel.
- For example (assuming that your Nintendo Wii IP is 192.168.1.47):
$ cd /home/isobel $ WIILOAD=tcp:192.168.1.47 wiiload apps/whiite-linux-installer-BETA1/boot.elf
- (Option B) From your SD card. Please, refer to these articles if you need help with that:
Interacting with the installer
Once the whiite-linux installer boots you will be presented with a welcome text screen.
Always follow the on-screen instructions to proceed with the installation.
You can use the USB keyboard to interact with the installer dialogs. By default, all actions that can cause data loss will be announced with a proper warning dialog and the user will need to explicitly agree by choosing a different option than the default option.
When the installation is finished you will be presented with a congratulations dialog. After accepting this dialog the videoconsole will be rebooted and the whiite-linux system will be useable as documented in the whiite-linux article.
You can cancel and restart the installation at any point using the No or Cancel options.
- Q: I'm a Windows user and I still don't get it. How can I partition my card and install whiite-linux on it?
- A: Ok. Briefly, this is one way of doing it:
- Backup the contents of the SD card you use for The Homebrew Channel - Get http://downloads.sf.net/gc-linux/whiite-linux-installer-BETA1.tar.bz2 - Open it and copy the whole "apps" directory with its subdirectories and files to the root of the SD card that you use with The Homebrew Channel - Get http://downloads.sf.net/gc-linux/whiite-linux-bundle-0.1_2.6.27b.tar - Open it and copy the following three files to the root directory of a USB stick (copy them as is, do not decompress them): - whiite-linux-installer.conf - debian-etch-4.0+whiite-0.1.tar.bz2 - whiite-linux-kernel-2.6.27b.tar.bz2 - Connect a USB keyboard and the USB stick to the Nintendo Wii - Boot The Homebrew Channel with your SD card inserted and select the "whiite-linux Installer" icon - Once the installer has booted, and shows the welcome screen, you have to decide wether you: - (option A) put a new *BLANK* SD card into the front SD card slot - (option B) *ERASE* the card that is currently inserted and that you have backed up on the first step - Follow the installer instructions, and choose an appropiate size for the Homebrew Channel partition. - Once the installer has finished it will reboot your console. - Boot The Homebrew Channel with your SD card inserted and select the "whiite-linux k2627b" icon - DO NOT REMOVE THE SD CARD WHILE LINUX IS RUNNING - ALWAYS SHUTDOWN LINUX CLEANLY (CTRL-ALT-DEL IS OK) - If you choosed (option B) before, then you can manually copy back to the FAT partition of the SD card the contents backed up on the first step
Hints for whiite-linux distro builders and tweakers
The whiite-linux installer uses a configuration file called whiite-linux-installer.conf. The configuration file follows the ash shell syntax and contains a series of variables that can modify the behaviour of the whiite-linux installer.
This variable indicates the minimum card size in MB that the installer should accept.
MINIMUM_CARD_SIZE=450 # MBs
This variable indicates the minimum partition size acceptable for the root files ystem of the whiite-linux system.
FS_MINIMUM_PART_SIZE=384 # MBs
This variable indicates the name of the tarball file that contains the root file system of the whiite-linux-system. This file must be a tar.bz2 file and the files contained in it must untar directly to the root of the filesystem.
A typical listing of the tarball will be of the form:
./ ./lib/ ./lib/libctutils.so.0 ./lib/libSegFault.so ./lib/tls/ ./lib/tls/libSegFault.so ./lib/tls/libthread_db.so.1 ./lib/tls/libBrokenLocale-2.3.6.so ./lib/tls/libcrypt.so.1 ./lib/tls/libpcprofile.so [...]
This variable indicates the number of files present in the root filesystem tarball. It is only used as a hint to properly show a progress bar while untarring the root filesystem tarball.
This variable indicates the name of the tarball file that contains the kernel package of the whiite-linux-system.
This file must be a tar.bz2 file and the files contained in it must have a Homebrew Channel compatible structure with one directory level extra for the package itself.
A typical listing of the tarball will be of the form:
./whiite-linux-kernel-2.6.27b/apps/whiite-linux-2627b/boot.elf ./whiite-linux-kernel-2.6.27b/apps/whiite-linux-2627b/readme.txt ./whiite-linux-kernel-2.6.27b/apps/whiite-linux-2627b/meta.xml ./whiite-linux-kernel-2.6.27b/apps/whiite-linux-2627b/icon.png
This variable indicates the number of files present in the kernel package tarbal l. It is only used as a hint to properly show a progress bar while untarring the kernel package tarball.
As seen during this document, the installer needs 3 files to operate:
- the whiite-linux-installer.conf configuration file
- a filesystem tarball
- and a kernel tarball
These three files when packed together is what we call the "bundle". A bundle is handy to distribute a kernel and a filesystem in a installable form, but the installer can't operate with the bundle directly: it requires someone to extract the three files within the bundle to a USB stick.
In some special cases, it may make no sense to distribute a bundle. For example, suppose that you have already published a large filesystem tarball of your distro. Instead of creating a bundle with the large filesystem tarball, a kernel tarball and a whiite-linux-installer.conf file, you may want to create just a mini-bundle with the kernel tarball and the whiite-linux-installer.conf file only and let the user put together the contents of the mini-bundle and the previous large filesystem tarball to a USB stick.
The whiite-linux installer will try to find a file called whiite-linux-installer.conf in any available USB disk. The file whiite-linux-installer.conf must be placed at the root directory level or within one directory level, otherwise the installer will ignore it.
If the whiite-linux installer cannot find the file whiite-linux-installer.conf it will use hardcoded defaults valid to install the original whiite-linux 0.1 distribution, provided that the installation media is available.
If the whiite-linux installer finds the whiite-linux-installer.conf file it will try to honour its settings. The tarballs specificed (using the FS_TARBALL and KERNEL_TARBALL variables) will be first searched in the directory where the whiite-linux-installer.conf file is located. If a tarball is not found there, the whiite-linux installer will look for it across all the available USB disks using the same rules applicable to the search of the 'whiite-linux-installer.conf' file.
If the SD card has the proper size and the tarballs are found, the installer will proceed.
Special partition layout case
The whiite-linux installer will behave slightly different if a properly sized Linux filesystem is found at the second partition of the SD card, and a FAT filesystem is found at the first partition of the same card. In this particular case, the installer will not re-partition the SD card, but will use the existing partition layout.
The first partition of the SD card will be left unaltered. But, in this case, and if the user agrees, the existing Linux filesystem will be wiped out (erased!) and reinstalled using a fresh copy from the installation tarballs.
The whiite-linux installer kernel includes a initramfs containing all the required files to run the installer itself.
The installer is fully written as an ash shell script and relies heavily on whiptail to interact with the user.
- tty1 is where the installer runs
- tty2 and tty3 can be used to "log in" while the installer runs
- tty4 is where the installer sends standard error messages
The following open source software was used to build this package:
- Linux Kernel 2.6.27 (http://www.kernel.org/)
- busybox 1.9.1 (http://busybox.net/)
- Debian etch (http://packages.debian.org)
- Package: libnewt0.52 (0.52.2-10)
- Package: whiptail (0.52.2-10)
- Package: strace (4.5.14-2)
- Package: ncurses-base (5.5-5)
- Package: libc6 (2.3.6.ds1-13etch7)
- Package: libslang2 (2.0.6-4)
- Package: libbz2-1.0 (1.0.3-6)
- Package: libsepol1 (1.14-2)
- Package: libpopt0 (1.10-3)
- Package: e2fslibs (1.39+1.40-WIP-2006.11.14+dfsg-2etch1)
- Package: libselinux1 (1.32-3)
- Package: libblkid1 (1.39+1.40-WIP-2006.11.14+dfsg-2etch1)
- Package: libuuid1 (1.39+1.40-WIP-2006.11.14+dfsg-2etch1)
- Package: libdevmapper1.02 (2:1.02.08-1)
- Package: libcomerr2 (1.39+1.40-WIP-2006.11.14+dfsg-2etch1)
- Package: dosfstools (2.11-2.1+b1)
- Package: e2fsprogs (1.39+1.40-WIP-2006.11.14+dfsg-2etch1)
- Package: util-linux (2.12r-19etch1)
- Package: bzip2 (1.0.3-6)
- Package: tar (1.16-2etch1)
All software, except the Linux kernel, was built natively on a Nintendo Wii running whiite-linux. The Linux kernel was cross-compiled using an x86 machine.
THIS PROGRAM IS NOT AFFILIATED WITH NINTENDO. IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE AUTHOR HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.