LiveCPD
Contents
Overview
CPD Basic Usage
Editing Configuration Files
Updating the System
Setting up a USB Override Device
Using the Hard Disk as an Override Device
Changing the Data Storage Device
Running CPD Using Changes
General Notes
Readme File
UNIX Basics
Text Editing
Troubleshooting
If the Graphical Interface Fails to Start
Advanced
Overview:
LiveCPD is a self-contained version of the NOAA CMDL Aerosol Group's CPD
software. This software is used to automate the operation of CMDL's surface
in situ aerosol sampling systems and is typically run from a computer hard
disk. LiveCPD can be run from an internal or external drive such as a
CD-ROM, instead of the hard drive, providing for a completely portable and
very robust system operation in the case of short-term sampling (i.e., field
intensives and aircraft sampling) or hard drive failure. LiveCPD can be
obtained on a CD or ftp'ed to any location from
ftp://ftp.cmdl.noaa.gov/aerosol/etc/cpd/cpdlive.iso and copied to CD.
Below are instructions for the installation and configuration of LiveCPD.
Because LiveCPD boots from a CD-ROM, no computer-specific configuration
information can be stored in the normal manner. Since the LiveCPD CD is not
a writable device, all custom configuration information is handled with a
separate writable device (e.g., RAM or USB pen drive), overriding default
configuration files from the CD during system boot up. If a file exists on
both the override and boot devices, then whichever file was modified more
recently is used. See below for more information on how to use this override
system. If no override device is found, then all configuration defaults as
they are programmed on the LiveCPD CD are used.
Installation can be as simple as booting the computer with the CD if you
choose to operate the system using all the defaults programmed on the CD.
In this case, data will be written to RAM in a directory called:
/aer/nil/log
Configuration instructions allow for data collection on an external drive
such as a USB pen drive. In this case, configuration files will be stored
on the USB drive in a directory called
/mnt/override
and data will be stored on the USB drive in
/aer/nil/log.
In either case, to change the location of data files, (e.g., specify a
station name in the above path) the configuration files ("cpd.ini") must be
edited. You may also need to edit "cpd.ini" to initialize the instruments to
the correct ports.
CPD Basic Usage:
All of the icons on the bar (panel) on the bottom of the screen can be single
clicked to perform their associated action. The 2x2 grid near the center of
the bar is the desktop pager. Clicking on one of the squares changes the
current workspace to that instance of the desktop. Applications launched on
one desktop are only visible from their parent desktop. A list of the other
icons on the panel follows:
Start CPD Runs "cpd.start" in a new terminal window. This will
both start CPD (if needed) and bring up a display
client for it.
Stop CPD Runs "cpd.kill" after a confirmation dialog box.
Stops any instance of CPD that is currently running.
CPX Starts CPX, the graphical display client for CPD.
Send Data Runs "cpd.archive send=1". This archives current data
and sends all archived data (including the most recent
data) back to CMDL for processing.
Edit cpd.ini Pops up an NEdit text editor session for "cpd.ini".
Mozilla Start the Mozilla web-browser and email client.
NEdit Starts the NEdit text editor.
Terminal Creates a new terminal.
Shutdown Shuts down the computer after a confirmation dialog box.
On the Desktop you will see the following icons:
Home Brings up a file browser in the current user's home
directory.
CPD Data Brings up a file browser in the CPD Data directory.
USB Drive Brings up a file browser on any removable USB device
connected to the computer. This excludes the device
(if any) that was used to load configuration
information, or that is being used as a data storage
device. Clicking on this without a qualified device
connected will result in an error message.
INI Documen... Brings up a reference guide to "cpd.ini".
Readme Brings up this documentation file.
Initialize USB..Initialize the currently connected USB drive (but not
the one in use), for data and configuration storage.
Unplug Config...Allows you to remove the current device in use for
data and configuration storage.
Swap Config... Allows you to duplicate and swap the current storage
device for a new one.
Plug in Config..Sets up a previously initialized USB device as the
current data and configuration storage device.
The file browser works as you might expect. Files can be dragged and dropped
from one place to another. After dropping a file, a context menu will be
displayed with a choice of actions that can be taken. Double clicking on a
file performs the associated action for that file type (e.g. open a text
editor). To change this action, right click on the file and select:
File 'FILENAME' -> Set Run Action
Similarly, to edit any file with vi:
File 'FILENAME' -> Open as text
You may also drag and drop a file (or multiple files, if selected), on to
NEdit to open them with this editor. This also works for Mozilla, but the
Mozilla application can only handle single file selections.
Editing Configuration Files:
Because of the unique way configuration files are handled in LiveCPD,
editing these files requires the use of special programs for the changes to
be made persistent. Upon bootup, the system has already set "cpd.ini" and
"CPX" up to be editable without the need of any special programs. They can
be edited as normal. To edit any other file, you must either first invoke
the command:
"make_editable FILENAME [FILENAME2...]"
on the file or use the
"edt" script
and then pop up an editor. When using "edt" you will be asked for your
preference in using either the vim or NEdit text editors. Changes to the
files take effect immediately though the programs they affect, if any, may
need to be restarted so that the file can be re-read by the system.
Some files exist only on the CD and can not be changed or edited (see the
attached directory structure map). In order to edit files, they must be
placed on a writable medium such as the USB drive or in RAM. A simple way
to accomplish this is to set up a "symlink" which points the files on the
CD to the writable device.
NOTE: Files in /usr, /bin, /sbin, /lib, and /boot cannot be edited.
To set up a symlink (for instance in the rcX.d directories), first create
the directory in
/mnt/override/
then create a symlink from there, as if it were /.
For example, to enable samba:
mkdir -p /mnt/override/etc/rc5.d
cd /mnt/override/etc/rc5.d
ln -s ../init.d/samba S20samba
Or for "cpd.ini" (this is set by default to point to cpd.ini.nil):
mkdir -p /mnt/override/aer/prg/cpd/etc
cd /mnt/override/aer/prg/cpd/etc
ln -fs cpd.ini.STN cpd.ini
Similarly, configuration files can be directly copied and/or edited on
/mnt/override. Changes of this sort require a reboot to take effect.
NOTE: To make changes to the desktop environment persistent, first make changes as needed, then do:
make_editable ~/.rox_choices/ROX-Filer/*
Configuring the network:
To change the network configuration, use:
sudo configure_networking
This updates network settings, making the changes persistent, and restarts
the network with the updated settings.
Updating the system:
When? For What?
The simplest way to update the version system on the CD is to use the
included (modified) rsync.aerprg script, run as aerosol. It will update all
of the /aer tree (including cpd). It will also synchronize $CPD/etc with
CVS, including (optionally) merging changes to "cpd.ini" back into the main
repository. (If you don't do this, the local version will be overwritten).
This script automatically places any updated files on the override device,
so that the update persists between reboots.
Setting Up a USB Override Device:
A typical override device is a USB "pen drive", though any external USB
storage works the same. If such a device is connected to the system during
boot up and has not been initialized for configuration storage, the system
will prompt you about initializing it. If you accept, the device will be
automatically initialized as if you had invoked the command below.
Afterwords, the system will continue to boot using it. If you use this
option you can disregard the notes below about rebooting after initializing
the override device, but not the ones about rebooting for configuration
changes after the initial setup. In most cases you should answer no to
the question about restoring an override device backup.
To manually initialize a USB drive connected to the system, either click on
the desktop icon, or use the command:
"sudo setup_override_part /dev/usbrootdev"
in a terminal window. You will be asked several questions regarding the
initialization of the device. If you choose to initialize the device
without repartitioning it (i.e. preserving the existing contents). A file
called override_fs.img will be created in the root directory of it. This
file contains all configuration information, so do not delete or move it.
Choosing this option reduces the expected lifetime of the device the most.
NOTE: You will only be given this option if the device has only a single
windows partition on it when it is initialized. This is the case for nearly
all USB drives as they come from the manufacturer (but not the if you have
initialized it with this command to another state).
If you choose to destructively partition the device:
If you want to be able to access stored data from a windows machine without
having to copy it to another device, you should answer yes to the question
regarding windows readability. Otherwise you should answer no, as using the
windows file system reduces the long-term integrity of the device. In most
cases 16384 kbytes should be enough for all configuration files. If more
files are anticipated, increase as needed.
Setting up an override device for your configuration files causes several
directories to be created on the USB device, on the override partition:
aer All the directories in the aer tree, without any files
home/cpd Default user's home directories
home/aerosol
home/local/pub Default public directory
override_marker A file used internally to mark this device, DO NOT DELETE
The directory "/aer/stn/log" will be created on the storage device, where
"stn" is the three digit station code (in lower-case), and log files will be
placed there
Using the Hard Disk as an Override Device
You can also initialize a hard-disk to store configuration information, but
this requires root access. To setup an entire hard disk type:
"setup_override_part /dev/hdX" (where X is a,b,c...)
WARNING: Initializing a device erases ALL data and configuration stored on the device, even if it was previously initialized.
To mark an existing partition on a hard disk to be used as an override
partition:
mkdir -p /tmp/hdmnt
mount /dev/hdaX /tmp/hdmnt (where X is 1,2,3...15)
touch /tmp/hdmnt/
This will initialize a portion of the hard-disk to be used as the override
device but will not erase any existing files on the disk.
You must now reboot and the system will use the newly initialized device as
the override device. Once the reboot is finished, the above section on
editing configuration files has directions to make changes persistent.
After an override device is initialized, a default "cpd.ini" file is set up.
This ".ini" file contains a definition for all instruments supported by CPD.
The default version of "cpd.ini" that comes on LiveCPD has only a Neph, CNC,
and PSAP enabled. These instruments are configured for USB serial ports
1, 2, and 3 respectively. A copy of this full ".ini" file is also available
in
$CPD/etc/cpd.ini.example.
NOTE: If two viable override devices are plugged into the system, the device
that is used to boot the system is arbitrary. But once the system has booted
from one device, that device is excluded from being re-initialized and the
above still holds.
If you wish to initialize a new override device as the one the system was
booted from you must do the following, as root:
setup_override_part /dev/usbrootdev -c
Changing the Data Storage Device:
By default, data will be stored on the same device as the configuration files
are, though on a different partition. This will be the RAM disk is you have
not created an override device, or the external USB drive if you have
configured one to be the override device.
To have data saved to a device other than the one the configuration files,
create the file:
"/mnt/override/etc/dev.storage"
Its contents should be the device to which data files are to be written,
e.g. to log data to /dev/hda7, do, as root:
mkdir -p /mnt/override/etc
echo -n "/dev/hda7" > /mnt/override/etc/dev.storage
Similarly contains the file system type (if not ext2/3, what Linux uses):
"/mnt/override/etc/storage.fs"
ls -l
To change write permissions type:
chmod gu+rwX
Running CPD Using Changes:
Once all of the desired steps are completed, a final reboot is required for
the system to properly use all the updated settings. This is only required
if you have changed core system settings (i.e. it is not needed if you all
that you have changed is the CPD configuration, in this case just stop and
restart CPD).
General Notes:
Readme File
This readme file can be accessed at any time, even if the graphical interface
is not running, by pressing CTRL-ALT-F12. To return to the graphical
interface from the readme file press ALT-F7. Similarly, a root shell (full
access) that can be accessed by pressing CTRL-ALT-F11; again, ALT-F7 returns
from the root shell to the graphical interface. Pressing CTRL-ALT-BACKSPACE
followed by CTRL-ALT-DELETE will reboot the system.
UNIX Basics
To control and make changes to the system you will be working in a UNIX
terminal window on the Linux desktop. Clicking the "Terminal" icon on the
bar at the bottom of the graphical interface will open a window to work in.
When you first open a window your location will be /aer. You can perform
most of the required tasks for configuration of the system from this
location. See the attached directory structure map for locations of all
CPD related files.
Text Editing
While custom configuring the system, you may need to edit configuration text
files. The command "edt" will invoke the VI text editor if used from the
command line. If you have never used VI before, the F1 key will launch an
on-line help window. A quick guide for VI usage is as follows:
Press "i" to enter insert mode in order to type text (in this mode, VI
acts like most other editors).
Press ":w" to save changes (you'll have to re-enter insert mode to
add text again).
Press ":q" to quit out of the VI editor and regain your command line
prompt.
Troubleshooting
If the graphical interface fails to start:
If you are looking at the graphical interface desktop now, skip this section
and continue with "General Notes." The graphical interface is a Linux desktop
with a large NOAA icon in the center, a task bar at the bottom, and several
icons on the desktop.
On most systems the default drivers programmed into LiveCD will work and the
graphical desktop will appear. If it fails to do so some manual
configuration will be needed. This requires that the root shell be accessed
by pressing CTRL-ALT-F11.
One reason the graphical interface may fail to launch is an issue that has
been encountered on some Intel 810 based motherboards. This problem can be
solved as follows:
edt /etc/X11/XF86Config-4
Find the line that says:
Driver "vesa"
And change it to:
Driver "i810"
Exit VI.
make_editable /etc/load_modules
echo "agpgart" >> /etc/load_modules
echo "intel_agp" >> /etc/load_modules
After a change is made, you can see if it worked by doing:
/etc/init.d/xdm restart
The interface should now start. If it does not, you can try to input specific
timings for your monitor:
edt /etc/X11/XF86Config-4
Find the line:
HorizSync "XX-YY"
And replace XX-YY with your monitor's horizontal sync range, in kHz
Find the line:
VertRefresh "XX-YY"
And replace XX-YY with your monitor's vertical refresh rate range, in Hz.
If all else fails, you can try running through the X11 configurator by doing:
make_editable /etc/X11/XF86Config-4
xf86config
If this is the first boot-up of the system, any of these changes you have just
made will not be made persistent. That is, they will not exist once the
machine is restarted. To make the changes persistent, you will need to repeat
them once you follow the "Override Device Setup" directions above.
Advanced
All of the below assumes root access and significant Linux knowledge.
To repartition a USB device back to a single windows partition:
fdisk /dev/sda
Type:
o New partition table
n New partition
p Primary
1 First partition
Start of drive
End of drive
t Set type
b Fat32
w Write and quit
mkfs -t vfat /dev/sda
Most dialog based programs store their log files in
/var/log/.log
If one isn't working, check that file.
To copy from the existing override device to a new one:
setup_override_part /dev/newdev -c
Help:
setup_override_part none -h
Backing up the override device:
backup_override
Use the -h switch for more info
Restoring a backup to an already mounted device:
restore_override
Again, use the -h switch
Plugging in an override device:
plugin_override
Use the -h switch for more info
Unplugging in an override device:
unplug_override
Use the -h switch for more info
Swapping the override device:
swap_override
To make changes to a crontab persistant:
Edit the crontab normally (i.e. with 'crontab somfile')
As root:
make_editable /var/spool/cron/crontabs/
Where is the user who's crontab you just changed.
This needs to be re-run after every CHANGE to the crontab.
After each replacement of the crontab, the system has to be restarted
before cron will execute correctly again.
It is possible to place the override loopback file on any device that is
scanned during the InitRD stage. If you already have such an image
just place it in the root directory of the target filesystem. To create
one:
cd /new/override/mount
dd if=/dev/zero of=/new/override/mount/override_fs.img bs=1k count=SIZE
losetup /dev/loop3 /new/override/mount/override_fs.img
mke2fs -b 1024 -m 0 /dev/loop3
tune2fs -i 0 -c 0 /dev/loop3
mkdir /tmp/overridetmp
mount /dev/loop3 /tmp/overridetmp
touch /tmp/overridetmp/override_marker
Then configure it as above (creating the directory
structures, etc)
umount /tmp/overridetmp
losetup -d /dev/loop3
umount /new/override/mount
Similarly to mount an existing loopback file, do:
losetup /dev/loop3 /path/to/file/override_fs.img
mount /dev/loop3 /path/to/tmp/mount
...
umount /path/to/tmp/mount
losetup -d /dev/loop3
NOTE: /dev/loop[0-2] are used by the system, don't try to setup them manually
If the automatic override setup critically fails, before the system resumes
bootup, the restore_override, setup_override_part, and auto_override_setup
logs are on VTs 12, 11, and 10 respectively.
To force module loading, add the modules (and possibly arguments) to
/etc/load_modules
To force a scan of a USB device:
rescan_usbplug [dev1] [dev2] ...
If the unplug_override script is failing (possibly as a part of
swap_override), while waiting for files to close, make sure that you don't
have any shells with current directory in /mnt/override/*, nor any programs
running with that working directory. Also make sure that there aren't any
programs trying to use files there. To get a list of open files:
lsof | grep "/mnt/override"
And possibly kill anything with one open.