Page History

...

• General Configuration - addresses general conventions used with configuring not only the dspace.cfg file, but other configuration files which use similar conventions.
• The build.properties Configuration Properties File - specifies the basic build.properties file settings (these basic settings are used when building/installing/upgrading DSpace)
• The dspace.cfg Configuration Properties File - specifies the basic dspace.cfg file settings (these settings are used when DSpace is actually running)

• Optional or Advanced Configuration Settings - contain other more advanced settings that are optional in the dspace.cfg configuration file.

  Info
  As of version 1.8 much of Much of the DSpace configuration has been moved to discrete configuration files related to specific functionality and is documented in subsequent sections of this document.

...

In the following sections you will learn about the different configuration files that you will need to edit so that you may make your DSpace installation work. Of the several configuration files which you will work with, it is the dspace.cfg file you need to learn to configure first and foremost.

In general, most of the configuration files, namely dspace.cfg and xmlui.xconf will provide a good source of information not only with configuration but also with customization (cf. Customization chapters)

Input Conventions

We will use the dspace.cfg as our example for input conventions used throughout the system. It is a basic Java properties file, where lines are either comments, starting with a '#', blank lines, or property/value pairs of the form:

property.name = property value

Some property defaults are "commented out". That is, they have a "#" preceding them, and the DSpace software ignores the config property. This may cause the feature not to be enabled, or, cause a default property to be used when the software is compiled and updated.

The property value may contain references to other configuration properties, in the form ${property.name}. This follows the ant convention of allowing references in property files. A property may not refer to itself. Examples:

property.name = word1 ${other.property.name} more words
property2.name = ${dspace.dir}/rest/of/path

Property values can include other, previously defined values, by enclosing the property name in ${...}. For example, if your dspace.cfg contains:

dspace.dir = /dspace
dspace.history = ${dspace.dir}/history

DSpace provides a number of textual configuration files which may be used to configure your site based on local needs. These include:

• [dspace]/config/dspace.cfg : The primary configuration file, which contains the main configurations for DSpace.
• [dspace]/config/modules/*.cfg : Module configuration files, which are specific to various modules/features within DSpace.
• [dspace]/config/local.cfg : A (optional, but highly recommended) localized copy of configurations/settings specific to your DSpace (see local.cfg documentation below)
• Additional feature-specific configuration files also exist under [dspace]/config/, some of these include:

  • default.license : the default deposit license used by DSpace during the submission process (see Submission User Interface documentation)
  • hibernate.cfg.xml : The Hibernate class configuration for the DSpace database (almost never requires changing)
  • input-forms.xml : The default deposit input forms for DSpace (see Submission User Interface documentation)
  • item-submission.xml : the default item submission process for DSpace (see Submission User Interface documentation)
  • launcher.xml : The configuration of the DSpace command-line "launcher" ( [dspace]/bin/dspace , see the DSpace Command Launcher documentation)
  • log4j.properties : The default logging settings for DSpace log files (usually placed in [dspace]/log)
  • news-side.html and news-top.html : HTML news configuration files for the JSPUI homepage (see JSPUI Configuration and Customization)
  • news-xmlui.xml : News configuration file for the XMLUI homepage (see XMLUI Configuration and Customization)
  • workflow.xml : Configuration for the Configurable Workflow feature (not used by default)
  • xmlui.xconf : Configuration for the XMLUI (see XMLUI Configuration and Customization)

As most of these configurations are detailed in other areas of the DSpace documentation (see links above), this section concentrates primarily on the "*.cfg" configuration files (namely dspace.cfg and local.cfg).

Input Conventions

We will use the dspace.cfg as our example for input conventions used throughout the system. These same input conventions apply to all DSpace *.cfg files.

All DSpace *.cfg files use the Apache Commons Configuration properties file syntax.  This syntax is very similar to a standard Java properties file, with a few notable enhancements described below.

• Comments all start with a "#" symbol. These lines are ignored by DSpace.
• Other settings appear as property/value pairs of the form: property.name = property value
• Certain special characters (namely commas) MUST BE escaped.  See the "Special Characters" section below
• Values assigned in the same *.cfg file are "additive", and result in an array of values. See "Specifying Multiple Values" below.

Some property defaults are "commented out". That is, they have a "#" preceding them, and the DSpace software ignores the config property. This may cause the feature not to be enabled, or, cause a default property to be used.

The property value may contain references to other configuration properties, in the form ${property.name}. A property may not refer to itself. Examples:

dspace.dir = /path/to/dspace
dspace.name = My DSpace

# property.name will be equal to "My DSpace is great!"
property.name = ${dspace.name} is great!

# property2.name will be equal to "/path/to/dspace/rest/of/path"
property2.name = ${dspace.dir}/rest/of/path

# However, this will result in an ERROR, as the property cannot reference itself
property3.name = ${property3.name} 

Special Characters

Certain characters in *.cfg files are considered special characters, and must be escaped in any values.  The most notable of these special characters include:

• Commas (,) : as they represent lists or arrays of values (see "Specifying Multiple Values" below)
• Backslashes (\) : as this is the escape character

This means that if a particular setting needs to use one of these special characters in its value, it must be escaped. Here's a few examples:

# WRONG SETTING
# This setting is INVALID. DSpace is expecting your site name to be a single value,
# But, this setting would create an array of two values: "DSpace" and "My Institution"
dspace.name = DSpace, My Institution

# CORRECT SETTING (commas is escaped)
# Instead, if the name of your DSpace includes a comma, you need to escape it with "\,"
dspace.name = DSpace\, My Institution

# WRONG SETTING
# As the backslash is the escape character, this won't work
property.name = \some\path

# CORRECT SETTING
# If you want a literal backslash, you need to escape it with "\\"
# So, the below value will be returned as "\some\path"
property.name = \\some\\path

Additional examples of escaping special characters are provided in the documentation of the Apache Commons Configuration properties file syntax.

Specifying Multiple Values for Properties

Because DSpace supports the Apache Commons Configuration properties file syntax, it is much easier to specify multiple values for a single setting. All you have to do is repeat the same property name multiple times in the same *.cfg file.

For example:

# The below settings define *two* AuthenticationMethods that will be enabled, LDAP and Password authentication
# Notice how the same property name is simply repeated, and passed different values.
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.LDAPAuthentication
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.PasswordAuthentication

# Alternatively, you can also define them as a comma-separated list 
# (In this scenario, you would NOT escape the comma, as you want them to be considered multiple values)
# So, this single line is exactly equavalent to the settings above:
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.LDAPAuthentication, org.dspace.authenticate.PasswordAuthentication

Please be aware that this ONLY works if you are reusing the exact same configuration in the same configuration file. This causes the values to be "additive" (i.e they are appended to the same list). 

However, as you'll see below, the "local.cfg" file always overrides settings elsewhere. So, if the above "AuthenticationMethod" plugin was specified in both your authentication.cfg and your local.cfg, the value(s) in your local.cfg would override the defaults in your authentication.cfg (more on that below).

Additional examples of creating lists or arrays of values are provided in the documentation of the Apache Commons Configuration properties file syntaxThen the value of dspace.history property is expanded to be /dspace/history. This method is especially useful for handling commonly used file paths.

Update Reminder

Things you should know about editing dspace.cfg files.
It is important to remember that there are * multiple dspace.cfg files in serveral places after an installation of DSpace.* The only two you should notice are:

...