Page History

...

• 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 for Properties" 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.

...

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 for Properties" below)
• Backslashes (\) : as this is the escape character

...

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

...

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

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:

Including other Property Files

Because DSpace supports the Apache Commons Configuration properties file syntax, it also can include/embed property files within other property files by using the "include=" setting.

For example, the dspace.cfg includes/embeds all of the default config/modules/*.cfg files via a series of "include=" settings near the bottom of the dspace.cfg. As an example, here's a small subset of those include calls:

# defines our modules subdirectory
module_dir = modules

# The following lines include specific "authentication*.cfg" files inside your dspace.cfg
# This essentially "embeds" their configurations into your dspace.cfg by default,
# treating them as a single configuration file.
include = ${module_dir}/authentication.cfg
include = ${module_dir}/authentication-ip.cfg
include = ${module_dir}/authentication-ldap.cfg
include = ${module_dir}/authentication-password.cfg
include = ${module_dir}/authentication-shibboleth.cfg

This ability to include properties files within others is very powerful, as it allows you to inherit settings from other files, or subdivide large configuration files. Be aware that this essentially causes DSpace to treat all included configurations as if they were part of the parent file. This means that, in the above example, as far as DSpace is concerned, all the settings contained within the authentication*.cfg files "appear" as though they are specified in the main dspace.cfg.

This ability to include other files is also possible with the local.cfg file, should you want to subdivide your localized settings into several locally specific configuration files.

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:

1. The "source" file that is found in [dspace-source]/dspace/config/dspace.cfg
2. The "runtime" file that is found in [dspace]/config/dspace.cfg
   The
3. The "source" file that is found in [dspace-source]/dspace/config/dspace.cfg
4. The "runtime" file that is found in [dspace]/config/dspace.cfg
   The runtime file is supposed to be the copy of the source file, which is considered the master version. However, the DSpace server and command programs only look at the runtime configuration file, so when you are revising your configuration values, it is tempting to only edit the runtime file. DO NOT do this. Always make the same changes to the source version of dspace.cfg in addition to the runtime file. The two files should always be identical, since the source dspace.cfg will be the basis of your next upgrade.

...

• "ant -Doverwrite=false update_configs" ==> Leaves existing configs in [dspace]/config/ intact. Just copies new configs from
  [dspace-source]/dspace/config/ over to *.new files.

The

...

local.

...

cfg Configuration Properties File

As of DSpace 3.0, we now provide a [dspace-source]/build.properties as an easy means of configuration a subset of properties before you build DSpace (by running "mvn package" or similar).  Any properties set in this build.properties file will be automatically copied over to your final dspace.cfg file as part of the Maven build process.

...