====== Synchronet IRCd — Annotated ircd.ini Reference ======

This is an annotated sample ''ircd.ini'' for the Synchronet IRC daemon.  The
config file is usually maintained with the interactive editor:

  jsexec ircdcfg.js

Lines beginning with '';'' are comments and are ignored by the server.

If you are still running the older colon-delimited ''ircd.conf'', convert it
with:

  jsexec ircd_conf2ini.js

With no arguments it finds the ''ircd.conf'' the IRCd would have used, writes
the equivalent ''.ini'' beside it, and keeps the original as ''.bak''.  It
re-reads what it wrote and compares it against the ''.conf'' entry by entry,
and leaves the original in place if anything failed to survive the trip.  It
also reports settings the two formats express differently — Z:lines, masks
that can never match, and ''[Allow]'' entries shadowed by a broader one above
them.  Both formats remain supported; the ''.ini'' is preferred.

Placeholders such as ''SYSTEM_HOST_NAME'' survive the conversion unchanged —
see **[Info]** below.

The section name before the colon is the section type; the value after the
colon is a label used to distinguish multiple sections of the same type (e.g.
''[Allow:1]'', ''[Allow:2]'').  Labels on most section types are arbitrary
strings, but ''[Class:N]'' and ''[Port:N]'' use the actual class number / port
number as the label.

-----

===== [Info] — Server identity =====

Equivalent to the classic **A:line** and **M:line**.  Provides the server's
name on the IRC network, a short description, and contact information shown
when users run ''/ADMIN''.

^ Key ^ Description ^
| ''Servername'' | Fully-qualified server name as it appears on the IRC network.\\ Defaults to ''<qwkid>.synchro.net''. |
| ''Description'' | One-line description of the server. |
| ''Admin1'' | First line of ''/ADMIN'' output.  Usually the BBS name. |
| ''Admin2'' | Second line.  Typically software or system info. |
| ''Admin3'' | Third line.  Typically the sysop contact e-mail. |

<file ini>
[Info]
Servername=mobbs.synchro.net
Description=My Own BBS
Admin1=My Own BBS (MOBBS)
Admin2=Synchronet BBS for Linux
Admin3=Sysop - <sysop@myownbbs.com>
</file>

== System macros ==

Any value in the file may contain these placeholders, which the server
replaces as it reads the file.  The legacy ''ircd.conf'' template uses them,
so a converted file will contain them; they are equally valid typed by hand:

^ Macro ^ Replaced with ^
| ''SYSTEM_HOST_NAME'' | The system's host name, as set in SCFG.  ''jsexec -h'' overrides it for that instance. |
| ''SYSTEM_NAME'' | The BBS name. |
| ''SYSTEM_QWKID'' | The QWK-ID, in lower case. |
| ''VERSION_NOTICE'' | The Synchronet version notice. |

Leaving them in place keeps the file portable: one ''ircd.ini'' can be shared
by several hosts and each will identify itself correctly.  ''ircdcfg.js'' and
''ircd_conf2ini.js'' preserve the macros rather than substituting the values
of whichever host was running when the file was written.

<file ini>
[Info]
Servername=SYSTEM_HOST_NAME
Description=SYSTEM_NAME
Admin1=SYSTEM_NAME (SYSTEM_QWKID)
Admin2=VERSION_NOTICE
Admin3=Sysop- <sysop@SYSTEM_HOST_NAME>
</file>

-----

===== [Port:N] — Listening ports =====

Equivalent to the classic **P:line**.  Each section opens a TCP port for
incoming IRC connections.  The label ''N'' is the port number.

^ Key ^ Description ^
| ''Default'' | Set to ''true'' on exactly one port — this becomes the server's primary port, reported in ''/STATS p'' and used for outbound server connections when no port is specified. |
| ''SSL'' | Cosmetic annotation only — **SSL is not controlled by this field**.  The server automatically enables TLS on connections accepted on ports **994** and **6697**; all other ports are plain-text regardless of this setting. |

** NOTE: ** Only ports **994** and **6697** will use TLS.  Setting ''SSL=true'' on any
other port has no effect.  Setting ''SSL=false'' on 994 or 6697 also has no
effect — those ports will still negotiate TLS. This will be fixed in a later release.

<file ini>
[Port:6667]
Default=true
SSL=false

[Port:6697]
SSL=true

[Port:994]
SSL=true

[Port:7000]
SSL=false
</file>

-----

===== [Capab] — Capability enforcement =====

Controls whether the server enforces the **TSJOIN** capability when linking
to other Synchronet IRCd servers.  TSJOIN signals support for channel
timestamp enforcement, SJOIN origin validation, and nick-collision handling.
This is only required on hub servers and is not necessary on a leaf.

A link that does not advertise TSJOIN always produces a warning in the log
and an operator notice, whether or not enforcement is on.  Servers listed in
a ''[Services]'' section are exempt from the check entirely.

^ Key ^ Description ^
| ''Enforce'' | ''true'' = refuse links from servers that do not advertise TSJOIN.\\ ''false'' (default) = warn, but allow the link. |

When new capacities are added to the IRCd that require older versions to upgrade to avoid network issues, there will usually be a grade period announced before enforcing is turned on.
<file ini>
[Capab]
Enforce=false
</file>

-----

===== [Class:N] — Connection classes =====

Equivalent to the classic **Y:line**.  Connection classes group clients and
server links, controlling ping intervals, reconnect behaviour, connection
limits, and send queue sizes.  The label ''N'' is the class number referenced
by ''[Allow]'', ''[Operator]'', and ''[Server]'' sections.

^ Key ^ Description ^
| ''Comment'' | Free-text note describing the class — for the sysop's reference only. |
| ''PingFrequency'' | How often (in seconds) the server sends a PING to connections in this class to verify they are still alive. |
| ''ConnectFrequency'' | For server classes: how often (in seconds) a **leaf** will attempt to reconnect to its hub after a lost connection.\\ Set to ''0'' to disable automatic reconnection (required for hub classes — a hub must never initiate a connection to a leaf). |
| ''Maximum'' | Maximum number of simultaneous connections allowed in this class.\\ For server classes this limits how many servers of this class may link simultaneously — set it large enough for all expected leaf nodes.\\ ''0'' means unlimited. |
| ''SendQ'' | Maximum bytes allowed to queue unsent in a single connection before that connection is forcibly closed with "SendQ exceeded".  A large SendQ is important for server links, which can burst large amounts of data during a network join. |

Suggested class layout:

^ Class ^ Purpose ^
| 1 | Regular clients connecting with their own IRC software |
| 2 | BBS users connecting via the built-in IRC client |
| 10 | IRC operators |
| 30 | Leaf server → hub outbound link |
| 35 | Hub → leaf (hub accepts inbound only, leaf initiates) |
| 40 | Hub ↔ hub links |
| 50 | Hub → QWK master (vert, cvs) |

<file ini>
[Class:1]
Comment=Regular, unprivileged users
PingFrequency=120
ConnectFrequency=0
Maximum=100
SendQ=1000000

[Class:2]
Comment=BBS users
PingFrequency=30
ConnectFrequency=0
Maximum=100
SendQ=10000000

[Class:10]
Comment=IRC operators
PingFrequency=400
ConnectFrequency=0
Maximum=100
SendQ=10000000

[Class:30]
Comment=Servers only, Leaf->Hub
PingFrequency=60
ConnectFrequency=300
Maximum=1
SendQ=150000000

[Class:35]
Comment=Server > Hub (hub-side, accepts inbound only)
PingFrequency=60
ConnectFrequency=0
Maximum=10
SendQ=150000000

[Class:40]
Comment=Servers only, Hub->Hub
PingFrequency=90
ConnectFrequency=60
Maximum=10
SendQ=200000000

[Class:50]
Comment=Servers only, Hub->QWK (vert, cvs)
PingFrequency=90
ConnectFrequency=60
Maximum=1
SendQ=200000000
</file>

-----

===== [Allow:N] — Client authorization =====

Equivalent to the classic **I:line**.  Assigns connecting clients to a
connection class.  The server checks ''[Allow]'' sections in the order they
appear in the config file and uses the **first match**.  More specific entries
must appear **before** more general ones — put the catch-all ''*@*'' entry last.

^ Key ^ Description ^
| ''Mask'' | Comma-separated list of ''user@host'' masks.  Both IP address and resolved hostname forms are checked; a client must match both.  Wildcards (''*'', ''?'') are supported. |
| ''Password'' | Optional.  If set, the client must supply this password in their IRC client's server password field.  Stored and compared as **plain text**. |
| ''Port'' | Optional.  If set, this Allow entry only matches clients who connected on this specific port.  Useful for separating TLS and plain-text connections into different classes.  Omit or set to ''0'' for any port. |
| ''Class'' | The class number (from ''[Class:N]'') to assign matched connections to. |

<file ini>
; BBS localhost and known hostnames get class 2 (BBS users)
[Allow:2]
Mask=*@127.0.0.1,*@mobbs.synchro.net,*@myownbbs.com
Class=2

; Everyone else gets class 1 (regular users) — must be last
[Allow:1]
Mask=*@*
Class=1
</file>

-----

===== [Operator:name] — IRC operators =====

Equivalent to the classic **O:line**.  Defines who may use the ''/OPER''
command and what privileges they receive.  The label is a descriptive name for
this operator entry. An example of how to gain your operator privileged would be ''/OPER sysop sysoppass''
where sysoppass is your BBS sysop password.

^ Key ^ Description ^
| ''Nick'' | The oper name the user types in ''/OPER <nick> <password>''.\\ Use ''Sysop'' (case-insensitive) combined with flag ''S'' to authenticate against the BBS sysop password instead of a stored password. |
| ''Mask'' | Comma-separated list of ''user@host'' masks.  The connecting user must match one of these or the ''/OPER'' attempt is rejected, providing an extra layer of security. |
| ''Password'' | Plain-text password.  Not used when flag ''S'' is set, and may be omitted entirely in that case. |
| ''Flags'' | A string of flag characters controlling what the oper is permitted to do (see table below). |
| ''Class'' | Connection class to switch to upon successful ''/OPER''. |

== Operator Flags ==

Two shorthand flags cover the most common configurations:

^ Flag ^ Meaning ^
| ''o'' | **Local operator** — grants: rehash, globops, wallops, locops, local SQUIT/CONNECT, local KILL, KLINE/UNKLINE, local server notices, umode +c |
| ''O'' | **Global operator** — everything ''o'' grants, plus: global SQUIT/CONNECT, global KILL, global server notices, chatops |

Individual flags for fine-grained control:

^ Flag ^ Privilege ^
| ''r'' | REHASH — reload config without restarting |
| ''R'' | RESTART — restart the IRCd process |
| ''D'' | DIE — shut down the IRCd |
| ''g'' | GLOBOPS — send a global operator message |
| ''w'' | WALLOPS — send a wallops message |
| ''l'' | LOCOPS — send a local operator message |
| ''c'' | Local SQUIT / CONNECT |
| ''C'' | Global SQUIT / CONNECT |
| ''k'' | Local KILL |
| ''K'' | Global KILL |
| ''b'' | KLINE (add ban) |
| ''B'' | UNKLINE (remove ban) |
| ''n'' | Local server notices |
| ''N'' | Global server notices |
| ''u'' | Set umode +c (see client connect/disconnect notices) |
| ''A'' | Mark as IRC administrator |
| ''s'' | CHATOPS |
| ''S'' | Authenticate using the **BBS sysop password** instead of ''Password='' |
| ''x'' | JavaScript eval access — **use with extreme caution** |

<file ini>
[Operator:sysop]
Nick=Sysop
Mask=*@127.0.0.1,*@mobbs.synchro.net,*@myownbbs.com
; S flag means /oper uses the BBS sysop password — no Password= needed
Flags=oS
Class=10

; Example of a remote oper with an explicit password
;[Operator:remoteop]
;Nick=RemoteOp
;Mask=*@trusted.host.example.com
;Password=s3cr3t
;Flags=o
;Class=10
</file>

-----

===== [Services:name] — Services servers (U:lines) =====

Equivalent to the classic **U:line**.  Servers listed here are trusted as
services (e.g. NickServ, ChanServ) and are exempt from normal mode and KICK
enforcement — they may set modes and kick users without holding channel ops.
The label is a descriptive name.

Two servers are always implicitly trusted and do not need entries here:
''services.synchro.net'' and ''stats.synchro.net''.

^ Key ^ Description ^
| ''Servername'' | The IRC server name of the services server to trust. |

<file ini>
;[Services:myservices]
;Servername=services.example.synchro.net
</file>

-----

===== [Ban:name] — Banned hosts/users (K:lines) =====

Equivalent to the classic **K:line**.  Permanently prevents matching
connections from being accepted.  Bans can also be added and removed at
runtime with ''/KLINE'' and ''/UNKLINE'' by operators with the appropriate
flags, however they will be lost when a server restarts unless added to the
ircd.ini file.  The label is a descriptive name for this ban entry.

^ Key ^ Description ^
| ''Mask'' | Comma-separated list of masks to ban.  Format is ''user@host''.  The tilde prefix (''~'') means "ident not confirmed" — use ''~*'' to match unidentified users.  Wildcards are supported. |
| ''Reason'' | Message shown to the client when their connection is refused. |

<file ini>
;[Ban:whitehouse]
;Mask=*@whitehouse.gov,~*@*.whitehouse.gov
;Reason=I doubt someone's using IRC from the White House.

;[Ban:noroot]
;Mask=~root@*
;Reason=Don't IRC as root.

;[Ban:badip]
;Mask=*@0.0.0.0,*@255.255.255.255
;Reason=Bogus IP address tried to connect??
</file>

-----

===== [Restrict:name] — Reserved nicks (Q:lines) =====

Equivalent to the classic **Q:line**.  Prevents the listed nick masks from
being used by regular users.  Useful for reserving service bot names.
The label is a descriptive name.

Two nick masks are always reserved automatically: ''*Serv'' and the server's
own name.

^ Key ^ Description ^
| ''Mask'' | Comma-separated list of nick masks to reserve.  Wildcards supported. |
| ''Reason'' | Reason shown when a user tries to use a restricted nick. |

<file ini>
;[Restrict:services]
;Mask=NickServ,ChanServ,MemoServ,OperServ
;Reason=Reserved for network services.

;[Restrict:bots]
;Mask=*Bot,*Serv
;Reason=Reserved nick pattern.
</file>

-----

===== [RBL:name] — DNS Blacklists =====

Configures Realtime Blackhole Lists (DNS-based block/allow lists) checked
against each incoming connection's IP address before they are allowed onto the
server.  A ''Hostname'' is required.  The label is a descriptive name.

** NOTE: ** Every server connecting to the Synchronet IRC Network should have at least
one RBL listed. This helps protect against bad actors trying to disrupt the network. 

If no ''BadResponses'' or ''GoodResponses'' is specified, **any** DNS response
from the RBL causes the connection to be blocked.

^ Key ^ Description ^
| ''Hostname'' | The RBL DNS zone to query (e.g. ''dnsbl.dronebl.org''). |
| ''BadResponses'' | Optional.  Comma-separated list of IP addresses.  If the RBL query returns one of these, the connection is **blocked**.  Any other response (or no response) allows the connection. |
| ''GoodResponses'' | Optional.  Comma-separated list of IP addresses.  If the RBL query returns one of these, the connection is **allowed**.  Any other response (or no response — meaning the IP is not on the whitelist) **blocks** the connection. |

<note>
''BadResponses'' and ''GoodResponses'' are mutually exclusive per entry.
Use ''BadResponses'' for traditional blocklists where specific return codes
indicate bad actors.  Use ''GoodResponses'' for DNS whitelists where a
positive response means the IP is trusted.
</note>

<file ini>
; Block all IPs listed in DroneBL (any response code = block)
[RBL:dronebl]
Hostname=dnsbl.dronebl.org

; Block only specific DroneBL response codes (open proxies and botnets)
;[RBL:dronebl-selective]
;Hostname=dnsbl.dronebl.org
;BadResponses=127.0.0.9,127.0.0.10

; DNS whitelist: only allow IPs that appear in the whitelist
;[RBL:whitelist-example]
;Hostname=whitelist.example.com
;GoodResponses=127.0.0.1
</file>

-----

===== [WebIRC:name] — WebIRC gateways =====

Equivalent to the classic **W:line**.  Allows a trusted WebIRC gateway (such
as Kiwi IRC or The Lounge) to pass the real client IP address to the server
via the ''WEBIRC'' command.  Without this, all WebIRC users appear to connect
from the gateway's IP.  The label is a descriptive name.

^ Key ^ Description ^
| ''Hostname'' | IP address or hostname of the trusted gateway. |
| ''Password'' | Shared secret that the gateway sends in its ''WEBIRC'' command.  Stored and compared as **plain text**. |

<file ini>
;[WebIRC:kiwiirc]
;Hostname=192.168.1.100
;Password=sharedgatewaysecret
</file>

-----

===== [Server:name] — Server links =====

Equivalent to the classic **C:line** (outbound connect) and **N:line**
(inbound accept) combined.  Defines a peering relationship with another IRC
server.  The label is a descriptive name for this link.

^ Key ^ Description ^
| ''Servername'' | The IRC server name of the remote server (e.g. ''otherbbs.synchro.net''). |
| ''Hostname'' | IP address or hostname used to reach the remote server for outbound connections. |
| ''Password'' | Shared password used for both inbound and outbound authentication.  Use ''InboundPassword'' and ''OutboundPassword'' instead if the two sides use different passwords. |
| ''InboundPassword'' | Password the remote server must send when connecting to us. |
| ''OutboundPassword'' | Password we send when connecting to the remote server. |
| ''Port'' | Port to connect to on the remote server for outbound connections.\\ ''0'' or omitted means this server only accepts inbound connections from the remote (hub-side entry). |
| ''Hub'' | ''true'' = the remote server is a hub and may introduce other servers.\\ ''false'' = the remote is a leaf and may not introduce other servers. |
| ''Class'' | Connection class to use for this server link. |
| ''Flags'' | Optional flags for QWK-related server types (see below). |

** NOTE: ** A server cannot link to itself.  A ''[Server]'' section whose
''Servername'' is this server's own name is reported at startup and ignored,
and an incoming link presenting this server's name is refused.  Watch for this
after changing ''Servername'' in **[Info]**, which can turn a valid link into a
self-reference.

== Server Flags ==

These flags apply only to QWK-based server links:

^ Flag ^ Meaning ^
| ''q'' | Authenticate this server link using the remote BBS's QWK password. |
| ''w'' | This remote server is a QWK master hub. |
| ''k'' | Verify this server's credentials with the QWK master before accepting the link. |

<file ini>
; Leaf server entry — we (the leaf) connect outbound to the hub
; Use class 30 on the leaf side.
;[Server:synchro-hub]
;Servername=cvs.synchro.net
;Hostname=cvs.synchro.net
;Password=secretpassword
;Port=6667
;Hub=true
;Class=30

; Hub-side entry for the same link — hub accepts inbound only (Port=0)
; Use class 35 on the hub side.
;[Server:myleaf]
;Servername=eotlbbs.synchro.net
;Hostname=bbs.endofthelinebbs.com
;Password=secretpassword
;Port=0
;Hub=false
;Class=35

; Hub-to-hub link — both sides may initiate
;[Server:otherhub]
;Servername=otherhub.synchro.net
;Hostname=otherhub.synchro.net
;InboundPassword=theysendusthis
;OutboundPassword=wesendthem this
;Port=6667
;Hub=true
;Class=40
</file>

-----

===== [Hub:name] — Hub declarations =====

Equivalent to the classic **H:line**.  Explicitly marks a server as a hub,
allowing it to introduce other servers into the network.  This is an
alternative to setting ''Hub=true'' in a ''[Server:]'' section — useful when
you want to grant hub status without also defining a connect entry.  The label
is a descriptive name.

^ Key ^ Description ^
| ''Servername'' | The IRC server name to grant hub status to. |

<file ini>
;[Hub:synchro-hub]
;Servername=cvs.synchro.net
</file>



===== See Also =====
  * [[:config:|config index]]

{{tag>}}
