.ini files

.ini files are used by Synchronet for initialization control, configuration, and data-storage.

Configuration

Synchronet's INI configuration files are typically stored in the ctrl directory, with a .ini filename suffix/extension.

Primary Configuration Files

The primary configuration files managed by the SCFG utility are:

Filename Description
sbbs.ini Synchronet Server Initialization File
main.ini Primary system settings (e.g. BBS name, location, security settings) and command shells
msgs.ini Message areas, message options, and message networking
file.ini File areas (for uploads, download), text file areas, and file-related options
xtrn.ini External program configurations which includes timed events, message editors, hot-key events and doors
chat.ini Chat Features settings, specifically the Guru, Multi-node chat actions and channels, and external sysop pagers
node.ini Located in the node directories, and configured via the SCFG Nodes menu

Secondary Configuration Files

Filename Page Default ContentsDescription
text.ini N/A Customized text.dat strings (optional)
text.lang.ini varies Alternate language text.ini files
cgi_env.ini cgi_env.iniWeb Server CGI Settings
formmail.ini formmail.iniConfiguration for web/formmail.ssjs, Synchronet's Server-side JavaScript version of FormMail
ircbot.ini ircbot.iniConfiguration for IRC robots, optionally works with the Synchronet IRCd
listserver.ini listserver.iniConfiguration for the Synchronet ListServer module (exec/listserver.js)
mailproc.ini mailproc.iniConfiguration of External Mail Processors for the Mail Server (SMTP)
mime_types.ini mime_types.iniMIME File Types registered in the Web Server
modopts.ini modopts.iniConfiguration settings (options) for various JavaScript modules, stock and/or 3rd party
rss.ini rss.iniConfiguration for Synchronet RSS Feed module (web/root/rss.ssjs)
sbbsctrl.ini N/AConfiguration for Synchronet Control Panel (SBBSCTRL) for Windows, exported from Windows Registry
sbbsexec.ini sbbsexec.iniConfiguration for the Synchronet Virtual FOSSIL / UART Driver for Windows
services.ini services.iniConfiguration for Synchronet Services
sexpots.ini N/AConfiguration for Synchronet External POTS Support utility (SEXPOTS)
sexyz.ini N/AConfiguration for Synchronet External X/Y/ZMODEM protocol driver (SEXYZ)
sockopts.ini sockopts.iniConfiguration of TCP/IP socket options
web_handler.ini web_handler.iniConfiguration of special content (file type) handlers for the Web Server
webicons.ini webicons.iniConfiguration of icon files used to represent specific file types in the Web Server

Database

INI files are also sometimes used for data storage (not related to configuration). This is popular with some JavaScript modules. Such files are typically stored in the data or xtrn directory hierarchies. When INI files are used for data storage purposes, they may or may not have a .ini file suffix/extension.

Filenaming

Synchronet supports a variety of configuration files of different formats. A growing majority of these configuration files are of the INI file type. Synchronet's INI files are typically stored in the ctrl directory, with a .ini filename suffix/extension.

All of Synchronet's INI filenames support a flexible naming convention so multi-host BBSes can share the same ctrl directory, but have a subset of unique INI files particular to each host.

This flexible naming takes the normal base filename, for example, ctrl/services.ini, and allows for the local host's name (host name or host.domain name) or platform description (e.g. “linux” or “win32”) to be inserted before the .ini filename suffix/extension.

The order of preference (using ctrl/service.ini as an example base filename) is:

  1. ctrl/services.host.domain.ini
  2. ctrl/services.host.ini
  3. ctrl/services.platform.ini
  4. ctrl/services.ini

NOTE: Only one file is actually used per host.

Case Sensitivity

The INI filenames are not case sensitive.

Syntax

Synchronet uses the XPDEV library for it's INI file parsing and creation. The XPDEV INI file syntax closely matches that of the common use in Windows applications. The basic syntax is:

; INI files are plain text files that may be edited with a common text editor.

; Lines beginning with a semicolon are considered "comments" and are ignored.

; Blank lines are ignored.

; Values are assigned to "keys" with the syntax "keyname=value" on a line by themselves.
 
SomeKey=100
SomeOtherKey=Hello, world.

; Keys are sometimes grouped together into "sections". 
; A "section" begins with the section name enclosed in square-brackets:
[section1]
SectionKey=true

; Additional sections may be included.
; Keys (even with the same name) will not collide with those in other sections:
[section2]
SectionKey=42

The Synchronet/XPDEV INI file format has some minor deviations from the Windows INI format:

Root Section

Some Synchronet INI files support the concept of a root section, that is, a virtual section that consists of a set of key=value pairs in the file before any [section] tags. The root section is typically used for global or default values for other sections in the INI file. In some INI files, the root section is the only supported section and discovery of any [section] tags will terminate the file.

Example:

; This is the top of the file

; This is the root section
RootKey=Value
 
[some section]
;This is a section named "some section" (not the "root section")
SomeSectionKey=Value

Named Sections

All sections in an INI file, except for the Root Section, have a name (or some times, multiple names). Section names are used by application programs and scripts to find the set of keys they are interested in. Section names are not case sensitive.

Section With Multiple Names

A single section may go by more than one section name by separating the names in the [section] tag with a pipe (|) symbol.

Example:

[Mail|Web]
; The keys in this section belong to both the "Mail" and "Web" sections 

Note: Since section names may not be reused in a single .ini file, a single section with more than one name will be the only representation of the named sections and any following section with one of the used names will be ignored.

String Literals

By using a colon character (:) rather than equals sign (=) as a key/value separator, string value with embedded control characters and trailing white-space characters may be specified in .ini files.

Quotes

If the first non-white-space character following the colon key/value separate is a double-quote () character, then the string will be terminated at the last (right-most) double-quote character. This allows a string value to be specified with trailing white-space:

mystring: "a string with trailing white-space "

Escape Sequences

Character values may be specified using C-style character literal escaping for control characters (e.g. \r for carriage-return, \n for line-feed, \x01 for Ctrl-A, etc.) or CP437 characters (e.g. \xb3 for a vertical bar).

Directives

INI file directives must be on a line by themselves and must begin with the ! character.

EOF

A premature end-of-file may be defined by using the !eof directive. No lines after this directive will be parsed by the INI file parser.

Example:

!eof

Include

Some INI files support the embedding of other files using the !include filename directive.

Example:

!include another.ini

In Synchronet v3.18c, the ability to include multiple files was added, e.g.

!include sub-dir/*.ini

Editing

When an INI file must be edited by hand, any good text file editor should work fine.

Line Lengths

Each line in an INI file cannot be more than 2045 characters in length.

Line Termination

Lines may be terminated with a single LF character (Unix style) or CR/LF pair (DOS/Windows style).

Value Lengths

The maximum length of a value that may be assigned to key (e.g. key=value) is 1023 characters.

Value Termination

String values are terminated by a new-line sequence or the end of file.

Trailing white-space is normally removed from the string value, unless the key:value syntax is used (instead of key=value).

Boolean Values

For keys that only support a simple true or false value, the following values will be evaluated as a true value:

  • true (case-insensitive)
  • yes (case-insensitive)
  • on (case-insensitive)
  • Any non-zero number

Any other value will be evaluated as a false value.

Byte Values

For keys that indicate a number of bytes (e.g. of memory, file, or disk), the value may be specified in kilobytes (e.g. 500K), megabytes (e.g. 1.5M), gigabytes (e.g. 16G), terabytes (1T), and exabytes (0.5E).

Enumerated Values

Some keys support values specified either by number (typically from 0 through n) or by a symbolic name for each supported value. These are referred to as enumerated values.

A numeric value higher than the highest supported enumerated value will be treated the same as the highest supported enumerated value.

When a word is provided for the enumerated key value, an exact case-insensitive match is performed search following by a partial-match search, so “Debug” would match the enum value for “Debugging”, and “Info” would match the enum value for “Informational”.

Log Levels

LogLevel keys are one example of a key with enumerated values. The LogLevel value may be specified as a decimal number (from 0 to 7) or by specifying one of the following enumerated names:

Value Name
0 Emergency
1 Alert
2 Critical
3 Error
4 Warning
5 Notice
6 Informational
7 Debugging

Log entries with a log level higher than the specified LogLevel value will not be logged/displayed.

The Debugging (7) log level enables all possible log output.

Bit-field Values

Some key values may be specified as a series of numeric values separated by the | (ASCII 124) character. The numeric values may be specified with the literal decimal or hexadecimal value or, more commonly, using a representative name. The individual values are bit-wise OR'd together to produce the end result for the key value.

Options

Options keys are one example of a key with a bit-field value. The value is usually made up of one or more option names separated by the | character. Which option names are supported depends on which section the Options key is located.

Common Options (e.g. from the sbbs.ini file) include:

  • NO_HOST_LOOKUP
  • NO_RECYLCE
  • NO_JAVASCRIPT
  • GET_IDENT
  • MUTE

These could be specified in a .ini file like so:

Options = NO_HOST_LOOKUP | NO_RECYCLE | GET_IDENT

Source Code

Synchronet's INI file support comes from the XPDEV C library. The main source file is https://gitlab.synchro.net/sbbs/sbbs/-/blob/master/src/xpdev/ini_file.c.

See Also

config/ini_files.txt · Last modified: 2023/10/26 17:21 by digital man
Back to top
CC Attribution 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0