Debian GNU/Linux for ADS Embedded Computer Systems


The ADS Debian distribution is a set of root filesystems that
allow you to run a full-featured Debian GNU/Linux operating system
on PXA and other ARM-based embedded computer systems from Applied 
Data Systems. Using the ADS Debian distribution, you can write, 
compile and debug your applications directly on your target 
platform (the ADS embedded computer) without having to use 
complicated cross-compilers and cross-debuggers.

This document contains information about setting up your Debian
system for network access and program development, as well as notes
about the smaller flash/ramdisk versions of the ADS Debian
distribution. Please read this document completely to familiarize
yourself with the Debian environment on ADS embedded computer
systems.


Debian comes in three versions: 'stable', 'testing', and 'unstable'.
'testing' is the version provided in this distribution. Debian
'testing' is reliable, but it changes on a daily basis. This tar file
contains a snapshot of 'testing' as of 2006-01-27.

The root password for the ADS Debian distributions is 'rootme'. You
should begin by logging is as 'root' on the serial port (debug port).
Normally, the serial (debug) port on ADS boards is also the system console.
You can change this by changing the value of 'console=' on the kernel
command line (cmdline.txt). See the appropriate bootloader manual for
your ADS board for more details.

Beginning with the 04/26/2005 release, there is an additional
command line option, 'SERIALGETTY=', which controls which serial port
is used for logins. This can be different from the 'console='
parameter, which controls which terminal recieves the kernel messages.
By default, a serial terminal is only present on ttyS0.

There is also an optional command line option, 'SERIALBAUD=',
which controls the speed of the serial port used for logins.


## Configuring the network interface

By default, the ADS Debian distribution will attempt to auto-
configure the network interfaces using DHCP. If you do not have a DHCP
server on your network or you do not wish to use DHCP, you can configure
a static IP address by editing the file /etc/network/interfaces and
changing the line

iface eth0 inet dhcp

to read 

iface eth0 inet static
        address <IP address>
        netmask <netmask>
        broadcast <broadcast>
        gateway <gateway>
        
Where the addresses are in dotted-quad notation
(aaa.bbb.ccc.ddd)

You should also change /etc/resolv.conf to list the proper
nameservers for you network.



## Using your system for native development

The ADS Debian distribution comes with native compilers, editors
and debuggers so you can begin developing your application directly
on your embedded computer system. In most cases, you could even
attach a keyboard and begin working without needing any other systems.
However, most people find the VGA screen on the development kit too
small for serious program development.

You can use 'SSH' from a linux workstation to access your embedded
system over the network. SSH X-forwarding is enabled by default -
allowing X clients running on the embedded board to display on your
workstation screen. Once you log in to your board via SSH, you should
have a DISPLAY environment variable set by SSH - DO NOT CHANGE IT or X
forwarding will stop working.

Starting an X program (xterm, etc.) from your SSH session should
automatically display the program on your Linux workstation.

The SSH daemon is not started automatically. See the notes below on SSH for
more details.

The ADS Debian distribution comes with many common development 
libraries, including C, C++, x11 and gtk. See the section on
'Installing additional Debian Packages' for information on installing
any development libraries you may need that are not included by default.

NOTE:  Compiling a kernel or kernel modules natively on the system is
not recommended. You should use the proper cross-compiler as listed in
the 'Getting Started' section of the ADS Linux support pages:

http://www.applieddata.net/forums/topic.asp?TOPIC_ID=294



## Installing additional Debian packages

Debian's 'apt-get' command allows you to easily install any of
thousands of pre-compiled packages available for ARM. Before using
apt, however, you must "update" it to ensure that it has access to the
most recent list of packages.

By default, apt-get is configured to use the master Debian package
repository for most packages, and suppliment this with 
a few ADS-specific packages from an ADS Debian package repository.
While you can reconfigure apt to use a Debian mirror closer to you
for better download speeds, we recommend that you leave the configuration
for the ADS repository as-is so you can access sources and updates for
ADS-specific packages.

A list of Debian's mirrors can be found at this web URL:
http://www.debian.org/mirror/list

After configuring apt, you should run

  apt-get update
  
to pull the latest package lists from your chosen mirror.

After updating, you can install a package with the command

  apt-get install <package name>
  
You can look at a list of thousands of Debian packages available for
installation by visiting Debian's package site at:

http://packages.debian.org/

When searching or browsing the package list, you should select the
'testing' distribution. ('etch' is the code-name for the current
'testing' branch of Debian)

If you are going to downloading the same files from the debian site
many times, you might consider setting up a proxy server like Squid on
your server or workstation. Once you have squid working (you can test
it with your browser), add a line like the following to the file
/etc/apt/apt.conf for your server:

Acquire::http::Proxy "http://192.168.1.1:3128";



## Using SSH/SCP/SFTP

The Debian root filesystems now support SSH (and the companion SCP
and SFTP protocols) for enhanced security for remote access. The
SSH system has replaced telnet and ftp functionality with the more
secure ssh and scp commands. Use 'man ssh' for more information. By
default, the SSH server is not started but does allow root access.
(This is a change from previous behaviour.)  To start the SSH server,
run '/etc/init.d/ssh start' from the command line. To make the
system start SSH automatically at boot-time, create a symbolic link
from /etc/rc3.d/S20ssh to /etc/init.d/ssh. This will start the SSH
server automatically at runlevel 3 (runlevel 3 is the default).

* Security notes:

The SSH daemon has been designed with security in mind, but no
software can ever be 'bug-proof'. If you do not require network
remote access, disable SSH by removing the ssh start files from
the /etc/rc*.d directories and removing the /etc/init.d/ssh script.

Before you start the SSH server, please be sure you have at least
changed the root password!

As in all cases, you should seek the advice of an experienced 
systems administrator or security professional before deploying a 
networked system.



## Using FTP

FTP is not enabled by default. To enable the FTP daemon (server), 
edit /etc/inetd.conf and uncomment the line for the FTP service.

* Security notes:

FTP is not a secure protocol!  The authentication information 
(usernames, passwords) is sent over the wire in clear text!  
Wherever possible, users are encouraged to switch to SSH/SCP/SFTP.

When enabled, the FTP daemon allows anonymous upload to 
/usr/ftp/incoming. While the '731' permissions on this directory
prevent an anonymous user from listing any files uploaded there, a
user who knows the name of an uploaded file can retrieve it. This
could allow malicious users to abuse the FTP service (by turning it
into an illegal file drop or 'warez server') on a system that has
the FTP daemon enabled.

If you need to enable non-anonymous FTP, you will need to edit
the file /etc/pam.d/ftp (see the comments in that file). FTP
access for the root user will still not be allowed; you should
create a non-privileged user for FTP access.



## Notes specific to the Full (Microdrive) distribution

The microdrive is much like the disk drive on your workstation.
You are probably careful to shutdown you workstation before powering
it off. You should be equally careful with debian on the microdrive
- run the shutdown command and wait for it to complete before removing
the power from your board.

Also, the Microdrive is a very fragile piece of equipment. It is
especially sensitive to pressure on the top and bottom (large flat
areas) of the drive. When handling a Microdrive, always hold it by
its edges!  To remove a Microdrive from a PCMCIA slot adapter, use your
thumbnails to push it out of the adapter from the front (where the pins
connect to the drive) rather than pulling the drive out from the back.



## Notes specific to the Ramdisk distribution

The ramdisk distribution of Debian for ADS embedded systems is
a minimal subset of the Debian distribution capable of fitting
into 5 megs of flash and roughly 12 megs of RAM (once uncompressed).

The ADS Debian ramdisk uses Microwindows/Nano-X as its GUI 
environment. The GUI is based on the 0.9 version of Microwindows.
The source code the the GUI and all included Microwindows programs
is included in the ADS Debian apt repository in the form of Debian source
packages.



## Notes specific to the JFFS2 distribution

The JFFS2 distribution of Debian for ADS embedded systems is a
subset of the Debian distribution capable of fitting into on-
board flash, leaving over 14 megs of available space in the JFFS2
partition.

The ADS Debian JFFS2 root uses x11 (XFree86) as its GUI and
includes several demo programs that run under x11. The media files
for several of these demos are stored in the /root/demo_media
directory. Many common x11 shared libraries are included in the
JFFS2 root, including those necessary to run gtk programs.

The JFFS2 filesystem is a persistent flash filesystem that keeps
changes across reboots - it is not always the same on each boot
(like the ramdisk). Although it is designed to be resilient in
the case of power loss and unclean shutdown/dismount, you should
shut down your JFFS2 system properly (using the 'shutdown' command)
to cleanly unmount the root filesystem.

A tar file containing the contents of the JFFS2 image is available
for download along with the image (see the 'Root File Systems'
topic on the ADS Linux support pages). To generate a modified
JFFS2 image for your system, download and extract this tar file
(as root):

  tar jxpf debian-jffs2.tar.bz2
  
To create a new JFFS2 image, you will need the mkfs.jffs2
program. Under Debian, you can install mkfs.jffs2 by running
'apt-get install mtd-tools'. Users of other distributions can
download the source for mkfs.jffs2 from
http://www.linux-mtd.infradead.org/source.html

To create a JFFS2 image, run

  mkfs.jffs2 -e 0x40000 -p -d flashwork -o flashfs1



## Notes specific to the CRAMFS distribution

The CRAMFS distribution of Debian for ADS embedded systems is a
subset of the Debian distribution similar to the JFFS2
distribution but packaged as a read-only CRAMFS image with an
accompanying JFFS2 image for persistent storage. The read-only
portion of the CRAMFS distribution fits into roughly 14 megs of
on-board flash. The remaining space in flash is used for
persistent storage.

Unlike the ramdisk and JFFS2 distributions, the CRAMFS is read-
only with the exception of /var, /tmp and /etc which are loaded
into RAMFS temporary filesystems. Attempts to change any other
part of the filesystem will fail.

The CRAMFS distribution included a shell script called 'altshadow',
which can be used to quickly "shadow" a file in /etc or /var with
a file in the JFFS2 persistent storage. This JFFS2 partition is
mounted as /alt on the system. To "shadow" a file in /etc, run

  altshadow /alt /etc/<filename>
  
This will copy the current /etc/<filename> to the JFFS2 partition
and replace /etc/<filename> with a symlink to the "shadowed" 
version. This file will now retain changes across reboots. For
example, to change the nameserver information in /etc/resolv.conf,
run

  altshadow /alt /etc/resolv.conf
  
You may now edit /etc/resolv.conf and the changes will remain when
the system is rebooted.

Note:  Since the CRAMFS distribution also includes a JFFS2
partition, you should try to shut it down cleanly before removing
power from the board. The advantage to the CRAMFS distribution is
that, in the event that the JFFS2 filesystem does get corrupted or
otherwise become unmountable, the rest of the system will still be
intact because it is read-only. Only the "shadowed" files will
be reverted to their previous/default contents.

SECURITY NOTE:  Since the default root password is stored in the
read-only CRAMFS filesystem, shadowing the file /etc/shadow in
order to change the root password across reboots is not safe.
If an attacker can cause your system to boot without mounting the
JFFS2 partition (by modifying the kernel command line or
corrupting the JFFS2 filesystem), THE DEFAULT ROOT PASSWORD WILL
BE RESTORED! To truly change the root password, you must generate
a new CRAMFS image with the new password encrypted into 
/etc/shadow.

A tar file containing the contents of the CRAMFS image is available
for download along with the CRAMFS image (see the 'Root File
Systems' topic on the ADS Linux support pages). To generate a
modified CRAMFS image for your system, download and extract this
tar file (as root)

  tar jxpf debian-cramfs.tar.bz2

This will create two directories containing the files from the CRAMFS
image and the JFFS2 image. You can modify the files in this
directory and then create a new CRAMFS image using the 'mkcramfs'
utility. Under Debian, you can install mkcramfs by running 'apt-get
install mkcramfs'. Users of other distributions can download the
source for mkcramfs from  http://sourceforge.net/projects/cramfs/

To create a CRAMFS image from a directory, run

  mkcramfs cramwork cramfs.img


To create a JFFS2 image (for the /alt partition), run

  mke2fs -e 0x40000 -p -d cramalt -o flashfs2