Table of Contents
New Config Files (introduced in v3.20)
Synchronet v3.20 introduces a new primary configuration file format using
ini file syntax. Sysops can upgrade a Synchronet v3.1x configuration to
v3.20 by running 'jsexec upgrade_to_v320.js' either before (preferably) or
after upgrading their Synchronet executable binary files to v3.20.
update.js included with Synchronet v3.20 (invoked with 'jsexec update') will automatically invoke the 'upgrade_to_v320.js' as needed.
ctrl/*.cnf files are converted one-to-one to
Are all configurations settings converted?
With the exception of a few never-used or no-longer-used configuration fields,
.cnf files should be completely represented by the newly created
files. Once converted, the old
.cnf files will no longer be used and may be
deleted if desired. If you're weary of the upgrade process, keep those old
.cnf files around so that you can revert to Synchronet v3.1x if needed or
even re-convert the
.cnf files by executing
upgrade_to_v320.js again if/when
any issues in the script have been found and fixed later.
Why the change?
.cnf files were introduced in Synchronet v2.0 back in 1994.
.cnf files were designed for fast-loading: structured binary files with
fixed length records comprised of fixed length fields (configuration
properties) in a fixed order. Unfortunately, this lack of flexibility means it
has also been an ongoing-challenge to add new configuration fields or extend
the size of existing configuration fields. Most records included “padding”
bytes for future expansion, but the future is now past and most of those bytes
were consumed with new and expanded configuration fields; we've consumed the
growth budget of most of the configuration records already. Now it'll be much
easier to add new configuration fields and extend the size of existing fields
when desired (e.g. no more 8-character internal code suffix limits!).
Additionally, it has been a challenge to keep track of changes to the stock
configuration files stored in the Synchronet source code repository. Revision
control systems (e.g. CVS, Git) can track changes in text files much better
than changes to binary files. Moving to text-based configuration files
remedies this change management issue and allows sysops to easily search and
compare the contents of Synchronet configuration files (e.g. comparing with
backed-up or stock/original versions of
.cnf file has now been replaced with an equivalent
containing LF or CRLF-terminated lines of ASCII text conforming to the
.ini file syntax.
Interestingly, Synchronet v1 also used text configuration (
*.cfg) files for
the vast majority of its configuration settings, however the format was not as
.ini and the large
.cfg files were slow to load.
The flexible format of
.ini files does mean that they take more compute
(and time) to parse than fixed-structure (e.g.
.cnf) files, but through
better programming and the power of modern computers, the difference should be
Although the new
.ini files can be directly edited using pretty much any plain-text
editor, the primary supported method of manipulating these
files is via the Synchronet Configuration Utility (SCFG). Any manually
added comments (lines beginning with a semicolon) or white-space changes will
be lost when the file is subsequently edited using SCFG. Unlike other
Synchronet initialization files (e.g.
sbbs.ini), there's been no effort made
to make these new configuration files particularly easy to read (e.g. optional
comments, named bits for bit-fields) and no effort made to maintain the exact
key ordering or formatting used during any manual edits of the files. If a
sysop chooses to make manual edits, they should either no longer use SCFG or
be okay with the idea that the files will be completely re-formatted
when subsequently edited with SCFG.
.ini file format was chosen because this is already a first class data
file format in Synchronet, supported equally well in the C/C++ code and
the pros and cons were weighed, and
Thanks to mcmlxxix for his cnflib.js load library that made this configuration
migration (the creation of
upgrade_to_v320.js) relatively painless as
Synchronet v3.20 maintains no knowledge of or ability to parse