Unix Administration

This page documents the administrative practices adopted to manage sokwe.janegoodall.org. Following these practices should minimize the work involved in long-term maintenance of the SokweDB project.

This section assumes familiarity with basic Unix administration, like user creation. There is little attempt to document common tasks.

Reading Un*x Documentation

Run the man less command to learn how to use the man (manual) page reader. Learning to use the info reader by running info info can also be helpful.

Unix Shell Access

There are only a few people who should have access to the Unix shell on the server:

• A qualified data manager, if such exists
• Technical staff who act as software developers, database developers, database administrators, or system administrators
• Security personnel
• The JGI affiliated researchers who ultimately manage the SokweDB project

New Unix shell accounts should be given a related outside email address so that the account supports email delivery.

Those unfamiliar with Unix user administration can use the instructions found on the VPN User Management page as a guide when creating a new Unix user with shell access. The "non-standard" part is setting up authentication via SSH key pairs.

Be sure _not_ to put the shell user into the vpn group! Membership in the vpn group is what distinguishes those with shell access from those without.

Periodic Jobs and Email Delivery

The system runs various programs periodically. It can send emails to notify people of the results of actions taken by the system or of other events. This section describes how that works.

Email Destination Addresses

The addresses to which various emails are sent is configured by editing the text file /etc/aliases. The system expects to send system related information to the user root, the superuser account historically used by the system administrator. The aliases file configures the forwarding of email, from such "generic" destinations as root to email addresses given to actual humans. You will most likely be interested in emails originally sent to root, but there may be be other "generic" destinations to forward as well.

After making any changes to /etc/aliases type the following command and run it to make the changes take effect:

newaliases

Email Delivery Failure

Because email is outbound-only, relayed through outlook.com, there is no way to tell whether email sent was actually delivered. Bounce notifications are not delivered back to the server. (I have not looked into whether the server could poll a mailbox, if such exists. At that point it might be better to abandon email relays and deliver mail directly to the Internet.)

Bounces from the email relay, containing notifications of problems communicating with the relay, are delivered into /var/mail/bounces/cur/.

Periodic Jobs

Most often, the periodic running of jobs is scheduled by putting a program (or a script, or a symlink to a program or script) in a special directory. The directories /etc/cron.hourly, /etc/cron.daily, /etc/cron.weekly, and /etc/cron.monthly contain programs which are run at the intervals given in their names.

If you want to do anything more complicated either find a real Linux administrator or use the following commands to read the manual pages:

* man crontab
* man 5 crontab
* man systemd.unit (To read about /etc/systemd/system/*)
* man systemd.timer
* man systemd.service

User Privileges

Unix Groups

Privileges are granted to user accounts by making the account a member of a group, with adduser.

wwwdev

The group in which developers are expected to be placed.

This group grants read/write access to the SokweDB code/documentation repository.

The group allows editing within /var/www/html/, the Document Root of the webserver. Users who alter website content, including those who install generated documentation, edit the wiki engine's configuration or the wiki logos, etc., should be in this group.

Membership in this group allows installation of programs and the like into the /usr/local/ hierarchy.

adm

Allows viewing of the logs in /var/log/. Users who work with the webserver, and others, may need to be in this group.

sudo

Lets the user use the sudo command. Unless other configuration is done, this allows the user to run commands as the root user (the superuser).

vpn

Prevents access to the shell. Used to distinguish accounts which exist only to provide direct network access to the database from other Unix accounts.

Running Commands as the Superuser, root

To grant users sudo privileges, put them in the sudo group. Edit /etc/sudoers.d/50sokwe to change whether a user needs to give their password to use sudo.

The Unix File System

For general information see the Filesystem Hierarchy Standard.

WARNING!: Almost all of SokweDB is generated by the SokweDB build system. Do not directly change things as the Unix or PostgreSQL level! See the Development page for more information.

The Webserver's Document Root: /var/www/html/

The website content, documentation etc., is installed in document root. Some programs that provide functionality for the website, like the wiki or some bespoke software, are designed to be installed in document root and must also go there. (Notably, PHP programs.)

Bespoke Software: /usr/local/

Software written for SokweDB should be installed into the /usr/local/ hierarchy. The exception is web-based programs that are run out of the webserver's document root (/var/www/html/), and Python programs which are installed in virtual environments (in /srv/).

Software configuration: /user/local/etc/

Configuration files, which are usually kept in /etc/, may need to be modified. It is good practice to keep a *.orig file with the original content. All modified configuration files should be symlinked (ln -s ...) into /usr/local/etc/. This directory then provides a catalog of modified files should the configuration need to be reproduced on another server. (As it will need to be, sooner or later.)

Non-Database Storage for SokweDB: /srv/

Put data that is part of SokweDB, but not database content, into /srv/. This includes Python virtual environments which drive website functionality.

Python Virtual Environments

Python virtual environments are used to support the execution of some Python programs. There are management instructions and tools which support this.

Granting and Removing Direct Access to the Database Via a VPN

Users can access the database directly, using programs which run on their desktop, instead of using a browser. To do this a user must have their own Unix login on sokwe.janegoodall.org, properly configured to limit access to the server iteslf. When such a user uses ssh to log in to the sokwe.janegoodall.org server, connecting with the proper set of options, a VPN is established that allows the user to connect directly to the SokweDB PostgreSQL server.

For instructions see the page on managing VPN users.