Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml,v
diff -u -r1.6 -r1.6.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 10 Aug 2002 19:53:50 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 24 Nov 2002 21:29:24 -0000 1.6.2.1
@@ -2,158 +2,155 @@
Install AOLserver 3.3+ad13
- by Vinod Kurup
+ by Vinod Kurup
- Download the Distribution
+ Download the Distribution
-
- Mat Kovach is graciously maintaining an AOLServer distribution that
- includes all the patches and modules needed to run OpenACS &version;. These
- instructions will describe how to install using his source
- distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and
- perhaps more to come), currently located at uptime.openacs.org.
-
+
+ Mat Kovach is graciously maintaining an AOLServer distribution that
+ includes all the patches and modules needed to run OpenACS &version;. These
+ instructions will describe how to install using his source
+ distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and
+ perhaps more to come), currently located at uptime.openacs.org.
+
-
- It's also possible to download all the pieces and patches yourself:
-
+
+ It's also possible to download all the pieces and patches yourself:
+
-
-
- AOLServer is available at aolserver.com
-
+
+
+ AOLServer is available at aolserver.com
+
-
- ArsDigita's AOLServer distribution (including
- internationalization patches, nscache, nsrewrite, nssha1 and the
- oracle driver) is available at arsdigita.com
-
+
+ ArsDigita's AOLServer distribution (including
+ internationalization patches, nscache, nsrewrite, nssha1 and the
+ oracle driver) is available at arsdigita.com
+
-
- The OpenACS PostgreSQL driver is available from OpenACS
-
+
+ The OpenACS PostgreSQL driver is available from OpenACS
+
-
- nsxml is available at http://acs-misc.sourceforge.net.
-
+
+ nsxml is available at http://acs-misc.sourceforge.net.
+
-
- The patch that makes exec work
- on BSD is available at sourceforge.net
-
+
+ The patch that makes exec work
+ on BSD is available at sourceforge.net
+
-
- The patch that makes ns_uuencode
- work for binary files is available at sourceforge.net
-
+
+ The patch that makes ns_uuencode
+ work for binary files is available at sourceforge.net
+
-
- The patch that makes AOLServer respect the
- -g flag is available at sourceforge.net
-
+
+ The patch that makes AOLServer respect the
+ -g flag is available at sourceforge.net
+
-
+
-
+
- .... or just Download Mat's
- AOLServer distribution to
- /tmp
+ .... or just Download Mat's
+ AOLServer distribution to
+ /tmp
-
+
-
+
joeuser:~$ cd /tmp
joeuser:/tmp$ wget -c http://uptime.openacs.org/aolserver-openacs/aolserver3.3ad13-oacs1-beta-src.tar.gz
joeuser:/tmp$ cd
-
+
- As root, untar
- aolserver3.3ad13-oacs1-beta-src.tar.gz
- into /usr/local/src
+ As root, untar
+ aolserver3.3ad13-oacs1-beta-src.tar.gz
+ into /usr/local/src
-
-
-
+
+
+
joeuser:~$ su -
Password: **********
-root:~$ cd /usr/local/src
-root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz
+root:~# cd /usr/local/src
+root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz
+root:/usr/local/src# chown -R root.root aolserver
- Create the nsadmin user
+ Set up your user account
- You will need a special user account for running AOLServer. This user
- will be called nsadmin and belong
- to the special group web.
- nsadmin's home directory will
- be /usr/local/aolserver.You must
- execute these steps as root.
-
+ 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 him 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 as the
+ nobody user and the
+ web group. We'll add your regular
+ user account to the web group and
+ make sure that OpenACS files are group readable and writable.
+
+
+
- Run these commands:
-
+ Run these commands:
+
-
+
root:/usr/local/src# cd
-root:~# groupadd nsadmin
root:~# groupadd web
-root:~# useradd -g nsadmin -G web -d /usr/local/aolserver nsadmin
-root:~# passwd nsadmin
-; Set password for nsadmin
-
-root:~# mkdir -p /web /usr/local/aolserver
-root:~# chown -R nsadmin.web /usr/local/aolserver /web /usr/local/src/aolserver
-root:~# chmod 775 /usr/local/aolserver /web
+root:~# adduser joeuser web
root:~# exit
-
-
+
-
- Set up nsadmin's environment variables
+
-
- At this point, you should customize the
- nsadmin login scripts. Login as
- nsadmin and add the following
- lines to your
- /usr/local/aolserver/.bash_profile:
-
+ Next, we'll set up our environment variables. Add the following lines
+ to your /home/joeuser/.bash_profile:
-
-joeuser:~$ su - nsadmin
-Password: ***********
-nsadmin:~$ emacs .bash_profile
+
-
- Add the first set of lines, if you're using Oracle. The 2nd set
- of lines, if you're using PostgreSQL. Oracle
- Note: 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.
-
-
-
+
+joeuser:~$ emacs .bash_profile
+
+
+
+ Add the first set of lines, if you're using Oracle. The 2nd set of
+ lines, if you're using PostgreSQL. Oracle Note:
+ 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.
+
+
+
+
# For Oracle
export ORACLE_BASE=/ora8/m01/app/oracle
export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
@@ -167,246 +164,307 @@
export PATH=$PATH:/usr/local/pgsql/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
-
- Be absolutely certain that you have entered these lines correctly
- and that you have saved the file - a slight error in these lines
- can lead to many inscrutable error messages. Logout and log back
- in so these settings will take effect. Use the
- echo command to be sure that the
- environment variables have been properly assigned.
-
+
-
-nsadmin:~$ exit
-joeuser:~$ su - nsadmin
+ Be absolutely certain that you have entered these lines correctly and
+ that you have saved the file - a slight error in these lines can lead
+ to many inscrutable error messages. Logout and log back in so these
+ settings will take effect. Use the
+ echo command to be sure that the
+ environment variables have been properly assigned.
+
+
+
+
+joeuser:~$ exit
+LOGIN: joeuser
Password: *********
-nsadmin:~$ echo $PATH
+joeuser:~$ echo $PATH
...some other directory paths...:/usr/local/pgsql/bin
-nsadmin:~$ echo $LD_LIBRARY_PATH
+joeuser:~$ echo $LD_LIBRARY_PATH
:/usr/local/pgsql/lib
-
- Note: The result should be different if you're using Oracle.
- /ora8/m01/app/oracle/product/8.1.7
- should have been in $PATH.
-
-
-
+
+
+ Note: The result should be different if you're using Oracle.
+ /ora8/m01/app/oracle/product/8.1.7
+ should have been in $PATH.
+
+
- Install libxml2 & headers
+ Install libxml2 & headers
-
+
- In order for nsxml to compile, you need libxml2
- (available from http://xmlsoft.org). On Debian,
- this can be installed by doing apt-get install
- libxml2-dev. Users of other distributions can
- download rpms from ftp.gnome.org. You'll
- need the libxml2 and
- libxml2-devel packages.
-
+ In order for nsxml to compile, you need libxml2
+ (available from http://xmlsoft.org). On Debian,
+ this can be installed by doing apt-get install
+ libxml2-dev. Users of other distributions can
+ download rpms from rpmfind.net. You'll
+ need the libxml2 and
+ libxml2-devel packages.
+
- Compile and install AOLserver
+ Compile and install AOLserver
- Prepare the distribution
+ Prepare the distribution. You need to be root.
-
-nsadmin:~$ cd /usr/local/src/aolserver
-nsadmin:/usr/local/src/aolserver$ ./conf-clean
+
+joeuser:~$ su -p
+Password: ********
+root:~# mkdir -p /usr/local/aolserver
+root:~# cd /usr/local/src/aolserver
+root:/usr/local/src/aolserver# ./conf-clean
cat: BUILD-MODULES: No such file or directory
Done.
-
+
-
+
- Put the name of the driver(s) that you want into
- conf-db. This can be
- "postgresql",
- "oracle", or the word
- "both" if you want both drivers
- installed.
-
+ Put the name of the driver(s) that you want into
+ conf-db. This can be
+ "postgresql",
+ "oracle", or the word
+ "both" if you want both drivers
+ installed.
-
-nsadmin:/usr/local/src/aolserver$ echo "postgresql" > conf-db
-
+
-
+
+root:/usr/local/src/aolserver# echo "postgresql" > conf-db
+
- conf-inst should contain the
- location where AOLserver is to be installed. This defaults to
- /usr/local/aolserver, so we
- don't need to change it.
+
-
+ conf-inst should contain the
+ location where AOLserver is to be installed. This defaults to
+ /usr/local/aolserver, so we
+ don't need to change it.
-
+
- conf-make should contain the
- name of the GNU Make command on your system. It defaults to
- gmake. You may need to change
- this to make.
-
+
-
-nsadmin:/usr/local/src/aolserver$ echo "make" > conf-make
-
+ conf-make should contain the
+ name of the GNU Make command on your system. It defaults to
+ gmake. You may need to change
+ this to make.
+
-
- If you're going to be installing the Postgresql driver, you'll
- have to adjust the makefile first. This will hopefully be cleaned
- up in future versions of this distribution.
-
+
+root:/usr/local/src/aolserver# echo "make" > conf-make
+
-
-nsadmin:/usr/local/src/aolserver$ emacs pgdriver/makefile
+
+ If you're going to be installing the Postgresql driver, you'll
+ have to adjust the makefile first. This will hopefully be cleaned
+ up in future versions of this distribution.
+
-
- Edit the lines containing PGLIB and PGINC so they look like this:
-
-
-
+
+root:/usr/local/src/aolserver# emacs pgdriver/makefile
+
+
+ Edit the lines containing PGLIB and PGINC so they look like this:
+
+
+
PGINC=/usr/local/pgsql/include
PGLIB=/usr/local/pgsql/lib
-
+
Compile and install AOLserver and modules
-
-nsadmin:/usr/local/src/aolserver$ ./conf
+
+root:/usr/local/src/aolserver# ./conf
-
- This takes about 5 minutes. All of the results are logged to
- files in
- /usr/local/src/aolserver/log. Make
- sure to check these files to see if any errors occurred.
-
-
-
+
+ This takes about 5 minutes. All of the results are logged to
+ files in
+ /usr/local/src/aolserver/log. Make
+ sure to check these files to see if any errors occurred.
+
+
+
+
+
+
+ Set File Permissions
+
+
+
+ In order to test AOLserver, we'll run it using the sample-config.tcl
+ file provided in the AOLserver distribution. We need to adjust
+ permissions a little since AOLserver needs to be able to write its
+ logs properly.
+
+
+root:/usr/local/src/aolserver# cd /usr/local/aolserver
+root:/usr/local/aolserver# chown -R root.web log servers
+root:/usr/local/aolserver# chmod -R g+w log servers
+root:/usr/local/aolserver# ls -l
+ drwxr-sr-x 8 root staff 1024 Nov 12 01:35 .
+ drwxrwsr-x 12 root staff 1024 Nov 12 01:25 ..
+ drwxr-xr-x 2 root staff 1024 Nov 12 01:36 bin
+ drwxr-xr-x 2 root staff 1024 Jun 11 2001 include
+ drwxr-xr-x 3 root staff 1024 Nov 12 01:36 lib
+ drwxrwxr-x 2 root web 1024 Nov 12 01:45 log
+ drwxr-xr-x 3 root staff 1024 Nov 12 01:35 modules
+ -rw-r--r-- 1 root staff 7320 Mar 31 2001 sample-config.tcl
+ drwxrwxr-x 3 root web 1024 Nov 12 01:35 servers
+
+
+
- Test AOLserver
+ Test AOLserver
-
+
- You will now test to ensure AOLserver is running correctly. We'll
- use the sample config file provided with AOLserver. This file
- will attempt to guess your IP address and hostname. It will then
- set up the server at port 8000 of that IP address.
-
-
-nsadmin:/usr/local/src/aolserver$ cd
-nsadmin:~$ ./bin/nsd -t sample-config.tcl
+ Now, we'll run a quick test to ensure AOLserver is running
+ correctly. We'll use the sample config file provided with
+ AOLserver. This file will attempt to guess your IP address and
+ hostname. It will then start up the server at port 8000 of that
+ IP address.
+
+
+
+root:/usr/local/aolserver# ./bin/nsd -t sample-config.tcl -u nobody -g web
+
- As the AOLserver daemon starts up, you should see a few normal
- warnings (listed below), which are safe to ignore.
-
-
+ As the AOLserver daemon starts up, you should see a few normal
+ warnings (listed below), which are safe to ignore.
+
+
+
+
Warning: nsd.tcl: nsssl not loaded -- key/cert files do not exist.
Warning: nsd.tcl: nscp not loaded -- user/password is not set.
-
- The first warning means that the server is missing files for
- running ssl, a necessary module
- for encrypted HTTPS. See Scott Goodwin's excellent
- documentation if you want to set up SSL. The second
- warning means that the AOLserver control panel, a special module
- for administering AOLserver, could not be loaded. If you're
- interested in configuring nscp, please see the AOLserver
- documentation.
-
+
+ The first warning means that the server is missing files for
+ running ssl, a necessary module
+ for encrypted HTTPS. See Scott Goodwin's excellent
+ documentation if you want to set up SSL. The second
+ warning means that the AOLserver control panel, a special module
+ for administering AOLserver, could not be loaded. If you're
+ interested in configuring nscp, please see the AOLserver
+ documentation.
+
+
+
- Test to see if AOLserver is working by starting
- Mozilla or
- Lynx, and surfing over to your
- web page:
-
-
-nsadmin:~$ lynx localhost:8000
+ Test to see if AOLserver is working by starting
+ Mozilla or
+ Lynx, and surfing over to your
+ web page:
+
+
+
+root:~# lynx localhost:8000
+
- You should see a "Welcome to AOLserver" page. If this
- doesn't work, try going to
- http://127.0.0.1:8000/. If this
- still doesn't work, check out the section below.
-
+ You should see a "Welcome to AOLserver" page. If this
+ doesn't work, try going to
+ http://127.0.0.1:8000/. If this
+ still doesn't work, check out the section below.
+
+
+
- Shutdown the test server:
-
-nsadmin:~$ killall nsd
+ Shutdown the test server:
+
+
+
+root:~# killall nsd
+
- The killall command will kill
- all processes with the name nsd,
- but clearly this is not a good tool to use for managing your
- services in general. We cover this topic in the section.
-
-
+
+ The killall command will kill
+ all processes with the name nsd,
+ but clearly this is not a good tool to use for managing your
+ services in general. We cover this topic in the section.
+
+
+
- Troubleshooting the AOLserver Install
+ Troubleshooting the AOLserver Install
- If you can't view the welcome page, it's likely
- there's a problem with your server configuration. Start by
- viewing your AOLserver log, which is in
- /usr/local/aolserver/log/server.log.
- You should also try to find lines of the form:
-
+
+
+ If you can't view the welcome page, it's likely there's a
+ problem with your server configuration. Start by viewing your
+ AOLserver log, which is in
+ /usr/local/aolserver/log/server.log.
+ You should also try to find lines of the form:
+
+
+
[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000)
[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections
- If you can find these lines, try entering the URL the server is
- listening on. If you cannot find these lines, there must be an error
- somewhere in the file. Search for lines beginning with the word
- Error instead of
- Notice.
+
- The sample-config.tcl file grabs
- your address and hostname from your OS settings.
+ If you can find these lines, try entering the URL the server is
+ listening on. If you cannot find these lines, there must be an error
+ somewhere in the file. Search for lines beginning with the word
+ Error instead of
+ Notice.
-
+
+
+
+
+ The sample-config.tcl file grabs
+ your address and hostname from your OS settings.
+
+
+
+
set hostname [ns_info hostname]
set address [ns_info address]
- If you get an error that nssock can't get the requested address,
- you can set these manually:
+
-
-#set hostname [ns_info hostname]
-set hostname 127.0.0.1
+ If you get an error that nssock can't get the requested address, you
+ can set these manually. If you type 0.0.0.0, AOLserver will try to
+ listen on all available addresses.
+
+
+
+
+set hostname [ns_info hostname]
#set address [ns_info address]
-set address 127.0.0.1
+set address 0.0.0.0
-
- If you get an error that nssock can't assign the requested port,
- then that port may already be taken by another service. Try specifying
- a different port in the config file.
-