Installation

AllegroGraph is distributed without Java. We assume that Sun's Java is already installed. The Java interface to AllegroGraph requires Java version 1.4.2 or later.

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 priviledges, 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.

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

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.

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

If you do not have root permissions and still want to use the RPM package, then you can install into an alternate directory by doing the following:

% rm -fr ~/rpmdb  
% mkdir ~/rpmdb  
% rpm --dbpath $HOME/rpmdb --initdb  
% rm -fr ~/agraph  
% mkdir ~/agraph  
% rpm -ivh --nodeps \  
   --relocate /usr/lib/agraph=$HOME/agraph/agraph \  
   --relocate /etc/sysconfig/agraph=$HOME/agraph/sysconfig/agraph \  
   --relocate /etc/rc.d/init.d/agraph=$HOME/agraph/init.d/agraph \  
   --dbpath $HOME/rpmdb agraph-3.0-1.x86_64.rpm  
Preparing...         ########################################### [100%]  
   1:agraph          warning: user agraph does not exist - using root  
warning: user agraph does not exist - using root  
...  
warning: user agraph does not exist - using root  
########################################### [100%]  
warning: user agraph does not exist - using root  
warning: user agraph does not exist - using root  
error reading information on service agraph: No such file or directory  
error: %post(agraph-3.0-1.x86_64) scriptlet failed, exit status 1  
% 

Despite the warnings and error at the end, the files you need to run AllegroGraph will be in $HOME/agraph.

Mac OS X

There are two Mac OS X versions of AllegroGraph, one for 32 and 64-bit x86. 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 [email protected].

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/2.2/DESCRIPTIONS  
downloading: update/agraph/2.2/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/2.2/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 what ever directory 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 Java  
;; server for information on valid values for these options.  
;;  
;; Comments start with a semicolon (;).  
(  
;; Please do not change the following line:  
(:agraph-server-config 3)  
;; 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  
:client-select-queries 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:

• :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.

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

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

• :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.

• :eval-in-server-file -- the value of this option controls what the evalInServer() method is allowed to execute. For more information read this.

• :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 the lisp, lisp*, etc. functors.

t -- allows all queries without checking, and is appropriate only for environnments where clients can be trusted.

:disallow -- blocks any use of select by clients.

• :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.

• :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.

• :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.

• :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.

• :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.

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

• :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.

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

• :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.

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

• :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.

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:

• --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.

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

• --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.

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

• --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.

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 may result in arbitrary Lisp code. The default behavior in the standard installation is to allow Prolog queries from clients but suppress any Lisp evaluations.

The behavior can be modified with the configuration file option :client-select-queries or by calling the function enable-lisp-in-client-select-queries.

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.