View source for DebXO

[[DebXO]] was a set of OS images and build scripts for the Debian [[Linux]] distribution that could be run on your XO.  It was maintained by Andres Salomon; bug reports should be sent to: dilinger AT queued DOT net .  Build scripts are still available if you want to try to make your own images.  See also [[Installing Debian as an upgrade]] and [[Debian Jessie on XO]].

== Latest images ==
The latest release (described below) could be found at http://lunge.queued.net/~dilinger/debxo-latest .  This site is now down.  Conact Andres or OLPC if you need these images brought back online.  The scripts for building them are still available, but some tweaks will be needed to handle expired PGP keys.

See the [[DebXO#Installation|Installation]] section below for instructions on using these images.

== New features/changes in DebXO 0.6 ==

* Update distribution to Squeeze.  Major packages and desktops have been upgraded.

* Update kernel to (an almost-stock-Linus, with the exception of a few patches pulled from the -next tree) 2.6.37-rc4+, rework the config to closely match the Debian stock kernel config.  This means lots and lots of random modules are now enabled, so support for random USB or SDIO devices should Just Work.  The camera driver is currently disabled (as it's broken).

* Switch the nand images from using jffs2 to UBIFS.  This makes an amazing difference in terms of usability; over time jffs2 filesystems get slower, while UBIFS keeps on chugging along.

* Initial XO-1.5 support.  It's still rough around the edges, but it's functional (currently xorg.conf and /boot/olpc.fth must be edited).

* Switch from autox to nodm for LXDE, and XFCE desktops.  LXDE usability has been vastly improved (for example, wicd is installed and configured automatically; LXDE can now get online).  Webkit-based browsers are used throughout - less ram thrashing throughout.

* KDE image has been dropped (at least for now).  KDE4 took at least 10 minutes to start up and then crashed, so.. I'll deal with it another time.  Patches to make it work accepted!

* Awesome image has been dropped.  I'd intended to replace this with XMonad (as that's what I actually use), but currently that requires some tweaking and needs to drop about 300MB of devel libs.  So for now, it's just dropped.

* Hal is no longer used.  Key bindings are pulled from DMI and loaded by udev (note: upgrade your version of OFW if hitting the 'fn' key results in lots of '='s.  Alternatively, add "/lib/udev/keymap /dev/input/event0 olpc-xo" to your /etc/rc.local to auto-load the proper keymap).

== New features/changes in DebXO 0.5 ==

* OFW q2e30+ freezes the DCON on boot, so DebXO's olpc.fth now unfreezes it.  If you upgraded your machine to q2e30 and it looked like DebXO no longer worked.. this version of DebXO will work.  Alternatively, you can just edit your /boot/olpc.fth to add the line "dcon-unfreeze" before the "boot" line.

* The Sugar desktop has gotten an upgrade, from Sugar 0.81 to 0.82.

* There's a new XFCE desktop, courtesy of Erik Garrison.

* Desktops will now auto-start X.  Gdm and Kdm have been dropped from the images.  If you want them back, just 'apt-get remove autox' and 'apt-get install gdm' (or kdm).

* Youtube has now been made possible via Totem in Gnome. Under the Edit->Plugins tab, select the Youtube plugin. After selecting the plugin, select the show Sidebar in the View tab. When the sidebar appears, click under the Playlist box, and select Youtube. Files play at full speed and buffer correctly, even at full screen.

== New features/changes in DebXO 0.4 ==

* Gnome improvements: the battery applet shows up properly, GUI apps that require root access (ie, the stuff in System->Administration) should launch properly despite lack of a password, auto-mounting of SD and USB keys is now enabled.

* A new geode Xorg driver (2.11) is included.  This fixes font issues with a number of applications, and things simply look better.  With 0.3, the default fonts in LXDE looked terrible; in 0.4, this is no longer the case.  Applications like NetSurf (where font size cannot be overridden) are now usable.

* Better hardware support; the MIC LED no longer is on by default, the ALSA driver saw a bunch of updates, and the gamekeys now work.  I've mapped the gamekeys to scroll on the right, and support pageup/pagedown on the left.  This could change later on, depending upon feedback and what HAL ends up accepting upstream.  The brightness and sound adjustment keys on the keyboard now work.

== New features/changes in DebXO 0.3 ==

* Disable LZO compression in the JFFS2 driver.  This was causing machines to fail to boot after upgrading the kernel.  If you're still running DebXO 0.2 on the nand, do not upgrade the kernel.  Instead, reflashing is recommended.

* A new 'base' desktop has been added.  This is a minimal install, with no graphics or X at all.  It's good for rescue situations, or where you have a local package mirror and don't want to waste bandwidth downloading a graphical desktop image.

* Some programs (including kde and gnome's logout/reboot functions) had problems in previous releases due to lack of loopback interface (oops).  Thanks to James Cameron for spotting this.  0.3 sets up 'lo' properly.

* Custom DebXO packages are put on hold; this means you can safely  entery <tt>apt-get dist-upgrade</tt> without having to fear things like initramfs-tools being upgraded.

* JFFS2 images uses DOS 8.3 filenames.  This is primarily to ensure that when running <tt>update-nand disk:\gnome.img</tt> using a USB flash drive that's been formatted using vfat, OFW won't complain about not being able to find the gnome.dat file.   As such, the JFFS2 images are named with their desktop names &mdash; <tt>awesome.img</tt>, <tt>kde.img</tt>, etc.  EXT3 images still retain the old naming scheme.

* James Cameron added a script that is capable of creating an auto-install USB key (onto nand). 

* A debxo-latest symlink now points to the latest release.  Please use that in wiki/doc pages for download links.

== New features/changes in DebXO 0.2 ==

* The JFFS2 images now have partition support.  While this shaves a number of seconds off of the boot time, we can take better advantage of it in the future (doing things like using UBIFS).  JFFS2 is well past its prime; moving away from it will help performance a lot.

* EXT3 images are available.  This allows for booting off of USB and/or SD.  Note that the image size I chose is 2GB, so you'll need a USB flash drive or SD card of at least that size.

* The kernel is now almost completely modular, and includes every module under the sun.  For those of you with random USB hardware that wanted to use it with DebXO.. if it's in 2.6.25, it should work with DebXO.

* New desktops!  DebXO 0.1 only had a Gnome desktop; this release includes options for KDE, LXDE, Sugar, Awesome and Gnome desktops.  I personally run (and work on) the Gnome desktop.  Holger Levsen is to thank for the Sugar and Awesome desktops.  James Cameron did the work for the KDE and LXDE desktops.  A huge thanks to both of them!

== Known bugs ==

* Messing with gnome packages in the gnome desktop results in gconftool-2 getting called from dpkg.  If you're doing this from within X, it will consume all of the XO-1's available memory; see http://bugs.debian.org/593849 for details.  The workaround is either to shut down X to finish the upgrade (doing it from a virtual console), or don't use gnome.

* Power management is currently not enabled.  It's on the roadmap.

* KDE and Awesome images are disabled (for DebXO 0.6).

* The camera driver is disabled due to a crash in the kernel.

* Upon first bootup, the LXDE and XFCE desktops display a wicd error.  It only happens on the first boot, so I think it's related to copying files around.  Just restart and it'll go away.

* Also upon first bootup, if you reboot XFCE via the menu (logout->reboot), it appears to kill the panel prior to saving the startup applications.  This means that when XFCE boots up the second time, there's no panel or desktop.  I believe that this is an XFCE race; after the first boot, using the menu to reboot doesn't break anything.  So, just open up a terminal and "sudo reboot" the first time, if using XFCE.

* Nodm doesn't currently set ~/.Xauthority; see http://bugs.debian.org/605633 .  This means gksu (and gksudo) are broken.  For now, just open up a terminal and call (for example) "sudo synaptic".

* The volume/brightness keys are mapped to function keys.  It's unclear how best to handle this, as it is useful to have f11, for example.  Will figure something out later.

* Due to a switch from Hal to udev and upower, battery status reporting is broken.  This is fixed with a pending kernel update, but it's in the process of being pushed upstream (and therefore will be fixed in 0.7).

== Installation ==

=== Prerequisites ===

'''You need a [[developer key]] to run this release!'''  Start by [[jailbreaking the XO]] if you haven't already.   Then when you reflash your machine and unplug your USB memory stick, the system will boot Debian rather than making you jump through unlocking hoops again. More details are at the [[Activation and developer keys]] page.

To install the DebXO release onto NAND flash, you will also need to be running [[Open Firmware]] release Q2E20 or later (see [[How to check the OS and firmware versions]]).  If running DebXO from an SD card or USB stick, upgrading the firmware should not be necessary.
: The q2d* series do not support <tt>update-nand</tt>, and versions q2e18 and q2e19 are known to be buggy
with partitions.  Firmware and instructions for upgrading are at [[Firmware]].  You'll need a developer key, or to disable security as above, merely to reflash your firmware, too.

=== Installation onto the XO's build-in NAND flash memory ===

The NAND images could be found at http://lunge.queued.net/~dilinger/debxo-latest/images/nand/ but the site is down.  Contact the DebXO maintainer or OLPC if you need the old prebuilt images.

To install onto the XO's flash, download the <tt>''$DESKTOP''.dat</tt>
and <tt>''$DESKTOP''.img</tt> files to a USB or SD stick (where ''$DESKTOP'' is
one of the various desktops - gnome, kde, lxde, sugar, or awesome; note that 'base' is 403 forbidden as of 5/22/2010).
Boot into Open Firmware (make sure your XO is unlocked!), and run
  update-nand disk:\''$DESKTOP''.img

or

  update-nand sd:\''$DESKTOP''.img

(depending upon whether you downloaded to an SD or USB disk).

If update-nand spits out any errors, make sure you're running an
appropriately up-to-date version of OFW.

=== Installation onto SD/USB ===

The ext3 images could be found at http://lunge.queued.net/~dilinger/debxo-latest/images/ext3/ but the site is now down.  Contact the DebXO maintainer or OLPC if you need the prebuilt images.

To install onto an SD or USB device, download the
debxo-''$DESKTOP''.ext3.img.gz file (where ''$DESKTOP'' is one of the various desktops - gnome, kde, lxde, sugar, or awesome), and run

  zcat debxo-''$DESKTOP''.ext3.img.gz > /dev/mmcblk0

or

  zcat debxo-''$DESKTOP''.ext3.img.gz > /dev/sdX  (for instance, sdb; not sdb1)

(depending upon whether you're writing to an SD or USB disk).  Note
that this will overwrite any data that is on the SD or USB disk.

Note: this method is not necessarily portable to any other operating system build apart from DebXO.

== Also you can use dd instead of zcat after decompressing the file ==


<pre>sudo dd if=debxo-$DESKTOP.ext3.img of=/dev/sdX bs=4</pre>

==== For media larger than 2GB ====

If you follow the instructions above and install DebXO onto an SD card or USB drive that is larger than 2GB, the DebXO partition created during the install will only be 2GB in size and the rest of the volume will not be used. To use the entire volume, you can expand the DebXO filesystem using the gparted program. Boot into Sugar from your internal flash memory, change to the Gnome desktop, connect to the Internet, open a terminal, and type:

<pre>
sudo yum install gparted.i586
</pre>

to install gparted. Then insert your USB drive or SD card and run

<pre>
sudo gparted
</pre>

In gparted find your DebXO device, find the ext3 filesystem labelled DebXO, and resize it to fill the entire volume. If you have a large volume (e.g. 16-32GB) this will take a long time. After resizing the volume you can reboot from your SD card, and boot into DebXO to find much more free space in your filesystem.

There is a bug in some versions of gparted that means the SD card will not show up in gparted. If you're getting that, you can get around it by specifying your SD card on the command-line when you launch gparted:

<pre>
sudo gparted /dev/mmcblk0
</pre>

==== For media smaller than 2GB ====
The disk images are about 2GB big, but since they are not full, you don't necessarily need to buy a new SD card if yours is smaller than 2GB.

# Prepare the device (SD or USB disk).
#* Use a partition editor (e.g. parted) to set the type to 'Linux' (x83) (There is probably only one partition on the device, e.g. /dev/sdX1.)
#* Make an ext3 filesystem, e.g. <tt>mkfs.ext3 /dev/sdX1</tt>
#* Set the partition label to 'DebXO', e.g. <tt>e2label /dev/sdX1 DebXO</tt>, otherwise the bootscripts won't find it. 
#* Mount this partition at, say, <tt>/media/sdreal</tt>
# Mount the downloaded image.
#* gunzip the image file
#* Find the offset of the ext3 partition within the image file (usually 16384): 
 <nowiki>
gunzip /location/of/your/image/debxo-lxde.ext3.img.gz
mkdir -p /media/sdloop
img=/location/of/your/image/debxo-lxde.ext3.img
partition_start=$(parted -s "$img" "unit B" "print" | sed -ne 's/^ 1[[:space:]]\+//p' | cut -dB -f1)</nowiki>
#* loopmount it as ext3 at, say, <tt>/media/sdloop</tt>  
 <nowiki>mount -t ext3 -o offset=$partition_start,loop $img /media/sdloop</nowiki>
# Copy the guts of the image onto your device.
#* e.g. <tt>rsync -a /media/sdloop/ /media/sdreal/</tt>, or
#* e.g. <tt>cp -ar /media/sdloop/ /media/sdreal/</tt>
# Unmount.

If the copy to succeeded completely, plug that SD card (or USB drive) into the XO as continue with the rest of this page as you would have done if you'd had a >2GB device.

== Usage ==

By default, a user 'olpc' is created (with no password, and sudo
access).  Some desktops automatically start a display manager and log
you in; some do not.  The root password is disabled by default.  This
is a stock Debian Lenny system with only a few modifications, so it can
obviously be tailored.


== Hacking ==

'''xodist''' is the name of the collection of scripts that are used to
produce DebXO.  The git repository can be downloaded via:

  git clone git://spindle.queued.net/xodist

There's also a web interface to that:

  https://spindle.queued.net/cgi-bin/gitweb.cgi?p=xodist;a=summary

Help is always appreciated.  The roadmap for future releases can be found
here:

https://spindle.queued.net/cgi-bin/gitweb.cgi?p=xodist;a=blob;f=TODO

There is also a mirror of this repository at:

  https://github.com/xloem/debxo

Development discussions happen on IRC as well, on irc.oftc.net in #DebXO, although this channel is now empty.

== Updating ==

=== Updating the distribution ===
The <tt>apt</tt> package manager command should Just Work for the majority
of the distribution, but there are a few custom packages that are put on hold by default.   This requires some extra steps.  Also, the kernel package *MUST* be upgraded, as newer versions of udev require a kernel newer than what was in 0.5.  The instructions below are for upgrading a DebXO 0.5 system to Debian Squeeze or Sid (Squeeze is recommend, of course, as Sid is unstable and could break your system).

1 - First, we'll take some packages off hold:
  
  echo xserver-xorg-video-geode install | sudo dpkg --set-selections
  echo initramfs-tools install | sudo dpkg --set-selections

2 - Next, install some packages from the lenny-backports distribution

  sudo cp /etc/apt/sources.list /etc/apt/sources.list.orig
  cp /etc/apt/sources.list sources.list
  echo "deb http://backports.debian.org/debian-backports lenny-backports main contrib non-free" >> sources.list
  sudo mv sources.list /etc/apt/
  sudo apt-get update
  sudo apt-get install -t lenny-backports initramfs-tools xserver-xorg-video-geode olpc-xo1-hw
  sudo mv /etc/apt/sources.list.orig /etc/apt/sources.list

3 - At this point, you should be able to simply edit your /etc/apt/sources.list to use whatever distribution you'd like, apt-get update, and apt-get dist-upgrade.  The packages from lenny-backports should be updated to the equivalent squeeze or sid versions without any problems.

4 - Install a newer kernel.  Grab it from http://lunge.queued.net/~dilinger/debxo-0.6/, and install with "sudo dpkg -i linux-image-2.6.37-rc1+_2.6.37-rc1+-47_i386.deb".  If desired, also grab and install the related linux-firmware-image package (it's not required, but it has firmware for things that one might plug in via USB).  Make sure all the symlinks are pointing to the right place (see below about kernel upgrades).

=== Upgrading the kernel ===
As far as upgrading the kernel, it depends on how it's built.  Note that
/boot/olpc.fth uses /vmlinuz and /vmlinuz.old symlinks, so make sure that
they're pointed to the correct image after you've upgraded.

=== Xorg changes ===
By default, DebXO does not use an xorg.conf.  In order to generate one (after stopping X via ''sudo /etc/init.d/gdm stop'' or equivalent), run:
  sudo Xorg -configure
  sudo mv xorg.conf.new /etc/X11/xorg.conf
This is necessary for certain things; For example, when using a USB-VGA adapter to add a VGA monitor to your XO, you need to edit an xorg.conf to add something like:
  Section "Device"
  Identifier "SIS USB-VGA"
  Driver "sisusb"
  EndSection

=== Using an external screen or projector ===

The XO-1 doesn't have a video-out port but you can use it with an external screen or projector via a USB-VGA converter. The following process is said to work with SiS USB-VGA adapters, see:

  http://www.startech.com/item/USB2VGA2-USB-VGA-External-Multi-Monitor-Video-Adapter-High-Resolution.aspx
  http://wiki.laptop.org/go/Remote_display
  http://wiki.laptop.org/go/Adding_USB_SVGA

The following procedure will disable your XO-1's internal screen in favor of your external display. If you make a copy of the <tt>xorg.conf</tt> file before editing it in step 6, then you'll be able to re-enable the internal screen by putting the unedited <tt>/etc/X11/xorg.conf</tt> back in place and repeating step 7.

To be able to login in step 2 below, you may need to add a password to user olpc (who does not have a password by default) first. If you're using the Gnome desktop environment you can add a password by running <tt>gnome-control-center</tt> and going to "Users and Groups".

1. Stop the X server. Assuming you're running Gnome Display Manager (gdm) the command is: <tt>sudo /etc/init.d/gdm stop</tt>

2. This will dump you into a text-only environment. Now log in and do: <tt>sudo Xorg -configure</tt> This will create an xorg configuration file at <tt>~/xorg.conf.new</tt>

3. Now you can start X again. If you use gdm: <tt>sudo /etc/init.d/gdm start</tt>

4. <tt>mv ~/xorg.conf.new /etc/X11/xorg.conf</tt>

5. <tt>sudo aptitude install xserver-xorg-video-sisusb</tt>

6. Edit <tt>/etc/X11/xorg.conf</tt>, add the following section:

     Section "Device"
       Identifier "SIS USB-VGA"
       Driver "sisusb"
     EndSection

And also replace "Card 0" in the "Screen" section with "SIS USB-VGA".

7. Stop and start X again. Your XO should now be using your external display.

== Credits ==

There are a number of contributors; see http://lunge.queued.net/cgi-bin/gitweb.cgi?p=xodist;a=summary for the list of committers.  Thanks to all of them, as well as the people who've tested and provided feedback.

== See also ==
* [[Installing Debian as an upgrade]]

[[Category: Linux distributions]]