Installing CIAO 4.2 Using the ciao-install Script (Recommended)
CIAO 4.2 Science Threads
Last Update: 27 Sep 2010 - updated for CALDB 4.3.1: version number of CALDB main
The ciao-install script is intended to simplify and automate the installation and upgrade of the CIAO - Chandra Interactive Analysis of Observations - software package, and the Chandra Calibration DataBase (CALDB). It downloads the tarfiles, installs the software, and tests the installation for key functionality.
The ciao-install.README file describes the script in detail.
- Quick Start: Running ciao-install
- System Requirements
- Download the ciao-install script
- Where should CIAO and CALDB be installed?
- Installing the CIAO Software
- How to Install the CALDB in an Independent Directory
- Check the CALDB installation
- Clean Up
- Create a CIAO alias
Just looking for a reminder on how to run the ciao-install script? Here is it:
unix% bash /<path>/ciao-install
For a detailed description of running the script, read the rest of this thread.
CIAO is supported on a number of operating systems, which are listed on the Platform Support page. Certain system requirements are necessary to successfully install and run CIAO; review these system requirements before continuing with the installation.
The ciao-install script been greatly enhanced for CIAO 4.2. The script now:
- downloads the selected tarfiles for the specified platform
- unpacks and installs the CIAO software and CALDB
- runs the "smoke tests" to spot-check the installation for critical problems
Before continuing, download the ciao-install script.
The CIAO software package and the Chandra Calibration Database (CALDB) can be installed in any location and do not need to be installed with root or super-user privileges.
CIAO unpacks into a directory called ciao-<version>/, i.e. ciao-4.2 for this release. If the current version of CIAO were to be installed into /usr/local/, the full path to CIAO would be /usr/local/ciao-4.2/. This directory (/usr/local/ciao-4.2/) is referred to as the root directory of CIAO in the rest of this thread. It is also the value that the $ASCDS_INSTALL environment variable is set to once CIAO has been started.
In the rest of this thread we will assume CIAO is being installed into /soft/.
CALDB may be installed in two ways:
- within the CIAO installation, in the directory $ASCDS_INSTALL/CALDB
- in a separate directory, in which case $ASCDS_INSTALL/CALDB will be a soft link to the actual CALDB location.
This thread shows both installation methods.
It is is strongly suggested that CIAO be installed as a non-privileged user and not as the root user. If CIAO must be installed in a directory owned by root and you are following the manual process, then
- unpack CIAO as root (so creating the ciao-4.2/ directory);
- use the chown utility to change ownership of this directory to the installer's username.
When using the ciao-install tool to install in a root-owned directory, run the tool as a normal user and it will use sudo to create the directory (prompting you for the super user password), followed by running chown on the directory to return ownership to the installer.
In this example, the CALDB will be installed as a subdirectory of CIAO. If you want your CALDB to be in a different location, refer to "How to install the CALDB in an independent directory".
ciao-install may be run from any location. It prompts for required information. Here are the prompts and sample answers for a user named "ciaouser"; each prompt is explained in the following section:
unix% bash /<path>/ciao-install ciao-install v1.0 Requested packages: sherpa chips tools prism obsvis contrib CALDB_main Script log file is /home/ciaouser/ciao-install-09-12-188.8.131.52.log Download directory for tar files (/home/ciaouser): /soft/download CIAO installation directory (/usr): /soft Run smoke tests? (y|n) (y): Save these settings? (y|n) (y):
Note that tab completion may be used at these prompts.
After printing the script version number, ciao-install lists the packages that were requested for this installation:
sherpa chips tools prism obsvis contrib CALDB_main
This example is installing the standard installation: CIAO tools, ChIPS and Sherpa, the CALDB (except for ACIS blank-sky files and the PSF libraries), and the contributed science scripts.
The log file - ~/ciao-install-<pid>.log; - records the script status information; this is also printed to the screen. The log file can be used to help diagnose problems via the Helpdesk.
The download directory is a location to which the software and CALDB tarfiles are downloaded before the software is installed. For this installation the directory name is /soft/download/:
Download directory for tar files (/home/ciaouser): /soft/download
The next prompt is for the location of CIAO; we want CIAO to be installed into /soft/ciao-4.2 so we answer /soft rather than accept the default value:
CIAO installation directory (/usr): /soft
The next prompt asks you whether to run the CIAO smoke tests; these are some simple tests we provide to help validate the installation. Is is strongly suggested that you accept the default value of y here:
Run smoke tests? (y|n) (y):
The final prompt is to ask you whether the default answers for the prompts should be updated to use your current selection. If you answer "yes" (y), then the values will be written to the text file ~/.ciaoinstall.rc and will be used the next time the tool is run. In this case we accept the default value:
Save these settings? (y|n) (y):
At this point, the script begins to download the software tarfiles and install them (e.g. gunzip and untar them). The name, filesize, and download location of each file is printed to the screen:
Downloading file ciao-control (1 Kb) to /soft/download/ Downloading file ciao-4.2-bin-core-Linux64.tar.gz (255 Mb) to /soft/download/ Verifying file ciao-4.2-bin-core-Linux64.tar.gz Installing file /soft/download/ciao-4.2-bin-core-Linux64.tar.gz to /soft/ Downloading file ciao-4.2-bin-sherpa-Linux64.tar.gz (208 Mb) to /soft/download/ Verifying file ciao-4.2-bin-sherpa-Linux64.tar.gz Installing file /soft/download/ciao-4.2-bin-sherpa-Linux64.tar.gz to /soft/ Downloading file ciao-4.2-bin-chips-Linux64.tar.gz (67 Mb) to /soft/download/ Verifying file ciao-4.2-bin-chips-Linux64.tar.gz Installing file /soft/download/ciao-4.2-bin-chips-Linux64.tar.gz to /soft/ Downloading file ciao-4.2-bin-tools-Linux64.tar.gz (74 Mb) to /soft/download/ Verifying file ciao-4.2-bin-tools-Linux64.tar.gz Installing file /soft/download/ciao-4.2-bin-tools-Linux64.tar.gz to /soft/ Downloading file ciao-4.2-bin-prism-Linux64.tar.gz (946 Kb) to /soft/download/ Verifying file ciao-4.2-bin-prism-Linux64.tar.gz Installing file /soft/download/ciao-4.2-bin-prism-Linux64.tar.gz to /soft/ Downloading file ciao-4.2-bin-obsvis-Linux64.tar.gz (307 Kb) to /soft/download/ Verifying file ciao-4.2-bin-obsvis-Linux64.tar.gz Installing file /soft/download/ciao-4.2-bin-obsvis-Linux64.tar.gz to /soft/ Downloading file ciao-4.2-bin-graphics-Linux64.tar.gz (32 Mb) to /soft/download/ Verifying file ciao-4.2-bin-graphics-Linux64.tar.gz Installing file /soft/download/ciao-4.2-bin-graphics-Linux64.tar.gz to /soft/ Downloading file caldb_4.3.1_main.tar.gz (2 Gb) to /soft/download/ Verifying file caldb_4.3.1_main.tar.gz Installing file /soft/download/caldb_4.3.1_main.tar.gz to /soft/ciao-4.2/CALDB Downloading file ciao-4.2-contrib-14Dec2009.tar.gz (191 Kb) to /soft/download/ Verifying file ciao-4.2-contrib-14Dec2009.tar.gz Installing file /soft/download/ciao-4.2-contrib-14Dec2009.tar.gz to /soft/
If you get an error about being unable to download the CALDB files, please refer to the Downloading the CALDB: FTP passive mode note at the end of this thread.
After the files are downloaded and unpacked, the script configures CIAO and reindexes the CIAO help files ("ahelp"). The reindexing step takes a few minutes:
running chcon to allow CIAO to work with SELinux Running configure ./configure Re-indexing ahelp system (be patient!) Creating binary compiled python modules
The 'running chcon' line only appears on Linux installations. It indicates that the installation has been updated to run under Security-Enhanced Linux, if is installed on your system.
The script will then run the smoke tests. Since the smoke tests include tests of a number of the GUI applications in CIAO, windows will appear and disappear during these tests. This can make using your computer difficult, since these windows may take the mouse focus or overlap your working windows.
The screen output provides a count of how many tests have been run:
Running smoke tests Requested test suite includes 42 tests [1/42] Running test prism-smoke001 ... PASS [2/42] Running test prism-smoke002 ... PASS [3/42] Running test ahelp-smoke001 ... PASS [4/42] Running test obsvis-smoke004 ... PASS [5/42] Running test chips-smoke001 ... PASS [6/42] Running test chips-smoke002 ... PASS ...
This will continue until all the tests have finished, at which point you should see
[40/42] Running test tools-dmstat-smoke001 ... PASS [41/42] Running test tools-dmstat-smoke002 ... PASS [42/42] Running test tools-dmstat-smoke003 ... PASS All smoke tests completed: PASS ************************************************************* Smoke tests complete. All tests passed! Processing complete! Script Log file is /home/ciaouser/ciao-install-09-12-184.108.40.206.log
Verifying test successes
A successful test is logged with a "... PASS", while an unsuccessful test reports:
[7/42] Running test <testname> ... FAIL Review /tmp/smoke.username/<testname>/diff.log for details
The smoke tests print a summary of successful and failed tests. If all tests were successful:
All smoke tests completed: PASS ************************************************************* Smoke tests complete. All tests passed!
or if any failed:
1 out of 42 smoke tests FAILED. !! CIAO MAY HAVE FAILED TO INSTALL PROPERLY !! Please check http://cxc.harvard.edu/ciao4.2/bugs/smoke.html for a list of known issues before contacting the Help Desk.
Known Smoke Test Issues
You can now proceed to the checking the CALDB installation step.
Prior to CIAO 4.2, ciao-install had to be run twice to install the CALDB in a separate directory. The script now only has to be run once, with both the CIAO and CALDB installation directories specified.
The destination directory for the CALDB must exist before running ciao-install. In this example, we want to install the CALDB into /soft/CALDB. The directory is created, then --caldb switch is used to set this location in ciao-install.
unix% mkdir /soft/CALDB unix% bash /<path>/ciao-install --caldb /soft/CALDB ciao-install v1.0 Requested packages: sherpa chips tools prism obsvis contrib CALDB_main Script log file is /home/ciaouser/ciao-install-09-12-16.09.32.06.log Download directory for tar files (/home/ciaouser): /soft/download CIAO installation directory (/usr): /soft Run smoke tests? (y|n) (y): Save these settings? (y|n) (y):
ciao-install is run one time: it installs the CIAO software in /soft, installs the CALDB in /soft/CALDB, and links CIAO to the CALDB directory. It then runs the smoke tests, as described in detail in the "Installing the Software: CALDB within CIAO" section.
The scripts package contains the check_ciao_caldb tool which performs a simple test of the Chandra CALDB installation.
After starting CIAO, running the tool should produce screen output like the following:
unix% ls -1 /soft/ciao-4.2/CALDB/ data/ docs/ software/ unix% check_ciao_caldb CALDB environment variable = /soft/ciao-4.2/CALDB CALDB version = 4.2.2 release date = 2010-04-19T19:00:00 UTC CALDB query completed successfully.
If CALDB is installed in a different location, the check_ciao_caldb output will include the line:
CALDB environment variable = /soft/ciao-4.2/CALDB which is a link to = /soft/CALDB/
For a more-thorough validation please follow the chkcif steps described on the download CALDB page.
Finally, you may delete the tarfiles from the original download directory. For this example we would say:
unix% cd /soft/download unix% rm ciao-4.2*gz unix% rm caldb_4.2_main.tar.gz unix% rm ciao-install
You may also delete the log file(s) - e.g. ~/ciao-install-<pid>.log - once you have reviewed them for errors.
It is strongly suggested that you create an alias to make it easy to set up and use CIAO.
The alias syntax depends on the shell (tcsh, csh, bash); see this FAQ for help in determining which shell you are using.
csh/tcsh users should add the following
to their $HOME/.cshrc file.
alias ciao "source /soft/ciao-4.2/bin/ciao.csh"
bash users should add the following
to their $HOME/.bashrc file.
alias ciao=". /soft/ciao-4.2/bin/ciao.bash"
ksh users should add the following
to their $HOME/.login file.
alias ciao=". /soft/ciao-4.2/bin/ciao.ksh"
Once the alias is defined, you will be able to simply type
and CIAO will be setup and ready to use in that window.
Some users are unable to download the CALDB via ciao-install. A message of this form is printed:
ERROR: Unable to retrieve ftp://cda.harvard.edu/pub/arcftp/caldb_4/caldb_4.3.1_main.tar.gz ERROR: Unable to download caldb_4.3.1_main.tar.gz ERROR: Bad Download. Please try again. If the problem continues Please contact the CfA helpdesk.
This is because the user's FTP has defaulted to extended passive mode for the file transfer. Extended passive mode is not supported for the Archive web server, which hosts the CALDB tarfiles.
The workaround is for users to create a $HOME/.netrc file containing the following:
default macdef init epsv4 off
Note that there is a blank line after the "epsv4 off" entry.
The re-run ciao-install to download the missing files.
Snow Leopard is not an officially supported platform for CIAO 4.2, but a user-submitted workaround allows CIAO to run. This is an issue with the 32-bit CIAO build; users installing the 64-bit build should not have a library version conflict.
The help file indexing and smoke tests steps of ciao-install will fail until the workaround is done. In this case:
- run ciao-install, answering "n" at the "Run smoke tests?" prompt
- complete the Snow Leopard workaround
- run ciao-install a second time, answering "y" at the "Run smoke tests?" prompt
In the first run of the script, the software will be unpacked and configured, but the ahelp indexing step will fail. Running ciao-install again after the workaround will index the help files and run the smoke tests.
If a file named "@LongLink" is created when the tarfiles are unpacked on Solaris, it is an indication that tar was used instead of GNU tar ("gtar").
As noted in the System Requirements section, Solaris users must use gtar to unpack the files. If native Solaris tar is used, some of the test filenames will be truncated.
There are some known conflicts between CIAO and other software or system libraries and tools. They are documented in the following webpages:
All non-OTS source code will be freely available in support of any CIAO release. The software is subject to Smithsonian Institution Copyright, a statement of which can be found in the headers of the source files, as well as at $ASCDS_INSTALL/LICENSE.SAO.
CIAO 4.2 is further governed by the GNU General Public License ($ASCDS_INSTALL/COPYING) and/or the GNU Library General Public License ($ASCDS_INSTALL/COPYING.LIB), both of which are bundled with the software.
The CIAO installation is now complete. For help getting started with the software, read the Introductory science threads.
|20 Apr 2009||The CIAO 4.1.2 release coincides with the beta release of the ciao-install script.|
|16 Jun 2009||clarified why ciao-install must be run twice to install CALDB in a separate location|
|15 Dec 2009||updated for the CIAO 4.2 release: ciao-install is the recommended method for installing CIAO. Many enhancements have been made to the script: it now downloads and unpacks the tarfiles, installs the software, and runs the smoke tests.|
|29 Dec 2009||Added Installing on Snow Leopard note|
|16 Mar 2010||Added Downloading the CALDB: FTP passive mode note|
|05 Apr 2010||updated for CALDB 4.2.1: version number of CALDB main tarfile|
|19 Apr 2010||updated for CALDB 4.2.2: version number of CALDB main tarfile|
|27 Sep 2010||updated for CALDB 4.3.1: version number of CALDB main|