Tgames Actualité Consoles et Homebrew

The whiite-linux Installer BETA1
9 Dec 2008, Albert Herranz


1. INTRODUCTION

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.

For more information about whiite-linux please refer to
https://www.gc-linux.org/wiki/WL:whiite-linux

For up-to-date information about the whiite-linux installer, please visit
https://www.gc-linux.org/wiki/WL:whiite-linux-installer


2. OVERVIEW

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.


3. SETUP

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.


3.1 Installer pre-requisites

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)
* https://downloads.sf.net/gc-linux/whiite ... A1.tar.bz2
(the installer kernel package)
* https://downloads.sf.net/gc-linux/whiite ... .6.27b.tar
(a compatible bundle package)
* 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.


3.2 Preparations (using a Linux operating system)

3.2.1 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

* Unmount the USB storage device.

$ sudo mount /media/usb_disk

3.2.2 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 --strip-components 1
$ sudo umount /media/boot


3.3 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 whiite-linux-installer-BETA1/apps/whiite-linux-installer-BETA1/boot.elf

+ (Option B) From your SD card. Please, refer to these articles if you
need help with that:

https://wiibrew.org/wiki/Twilight_Hack
https://wiibrew.org/wiki/Homebrew_Channel


3.4 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 following article:

https://www.gc-linux.org/wiki/WL:whiite-linux

You can cancel and restart the installation at any point using the No or
Cancel options.


4. MINI FAQ

- 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:
- Backup the contents of the SD card you use for The Homebrew Channel
- Get https://downloads.sf.net/gc-linux/whiite ... A1.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 https://downloads.sf.net/gc-linux/whiite ... .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

5. 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.

5.1 Variables

5.1.1 MINIMUM_CARD_SIZE

This variable indicates the minimum card size in MB that the installer
should accept.

Example:

MINIMUM_CARD_SIZE=450 # MBs

5.1.2 FS_MINIMUM_PART_SIZE

This variable indicates the minimum partition size acceptable for the
root filesystem of the whiite-linux system.

Example:

FS_MINIMUM_PART_SIZE=384 # MBs

5.1.3 FS_TARBALL

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:

./dev
./usr
./usr/lib
./etc

(etc)

Example:

FS_TARBALL="debian-etch-4.0+whiite-0.1.tar.bz2"

5.1.4 FS_TARBALL_FILE_COUNT

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.

Example:

FS_TARBALL_FILE_COUNT=12637

5.1.5 KERNEL_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

Example:

KERNEL_TARBALL="whiite-linux-kernel-2.6.27b.tar.bz2"

5.1.6 KERNEL_TARBALL_FILE_COUNT

This variable indicates the number of files present in the kernel package
tarball. It is only used as a hint to properly show a progress bar while
untarring the kernel package tarball.

Example:

KERNEL_TARBALL_FILE_COUNT=7


5.2 Installer Logic

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.

5.2.1 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.


5.3 Installer Concept

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.


5.3.1 Virtual consoles

- 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


6. SOFTWARE USED

The following open source software was used to build this package:

+ Linux Kernel 2.6.27 (https://www.kernel.org/)
+ busybox 1.9.1 (https://busybox.net/)
+ Debian etch (https://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.


7. THANKS

This time thanks go to:

- The Debian project (for making building distros a snap)


8. DISCLAIMER

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.