About this document
First and foremost, this document is intended to be an absolute reference regarding the Synchronet IRCd. This document should be the first place to look if you're having a problem of some kind, regardless of what that problem may be. It intends to be an installation guide which will aide you through setting up your own IRCd. Or, if you're simply curious about the IRCd from a theoretical standpoint (it's not every day that you get to see an IRC daemon as functional as this implemented inside of a scripting language), this document will do its best to explain certain implementation decisions to you.
What this document won't accomplish
This document is not a replacement for your brain. If you're having a problem of some kind, and it's not covered by this document, PLEASE take a few hours to think about the problem and solve it. Use a systematic approach to the problem; “If I do X, does Y still happen?” Remember, installation and maintenance of the Synchronet IRCd isn't life or death, it's a hobby, and like all good hobbies, you're supposed to learn something from it. So, take a few days before you even consider asking for support – take a deep breath, go jog around the block, turn off the computer – and then come back later. On the other hand, if you've found a unique or interesting solution to your problem, and it hasn't been covered here, then by all means tell us about it!
We don't intend to teach you the basics of IRC here. While you can certainly still get the Synchronet IRCd up and running with a minimal amount of effort and IRC knowledge, your experience will be more enjoyable if you have at the very least a working knowledge of IRC. If you don't understand some of the terminology used in this document, then it's best that you go to http://www.irchelp.org and read through their very helpful documents about IRC. This way, you'll gain a better understanding about what IRC really is, what it's here for, the terminology, and a little history, too. At the very least, this is so that when someone asks you to edit your 'M:Line' to solve or diagnose a problem, you'll at least know what they're talking about. We don't cover any IRC basics in this document.
Don't be surprised if you're ignored or simply referred to a URL without further explanation if you ask for help and refer to an IRC *channel* as a room, call *IRC operators* 'cops', don't understand why a 10 second 'ping' time is bad, or not know how to DCC SEND a file (such as your ircd.conf) to be inspected. That includes not having your NAT or proxy set correctly to properly masquerade your IP address on a DCC CTCP.
In short, this document assumes that you know:
- How to use your computer and operating system effectively.
- The basics of IRC and its terminology.
- How to use, configure, and make basic modifications to Synchronet.
- The basics of the Internet (or at least the ability to visualize a routed, distributed network)
The Synchronet IRCd has been included in all default installs of Synchronet BBS since 3.11. If you're running an older version of Synchronet, and want to run the IRCd, then you need to upgrade.
By default, the Synchronet IRCd is installed as a service. It should already be present in your “services.ini” file inside the BBS 'ctrl' directory. The IRCd will automatically start when you start your BBS. The default entry for the IRCd inside of services.ini looks like this:
[IRC] Port=6667 Options=STATIC | LOOP Command=ircd.js
The 'maximum clients' value used inside of the services configuration is *ignored* by Synchronet Services since that value is managed by the IRCd itself. The maximum number of IRC clients can be changed on a Y:Line in your ircd.conf, and is set to 100 by default (more on the ircd.conf later.)
Take a look at your ircd.conf, and familiarize yourself with the options and terminology. Although the ircd.conf has been specifically made so that it works right out of the box, you may wish to tweak some options. The configuration file is self-documenting, so you should carefully read about each of the configuration options. At the very least, this will familiarize you with what a 'Z:Line' is, and where a 'K:Line' is, or how to enable passwords on sensitive IRC commands. If you intend to link to the Synchronet IRC Network, pay careful attention to where the C:Line and N:Line pair is configured. We'll be dealing with those later.
If you're already familiar with other IRC daemon configuration files, the Synchronet ircd.conf has been carefully engineered to be compatible with the Bahamut ircd.conf. Thus, if you've already got a working Bahamut configuration, putting that ircd.conf in place of the stock ircd.conf should give you an IRCd configured exactly the way it was on Bahamut. Configuration files from other IRC daemons have *not* been tested, so your mileage may vary with those (although the configuration should be very similar.) Certainly if you find an ircd.conf from another daemon that works, let us know about it!
You will know if the IRCd has started successfully if you see entries like this in your BBS log:
srvc 0007 IRC SynchronetIRCd-1.1b(1.102) started. srvc 0007 IRC Reading Config: /sbbs/ctrl/ircd.conf
You may have to scroll up to see the message. Any errors should be self-explanatory (and usually involve not being able to read the configuration file.) If you get an error about not being able to bind to a socket, or that a socket is already in use, then you already have something running on the port you defined in your services configuration. Could it be another IRC server running? Try disabling any other IRC servers or proxies and restart the BBS. If you recently restarted Synchronet with users connected to an already operating IRCd, then it's likely that some of your sockets are in a 'TIME_WAIT' state. Wait a minute or two for the condition to clear up, then try again. Repeat this process of elimination until your IRCd starts successfully.
Test your new IRCd by connecting to it with an IRC client. At the very least, using 'telnet' to connect to the IRCd port (port 6667 by default) should give you something similar to the following line:
:rrx.synchro.net NOTICE * :*** SynchronetIRCd-1.1b(1.102) (RoadRunner X) Ready.
This is the standard Synchronet IRCd banner, informing you that the IRCd is accepting new connections correctly.
At this point, you should have a working, fully-functional IRC server available for users to use. You may want to point Synchronet's internal IRC client to your local IRC server (just 'localhost' or '127.0.0.1'), so that your BBS users will be able to make use of your new IRCd. By default, an O:Line has been added so that anyone connecting either from the BBS itself, or your internal network will be able to make use of the /OPER command to become an IRC Operator. To become an IRC Operator, first /WHOIS yourself to make sure that your hostname is your local BBS's hostname (i.e. mybbs.synchro.net) If so, execute '/OPER Sysop <pass>', where <pass> is your local BBS system password. If your hostname isn't the local BBS's hostname, go ahead and edit ircd.conf (in the Synchronet 'ctrl' directory) and add an O:Line for your hostname as directed by the instructions inside of the configuration file.
Linking to the Synchronet IRC Network (irc.synchro.net)
Connecting your IRC server to the Synchronet IRC Network has certain advantages. The best advantage is that you'll be allowing any users who use your IRC server (i.e. your BBS users) to also talk to other users on the network. Since the network is largely BBS-oriented, there are a wide variety of channels available for users to join and discuss various topics. Furthermore, you'll be offering your system to the pool of IRC servers available for the public to use. Just like how DOVE-Net is a network of Synchronet systems that pass message group messages to one another, the Synchronet IRC Network is a network of Synchronet systems for the purposes of chatting in realtime.
Linking with the Synchronet IRC Network takes about as much time (if not less) as it does to establish a DOVE-Net node. Therefore, the procedures have been kept very similar. The Synchronet IRC Network is the only IRC network in the world that allows you to link without going through a tiresome application process, or other such bureaucracy. In fact, no network admin need be present at all for you to link to the Synchronet IRC network.
Just as with establishing a DOVE-Net node, the following steps must be taken to ensure a smooth link to the Synchronet IRC Network:
(1) Ensure that you have a DOVE-Net node established. Although you aren't required to be a member of DOVE-Net to be a member of the Synchronet IRC Network, you need to at least go through the same automatic registration process to obtain and configure your QWK-ID. Instructions about obtaining your QWK-ID can be found here: http://www.synchro.net/docs/dove-net.txt Only steps 1 and 2 need be followed, but heed the document's warning: “Remember the password you used to create this account, you'll need it later.” You do not need to create a new QWK-ID for the IRCd if you already have an existing one for DOVE-Net.
(2) Setup the “dyndns.js” module with your appropriate QWK-id information so that the hostname “mybbs.synchro.net” will point towards your correct IP address. This is required so that users who try to reach your IRC server will be able to resolve the hostname used on the IRC network. That way, if anyone wishes to connect to your server/BBS specifically, they'll be able to use “mybbs.synchro.net” (i.e. if your server happens to be faster, closer, or offers interesting BBS features.) The dyndns.js module comes with Synchronet 3.11.
To enable the dyndns module, add a timed event inside of SCFG under “External Programs->Timed Events” to run the command “?dyndns <pass>” every now and then. Replace <pass> with your exact QWK password. Running the module once per day is usually acceptable, although you may want to run it more often if your IP address is prone to changing rapidly.
After the timed event has been configured, force the event to be ran. This can be done at the BBS itself (by using “;EXEC ?dyndns <pass>” from the BBS main menu.) Then, after about 3 or 5 minutes, attempt to ping your new hostname (qwk-id.synchro.net, where 'qwk-id' is your qwk-id.) It is very important that the IP address you're connecting to the Synchronet IRC Network from and the IP address that your new hostname (in the form of qwk-id.synchro.net) resolves to are exactly the same, otherwise you won't be able to link. This is to prevent anyone from arbitrarily linking their server to the network by utilizing your qwk-id.
(3) Edit your ircd.conf and include a C/N line pair for connecting to 'vert.synchro.net'. These should be commented out in the stock ircd.conf, and will look like this:
Remove the '#' from each line, and replace 'QWK_PASSWORD' with the password you were assigned (or selected) when registering for a QWK-ID. The ircd.conf contains a description of what each of the lines (and fields) mean. It is very important that you leave the asterisks as they are, especially on the N:Line. This is because the server you're connecting to may be randomly assigned, and the server will never echo your QWK password back to you, so it chooses to echo a '*' back instead. An asterisk in the N:Line also forbids any servers from connecting *to* you, which is important, since you'll only be doing outbound connects with this C/N pair.
(4) If you know how to become an IRC operator, simply use the /REHASH command. If not, you can try touch /sbbs/ctrl/ircd.rehash otherwise restart your BBS. You should see a message similar to the following in your Synchronet console:
srvc 0008 IRC Routing: Auto-connecting to rrx.synchro.net srvc 0008 IRC Routing: Connected! Sending info... srvc 0008 IRC 0018 Accepted new connection: 184.108.40.206 port 6667 srvc 0008 IRC Routing: Link with rrx.synchro.net established, states: TS
If you see any messages in regards to “Server not configured” or “Connection reset by peer”, it's highly likely that you've mistyped your QWK password into the C:Line in your ircd.conf. Double-check to make sure that the password is correct, and that you haven't otherwise malformed the C/N line pair. In particular, make sure all the asterisks (as per the default) are where they should be.
Otherwise, if you have received those messages, then you're connected! You should be able to join the typical busy Synchronet IRC channels, #bbs and #synchronet, and be able to chat with people across the network. You can find network administrators in #opers if you have any questions or concerns.
Using JSexec to run the IRCd
There are times where you may wish to run the IRCd service separately from Synchronet so that whenever your BBS goes up or down, the IRCd isn't affected. A special program, included with Synchronet, is called “JSexec” and is intended for use in this way. By using JSexec, your IRCd will remain operational regardless of what your BBS is doing, while still integrating with all of the regular Synchronet features. In fact, in most respects, running the IRCd via JSexec is the preferred method.
To run your IRCd with JSexec, make sure that you've followed all the installation instructions above. In particular, take a look at your M:Line on your ircd.conf and ensure that the last argument is the port you wish to run the IRCd on (typically 6667.) If you're currently running the IRCd through Synchronet, shutdown your BBS and comment out (or remove) the sections in your services configuration files (services.ini or services.cfg) so that the service is not restarted when you bring the BBS back up.
Just like when you're running the IRCd from within Synchronet, you need to tell JSexec that the service you're running is to be 'looped,' which is done with the -l option. Thus, a typical JSexec execution will look like this:
jsexec -l ircd
The above command is typed from within the Synchronet 'exec' directory. All console commands and errors are logged to the terminal that JSexec was started from. You should see the standard IRCd startup messages, which means that the IRCd is now operational through JSexec. Connecting to the IRCd should now work as per normal.
Using JSexec with systemd
Create a file /etc/systemd/system/ircd.service containing (for logging to a logfile):
[Unit] Description=Synchronet BBS IRCD After=syslog.target network.target [Service] Type=simple Environment=SBBSROOT=/sbbs SBBSCTRL=/sbbs/ctrl SBBSEXEC=/sbbs/exec/ User=sbbs Group=sbbs StandardOutput=file:/sbbs/data/logs/ircd.log StandardError=file:/sbbs/data/logs/ircd.err ExecStart=/sbbs/exec/jsexec -A -l /sbbs/exec/ircd.js [Install] WantedBy=default.target
Or for logging using syslog:
[Unit] Description=Synchronet BBS IRCD After=syslog.target network.target [Service] Type=forking Environment=SBBSROOT=/sbbs SBBSCTRL=/sbbs/ctrl SBBSEXEC=/sbbs/exec/ User=sbbs Group=sbbs ExecStart=/sbbs/exec/jsexec -d -l /sbbs/exec/ircd.js [Install] WantedBy=default.target
Then run: systemctl enable ircd systemctl daemon-reload systemctl start ircd
Setting up TLS/Secure Connections
If you are running with JSExec, you can add this line to your ircd.conf in order to accept secure requests:
About the Synchronet IRC Network (irc.synchro.net)
The Synchronet IRC Network is currently a small network with a BBS focus. Like all new IRC networks, we hope that with the help of other BBS sysops around the globe, the Synchronet IRC Network will grow to become a thriving community sporting a wide variety of topics. Currently, the network has a very relaxed authoritative structure – perhaps one of the most relaxed among all IRC networks. Even so, certain 'common sense' rules still apply.
Servers linked to the Synchronet IRC Network are automatically put into the DNS round-robin for 'irc.synchro.net', which means that you can expect to see connections from other clients who choose to use that address to connect to IRC. You should expect to see your server listed in the round-robin within about 30 minutes, although it typically takes less.
[5.1] - Limits of the Synchronet IRCd
If you notice any slowdown or scaling problems, please let us know.
[5.2] - Compliance with RFC's, and established protocols
The Synchronet IRCd has always aimed to be compliant with RFC1459, which was the first published IRC specification. However, it has chosen to deviate from the RFC where appropriate. This might be because of errors inside the RFC itself (i.e. +p channels being listed as “*” instead of “Prv”,) for the purpose of added functionality (i.e. handling of the PASS message for dynamic QWK connections,) or for security (not displaying some sensitive STATS output to users who are not IRC operators.) Compliance with the newer IRC RFC papers (inclusive of RFC's 2810 through 2813) is mostly correct, however deviates wherever Bahamut-specific extensions conflict.
The DALnet-style Bahamut extensions to the server-to-server protocol involve improving performance between server links by reducing the amount of traffic that needs to go across any link. Furthermore, extra arguments are added to common commands (NICK, MODE, TOPIC, etc) in order to better establish the authenticity of the message. In particular, timestamps (“TS”) have been added to many commands in order to resolve conflicts between messages. Although the Bahamut extensions are largely undocumented, the author chose to use these extensions as a base for extending the IRC protocol (as described in RFC1459) for the purpose of providing modern features.
The Synchronet IRCd diverges from common IRC practice and Bahamut IRC protocol in the following fashion:
* The Synchronet IRCd does NOT make use of the “ident” protocol, which is popular among larger IRC networks. This exclusion was decided on because it provides very little in the way of authoritative information. Instead, a user has been considered to be “identified” (by the lack of a tilde in the username portion of the user “user@host” mask) when they have correctly identified to a local BBS account. Identifying to the BBS account is done by sending a PASS message in the registration stage. Checks against a local BBS account are done against the username, and then the nickname respectively. Thus, any IRC servers not running the Synchronet IRCd MUST NOT accept ident, as it could seriously compromise a BBS-style authorization structure.
* The PASS message has been extended to allow for the passing and checking of QWK passwords in the case of dynamic connections:
PASS <password> :<qwk-id> QWK
No destination is specified within the message, as the routing is handled by static configuration directives (in the form of flags on the N:Line) which show a single path for the message to take. This is to ensure that the password cannot be sent over an arbitrary connection, improving the security of the message. The reply to a query looks like this:
PASS <result> :<qwk-id> QWK <origin>
Where <result> is “OK” if the password check succeeded, and anything else (typically “VOID”) on failure. The origin is specified so that the message may be routed back to the correct server. Thus, a PASS message without an origin is a check, and a PASS message with an origin is a reply.
* Leaf servers are considered to be 'untrusted' servers by default, due to the highly dynamic nature of a Synchronet-based IRC network. This is to prevent bogus messages from being injected into the network, false representation of authority, or otherwise harmful activity. Since untrusted servers are allowed to connect to the network, leaf servers are restricted in the following way beyond the standard behavior:
- All timestamps received from a leaf are ignored and are instead replaced by the current time. Thus, nickname collisions cannot be forced, and TS blasting is prevented. - User mode +o (oper) is ignored. However, local operators still retain authority over their local server. - The KILL and SQUIT messages are ignored and reversed if the target is connected to a server beyond the scope of the leaf. - Services authorization modes (+z, +r, +q and friends) are ignored. - Authenticity of mode change messages (channel ops, voice, bans, etc) are strictly checked and reversed if there's a mismatch. Mode hacking is thus prevented. - All channel modes are bounced on behalf of the leaf by the hub upon a resync. - Private/Secret channels are not revealed to the leaf unless a user on the leaf explicitly joins the channel.
Compatibility with other IRCd's
The Synchronet IRCd has been tested to be link compatible with:
- Bahamut 1.4.35, 1.4.36 http://bahamut.dal.net
- Andy Church's IRC Services 5.0 http://www.ircservices.za.net
The IRCd should be compatible with any other daemon that supports the DALnet-style Bahamut extensions. If you successfully link another IRCd (including a services package, or other pseudo-server,) then please feel free to let us know about it in #synchronet. Patches may be accepted to allow the IRCd to be link compatible with other protocols at the sole discretion of the author.
Although the original intention of the IRCd was to allow users to interact between one another from the BBS multi-node chat area, that has yet to occur. Eventually, users will be able to talk to one another from various BBS's and not even be aware that they're using IRC as the transport protocol for their chat sessions. For the time being, one can use the Synchronet IRC client (irc.js) to connect to their local IRC server.
Further compatibility with the later Bahamut daemons is planned, including the server-to-server “RESYNCH” command. Also, more umodes will be supported, in addition to the possibility of gaining some of the Bahamut channel modes (i.e. +c) Exception modes (+e, etc) and exception lines (to circumvent K:Lines) may be implemented.
Some sort of mechanism will be implemented to allow individual BBS's to share their message and file areas over IRC. This means that you'll be able to DCC send/receive files from a BBS, QWK packets, messages, and that sort of thing.
Frequently Asked Questions
Q: After setting up my IRCd, and trying to connect, it gives me an error stating: "You're not authorized to use this server." or "Your host isn't among the privileged." (Numeric 463)
Q: I try to connect and it tells me "Password Incorrect" or "Denied." (Numeric 464)
A: You've required a password to be passed to the IRC server via the PASS command upon registration. Check your I:Lines.
Q: I keep on getting "Error setting up socket for listening" or "Error binding socket to TCP port."
A: It's highly likely that you already have something running on the port that you've defined the IRCd to use (typically 6667.) If you have another IRCd running, shut it down or redefine the port that the Synchronet IRCd uses to listen for connections. If you get this error after having recently shut down Synchronet, one or more sockets may be stuck in 'TIME_WAIT' or similar, in which case you should wait until they expire (as viewable with "netstat".)
Q: My server keeps on trying to auto-connect to other servers, and I don't want this! What do I do?
A: The IRCd will attempt to auto-connect if there's a port defined in the C:Line for that server. Furthermore, a connect frequency must be defined in a Y:Line for the applicable IRC class for an auto- connect to be attempted. Remove the port from the C:Line, or turn the auto-connect frequency down to 0 in the Y:Line.
Q: I installed the IRCd, but where are IRC Services? (ChanServ, NickServ, etc.)
Q: I've linked to the Synchronet IRC Network, and now I'm getting all sorts of weird 'Routing' messages.
A: These messages are sent whenever an 'important' event occurs on the IRC network. This includes whenever a server links or delinks from the network, which occurs with quite a bit of regularity. These messages are informational only, and simply indicate that your IRCd (and the network at large) are operating correctly.
Q: I've successfully installed my IRCd, now how do I become an IRC Operator?
A: Use the /OPER command, which has a syntax of '/OPER <nick> <pass>'. By default, the Synchronet IRCd configuration file is already pre- configured so that you may OPER to a nickname of 'Sysop' with the BBS system password so long as you're connecting from the BBS machine itself, or a system on your local network. This means you would execute the command like this: '/OPER Sysop <syspass>'. Also check out the O:Line section in ircd.conf.
Q: My ipv6 O:Line isn't working even if I surround the address with square brackets. A: You need to enclose the whole netmask within the square brackets. Do include leading zeros in the netmask. It should match your /whois netmask. For example: [~jsmith@2001:440:1fff:b0:99d2:3cde:43e7:c96]
Q: I've been forced off of the server with a "Terminated." message. What does this message mean?
A: This message is an indication that the Sysop of your BBS/IRCd has shut down the BBS, and the IRCd is terminated as a result of that. It is an indication of explicit termination (i.e., the IRCd was instructed to shut down by a human being).
Q: My question isn't answered in this document, where can I go?
A: First, make sure you've read this document *in its entirety* Second, read section 2.2 again. Third, if you're still having a problem, feel free to join #synchronet on irc.synchro.net, the author typically uses the nick of 'Cyan' Support is not given via email or otherwise.
[7.2] - Technical Questions
Q: Why were the Bahamut protocol extensions used instead of EFnet, Undernet, Unreal, or otherwise?
A: The Bahamut extensions were simply the extensions that the author was most familiar with. Bahamut is a widely-deployed IRC daemon in use by many networks (DALnet in particular,) so it's had a strong test cycle. Furthermore, all modern IRC extensions are relatively similar to each other, but differ in name. For example, Bahamut's SJOIN is similar to EFnet's NJOIN.
Q: Will you be adding support for <X> protocol, or for <X> IRCd?
A: Highly unlikely. However, feel free to add in your own support and send me a diff. Depending on the scope of the changes, I may choose to include them, or perhaps offer it externally as a patch. When coding in support for different IRC protocol extensions, try to make use of modularity so that it's possible to link together servers of different protocols, with the IRCd as the bridge. Patches that follow this 'modular' approach are more likely to be accepted.
Q: Can I make modifications to the IRCd?
A: By all means, go for it! If you think that you've made a particularly useful or clever hack, please feel free to send your changes to email@example.com (in unified diff format, preferably) along with a description of what you've changed.
Q: I'm an IRC guru, and I'd like to talk to the author about the IRCd, where do I go?
A: The author can typically be found in #synchronet as 'Cyan' on irc.synchro.net, and welcomes all discussion about IRC protocol, theory (especially as it relates to IRC3 proposals,) or general banter among long-standing IRC users.