X-Git-Url: http://git.pk910.de/?p=ircu2.10.12-pk.git;a=blobdiff_plain;f=doc%2Fp10.html;fp=doc%2Fp10.html;h=fbbc4fe82fd1070295130e093343f2f76d847204;hp=0000000000000000000000000000000000000000;hb=0400a5a6479398d82526785c18c0df8bc8b92dce;hpb=d17e10da972ce5776c60b4c317267c6abe0e1ead diff --git a/doc/p10.html b/doc/p10.html new file mode 100644 index 0000000..fbbc4fe --- /dev/null +++ b/doc/p10.html @@ -0,0 +1,1184 @@ + + +
+ + ++
This document is "work in progress" and being continually updated :) +
2. General concepts and background +
2.1 Concepts. ++ +
2.2 Token Table.
++ ++TODO List +
[Back]
+
+
2. General concepts and background +
The undernet P10 protocol uses a scheme of "Numerics" to uniquenly identify +a client or server within the network. Each server has its own unique numeric +(0 -> 4095) and each client has its own numeric within that server (0->262,143). +
The numerics are encoded into a Base64 stream to maintain human readable +data flow and reduce the size of the messages. The Base64 character set +used in ircu is included below, this defines all valid characters allowed +in a Base64 numeric with "A" representing 0 and "]" representing 63. +
++Server numerics consist of 2 characters, with the minimum, 0, being represented +by "AA", and the maximum, 4095, being represented by "]]". Client numerics +are 3 characters long, with the minimum, 0, being represented by "AAA", +and the maximum, 262,143, being represented by "]]]". The unique identifier +of a client on the network consists of a combination of both the server +and client numeric in the format SSCCC. +ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789[]+
As an example, consider a server "irc.undernet.org" which has a numeric +of 2, translating to "AC" in Base64. On this server exists a client, whom +has been allocated the numeric 63 (which translates to "AA]" in Base64). +Therefore, the unique identifier of this client on the network is "ACAA]". +From this, we can determine which server the message came from, aswell +as the client who sent it. +
These numerics are used to prefix every message issued on the stream +except for the initial "PASS" or "SERVER" message, which are not prefixed. +Therefore, every message that can be recieved from a server will consist +of the format: +
++For Example: +[NUMERIC PREFIX] [TOKEN] [DATA]+
++2.2 Token Table +A[A5j P ABAAA :Foo.+
The following table lists all the acceptable messages, along with their
+relevant "Token", which is used in the server<>server protocol. The
+aim of tokenisation is to reduce the bandwidth used during network communication
+by reducing the length of common message identifiers.
+
+
Message | + +Token | +
PRIVMSG | + +P | +
WHO | + +H | +
WHOIS | + +W | +
WHOWAS | + +X | +
USER | + +USER | +
NICK | + +N | +
SERVER | + +S | +
LIST | + +LIST | +
TOPIC | + +T | +
INVITE | + +I | +
VERSION | + +V | +
QUIT | + +Q | +
SQUIT | + +SQ | +
KILL | + +D | +
INFO | + +F | +
LINKS | + +LI | +
STATS | + +R | +
HELP | + +HELP | +
ERROR | + +Y | +
AWAY | + +A | +
CONNECT | + +CO | +
MAP | + +MAP | +
PING | + +G | +
PONG | + +Z | +
OPER | + +OPER | +
PASS | + +PA | +
WALLOPS | + +WA | +
DESYNCH | + +DS | +
TIME | + +TI | +
SETTIME | + +SE | +
RPING | + +RI | +
RPONG | + +RO | +
NAMES | + +E | +
ADMIN | + +AD | +
TRACE | + +TR | +
NOTICE | + +O | +
WALLCHOPS | + +WC | +
CPRIVMSG | + +CP | +
CNOTICE | + +CN | +
JOIN | + +J | +
PART | + +L | +
LUSERS | + +LU | +
MOTD | + +MO | +
MODE | + +M | +
KICK | + +K | +
USERHOST | + +USERHOST | +
USERIP | + +USERIP | +
ISON | + +ISON | +
SQUERY | + +SQUERY | +
SERVLIST | + +SERVLIST | +
SERVSET | + +SERVSET | +
REHASH | + +REHASH | +
RESTART | + +RESTART | +
CLOSE | + +CLOSE | +
DIE | + +DIE | +
HASH | + +HASH | +
DNS | + +DNS | +
SILENCE | + +U | +
GLINE | + +GL | +
BURST | + +B | +
CREATE | + +C | +
DESTRUCT | + +DE | +
END_OF_BURST | + +EB | +
END_OF_BURST_ACK | + +EA | +
PROTO | + +PROTO | +
JUPE | + +JU | +
OPMODE | + +OM | +
CLEARMODE | + +CM | +
ACCOUNT | + +AC | +
3. Registration and syncronisation +
3.1 Server registration and authentication +
After a TCP connection has been established, the server initally introduces +itself via a "PASS" message as follows: +
++"PASSWORD" is simply compared with the password present in the destination +servers config file, and is used to confirm credentials after the "SERVER" +message has been recieved, as follows: +PASS :[PASSWORD]+
++For Example: +SERVER [SERVERNAME] [HOPCOUNT] [START TIME] [LINK TIME] [PROTOCOL] [NUMERIC/MAXCONN] :[DESCRIPTION]+
++Notes: +1 2 3 4 5 6 7 8 +SERVER irc.undernet.org 1 933022556 947908144 J10 AA]]] :[127.0.0.1] A Undernet Server.+
After the connection has been established and verified, the next step +is to syncronise the database of client/server/channel information between +the two servers. +
3.2.1 - SERVER Messages+ +
Server details are transmitted via "SERVER" messages similar +to the initial introduction message, with the following format:+ +
++ +[OWNING SERVER PREFIX] S [SERVERNAME] +[HOPCOUNT] [START TIME] [LINK TIME] [PROTOCOL] [NUMERIC/MAXCONN] 0 :[DESCRIPTION]+The syntax of this message is almost identical to +the originally recieved server message, with the only exception being that +the message is numeric prefixed, to indicate which server sent this message +(and also therefore, which hub this new server is linked too). There is +also a fixed "0" present before the Description field, this is a placeholder +for future use and currently unused. [Isomer: Question, what IS this +reserved for?] +3.2.2 - NICK Messages
Client information is transmitted via "NICK" messages, of the +following format:+ +
++ +++For Example: +[NUMERIC PREFIX] N [NICK] [HOPCOUNT] [TIMESTAMP] [USERNAME] [HOST] <+modes> [BASE64 IP] [NUMERIC] :[USERINFO]+1 2 3 +4 5 6 +7 8 +9 10 11 ++Notes: +
AF N Client1 1 947957573 User userhost.net ++oiwg DAqAoB AFAAA :Generic Client.+
+- +The numeric of the server sending this message. (And hence, owning this +client).
+ +- +The "NICK" token.
+ +- +The nickname of this client, currently max 9 chars.
+ +- +The "Hopcount" of this client, Ie: how many servers away it is on.
+ +- +The epoch timestamp indicating when the user was created.
+ +- +The "User" part of the user@host mask.
+ +- +the "Host" part of the user@host mask.
+ +- +[Optional]: User modes. If present, this is always +<user modes +for this client>. Note that the special +r usermode is followed by the +client's account name; see the documentation for ACCOUNT.
+ +- +The real IP address of this client, a Base64 encoded 32bit int.
+ +- +This client's numeric, in SSCCC format.
+ +- +Free format user info line.
+ +
3.2.3 - BURST Messages+ +
Channel details and membership information is synchronised +in one (or more) BURST messages for each channel that exists, formatted +as follows:+ +
++ +++[NUMERIC PREFIX] B [CHANNEL] [CREATION TIMESTAMP] <+MODES> <ARG1> <ARG2> [MEMBER LIST] <:%BANS>+
For Example:+ +
++ +++1 2 3 4 5 6 7 8 9 +AZ B #coder-com 949217470 +tinkl key 56 AAAAA,AAAAB,AAAAC,ABAAA,ABAAB,ABAAC,ACAAA :%*!*@*.net+
Notes:+ +
*!*@*.foobar.net
+
another!ban@*.com
+
*!*fred@a.host.co.uk
If the length of a BURST message exceeds the maximum lenght +of a line (512 characters) then the remaining channel members/bans are +sent in subsequent BURST lines. The subsequent burst lines are only +used to add additional members to the channel, and if neccessary, channel +bans. There will be no "Mode" parameters present. A sample additional burst +line would be:+ +
++ +++AZ BURST #coder-com 949217470 ACAAB:o,ACAAD :%*!*another@*.ban.com+
Which adds two more opped members and a ban to the channel.+ +
3.2.4 - JUPE Messages+ +
Any currently unexpired JUPEs are transmitted via "JUPE" messages +with the following format:+ +
++ +[NUMERIC PREFIX] JU * (+|-)[SERVER +NAME] [LIFETIME] [LAST MOD] :[REASON]+For example:
++ +1 2 3 4 +5 6 +7 ++Notes:
AZ JU * +juped.undernet.org 000003593 955419707 +:Juped Server
The following table summarises the sequence of events that occur when +a server connects to another server. S1 is our server, and S2 is a HUB +on the target network. +
S1: Sends Password.
+
S1: Sends initial SERVER message.
+
S2 Confirms S1 has the correct credentials, and if so, proceeds. +If not, S1 is squit with a relevant reason. +
S2: Sends Password.
+
S2: Sends initial SERVER message.
+
S1 Confirms S2 has the correct credentials, and if so, proceeds. +If not, S2 is squit with a relevant reason. +
The follow occur asynchronously, however they have been shown +seperately below for simplicity. +
S1: Sends all the servers it is aware of as a stream of SERVER messages.
+
S1: Sends all the clients it is aware of as a stream of NICK messages.
+
S1: Sends the database of channel states on the network, as a stream
+of BURST messages.
+
S1: Sends all the jupes it is aware of as a stream of JUPE messages.
+
S1: Sends a END_OF_BURST token (EB) to indicate it has finished sending.
+
S2: Sends all the servers it is aware of as a stream of SERVER messages.
+
S2: Sends all the clients it is aware of as a stream of NICK messages.
+
S2: Sends the database of channel states on the network, as a stream
+of BURST messages.
+
S2: Sends all the jupes it is aware of as a stream of JUPE messages.
+
S2: Sends a END_OF_BURST token (EB) to indicate it has finished sending.
+
S2: Sends an EOB_ACK token (EA) to indicate it has succesfully recieved
+the END_OF_BURST from S1
+
S1: Sends an EOB_ACK token (EA) to indicate it has succesfully recieved
+the END_OF_BURST from S2
+
Example Session: +
[WRITE]: PASS :54321 +[WRITE]: SERVER irc.undernet.org 1 947957852 947957852 J10 AB]]] :Undernet Client Server. +[WRITE]: AB N MrFoo 1 947957852 ~me myhost.foobar.net +diksw DAqAoB ABAAA :Mr Foo (foo@bar.com). +[WRITE]: AB B #mychannel 946101324 ABAAA:o +[WRITE]: AB EB +[ READ]: PASS :54321 +[ READ]: SERVER server1.undernet.org 1 947901540 947958150 J10 AFAD] :A Generic Server. +[ READ]: AF S server2.undernet.org 2 0 947957585 P10 AZAD] 0 :[192.168.10.3] A Generic Server. +[ READ]: AZ S server3.undernet.org 3 0 947957607 P10 AIAD] 0 :[192.168.10.5] A Generic Server. +[ READ]: AF N Client1 1 947957573 Ident userhost.net +oiwg DAqAoB AFAAA :Generic Client. +[ READ]: AZ N Client2 2 947957719 Ident userhost.net +iwg DAqAoB AZAAA :Generic Client. +[ READ]: AI N Client3 3 947957742 Ident userhost.net +iwg DAqAoB AIAAA :Generic Client. +[ READ]: AI N Client4 3 947958121 Ident userhost.net +iwg DAqAoB AIAAB :Generic Client. +[ READ]: AF B #foobar 947957734 +tink akey AIAAB,AIAAA:v,AZAAA:o :%*!*another@*.ban.com *!*foo@bar.net +[ READ]: AF B #coder-com 947957727 AIAAB,AZAAA:o +[ READ]: AF B #another 946101321 AFAAA +[ READ]: AF JU * +juped.undernet.org 3600 947958100 :Broken, please fix +[ READ]: AF EB +[WRITE]: AB EA +[ READ]: AF EA+[Back] +
This chapter provides details of the messages that can be sent after +successfully linking to a network, and synchronising the channel/user database. +
4.1 Channel state operations +
There are a number of messages that can modify the state of a channel, +these are: +
The MODE message can modify channel modes and bans, and also give or +take operator/voice status from channel members. +
For Example:
+
Notes:
+
+
Token | + +Function | + +Parameters | +
p | + +Sets/Unsets 'Private' Flag. | + +None. | +
s | + +Sets/Unsets 'Secret' Flag. | + +None. | +
m | + +Sets/Unsets 'Moderated' Flag. | + +None. | +
n | + +Sets/Unsets 'External Messages' Flag. | + +None. | +
t | + +Sets/Unsets 'Topic Limit' Flag. | + +None. | +
i | + +Sets/Unsets 'Invite only' Flag. | + +None. | +
l | + +Sets/Unsets 'Channel Limit' Flag. | + +The channel limit. | +
k | + +Sets/Unsets 'Channel Key' Flag. | + +The channel keyword (Password). | +
o | + +Ops and Deops users. | + +Numeric of user to be opped. | +
v | + +Voice | + +Numeric of user to be voiced. | +
b | + +Ban | + +Ban string. | +
N.B: The "MODE" message is also used to modify a client's user modes,
+not just channel modes. See section 4.2 for details.
The OPMODE message is identical in syntax to the MODE message, however +it will only ever have an operator as the source. It is likely that the +source of this mode will not have ops in the target channel, but it should +succeed never the less. +
4.1.3 - JOIN +
4.1.4 - PART +
4.1.5 - KICK +
4.1.6 - TOPIC +
4.1.7 - CLEARMODE
+
+
4.2.1 - NICK ++4.3 Channel/Client Messaging. +AZAAA N Nick2 955423230+4.2.2 - MODE +AZAAA M Nick2 :+odi+4.2.3 - ACCOUNT +AX AC AZAAA oper+The ACCOUNT message provides a way for servers, such as the channel service +server, to set the account name information that is associated with a client. +Once set, it cannot be unset or changed, and will be propagated in NICK during +net bursts using the special user mode +r followed by the account name. +
4.3.1 - PRIVMSG ++[Back] +4.3.2 - NOTICE +
4.3.3 - CNOTICE +
4.3.4 - CPRIVMSG +
5. Programmers reference: Client/Server +Structures +
This section provides information on the standard Client/Server structures, +for easy reference during development. +
[..Link to autogenerated struct.html..] +
[Back]
+
+
Frequently asked questions. +
[2000-01-20]: Initial draft, structure, background info.
+
[2000-02-13]: Added initial BURST documentation.
+
[2000-02-14]: Continued BURST documentation / Begin NICK and SERVER
+documentation.
+
[2000-02-26]: Continued chapter 5, few example fixes, added token table
+from msg.h. -Gte.
+
[2000-03-02]: Added NICK spec. -Gte.
+
[2000-03-18]: Added JUPE spec. -Kev
+
[2000-04-10]: Added information about OPMODE and CLEARMODE tokens.
+-Kev
+
[2000-04-11]: Started work on chapter 4. -Gte
+
[2000-06-01]: Changed some info about the max number of clients -Isomer
+
[2002-01-11]: Wrote a specification for ACCOUNT and noted that a usermode
+in a NICK message may have an argument. -Kev
+