NetDRMS Preparation Version 9.1

Preparing for NetDRMS

Setting up a system or local network in which NetDRMS can run involves the establishment and configuration of two elements, the database server, and the bulk data storage system. These should be one-time tasks for someone with administrative privileges on the systems on which these services will run. Once the services have been established, any user should be able to set up their own NetDRMS development environment by following the User Setup instructions. Users who only want access to public NetDRMS codes or libraries can do so by getting appropriate instructions from the site administrator (guidelines to be supplied).

You can download and even build the NetDRMS software before or after the site preparation described here, provided that the required third-party libraries are in place. Naturally any code that requires access to the database will not work until the DRMS and SUMS services are running, and these will require the setup described here.

Setting up the Environment

If you will be running a multi-user system, you need to set up shared file directories where the bulk data segments associated with records in the database are physically stored. This directory space is managed by the Storage Unit Management System (SUMS) software, which consequently needs the ability to create and remove files on the system and to change their ownerships to those of the users requesting storage. This can be accomplished by doing the following:

  1. Create a pseudo-user (production by default), or designate a regular user who manages the SUMS and will own the SUMS directory root. This account is what will be used for SUMS_MANAGER in configuring the NetDRMS software.
  2. If necessary, modify your sudoers file (probably /etc/sudoers) to include the name of the SUMS manager. This user must have at least the privileges to run the setuid program sum_chmown on the system on which the SUMS directory root will be mounted without password prompt:
          production host=NOPASSWD:/usr/local/bin/sum_chmown
    
    The actual location of the program is up to you, but since it is a system-privileged program you may want to keep it in a a system directory.
  3. Create a user group to which the SUMS owner (production by default) belongs. Any users who will be using the NetDRMS system to access or create data also must belong to this group.
  4. If a pseudo-user account has been created, make sure that its login directory contains a .pgpass file with appropriate contents and permissions, as described in the user setup instructions

If you are running a single-user system on your workstation or laptop, this should not be necessary. Just make sure that you are the SUMS administrator, i.e. that you own the SUMS disk storage space directories discussed below under "Setting up the Data Storage."

Setting up the Database

NetDRMS is built around the PostgreSQL database; therefore, you must have the PostgreSQL Core installed, at least as a client library, on any machine on which you or other users intend to build the package. You must also have it installed as a server on at least one machine to which your client(s) will have access. For instructions on installing and configuring PostgreSQL, see the Postgres instructions. You should have PostgreSQL Version 8.1 or higher (8.4 is recommended.) Installed DRMS database servers currently run at various NetDRMS installations under the following:

Once Postgres has been installed and properly configured, you can proceed to build the DRMS and SUMS databases.

  1. Make sure that postmaster (or postgres), the PostgreSQL server, is running on your server. See the instructions in Chapter 17 of the PostgreSQL 8.3 Documentation. The hostname of your PostgreSQL server is what users will use for DBSERVER_HOST in configuring their NetDRMS software.
        $ su postgres_admin
        $ cd postgres_root_directory
        % pg_ctl start -D data -l logfile
        % pg_ctl start -D data_sums -l logfile -o "-p 5434"
    
    You may see warning messages in the logfile like
        LOG:  could not create IPv6 socket: Address family not supported by protocol
    
    It seems to be safe to ignore these.
  2. Create a database that will serve NetDRMS using the createdb command. Individual users can of course create their personal databases, but it is a good idea to have a common site database that will have registered namespaces that can be shared with other NetDRMS databases. At the Stanford SDO JSOC, this database is named jsoc. This database name is what users will use for DBNAME in configuring their NetDRMS software. Also, the character encoding for the SDO JSOC is LATIN1 (rather than the default UTF8), so it is advisable to use this character encoding for the NetDRMS database at your site:
        $ su postgres_admin
        % createdb --locale C -E LATIN1 -T template0 dbname
        % createdb --locale C -E LATIN1 -T template0 -p 5434 dbname_sums
    
  3. Issue the following command, using whatever database name you have assigned above:
        $ su postgres_admin
        % createlang plpgsql dbname
    
  4. Create the administrative tables necessary to adminster NetDRMS in your PostgreSQL server. If you have downloaded the NetDRMS distribution and run a configure successfully, you can do so by running, as the postgres administrator in the DRMS root directory, the following scripts:
        % psql -f scripts/NetDRMS.sql dbname                      (view script)
        % scripts/createpgfuncs.pl dbname                         (view script)
    
    Alternatively, you can create the tables by connecting to the appropriate database dbname and executing the script commands (view script above).

    (Strictly speaking, only the admin.ns table is required. The admin.sessionns table is optional. It provides for a default session namespace if none is specified on the command line.)
  5. At this point, you need to set up at least two roles. Run the following :
        $ psql -h dbserver -d dbname -U postgres_admin
        db=> create role drmsuser;
        db=> create role sumsadmin;
        db=> \q
    
  6. Create the SUMS_MANAGER (e.g. "production") postgres user in the database. Follow the instructions for user setup step 1 only using the name production (or whatever you have designated the SUMS_MANAGER account to be in your config.local).
  7. If you have any shared namespaces (e.g. "drms", shared by users with the role "drmsuser"), then you should run (for each):
        % masterlists dbuser=drmsuser namespace=drms nsgrp=sys
    
    Note that you can create additional roles for different shared namespaces. Users can be added to roles by following step 7 of the user setup instructions.
    Note: Even if you do not create the "drmsuser" role, you will still need the "drms" namespace for the next step. In that case it may suffice to create the schema thus:
        $ psql -h dbserver -d dbname -U postgres_admin
        db=> create schema drms;
        db=> \q
    
  8. Set up the software version control table:
        $ psql -h dbserver -d dbname -U postgres_admin
        db=> create table drms.minvers (minversion text default '1.0' not null);
        db=> grant select on drms.minvers to public;
        db=> insert into drms.minvers (minversion) values ('1.0');
        db=> \q
    

Installing Third-Party Libraries

Apart from the PostgreSQL libraries, the DRMS API requires the CFITSIO library to be available for reading and writing FITS files internally. Distribution packages and straightforward installation instructions can befound at the FITSIO Home Page. The libraries and include files should be installed in directories accessible to the DRMS/SUMS installers, administrators, and any users wishing to write programs using the DRMS API, preferably /usr/lib and /usr/include or /usr/local/lib and /usr/local/include. In any case, the paths will need to be included in the site localization file config.local.

Setting up the Data Storage

  1. Create one or more directories to serve as dynamically allocated SUMS disk storage space. These directories must be named /SUM[0-9]*, e.g. /SUM, /SUM0, /SUM101. The actual locations do not matter, as long as there are path links at the file system root named /SUM[0-9]*, but it is better if each directory resides on its own disk partition. Because the storage is dynamically located, it is a good idea to use partitions that are not automatically backed up. The directories must be owned by a user who is the SUMS administrator, with permission to run the scripts to start, stop, and manage the SUMS servers. The disk partitions must be visible on any system on which DRMS will run. The SUMS directories must be writeable by any DRMS users. This can be achieved either by setting their protection mask to drwxrwsr-x and having their group ownership be that of the DRMS user group, or by setting the mask to drwxrwxrwx (or drwxrwxrwt ?)

    N.B. It is strongly recommended that the SUMS directories be mounted on XFS file systems. The EXT3 file system limits the number of directories to less then 64K, which is impossibly small for the dynamic directory needs of SUMS.
  2. Make sure there is a SUMS log directory on the SUMS server machine. By default this directory is expected to be named /usr/local/logs/SUM If it is named anything else, you will have to modify the SUMS_LOG_BASEDIR line in the file config.local accordingly. This directory must either be world writeable, or it should have the group sticky bit set and be owned by a group that includes all users of the DRMS.

Finishing up: Building SUMS

At this point, additional configuration of the database is most easily accomplished if you already have built (or upgraded) the NetDRMS package. Follow the installation instructions, then proceed to the following steps:

  1. Follow the user setup instructions to set up database access for the SUMS manager (SUMS_MANAGER as defined in your config.local). In addition to adding the SUMS manager to the regular database, access must also be granted to the SUMS database. This only requires step 1 of the user setup instructions, changing the connection of course from:
        % psql -h dbserver -d dbname -U postgres_admin
    
    to
        % psql -h dbserver -p5434 -d dbname_sums -U postgres_admin
    
    Note that the password for the SUMS manager must be the same for connecting to both databases.
  2. Create the public tables needed for SUMS. The easiest way to do this is to run, as the postgres administrator but in the DRMS root directory,
        % psql -p5434 -f scripts/create_sums_tables.sql dbname_sums  (view script)
        % psql -p5434 -f scripts/create_sumindex.sql dbname_sums     (view script)
    
  3. For each SUMS storage root path named dirname, enter its name and storage size, in bytes, into the sum_partn_avail table:
        $ psql -h dbserver -p 5434 dbname_sums -U postgres_admin
        db_sums=>   insert into sum_partn_avail (partn_name,total_bytes,avail_bytes,
                    pds_set_num,pds_set_prime)
               values ('dirname', bytes, bytes, 0, 0);
        db_sums=> \q
    
    bytes should be less than the total available storage on the relevant partition, as shown by df. (Remember to multiply the number of blocks by 1024 or 512 as appropriate.) The exact numbers don't really matter as long as they are less than the currently available storage on the partition. They will be updated automatically by the SUMS service.
  4. Regardless of whether you will be running single-user or multi-user, the SUMS manager (yourself if you are running single-user) needs to be granted proper access to the SUMS tables in the database by the Postgres adminsistrator. Assuming the SUMS manager is named "production", and the Postgres manager is named "postgres", you need to create the user production, and then grant appropriate privileges:
        $ psql -h dbserver -p 5434 -d dbname_sums -U postgres_admin
        db_sums=> create user production;
        db_sums=> alter user production with password 'init_pass';
        db_sums=> grant all on sum_tape to production;
        db_sums=> grant all on sum_ds_index_seq,sum_seq to production;
        db_sums=> grant all on sum_file,sum_group,sum_main,sum_open to production;
        db_sums=> grant all on sum_partn_alloc,sum_partn_avail to production;
        db_sums=> \q
    
  5. As the SUMS_MANAGER (e.g. "production"), in the DRMS root directory, run
      # make sums
    
  6. If this is a fresh installation, or if the sum_chmown command has changed (or been added) since the previous release, you must have your system manager copy the binary file sum_chmown to a system directory (the one specified in step 2 of the section "Setting up the Environment" above), change its ownership to root, and it permissions to setuid, e.g.:
        [root]# cp ~production/drms/_linux_x86_64/base/sums/apps/sum_chmown /usr/local/bin
        [root]# chown root:root /usr/local/bin/sum_chmown
        [root]# chmod u+s /usr/local/bin/sum_chmown
    
  7. To start the SUMS server, run (as the SUMS_MANAGER)
          sum_start.NetDRMS
    
    provided that you have $DRMS/bin/$PLATFORM and $DRMS/scripts in your path, which is highly advisable.

    N.B. The script does not return a prompt after echoing
      sum_svc now available
    
    Just hit a RETURN. And don't worry about messages like:
      Can't open config file /usr/local/logs/SUM/sum_rm.cfg. Using defaults...
      !!WARNING: No JSOC_MACHINE in env
      SUMLIB_InfoGetArray() calls will fail
    
    (The last is not true.)
  8. To stop the SUMS server at any time, run (as the SUMS_MANAGER)
          $DRMS/scripts/sum_stop.NetDRMS
    
    (You may need to provide a -f flag to force a stop if there are pending or hanging processes.)
  9. To start up a RemoteSUMS server, so that mirrored data can be automatically downloaded from its originating DRMS site, see the RemoteSUMS Configuration instructions.

Valid HTML 4.01 Strict NetDRMS Home 26 Nov 2012, 23:10-0800