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.
-
Install a script called restart-aolserver
. This script doesn't actually restart AOLserver - it just kills it.
-
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.
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.
-
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
-
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]$
-
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]#
-
Recovery.
-
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).
-
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
-
Restore the database
-
Oracle.
-
Set up a clean Oracle database user and tablespace with the same names as the ones exported from (more information).
-
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
-
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
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.
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:
-
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
-
Add the Service to CVS (OPTIONAL)
-
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.
-
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.
-
Connect to Oracle using
svrmgrl
and login:
[$OPENACS_SERVICE_NAME ~]$ svrmgrl
SVRMGR> connect internal
Connected.
-
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
-
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/
.
-
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 ~]$
-
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;
-
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.
-
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.
-
Configure an AOLserver Service for OpenACS.
-
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.
-
AOLserver is very configurable. These settings should get you
started, but for more options, read the AOLserver
docs.
-
Enable OpenFTS Full Text Search (OPTIONAL)
-
Install nsopenssl
for SSL support. (OPTIONAL)
-
Verify AOLserver startup.
-
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.
-
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
.
-
Automate
AOLserver keepalive (OPTIONAL)
-
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”.
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
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:
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:
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:
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:
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:
-
Present a form to the user
-
Present a confirmation page to the user
-
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:
In the Tcl library directory:
-
For files that contain module-specific procedures, use the convention:
-
For files that contain procedures that are part of the core ACS, use the convention:
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.
or
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.
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:
-
Execute the following command:
/usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh
-
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:
-
-
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:
-
The "Installation Types" screen
-
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
-
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
-
The next screen is "Choose JDK home directory"
-
The "Create a Database" screen in the OUI
-
The next screen is "Oracle Product Support"
-
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
-
The "Welcome" screen in the "net 8 Configuration
Assistant"
-
The "Listener Configuration, Listener Name" screen in
the "Net 8 Configuration Assistant"
-
The "Listener Configuration, Select
Protocols" screen in the "Net 8 Configuration
Assistant"
-
The "Listener Configuration TCP/IP Protocol" screen in
the "Net 8 Configuration Assistant"
-
The "Listener Configuration, More Listeners" screen in
the "Net 8 Configuration Assistant"
-
The "Listener Configuration Done" screen in the
"Net 8 Configuration Assistant"
-
The "Naming Methods Configuration" screen
in the "Net 8 Configuration Assistant"
-
The "Done" screen in the "Net 8 Configuration
Assistant"
-
The "End of Installation" screen in the OUI
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.
-
Download the glibc
patch from Oracle Technet into /var/tmp
.
-
cd $ORACLE_HOME
-
tar xzf /var/tmp/glibc2.1.3-stubs.tgz
-
./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)
-
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 "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
150
MB. 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
init
SID.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.
sqlplus
username/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/init
SID.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.