# AllegroGraph 3.3 Server Installation

# Table of Contents

## Introduction

### Java client

### Common Lisp client

### Python client

## Installation

### Windows

### Linux

### Mac OS X

### Solaris

### FreeBSD

## Updater

## The AllegroGraph server application

## Security considerations

### Contents of the eval-in-server permission file

### Prolog select queries

## Introduction

We discuss here how to install the server for AllegroGraph. This server services clients from many languages, including Java and Common Lisp, as well as access via the HTTP protocol. Future clients include C# and Ruby.

### Java client

AllegroGraph is distributed without Java. To use the Java client, you must install Sun's Java runtime environment. The Java interface to AllegroGraph requires Java version 1.5 or later.

#### Compatibility with Previous Versions of AllegroGraph

This release of AllegroGraph presents a new revised API that is not compatible with previous versions. Existing application can continue to run using a compatibility jar file distributed in agraph-3-1-1.jar and agraph-3-1-1.jar.

#### Jena and Sesame

We have implemented classes and methods that allow access to AllegroGraph triple stores with Jena or Sesame 2 API calls. For details on the implementation please see the Javadocs for AllegroGraph with Jena and Sesame Extensions.

We implement the Sesame 2 Sail interfaces. The code was tested with the Sesame 2.2 libraries obtained from openrdf.org.

A Sesame application gains access to an AllegroGraph store by instantiating the class com.franz.ag.repository.AGRepository:

    AllegroGraph ag;   // initialized with AllegroGraph API calls
    Repository repo = new AGRepository(ag);
    repo.initialize();
    RepositoryConnection rc = repo.getConnection();
    ...
    Sesame operations

A Sesame application can also gain access to an AllegroGraph store by instantiating the class com.knowledgereefsystems.agsail.AllegroSail, but this usage is likely to be much less efficient.

    Sail sail = new AllegroSail(host, port, ... );
    sail.initialize();
    SailConnection sc = sail.getConnection();
    ...
    Sesame operations

Sesame documentation is hosted on openrdf.org. There are some additional code examples in package com.knowledgereefsystems.agsail in the source files distributed in agsrc-3-3.jar.

##### External Jar files needed for Sesame 2.2:

- From the file openrdf-sesame-2.2-onejar.jar.

- From the file log4j-1.2.12.jar.

- From the file slf4j-1.4.3.zip, which contains slf4j-api-1.4.3.jar and slf4j-log4j12-1.4.3.jar.

- From the file junit.jar (we have been using version 3.8.1 included in a Jena distribution).

We implement Jena 2.5 interfaces tested with Jena 2.5.6 from . A Jena application gains access to an AllegroGraph store by instantiating classes in the com.franz.agjena package:

    AllegroGraphConnection conn = new AllegroGraphConnection()
    conn.enable();
    AllegroGraph agStore = conn.access("storename", "/foo/bar/");
    AllegroGraphGraphMaker maker = new AllegroGraphGraphMaker(agStore);
    Graph graph = maker.createGraph();
    Model model = new AllegroGraphModel(graph);
    ...
    Jena operations

Jena documentation and tutorials are obtained from . There are some additional code examples in package com.franz.agjena.test in the source files distributed in agsrc-3-3.jar.

##### External Jar files needed for Jena 2.5.6:

All the jar files in the lib subdirectory of jena-2.5.6.zip from .

### Common Lisp client

The supported version of Common Lisp is Allegro Common Lisp, version 8.1. You should make sure you have installed all current patches for the base Lisp.

### Python client

Once AllegroGraph is installed, the Python client can be found in the python directory in the AllegroGraph installation directory.

The AllegroGraph Python client depends on pycurl (included with AllegroGraph) and cjson.

After fulfilling the requirements of the following sections for each operating system on which you wish to use the Python client, we recommend that you read our Python Tutorial.

#### Python client: Windows

See the Python Tutorial for information on setting up clients on Windows.

#### Python client: Linux

See the Python Tutorial for information on setting up clients on Linux.

#### Python client: Mac OS X

Installing PyCurl from source:

Download the PyCurl source code from and place the source where you put auxiliary Python sources. `cd` to the location and type

    python setup.py install

Alternatively, you can use EasyInstall, if you have that.

If this does not work, then likely your copy of curl, the C companion to pycurl, is out of date. In that case, you need to install a recent copy of curl. You can find out the version you have by executing

    curl-config –version

The best way to do install a more recent version of curl is to first install MacPorts, from . The dmg installation creates files, but doesn't create a launchable application. It is supposed to modify the PATH variable so that its commands are visible from a shell interpreter. However, it may not do that, and in that case add to the file ~/.bashrc something like this:

    export PATH=/opt/local/bin:$PATH

Restart your shell to get the new PATH.

You can now locate the latest version of curl by typing:

    port search curl

You install it with:

    sudo port install curl

It will install the most recent version of curl, pulled from the Web.

Now, if all is well, you should be able to install pycurl with this command:

    sudo easy_install pycurl

#### Python client: testing the installation

See the Python Tutorial for information on testing the installation.

#### Python client: server options

The Python client requires the use of new command line arguments or configuration file options. These new arguments are to start and configure the new HTTP server used by the Python client.

One way to start the server is to run the AllegroGraphServer executable with a `--new-http-port` argument. This will start the HTTP server on the local machine on the given port.

To actually have access to triple stores, you must also publish one or more catalogs in the server. A catalog is a directory in the file system where the server can find triple stores, and where users of the server are allowed to create new stores. To publish catalogs, pass one or more `--new-http-catalog` parameters to AllegroGraphServer, each followed by the name of a directory.

Finally, the catalogs can be protected with basic HTTP authentication by providing a `--new-http-auth` parameter, followed by a username:password (separated by a colon) combination.

For example, to start a server on port 8080, publishing two catalogs, and requiring the login name `jack` with password `xyzzy`, you would run this:

    AllegroGraphServer --new-http-port 8080 --new-http-auth jack:xyzzy \
                       --new-http-catalog /home/jack/stores/ \
                       --new-http-catalog /tmp/scratch/

#### Python client: server options and Windows considerations

On Windows, since AllegroGraph by default runs as a service, you cannot merely pass command line arguments directly to the server. In this case, we recommend using the configuration file. The example in the previous section, using command line arguments, would translate to these agraph.cfg options:

    :new-http-port 8080
    :new-http-auth "jack:xyzzy"
    :new-http-catalog ("/home/jacl/stores/" "/tmp/scratch/")

If you change the configuration file, you must restart the service. For more information, please see the AllegroGraph server section below.

## Installation

### Windows

There are 32 and 64-bit versions of AllegroGraph available for Windows. Select the appropriate one for the version of Windows you are running. The 32-bit version of AllegroGraph will run on the 64-bit version of Windows, but the 64-bit version of AllegroGraph will not run on the 32-bit version of Windows.

After downloading the installer executable, just run it. It will guide you through the installation. AllegroGraph runs as a service. The installation will start the service and run the AllegroGraph console application, that allows you to see messages from the server. The console displays an icon in the system tray. Just double-click on the icon to show the window containing server messages.

The AllegroGraph service, by default, runs as the Local System account. If you wish to run the server as a particular user, with reduced privileges, you can do so by running the services Windows program (in the Control Panel). Once there, right click on the AllegroGraph Server entry and select properties. On the Log On tab you can change the Log on as values with an account and password. You must restart the service for the change to take effect.

### Linux

There are two Linux versions of AllegroGraph: 32-bit (x86) and 64-bit (x86-64). Select the appropriate one for the version of Linux you are running. The 32-bit version of AllegroGraph may run on 64-bit Linux, but the the 64-bit version of AllegroGraph will not run on the 32-bit version of Linux.

NOTE: on Linux with SELinux enabled, AllegroGraph likely will not function. Please see the SELinux FAQ entry for the solution to this problem. The FAQ entry is about the Allegro CL Express Edition, but it applies to the .so file in the AllegroGraph installation directory.

On Linux, AllegroGraph is distributed both as an RPM and a tar.gz file. If you do not have root permissions, then please use the tar.gz file for installation.

For the RPM installation, the files are located in the /usr/lib/agraph/ directory. The server executable is /usr/lib/agraph/AllegroGraphServer. The RPM package also installs a script for starting and stopping AllegroGraph with system startup and shutdown, /etc/rc.d/init.d/agraph. AllegroGraph is set to start at the end of the Linux boot process. See the section Security considerations for important information.

If you want AllegroGraph to start and stop with as the system is booted and shutdown, then you can use the /etc/rc.d/init.d/agraph script. You do, however, need to tell the system to use the script, as this is not done by default. The following command would do that:

    # chkconfig --add agraph

The server can manually be started with this command:

    # /etc/rc.d/init.d/agraph start

and manually stopped with this command:

    # /etc/rc.d/init.d/agraph stop

You may also wish to just run the server executable from the command line, without using the init script.

For the tar.gz installation, just unpack the files anywhere that does not already have an existing agraph-3.3 directory. Once unpacked, the executable is agraph-3.3/AllegroGraphServer .

### Mac OS X

There are two Mac OS X versions of AllegroGraph: one for 32 and one for 64-bit x86. The 32-bit version runs only on Mac OS X 10.4 or later. The 64-bit version runs only on Mac OS X 10.5 or later.

If you require PPC support, please contact Franz for the most up-to-date information.

On Mac OS X, AllegroGraph is distributed as a DMG file. Open the DMG and open the AllegroGraph.pkg file. Follow the prompts to install the software. AllegroGraph is installed into /Applications/AllegroGraph. The server is called AllegroGraphServer.

### Solaris

We support Solaris AMD64. Currently, there is no support for SPARC (32 or 64-bit). For information on SPARC releases contact .

On Solaris, AllegroGraph is distributed as a compressed tar archive. You may extract the files anywhere you wish. The tar archive contains a directory name agraph-version, where version is the version of AllegroGraph you downloaded. The server executable is called AllegroGraphServer in this directory.

### FreeBSD

On FreeBSD, AllegroGraph is distributed as a compressed tar archive. You may extract the files anywhere you wish. The tar archive contains a directory name agraph-version, where version is the version of AllegroGraph you downloaded. The server executable is called AllegroGraphServer in this directory.

## Updater

From time to time we release updates or fixes to the Server Edition. When we do, you can find descriptions of them on this page: .

In the AllegroGraph installation directory there is an application called updater when you can run to download the latest patches. When you do, the output of the program will look something like this:

    peep% ./updater
    ;; Connecting to http://www.franz.com/ftp/pub/patches/.
    ;; Reading CRC cache...done.
    ;; Checking for new update.fasl.
    ;; Retrieving list of available patches.
    ;; Checking which patches need to be downloaded.
    downloading: update/agraph/3.3/DESCRIPTIONS
    downloading: update/agraph/3.3/pfo013.001 (compressed)
    ;; Creating CRC cache (please wait)...done.

    ***** NOTE: You must restart the AllegroGraph server for the newly
          downloaded updates to be installed.

    peep%

In the above case, the line of interest is the one that references update/agraph/3.3/pfo013.001 .

Remember to restart your server after running the updater. Updates are loaded at server start time only.

If you are behind a proxy, you can give updater command line arguments to specify your proxy configuration:

    peep% ./updater -p myhost.com:port -P username:password

## The AllegroGraph server application

The AllegroGraph server application executable is called `AllegroGraphServer` and it resides in the installation directory of AllegroGraph. Previous to AllegroGraph version 3.0, the server accepted user-settable parameters in the form of command line arguments. These parameters now also reside in a configuration file, `agraph.cfg`, in the AllegroGraph installation directory. The current, valid command line arguments and configuration file options are described later in this section.

On Windows, the startup directory for the service is somewhere in the Windows system directory. For this reason we recommend that absolute pathnames be used to open databases. Naming databases with relative pathnames from the Windows system directory would be tricky, and unnecessary.

On Mac OS X and other UNIX platforms, the startup directory is the directory that is current when you start the server.

The configuration file is read when the server starts. The initial version of the configuration file looks like this:

        ;; This file contains the configuration options for AllegroGraph.
        ;; Please refer to the installation documentation for the
        ;; AllegroGraph server for information on valid values for these options.
        ;;
        ;; Comments start with a semicolon (;).
        (
        ;; Please do not change the following line:
        (:agraph-server-config 5)
        ;; User-settable options start here:
        :direct nil
        :new-http-port -1
        :new-http-auth nil
        :new-http-catalog nil
        :http-port -1
        :http-init-file nil
        :http-only nil
        :idle-life 86400
        :eval-in-server-file nil
        :pid-file "sys:agraph.pid"
        :client-prolog nil
        :index -1
        :init-file "sys:aginit.cl"
        :lease -1
        :limit -1
        :log-file "sys:agraph.log"
        :no-direct nil
        :no-java nil
        :port 4567
        :port2 4568
        :res -1
        :repl-port nil
        :standalone t
        :timeout 60
        :error-log nil
        :users 50
        :verbose t
        )
        ;;END OF CONFIG

The format of each entry is option-name and option-value. The option-name must start with a colon (:). The option-value is specific to the option, but `nil` means off or no value, and the value `t` means the option is on. Some options take numerical or string arguments.

If you edit the file take care to leave the syntax as is. The parentheses and colons are significant. Whitespace, however, is not significant.

You should ignore any option not listed here, unless instructed by an AllegroGraph support engineer:

- `:client-prolog` -- the value of this option controls what Prolog queries are allowed from remote clients. The values are:

  - `nil` or `:nolisp` -- allow select queries that have no escapes to Lisp code, that is, queries that do not contain the `??` syntax or calls to any of the `lisp`, `lisp*`, etc. functors.

  - `t` or `:withlisp` -- allows all queries without checking, and is appropriate only for environments where clients can be trusted.

  - `:block` or `:disallow` -- blocks any use of select by clients.

- `:error-log` -- this option controls how the server handles errors. A value of `nil` means all error information is sent only to the client. A value of `t` means error information is sent to the client and to the log file (see the `:log-file` option). The value can also be a string naming a file, in which case all error information will be sent to this file.

- `:eval-in-server-file` -- the value of this option controls what the `evalInServer()` method is allowed to execute. The value `nil` disables client calls to eval. The value can also be string that specifies a file of allowed operations. For more information, see the section on `evalInServer` below.

- `:http-init-file` -- specifies a file that is loaded after the Sesame HTTP server is started.

- `:http-port` -- this specifies the Sesame HTTP server port number. A value of -1 (which is the default) means to not start the Sesame server.

- `:new-http-port` -- specify the port number for the new HTTP server, used by the Python client. A value of -1 (which is the default) means to not start this server.

- `:new-http-auth` -- enable HTTP basic authentication for the new HTTP server. Should be a string containing a username, then a colon, then the password. The default is not to use authentication.

- `:new-http-catalog` -- the locations on disk in which the new HTTP server can find and create triple stores. Should be a list.

- `:new-http-catalog directory` -- a location on disk in which the new HTTP server can find and create triple stores. Can be specified multiple times for multiple catalogs.

- `:index` -- specifies how a database is broken down into segments during indexing. If this number is too large, the server may page excessively during indexing, or run out of memory. If this number is too small, too many file handles may be needed during indexing. When creating very large databases (millions of triples) a good estimate for this parameter will improve performance. A value of -1 denotes the built-in default. A value from 0 to 63 denotes a power of 2. Any other positive value is used verbatim.

- `:init-file` -- the path for a file that is loaded (and evaluated) when the server is started. The default is a file called `aginit.cl` in the server installation directory.

- `:pid-file` -- the process ID (PID) of the server is saved to the file given by this argument. The default is a file called `agraph.pid` in the server installation directory.

- `:lease` -- the number of seconds the server will run without any interactions. When the lease expires the server exits. The lease is renewed whenever a call arrives from Java. A negative number specifies an indefinite lease, which is the built-in default.

- `:limit` -- the total number of connections allowed over time. The default is -1 to specify an unlimited number.

- `:log-file` -- the path for a file where the server will log progress and error messages. If no directory component is given, the path is relative to the directory where the server is installed. An absolute path, of the form `"c:/Temporary Files/usern/agraph.log"`, is also allowed.

- `:no-java` -- this suppresses the starting of the Java server.

- `:port` -- the primary port on which the server will listen for client connections. If changed this must be an available port number, and the default is 4567.

- `:repl-port` -- specifies a port on which a read-eval-print loop is started. This should only be used at the direction of an AllegroGraph support engineer.

- `:res` -- specifies the number of expected unique literal values in a new database. If this value is too small, some internal tables will need to grow repeatedly as the database is built. These growth steps will delay creation and may trigger a memory overflow. When creating very large databases (millions of triples) a good estimate for this parameter will improve performance. A value of -1 means use the built-in server default, which is 100,000. A value from 0 to 63 denotes a power of 2. Any other positive value is used verbatim.

- `:standalone` -- if this option is `t`, the default, the server returns all error signals to Java as Java exceptions. If this option is `nil`, the server will stop for some serious conditions (such as out-of memory) and allow some diagnostic operations (if the command line argument `--debug` was specified).

- `:users` -- the maximum number of simultaneous connections allowed in this server instance. The default is 50.

- `:verbose` -- controls the volume of messages printed to the log file.

The command line arguments are listed below. Each configuration file option has a corresponding command line argument of the same name. The `:port` option becomes `--port` when it appears on the command line.

The command line arguments which are not configuration file options are:

- `--config-file` -- an alternate name for the configuration file.

- `--debug` -- indicates the server should run in the foreground. On UNIX, this means not running as a daemon. On Windows, this means not running as a service.

- `--service-install` [Windows only] -- install the Windows service for AllegroGraph.

- `--service-remove` [Windows only] -- remove the Windows service for AllegroGraph.

- `--service-start` [Windows only] -- start the Windows service for AllegroGraph. `"net start agraph"` also works.

- `--service-stop` [Windows only] -- stop the Windows service for AllegroGraph. `"net stop agraph"` also works.

- `--user username` [UNIX only] -- as soon as the server starts, set the effective user ID of the process to username.

- `--write-config [file]` -- given a set of command line arguments and default values, write a configuration file to file. If file is not given, then use the default configuration file name, `agraph.cfg`. If the configuration file exists, an error will be signaled.

## Security considerations

On Linux, AllegroGraph is installed to run as the user `agraph`. On other UNIX platforms, AllegroGraph will run as the user logged in when the server is run. On Windows, AllegroGraph runs as a service with system privileges. In each case, it is important that you consider what access these permissions grant to the users on your local area network.

On Linux, AllegroGraph is installed to run as the user `agraph`. On other UNIX platforms, AllegroGraph will run as the user logged in when the server is run. On Windows, AllegroGraph runs as a service with system privileges. In each case, it is important that you consider what access these permissions grant to the users on your local area network.

When the current version of AllegroGraph runs as a server (both direct and HTTP), we assume a secure environment where protection from malicious attack is not an issue. But even in such an environment, it is wise to take precautions against accidental unintended actions and effects.

The Java method `evalInServer()` and the Lisp client function eval-in-server are provided for the convenience of applications and support engineers. These functions allow server behavior which was not anticipated in the client/server interface. But at the same time, they allows a wide range of actions that may be undesirable. For example, a client call can redefine any of the internal functions of the AllegroGraph implementation, or call the function run-shell-command to execute an arbitrary system command.

To prevent accidental misuse, the Java method `evalInServer()` and the Lisp client function `eval-in-server` are disabled in the standard AllegroGraph installation. The functions are enabled by specifying a file name for the configuration option :eval-in-server-file. This file contains patterns of allowed operations.

### Contents of the eval-in-server permission file

Each line in the file may be a comment, a regular expression, or an exact match string.

- An empty line or a line containing spaces is ignored.

- A line beginning with a semi-colon ; may contain comments and is ignored.

- A line beginning with a caret ^ is a regular expression.

- Any other line is treated as an exact match string.

When a string argument arrives at the server for evaluation, it is matched against all the patterns in the file. If none match, then the call is rejected and the string has no effect. If the string matches one of the exact match strings or one of the regular expressions, then the string is parsed into a Lisp expression and the Lisp expression is evaluated. The evaluation may produce side effects on the server and the file system. Any values returned by the evaluation, are returned to the client.

For best security, one should always use the most restrictive form of a regular expression. An exact match string is always the most restrictive.

If the server is running in a secure environment and the application would benefit from extensive use of direct evaluations, the `eval` facility can be enabled fully by adding the line containing a single caret to the file. Such a file will allow the evaluation of all strings submitted to the server.

### Prolog select queries

Note also that a Prolog query is submitted to the server as a string that is parsed into code that could result in the execution of any Lisp functions. To prevent this, the default behavior in the standard installation is to allow calls to Prolog from clients only if they contain no `lisp` functors. These include the functors: `lisp`, `lisp*`, `lisp*!`, `lispp*`, `lispp!`, `*lisp!`, `lispp`, and `??`. See the Allegro Prolog documentation for details about the interaction between Prolog and Lisp.

The behavior can be modified with the configuration file option `:client-prolog` or by calling the function enable-lisp-in-client-select-queries. If `lisp` functors are not allowed then an error will be signaled if the Prolog query contains one.

The restricted Prolog behavior applies to Prolog queries submitted by remote Lisp or Java clients, to Prolog queries submitted by Sesame HTTP clients, and to SNA generator definitions submitted by Java clients.