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:

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:

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:

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.

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.