SAS Installation and initialisation

 

Introduction

The SAS software is distributed in a single archive for each product released. For specifc Operating System builds, the filename syntax of such archive is sas_m.n.p-OS.tgz, where m.n.p is the canonical SAS version number (the SAS a.k.a.) and OS is a string combining the name of the Operating System and its version.

Examples:

  • sas_21.0.0-macOS-12.6.tgz: SAS 21.0.0 built on macOS 12.6 (a.k.a. Monterey)
  • sas_21.0.0-Ubuntu22.04.tgz: SAS 21.0.0 built on Ubuntu 22.04LTS.

     

SAS is distributed as well in a Linux based Virtual Machine, where it has been installed together with some "ready-to-use" tools like Heasoft, ds9, Grace, etc. Such package is dubbed Virtual Machine for SAS (VM4SASNN) where NN is the short SAS version, e.g. VM4SAS21.0 is the Virtual Machine for SAS 21.0.0.

With SAS 21.0 we are introducing the SAS Docker image (docker4sas), a dockerized version of the SAS which can be run on any Operating System, allowing us to run directly individual SAS tasks, without the need to run a complete Virtual Machine.

For each release, Table 1 shows all the SAS downloadable products, including VM4SASNN and the new docker4sas. On the same page, reading section Which SAS should I take? might help you choose the most suitable SAS product for you.

To work with SAS builds you must install some tools. Find here detailed information on which tools you need to install.

To process XMM-Newton Observations with SAS you will need also the full set of calibration data files known as Current Calibration Files (CCF). You can find information on how to download and install these files here.

Detailed instructions on how to install and use the VM4SAS21.0 can be found here.

Detailed instructions on how to install and use the docker4sas:sas21_0 Docker image can be found here.

For Microsoft Windows users, we are providing for the first time detailed instructions on how to use directly in the Windows Subsystem for Linux (WSL) the build of SAS 21.0 made on the Ubuntu OS. Until now it was not possible to run Linux based applications directly on Windows. However, in September 2020, Microsoft released the WSL v2 which is a full porting of the Ubuntu 22.04LTS kernel to Windows, therefore opening the possibility to run directly any Linux applications on Windows. Such instructions can be found here.

Installation procedure

Let us get started by choosing properly the most appropriate SAS product for the Operating System you are working on. Please read carefully the tips given in here before clicking on any download link shown in Table 1. Once you have made up your choice, click on the selected link to start downloading the single compressed archive.

 

Before installing the macOS builds, specially if you are running macOS Catalina or BigSur, you must consider whether the System Integrity Protection or SIP is enabled or not. A simple way to check it is by running the command:

csrutil status

If it is enabled, just after downloading the compressed tarball including the build of SAS 21.0.0 for macOS, you must execute on that archive the following command (example shows the case for the macOS Catalina tarball):

xattr -d com.apple.quarantine sas_21.0.0-macOS-12.6.tgz

Such command will delete the com.apple.quarantine attribute which is set automatically on any file downloaded from internet via any web-browser. The file is put in quarantine because is considered suspicious of containing malicious software. Failing to remove such attribute will prevent you to run any installed SAS binary, raising fatal errors of the form:

code signature in (...) not valid for use in process using Library Validation: library load disallowed by system policy....

Once chosen the directory where you want to install the SAS, e.g. /top_dir, copy the downloaded archive to it and unpack it with

tar zxf sas_21.0.0-OS.tgz

Inmediately after, run the install.sh script as

./install.sh

The installation script checks for the presence of the required components of SAS and unpacks them into binaries, libraries and documentation in a directory named xmmsas_20230412_1735 below /top_dir. It finishes running a script named configure_install which checks for the exixtence in your system of installations of Perl and Python.

Regarding Perl it looks whether the variable SAS_PERL is defined and points to a binary which must be available through the PATH. Similarly, it checks whether a Python binary with version ≥3.8 is available through the PATH. In case any of the two conditions is not fulfilled, the script complains and stops the installation. Once the missing component is provided, to complete the installation you must run again configure_install, which is available in the subdirectory /top_dir/xmmsas_20230412_1735.

The installation is complete when configure_install creates, in the same directory, two shell scripts named setsas.sh and setsas.csh which can be used to initialise the SAS.

Initialisation

Depending on your shell, you can initialise SAS sourcing either setsas.sh or setsas.csh

source /top_dir/xmmsas_20230412_1735/setsas.sh (sh/bash/ksh)

source /top_dir/xmmsas_20230412_1735/setsas.csh (csh/tcsh)

The setsas.[c]sh scripts configure properly your shell environment to run any SAS task in your operating system except for the variables SAS_CCFPATH, SAS_ODF and SAS_CCF.

You must define SAS_CCFPATH to point to the directory where you have stored the Calibration Files.

Once you have chosen the XMM-Newton Observation to analize, SAS_CCF and SAS_ODF must be defined specifically for it. Detailed information on how to start working with SAS can be found in the SAS Startup Thread.

Some SAS tasks use Heasoft FTOOLS which forces us to initialise Heasoft before SAS. Any attempt to initialise only SAS will fail with an error message.

macOS SIP, SELinux and the (DY)LD_LIBRARY_PATH

The macOS System Integrity Protection or SIP, introduced by macOS v10.11 "El Capitan" in 2015, when enabled, prevents the use of the DYLD_LIBRARY_PATH as the mechanism used by a binary to search for the shared libraries it requires to run. Given that SAS macOS binaries relied on using DYLD_LIBRARY_PATH to run, we had to request to disable SIP until SAS 19.0.

A security system similar to SIP was available on Linux since 2003, the Security Enhanced Linux or SELinux, but computers running Linux were not setting it by default as it did macOS with SIP. SELinux disables the use of LD_LIBRARY_PATH to search for the shared libraries required to run a SAS Linux binary.

SAS 21.0.0 binaries on macOS and Linux do not require anymore the setting of the (DY)LD_LIBRARY_PATH as the search path for shared libraries. Therefore, macOS and Linux builds of SAS 21.0.0 can be used with macOS SIP enabled and on Linux running SELinux. Nevertheless, the SAS initialisation scripts still set properly the (DY)LD_LIBRARY_PATH environment variable, to allow running SAS on systems where SIP or SELinux are not enabled.