Table of Contents
Download the following from the ArsDigita download page to the /tmp directory:
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.
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.
You 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:
If you do not see these groups, take the following action:
If you get an error about an undefined group, then add that group manually:
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:
Determine where the system tablespaces are stored:
Example results:
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:
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.
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.
Your table space is now ready. In case you are trying to delete a previous ACS installation, consult these commands in Section 7.9. below.
Make sure that you can login to Oracle using your service_name account:
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.
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 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:
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 Section 7.8..
| Variable to replace | Target Valuee |
| service_database_username | service_name |
| service_database_password | database_password |
| AOL_HOME | /home/aol31 |
| service_short_name | service_name |
| service_short_description | a description of your service |
| service_email | the email address of the maintainer |
| ACS_HOME | /web/service_name |
| service_ip_address | your ip address |
| service_ip_name | your dns name |
| service_port | what port to use (80 is standard HTTP port) |
| service_ip_address_ssl | disabled by default |
| service_ip_name_ssl | disabled by default |
| service_port_ssl} | disabled by default |
Copy this nsd-oracle script into /tmp/nsd-oracle.txt:
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:
Attempt to connect to the service from a web browser as you did in the AOLserver documentation. You should specify a URL like:
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.
Assuming 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.
If 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:
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.
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.
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.
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.
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.
Copy this line into the bottom of the file as a template, making sure that the first field nss is unique.
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.
Important: See if it worked by running the restart-aolserver script again.
If the processes were killed, congratulations, your server is now automated for startup and shutdown. On to the Acceptance Tests!
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:
To import:
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
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.
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.
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:
and then
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:
While 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 Section 7.7.). 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:
Setup the export directory; this is the directory where backups will be stored. We recommend the directory /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:
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.
Now add the following line on a line by itself
Save the file, exit the editor. Verify that the addition succeeded by checking the output of the following command.
If you see the line, go ahead and log out.