0.00%
Search · Index

Weblog Page

Showing 11 - 20 of 230 Postings (summary)

AOLserver keepalive with inittab

Created by Gustaf Neumann, last modified by Gustaf Neumann 04 Jun 2017, at 10:42 AM

This is an alternative method for keeping the AOLserver process running. The recommended method is to run AOLserver supervised.

This step should be completed as root. This can break every service on your machine, so proceed with caution.

  • There are 2 general steps to getting this working.

    1. Install a script called restart-aolserver. This script doesn't actually restart AOLserver - it just kills it.

    2. Ask the OS to restart our service whenever it's not running. We do this by adding a line to /etc/inittab.

    Calling restart-aolserver kills our service. The OS notices that our service is not running, so it automatically restarts it. Thus, calling restart-aolserver effectively restarts our service.

  • Copy this file into /var/tmp/restart-aolserver.txt.

  • This script needs to be SUID-root, which means that the script will run as root. This is necessary to ensure that the AOLserver processes are killed regardless of who owns them. However the script should be executable by the web group to ensure that the users updating the web page can use the script, but that general system users cannot run the script. You also need to have Perl installed and also a symbolic link to it in /usr/local/bin.

    [joeuser ~]$ su -
    Password: ***********
    [root ~]# cp /var/tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver
    [root ~]# chown root.web /usr/local/bin/restart-aolserver
    [root ~]# chmod 4750 /usr/local/bin/restart-aolserver
    [root ~]# ln -s /usr/bin/perl /usr/local/bin/perl
    [root ~]# exit
  • Test the restart-aolserver script. We'll first kill all running servers to clean the slate. Then, we'll start one server and use restart-aolserver to kill it. If it works, then there should be no more servers running. You should see the following lines.

    [joeuser ~]$ killall nsd
    nsd: no process killed
    [joeuser ~]$ /usr/local/aolserver/bin/nsd-postgres -t ~/var/lib/aolserver/birdnotes/nsd.tcl
    [joeuser ~]$ restart-aolserver birdnotes
    Killing 23727
    [joeuser ~]$ killall nsd
    nsd: no process killed

    The number 23727 indicates the process id(s) (PIDs) of the processes being killed. It is important that no processes are killed by the second call to killall. If there are processes being killed, it means that the script is not working.

  • Assuming that the restart-aolserver script worked, login as root and open /etc/inittab for editing.

    [joeuser ~]$ su -
    Password: ************
    [root ~]# emacs -nw /etc/inittab
  • Copy this line into the bottom of the file as a template, making sure that the first field nss1 is unique.

    nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/birdnotes/nsd.tcl
  • Important: Make sure there is a newline at the end of the file. If there is not a newline at the end of the file, the system may suffer catastrophic failures.

  • Still as root, enter the following command to re-initialize /etc/inittab.

    [root ~]# killall nsd
    nsd: no process killed
    [root ~]# /sbin/init q
  • See if it worked by running the restart-aolserver script again.

    [root ~]# restart-aolserver birdnotes
    Killing 23750

If processes were killed, congratulations, your server is now automated for startup and shutdown.

Manual backup and recovery

Created by Gustaf Neumann, last modified by Gustaf Neumann 04 Jun 2017, at 10:38 AM

This section describes how to make a one-time backup and restore of the files and database. This is useful for rolling back to known-good versions of a service, such as at initial installation and just before an upgrade. First, you back up the database to a file within the file tree. Then, you back up the file tree. All of the information needed to rebuild the site, including the AOLserver config files, is then in tree for regular file system backup.

  1. Back up the database to a file.

    • Oracle.

      • Download the backup script. Save the file export-oracle.txt as /var/tmp/export-oracle.txt

      • Login as root. The following commands will install the export script:

        [joeuser ~]$ su -
        [root ~]# cp /var/tmp/export-oracle.txt /usr/sbin/export-oracle
        [root ~]# chmod 700 /usr/sbin/export-oracle
        
      • Setup the export directory; this is the directory where backups will be stored. We recommend the directory /ora8/m02/oracle-exports.

        [root ~]# mkdir /ora8/m02/oracle-exports
        [root ~]# chown oracle:dba /ora8/m02/oracle-exports
        [root ~]# chmod 770 /ora8/m02/oracle-exports
        
      • Now edit /usr/sbin/export-oracle and change the SERVICE_NAME and DATABASE_PASSWORD fields to their correct values. If you want to use a directory other than /ora8/m02/oracle-exports, you also need to change the exportdir setting.

        Test the export procedure by running the command:

        [root ~]# /usr/sbin/export-oracle
        mv: /ora8/m02/oracle-exports/oraexport-service_name.dmp.gz: No such file or directory
        
        Export: Release 8.1.6.1.0 - Production on Sun Jun 11 18:07:45 2000
        
        (c) Copyright 1999 Oracle Corporation.  All rights reserved.
        
        Connected to: Oracle8i Enterprise Edition Release 8.1.6.1.0 - Production
        With the Partitioning option
        JServer Release 8.1.6.0.0 - Production
        Export done in US7ASCII character set and US7ASCII NCHAR character set
          . exporting pre-schema procedural objects and actions
          . exporting foreign function library names for user SERVICE_NAME
          . exporting object type definitions for user SERVICE_NAME
          About to export SERVICE_NAME's objects ...
          . exporting database links
          . exporting sequence numbers
          . exporting cluster definitions
          . about to export SERVICE_NAME's tables via Conventional Path ...
          . exporting synonyms
          . exporting views
          . exporting stored procedures
          . exporting operators
          . exporting referential integrity constraints
          . exporting triggers
          . exporting indextypes
          . exporting bitmap, functional and extensible indexes
          . exporting posttables actions
          . exporting snapshots
          . exporting snapshot logs
          . exporting job queues
          . exporting refresh groups and children
          . exporting dimensions
          . exporting post-schema procedural objects and actions
          . exporting statistics
        Export terminated successfully without warnings.
    • PostgreSQL.Create a backup file and verify that it was created and has a reasonable size (several megabytes).

      [root root]# su - $OPENACS_SERVICE_NAME
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ pg_dump -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp $OPENACS_SERVICE_NAME
      
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ ls -al /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp 
      -rw-rw-r-x    1 $OPENACS_SERVICE_NAME  $OPENACS_SERVICE_NAME   4005995 Feb 21 18:28 /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
      [root root]#
      su - $OPENACS_SERVICE_NAME
      pg_dump -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp openacs-dev
      ls -al /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp
      exit
      
  2. Back up the file system.Back up all of the files in the service, including the database backup file but excluding the auto-generated supervise directory, which is unneccesary and has complicated permissions.

    In the tar command,

    • c create a new tar archive

    • p preserves permissions.

    • s preserves file sort order

    • z compresses the output with gzip.

    • The --exclude clauses skips some daemontools files that are owned by root and thus cannot be backed up by the service owner. These files are autogenerated and we don't break anything by omitting them.

    • The --file clause specifies the name of the output file to be generated; we manually add the correct extensions.

    • The last clause, /var/lib/aolserver/$OPENACS_SERVICE_NAME/, specifies the starting point for backup. Tar defaults to recursive backup.

    [root root]# su - $OPENACS_SERVICE_NAME
    
    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ tar -cpsz --exclude /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/supervise  --file /var/tmp/$OPENACS_SERVICE_NAME-backup.tar.gz /var/lib/aolserver/$OPENACS_SERVICE_NAME/
    tar: Removing leading `/' from member names
    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
  3. Suffer a catastrophic failure on your production system.(We'll simulate this step)

    [root root]# svc -d /service/$OPENACS_SERVICE_NAME
    [root root]# mv /var/lib/aolserver/$OPENACS_SERVICE_NAME/ /var/lib/aolserver/$OPENACS_SERVICE_NAME.lost
    [root root]# rm /service/$OPENACS_SERVICE_NAME
    rm: remove symbolic link `/service/$OPENACS_SERVICE_NAME'? y
    [root root]# ps -auxw | grep $OPENACS_SERVICE_NAME
    root      1496  0.0  0.0  1312  252 ?        S    16:58   0:00 supervise $OPENACS_SERVICE_NAME
    [root root]# kill 1496
    
    [root root]# ps -auxw | grep $OPENACS_SERVICE_NAME
    [root root]# su - postgres
    [postgres pgsql]$ dropdb $OPENACS_SERVICE_NAME
    DROP DATABASE
    [postgres pgsql]$ dropuser $OPENACS_SERVICE_NAME
    DROP USER
    [postgres pgsql]$ exit
    logout
    [root root]#
  4. Recovery.

    1. Restore the operating system and required software. You can do this with standard backup processes or by keeping copies of the install material (OS CDs, OpenACS tarball and supporting software) and repeating the install guide. Recreate the service user ($OPENACS_SERVICE_NAME).

    2. Restore the OpenACS files and database backup file.

      [root root]# su - $OPENACS_SERVICE_NAME
      
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver
      [$OPENACS_SERVICE_NAME aolserver]$ tar xzf /var/tmp/$OPENACS_SERVICE_NAME-backup.tar.gz
      [$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME
      
      [$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.web$OPENACS_SERVICE_NAME
      
      
    3. Restore the database

      • Oracle.

        1. Set up a clean Oracle database user and tablespace with the same names as the ones exported from (more information).

        2. Invoke the import command

          imp $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAME FILE=/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/nighty_backup.dmp FULL=Y
      • Postgres.If the database user does not already exist, create it.

        [root root]# su - postgres
        [postgres ~]$ createuser $OPENACS_SERVICE_NAME
        
        Shall the new user be allowed to create databases? (y/n) y
        Shall the new user be allowed to create more new users? (y/n) y
        CREATE USER
        [postgres ~]$ exit
        

        Because of a bug in Postgres backup-recovery, database objects are not guaranteed to be created in the right order. In practice, running the OpenACS initialization script is always sufficient to create any out-of-order database objects. Next, restore the database from the dump file. The restoration will show some error messages at the beginning for objects that were pre-created from the OpenACS initialization script, which can be ignored.

        [root root]# su - $OPENACS_SERVICE_NAME
        
        [$OPENACS_SERVICE_NAME ~]$ createdb $OPENACS_SERVICE_NAME
        
        CREATE DATABASE
        [$OPENACS_SERVICE_NAME ~]$ psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/postgresql.sql $OPENACS_SERVICE_NAME
        (many lines omitted)
        [$OPENACS_SERVICE_NAME ~]$ psql $OPENACS_SERVICE_NAME < /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/database-backup.dmp
        (many lines omitted)
        [$OPENACS_SERVICE_NAME ~]$ exit
        [postgres ~]$ exit
        logout
    4. Activate the service

      [root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools /service/$OPENACS_SERVICE_NAME
      
      [root root]# sleep 10
      [root root]# svgroup web /service/$OPENACS_SERVICE_NAME
      
      

Administrator's Guide

Created by Gustaf Neumann, last modified by Gustaf Neumann 01 Jun 2017, at 08:46 AM

Table of Contents

2. Installation Overview
Basic Steps
Prerequisite Software
3. Complete Installation
Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 4
Install OpenACS 5.2.3rc1
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X
4. Configuring a new OpenACS Site
Installing OpenACS packages
Mounting OpenACS packages
Configuring an OpenACS package
Setting Permissions on an OpenACS package
How Do I?
5. Upgrading
Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading the OpenACS files
Upgrading Platform components
6. Production Environments
Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support for an OpenACS service
Set up Log Analysis Reports
External uptime validation
Diagnosing Performance Problems
7. Database Management
Running a PostgreSQL database on another server
Deleting a tablespace
Vacuum Postgres nightly
8. Backup and Recovery
Backup Strategy
Manual backup and recovery
Automated Backup
Using CVS for backup-recovery
A. Install Red Hat 8/9
B. Install additional supporting software
Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1
C. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources

Upgrading

Created by Gustaf Neumann, last modified by Gustaf Neumann 01 Jun 2017, at 08:37 AM

OpenACS 4.6.2 Release Notes

Created by Gustaf Neumann, last modified by Gustaf Neumann 01 Jun 2017, at 08:33 AM

by Don Baccus
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff.

This is a final release of OpenACS 4.6.2. This release has been subjected to an organized test effort, but please bear in mind that we are still in the process of developing testing tools, methodology, and scripts.

Please report bugs using our Bug Tracker at the OpenACS website. This version of the OpenACS Toolkit supports PostgreSQL 7.2.3 and 7.3.2, and Oracle 8i. It will not work with Oracle 9i (support is planned for OpenACS 4.7.)

Upgrading from OpenACS 4.6.1

OpenACS 4.6.2 includes key datamodel changes to acs-kernel and other packages. Your first step after downloading OpenACS 4.6.2 and restarting AOLserver should be to visit the Package Manager, click on the "install packages" link, and select the checkbox to upgrade acs-kernel. After acs-kernel has been upgraded, return to the "install packages" page and select the checkboxes for all other packages you have installed that need upgrading (they are marked "upgrade" rather than "new install") and perform the upgrade step.

After packages have been upgraded, your installation should run without problems.

You may want to begin by reading our installation documentation for Chapter 3. Note that the Windows documentation is not current for OpenACS 4.6.2, but an alternative is to use John Sequeira's Oasis VM project.

After installation, the full documentation set can be found by visiting http://[your-host]/doc. Not all pieces are updated for OpenACS 4.6.2 at this moment.

If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want to uncomment the SQL that causes InterMedia to keep online searching online while indexing. The feature doesn't exist in Standard Edition and OpenACS 4.6.2 now defaults to being loadable in SE. Just grep for 'sync' to find the code.

Also be sure to read the documentation in the Site Wide Search package's sql/oracle directory. The APM doesn't execute the SQL for this package, in part due to the fact that some steps need to be run as the Oracle user 'ctxsys'.

If you're using PostgreSQL be sure to read the documentation on installing the Open FTS driver for OpenACS. It's included in the package as a text file and is also summarized at the end of the installation documentation in the section, 4. As with the Oracle version, there are steps you must take manually in order to get this feature working.

OpenMSG has organized the OpenACS 4.6.2 testing process with test servers provided by Hub.org. Visit the acceptance test server to see the current status of various packages. This may not be a permanent link. If it's not working, do a search of the OpenACS forums.

 

Complex Install OpenACS 5.3

Created by Gustaf Neumann, last modified by Gustaf Neumann 03 Mar 2017, at 08:49 AM

by Vinod Kurup

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

AOLserver needs to be started as the root user if you want to use port 80. Once it starts, though, it will drop the root privileges and run as another user, which you must specify on the command line. It's important that this user has as few privileges as possible. Why? Because if an intruder somehow breaks in through AOLserver, you don't want her to have any ability to do damage to the rest of your server.

At the same time, AOLserver needs to have write access to some files on your system in order for OpenACS to function properly. So, we'll run AOLserver with a different user account for each different service. A service name should be a single word, letters and numbers only. If the name of your site is one word, that would be a good choice. For example "$OPENACS_SERVICE_NAME" might be the service name for the $OPENACS_SERVICE_NAME.net community.

We'll leave the password blank, which prevents login by password, for increased security. The only way to log in will be with ssh certificates. The only people who should log in are developers for that specific instance. Add this user, and put it in the $OPENACS_SERVICE_NAME group so that it can use database and server commands associated with that group. (If you don't know how to do this, type man usermod. You can type groups to find out which groups a user is a part of)

[root root]# useradd $OPENACS_SERVICE_NAME

You also need to set up a group called web.

[root root]# groupadd web

Then change the user to be a part of this group:

[root root]# usermod -g web $OPENACS_SERVICE_NAME

FreeBSD creates the user this way:

[root root]# mkdir -p /home/$OPENACS_SERVICE_NAME

[root root]# pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash
[root root]#
mkdir -p /home/$OPENACS_SERVICE_NAME
pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash

For Linux Standard Base compliance and ease of backup, all of the files in each OpenACS site are stored in a subdirectory of /var/lib/aolserver, one subdirectory per site. The first time you install an OpenACS site on a server, you must create the parent directory and set its permissions:

[root root]# mkdir /var/lib/aolserver
[root root]# chgrp web /var/lib/aolserver
[root root]# chmod 770 /var/lib/aolserver
[root root]#
mkdir /var/lib/aolserver
chgrp web /var/lib/aolserver
chmod 770 /var/lib/aolserver

A bash script is available to automate all of the steps for the rest of this section. It requires tclwebtest. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a manual installation.

Get the install script from CVS. It is located within the main cvs tree, at /etc/install. Use anonymous CVS checkout to get that directory in the home directory of the service's dedicated user. We put it there so that it is not overwritten when we do the main CVS checkout to the target location.

[root root]# su - $OPENACS_SERVICE_NAME

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install
cvs server: Updating install
U install/README
U install/TODO
  ... many lines omitted ...
U install/tcl/twt-procs.tcl
U install/tcl/user-procs.tcl
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd install
[$OPENACS_SERVICE_NAME install]$ emacs install.tcl

Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file. If your system is different from the one described in the previous sections, check the file paths as well. Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.

Run the install script install.sh as root:

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit 
[root root]# sh /home/$OPENACS_SERVICE_NAME/install/install.sh
/home/$OPENACS_SERVICE_NAME/install/install.sh: Starting installation with config_file 
/home/$OPENACS_SERVICE_NAME/install/install.tcl. Using serverroot=/var/lib/aolserver/
$OPENACS_SERVICE_NAME, server_url=http://0.0.0.0:8000, do_checkout=yes, do_install=yes, 
dotlrn=no, and database=postgres., use_daemontools=true
  ... many lines omitted ...
Tue Jan 27 11:50:59 CET 2004: Finished (re)installing /var/lib/aolserver/$OPENACS_SERVICE_NAME.
######################################################################
  New site URL: http://127.0.0.1:8000
admin email   : admin@yourserver.net
admin password: xxxx
######################################################################
[root root]#

You can proceed to the section called “Next Steps”.

You should already have downloaded the OpenACS tarball to the /var/tmp directory. If not, download the OpenACS tarball and save it in /var/tmp and proceed:

  1. Unpack the OpenACS tarball and rename it to $OPENACS_SERVICE_NAME. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.

    FreeBSD note: Change the period in chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME to a colon: chown -R $OPENACS_SERVICE_NAME:$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME

    [root root]# su - $OPENACS_SERVICE_NAME
    
    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver
    [$OPENACS_SERVICE_NAME aolserver]$ tar xzf /var/tmp/openacs-5.2.3rc1.tgz
    [$OPENACS_SERVICE_NAME aolserver]$ mv openacs-5.2.3rc1 $OPENACS_SERVICE_NAME
    
    [$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME
    
    [$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME$OPENACS_SERVICE_NAME
    
    [$OPENACS_SERVICE_NAME aolserver]$ ls -al
    total 3
    drwxrwx---    3 root     web          1024 Mar 29 16:41 .
    drwxr-xr-x   25 root     root         1024 Mar 29 16:24 ..
    drwx------    7 $OPENACS_SERVICE_NAME web          1024 Jan  6 14:36 $OPENACS_SERVICE_NAME
    [$OPENACS_SERVICE_NAME aolserver]$ exit
    logout
    [root root]#
    su - $OPENACS_SERVICE_NAME
    cd /var/lib/aolserver
    tar xzf /var/tmp/openacs-5.2.3rc1.tgz
    mv openacs-5.2.3rc1 $OPENACS_SERVICE_NAME
    chmod -R 755 $OPENACS_SERVICE_NAME
    chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME
    exit
    
  2. Add the Service to CVS (OPTIONAL)

  3. Prepare the database

    • Prepare Oracle for OpenACS.If you won't be using Oracle, skip to Prepare PostgreSQL for an OpenACS Service

      You should be sure that your user account (e.g. $OPENACS_SERVICE_NAME) is in the dba group.

      1. Verify membership by typing groups when you login:

        [$OPENACS_SERVICE_NAME ~]$ groups
        dba web

        If you do not see these groups, take the following action:

        [$OPENACS_SERVICE_NAME ~]$ su -
        Password: ************
        [root ~]# adduser $OPENACS_SERVICE_NAME dba
        

        If you get an error about an undefined group, then add that group manually:

        [root ~]# groupadd dba
        [root ~]# groupadd web
        

        Make sure to logout as root when you are finished with this step and log back in as your regular user.

      2. Connect to Oracle using svrmgrl and login:

        [$OPENACS_SERVICE_NAME ~]$ svrmgrl
        SVRMGR> connect internal
        Connected.

      3. Determine where the system tablespaces are stored:

        SVRMGR> select file_name from dba_data_files;
        

        Example results:

        /ora8/m01/app/oracle/oradata/ora8/system01.dbf
        /ora8/m01/app/oracle/oradata/ora8/tools01.dbf
        /ora8/m01/app/oracle/oradata/ora8/rbs01.dbf
        /ora8/m01/app/oracle/oradata/ora8/temp01.dbf
        /ora8/m01/app/oracle/oradata/ora8/users01.dbf
        /ora8/m01/app/oracle/oradata/ora8/indx01.dbf
        /ora8/m01/app/oracle/oradata/ora8/drsys01.dbf

      4. Using the above output, you should determine where to store your tablespace. As a general rule, you'll want to store your tablespace on a mount point under the /ora8 directory that is separate from the Oracle system data files. By default, the Oracle system is on m01, so we will use m02. This enables your Oracle system and database files to be on separate disks for optimized performance. For more information on such a configuration, see Chapter 12 of Philip's book. For this example, we'll use /ora8/m02/oradata/ora8/.

      5. Create the directory for the datafile; to do this, exit from svrmgrl and login as root for this step:

        SVRMGR> exit
        [$OPENACS_SERVICE_NAME ~]$ su -
        Password: ************
        [root ~]# mkdir -p /ora8/m02/oradata/ora8/
        [root ~]# chown $OPENACS_SERVICE_NAME:web /ora8/m02/oradata/ora8
        [root ~]# chmod 775 /ora8/m02/oradata/ora8
        [root ~]# exit
        [$OPENACS_SERVICE_NAME ~]$
      6. Create a tablespace for the service. It is important that the tablespace can autoextend. This allows the tablespace's storage capacity to grow as the size of the data grows. We set the pctincrease to be a very low value so that our extents won't grow geometrically. We do not set it to 0 at the tablespace level because this would affect Oracle's ability to automatically coalesce free space in the tablespace.

        [$OPENACS_SERVICE_NAME ~]$ svrmgrl
        SVRMGR> connect internal;
        SVRMGR> create tablespace $OPENACS_SERVICE_NAME
              datafile '/ora8/m02/oradata/ora8/$OPENACS_SERVICE_NAME01.dbf' 
              size 50M 
              autoextend on 
              next 10M
              maxsize 300M
              extent management local
              uniform size 32K;
        
      7. Create a database user for this service. Give the user access to the tablespace and rights to connect. We'll use $OPENACS_SERVICE_NAMEpassword as our password.

        Write down what you specify as service_name (i.e. $OPENACS_SERVICE_NAME) and database_password (i.e. $OPENACS_SERVICE_NAMEpassword). You will need this information for configuring exports and AOLserver.

        SVRMGR> create user $OPENACS_SERVICE_NAME identified by $OPENACS_SERVICE_NAMEpassword default tablespace $OPENACS_SERVICE_NAME
            temporary tablespace temp quota unlimited on $OPENACS_SERVICE_NAME;
        SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to $OPENACS_SERVICE_NAME;
        SVRMGR> revoke unlimited tablespace from $OPENACS_SERVICE_NAME;
        SVRMGR> alter user $OPENACS_SERVICE_NAME quota unlimited on $OPENACS_SERVICE_NAME;
        SVRMGR> exit;
        

        Your table space is now ready. In case you are trying to delete a previous OpenACS installation, consult these commands in the section called “Deleting a tablespace” below.

      8. Make sure that you can login to Oracle using your service_name account:

        [$OPENACS_SERVICE_NAME ~]$ sqlplus $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAMEpassword
        
        SQL> select sysdate from dual;
        SYSDATE
        ----------
        2001-12-20
        SQL> exit;
        

        You should see today's date in a format 'YYYY-MM-DD.' If you can't login, try redoing step 1 again. If the date is in the wrong format, make sure you followed the steps outlined in the section called “Troubleshooting Oracle Dates”

    • Prepare PostgreSQL for an OpenACS Service.

      • PostgreSQL:

        Create a user in the database matching the service name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the openacs system accounts on a machine has full access to all postgresql databases on that machine.

        [root root]# su - postgres
        [postgres pgsql]$ createuser -a -d $OPENACS_SERVICE_NAME
        
        CREATE USER
        [postgres pgsql]$ exit
        logout
        [root root]#
      • Create a database with the same name as our service name, $OPENACS_SERVICE_NAME. The full pathname for createdb needs to be used, since the pgsql directory has not been added to the $OPENACS_SERVICE_NAME bash profile.

        [root root]# su - $OPENACS_SERVICE_NAME
        
        [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/createdb -E UNICODE $OPENACS_SERVICE_NAME
        
        CREATE DATABASE
        [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
        su - $OPENACS_SERVICE_NAME
        /usr/local/pgsql/bin/createdb -E UNICODE $OPENACS_SERVICE_NAME
        
        
      • Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day.

        [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ export EDITOR=emacs;crontab -e
        

        Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information.

        0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze $OPENACS_SERVICE_NAME
        0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze $OPENACS_SERVICE_NAME
        

        Depending on your distribution, you may receive email when the crontab items are executed. If you don't want to receive email for those crontab items, you can add > /dev/null 2>&1 to the end of each crontab line

      • Add Full Text Search Support (OPTIONAL)

      • At this point the database should be ready for installing OpenACS.

  4. Configure an AOLserver Service for OpenACS.

    1. The AOLserver architecture lets you run an arbitrary number of virtual servers. A virtual server is an HTTP service running on a specific port, e.g. port 80. In order for OpenACS to work, you need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl. Open it in an editor to adjust the parameters.

      [root root]# su - $OPENACS_SERVICE_NAME
      
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc
      [$OPENACS_SERVICE_NAME etc]$ emacs config.tcl
      

      You can continue without changing any values in the file. However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines.

      • httpport - If you want your server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.

      • httpsport - This is the port for https requests. The Reference Platform https port is 8443. If http port is set to 80, httpsport should be 443 to match the standard.

      • address - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses.

      • server - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses $OPENACS_SERVICE_NAME.

      • db_name - In almost all cases, this can be kept as a reference to $server. If for some reason, the tablespace you are using is different than your servername, then you can set it here. You should have a good reason for doing this.

      • servername - This is just a *pretty* name for your server.

      • user_account - The account that will both own OpenACS files and connect to the database (for Postgresql).

      • debug - Set to true for a very verbose error log, including many lines for every page view, success or failure.

    2. AOLserver is very configurable. These settings should get you started, but for more options, read the AOLserver docs.

    3. Enable OpenFTS Full Text Search (OPTIONAL)

    4. Install nsopenssl for SSL support. (OPTIONAL)

  5. Verify AOLserver startup.

    1. Kill any current running AOLserver processes and start a new one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run.

      If you want to use port 80, there are complications. AOLserver must be root to use system ports such as 80, but refuses to run as root for security reasons. So, we call the run script as root and specify a non-root user ID and Group ID which AOLserver will switch to after claiming the port. To do so, find the UID and GID of the $OPENACS_SERVICE_NAME user via grep $OPENACS_SERVICE_NAME /etc/passwd and then put those numbers into the command line via -u 501 -g 502 . In AOLserver 4, you must also send a -b flag. Do this by editing the run file as indicated in the comments.

      If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep nsd and selectively kill by job number.

      [$OPENACS_SERVICE_NAME etc]$ killall nsd
      nsd: no process killed
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file...
      [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.
    2. Attempt to connect to the service from a web browser. You should specify a URL like: http://yourserver.test:8000

      You should see a page that looks like this. If you imported your files into cvs, now that you know it worked you can erase the temp directory with rm -rf /var/lib/aolserver/$OPENACS_SERVICE_NAME.orig.

      If you don't see the login page, view your error log (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log) to make sure the service is starting without any problems. The most common errors here are trying to start a port 80 server while not root, failing to connect because of a firewall, and aolserver failing to start due to permissions errors or missing files. If you need to make changes, don't forget to kill any running servers with killall nsd.

    3. Automate AOLserver keepalive (OPTIONAL)

  6. Configure a Service with the OpenACS Installer. Now that you've got AOLserver up and running, let's install OpenACS 5.2.3rc1.

    • You should see a page from the webserver titled OpenACS Installation: Welcome. You will be warned if your version of the database driver is out of date, if AOLserver cannot connect to the database, if any modules are missing or out-of-date, or if there are any problems with filesystem permissions on the server side. But if everything is fine, you can click Next to proceed to load the OpenACS Kernel data model.

    • The next page shows the results of loading the OpenACS Kernel data model - be prepared to wait a few minutes as it works. You should see a string of output messages from the database as the datamodel is created. You'll see the line:

      Loading package .info files ... this will take a few minutes

      This will really take a few minutes. Have faith! Finally, another Next button will appear at the bottom - click it.

    • The following page shows the results of loading the core package data models. You should see positive results for each of the previously selected packages, but watch out for any errors. Eventually, the page will display "Generating secret tokens" and then "Done"- click Next.

    • You should see a page, "OpenACS Installation: Create Administrator" with form fields to define the OpenACS site administrator. Fill out the fields as appropriate, and click Create User.

    • You should see a page, "OpenACS Installation: Set System Information" allowing you to name your service. Fill out the fields as appropriate, and click Set System Information

    • You'll see the final Installer page, "OpenACS Installation: Complete." It will tell you that the server is being restarted; note that unless you already set up a way for AOLserver to restart itself (ie. inittab or daemontools), you'll need to manually restart your service.

      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/config.tcl
      
    • Give the server a few minutes to start up. Then reload the final page above. You should see the front page, with an area to login near the upper right. Congratulations, OpenACS 5.2.3rc1 is now up and running!

If you want to track fresh code developments inbetween releases, or you are an OpenACS core developer, you may want to install from CVS. This is identical to Option 2 except that you get the files from CVS instead of the tarball: CVS Checkout Instructions. So, instead of tar xzf /var/tmp/openacs-5.2.3rc1.tgz, cvs -z3 -d :pserver:anonymous@openacs.org:/cvsroot co acs-core.

  • Use daemontools supervise and svc, or inittab, to automate server startup and shutdown.

  • Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled OpenFTS, you can now install the OpenFTS Driver package and Full Text Search Engine package in the OpenACS service.

  • This is a good time to make a backup of your service. If this is a production site, you should set up automatic nightly backups.

  • If you want traffic reports, set up analog or another log processing program.

  • Follow the instruction on the home page to change the appearance of your service or add more packages. (more information)

  • Proceed to the tutorial to learn how to develop your own packages.

  • Set up database environment variables for the site user. Depending on how you installed Oracle or PostGreSQL, these settings may be necessary for working with the database while logged in as the service user. They do not directly affect the service's run-time connection with the database, because those environmental variables are set by the wrapper scripts nsd-postgres and nsd-oracle.

    [root root]# su - $OPENACS_SERVICE_NAME
    
    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrc
    

    Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.

    • PostgreSQL:

      export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
      export PATH=$PATH:/usr/local/pgsql/bin
    • Oracle. These environment variables are specific for a local Oracle installation communicating via IPC. If you are connecting to a remote Oracle installation, you'll need to adjust these appropriately. Also, make sure that the '8.1.7' matches your Oracle version.

      export ORACLE_BASE=/ora8/m01/app/oracle
      export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
      export PATH=$PATH:$ORACLE_HOME/bin
      export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
      export ORACLE_SID=ora8
      export ORACLE_TERM=vt100
      export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data

    Test this by logging out and back in as $OPENACS_SERVICE_NAME and checking the paths.

    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
    logout
    [root src]# su - $OPENACS_SERVICE_NAME
    
    [$OPENACS_SERVICE_NAME ~]$ env
    
    • For PostgreSQL, you should see:

      LD_LIBRARY_PATH=:/usr/local/pgsql/lib
      PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:\
        /root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin
    • For Oracle:

      ORACLE_BASE=/ora8/m01/app/oracle
      ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7
      PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:\
        /root/bin:/ora8/m01/app/oracle/product/8.1.7/bin
      LD_LIBRARY_PATH=/ora8/m01/app/oracle/product/8.1.7/lib:/lib:/usr/lib
      ORACLE_SID=ora8
      ORACLE_TERM=vt100
      ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
  • Test your backup and recovery procedure.

  • Set up the section called “External uptime validation”.

Basic String Operations

Created by Hal Abelson, Philip Greenspun, and Lydia Sandon, last modified by Gustaf Neumann 03 Mar 2017, at 08:42 AM

If your program receives data from a Web client, it comes in as a string. If your program sends an HTML page back to a Web client, it goes out as a string. This puts the string data type at the heart of Web page development:
set whole_page "some stuff for the top of the page\n\n"
append whole_page "some stuff for the middle of the page\n\n"
append whole_page "some stuff for the bottom of the page\n\n"
# done composing the page, let's write it back to the user
ns_return 200 text/html $whole_page
If you're processing data from the user, typically entered into an HTML form, you'll be using a rich variety of built-in string-handling procedures. Suppose that a user is registering at your site with the form variables first_names, last_name, email, password. Here's how we might build up a list of exceptions (using the Tcl lappend command, described in the chapter on lists):
# compare the first_names value to the empty string
if { [string compare $first_names ""] == 0 } {
    lappend exception_list "You forgot to type your first name"
}

# see if their email address has the form
#   something at-sign something
if { ![regexp {.+@.+} $email] } {
    lappend exception_list "Your email address doesn't look valid."
}

if { [string length $password] > 20 } {
    lappend exception_list "The password you selected is too long."
}
If there aren't any exceptions, we have to get these data ready for insertion into the database:
# remove whitespace from ends of input (if any)
set last_name_trimmed [string trim $last_name]

# escape any single quotes with an extra one (since the SQL
# string literal quoting system uses single quotes)
regsub -all ' $last_name_trimmed '' last_name_final

set sql_insert "insert into users (..., last_name, ...) 
values 
(..., '$last_name_final', ...)"

Looking for stuff in a string

The simplest way to look for a substring within a string is with the string first command. Some users of photo.net complained that they didn't like seeing classified ads that were simply pointers to the eBay auction site. Here's a simplified snippet from http://software.arsdigita.com/www/gc/place-ad-3.tcl:

if { [string first "ebay" [string tolower $full_ad]] != -1 } {
    # return an exception
    ...
}
an alternative formulation would be
if { [regexp -nocase {ebay} $full_ad] } {
    # return an exception
    ...
}
Both implementations will catch any capitalization variant of "eBAY". Both implementations will miss "e-bay" but it doesn't matter because if the poster of the ad includes a link with a URL, the hyperlink will contain "ebay". What about false positives? If you visit www.m-w.com and search for "*ebay*" you'll find that both implementations might bite someone selling rhododendrons or a water-powered mill. That's why the toolkit code checks a "DisalloweBay" parameter, set by the publisher, before declaring this an exception.

If you're just trying to find a substring, you can use either string first or regexp. If you're trying to do something more subtle, you'll need regexp (described more fully in the chapter "Pattern Matching"):

if { ![regexp {[a-z]} $full_ad] } {
    # no lowercase letters in the ad!
    append exception_text "
      
      
            
      
  • Your ad appears to be all uppercase. ON THE INTERNET THIS IS CONSIDERED SHOUTING. IT IS ALSO MUCH HARDER TO READ THAN MIXED CASE TEXT. So we don't allow it, out of decorum and consideration for people who may be visually impaired." incr exception_count }
  • Using only part of a string 

    In the ArsDigita Community System, we have a page that shows a user's complete history with a Web service, e.g., http://photo.net/shared/community-member.tcl?user_id=23069 shows all of the postings by Philip Greenspun. If a comment on a static page is short, we want to show the entire message. If not, we want to show just the first 1000 characters.

    In http://software.arsdigita.com/www/shared/community-member.tcl, we find the following use of the string range command:

    if { [string length $message] > 1000 } {
        set complete_message "[string range $message 0 1000]... "
    } else {
        set complete_message $message
    }
    

    Fortran-style formatting and reading of numbers 

    The Tcl commands format and scan resemble C's printf and scanf commands. That's pretty much all that any Tcl manual will tell you about these commands, which means that you're kind of S.O.L. if you don't know C. The basic idea of these commands comes from Fortran, a computer language developed by John Backus at IBM in 1954. The FORMAT command in Fortran would let you control the printed display of a number, including such aspects as spaces of padding to the left and digits of precision after the decimal point.

    With Tcl format, the first argument is a pattern for how you'd like the final output to look. Inside the pattern are placeholders for values. The second through Nth arguments to format are the values themselves:

    format pattern value1 value2 value3 .. valueN
    
    We can never figure out how to use format without either copying an earlier fragment of pattern or referring to the man page (http://www.tcl.tk/man/tcl8.4/TclCmd/format.htm). However, here are some examples for you to copy:
    % # format prices with two digits after the point
    % format "Price:  %0.2f" 17
    Price:  17.00
    % # pad some stuff out to fill 20 spaces
    % format "%20s" "a long thing"
            a long thing
    % format "%20s" "23"
                      23
    % # notice that the 20 spaces is a MINIMUM; use string range
    % # if you might need to truncate
    % format "%20s" "something way longer than 20 spaces"
    something way longer than 20 spaces
    % # turn a number into an ASCII character
    % format "%c" 65
    A
    
    The Tcl command scan performs the reverse operation, i.e., parses an input string according to a pattern and stuffs values as it finds them into variables:
    % # turn an ASCII character into a number
    % scan "A" "%c" the_ascii_value
    1
    % set the_ascii_value
    65
    % 
    
    Notice that the number returned by scan is a count of how many conversions it was able to perform successfully. If you really want to use scan, you'll need to visit the man page: http://www.tcl.tk/man/tcl8.4/TclCmd/scan.htm. For an idea of how useful this is for Web development, consider that the entire 250,000-line ArsDigita Community System does not contain a single use of the scan command.


    Reference: String operations

      A.) Commands that don't start with string

    • append variable_name value1 value2 value3 ... valueN
      sets the variable defined by variable_name to the concatenation of the old value and all the remaining arguments (http://www.tcl.tk/man/tcl8.4/TclCmd/append.htm)
    • regexp ?switches? expression string ?matchVar? ?subMatchVar subMatchVar ...?
      Returns 1 if expression matches string; 0 otherwise. If successful, regexp sets the match variables to the parts of string that matches the corresponding parts of expression.
      % set fraction "5/6"
      5/6
      % regexp {(.*)/(.*)} $fraction match num denom
      1
      % set match
      5/6
      % set num
      5
      % set denom
      6
      
      (more: the pattern matching chapter and http://www.tcl.tk/man/tcl8.4/TclCmd/regexp.htm)
    • regsub ?switches? expression string substitution_spec result_variable_name
      Returns a count of the number of matching items that were found and replaced. Primarily called for its effect in setting result_variable_name.

      Here's an example where we ask a user to type in keywords, separated by commands. We then expect to feed this list to a full-text search indexer that will throw an error if handed two commas in a row. We use regsub to clean up what the user typed:

      # here we destructively modify the variable $query_string'
      # replacing every occurrence of one or more commas with a single
      # command 
      % set query_string "samoyed,, sledding, harness"
      samoyed,, sledding, harness
      % regsub -all {,+} $query_string "," query_string
      2
      % set query_string
      samoyed, sledding, harness
      
      (more: the pattern matching chapter and http://www.tcl.tk/man/tcl8.4/TclCmd/regsub.htm)

      were dramatically improved with the Tcl 8.1 release. For a Web developer the most important feature is the inclusion of non-greedy regular expressions. This makes it easy to match the contents of HTML tags. See http://www.scriptics.com/services/support/howto/regexp81.html for a full discussion of the differences.

      B.) Commands that start with string

      (all of which are documented at http://www.tcl.tk/man/tcl8.4/TclCmd/string.htm)


    • string compare string1 string2
      returns 0 if the two strings are equal, -1 if string1 sorts lexicographically before string2, 1 if string2 sorts lexicographically before string1:
      string compare apple applesauce  ==> -1
      string compare apple Apple ==> 1
      
    • string first string1 string2
      returns -1 if string1 is not within string2, else returns the index of the first occurrence. Indices start from zero, e.g.,
      string first tcl catclaw  ==> 2
      
    • string last string1 string2
      -1 if string1 is not within string2, else index of last occurrence.
      string last abra abracadabra ==> 7
      
    • string match pattern string
      1 if string matches pattern, 0 if not. See the chapter on pattern matching for an explanation of patterns.
    • string range string i j
      range of characters in string from index i to j, inclusive.
      string range catclaw 2 4 ==> tcl
      
    • string tolower string
      string in lower case.
      string compare weBmaster Webmaster => 1
      
      string compare [string tolower weBmaster] \
                     [string tolower Webmaster] => 0
      
    • string toupper string
      string in upper case.
      set password "ferrari"
      string compare "FERRARI" [string toupper $password] ==> 0
      
    • string trim string ?chars?
      trims chars from right and left side of string; defaults to whitespace.
      set password [string trim $form_password] ; # see above example
      
    • string trimleft string ?chars?
      trims chars from left of string; defaults to whitespace.
      set password [string trimleft $form_password] 
      
    • string trimright string ?chars?
      trims chars from right of string; defaults to whitespace.
      set password [string trimright $form_password] 
      
    • string wordend string index
      index of the first character after the last character of the word containing index.
      string wordend "tcl is the greatest" 0 ==>3
      
    • string wordstart string index
      index of the first char of the word containing index.
      string wordstart "tcl is the greatest" 5 ==> 4
      



    Exercises ( see section V.3  List Operations )

    ---

    based on Tcl for Web Nerds 


    OpenACS Installation Guide for Windows2000

    Created by Gustaf Neumann, last modified by Gustaf Neumann 06 Jan 2017, at 10:09 AM

    A binary version of OpenACS and NaviServer is maintained by Maurizio Martignano and is available from Spazio IT

    ACS File Naming and Formatting Standards

    Created by Gustaf Neumann, last modified by Gustaf Neumann 17 Dec 2016, at 10:29 AM

    By Michael Yoon and Aurelius Prochazka

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas:

    Usually we organize our files so that they mainly serve one of the following three purposes:

    • displaying objects and their properties

    • manipulating or acting on objects in some way (by creating, editing, linking, etc)

    • housing procedures, packages, data models and other prerequisite code Essentially, we want our files named in a fashion that reflects their purpose.

    Under the page root:

    • For naming files that enable a specific action on an object, use this format:

      object-verb.extension

      For example, the page to erase a user's portrait from the database is /admin/users/portrait-erase.tcl.

    • However, modules typically deal with only one primary type of object - e.g., the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages for the Bookmarks module live in the /bookmarks/ directory, and so there is no need to name the bookmark editing page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention:

      verb.extension

      Thus, the page to edit a bookmark is /bookmarks/edit.tcl.

    • For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:

      one.extension

      For example, the page to view one bookmark is /bookmarks/one.tcl. Note that no verb is necessary for display-type files.

    • Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:

      object.extension

      For example, the page to view the properties of an ecommerce product is /ecommerce/product.tcl.

    • For naming files in a page flow, use the convention:

      • foobar.extension (Step 1)

      • foobar-2.extension (Step 2)

      • ...

      • foobar-N.extension (Step N)

      where foobar is determined by the above rules.

      Typically, we use a three-step page flow when taking user information:

      1. Present a form to the user

      2. Present a confirmation page to the user

      3. Perform the database transaction, then redirect

    • Put data model files in /www/doc/sql, and name them for the modules towards which they are used:

      module.sql

    In the Tcl library directory:

    • For files that contain module-specific procedures, use the convention:

      module-procs.tcl

    • For files that contain procedures that are part of the core ACS, use the convention:

      ad-description-procs.tcl

    File names also appear within pages, as linked URLs and form targets. When they do, always use abstract URLs (e.g., user-delete instead of user-delete.tcl), because they enhance maintainability.

    Similarly, when linking to the index page of a directory, do not explicitly name the index file (index.tcl, index.adp, index.html, etc.). Instead, use just the directory name, for both relative links (subdir/) and absolute links (/top-level-dir/). If linking to the directory in which the page is located, use the empty string (""), which browsers will resolve correctly.

    Include the appropriate standard header in all scripts. The first line should be a comment specifying the file path relative to the ACS root directory. e.g.

    # /www/index.tcl

    or

    # /tcl/module-defs.tcl

    For static content files (html or adp), include a CVS identification tag as a comment at the top of the file, e.g.

    <!-- file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp -->
    

    In addition, all static HTML files, documentation and other pages should have a visible CVS ID stamp, at least during development. These can be removed at release times. This should take the form of a line like this:

    <p>
    Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp
    </p>
    

    This can be at the top or bottom of the file.

    Using ad_page_contract

    For non-library Tcl files (those not in the private Tcl directory), use ad_page_contract after the file path comment (this supersedes set_the_usual_form_variables and ad_return_complaint). Here is an example of using ad_page_contract, which serves both documentation and page input validation purposes:

    # www/register/user-login-2.tcl
    
    ad_page_contract {
        Verify the user's password and issue the cookie.
    
        @param user_id The user's id in users table.
        @param password_from_from The password the user entered.
        @param return_url What url to return to after successful login.
        @param persistent_cookie_p Specifies whether a cookie should be set to keep the user logged in forever.
        @author John Doe (jdoe@example.com)
        @cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp
    } {
        user_id:integer,notnull
        password_from_form:notnull
        {return_url {[ad_pvt_home]}}
        {persistent_cookie_p f}
    }
    

    Salient features of ad_page_contract:

    • A mandatory documentation string is the first argument. This has the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations.

    • The second argument specifies the page inputs. The syntax for switches/flags (e.g. multiple-list, array, etc.) uses a colon (:) followed by any number of flags separated by commas (,), e.g. foo:integer,multiple,trim. In particular, multiple and array are the flags that correspond to the old ad_page_variables flags.

    • There are new flags: trim, notnull and optional. They do what you'd expect; values will not be trimmed, unless you mark them for it; empty strings are valid input, unless you specify notnull; and a specified variable will be considered required, unless you declare it optional.

    • ad_page_contract can do validation for you: the flags integer and sql_identifier will make sure that the values supplied are integers/sql_identifiers. The integer flag will also trim leading zeros. Note that unless you specify notnull, both will accept the empty string.

    • Note that ad_page_contract does not generate QQvariables, which were automatically created by ad_page_variables and set_the_usual_form_variables. The use of bind variables makes such previous variable syntax obsolete.

    Using ad_library

    For shared Tcl library files, use ad_library after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like ad_page_contract. Don't forget to put the @cvs-id in there. Here is an example of using ad_library:

    # tcl/wp-defs.tcl
    
    ad_library {
        Provides helper routines for the Wimpy Point module.
    
        @author John Doe (jdoe@example.com)
        @cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp
    }
    
    Non-Tcl Files

    For SQL and other non-Tcl source files, the following file header structure is recommended:

    -- path relative to the ACS root directory
    --
    -- brief description of the file's purpose
    --
    -- author
    -- created
    --
    -- $Id: eng-standards-filenaming.html,v 1.41 2006/07/17 05:38:31 torbenb Exp $
    

    Of course, replace "--" with the comment delimiter appropriate for the language in which you are programming.

    Construct the page as one Tcl variable (name it page_content), and then send it back to the browser with one call to doc_return, which will call db_release_unused_handles prior to executing ns_return, effectively combining the two operations.

    For example:

    set page_content "[ad_header "Page Title"]
    
    <h2>Page Title</h2>
    
    <hr>
    
    <ul>
    "
    
    db_foreach get_row_info {
        select row_information
        from bar
    } {
        append page_content "<li>row_information\n"
    }
    
    append page_content "</ul>
    
    [ad_footer]"
    
    doc_return 200 text/html $page_content
    

    The old convention was to call ReturnHeaders and then ns_write for each distinct chunk of the page. This approach has the disadvantage of tying up a scarce and valuable resource (namely, a database handle) for an unpredictable amount of time while sending packets back to the browser, and so it should be avoided in most cases. (On the other hand, for a page that requires an expensive database query, it's better to call ad_return_top_of_page first, so that the user is not left to stare at an empty page while the query is running.)

    Local procedures (i.e., procedures defined and used only within one page) should be prefixed with "module_" and should be used rarely, only when they are exceedingly useful.

    All files that prepare HTML to display should end with [ad_footer] or [module_footer]. If your module requires its own footer, this footer should call ad_footer within it. Why? Because when we adapt the ACS to a new site, it is often the case that the client will want a much fancier display than the ACS standard. We like to be able to edit ad_header (which quite possibly can start a <table>) and ad_footer (which may need to end the table started in ad_footer) to customize the look and feel of the entire site.

    Further standards for Tcl library files are under discussion; we plan to include naming conventions for procs.

    Install Oracle 8.1.7

    Created by Gustaf Neumann, last modified by Gustaf Neumann 05 Dec 2016, at 08:09 AM

    By Vinod Kurup

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    If you are installing PostGreSQL instead of Oracle, skip this section.

    OpenACS 5.2.3rc1 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See Andrew Piskorski's Oracle 9i notes for guidance.

    This installation guide attempts to present all of the information necessary to complete an OpenACS installation. We try hard to make all of the steps possible in one pass, rather than having a step which amounts to "go away and develop a profound understanding of software X and then come back and, in 99% of all cases, type these two lines." The exception to our rule is Oracle production systems. This page describes a set of steps to get a working Oracle development server, but it is unsuitable for production systems. If you will be using OpenACS on Oracle in a production environment, you will experience many problems unless you develop a basic understanding of Oracle which is outside the scope of this document. T

    This document assumes that you'll be installing Oracle on the same box as AOLserver. For more details on a remote Oracle installation, see Daryl Biberdorf's document.

    Useful links to find help on how to set up Oracle under Linux are:

    Production Oracle systems should run on certified platforms. Follow the metalink note 223718.1to find certified platforms. If you don't have metalink access, take a look at the Oracle on Linux FAQ: Which Linux Distributions Are Directly Supported By Oracle?. In summary, free and inexpensive Linux distributions are not certified.

    If you don't have an account at OTN get one: you can download the Oracle software from the Oracle Downloads page. It is also get the CDs shipped to you for a nominal fee from the Oracle Store.

    Each Oracle release comes with extensive and usually quite well-written documentation. Your first step should be to thoroughly read the release notes for your operating system and your Oracle version. Find the docs here:

    It is generally useful to run a particular Oracle version with its latest patchset. At the time of writing these were 8.1.7.4 and 9.2.0.5, both of which are considered to be very stable.

    To be able to download a patchset, you need a (to-pay-for) account on Metalink. You may find the appropriate patchset by following Andrew's suggestion.

    Oracle is very well-documented software, the online documentation comes with printable PDFs and full-text search. Altogether there is more than 20.000 pages of documentation, so do not expect to understand Oracle within in a few hours. The best starting pointing into Oracle is the Concepts book. Here's the 8i version and the 9.2 version.

    To give you an idea of how configurable Oracle is and how much thought you may need to put into buying the proper hardware and creating a sane setup, you should thoroughly read Cary Millsap's Configuring Oracle Server for VLDB and the Optimal Flexible Architecture standard.

    Throughout these instructions, we will refer to a number of configurable settings and advise certain defaults. With the exception of passwords, we advise you to follow these defaults unless you know what you are doing. Subsequent documents will expect that you used the defaults, so a change made here will necessitate further changes later. For a guide to the defaults, please see the section called “Defaults”.

    In order for OpenACS to work properly you need to set the environment appropriately.

    export ORACLE_BASE=/ora8/m01/app/oracle
    export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
    export PATH=$PATH:$ORACLE_HOME/bin
    export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
    export ORACLE_SID=ora8
    export ORACLE_TERM=vt100
    export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
    
    umask 022
    open_cursors = 500
    nls_date_format = "YYYY-MM-DD"

    For additional resources/documentation, please see this thread and Andrew Piskorski's mini-guide.

    Though Oracle 8.1.7 has an automated installer, we still need to perform several manual, administrative tasks before we can launch it. You must perform all of these steps as the root user. We recommend entering the X window system as a normal user and then doing a su -. This command gives you full root access.

    • Login as a non-root user and start X by typing startx

      [joeuser ~]$ startx

    • Open a terminal window type and login as root

      [joeuser ~]$ su -
      Password: ***********
      [root ~]#

    • Create and setup the oracle group and oracle account

      We need to create a user oracle, which is used to install the product, as well as starting and stopping the database.

      [root ~]# groupadd dba
      [root ~]# groupadd oinstall
      [root ~]# groupadd oracle
      [root ~]# useradd -g dba -G oinstall,oracle -m oracle
      [root ~]# passwd oracle

      You will be prompted for the New Password and Confirmation of that password.

    • Setup the installation location for Oracle. While Oracle can reside in a variety of places in the file system, OpenACS has adopted /ora8 as the base directory.

      Note: the Oracle install needs about 1 GB free on /ora8 to install successfully.

      [root ~]# mkdir /ora8
      root:/ora8# cd /ora8
      root:/ora8# mkdir -p m01 m02 m03/oradata/ora8
      root:/ora8# chown -R oracle.dba /ora8
      root:/ora8# exit
    • Set up the oracle user's environment

      • Log in as the user oracle by typing the following:

        [joeuser ~]$ su - oracle
        Password: ********
      • Use a text editor to edit the .bash_profile file in the oracle account home directory.

        [oracle ~]$ emacs .bash_profile

        You may get this error trying to start emacs:

        Xlib: connection to ":0.0" refused by server
        Xlib: Client is not authorized to connect to Server
        emacs: Cannot connect to X server :0.
        Check the DISPLAY environment variable or use `-d'.
        Also use the `xhost' program to verify that it is set to permit
        connections from your machine.

        If so, open a new terminal window and do the following:

        [joeuser ~]$ xhost +localhost

        Now, back in the oracle terminal:

        [oracle ~]$ export DISPLAY=localhost:0.0
        [oracle ~]$ emacs .bash_profile

        Try this procedure anytime you get an Xlib connection refused error.

      • Add the following lines (substituting your Oracle version number as needed) to .bash_profile:

        export ORACLE_BASE=/ora8/m01/app/oracle
        export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
        export PATH=$PATH:$ORACLE_HOME/bin
        export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
        export ORACLE_SID=ora8
        export ORACLE_TERM=vt100
        export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
        
        umask 022

        Save the file by typing CTRL-X CTRL-S and then exit by typing CTRL-X CTRL-C. Alternatively, use the menus.

      Make sure that you do not add any lines like the following

      # NLS_LANG=american
      # export NLS_LANG

      These lines will change the Oracle date settings and will break OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD dates.

    • Log out as oracle

      [oracle ~]$ exit
    • Log back in as oracle and double check that your environment variables are as intended. The env command lists all of the variables that are set in your environment, and grep shows you just the lines you want (those with ORA in it).

      [joeuser ~]$ su - oracle
      [oracle ~]$ env | grep ORA

      If it worked, you should see:

      ORACLE_SID=ora8
      ORACLE_BASE=/ora8/m01/app/oracle
      ORACLE_TERM=vt100
      ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7
      ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data

      If not, try adding the files to ~/.bashrc instead of .bash_profile. Then logout and log back in again. Also, be certain you are doing su - oracle and not just su oracle. The - means that .bashrc and .bash_profile will be evaluated.

      Make sure that /bin, /usr/bin, and /usr/local/bin are in your path by typing:

      [oracle ~]$ echo $PATH
      /bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin

      If they are not, then add them to the .bash_profile by changing the PATH statement above to PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin

    • Log in as oracle and start X if not already running. Start a new terminal:

      [joeuser ~]$ xhost +localhost
      [joeuser ~]$ su - oracle
      Password: **********
      [oracle ~]$ export DISPLAY=localhost:0.0
    • Find the runInstaller script

      • If you are installing Oracle from a CD-ROM, it is located in the install/linux path from the cd-rom mount point

        [oracle ~]$ su - root
        [root ~]# mount -t iso9660 /dev/cdrom /mnt/cdrom
        [root ~]# exit
        [oracle ~]$ cd /mnt/cdrom
      • If you are installing from the tarball, the install script is located in the Oracle8iR2 directory that was created when you expanded the archive.

        [oracle ~]$ cd /where/oracle/Disk1

      Check to make sure the file is there.

      oracle:/where/oracle/Disk1$ ls
      doc  index.htm  install  runInstaller  stage  starterdb

      If you don't see runInstaller, you are in the wrong directory.

    • Run the installer

      oracle:/where/oracle/Disk1$ ./runInstaller

      A window will open that welcomes you to the 'Oracle Universal Installer' (OUI). Click on "Next"

      Note

      Some people have had trouble with this step on RedHat 7.3 and 8.0. If so, try the following steps before calling ./runInstaller:

      1. Execute the following command: /usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh

      2. Type export LD_ASSUME_KERNEL=2.2.5

    • The "File Locations" screen in the OUI:

      • "Source" path should have been prefilled with "(wherever you mounted the CDROM)/stage/products.jar"

      • "destination" path says "/ora8/m01/app/oracle/product/8.1.7"

        If the destination is not correct it is because your environment variables are not set properly. Make sure you logged on as oracle using su - oracle. If so, edit the ~/.bash_profile as you did in the section called “Pre-Installation Tasks”

      • Click "Next" (a pop up window will display Loading Product information).

    • The "Unix Group Name" screen in the OUI:

      • The Unix Group name needs to be set to 'oinstall' ( we made this Unix group earlier ).

      • Click "Next"

      • A popup window appears instantly, requesting you to run a script as root:

        • Debian users need to link /bin/awk to /usr/bin/awk before running the script below

          [joueser ~]$ su -
          [root ~]# ln -s /usr/bin/awk /bin/awk
      • Open a new terminal window, then type:

        [joeuser ~]$ su -
        [root ~]# cd /ora8/m01/app/oracle/product/8.1.7
        [root ~]# ./orainstRoot.sh  
        ; You should see:
        Creating Oracle Inventory pointer file (/etc/oraInst.loc)
        Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall.
        [root ~]# mkdir -p /usr/local/java
        [root ~]# exit
        [joeuser ~]$ exit
      • Click "Retry"

    • The "Available Products" screen in the OUI:

      • Select "Oracle 8i Enterprise Edition 8.1.7.1.0"

      • Click "Next"

    • The "Installation Types" screen

      • Select the "Custom" installation type.

      • Click "Next"

    • The "Available Product Components" screen

      • In addition to the defaults, make sure that "Oracle SQLJ 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and "Linux Documentation 8.1.7.0.0" are also checked.

      • Click "Next"

      • A progress bar will appear for about 1 minute.

    • The "Component Locations" screen in the OUI

      • Click on the "Java Runtime Environment 1.1.8" It should have the path "/ora8/m01/app/oracle/jre/1.1.8"

      • Click "Next"

      • A progress bar will appear for about 1 minute.

    • The "Privileged Operation System Groups" screen in the OUI

      • Enter "dba" for "Database Administrator (OSDBA) Group"

      • Enter "dba" for the "Database Operator (OSOPER) Group"

      • Click "Next"

      • A progress bar will appear for about 1 minute.

    • The "Authentication Methods" screen

      • Click "Next"

    • The next screen is "Choose JDK home directory"

      • Keep the default path: /usr/local/java

      • Click "Next"

    • The "Create a Database" screen in the OUI

      • Select "No" as we will do this later, after some important configuration changes.

      • Click "Next"

    • The next screen is "Oracle Product Support"

      • TCP should be checked with "Status" listed as Required

      • Click "Next"

    • The "Summary" screen in the OUI

      • Check the "Space Requirements" section to verify you have enough disk space for the install.

      • Check that "(144 products)" is in the "New Installations" section title.

      • Click "Install"

      • A progress bar will appear for about 20 - 30 minutes. Now is a good time to take a break.

      • A "Setup Privileges" window will popup towards the end of the installation asking you to run a script as root

      • Run the script. Switch to the oracle user first to set the environment appropriately and then do su to get root privileges, while keeping the oracle user's enviroment.

        [joeuser ~]$ su - oracle
        Password: *********
        [oracle ~]$ su
        Password: *********
        [root ~]# /ora8/m01/app/oracle/product/8.1.7/root.sh
        ; You should see the following.   
        
        Creating Oracle Inventory pointer file (/etc/oraInst.loc)
        Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall.
        # /ora8/m01/app/oracle/product/8.1.7/root.sh
        Running Oracle8 root.sh script...
        The following environment variables are set as:
            ORACLE_OWNER= oracle
            ORACLE_HOME=  /ora8/m01/app/oracle/product/8.1.7
            ORACLE_SID=   ora8
        
        Enter the full pathname of the local bin directory: [/usr/local/bin]: 
        
        Press ENTER here to accept default of /usr/local/bin
              
        
        Creating /etc/oratab file...
        Entry will be added to the /etc/oratab file by
        Database Configuration Assistants when a database is created
        Finished running generic part of root.sh script.
        Now product-specific root actions will be performed.
        IMPORTANT NOTE: Please delete any log and trace files previously
                        created by the Oracle Enterprise Manager Intelligent
                        Agent. These files may be found in the directories
                        you use for storing other Net8 log and trace files.
                        If such files exist, the OEM IA may not restart.
      • Do not follow the instructions on deleting trace and log files, it is not necessary.

      [root ~]# exit
      [joeuser ~]$ exit
    • Go back to the pop-up window and click "OK"

    • The "Configuration Tools" screen in the OUI

      • This window displays the config tools that will automatically be launched.

    • The "Welcome" screen in the "net 8 Configuration Assistant"

      • Make sure the "Perform Typical installation" is not selected.

      • Click "Next"

      • The "Directory Service Access" screen in the "Net 8 Configuration Assistant"

      • Select "No"

      • Click "Next"

    • The "Listener Configuration, Listener Name" screen in the "Net 8 Configuration Assistant"

      • Accept the default listener name of "LISTENER"

      • Click "Next"

    • The "Listener Configuration, Select Protocols" screen in the "Net 8 Configuration Assistant"

      • The only choice in "Select protocols:" should be "TCP/IP"

      • Click "Next"

    • The "Listener Configuration TCP/IP Protocol" screen in the "Net 8 Configuration Assistant"

      • Default Port should be 1521 and selected.

      • Click "Next"

    • The "Listener Configuration, More Listeners" screen in the "Net 8 Configuration Assistant"

      • Select "No"

      • Click "Next"

    • The "Listener Configuration Done" screen in the "Net 8 Configuration Assistant"

      • Click "Next"

    • The "Naming Methods Configuration" screen in the "Net 8 Configuration Assistant"

      • Select "No"

      • Click "Next"

    • The "Done" screen in the "Net 8 Configuration Assistant"

      • Click "Finish"

    • The "End of Installation" screen in the OUI

      • Click "Exit"

      • Click "Yes" on the confirmation pop up window.

      • The Oracle Universal Installer window should have disappeared!

    Congratulations, you have just installed Oracle 8.1.7 Server! However, you still need to create a database which can take about an hour of non-interactive time, so don't quit yet.

    This step will take you through the steps of creating a customized database. Be warned that this process takes about an hour on a Pentium II with 128 MB of RAM.

    Note

    RedHat 7.3 and 8.0 users: Before running dbassist, do the following.

    1. Download the glibc patch from Oracle Technet into /var/tmp.

    2. cd $ORACLE_HOME

    3. tar xzf /var/tmp/glibc2.1.3-stubs.tgz

    4. ./setup_stubs

    • Make sure you are running X. Open up a terminal and su to oracle and then run the dbassist program.

      [joeuser ~]$ xhost +localhost
      [joeuser ~]$ su - oracle
      Password: *********
      [oracle ~]$ export DISPLAY=localhost:0.0
      [oracle ~]$ dbassist
    • The "Welcome" screen in the Oracle Database Configuration Agent (ODCA)

      • Select "Create a database"

      • Click "Next"

    • The "Select database type" screen in the ODCA

      • Select "Custom"

      • Click "Next"

    • The "Primary Database Type" window in ODCA

      • Select "Multipurpose"

      • Click "Next"

    • The "concurrent users" screen of the ODCA

      • Select "60" concurrent users.

      • Click "Next"

    • Select "Dedicated Server Mode", click "Next"

    • Accept all of the options, and click Next Oracle Visual Information Retrieval may be grayed out. If so, you can ignore it; just make sure that everything else is checked.

    • For "Global Database Name", enter "ora8"; for "SID", also enter "ora8" (it should do this automatically). Click "Change Character Set and select UTF8. Click "Next".

    • Accept the defaults for the next screen (control file location). Click "Next"

    • Go to the "temporary" and "rollback" tabs, and change the Size (upper-right text box) to 150MB. Click "Next"

    • Increase the redo log sizes to 10000K each. Click "Next"

    • Use the default checkpoint interval & timeout. Click "Next"

    • Increase "Processes" to 100; "Block Size" to 4096 (better for small Linux boxes; use 8192 for a big Solaris machine).

    • Accept the defaults for the Trace File Directory. Click "Next"

    • Finally, select "Save information to a shell script" and click "Finish" (We're going to examine the contents of this file before creating our database.)

    • Click the "Save" button. Oracle will automatically save it to the correct directory and with the correct file name. This will likely be /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh

    • It will alert you that the script has been saved successfully.

    • Now we need to customize the database configuration a bit. While still logged on as oracle, edit the database initialization script (run when the db loads). The scripts are kept in $ORACLE_HOME/dbs and the name of the script is usually initSID.ora where SID is the SID of your database. Assuming your $ORACLE_HOME matches our default of /ora8/m01/app/oracle/product/8.1.7, the following will open the file for editing.

      [oracle ~]$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora
    • Add the following line to the end:

      nls_date_format = "YYYY-MM-DD"
    • Now find the open_cursors line in the file. If you're using emacs scroll up to the top of the buffer and do CTRL-S and type open_cursors to find the line. The default is 100. Change it to 500.

      open_cursors = 500
    • Save the file. In emacs, do CTRL-X CTRL-S to save followed by CTRL-X CTRL-C to exit or use the menu.

    • At this point, you are ready to initiate database creation. We recommend shutting down X to free up some RAM unless you have 256 MB of RAM or more. You can do this quickly by doing a CRTL-ALT-BACKSPACE, but make sure you have saved any files you were editing. You should now be returned to a text shell prompt. If you get sent to a graphical login screen instead, switch to a virtual console by doing CRTL-ALT-F1. Then login as oracle.

    • Change to the directory where the database creation script is and run it:

      [oracle ~]$ cd /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib
      oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh

      In some instances, Oracle will save the file to /ora8/m01/app/oracle/product/8.1.7/assistants/dbca Try running the script there if your first attempt does not succeed.

    • Your database will now be built. It will take > 1 hour - no fooling. You will see lots of errors scroll by (like: "ORA-01432: public synonym to be dropped does not exist") Fear not, this is normal.

      Eventually, you'll be returned to your shell prompt. In the meantime, relax, you've earned it.

    For this step, open up a terminal and su to oracle as usual. You should be running X and Netscape (or other web browser) for this phase.

    • You need to download the "Oracle Acceptance Test" file. It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. Save the file to /var/tmp

    • In the oracle shell, copy the file.

      [oracle ~]$ cp /var/tmp/acceptance-sql.txt /var/tmp/acceptance.sql
    • Once you've got the acceptance test file all set, stay in your term and type the following:

      [oracle ~]$ sqlplus system/manager

      SQL*Plus should startup. If you get an ORA-01034: Oracle not Available error, it is because your Oracle instance is not running. You can manually start it as the oracle user.

      [oracle ~]$ svrmgrl
      SVRMGR> connect internal
      SVRMGR> startup
    • Now that you're into SQL*Plus, change the default passwords for system, sys, and ctxsys to "alexisahunk" (or to something you'll remember):

      SQL> alter user system identified by alexisahunk;
      SQL> alter user sys identified by alexisahunk;
      SQL> alter user ctxsys identified by alexisahunk;
    • Verify that your date settings are correct.

      SQL> select sysdate from dual;

      If you don't see a date that fits the format YYYY-MM-DD, please read the section called “Troubleshooting Oracle Dates”.

    • At this point we are going to hammer your database with an intense acceptance test. This usually takes around 30 minutes.

      SQL> @ /var/tmp/acceptance.sql
      
      ; A bunch of lines will scroll by.  You'll know if the test worked if
      ; you see this at the end:
      
      SYSDATE
      ----------
      2000-06-10
      
      SQL>

      Many people encounter an error regarding maximum key length:

      ERROR at line 1:
      ORA-01450: maximum key length (758) exceeded

      This error occurs if your database block size is wrong and is usually suffered by people trying to load OpenACS into a pre-existing database. Unfortunately, the only solution is to create a new database with a block size of at least 4096. For instructions on how to do this, see the section called “Creating the First Database” above. You can set the parameter using the dbassist program or by setting the DB_BLOCK_SIZE parameter in your database's creation script.

      If there were no errors, then consider yourself fortunate. Your Oracle installation is working.

    You will want to automate the database startup and shutdown process. It's probably best to have Oracle spring to life when you boot up your machine.

    • Oracle includes a script called dbstart that can be used to automatically start the database. Unfortunately, the script shipped in the Linux distribution does not work out of the box. The fix is simple. Follow these directions to apply it. First, save dbstart to /var/tmp. Then, as oracle, do the following:

      [oracle ~]$ cp /var/tmp/dbstart.txt /ora8/m01/app/oracle/product/8.1.7/bin/dbstart 
      [oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart
    • While you're logged in as oracle, you should configure the oratab file to load your database at start. Edit the file /etc/oratab:

      • You will see this line.

        ora8:/ora8/m01/app/oracle/product/8.1.7:N

        By the way, if you changed the service name or have multiple databases, the format of this file is:

        service_name:$ORACLE_HOME:Y || N (for autoload)

      • Change the last letter from "N" to "Y". This tells Oracle that you want the database to start when the machine boots. It should look like this.

        ora8:/ora8/m01/app/oracle/product/8.1.7:Y
      • Save the file & quit the terminal.

    • You need a script to automate startup and shutdown. Save oracle8i.txt in /var/tmp. Then login as root and install the script. (Debian users: substitute /etc/init.d for /etc/rc.d/init.d throughout this section)

      [oracle ~]$ su -
      [root ~]# cp /var/tmp/oracle8i.txt /etc/rc.d/init.d/oracle8i
      [root ~]# chown root.root /etc/rc.d/init.d/oracle8i
      [root ~]# chmod 755 /etc/rc.d/init.d/oracle8i
    • Test the script by typing the following commands and checking the output. (Debian Users: as root, do mkdir /var/lock/subsys first)

      [root ~]# /etc/rc.d/init.d/oracle8i stop
      Oracle 8i auto start/stop
      Shutting Oracle8i:
      Oracle Server Manager Release 3.1.7.0.0 - Production
      
      Copyright (c) 1997, 1999, Oracle Corporation.  All
      Rights Reserved.
      
      Oracle8i Enterprise Edition Release 8.1.7.0.1 -
      Production
      With the Partitioning option
      JServer Release 8.1.7.0.1 - Production
      
      SVRMGR> Connected.
      SVRMGR> Database closed.
      Database dismounted.
      ORACLE instance shut down.
      SVRMGR>
      Server Manager complete.
      Database "ora8" shut down.
            
      [root ~]# /etc/rc.d/init.d/oracle8i start
      Oracle 8i auto start/stop
      Starting Oracle8i: 
      SQL*Plus: Release 8.1.7.0.0 - Production on Wed Mar 6 17:56:02 2002
      
      (c) Copyright 2000 Oracle Corporation.  All rights reserved.
      
      SQL> Connected to an idle instance.
      SQL> ORACLE instance started.
      
      Total System Global Area   84713632 bytes
      Fixed Size                    73888 bytes
      Variable Size              76079104 bytes
      Database Buffers            8388608 bytes
      Redo Buffers                 172032 bytes
      Database mounted.
      Database opened.
      SQL> Disconnected
      
      Database "ora8" warm started.
      
      Database "ora8" warm started.
    • If it worked, then run these commands to make the startup and shutdown automatic.

      • Red Hat users:

        [root ~]# cd /etc/rc.d/init.d/                      
        [root ~]# chkconfig --add oracle8i
        [root ~]# chkconfig --list oracle8i
        ; You should see:
        oracle8i        0:off   1:off   2:off   3:on    4:on    5:on    6:off
      • Debian users:

        [root ~]# update-rc.d oracle8i defaults
         Adding system startup for /etc/init.d/oracle8i ...
           /etc/rc0.d/K20oracle8i -> ../init.d/oracle8i
           /etc/rc1.d/K20oracle8i -> ../init.d/oracle8i
           /etc/rc6.d/K20oracle8i -> ../init.d/oracle8i
           /etc/rc2.d/S20oracle8i -> ../init.d/oracle8i
           /etc/rc3.d/S20oracle8i -> ../init.d/oracle8i
           /etc/rc4.d/S20oracle8i -> ../init.d/oracle8i
           /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i
      • SuSE users:

        [root ~]# cd /etc/rc.d/init.d
        root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i K20oracle8i
        root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i S20oracle8i
        root:/etc/rc.d/init.d# cp K20oracle8i rc0.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc0.d
        root:/etc/rc.d/init.d# cp K20oracle8i rc1.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc1.d 
        root:/etc/rc.d/init.d# cp K20oracle8i rc6.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc6.d
        root:/etc/rc.d/init.d# cp K20oracle8i rc2.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc2.d
        root:/etc/rc.d/init.d# cp K20oracle8i rc3.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc3.d 
        root:/etc/rc.d/init.d# cp K20oracle8i rc4.d  
        root:/etc/rc.d/init.d# cp S20oracle8i rc4.d  
        root:/etc/rc.d/init.d# cp K20oracle8i rc5.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc5.d
        root:/etc/rc.d/init.d# rm K20oracle8i
        root:/etc/rc.d/init.d# rm S20oracle8i
        root:/etc/rc.d/init.d# cd
        [root ~]# SuSEconfig
        Started the SuSE-Configuration Tool.
        Running in full featured mode.
        Reading /etc/rc.config and updating the system...
        Executing /sbin/conf.d/SuSEconfig.gdm...   
        Executing /sbin/conf.d/SuSEconfig.gnprint...
        Executing /sbin/conf.d/SuSEconfig.groff...   
        Executing /sbin/conf.d/SuSEconfig.java...    
        Executing /sbin/conf.d/SuSEconfig.kdm...   
        Executing /sbin/conf.d/SuSEconfig.pcmcia...
        Executing /sbin/conf.d/SuSEconfig.perl...
        Executing /sbin/conf.d/SuSEconfig.postfix...
        Executing /sbin/conf.d/SuSEconfig.sendmail...
        Executing /sbin/conf.d/SuSEconfig.susehilf...
        Executing /sbin/conf.d/SuSEconfig.susehilf.add...
        Executing /sbin/conf.d/SuSEconfig.susewm...
        Executing /sbin/conf.d/SuSEconfig.tetex...
        Executing /sbin/conf.d/SuSEconfig.ypclient...
        Processing index files of all manpages...
        Finished.
    • You also need some scripts to automate startup and shutdown of the Oracle8i listener. The listener is a name server that allows your Oracle programs to talk to local and remote databases using a standard naming convention. It is required for Intermedia Text and full site search.

      Download these three scripts into /var/tmp

      Now issue the following commands (still as root).

      [root ~]# su - oracle
      [oracle ~]$ cp /var/tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
      [oracle ~]$ cp /var/tmp/stoplsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr    
      [oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
      [oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr
      [oracle ~]$ exit
      [root ~]# cp /var/tmp/listener8i.txt /etc/rc.d/init.d/listener8i
      [root ~]# cd /etc/rc.d/init.d
      root:/etc/rc.d/init.d# chmod 755 listener8i

      Test the listener automation by running the following commands and checking the output.

      root:/etc/rc.d/init.d# ./listener8i stop
      Oracle 8i listener start/stop
      Shutting down Listener for 8i: 
      LSNRCTL for Linux: Version 8.1.7.0.0 - Production on 06-MAR-2002 18:28:49
      
      (c) Copyright 1998, Oracle Corporation.  All rights reserved.
      
      Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost.localdomain)(PORT=1521)))
      The command completed successfully
      
          
      root:/etc/rc.d/init.d# ./listener8i start
      Oracle 8i listener start/stop
      Starting the Listener for 8i: 
      LSNRCTL for Linux: Version 8.1.7.0.0 - Production on 06-MAR-2002 18:28:52
      
      (c) Copyright 1998, Oracle Corporation.  All rights reserved.
      
      Starting /ora8/m01/app/oracle/product/8.1.7/bin/tnslsnr: please wait...
      
      TNSLSNR for Linux: Version 8.1.7.0.0 - Production
      System parameter file is /ora8/m01/app/oracle/product/8.1.7/network/admin/listener.ora
      Log messages written to /ora8/m01/app/oracle/product/8.1.7/network/log/listener.log
      Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost.localdomain)(PORT=1521)))
      Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC)))
      
      Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost.localdomain)(PORT=1521)))
      STATUS of the LISTENER
      ------------------------
      Alias                     LISTENER
      Version                   TNSLSNR for Linux: Version 8.1.7.0.0 - Production
      Start Date                06-MAR-2002 18:28:53
      Uptime                    0 days 0 hr. 0 min. 0 sec
      Trace Level               off
      Security                  OFF
      SNMP                      OFF
      Listener Parameter File   /ora8/m01/app/oracle/product/8.1.7/network/admin/listener.ora
      Listener Log File         /ora8/m01/app/oracle/product/8.1.7/network/log/listener.log
      Services Summary...
        PLSExtProc        has 1 service handler(s)
        ora8      has 1 service handler(s)
      The command completed successfully

      This test will verify that the listener is operating normally. Login into the database using the listener naming convention.

      sqlplususername/password/@SID

      [root ~]# su - oracle
      [oracle ~]$ sqlplus system/alexisahunk@ora8
      
      SQL> select sysdate from dual;
      
      SYSDATE
      ----------
      2002-02-22
      
      SQL> exit
      [oracle ~]$ exit
      [root ~]#
      • RedHat users:

        Now run chkconfig on the listener8i script.

        [root ~]# cd /etc/rc.d/init.d/
        root:/etc/rc.d/init.d# chkconfig --add listener8i
        root:/etc/rc.d/init.d# chkconfig --list listener8i
        listener8i      0:off   1:off   2:off   3:on    4:on    5:on    6:off
      • Debian users:

        Now run update-rc.d on the listener8i script.

        [root ~]# update-rc.d listener8i defaults 21 19
         Adding system startup for /etc/init.d/listener8i ...
           /etc/rc0.d/K19listener8i -> ../init.d/listener8i
           /etc/rc1.d/K19listener8i -> ../init.d/listener8i
           /etc/rc6.d/K19listener8i -> ../init.d/listener8i
           /etc/rc2.d/S21listener8i -> ../init.d/listener8i
           /etc/rc3.d/S21listener8i -> ../init.d/listener8i
           /etc/rc4.d/S21listener8i -> ../init.d/listener8i
           /etc/rc5.d/S21listener8i -> ../init.d/listener8i
    • Test the automation

      As a final test, reboot your computer and make sure Oracle comes up. You can do this by typing

      [root ~]# /sbin/shutdown -r -t 0 now

      Log back in and ensure that Oracle started automatically.

      [joeuser ~]$ su - oracle
      [oracle ~]$ sqlplus system/alexisahunk@ora8
      
      SQL> exit

    Congratulations, your installation of Oracle 8.1.7 is complete.

    Oracle has an internal representation for storing the data based on the number of seconds elapsed since some date. However, for the purposes of inputing dates into Oracle and getting them back out, Oracle needs to be told to use a specific date format. By default, it uses an Oracle-specific format which isn't copacetic. You want Oracle to use the ANSI-compliant date format which is of form 'YYYY-MM-DD'.

    To fix this, you should include the following line in $ORACLE_HOME/dbs/initSID.ora or for the default case, $ORACLE_HOME/dbs/initora8.ora

    nls_date_format = "YYYY-MM-DD"

    You test whether this solved the problem by firing up sqlplus and typing:

    SQL> select sysdate from dual;

    You should see back a date like 2000-06-02. If some of the date is chopped off, i.e. like 2000-06-0, everything is still fine. The problem here is that sqlplus is simply truncating the output. You can fix this by typing:

    SQL> column sysdate format a15
    SQL> select sysdate from dual;

    If the date does not conform to this format, double-check that you included the necessary line in the init scripts. If it still isn't working, make sure that you have restarted the database since adding the line:

    [joeuser ~]$ svrmgrl
    SVRMGR> connect internal
    Connected.
    SVRMGR> shutdown
    Database closed.
    Database dismounted.
    ORACLE instance shut down.
    SVRMGR> startup
    ORACLE instance started.

    If you're sure that you have restarted the database since adding the line, check your initialization scripts. Make sure that the following line is not included:

    export nls_lang = american

    Setting this environment variable will override the date setting. Either delete this line and login again or add the following entry to your login scripts after the nls_lang line:

    export nls_date_format = 'YYYY-MM-DD'

    Log back in again. If adding the nls_date_format line doesn't help, you can ask for advice in our OpenACS forums.

    • Dropping a tablespace

      • Run sqlplus as the dba:

        [oracle ~]$ sqlplus system/changeme
      • To drop a user and all of the tables and data owned by that user:

        SQL> drop user oracle_user_name cascade;
      • To drop the tablespace: This will delete everything in the tablespace overriding any referential integrity constraints. Run this command only if you want to clean out your database entirely.

        SQL> drop tablespace table_space_name including contents cascade constraints;

    For more information on Oracle, please consult the documentation.

    We used the following defaults while installing Oracle.

    Variable Value Reason
    ORACLE_HOME /ora8/m01/app/oracle/product/8.1.7 This is the default Oracle installation directory.
    ORACLE_SERVICE ora8 The service name is a domain-qualified identifier for your Oracle server.
    ORACLE_SID ora8 This is an identifier for your Oracle server.
    ORACLE_OWNER oracle The user who owns all of the oracle files.
    ORACLE_GROUP dba The special oracle group. Users in the dba group are authorized to do a connect internal within svrmgrl to gain full system access to the Oracle system.

    Next Page