Installing CIAO using the ciao-install tool

Upgrading to CIAO 4.1.2

If the installation directory contains an existing CIAO installation then ciao-install will only attempt to install the patch/upgrade files.

Therefore, if you are upgrading CIAO, you only need to download the necessary patch file or files. It does not cause any problems if you have downloaded the full CIAO installation, other than the time taken and disk space used.

Note that the tool is currently not intelligent enough to determine whether the CALDB or CIAO contributed script packages are up to date, so these files will always be installed. As noted below the script package has been updated to match the CIAO 4.1.2 release and so it should be downloaded.

Upgrading from CIAO 4.1

If your existing CIAO installation is CIAO 4.1 then you need to download both the CIAO 4.1.1 and CIAO 4.1.2 patches. They are available from the CIAO download pages for your system.

The CIAO 4.1.1 patch is a platform independent file called ciao-4.1.1-tools.tar.gz and the 4.1.2 patch is called ciao-4.1.2-patch-<os>.tar.gz, where <os> is one of fc4, fc8, osxi, osxppc, sun, or sun10 and should match the system you are upgrading.

Upgrading from CIAO 4.1.1

If your existing CIAO installation is CIAO 4.1.1 then you need to download the CIAO 4.1.2 patch file from the CIAO download pages for your system.

The 4.1.2 patch file is called ciao-4.1.2-patch-<os>.tar.gz, where <os> is one of fc4, fc8, osxi, osxppc, sun, or sun10 and should match the system you are upgrading.

CIAO contributed scripts

Since the CIAO contributed script package has been updated for the CIAO 4.1.2 release then you should also download this file. It is called CIAO_4.1_scripts.tar and is available from the same page as the patch files.

A full installation of CIAO 4.1.2

If all the CIAO components are downloaded, and the installation directory does not contain an existing CIAO installation, then the tool will install the full CIAO package (version 4.1.2).

To install CIAO, you need the following packages from the CIAO download pages:

• Binaries: ciao-4.1-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. There are five components in CIAO 4.1: core, tools, chips, sherpa, and obsvis.

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

  <OS>	Operating system
  fc8	Fedora Core 8
  fc4	Fedora Core 4
  osxi	OS-X with an Intel processor
  osxppc	OS-X with a PPC processor
  sun	Solaris 8 and 9
  sun10	Solaris 10

  CIAO 4.1.1 (optional, all platforms): there is a platform-independent patch which contains Cycle 11 proposal planning calibration files: ciao-4.1.1-tools.tar. This is required for users of PIMMS or if you are planning to use the ciao-install tool to install CIAO.

  CIAO 4.1.2: the platform-specific binary patch file: ciao-4.1.2-patch-<OS>.tar.gz.

  Solaris 10 Note: the CIAO 4.1.2 release for Solaris 10 is a full release, so there are no 4.1.1 or 4.1.2 patch files for that platform and the binary files are called ciao-4.1.2-bin-xxx rather than ciao-4.1-bin-xxx.

• Chandra Calibration Database (CALDB)

• Contributed science scripts and modules: CIAO_4.1_scripts.tar

Save the tarfiles to a location that is accessible from where you wish to install CIAO. These files were used to install CIAO on a Fedora Core 8 machine:

unix% ls -1
acis_bkgrnd_4.1.2.tar.gz
caldb_4.1.2_main.tar.gz
ciao-4.1.1-tools.tar.gz
ciao-4.1.2-patch-fc8.tar.gz
ciao-4.1-bin-chips-fc8.tar.gz
ciao-4.1-bin-core-fc8.tar.gz
ciao-4.1-bin-obsvis-fc8.tar.gz
ciao-4.1-bin-sherpa-fc8.tar.gz
ciao-4.1-bin-tools-fc8.tar.gz
CIAO_4.1_scripts.tar

CIAO

As of CIAO 4.0, CIAO unpacks into a directory called ciao-<version>/, so for the current release this is ciao-4.1/; prior to CIAO 4.0 the files unpacked into the working directory. So if CIAO were to be installed into /usr/local/, it would be placed into the directory /usr/local/ciao-4.1/. This directory (/usr/local/ciao-4.1/) 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

You can choose to install the CALDB within the CIAO installation - in the directory $ASCDS_INSTALL/CALDB or in a separate directory, in which case $ASCDS_INSTALL/CALDB should be a soft link to the actual location.

For this thread, we assume that the database will be installed in the /soft directory:

/soft/CALDB/

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.1/ directory);
2. 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.

1. The installation log

The tool prints brief messages to the screen and a more extensive log to the file ~/ciao-install-<pid>.log; in our example the user running the tool is called ciaouser.

The log file can be used to help diagnose problems via the Helpdesk, as well as to monitor progress of the installation. It is suggested that at this point you start another terminal and use the tail command to monitor this output; in this case the command would be:

unix% tail -f ~/ciao-install-7557.log
Output recorded in /home/ciaouser/ciao-install-7557.log

2. The download directory

At this stage we move back into the terminal running the ciao-install tool and enter return to accept the default location for the download directory. For this installation the files were placed in the directory /soft/download/. If we wanted to change this location then we would have entered the full path to the desired directory; note that tab completion is possible at these prompts.

3. The OS

The following message is printed to both the screen and the log file:

Installing system fc8

The tool has analyzed the contents of the download directory and realized that there is only one system available for installation; in this case fc8 so it has automatically selected it. If there were multiple systems present then the tool would have asked you which one to install (the output of this prompt is not shown here).

4. Location for CIAO

The next prompt is for the location of CIAO; as we wish CIAO to be installed into /soft/ciao-4.1 so we answer /soft rather than accept the default value (again, command-line completion is available at this prompt):

Install Directory - Default: /usr: /soft

5. Test the installation

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? (Default y) y/n?: 

6. Update the defaults

The final prompt is to ask you whether the default answers for the prompts should be updated to use your current selection. If you accept the default here (which is yes), 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:

Update Defaults? (Default y) y/n?: 

7. The smoke tests

At this point the tool starts to unpack and install CIAO; both the screen and log file will be filled by lines like the following (the exact output depends on what parts of CIAO you downloaded):

Installing /soft/download/ciao-4.1-bin-core-fc8.tar.gz in /soft
Installing /soft/download/ciao-4.1-bin-sherpa-fc8.tar.gz in /soft
Installing /soft/download/ciao-4.1-bin-tools-fc8.tar.gz in /soft
Installing /soft/download/ciao-4.1-bin-chips-fc8.tar.gz in /soft
Installing /soft/download/ciao-4.1-bin-obsvis-fc8.tar.gz in /soft
Installing /soft/download/ciao-4.1.1-tools.tar.gz in /soft
Installing /soft/download/ciao-4.1.2-patch-fc8.tar.gz in /soft
Installing /soft/download/CIAO_4.1_scripts.tar in /soft
running chcon to allow CIAO to work with SELinux
Running configure ./configure

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.

If ciao-install was run without the -caldb flag then the CALDB files would also be installed at this stage, so the screen output would include lines like

Installing /soft/download/caldb_4.1.2_main.tar.gz in /soft
Installing /soft/download/acis_bkgrnd_4.1.2.tar.gz in /soft

At this point the output of the installation log will diverge from the screen output; the screen will show the following (the time taken to output all these lines depends on the speed of your system)

Re-indexing system
Creating binary compiled python modules
Running smoke tests
Smoke tests complete. Please check logfile.
Processing complete! Log file is /home/ciaouser/ciao-install-7557.log

whilst the log file will include more details. The main part of the log file output to notice is the test results. This begins with

Running smoke tests
PATH=${PWD}/smoke/bin:${PATH} && \
        export PATH && \
        make test-ui test-obsvis test-chips test-sherpa \
                test-dm test-crates test-tools
make[1]: Entering directory `/soft/ciao-4.1/test'

Running test prism-smoke001
prism-smoke001 completed SUCCESSFULLY

Running test prism-smoke002
prism-smoke002 completed SUCCESSFULLY

and will continue until all the tests have been run, at which point you should see

Running test tools-dmstat3
PASS: Test tools-dmstat3 completed successfully

make[1]: Leaving directory `/soft/ciao-4.1/test'
Smoke tests complete. Please check logfile.
Processing complete! Log file is /home/ciaouser/ciao-install-7557.log

and you can control-c out of the tail command.

Screen output during the 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.

Verifying test successes

A successful test logs the message:

<testname> completed SUCCESSFULLY

or

PASS: Test <testname> completed SUCCESSFULLY

whilst unsuccessful tests report:

<testname> FAILED
 Review /tmp/smoke/<testname>/diff.log for details

The smoke tests do not currently print a summary of successful and failed tests. Review the log file to be certain that none of the tests failed.

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.

8. CALDB installation

Since the CALDB is being installed in a separate location the ciao-install tool needs to be re-run without the -caldb switch to unpack and install the CALDB. ciao-install follows the link created in the first run to know where to install the CALDB files.

If the CALDB were installed within the CIAO installation (i.e. ciao-install was run without the -caldb switch) then this step is unnecessary and you can skip to checking the CALDB installation.

We accept the default values for download and installation, but answer no to the smoke tests and update of defaults (the smoke tests do not check the CALDB installation):

unix% ./ciao-install
Output recorded in /home/ciaouser/ciao-install-8388.log
Download Directory - Default: /soft/download: 
Installing system fc8
Install Directory - Default: /soft: 
Run Smoke tests? (Default y) y/n?: n
Update Defaults? (Default y) y/n?: n

The tool will now proceed to install the CALDB files into the /soft/ciao-4.1/CALDB directory, which was created in the first ciao-install run as a soft link to /soft/CALDB/.

Installing /soft/download/CIAO_4.1_scripts.tar in /soft
Installing /soft/download/caldb_4.1.2_main.tar.gz in /soft
Installing /soft/download/acis_bkgrnd_4.1.2.tar.gz in /soft
running chcon to allow CIAO to work with SELinux
Running configure ./configure
Re-indexing system
Creating binary compiled python modules
Processing complete! Log file is /home/ciaouser/ciao-install-8388.log

The ciao-install has not installed the CIAO tar files since it determined that they were already installed; it did however re-install the scripts file (CIAO_4.1_scripts.tar) since it can not safely compare the version of this package to the installed version.

9. Check the CALDB installation

The scripts package contains the check_ciao_caldb tool which performs a simple test of the Chandra CALDB installation. Running the tool should produce screen output like the following:

unix% ls -1 /soft/ciao-4.1/CALDB/
data/
docs/
software/
unix% check_ciao_caldb
CALDB environment variable = /soft/ciao-4.1/CALDB
        which is a link to = /soft/CALDB/
             CALDB version = 4.1.2
             relelase date = 2009-03-26T18:00:00
CALDB query completed successfully.

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

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:

• "Watch Out" List

• Other Software Packages bug page

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