AllegroGraph 4.0 Daemon configuration

The AllegroGraph server requires a configuration file in order to start up. Usually, this file is specified using the --config command-line argument. A minimal file could look like this:

SettingsDirectory /tmp/ag4/settings  
SuperUser test:xyzzy  
 
<RootCatalog>  
  Main /tmp/ag4/root  
</RootCatalog> 

An AllegroGraph configuration file consists of a set of top-level directives, and one or more catalog definitions. The syntax is straight-forward: directives (both top-level and within a catalog definition) consist of an alphanumeric word, whitespace, and then the value of the directive. Indentation is ignored. A directive can span multiple lines by escaping newlines with a back-slash, in which case both the newline and the backslash will be treated as if they are not there. Catalog definitions are delimited by pseudo-XML markers like <RootCatalog>. Lines starting with a # are treated as comments.

The directories named in this file must either already exist and be writeable by the user running the server, or that user must be able to create them himself. You'll usually not want to use temporary paths as in the example, of course.

Top-level directives

SettingsDirectory

Required setting. Specifies the directory in which the server stores persistent information such as user accounts.

Port

Should be an integer. Used to set the port on which the daemon runs its HTTP server. When not given, this defaults to 10035.

HostName

Determines the host on which the HTTP server listens. Can be left out to have the server listen on all interfaces. Set to localhost to listen only locally.

AllowHTTP

A boolean (yes/no) that can be used to turn off HTTP access to the server. Default is yes.

SSLPort

An integer. If given, an SSL HTTP server will be run on this port.

SSLCertificate

When an SSLPort is given, this should be used to point at a file containing a server certificate and private key, PEM-encoded.

SuperUser

If given, should be a string in name:password format. The server will ensure, on startup, that a superuser with this name and password exists. Note that this means anyone that can read your configuration file has full access to the server. It is recommended to use the server setup script to create a superuser instead, or if you do use this directive, remove it after the first run of the server has created the user.

Backends

Specifies the maximum number of processes spawned to handle HTTP requests (note that session processes do not count towards this limit). Default is 3.

SessionPorts

If given, should be an integer range like 8000-8020. Defines the ports that will be used for sessions. Useful when these need to be opened in a firewall or similar. When not specified, random ports will be used.

LogDir

Specifies the directory where the server log file is written.

RunAs

Have the server, if started by root, run as the given user instead (defaults to agraph).

PidFile

A file to which the server writes out its process id.

SPARQLBaseURL

If given, the HTTP server will use this value as the base-url when parsing SPARQL queries. When not given, the URL of the request is used instead.

Catalog definitions

Catalogs are locations on disk where AllegroGraph keeps its triple-stores. These locations are specified in the configuration file, along with some optional default settings for stores in the catalogs. Most of the time, you will want to specify all catalogs directly in the configuration file, but it is also possible to enable dynamic catalogs, which can be created and deleted through the HTTP interface.

There are three types of catalog definitions that can occur in an AllegroGraph configuration file: a root catalog, named catalogs, and a dynamic catalog specification. The first was seen in the example above (<RootCatalog> ... </RootCatalog>), and is used to determine where stores live that do not have a catalog specified. Named catalogs look similar:

<Catalog temporary>  
  Main /tmp/catalog  
</Catalog> 

Their opening line specifies their name, which can contain any characters except slashes, backslashes, colons, and tildes. This name can then be used as catalog name when creating or accessing triple-stores.

Finally, a dynamic catalog definition is used to provide the settings for catalogs created over HTTP. If no dynamic catalog is defined, this feature is disabled.

<DynamicCatalogs>  
  Main /tmp/dynamic  
</DynamicCatalogs> 

The directory (as well as Aux directories, see below) given for dynamic catalogs will be extended with a catalog name when such a catalog is created. For example, given the above configuration, a dynamic catalog named scratch would end up in /tmp/dynamic/scratch.

Catalog directives

Some of the directives allowed within a catalog definition (those marked as inheritable) can also be specified at the top-level, where they act as a default value inherited by catalogs which don't explicitly specify that setting.

Main

Required for every catalog. Specifies the directory in which the triple-stores for the catalog are stored.

Aux

Can be specified zero or more times to add extra directories that can be used to hold triple-store data. In high-performance setups, it can be helpful to spread out data over multiple disks.

TransactionLogDir

Specifies the directory in which transaction log subdirectories will be created for triple-stores in this catalog. The directory will be extended with the name of a triple-store. For example, if TransactionLogDir is /tmp/tlogs, then transaction logs for triple-store example will be stored in /tmp/tlogs/example. This parameter is optional and defaults to the value supplied for the Main parameter.

ExpectedStoreSize inheritable

An integer. If given, it is used by the server to guess suitable values for things like internal table sizes. You should only worry about this when trying to squeeze out more performance. Setting it too big can lead to some wasted resources, setting it too small to sub-optimal performance.

CheckpointInterval inheritable

A time (value like 10s, 5m, 1h) that is used to determine the amount of time between checkpoint writes for the store. A higher value increases the recovery time but might make checkpoints happen less frequently.

TransactionLogSize inheritable

A size (for example 10m) that determines how big individual transaction log files are allowed to grow. When a transaction log size meets or exceeds this size, a new transaction log file will be created. The maximum is just under 4GB.

Example

A bigger example to demonstrate what some of the options can look like.

# Don't allow normal HTTP access, only SSL  
Port 10035  
AllowHTTP no  
SSLPort 10036  
SSLCertificate /var/lib/ag4/server.cert  
 
SettingsDirectory /var/lib/ag4/settings  
 
Backends 5  
# You can actually remove this after the first server run, to  
# reduce the risk of someone finding it here.  
SuperUser test:xyzzy  
 
ExpectedStoreSize 100000  
SessionPorts 8080-8083  
 
<RootCatalog>  
  Main /var/lib/ag4/root  
</RootCatalog>  
 
<Catalog fast>  
  ExpectedStoreSize 2000000  
  CheckpointInterval 1h       
  Main /var/lib/ag4/fast  
  Aux /mnt/disk2/ag4/fast  
</Catalog>  
 
<DynamicCatalogs>  
  Main /var/lib/ag4/dynamic  
</DynamicCatalogs>