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.