Add doc/Contributing.txt to distribution archive

[ngircd-alex.git] / doc / Protocol.txt

diff --git a/doc/Protocol.txt b/doc/Protocol.txt
index e3c6bbfe417d0cd56b64b149e9f3faec745ad40e..5093eea9f3ace44b40b5c6388f0395dcc66f4693 100644 (file)
--- a/doc/Protocol.txt
+++ b/doc/Protocol.txt
@@ -1,7 +1,7 @@
 
                      ngIRCd - Next Generation IRC Server
 
 
                      ngIRCd - Next Generation IRC Server
 

-                      (c)2001-2003 by Alexander Barton,
+                        (c)2001-2008 Alexander Barton,

                     alex@barton.de, http://www.barton.de/
 
                ngIRCd is free software and published under the
                     alex@barton.de, http://www.barton.de/
 
                ngIRCd is free software and published under the


@@ -22,9 +22,10 @@ in all details. But because the ngIRCd should be a fully compatible
 replacement for this server ("ircd") it tries to emulate these differences.
 
 If you don't like this behavior please ./configure the ngIRCd using the
 replacement for this server ("ircd") it tries to emulate these differences.
 
 If you don't like this behavior please ./configure the ngIRCd using the

-"--enable-strict-rfc" command line option. But please note: not all IRC
-clients are compatible with such an server, some can't even connect at all!
-Therefore this option isn't desired for "normal operation".
+"--enable-strict-rfc" command line option. But keep in mind: not all IRC
+clients are compatible with a server configured that way, some can't even
+connect at all! Therefore this option usually isn't desired for "normal
+server operation".

 
 
 II. The IRC+ Protocol
 
 
 II. The IRC+ Protocol


@@ -35,8 +36,8 @@ as defined in RFC 2810-2813. This enhanced protocol is named "IRC+". It is
 backwards compatible to the "plain" IRC protocol and will only be used by
 the ngIRCd if it detects that the peer supports it as well.
 
 backwards compatible to the "plain" IRC protocol and will only be used by
 the ngIRCd if it detects that the peer supports it as well.
 

-The "PASSV" command is used to detect the protocol and peer versions (see
-RFC 2813, section 4.1.1).
+The "PASS" command is used to detect the protocol and peer versions see
+RFC 2813 (section 4.1.1) and below.

 
 
 II.1 Register new server link
 
 
 II.1 Register new server link


@@ -57,9 +58,11 @@ The following optional(!) 10 bytes contain an implementation-dependent
 version number. Servers supporting the IRC+ protocol as defined in this
 document provide the string "-IRC+" here.
 
 version number. Servers supporting the IRC+ protocol as defined in this
 document provide the string "-IRC+" here.
 

+Example for <version>: "0210-IRC+".
+

 <flags> consists of two parts separated with the character "|" and is at
 most 100 bytes long. The first part contains the name of the implementation
 <flags> consists of two parts separated with the character "|" and is at
 most 100 bytes long. The first part contains the name of the implementation

-(ngIRCd sets this to "ngIRCd", the original ircd to "IRC", e.g.). The second
+(ngIRCd sets this to "ngircd", the original ircd to "IRC", e.g.). The second

 part is implementation-dependent and should only be parsed if the peer
 supports the IRC+ protocol as well. In this case the following syntax is
 used: "<serverversion>[:<serverflags>]".
 part is implementation-dependent and should only be parsed if the peer
 supports the IRC+ protocol as well. In this case the following syntax is
 used: "<serverversion>[:<serverflags>]".


@@ -68,25 +71,87 @@ used: "<serverversion>[:<serverflags>]".
 number, <serverflags> indicates the supported IRC+ protocol extensions (and
 may be empty!).
 
 number, <serverflags> indicates the supported IRC+ protocol extensions (and
 may be empty!).
 

-The optional parameter <options> is used to propagate server options as
-defined in RFC 2813, section 4.1.1.
-

 The following <serverflags> are defined at the moment:
 
 The following <serverflags> are defined at the moment:
 

+- C: The server supports the CHANINFO command.
+
+- L: INVITE- and BAN-lists should be synchronized between servers: if the
+     peer understands this flag, it will send "MODE +I" and "MODE +b"
+     commands after the server link has been established.
+
+- H: The server supports the "enhanced server handshake", see section II.2
+     for a detailed description.
+

 - o: IRC operators are allowed to change channel- and channel-user-modes
      even if they aren't channel-operator of the affected channel.
 
 - o: IRC operators are allowed to change channel- and channel-user-modes
      even if they aren't channel-operator of the affected channel.
 

-- C: The server supports the CHANINFO command.
+- S: The server supports the SERVICE command (on this link).
+
+- Z: Compressed server links are supported by the server.
+
+Example for a complete <flags> string: "ngircd|0.7.5:CZ".
+
+The optional parameter <options> is used to propagate server options as
+defined in RFC 2813, section 4.1.1.

 
 
 
 

-II.2 Exchange channel-modes, topics, and persistent channels
+II.2 Enhanced Server Handshake
+
+The "enhanced server handshake" is used when both servers support this IRC+
+extension, which is indicated by the 'H' flag in the <serverflags> sent with
+the PASS command, see section II.1.
+
+It basically means, that after exchanging the PASS and SERVER commands the
+server is not registered in the network (as usual), but that IRC numerics
+are exchanged until the numeric 376 (ENDOFMOTD) is received. Afterwards the
+peer is registered in the network as with the regular IRC protocol.
+
+A server implementing the enhanced server handshake (and indicating this
+using 'H' in the <serverflags>) MUST ignore all unknown numerics to it
+silently.
+
+In addition, such a server should at least send the numeric 005 (ISUPPORT)
+to its peer, containing the following information. Syntax: <key>=<value>,
+one token per IRC parameter. If the server has to send more than 12 token
+it must send separate ISUPPORT numerics (this is a limitation of the IRC
+protocol which allows at max 15 arguments per command).
+
+ - NICKLEN: Maximum nickname length. Default: 9.
+ - CASEMAPPING: Case mapping used for nick- and channel name comparing.
+   Default: "ascii", the chars [a-z] are lowercase of [A-Z].
+ - PREFIX: List of channel modes a person can get and the respective prefix
+   a channel or nickname will get in case the person has it. The order of the
+   modes goes from most powerful to least powerful. Default: "(ov)@+"
+ - CHANTYPES: Supported channel prefixes. Default: "#".
+ - CHANMODES: List of channel modes for 4 types, separated by comma (","):
+   Mode that adds or removes a nick or address to a list, mode that changes
+   a setting (both have always has a parameter), mode that changes a setting
+   and only has a parameter when set, and mode that changes a setting and
+   never has a parameter. For example "bI,k,l,imnPst".
+ - CHANLIMIT: Maximum number of channels allowed to join by channel prefix,
+   for example "#:10".
+
+Please see <http://www.irc.org/tech_docs/005.html> for details.
+
+The information exchanged using ISUPPORT can be used to detect configuration
+incompatibilities (different maximum nick name length, for example) and
+therefore to disconnect the peer prior to registering it in the network.
+
+
+II.3 Exchange channel-modes, topics, and persistent channels

 
      Command: CHANINFO
 
      Command: CHANINFO

-  Parameters: <channel> +<modes> <key> <maxusers> [<topic>]
+  Parameters: <channel> +<modes> [[<key> <limit>] <topic>]

      Used by: servers only
 
 CHANINFO is used by servers to inform each other about a channel: its
      Used by: servers only
 
 CHANINFO is used by servers to inform each other about a channel: its

-modes, channel key, user limits and its topic. <topic> is optional.
+modes, channel key, user limits and its topic. The parameter combination
+<key> and <limit> is optional, as well as the <topic> parameter, so that
+there are three possible forms of this command:
+
+  CHANINFO <channel> +<modes>
+  CHANINFO <channel> +<modes> <topic>
+  CHANINFO <channel> +<modes> <key> <limit> <topic>

 
 If the channel already exists on the server receiving the CHANINFO command,
 it only adopts the <modes> (or the <topic>) if there are no modes (or topic)
 
 If the channel already exists on the server receiving the CHANINFO command,
 it only adopts the <modes> (or the <topic>) if there are no modes (or topic)


@@ -103,5 +168,16 @@ a channel has no user limit (the parameter <modes> doesn't list the "l"
 channel mode). In this case <limit> should be "0".
 
 
 channel mode). In this case <limit> should be "0".
 
 

--- 
-$Id: Protocol.txt,v 1.10 2003/04/29 13:37:36 goetz Exp $
+II.4 Update webchat/proxy client information
+
+     Command: WEBIRC
+  Parameters: <password> <username> <hostname> <ip-address>
+     Used by: unregistered clients only
+
+The WEBIRC command is used by some Web-to-IRC gateways to set the correct
+user name and host name of users instead of their own. It must be the very
+first command sent to the server, even before USER and NICK commands!
+
+The <password> must be set in the server configuration file to prevent
+unauthorized clients to fake their identity; it is an arbitrary string.
+