From b867b19b1ff0267d1a8e1e08f84ee7a313596506 Mon Sep 17 00:00:00 2001 From: cyan <> Date: Fri, 14 Nov 2003 12:11:11 +0000 Subject: [PATCH] First commit of ircd.txt, documentation for the Synchronet IRCd Service. Hopefully, with a little luck, I haven't come off as being too abrasive in this document ;) --- docs/ircd.txt | 525 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 525 insertions(+) create mode 100644 docs/ircd.txt diff --git a/docs/ircd.txt b/docs/ircd.txt new file mode 100644 index 0000000000..c4f70196e3 --- /dev/null +++ b/docs/ircd.txt @@ -0,0 +1,525 @@ + + ** ircd.js : The Synchronet IRCd Service ** + by: Randy Sommerfeld <cyan@rrx.ca> + +1 .... Introduction +2 .... About this document +2.1 .... What this document hopes to accomplish +2.2 .... What this document won't accomplish +2.3 .... Assumptions we make about you +3 .... Installation +3.1 .... Getting the IRCd up and running +3.2 .... Linking to the Synchronet IRC Network (irc.synchro.net) +4 .... About the Synchronet IRC Network (irc.synchro.net) +5 .... Technical information +5.1 .... Limits of the Synchronet IRCd +5.2 .... Compliance with RFC's, and established protocols +5.3 .... Compatibility with ther IRCd's +6 .... The Future +7 .... Frequently Asked Questions +7.1 .... Installation Questions +7.2 .... Technical Questions + +=======- 1.0 -- Introduction -================================================ + + The Synchronet IRCd (IRC daemon) service is the newest Synchronet +service written in 100% Javascript. It's currently the largest (and perhaps +the most complex) service available for Synchronet. The IRCd service aims to +eventually be a 'communications bridge' of sorts which will allow multiple +BBS's to link their "multinode chat" areas together in a network so that users +may talk to one another from the comfort of their home BBS. While +accomplishing this goal, the Synchronet IRCd intends to also be a fully- +functional IRC daemon that rivals the bigger, legacy UNIX IRC daemons in terms +of features. This way, everyone who wishes to chat on a common network will +be able to use the local BBS, or a standard IRC client (if they wish.) + +=======- 2.0 -- About this document -========================================= + +[2.1] - What this document hopes to accomplish + + 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. + +[2.2] - 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. To guage your knowledge +of IRC, answer the following questions either with a 'true' or 'false': + + * People chat in 'rooms' on IRC. + * 'IRCop' is short for 'IRC cop', the police officers of IRC. + * A 'ping' is something submarines use to guage distance under water. + * CTCP and DCC stand for Client Tunneling Carrier Protocol and + Direct Channel Cutting, respectively. + + If you answered 'true' to any of the above questions, or if you don't +understand some of the terminology used in the questions, 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. + +[2.3] - Assumptions we make about you + + 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) + +=======- 3.0 -- Installation -================================================ + +[3.1] - Getting the IRCd up and running + + (1) Make sure you are running a modern version of the Synchronet BBS +software. The Synchronet IRCd is not intended to run on versions 3.10 or +earlier. While care has been taken to ensure backwards compatibility with +3.10, it should only be run on that version for testing purposes. Upgrading +may include retrieving the latest version of Synchronet from the Synchronet +CVS (if you're familiar with building from CVS), from the Synchronet web site +(http://www.synchro.net), or elsewhere. Synchronet 3.11 is the minimum +required version to run version 1.0 of the Synchronet IRCd. + + Older versions of Synchronet also come packaged with older Javascript +libraries. The Synchronet IRCd makes use of some of the newer Javascript +library features (such as the ability to treat strings as an array of +characters), therefore it's critical to have a modern JS library. If your +Javascript library is from 2001 or so (you can check this in the 'system +information' part of your BBS main menu), then it's too old. Time to upgrade. + + (2) Check to make sure that all of the components of the Synchronet +IRCd are resting in their correct directories. While you're at it, check the +file sizes to make sure they're relatively normal. Make sure that all of the +files are readable by the user you're intending to run the IRCd as. Here's a +chart to help: + + File Synchronet Directory Approximate Size + + ircd.js exec 200KB + ircd.conf ctrl 12KB + ircmotd.txt text 180bytes + + (3) Edit your relevant services configuration file (in the Synchronet +'ctrl' directory.) For Synchronet 3.11, this is most likely "services.ini", +however, backwards compatibility has been retained with the old style +"services.cfg" just in case you want to bring yours over from an older version +of Synchronet. You may run the Synchronet IRCd on any port you wish, however, +standard convention dictates that it be run on port 6667 (which is the +standard port that most IRC clients will try to connect to, first.) It's +important that the IRCd be defined as a STATIC service (i.e. one that runs in +the background continuously and does not require a connection to start the +service), and that it uses the LOOP option (so that if you wish to restart only +the IRCd, or if it crashes, it comes back up immediately.) + + The combined options for 'services.cfg' represented in hex is '806', +so that a completed services.cfg line should look like this: + +;protocol port max_clients options(hex) command-line +IRC 6667 10 806 ircd.js + + An example IRC section from services.ini looks like this, and should +already be present (but commented out) in services.ini for Synchronet 3.11 +and above: + +[IRC] +Port=6667 +MaxClients=100 +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.) + + (4) 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 milage 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! + + (5) Restart your BBS, or recycle your services so that your new IRC +service is brought online with your BBS. Watch your BBS console carefully, +as you should see something similar to the following messages: + +srvc 0007 IRC SynchronetIRCd-1.0b(1.79) 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-explanitory (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. Repeat this process of elimination until your IRCd starts +successfully. + + (6) Test your new IRCd by connecting to it with an IRC client. +At the very least, using 'telnet' to connect to the IRCd port should give you +something similar to the following line: + +:rrx.synchro.net NOTICE * :*** SynchronetIRCd-1.0b(1.76) (RoadRunner X) Ready. + + Which 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. + +[3.2] - 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. + + In later versions of the IRCd or the network, you'll be able to offer +your BBS's files over IRC, integrate your BBS chat area with IRC, or even +receive alerts about new messages or BBS email while on IRC. + + 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) 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: + +#C:vert.synchro.net:QWK_PASSWORD:*.synchro.net:6667:30 +#N:vert.synchro.net:*:*.synchro.net::30 + + 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 asteriks 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 asterik 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. + + (3) Restart your BBS (or, if you know how to become an IRC operator, +simply use the /REHASH command), and 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: 154.5.119.21 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 asteriks (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. + +=======- 4.0 -- 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.0 -- Technical Information -======================================= + +[5.1] - Limits of the Synchronet IRCd + + Since the Synchronet IRCd Service is written in Javascript, which is +still an interpreted script language, the IRCd will be severely limited in its +capability and speed when compared against other 'legacy' IRC daemons. In +particular, the IRCd will only be able to (at best) hold a hundred clients or +less before severe slowdown problems are exposed. If you find that you are +commonly holding more than a hundred clients, or are experiencing slowdown +problems, it's recommended that you switch to a legacy IRCd such as Bahamut, +which can be found at http://bahamut.dal.net. + + A solution would be to link the Synchronet IRCd to the Bahamut IRCd, +and then link Bahamut to the network. Then, limit connections only to local +BBS users for the Synchronet IRCd, and use Bahamut for accepting connections +from the Internet at large. + + Other problems may also creep up, especially as the network grows in +size. Although the author is continually working to improve the performance +of the IRCd, it should be assumed that there will be scalability issues due to +the use of Javascript. + +[5.2] - Compliance with RFC's, and established protocols + + The Synchronet IRCd has always aimed to be compiant 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, care MUST be taken when linking non-Synchronet IRCd's together, as it +could 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 behaviour: + + - 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. + +[5.3] - Compatibility with other IRCd's + + The Synchronet IRCd has only been tested to be link compatible with: + + * Bahamut 1.4.35, 1.4.36-rc1 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. + +=======- 6.0 -- The Future -================================================== + + 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, user-accessible "WATCH", and +"SILENCE." 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. + + I'm sure DigitalMan has a ton of cool ideas, too ;) + +=======- 7.0 -- Frequently Asked Questions -================================== + +[7.1] - Installation 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) + + A: Most likely your Javascript libraries are too old. Upgrade to + Synchronet 3.11, which contains sufficiently modern Javascript + libraries. If you're certain that you're running new libraries, + double-check your I:Lines and Y:Lines inside the ircd.conf. + + 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: Ack, 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: 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 + particuarily useful or clever hack, please feel free to send your + changes to ircd@rrx.ca (in unified diff format, preferrably) 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. + +=======- EOF -================================================================ -- GitLab