Introduction
CloudStore can be configured using multiple properties-files. Many settings can be specified on multiple levels:
- globally (per user)
- per directory
- per file
The more specific level can override individual settings otherwise inherited from the parent's configuration.
Every property file is optional. If it does not exist, all settings are inherited. If it does exist, only those properties contained in the file are overriden. All properties not contained in the file are still inherited. Inheritance is thus applicable on every individual property.
Creations, modifications and deletions of properties files are detected during runtime (pretty immediately). Note, that this detection is based on the files' timestamps. Since most file systems have a granularity of 1 second (some even 2) for the last-modified-timestamp, multiple modifications in the same second might not be detected.
Global configuration
The global configuration is named cloudstore.properties and it is normally located in ${user.home}/.cloudstore/ but this path might be overridden using the system property cloudstore.configDir or the environment variable cloudstore_configDir. The system property has higher priority and thus overrides the environment variable (if both are set).
Configuration per directory or per file
Additionally, every directory can optionally contain the following files:
- .cloudstore.properties
- cloudstore.properties
- .${anyFileName}.cloudstore.properties
- ${anyFileName}.cloudstore.properties
The files 1. and 2. are applicable to the entire directory and all sub-directories and files in it. Usually, on GNU/Linux people will prefer 1., but when using Windows, files starting with a "." are sometimes a bit hard to deal with. Therefore, we support both. The file 2. overrides the settings of file 1..
The files 3. and 4. are applicable only to the file ${anyFileName}. Thus, if you want to set special behaviour for the file example.db only, you can create the file .example.db.cloudstore.properties in the same directory.
Configuration settings
The following property keys can be used to configure the behaviour of CloudStore:
fileWriteStrategy
This strategy controls how and when a destination file is written. There are the following possible values:
- directAfterTransfer (default)
- directDuringTransfer
- replaceAfterTransfer
So, if you want to switch to the strategy replaceAfterTransfer, you have to write the following into one of the .cloudstore.properties files:
fileWriteStrategy = replaceAfterTransfer
And here's what these strategies actually mean:
directAfterTransfer
Write directly into the destination file after all blocks have been transferred. During transfer, the destination file is not touched.
This strategy requires as much temporary space in the destination file system as blocks are transferred: The maximum total space requirement is thus twice the file size (old file + all blocks).
This is the default strategy (since CloudStore version 0.9.3).
directDuringTransfer
Write each block directly into the destination file immediately when it was transferred. Don't wait for all other blocks.
In contrast to directAfterTransfer this may leave the destination file in an inconsistent state for hours or even days - as long as the transfer takes.
However, this strategy requires the least space in the file system: Only once the file size. There are no temporary files involved and thus no additional temporary space is required.
replaceAfterTransfer
Similar to directAfterTransfer, but write a new file and then switch the files (delete the old file and rename the new file).
This strategy is the safest concerning consistency, but requires the most temporary space in the destination file system: The maximum total space requirement is a bit more than twice the file size (old file + blocks not yet written to new file + partial new file). Because the blocks are immediately deleted when written to the (partial) new file and the new file is growing while blocks are deleted (it doesn't have the final size immediately), the required space is not 3 times the size, but - as said - only a bit more than twice the size.
socket.connectTimeout
This is the maximum time in milliseconds allowed for establishing a socket connection. If the TCP handshake is not done within this time, an exception is thrown.
The default value is "60000" (1 minute).
This property can only be set in the global configuration (in ${user.home}/.cloudstore/cloudstore.properties).
It is possible to override the setting using the system property cloudstore.socket.connectTimeout.
socket.readTimeout
This is the maximum time in milliseconds the socket waits for incoming data. Thus, the server must be capable of processing and replying within this time.
Note, though, that there are long-running operations, which the server cannot guarantee to be done in a short time (e.g. re-indexing an extremely huge repository). For these, the server will throw a DeferredCompletionException which is transferred to the client instead of the real response. The client can (and should) then repeat the request.
How long the server waits before throwing this DeferredCompletionException, is configurable via the deferrableExecutor.timeout (see below). The socket.readTimeout must be longer than this deferrableExecutor.timeout!
The default value is "300000" (5 minutes).
This property can only be set in the global configuration (in ${user.home}/.cloudstore/cloudstore.properties).
It is possible to override the setting using the system property cloudstore.socket.readTimeout.
deferrableExecutor.timeout
TODO document this!
deferrableExecutor.expiryPeriod
TODO document this!
transientRepoPassword.validityPeriod
TODO document this!
The default value is "3600000" (1 hour).
transientRepoPassword.renewalPeriod
TODO document this!
The default value is "1800000" (30 minutes).
transientRepoPassword.earlyRenewalPeriod
TODO document this!
The default value is "900000" (15 minutes).
transientRepoPassword.expiryTimerPeriod
TODO document this!
The default value is "60000" (1 minute).
updater.downgrade
TODO document this!
updater.enabled
Controls whether the updater is enabled. The updater periodically checks the version on the server and compares it with the version installed locally. If the server's version is newer, it performs an automatic online-update.
The default value is "true".
It is highly recommended to keep this default value, but if you want to make sure that your CloudStore installation never connects to our servers (some people don't like an application to phone home), you can set this to "false".
updater.force
TODO document this!
updater.remoteVersionCache.validityPeriod
TODO document this!
server.securePort
TODO document this!
ldap.url
URL of a server used for LDAP-based authentication.
The default value is ldap://localhost:389.
ldap.bindDnTemplate[${index}]
${index} inside the name of the property is just an integer, which tells in which order templates should be used. First index has to be 0, and all templates have to have consecutive indexes.
Every template should contain one or more of ${login} template variables, which will be replaced with userName, provided by user during authentication. See also LDAP First variant.
Example template: ldap.bindDnTemplate[0] = cn=${login}+sn=secret,ou=users,dc=example,dc=com
ldap.query
LDAP search filter. Every query should contain one or more of ${login} template variables, which will be replaced with userName, provided by user during authentication. Queries are executed as a call to method DirContext#search. During this call ldap.query is used as "filter" parameter, ldap.queryDn as "name" and SUBTREE_SCOPE is added to SearchControls. See also LDAP Second variant.
ldap.adminDn
DN of technical user, which is used to create a context for execution of LDAP queries in LDAP Second variant.
