Installing the ArsDigita Community System v 4.0Downloading the ACS
Download the following from the ArsDigita download page to the
/tmp directory:
ArsDigita Community System v 4.0.
Login as nsadmin and uncompress the downloaded components into
/web. Substitute the correct file name into the line
below. Tip: If you type acs- and then press the
TAB key, your shell should complete the file name
for you.
$ su - nsadmin
; Enter nsadmin's password.
$ cd /tmp
$ tar -xzvf acs-4.0.tar.gz --directory=/web
; Stay logged in as nsadmin.
You should now have an acs/ directory tree in
/web. Rename this directory to whatever you want
your web service to be identified as. The name of your web service is
referred to as the service_name. This identification is used
internally by AOLserver to differentiate your services from one
another. 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 "arfdigita" is the service
name for the ArfDigita.org
community.
$ cd /web
$ mv acs service_namePrepare Oracle for ACSYou should be logged on as nsadmin for this step and
you should make sure that nsadmin is in the
dba group.
Verify nsadmin membership by typing groups when you
login:
$ groups
nsadmin dba web
If you do not see these groups, take the following action:
$ su - # Enter root password
# usermod -g nsadmin -G dba,web nsadmin
If you get an error about an undefined group, then add that group
manually:
# groupadd dba
# groupadd nsadmin
# groupadd web
Make sure to logout as root when you are finished with
this step and log back in as nsadmin.
Connect to Oracle using svrmgrl and login:
$ 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
$ su -
; Enter root password.
# mkdir -p /ora8/m02/oradata/ora8/
# chown nsadmin.web /ora8/m02/oradata/ora8
# chmod 775 /ora8/m02/oradata/ora8
# exit
$
As nsadmin, 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.
$ svrmgrl
SVRMGR> connect internal;
SVRMGR> create tablespace service_name datafile '/ora8/m02/oradata/ora8/service_name01.dbf' size 50m autoextend on default storage (pctincrease 1);
Create a database user for this service. Give the user access to the
tablespace and rights to connect. (Substitute
database_password with the appropriate password.)Write down what you specify as service_name and
database_password. You will need this information
for configuring exports and AOLserver.
SVRMGR> create user service_name identified by database_password default tablespace service_name
temporary tablespace temp quota unlimited on service_name;
SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to service_name;
SVRMGR> revoke unlimited tablespace from service_name;
SVRMGR> alter user service_name quota unlimited on service_name;
SVRMGR> exit;
Your table space is now ready. In case you are trying to delete a
previous ACS installation, consult these commands in below.
Make sure that you can login to Oracle using your
service_name account:
$ sqlplus service_name/database_password
SQL> select sysdate from dual;
SYSDATE
----------
2000-06-11
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 Oracle documentation.
Configuring AOLserverThe 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 the ACS to work, you need to configure a
virtual server. Because the process is involved, we have prepared a
sample virtual server configuration file.
Allot an IP address: You must know what IP address has been assigned
to your web service. If you don't know, contact your system
administrator and find out. If you do not have a network connection,
use localhost 127.0.0.1 Once you have installed a
virtual server as described below, you should notify your sysadmin
that you have claimed this IP.
Save the template configuration file template-ini.ini into
/tmp.
Login as nsadmin:
$ cp /tmp/template-ini.ini /home/aol31/service_name.ini
Replace the following variables in the file as dictated below using a
text editor. You must specify a service port for your web server to
run. The standard HTTP port number is port 80. If you are already
running a web server (such as Apache, then port 80 is likely no
longer available. We recommend setting the service port to
8080 for a first time installation. No other service
uses this port and special access is not required to use it. If you
want to use port 80, please read .
Variable to replaceTarget Valueeservice_database_usernameservice_nameservice_database_passworddatabase_passwordAOL_HOME/home/aol31service_short_nameservice_nameservice_short_descriptiona description of your serviceservice_emailthe email address of the maintainerACS_HOME/web/service_nameservice_ip_addressyour ip addressservice_ip_nameyour dns nameservice_portwhat port to use (80 is standard HTTP port)service_ip_address_ssldisabled by defaultservice_ip_name_ssldisabled by defaultservice_port_ssl}disabled by default
Copy this nsd-oracle script into
/tmp/nsd-oracle.txt:
$ cd /usr/local/aolserver/bin
$ cp /tmp/nsd-oracle.txt ./nsd-oracle
$ chmod 700 /usr/local/aolserver/bin/nsd-oracle
If you deviated from the Oracle
installation defaults we specified, edit nsd-oracle
as necessary.
Kill any current running AOLserver processes and start a new one:
$ killall -9 nsd
; Should probably see:
nsd: no process killed
$ /usr/local/aolserver/bin/nsd-oracle -c /home/aol31/servername.ini
Attempt to connect to the service from a web browser as you did in
the AOLserver documentation. You
should specify a URL like:
http://ip_name:ip_port/
You should see a page that looks like this - if so, go on to the next
section.If you don't see the login page, view your error log
(/home/aol31/log/servername-error.log) to make sure
the service is starting without any problems. If you need to make
changes, don't forget to kill any running servers.
$ killall -9 nsd
Using the ACS InstallerAssuming you got your AOLserver up and running previously,
You should see a page from the webserver titled ACS
Installation: Welcome. You will be warned if your version of
the Oracle driver is out of date, if AOLserver cannot connect to the
database, 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 ACS Kernel data model.
The next page shows the results of loading the ACS Kernel data model
- be prepared to wait 20-30 seconds as it works. You should see a
string of "No errors." as the tables are created in Oracle.
Finally, another Next button will appear at the
bottom - click it.
The following page shows the results of loading the 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 "Done installing packages." - click
Create Administrator.
You should see a page, "ACS Installation: Create
Administrator" with form fields to define the ACS site
administrator. Fill out the fields as appropriate, and click
Create User.
You should see a page, "ACS Installation: Set System
Information" allowing you to essentially name your service. Fill
out the fields as appropriate, and click Set System
Information
You'll see the final Installer page, "ACS Installation:
Complete." It will tell you that the server is being restarted;
note that unless you already added your AOLserver entry to the
inittab, you'll need to manually restart your service.
After the server restarts and you reload the final page above, you
should see a login screen, asking for your email address and password.
Congratulations, ACS 4 is now up and running.TroubleshootingIf you can't get to the login page, check for one of the below
errors:
If you don't see a page at all.Check the log file. Make sure there is a line like:
Notice: nssock: listening on http://localhost.localdomain:8000
If you can't find this line, look for a line specifying an error
listening to a port. Such errors are caused if another process is
listening to that port or if you don't have permission to access
the port. Try using another port, perhaps 8086. You specify the port
in /home/aol30/service_name.ini under
[ns/server/service_name/module/nssock] Here is a sample
for a computer programmed to listen to 127.0.0.1:8080. Try replacing
the entries in your file with this one.
[ns/server/service_name/module/nssock]
timeout=120
Address=127.0.0.1
Hostname=127.0.0.1
Port=8080
Carefully scan the error log file for other entries flagged as
errors. If you can't figure out what is wrong, try posting to the
web/db
bboard.Ensure that Your Service Automatically Starts on Boot (or any other
time the service dies)This step should be completed as root. This can break every service on
your machine, so proceed with caution.
Copy this restart-aolserver into
/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.
$ su -
; Enter root password.
# cp /tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver
# chown root.web /usr/local/bin/restart-aolserver
# chmod 4750 /usr/local/bin/restart-aolserver
# ln -s /usr/bin/perl /usr/local/bin/perl
# su - nsadmin
Test the restart-aolserver script by making sure all
servers are dead, starting a new server, and then killing it. You
should see the following lines.
$ killall -9 nsd
nsd: no process killed
$ /usr/local/aolserver/bin/nsd-oracle -c /home/aol31/service_name.ini
$ restart-aolserver service_name
Killing 23727 23728 23729 23730
$ killall -9 nsd
nsd: no process killed
The numbers indicate the process ids (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.
$ su -
; Enter root password
# emacs -nw /etc/inittab
Copy this line into the bottom of the file as a template, making sure
that the first field nss is unique.
nss:2345:respawn:/usr/local/aolserver/bin/nsd-oracle -i -c /home/aol31/service_name.ini
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.
# killall -9 nsd
# /sbin/init q
Important: See if it worked by running the
restart-aolserver script again.
# restart-aolserver service_name
Killing 23750 23753 23754 23756
If the processes were killed, congratulations, your server is now
automated for startup and shutdown. On to the Acceptance Tests!How to Transfer Data
If you are moving the service from one location to another, export code
for the old database and import into the new. If your database has been
hosed and you want to restore a backup, use the imp command.
These commands can be run from the shell, you don't need to use
sqlplus. To export:
exp service_name/database_password file=foo.dmp consistent=y full=y
To import:
imp service_name/database_password file=foo.dmp [fromuser=olduser touser=service_name]
Running AOLserver on Port 80
If you want to run the service on port 80 (the default HTTP port), you
need to add some additional settings to your
service_name.ini file in /home/aol30. Under the
[ns/parameters] section, ensure that there is an entry
User=nsadmin
Moreover, you will need to start the service as root. If
you follow the instructions above for automating
startup, this will be taken care of, but if you ever start the server
from the command line, be sure to su - first.These steps are required because port 80 is a privileged
port. Only certain users can claim it. When you start
nsd as root, it obtains the port, and then changes to
run as whatever user you specify in the server configuration file. This
ensures a high level of security, as the server, once started, is not
running as root. This mean that if someone was able to
exploit your web server to execute a command on your server, they would
not be able to gain root access.Deleting a tablespace
Should it become necessary to rebuild a tablespace from scratch, you can
use the drop user command with the cascade
option. This command will drop the user and every database object the
user owns.
drop user
service_name cascade;
If this does not work because svrmgrl "cannot drop a user that is
currently connected", make sure to kill the AOLserver using this
user. If it still does not work, do:
select username, sid, serial# from v$session where username='service_name';
and then
alter system kill session 'sid,serial#';
where sid and serial# are replaced with the
corresponding values for the open session.Use with caution!If you feel the need to delete everything related to the
service, you can also issue the following:
drop tablespace service_name including contents cascade constraints;
Set Up Nightly Oracle ExportsWhile you're working with Oracle, you should configure it to do
automatic exports. An export is a separate backup copy of the database.
This copy includes all of the database's state at the time that the
export was initiated. If your database is corrupted, you can restore from
one of these backups (see ). You should
do this step as root.
Download the backup script. Save the file export-oracle.txt as
/tmp/export-oracle.txt.
Login as root. The following commands will install the export script:
$ su -
; Enter root password
# cp /tmp/export-oracle.txt /usr/sbin/export-oracle
# 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.
# mkdir /ora8/m02/oracle-exports
# chown oracle.dba /ora8/m02/oracle-exports
# 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:
# /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.
If you don't have any warnings, proceed to automate the
backups.
Automating backups is accomplished using the UNIX
crontab facility.While still root, run the following command. You
can replace the EDITOR="emacs -nw" portion
with whatever editor your prefer, such as EDITOR=vi.
# export EDITOR="emacs -nw"
# crontab -e
Now add the following line on a line by itself
0 23 * * * /usr/sbin/export-oracle
Save the file, exit the editor. Verify that the addition succeeded
by checking the output of the following command.
# crontab -l | grep export-oracle
0 23 * * * /usr/sbin/export-oracle
# exit
; Logout
If you see the line, go ahead and log out.
($Id: acs.xml,v 1.1 2001/03/13 22:59:26 ben Exp $)