next up previous contents
Next: Customize OA - Adding Up: Open Administration for Schools Previous: How to Upgrade Open

Model OpenAdmin Installation - Single Site with SSL

This section written by Andy Figueroa

  1. Operating System Installation

    Download Ubuntu 10.10 server edition starting here:

    Install the server, choosing the LAMP (Linux, Apache, MySQL, PHP) option when prompted.

    During the installation of Ubuntu server edition, you will be asked a few questions:

    When the installation is complete, boot into your new server.

    Unless you want to work exclusively using sudo, set up a root password using:
    sudo passwd root and you will be prompted to enter your password then you will be prompted to enter the root password twice. Write it down.

    1. Base System Configuration

      Do all of the following logged in as root, using su to become root, or prefixing each command with sudo

      Change the default DHCP network setting to a fixed IP address if appropriate for your installation (typically appropriate) by editing the file /etc/network/interfaces using IPs appropriate for your network. You may use any text editor. Text editors nano and vi are installed. A model file for static IP address follows:

      #file /etc/network/interfaces
      # The loopback network interface
      auto lo
      iface lo inet loopback
      # The primary network interface
      auto eth0
      #iface eth0 inet dhcp
      iface eth0 inet static

      To avoid errors from apache2 be sure to add your hostname and IP address to the /etc/hosts

      # file /etc/hosts     localhost   oaserver2   oaserver2

      Update sources using the command apt-get update

      Optional: If you didn't install the openssh-server as part of the base server installation, and you want to access your server using ssh, install the openssh-server using:
      apt-get install openssh-server

      Use apt-get to install the following additional packages and their automatically installed dependencies:

      apt-get install build-essential
      apt-get install emacs22-nox (for Emacs editor)
      apt-get install mc (Midnight Commander for File Management)
      apt-get install libssl-dev
      apt-get install openssh-server
      apt-get install libxml2-dev
      apt-get install texlive
      apt-get install zip

    2. Installing the necessary Perl modules

      You may get more information about Perl at

      Most of the perl modules needed by OpenAdmin can be installed from the Debian repositories using apt-get install modulename as follows (the portion in parenthesis shows perl module name):

      apt-get install libxml-libxml-perl (LibXML2 and XML::LibXML)
      apt-get install libtext-csv-perl (Text::CSV_XS)
      apt-get install libfreezethaw-perl (FreezeThaw)
      apt-get install libcgi-session-perl (CGI::Session)
      apt-get install libcrypt-ssleay-perl (Crypt::SSLeay)
      apt-get install libxml-writer-perl (XML::Writer)
      apt-get install libdata-uuid-perl (Data::UUID)
      apt-get install libcrypt-generatepassword-perl
      apt-get install libgd-graph-perl
      apt-get install libmail-sender-perl
      apt-get install libnet-scp-expect-perl
      apt-get install libnumber-format-perl

      The following perl modules were not identified in the Debian repositories and may be retrieved from CPAN. The first time you invoke CPAN you will be walked through a configuration dialog. The defaults suggested are correct and work fine. Enter appropriate responses when prompted for your geographic location and the servers you want to use.

      perl -MCPAN -e 'install Date::Business'
      perl -MCPAN -e 'install Time::JulianDay'
      perl -MCPAN -e 'install XML::Writer::String'

      You now have a working Apache2, MySLQ server on port 80 (normal http port) that meets all the program requirements of OpenAdmin 5.25. You may test it from another computer on your network by visiting with a web browser (substitute your own IP address if different). You may also test it locally using lynx from the shell if you don't have another computer on your network handy: lynx

  2. Configuring Apache2 for OpenAdmin using SSL

    The following changes are all applied in /etc/apache2: cd /etc/apache2

    Create symbolic links to ssl modules in /etc/apache2/mods-enabled:

    cd mods-enabled
    ln -s /etc/apache2/mods-available/ssl.load ssl.load
    ln -s /etc/apache2/mods-available/ssl.conf ssl.conf

    Use your favorite editor to edit dir.conf adding index.shtml to the list of automatically served files:

    <IfModule mod\_dir.c>
    # Keep the two lines below joined as one line in dir.conf.
       DirectoryIndex index.html index.shtml index.cgi
    index.php index.xhtml

    Return to /etc/apache2: cd ..

    Create a site to use ssl by copying the default site/file to the ssl site/file:

    cd sites-available
    cp default ssl

    Edit ssl using your favorite editor to modify existing lines or adding, as needed, to read:

    NameVirtualHost *:443
    <VirtualHost *:443>
            ServerAdmin webmaster@localhost
            SSLEngine on
            SSLCertificateFile /etc/apache2/ssl/apache.pem
            DocumentRoot /var/www/
            <Directory />
    	#  Options FollowSymLinks
               Options FollowSymLinks Includes
    	#  AllowOverride None
                AllowOverride All
            <Directory /var/www/>
                Options Indexes FollowSymLinks MultiViews
    	  # AllowOverride None
                AllowOverride All
                Order allow,deny
                allow from all
                # This directive allows us to have apache2's default
    	    # start page in /apache2-default/, but still have /
    	    # go to the right place
                RedirectMatch ^/$ /apache2-default/
    <IfModule alias_module>
    ## Note: This entire section to the end is required to allow
    ## openadmin to run perl scripts from the right path operating
    ## in a single SSL protected site.  It is not necessary for the
    ## purpose of getting the SSL site running.  The portion that is
    ## comment out below is from the original file and must remain so.
    #     ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
    #     <Directory "/usr/lib/cgi-bin">
    #            AllowOverride None
    #            Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
    #            Order allow,deny
    #            Allow from all
    #    </Directory>
    # ScriptAlias: This controls which directories contain server
    # scripts. ScriptAliases are essentially the same as Aliases,
    # except that documents in the realname directory are treated
    # as applications and run by the server when requested rather
    # than as documents sent to the client. The same rules about
    # trailing "/" apply to ScriptAlias directives as to Alias.
    #ScriptAlias /cgi-bin/ /var/www/localhost/cgi-bin/
    ScriptAlias /cgi-bin/ /var/www/openadmin/myschool/cgi/
    ScriptAlias /tcgi-bin/ /var/www/openadmin/myschool/tcgi/
    ScriptAlias /pcgi-bin/ /var/www/openadmin/myschool/pcgi/
    <Directory "/var/www/openadmin/myschool/cgi/">
    AllowOverride All
    Options FollowSymLinks Includes
    Order allow,deny
    Allow from all
    <Directory "/var/www/openadmin/myschool/tcgi/">
    AllowOverride All
    Options FollowSymLinks Includes
    Order allow,deny
    Allow from all
    <Directory "/var/www/openadmin/myschool/pcgi/">
    AllowOverride All
    Options FollowSymLinks Includes
    Order allow,deny
    Allow from all

    No further changes from ErrorLog /var/log/apache2/error.log to the end.

    Now, create a symbolic link /etc/apache2/sites-enabled/000-ssl to

    cd ..
    cd sites-enabled
    ln -s /etc/apache2/sites-available/ssl 000-ssl
    cd ..

    Generate a self-signed SSL certificate using the following commands:

    mkdir /etc/apache2/ssl

    # The following comand must all on one commandline:

    openssl req $a -new -x509 -days 3650 -nodes -out /etc/apache2/ssl/
         apache.pem -keyout /etc/apache2/ssl/apache.pem

    Use the same fully qualified domain name when prompted for Common Name that you used in /etc/hosts (i.e. ) to keep apache2 from giving an error about the domain name.

    or you can go to and grab the old apache2-ssl-certificate which is an easier way to generate a good self-signed SSL certificate.

    Extract the package and put ssleay.cnf in /usr/share/apache2/
    put apache2-ssl-certificate in /usr/sbin.
    Create /etc/apache2/ssl with mkdir /etc/apache2/ssl
    Then the apache2-ssl-certificate script should run from the commandline.

    Finally, restart apache2 with the following command:
    /etc/init.d/apache2 restart

    Test your work from another computer on your network with:

    If it does not work, check the error message on the screen and the logs in /var/log/apache2.

    Assuming that you do not also want an unsecured http connection to port 80, delete or comment out the Listen 80 line in /etc/apache2/ports

    Also delete the symbolic link 000-default in /etc/apache2/sites-enabled with:
    rm /etc/apache2/sites-enabled/000-default

    Next - setup your school's MySql database...

  3. Setting Up the MySQL database

    Create a database for your school where the database name is myschool and the root MySQL password in the example is (not the same as the system root password) oa99 which you established when installing the server:

    mysqladmin create -poa99 myschool

    Now create a non-root password for this school by using the mysql grant command by first entering the MySQL client:

    mysql -poa99 -u root myschool

    Then type (on one line):

    grant all on myschool.* to myuser@localhost identified by

    like the following (on one line, of course:

    grant all on myschool.* to oaadmin@localhost identified
    by 'oaadmin99';

    where myschool is the name of the database, and myuser ( oaadmin in the example) and mypassword ( oaadmin99 in the example) are the user and password to get access to the program. They do not have to exist on the system as a real user, but are merely used by the scripts. These are the $user and $password variables used in the etc/admin.conf file we will set up later.

    And then:

    A new mysql identity called rouser (read only user) should be created that has only read (sql select) capability for that school's database. This is particularly important for use with the publicly accessible parent page/site that allows students and parents to view attendance, report and gradebook marks. Other scripts may use this as well as development of OpenAdmin continues.

    grant select on myschool.* to rouser@localhost identified
    by 'ropassword';

    as in the example below (on one line):

    grant select on myschool.* to oauser@localhost identified
    by 'oauser99';

    where rouser ( oauser in the example) and ropassword ( oauser99 in the example) are the values also entered in the etc/admin.conf configuration file for $rouser and $ropassword.

    Also enter a global user with read-only cabability to be used in global.conf as shown:

    grant select on myschool.* to global@localhost identified
    by 'global99';

    Exit MySql by entering: exit; or quit;

    Be sure to write down all the names and passwords you just created. You will need them again to configure OpenAdmin.

    Now that you have a database name and users, you are now ready to set up OpenAdmin.

  4. Downloading, Installing, and Setting up OpenAdmin

    The following is a simplified version of what is found in the official OpenAdmin documentation for setting up a single school on a single server. For more complex arrangements, please see the official OpenAdmin documentation. It is recommended that you at least read through the official OpenAdmin documentation in order to better understand how OpenAdmin works.

    Download the latest Open Admin version from and then untar it into /opt (We will create symlinks from /var/www to the installation path a little later).

    cd /opt
    tar xzf /path/to/download/openadmin-2.50.tgz

    To make it easier to work with the new directory, create a symlink to the resulting openadmin directory:

    ln -s openadmin-5.25 openadmin

    Change the owner and group of the OpenAdmin directory and everything below it to the apache2 user:

    chown -R www-data:www-data openadmin

    Enter the OpenAdmin directory and copy the base school directory to a school directory for your own school:

    cd openadmin

    cp -a school myschool

    The new myschool directory is where OpenAdmin will run and where we will do almost all of our configuration. You may substitute any short single word for myschool if you would like to better distinguish your school identification, i.e da, stpeter, stmary, hhcs and so on.

    Next, we'll create symbolic links from the apache2 root httpd directory, /var/www/, to our installed OpenAdmin in /opt/openadmin where openadmin is an existing symbolic link to the current installation:

    cd /var/www
    ln -s /opt/openadmin openadmin
    ln -s /opt/openadmin/myschool/admin oaadmin
    ln -s oaadmin/js js
    ln -s oaadmin/images/favicon.ico favicon.ico
    ln -s /opt/openadmin/myschool/tadmin oateacher
    ln -s /opt/openadmin/myschool/padmin oastudent

    Change to the /opt/openadmin/myschool/etc directory and edit the admin.conf file:

    cd /opt/openadmin/myschool/etc

    Use your favorite editor to configure admin.conf

    nano admin.conf ( or vi admin.conf )

    The first 3 entries of the admin.conf configuration file following the added section at the top for release 2.50 are for user, password, and database,. These were established when we set up the database section above.

    Although many of the entries/changes that are needed are specific to a particular school, others are common to single site SSL operation. A model is included at the end of this guide. All of the entries are important, but most important are those providing paths to OpenAdmin's files.

    When finished with admin.conf, change to the myschool/tadmin directory and edit the index.shtml file, changing all the references to cgi-bin to tcgi-bin.

    cd /opt/openadmin/myschool/tadmin

    Such a global search and replace is easily done in vi as follows:

    vi index.shtml

    Also edit and configure the global.conf file in /opt/openadmin/global

    cd /opt/openadmin/global

    nano global.conf or vi global.conf

  5. Create the database tables

    Change directories to /opt/openadmin/utility and enter the following to setup the database tables:

    mysql -poaadmin99 -u oaadmin myschool $<$blank.sql.475.mysql5x

    Also, do the same with meta.sql to create the starting student and staff table values:

    mysql -poaadmin99 -u oaadmin myschool $<$meta.sql

    If you don't get any errors, you may be done. You can check by looking in
    to see if it is populated with a screen full of tables.

  6. How to get started

    If everything is working, you are now ready to enter dates, teachers, courses, schedule, and students, in that order. Then enroll students in classes. See the administration manual section 6, and the user manual in the OpenAdmin documentation for details.

  7. Files available

    The following files are all included in the archive oasslfiles.tgz found in the utility directory. Current versions are also maintained at

    Use the command tar xzpf oasslfiles.tgz and they will be extracted into your current path directory oasslfiles (i.e. /oasslfiles), which it will create if it doesn't exist. To use, edit the files as may be necessary for your own situation and copy them into their respective directories.


    script: symlink.scr

    Creates the necessary symlinks in /etc/apache2, /var/www/, /opt and creates the directory /etc/apache2/ssl.

    (Note: Look at this script before you run it. Edit it if necessary for your particular installation. You will have to delete and recreate the symlink at /opt/openadmin if your installed version of OpenAdmin changes from openadmin-2.50. The other symlinks should never have to change except to suit your own situation.)

    Optional: apache2-ssl.tgz

    A script included in earlier versions of Apache for easily generating a self-signed certificate. The files from the archive ssleay.cnf is to be copied into /usr/share/apache2/ and apache2-ssl-certificate into /usr/sbin Execute the sript by running apache2-ssl-certificate from the shell as described in the Apache2 configuration section, Section 3 above.

next up previous contents
Next: Customize OA - Adding Up: Open Administration for Schools Previous: How to Upgrade Open