== Abstract ==
This page shows how to install Debian, using the official Debian installer,
on the Linkstation Live LS-XL.

== Usual warning ==
Do this at your own risk! There is a non-zero probability that you will lose
everything stored on your device. (You may connect a different hard disk to
test these instructions, though)

== Prerequisites ==
* A computer running Linux, with root access
* A working DHCP server on the network
* You can retrieve the IP assigned to your NAS box when it does a DHCP request (or assign it a permanent DHCP bind).
* You may need to take apart your device to remove its hard drive

== Preliminary notes ==
I have noticed that the Debian-provided kernels for similar Buffalo devices (LS-CHL…) do not seem to successfully boot on the LS-XL. Moreover, the 3.3.4 kernel provided by Buffalo only starts up when compiled with the CodeSourcery arm-2007q3 4.2.1 gcc cross-compiler.

I am unsure why other configuration do not work, and the lack of debugging features on the LS-XL do not help.

If someone can shed some light on this, feel free to update this page.

== Debugging == 
[[Image:Ls-xl_uart_small.jpg|thumb|Soldering points]]
The LS-XL has a UART serial port, but requires:

* Three wires to be soldered on the board
* A UART serial device (search on google for USB uart board, can be found for around 2-3€)

The soldering points are not the hardest of points, but if you never have soldered before, you might want to practice elsewhere.

Once you've soldered the wires, connect the wires to the serial board.

Using PuTTY (or the like) select "Serial", the port of your USB device (on Windows it's something like COM13, on linux it's /dev/ttyUSB0).
Set the speed to 115200 like this:

[[File:Putty_serial_configuration.png]]

Hit enter, and power on the LS-XL. 
You should now be able to see bootloader/kernel messages and even change bootloader arguments.

Thanks to Ingmar Klein for the initial [http://forum.doozan.com/read.php?2,15699 pictures] and help.

== Kernel building ==
You first need to rebuild the Buffalo-provided 3.3.4 kernel, with some added configuration options.

Create a work directory, download the toolchain and kernel, and unpack them:
<pre>
mkdir nasbuild
cd nasbuild
wget http://buffalo.jp/php/los.php?to=gpl/storage/ls-x/165/linux-3.3.4.tar.gz -O linux-3.3.4.tar.gz
tar xzf linux-3.3.4.tar.gz
wget http://downloads.buffalo.nas-central.org/LSPro_ARM9/DevelopmentTools/CrossToolchains/CodeSourcery/arm-2007q3-53-arm-none-eabi-i686-pc-linux-gnu.tar.bz2
tar xjf arm-2007q3-53-arm-none-eabi-i686-pc-linux-gnu.tar.bz2
</pre>

Put the toolchain in your <code>PATH</code> and check if it’s working:
<pre>
export PATH=$PWD/arm-2007q3/bin:$PATH
</pre>

Running <code>arm-none-eabi-gcc --version</code> should output:
<pre>
arm-none-eabi-gcc (CodeSourcery Sourcery G++ Lite 2007q3-53) 4.2.1
Copyright (C) 2007 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
</pre>

(If you use a x86_64 system, and you get an error when running this command,
check that the x86_32 supporting libraries are installed)

Go in the <code>linux-3.3.4</code> directory.
Download [http://pastebin.com/8qQNNrpj this kernel config file] and put it in the current directory, under the name <code>.config</code>.
This configuration file is mostly identical to the Buffalo-provided configuration, with some differences to be able to start the Debian installer (hard-coded command line, mostly -- compare this file with <code>buffalo/configs/buffalo_nas_fw_88f6281.config</code> to find the changed options).
Edit the <code>Makefile</code>. At line 196, change
<pre>
CROSS_COMPILE   ?= arm-none-linux-gnueabi-
</pre>
with
<pre>
CROSS_COMPILE   ?= arm-none-eabi-
</pre>
Run <code>make oldconfig</code>. If you want to change some kernel configuration options, run <code>make menuconfig</code> (but note that the kernel we are building here will just be used for running the Debian installer; the final kernel will be built later)

Next, run
<pre>
make uImage modules
</pre>
to build the kernel. (If you have a multiprocessor machine, you can speed up the compilation by adding the <code>-jN</code> option to <code>make</code>, replacing <code>N</code> by the number of processor/cores in your machine).

== Configure the initramfs ==
Download the Debian installer initramfs and put in in a new directory of your work directory:
<pre>
cd ..
mkdir initramfs
cd initramfs
wget http://http.debian.net/debian/dists/unstable/main/installer-armel/current/images/orion5x/network-console/buffalo/ls-chl/initrd.buffalo -O orig_uImage
</pre>
Extract the gzipped initramfs from the uImage, and extract it on a newly created 20M ext2 filesystem:
<pre>
dd if=orig_uImage ibs=64 skip=1 | zcat > orig_initramfs.cpio
dd if=/dev/zero of=initrd bs=1M count=20
/sbin/mkfs.ext2 initrd
mkdir rootfs
sudo mount initrd rootfs
cd rootfs
sudo cpio -idv < ../orig_initramfs.cpio
</pre>

(Note: The Debian-provided <code>initrd.buffalo</code> is an initramfs, but it does not seem to boot correctly on the device, so we convert it to a classic initrd)

Remove the modules from the rootfs and copy the ones which were built with the kernel:
<pre>
sudo rm -r lib/modules/3.13-1-orion5x/
cd ../../linux-3.3.4/
sudo make INSTALL_MOD_PATH=../initramfs/rootfs/ modules_install
cd ../initramfs/rootfs/
</pre>

Create (as root) a file named <code>preseed.cfg</code> in the <code>rootfs</code> directory with the following contents:
<pre>
d-i lowmem/low			note

d-i netcfg/get_hostname string unassigned-hostname
d-i netcfg/get_domain string unassigned-domain

d-i network-console/password password rootme
d-i network-console/password-again password rootme
</pre>

This file is necessary to enable the remote install feature (via SSH).
You can change <code>rootme</code> to another password; you will be prompted for this password when connecting to the Debian installer.

Now unmount the filesystem and pack the initrd:
<pre>
cd ..
sudo umount rootfs
gzip initrd
mkimage -A arm -O linux -T ramdisk -C gzip -a 0x0 -e 0x0 -n initrd -d initrd.gz initrd.buffalo
cd ..
</pre>

== Starting the installer ==
Install [http://tftpy.sourceforge.net TFTPy] (on Debian, you can install the <code>python-tftpy</code> package).
Add the static IP <code>192.168.11.1</code> (netmask <code>255.255.255.0</code>) to your machine’s network interface.
Create a tftp root folder, copy the kernel and initrd into it, and start the TFTP server:
<pre>
mkdir tftpboot
cp linux-3.3.4/arch/arm/boot/uImage tftpboot/uImage.buffalo
cp initramfs/initrd.buffalo tftpboot/initrd.buffalo
sudo /usr/share/doc/python-tftpy/examples/tftpy_server.py -r tftpboot/
</pre>

Remove the hard drive from your device (to force it to start from TFTP), and plug it in.

The TFTP server should start displaying messages indicating that the kernel and the initrd are being loaded 10 seconds after power-up. '''Plug the disk as soon as the messages start to appear''' or else the disk will not be seen by the installer. 30 seconds later, the device should require an IP address from the DHCP server, and start using it.

You can now connect to the device and access the Debian installer with:
<pre>
ssh -o "UserKnownHostsFile /dev/null" installer@192.168.1.35
</pre>
(If you get a “Connection refused” error, wait a little bit)
Use the password you provided earlier (<code>rootme</code> by default).

You should, finally, get the Debian Installer network console.

== Kernel rebuild ==
While Debian is installing, you can prepare the kernel you will use on the device.

Go back to the <code>nasbuild</code> folder, put the toolchain path back in your PATH if you switched shells, go inside the <code>linux-3.3.4</code > directory, and run <code>make menuconfig</code>.

You need at least to change the <code>Boot options => Default kernel command string</code> and change
<pre>
console=ttyS0,115200 root=/dev/ram0 panic=5 lowmem=1
</pre>
to
<pre>
console=ttyS0,115200 root=/dev/sda2 panic=5 lowmem=1
</pre>
(this assumes that you will install Debian on the second partition of your drive). Save the new configuration and type <code>make uImage</code> to rebuild the kernel.

== Empty initramfs creation ==
The LS-XL’s bootloader insists on having an initrd to load along with the kernel, so we need to provide an empty one.
You can generate it by using:
<pre>
dd if=/dev/zero of=initrd bs=1M count=1
/sbin/mkfs.ext2 initrd
gzip initrd
mkimage -A arm -O linux -T ramdisk -C gzip -a 0x0 -e 0x0 -n initrd -d initrd.gz initrd.buffalo
</pre>

== Installation ==
The installer prompt should let you specify if you want to start the installer normally, or in expert mode. You should choose expert mode to get the extra installer questions (which are useful in our case).

Some installation steps (where special action is needed) are detailed below. For the others, refer to the official Debian documentation.

=== Kernel modules ===
Despite the kernel modules being copied in the installer image in the previous steps, the installer complains that no kernel modules are found.
This is harmless; just allow the installer to continue.

=== Installer components ===
On the “Download installer components” page, select “openssh-client-udeb” and “partman-ext3” and continue.

=== Disk partitioning ===
In order to boot the system from the hard drive, the following condition should be met:
* The drive should be partitioned using the GUID Partition Table format (GPT)
* Partition 1 should be formatted using the ext3 format (ext4 does not work)
* Partition 1 should contain the kernel and initramfs at its root.

It is clear that the first partition on the drive should be the /boot partition.

==== GPT partition format ====
This step is optional if you use the original drive for your device (and it was not damaged or altered), or if you know that the drive you use is using GPT (which is rarely the case).
In the partition tool, select the full drive (<code>SCSI1 (0,0,0) (sda)</code>). Select Yes when asked if a new partition table should be created. Select “gpt” in the list.

==== Partitioning ====
You should probably delete and recreate every partition, except the big XFS partition at the end of the drive if you use your device’s original hard disk (it’s the partition which contains the files you stored on your NAS)..

* As said before, you should create a small (around 256MB) ext3 partition at the start of the drive, which will be mounted on /boot. You can probably set the <code>nodev</code>, <code>nosuid</code>, <code>noexec</code> and <code>ro</code> flags on this file system.

* For the root partition (mounted on /), it is probably better to use ext3 or ext4. The partition should be at least 10-20GB.

* Since the LS-XL has only around 50MB of usable memory, you should probably create a 1 or 2GB swap partition.

=== Kernel install ===
The installer will complain that there is no kernel to install. This is also expected.

=== Software selection ===
Ensure that the “SSH server” entry is selected, or you will not be able to access the device after the installation!

=== Bootloader ===
The installer will tell you that it can not install a boot loader. This is expected.

'''Do not finish the installation at this point!'''
You still need to copy the kernel you have recompiled in your system, and add a fake inited.
To do this:
# Select the “Execute a shell” option
# <code>cd</code> to <code>/target/boot</code> (the /boot partition you created earlier)
# Run <code>sftp user@host</code> to connect to your computer (which needs to be running a SSH server)
# Navigate (using <code>pwd</code>, <code>ls</code> and <code>cd</code>) to the <code>nasbuild/linux-3.3.4/arch/arm/boot</code>
# Run <code>get uImage uImage.buffalo</code> to copy the kernel image you’ve compiled to your device’s <code>/boot</code> partition, renaming it <code>uImage.buffalo</code> in the process (this is necessary for the bootloader to find it).
# Navigate to the folder where you generated the empty <code>initrd.buffalo</code>
# Run <code>get initrd.buffalo</code> to copy it to the boot partition
# Type Control-D to exit <code>sftp</code>
# Type Control-D to exit the installer shell

You can now finish the installation.
Your newly-installed Debian should start up automatically, and request an adress by DHCP. You can now access it by SSH.

== Further setup ==
=== Hostname setting ===
Your hostname may have not been set during the installation. You can set it by following this procedure: https://wiki.debian.org/HowTo/ChangeHostname


=== Locales ===
In case the locales were not configured correctly on the system, you can reconfigure them by running:
<pre>
dpkg-reconfigure locales
</pre>

=== Bootlogd ===
<code>bootlogd</code> can be used to log the console output during the boot process, which may be useful for troubleshooting boot issues.
To activate it, install the <code>bootlogd</code> package and reboot.
In the event of a boot process failure, you will be able to debug the issue by restarting the Debian installer, starting a shell, mounting the root device and examining the <code>var/log/boot</code> file.

=== Stop the blinking LED after complete boot ===
To make the LED stop blinking after the boot process, you can add the line
<pre>
echo off > /proc/buffalo/gpio/led/power_blink
</pre>
before the <code>exit 0</code> line in the <code>/etc/rc.local</code> file.

=== Clock setting ===
The LS-XL loses the time when it is unplugged. To set it when a network connection becomes available, install <code>ntpdate</code>.

=== System halt ===
When the LS-XL is halted, it automatically reboots.
The solution to this is to put it in a low power state (HDD stopped, LED off) instead of trying to shut it down

Change the /etc/init.d/halt script:
Before
<pre>
halt -d -f $netdown $poweroff $hddown
</pre>
add the lines
<pre>
echo off > /proc/buffalo/gpio/led/power
echo off > /proc/buffalo/gpio/power_control/hdd0
sleep 300
</pre>

[[Category:LS-XL]]