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 Python, 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.
Jena and Sesame
We have implement classes and methods that allow access to AllegroGraph triple stores with Jena or Sesame API calls. Applications that use these interfaces must use agextn-3-1.jar instead of agraph-3-1.jar. For details on the implementation please see the Javadocs for AllegroGraph with Jena and Sesame Extensions.
We implement the Sesame 2.1 Sail interfaces. The code was tested with the Sesame 2.1.2 libraries obtained from openrdf.org. We have not tested Sesame 2.1.3 libraries, but using these does not reveal any static compiler errors. A Sesame application gains access to an AllegroGraph store by instantiating the class com.knowledgereefsystems.agsail.AllegroSail:
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 agextnsrc-3-1.jar.
External Jar files needed for Sesame 2.1.2:
From http://openrdf.org/download.jsp the file openrdf-sesame-2.1.2-onejar.jar.
From http://logging.apache.org/log4j/ the file log4j-1.2.12.jar.
From http://www.slf4j.org/dist/ the file slf4j-1.4.3.zip, which contains slf4j-api-1.4.3.jar and slf4j-log4j12-1.4.3.jar.
From http://www.junit.org/ the file junit.jar (we have been using version 3.8.1 included in a Jena distribution).
Sesame 2.2
The recent release of Sesame 2.2 includes a revised definition of SailConnectionListener. This definition is not compatible with earlier releases. As a result, the AllegroGraph Sesame adapter will not work with Sesame 2.2 libraries.
We implement Jena 2.5 interfaces tested with Jena 2.5.6 from http://jena.sourceforge.net/. 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 http://jena.sourceforge.net/documentation.html. There are some additional code examples in package com.franz.agjena.test in the source files distributed in agextnsrc-3-1.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 http://jena.sourceforge.net/downloads.html.
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.
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.1 directory. Once unpacked, the executable is agraph-3.1/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 info@franz.com.
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 Java Edition. When we do, you can find descriptions of them on this page: http://agraph.franz.com/support/patches/log/.
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.1/DESCRIPTIONS
downloading: update/agraph/3.1/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.1/pfo013.001.
Remember to restart your server after running the updater. Updates are loaded at server start time only.
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
:http-port -1
:http-init-file nil
:http-only nil
:idle-life 86400
:eval-in-server-file nil
:pid-file "sys:agraph.pid"
:client-select-queries t
: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-select-queries-- the value of this option controls what Prolog queries are allowed from remote clients. The values are:nil-- allow select queries that have no escapes to Lisp code, that is, queries that do not contain the??syntax or calls to any of thelisp,lisp*, etc. functors.t-- allows all queries without checking, and is appropriate only for environments where clients can be trusted.:disallow-- blocks any use of select by clients.
:error-log-- this option controls how the server handles errors. A value ofnilmeans all error information is sent only to the client. A value oftmeans error information is sent to the client and to the log file (see the:log-fileoption). 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 theevalInServer()method is allowed to execute. For more information, see the section onevalInServerbelow.: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.: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 calledaginit.clin 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 calledagraph.pidin 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 ist, the default, the server returns all error signals to Java as Java exceptions. If this option isnil, the server will stop for some serious conditions (such as out-of memory) and allow some diagnostic operations (if the command line argument--debugwas 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 supplying a file containing 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-select-queries 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.
