Skip to the navigation links
Last modified: 27 Sept 2010
Where are the PDFs?

Manually Installing CIAO 4.2

CIAO 4.2 Science Threads


Last Update: 27 Sep 2010 - updated for CALDB 4.3.1: version number of CALDB main


How to manually install version 4.2 of CIAO, the Chandra Interactive Analysis of Observations software package. This information is also available in the INSTALL_BINARY file that is packaged with CIAO.

[New] The ciao-install script automates the installation and upgrade of CIAO and CALDB. Use of this script, which is a the recommended method for installing the software, is described in the ciao-install thread.

This thread does not explain how to re-compile CIAO yourself. Refer to the INSTALL_SOURCE file for information on that process.

Related Links:


System Requirements

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.

Downloading the Software

For a standard CIAO installation, you need the following packages:

  • Binaries: ciao-4.2-bin-<component>-<OS>.tar.gz

    Contains the CIAO tools, libraries, parameter files, and help files. Also contains the pre-compiled off-the-shelf (OTS) programs required to run CIAO.

    The relationship between <OS> and the supported operating systems is given in the following table:

    <OS> Operating system
    Linux 32-bit Linux
    Linux64 64-bit Linux (beta)
    osxi 32-bit OS-X with an Intel processor
    osx64 64-bit OS-X with an Intel processor (beta)
    osxppc OS-X with a PPC processor
    sun10 Solaris 10
  • Chandra Calibration Database (CALDB) v4.3.1

    Some calibration products are packaged separately, due to the larger filesize and specific analysis uses for them. Users may opt to include the ACIS background files, HRC background files, and/or PSF library files when installing the CALDB. This thread includes only the ACIS background tarfile.

  • Contributed science scripts and modules ciao-4.2-contrib-<date>.tar.gz

The files are retrieved with wget. In this example, the 32-bit Linux files (<OS>="Linux") are retrieved; change the <OS> value to match your operating system. Save the tarfiles to a location - /soft/download/ in this example - that is accessible from where you wish to install CIAO.

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.

unix% wget -nH -nd -r -P/soft/download/

unix% wget -P/soft/download/

unix% wget -P/soft/download/
unix% wget -P/soft/download/

The following files were used to install CIAO on a 32-bit Linux (CentOS) machine:

unix% ls -1 /soft/download/

[New] The ciao-install script automates the installation and upgrade of CIAO and CALDB. Use of this script, which is a the recommended method for installing the software, is described in the ciao-install thread.

Where should CIAO and CALDB be installed?

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 assumes that you have installed the CALDB before starting the CIAO installation, as CIAO has to be linked to the location of those files. Installation instructions are available on the CALDB website:

Installing CIAO as the root user

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

  1. unpack CIAO as root (so creating the ciao-4.2/ directory);
  2. use the chown utility to change ownership of this directory to the installer's username.

Installing the CIAO Software

1. Change to the CIAO installation directory

The CIAO 4.2 tarfiles create a directory named ciao-4.2 for the software installation. It is not necessary to create the CIAO directory before starting the installation.

Move to the directory in which you would like the root of the CIAO installation to be located. If you are installing the software for a local network, this directory must also be visible to all potential CIAO users.

This installation will be done in the /soft directory:

unix% cd /soft/

2. Unpack CIAO 4.2

From the CIAO location just chosen, untar the CIAO 4.2 binary packages. (If you prefer more screen output, add the "v" option to the gtar command.)

Solaris users must use GNU tar, as shown in this example (see the system requirements page). Users on other platforms who don't have gtar installed can use tar with the same "xzf" options.

unix% pwd

unix% gtar xzf /soft/download/ciao-4.2-bin-chips-Linux.tar.gz

unix% gtar xzf /soft/download/ciao-4.2-bin-core-Linux.tar.gz

unix% gtar xzf /soft/download/ciao-4.2-bin-graphics-Linux.tar.gz

unix% gtar xzf /soft/download/ciao-4.2-bin-obsvis-Linux.tar.gz

unix% gtar xzf /soft/download/ciao-4.2-bin-prism-Linux.tar.gz

unix% gtar xzf /soft/download/ciao-4.2-bin-sherpa-Linux.tar.gz

unix% gtar xzf /soft/download/ciao-4.2-bin-tools-Linux.tar.gz

When all the files are unpacked, the CIAO directory will look like:

unix% ls ciao-4.2
COPYING*                VERSION_core  *
COPYING.LIB*            VERSION_obsvis          data/
INSTALL_BINARY          VERSION_prism           doc/
INSTALL_SOURCE          VERSION_sherpa          include/
LICENSE                 VERSION_tools           install-sh*
LICENSE.SAO             bin/                    lib/
Makefile                binexe/                 ots/
README                  config/                 param/
README.obsvis           config.guess*           share/
VERSION                    test/
VERSION.prop_tk         config.sub*
VERSION_chips           configure*

3. Contributed Science Scripts

The contributed science scripts are written and maintained by local CIAO users at the CXC. More information on each of the scripts is available from the CIAO 4.2 Contributed Scripts Page. Check that page for announcements about new scripts and updates to existing ones.

[New] In CIAO 4.2, the contributed tarfile is designed to be unpacked from the same directory as the CIAO software. (Prior to CIAO 4.2, the scripts had to be unpacked from within the CIAO installation.)

unix% pwd

Unpack the script tarfile:

unix% tar xzvf /soft/download/ciao-4.2-contrib-14Dec2009.tar.gz



The tarfile contains a VERSION.CIAO_scripts file. Compare the timestamp in this file to the "Last Updated" date on the Scripts page to determine when you need to update your local scripts installation.

4. Run the configuration script

Run the CIAO configuration script:

unix% cd ciao-4.2/

unix% ./configure
Running CXC configure, v4.3.10
checking build system type... x86_64-unknown-linux-gnu
checking host system type... x86_64-unknown-linux-gnu
checking target system type... x86_64-unknown-linux-gnu
checking for more... /bin/more
checking for main in -lpthread... no
--with-imagerdir not specified, defaulting to /soft/ciao-4.2/ots/bin
configure: creating ./config.status
config.status: creating bin/
config.status: creating ots/lib/python2.6/config/Makefile
config.status: creating bin/
config.status: creating bin/ciao.csh
config.status: creating bin/ciao.ksh
config.status: creating bin/ciao.bash
config.status: creating bin/
config.status: creating bin/setup_obsvis.csh
config.status: creating bin/
config.status: creating bin/setup_chips.csh
config.status: creating bin/
config.status: creating bin/setup_sherpa.csh
config.status: creating bin/
config.status: creating bin/setup_tools.csh
config.status: creating bin/ciao-python-fix
config.status: creating test/smoke/bin/
config.status: creating test/Makefile
config.status: creating ots/etc/pango/pangorc
config.status: creating ots/etc/pango/pango.modules
config.status: creating ots/etc/gtk-2.0/gtk.immodules
config.status: creating ots/etc/gtk-2.0/gdk-pixbuf.loaders

5. Link to CALDB

Create a link to the calibration data, changing the path to match your system installation:

unix% pwd

unix% ln -s /soft/CALDB CALDB

At this point, your directory should look like:

unix% ls
CALDB@                  VERSION_core            configure*
COPYING*                VERSION_obsvis*
COPYING.LIB*            VERSION_prism           contrib/
INSTALL_BINARY          VERSION_sherpa          data/
INSTALL_SOURCE          VERSION_tools           doc/
LICENSE                 bin/                    include/
LICENSE.SAO             binexe/                 install-sh*
Makefile                config/                 lib/
README                  config.guess*           ots/
README.obsvis              param/
VERSION                 config.log              share/
VERSION.prop_tk         config.status*          test/
VERSION_chips           config.sub*

6. Create a CIAO alias

It is strongly suggested that you create a CIAO alias before continuing.

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"

More information is given in the Running CIAO section of the Starting CIAO thread.

Once the alias is defined, you will be able to simply type

unix% ciao

and CIAO will be setup and ready to use in that window.

Mac OS X 10.6 (Snow Leopard) Workaround

Snow Leopard is not an officially supported platform for CIAO 4.2, but a user-submitted workaround allows CIAO to run.

The workaround must be done before continuing with the "Create the Help File Indexes" step.

Create the Help File Indexes

In order for CIAO to be able to access the help files packaged with the software, it is necessary to create the ahelp database indexes. This step must be run by the user who owns the CIAO installation.

Start CIAO and run ahelp -r:

unix% ciao
CIAO configuration is complete...
CIAO 4.2 Monday, November 30, 2009
  bindir      : /soft/ciao-4.2/bin

unix% ahelp -r

Processing file '/soft/ciao-4.2/doc/xml/ChipsId.xml'...OK

Processing file '/soft/ciao-4.2/doc/xml/Attributes.xml'...OK

Processing file '/soft/ciao-4.2/doc/xml/ChipsDictionary.xml'...OK


Processed Files  : 1039
Succeeded Files  : 1039
Failed Files     : 0
Purged Duplicates: 0

Creating Key Indexes...DONE
Subject DB Size: 1817

Creating Context Indexes...DONE
Context DB Size: 1817

Creating Crossreference DB...DONE
Crossreferences DB Size: 20990

Creating Seealso  DB...DONE
Seealso DB Size: 2461

Run the Smoke Tests

A set of smoke tests are packaged with CIAO 4.2. The tests are designed to spot-check the installation for critical problems, not to run a complete regression test of the system. The output created by the new installation of CIAO is compared against a baseline set of files included in the package.

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.

unix% cd $ASCDS_INSTALL/test
unix% pwd

The smoke test syntax depends on the shell (tcsh, csh, bash); see this FAQ for help in determining which shell you are using.

  • csh/tcsh users:
    unix% make -k test |& tee ~/ciao_test.log
  • bash or ksh users:
    unix% make -k test 2>&1 | tee ~/ciao_test.log

The screen output provides a count of how many tests have been run:

unix% make -k test |& tee ~/ciao_test.log

 Requested test suite includes 42 tests
   [1/42] Running test prism-smoke001 ..       
   [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
   [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 PASSED.

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 PASSED.

or if any failed:

 1 out of 42 smoke tests FAILED.

 Please check
 for a list of known issues before contacting the Help Desk.

Known Smoke Test Issues

There is a bug page for known smoke test issues. If you experience a problem that isn't listed there, submit it to Helpdesk.

Test the CALDB installation

The contributed scripts package contains a tool - check_ciao_caldb - that performs a simple check of the Chandra CALDB installation. Running the tool should produce screen output like the following:

unix% check_ciao_caldb
CALDB environment variable = /soft/ciao-4.2/CALDB
        which is a link to = /soft/CALDB/
             CALDB version = 4.3.1
             release date  = 2010-04-19T19:00:00 UTC
CALDB query completed successfully.

For a more-thorough validation please follow the chkcif steps described on the download CALDB page.

Clean Up the Tarfiles

Finally, you may delete the tarfiles from the original download directory:

unix% rm /soft/download/ciao*tar.gz


Downloading the CALDB: FTP passive mode

Some users are unable to download the CALDB via ciao-install or wget. 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:

macdef init
epsv4 off

Note that there is a blank line after the "epsv4 off" entry.

Using the "--no-passive-ftp" flag with wget may also resolve the issue.

Solaris: "@LongLink" file

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.

Known Conflicts

There are some known conflicts between CIAO and other software or system libraries and tools. They are documented in the following webpages:

Usage and Licensing

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.


12 Aug 2005 original version, new for CIAO 3.2.2
14 Nov 2005 updated for CIAO 3.3: added Linux8 package: renaming and Mac OS X 10.2: Using ds9 v3.0.3 notes.
12 Jan 2006 updated to include CIAO patch instructions
01 Dec 2006 updated for CIAO 3.4 and CALDB 3.3.0
29 Jan 2007 updated to include CIAO 3.4.1[.1] patch instructions
14 Dec 2007 updated for CIAO 4.0: tarfile creates a directory into which it unpacks; CIAO is shipped with gzip support enabled (no longer need to specify an option in the configure step); smoke tests are included in the AUX tarfile; CALDB 3.4.2 is used
21 Feb 2008 updated to include CIAO 4.0.1 patch instructions
26 Feb 2008 consistently use "/soft" as the installation directory
05 Mar 2008 renamed "Reindexing the Help Files" section to "Create the Help File Indices"
10 Mar 2008 system requirements moved to a separate page; "Create the Help File Indices" should be "Create the Help File Indexes"; CIAO does not need to be installed by the root user; "ahelp -r" must be run as user who owns installation; Mac users need to add xrdb to the PATH; FC7 expected smoke test failure
16 Apr 2008 updated to include CIAO 4.0.2 patch instructions; location of CIAO alias updated for bash users
08 Sep 2008 corrected ChIPS test number in Fedora Core 7 smoke test error (test 3 prints the error, not test 5)
15 Dec 2008 updated for CIAO 4.1: CALDB 4.1.0 is used, new supported platform (FC8 instead of FC7); added Known Smoke Test Issues section; removed the "setting xrdb path" section (needed for .CXCdefaults file, which the GUIs no longer use)
15 Jan 2009 updated to include CIAO 4.1.1 patch instructions; include full alias syntax in CIAO alias section; added bash syntax in Run the Smoke Tests section
29 Jan 2009 added "Installing CIAO as root user" information to Choose a CIAO installation directory section
20 Apr 2009 updated to include CIAO 4.1.2 patch instructions; CALDB version updated to 4.1.2; added the test the CALDB installation step; there is a new tool - ciao-install - that automates the installation of CIAO and CALDB
15 Dec 2009 updated for the CIAO 4.2 release: CALDB 4.2, new supported platforms, updates to filenames, "unzip the files" step replaced by using the "z" option to gtar. The contributed script tarfile unpacks from the same level as CIAO software.
30 Dec 2009 Added Snow Leopard workaround
22 Feb 2010 tarfiles are downloaded with wget instead of ciao-install
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 and ACIS background tarfiles
19 Apr 2010 updated for CALDB 4.2.2: version number of CALDB main and ACIS background tarfiles
27 Sep 2010 updated for CALDB 4.3.1: version number of CALDB main

Return to Threads Page: Top | All | Intro

Where are the PDFs?
Last modified: 27 Sept 2010