All services on a Sync server share a common configuration. Here's a format proposal for a unique configuration file that can be used to group this configuration.

Syntax

The configuration file is a ini-based file. (See http://en.wikipedia.org/wiki/INI_file for more details.) Variables name can be assigned values, and grouped into sections. A line that starts with "#" is commented out. Empty lines are also removed.

Example:

 [section1]
 # comment
 name = value
 name2 = "other value"
 [section2]
 foo = bar

Ini readers in Python, PHP and other languages understand this syntax. Although, there are subtle differences in the way they interpret values and in particular if/how they convert them.

Values conversion

Here are a set of rules for converting values:

- If value is quoted with " chars, it's a string. This notation is useful to include "=" characters in the value. In case the value contains a " character, it must be escaped with a "\" character.

- When the value is composed of digits and optionally prefixed by "-", it's tentatively converted to an integer or a long depending on the language. If the number exceeds the range available in the language, it's left as a string.

- If the value is "true" or "false", it's converted to a boolean, or 0 and 1 when the language does not have a boolean type.

- A value can be an environment variable : "${VAR}" is replaced by the value of VAR if found in the environment. If the variable is not found, an error must be raised.

- A value can contains multiple lines. When read, lines are converted into a sequence of values. Each new line for a multiple lines value must start with a least one space or tab character.

Examples:

 [section1]
 # comment
 a_flag = True
 a_number = 1
 a_string = "other=value"
 another_string = other value
 a_list = one
          two
          three
 user = ${USERNAME}

Extending a file

An INI file can extend another file. For this, a "DEFAULT" section must contain an "extends" variable that can point to one or several INI files which will be merged to the current file by adding new sections and values.

If the file pointed in "extends" contains section/variable names that already exist in the original file, they will not override existing ones.

file_one.ini:

 [section1]
 name2 = "other value"
 [section2]
 foo = baz
 bas = bar

file_two.ini:

 [DEFAULT]
 extends = file_one.ini    
 [section2]
 foo = bar

Result:

 [section1]
 name2 = "other value"
 [section2]
 foo = bar
 bas = bar

To point several files, the multi-line notation can be used:

 [DEFAULT]
 extends = file_one.ini
           file_two.ini

When several files are provided, they are processed sequentially. So if the first one has a value that is also present in the second, the second one will be ignored. This means that the configuration goes from the most specialized to the most common.

Sync INI files syntax

Here is a documented example of a full Sync file. This Sync file uses Memcached+MySQL for the storage backend, and LDAP for the authentication.

#
# Captcha configuration for the user account creation
#
[captcha]

# if set to false, all operations will be done w/ captcha
use = true

# public and provate key for reCaptacha
public_key = 6Le8OLwSAAAAAK-wkjNPBtHD4Iv50moNFANIalJL
private_key = 6Le8OLwSAAAAAEKoqfc-DmoF4HNswD7RNdGwxRij

# if set to true, will use SSL when connection to recaptcha
use_ssl = false

[storage]

# backend used for the storage
# existing backends : sql, memcached
backend = memcached

# memcached servers (multiple server allowed)
cache_servers = 127.0.0.1:11211

# uri for the DB. see RFC-1738
#   driver://username:password@host:port/database
#
# supported drivers: sqlite, postgres, oracle, mssql, mysql, firebird
#
sqluri = mysql://sync:sync@localhost/sync

# if set to true, the server will use hardcoded values for collections
standard_collections = false

# if set to false, users will not have any quota
use_quota = true
# quota size in KB
quota_size = 5120

# Define the size of the SQL connector pool
pool_size = 100

# time in ms to recycle a SQL connection that was closed
pool_recycle = 3600

[auth]
# backend used for the auth
# existing backends : ldap, sql, dummy
backend = ldap

# location of the ldap server
ldapuri = ldap://localhost

# if set to true, initiates a tls
use_tls = false

# user for common ldap operation
bind_user = "cn=admin,dc=mozilla"
bind_password = admin

# user with extended rights for write operations
admin_user = "cn=admin,dc=mozilla"
admin_password = admin

# root for all the users
# if set to "md5", will generate a specific location
# based on the hash of the user name so users are
# spread across several nodes.
#
# otherwise, all users will be under the same node
users_root = "ou=users,dc=mozilla"

# uri for the DB. see RFC-1738
#   driver://username:password@host:port/database
#
# supported drivers: sqlite, postgres, oracle, mssql, mysql, firebird
#
# SQL is used for the reset codes
sqluri = mysql://sync:sync@localhost/sync
pool_size = 100
pool_recycle = 3600

# cache server used by the ldap connector
cache_servers = 127.0.0.1:11211

#
# smpt host used to send e-mails
#
[smtp]
host = localhost
port = 25
sender = weave@mozilla.com

#
# CEF logger
#
[cef]
# if set to false, no CEF log will be emited
use = true

# where to log. can be a file or "syslog"
file = syslog

# CEF arguments for the logs - see CEF documentation
vendor = mozilla
version = 0
device_version = 1.3
product = weave

You can get an up-to-date version of this file at : http://bitbucket.org/tarek/sync-server/src/tip/etc/memcachedldap.conf

Implementations

There's one implementation in the core package of the Python server, but it could be moved to a standalone distribution if another project wants to use it.

http://bitbucket.org/tarek/sync-core/src/tip/synccore/config.py