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 numbers and optionally suffixed by "-", it's converted to an integer.
- If the value is any of those: Yes, yes, True, true, False, false, No, no, 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. It's left alone otherwise.
- 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 another INI file 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
Sync INI files syntax
Here is an example of a full Sync file.
[captcha] use = True public_key = 6Le8OLwSAAAAAK-wkjNPBtHD4Iv50moNFANIalJL private_key = 6Le8OLwSAAAAAEKoqfc-DmoF4HNswD7RNdGwxRij use_ssl = False [storage] backend = sql sqluri = mysql://sync:sync@localhost/sync standard_collections = False use_quota = True quota_size = 5120 pool_size = 100 pool_recycle = 3600 [auth] backend = sql sqluri = mysql://sync:sync@localhost/sync pool_size = 100 pool_recycle = 3600 [smtp] host = localhost port = 25 sender = weave@mozilla.com [cef] use = True file = syslog vendor = mozilla version = 0 device_version = 1.3 product = weave [nodes] node1 = host:db node2 = host:db
XXX
Notes
XX