X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?p=ngircd-alex.git;a=blobdiff_plain;f=doc%2FCommands.txt;h=7765d3a440cc6fe4431081b10b34120d426defa8;hp=83f811df978751b06d050281515472861f9aa0a5;hb=659d1264607e780708ace76181b0dc556b54e39a;hpb=a7023113e7546e3b278f753f0d38161f11afdb79 diff --git a/doc/Commands.txt b/doc/Commands.txt index 83f811df..7765d3a4 100644 --- a/doc/Commands.txt +++ b/doc/Commands.txt @@ -101,49 +101,117 @@ Connection Handling Commands - doc/Protocol.txt - NICK - NICK + NICK + NICK [] + NICK . - Change your nickname to . + Set or change the of a client (first form) and register + remote clients (second and third form; servers only). + + References: + - RFC 1459, 4.1.2 "Nick message" (old client and server protocol) + - RFC 2812, 3.1.2 "Nick message" (client protocol) + - RFC 2813, 4.1.3 "Nick" (server protocol) - PASS + PASS PASS [] . - Set a connection . This command must be sent before the - NICK/USER registration combination. + Set a connection . This command must be the first command + sent to the server, even before the NICK/USER or SERVER commands. . - See doc/Protocol.txt for more info. + The first form is used by user sessions or (old) RFC 1459 servers, + the second form is used by RFC 2812 or IRC+ compliant servers and + enables the server to indicate its version and supported protocol + features. + + References: + - RFC 1459, 4.1.1 "Password message" (old client and server protocol) + - RFC 2812, 3.1.1 "Password message" (client protocol) + - RFC 2813, 4.1.1 "Password message" (server protocol) + - doc/Protocol.txt - PING - PING [] + PING [] + . + Tests the presence of a connection to a client or server. + . + If no has been given, the local server is used. User clients + can only use other servers as , no user clients. . - Tests the presence of a connection. A PING message results in a PONG - reply. If is specified, the message gets passed on to it. + A PING message results in a PONG reply containing the , which + can be arbitrary text. + + Please note: + The RFCs state that the parameter is used to specify the + origin of the PING command when forwared in the network, but this + is not the case: the sender is specified using the prefix as usual, + and the parameter is used to identify the PONG reply in practice. + + References: + - RFC 2812, 3.7.2 "Ping message" - PONG - PONG [] + PONG [] + . + Reply to a "PING" command, indicate that the connection is alive. . - This command is a reply to the PING command and works in much the - same way. + The is the arbitrary text received in the "PING" command and + can be used to identify the correct PONG sent as answer. + . + When the "PONG" command is received from a user session, the + parameter is ignored; otherwise the PONG is forwarded to this client. + + References: + - RFC 2812, 3.7.3 "Pong message" - QUIT QUIT [] . - End IRC session and disconnect from the server. + Terminate a user session. . - If a has been given, it is displayed to all the - channels that you are a member of when leaving. + When received from a user, the server acknowledges this by sending + an "ERROR" message back to the client and terminates the connection. + . + When a has been given, it is sent to all the channels + that the client is a member of when leaving. + + References: + - RFC 2812, 3.1.7 "Quit" + - RFC 2813, 4.1.5 "Quit" - USER - USER + USER + . + Register (and authenticate) a new user session with a short + and a human-readable . . - This command is used at the beginning of a connection to specify the - name, hostname, and initial user of the - connecting client. + The parameter is only used when received by an other server + and ignored otherwise; and the parameter is always ignored. + But both parameters are required on each invocation by the protocol + and can be set to arbitrary characters/text when not used. . - may contain spaces, and thus must be prefixed with a colon. + If contains an "@" character, the full is used + for authentication, but only the first part up to this character is + set as "user name" for this session. + + References: + - RFC 2812, 3.1.3 "User message" - WEBIRC - See doc/Protocol.txt + WEBIRC + . + Allow Web-to-IRC gateway software (for example) 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 must be set in the server configuration file to prevent + unauthorized clients to fake their identity; it is an arbitrary string. + + References: + - doc/Protocol.txt, II.4: "Update webchat/proxy client information" General Commands @@ -184,21 +252,60 @@ General Commands See doc/Modes.txt for more information. - NOTICE - NOTICE + NOTICE [,[,...]] . - Send to (nick or channel). + Send a to a given , which can be a user or a + channel, but DON'T report any error. . - This command works similarly to PRIVMSG, except automatic replies must - never be sent in reply to NOTICE messages. + The "NOTICE" command exactly behaves like the "PRIVMSG" command, but + doesn't report any errors it encounters (like an unknown ). + Please see the help text of the "PRIVMSG" command for a detailed + description of the parameters! + + References: + - RFC 2812, 2.3.1 "Message format in Augmented BNF" + - RFC 2812, 3.3 "Sending messages" + - RFC 2812, 3.3.2 "Notice" - PRIVMSG - PRIVMSG + PRIVMSG [,[,...]] . - Send to (nick or channel). + Send a to a given , which can be a user or a + channel, and report all errors. . - Common IRC clients use MSG as PRIVMSG alias. - (Some clients use "QUERY []" to open a private chat.) + The must follow one of these syntax variants: + . + - + - + - [%]@ + - % + - !@ + . + If the is a user, a private message is sent directly to this + user; if it resolves to a channel name, a public message is sent + to all the members of that channel. + . + In addition, IRC Ops can use these two forms to specify the : + . + - # + - # + . + The can contain the wildcard characters "*" and "?", but must + contain at least one dot (".") and no wildcard after the last one. + Then, the is sent to all users matching this . + . + All warnings and errors are reported back to the initiator using + numeric status codes, which is the only difference to the "NOTICE" + command, which doesn't report back any errors or warnings at all. + . + Please note that clients often use "MSG" as an alias to PRIVMSG, and + a command "QUERY []" to initiate private chats. Both + are command extensions of the client and never sent to the server. + References: + - RFC 2812, 2.3.1 "Message format in Augmented BNF" + - RFC 2812, 3.3 "Sending messages" + - RFC 2812, 3.3.1 "Private messages" Status and Informational Commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -210,7 +317,7 @@ Status and Informational Commands . can be a server name, the nickname of a client connected to a specific server, or a mask matching a server name in the network. - The server of the current connecion is used when is omitted. + The server of the current connection is used when is omitted. References: - RFC 2812, 3.4.9 "Admin command" @@ -222,7 +329,7 @@ Status and Informational Commands . can be a server name, the nickname of a client connected to a specific server, or a mask matching a server name in the network. - The server of the current connecion is used when is omitted. + The server of the current connection is used when is omitted. References: - RFC 2812, 3.4.10 "Info command" @@ -231,7 +338,7 @@ Status and Informational Commands ISON [ [...]] . Query online status of a list of nicknames. The server replies with - a list only containing nicknes actually connected to a server in + a list only containing nicknames actually connected to a server in the network. If no nicknames of the given list are online, an empty list is returned to the client requesting the information. @@ -263,7 +370,7 @@ Status and Informational Commands . can be a server name, the nickname of a client connected to a specific server, or a mask matching a server name in the network. - The server of the current connecion is used when is omitted. + The server of the current connection is used when is omitted. Please note that ngIRCd ignores the parameter entirely: it is not possible to get information for a part of the network only. @@ -272,39 +379,68 @@ Status and Informational Commands - RFC 2812, 3.4.2 "Lusers message" - MOTD - MOTD [] + MOTD [] + . + Show the "Message of the Day" (MOTD) of an IRC server in the network. . - Show "Message Of The Day" of the current server or specified . + can be a server name, the nickname of a client connected to + a specific server, or a mask matching a server name in the network. + The server of the current connection is used when is omitted. + + References: + - RFC 2812, 3.4.1 "Motd message" - NAMES - NAMES [ []] + NAMES [[,[,...]] []] . - Returns a list of who is on the comma-separated list of , - by channel name. + Show the list of users that are members of a particular + (and that are visible for the client requesting this information) as + seen by the server . More than one can be given + separated by "," (but not whitespaces!). . - If is omitted, all users are shown, grouped by channel name - with all users who are not on a channel being shown as part of channel - "*". - If is specified, the command is sent to for - evaluation. + If has been omitted, all visible users are shown, grouped + by channel name, and all visible users not being members of at least + one channel are shown as members of the pseudo channel "*". + . + can be a server name, the nickname of a client connected to + a specific server, or a mask matching a server name in the network. + The server of the current connection is used when is omitted. + + References: + - RFC 2812, 3.2.5 "Names message" - STATS - STATS [] + STATS [ []] + . + Show statistics and other information of type of a particular + IRC server in the network. . - Returns statistics about the current server, or of a specified . + The following types are supported (case-insensitive): . - STATS flags: + - g Network-wide bans ("G-Lines"). + - k Server-local bans ("K-Lines"). + - l Link status (parent server and own link only). + - m Command usage count. + - u Server uptime. . - g = G-Lines (Network-wide bans) - k = K-Lines (Server-local bans) - l = Link status (Parent server and own link) - m = IRC command status (usage count) - u = Server uptime + can be a server name, the nickname of a client connected to + a specific server, or a mask matching a server name in the network. + The server of the current connection is used when is omitted. + + References: + - RFC 2812, 3.4.4 "Stats message" - TIME - TIME [] + TIME [] . - Show the local time of the current server, or of a specified . + Show the local time of an IRC server in the network. + . + can be a server name, the nickname of a client connected to + a specific server, or a mask matching a server name in the network. + The server of the current connection is used when is omitted. + + References + - RFC 2812, 3.4.6 "Time message" - TRACE TRACE [] @@ -313,56 +449,94 @@ Status and Informational Commands of a specific , in a similar method to traceroute. - USERHOST - USERHOST + USERHOST [ [...]] + . + Show flags and the hostmasks (@) of the s, + separated by spaces. The following flags are used: . - Show the user-host of (seperated by space). - "-" means is away, - "+" means is available, - "*" indicates your connection. + - "-" The client is "away" (the mode "+a" is set on this client). + - "+" Client seems to be available, at least it isn't marked "away". + - "*" The client is an IRC operator (the mode "+o" is set). + + References: + - RFC 2812, 4.8 "Userhost message" - VERSION - VERSION [] + VERSION [] + . + Show version information about a particular IRC server in the network. + . + can be a server name, the nickname of a client connected to + a specific server, or a mask matching a server name in the network. + The server of the current connection is used when is omitted. . - Show the ngIRCd version of the current server, or specified . + Please note: in normal operation, the version number ends in a dot + (".", for example "ngIRCd-20.1."). If it ends in ".1" (for example + "ngIRCd-20.1.1", same version than before!), the server is running in + debug-mode; and if it ends in ".2", the "network sniffer" is active! + Keep your privacy in mind ... + + References: + - RFC 2812, 3.4.3 "Version message" - WHO - WHO [ ["o"]] + WHO [ ["o"]] . - Returns a list of users who match (nick, hostmask or channel). + Show a list of users who match the , or all visible users when + the has been omitted. (Special case: the "0" is + equivalent to "*") . If the flag "o" is given, the server will only return information about IRC Operators. + References: + - RFC 2812, 3.6.1 "Who query" + - WHOIS - WHOIS [] + WHOIS [] [,[,...]] . - Returns information about the comma-separated list of . + Query information about users matching the parameter(s) as seen + by the server ; up to 3 are supported. . - If is given, the command is forwarded to it for processing. + can be a server name, the nickname of a client connected to a + specific server, or a mask matching a server name in the network. The + server of the current connection is used when is omitted. + + References: + - RFC 2812, 3.6.2 "Whois query" - WHOWAS - WHOWAS [ []] + WHOWAS [,[,...]] [ []] . - Used to return information about that are no longer in use - (due to client disconnection, or nickname changes). + Query information about nicknames no longer in use in the network, + either because of nickname changes or disconnects. The history is + searched backwards, returning the most recent entry first. If there + are multiple entries, up to entries will be shown (or all of + them, if no has been given). . - If given, the server will return information from the last times - the nickname has been used. - If is given, the command is forwarded to it for processing. + can be a server name, the nickname of a client connected to a + specific server, or a mask matching a server name in the network. The + server of the current connection is used when is omitted. + + References: + - RFC 2812, 3.6.3 "Whowas" Channel Commands ~~~~~~~~~~~~~~~~ - INVITE - INVITE + INVITE . - Invites to . - does not have to exist, but if it does, only members of the - channel are allowed to invite other clients. + Invite to join channel . . - If the mode "+i" is set, only operators may invite - other clients. + does not have to exist, but if it does, only members of the + channel are allowed to invite other users. If the channel mode "+i" + is set, only channel "half-ops" (and above) may invite other clients, + and if channel mode "+V" is set, nobody can invite other users. + + References: + - RFC 2812, 3.2.7 "Invite message" - JOIN JOIN [] @@ -374,11 +548,18 @@ Channel Commands If the channel(s) do not exist, then they will be created. - KICK - KICK [] + KICK [,[,...]] [,[,...]] [] . - Remove from , optional with a . + Remove users(s) with (s) from (s). . - Only operators are able to KICK. + There must be either exactly one parameter and multiple + parameters, or as many parameters as there are + parameters. The is shown to the users being + kicked, and the nickname of the current user is used when + is omitted. + + References: + - RFC 2812, 3.2.8 "Kick command" - LIST LIST [ []] @@ -439,9 +620,16 @@ Administrative Commands To list the G-Lines, type "STATS g". - KILL - KILL + KILL + . + Forcibly remove all users with a given from the IRC + network and display the given to them. . - Forcibly removes from the IRC network with a . + This command is used internally between servers, too, for example + to disconnect duplicate 's after a "net split". + + References: + - RFC 2812, 3.7.1 "Kill message" - KLINE KLINE : @@ -478,12 +666,69 @@ IRC Service Commands ~~~~~~~~~~~~~~~~~~~~ - SERVICE + SERVICE + SERVICE {|+} + . + Register a new service in the network. + . + The first form is used by directly linked services and isn't supported + by ngIRCd at the moment. The second form announces services connected + to remote "pseudo-servers" ("services hubs"). + . + The and parameters are ignored by ngIRCd. + + References: + - RFC 2812, 3.1.6 "Service message" + - RFC 2813, 4.1.4 "Service message" - SERVLIST + SERVLIST [ []] + . + List all IRC services currently registered in the network. + . + The optional and parameters can be used to limit the + listing to services matching the and that are of type . + . + Please note that ngIRCd doesn't use any service types at the moment + and therefore all services are of type "0". + + References: + - RFC 2812, 3.5.1 "Servlist message" - SQUERY + SQUERY [,[,...]] + . + Send a to a given IRC service, and report all + errors. + . + The "SQUERY" command exactly behaves like the "PRIVMSG" command, but + enforces that the of the is an IRC service. + Please see the help text of the "PRIVMSG" command for a detailed + description of the parameters! + . + If a user wants to interact with IRC services, he should use "SQUERY" + instead of "PRIVMSG" or "NOTICE": only "SQUERY makes sure that no + regular user, which uses the nickname of an IRC service, receives + the command in error, for example during a "net split"! + + References: + - RFC 2812, 2.3.1 "Message format in Augmented BNF" + - RFC 2812, 3.3 "Sending messages" + - RFC 2812, 3.3.2 "Notice" - SVSNICK + SVSNICK + . + Forcefully change foreign user nicknames. This command is allowed + for servers only. + . + The "SVSNICK" command is forwarded to the server to which the user + with nickname is connected to, which in turn generates a + regular "NICK" command that then is sent to the client, so no special + support in the client software is required. + + References: + - ngIRCd GIT commit e3f300d3231f Server Protocol Commands @@ -500,11 +745,18 @@ Server Protocol Commands - ERROR ERROR [ [<> [...]]] . - Return an error message to the server. The first parameter, if given, - will be logged by the server, all further parameters are silently - ignored. + Inform a client or a server about an error condition. The first + parameter, if given, is logged by the server receiving the message, + all other parameters are silently ignored. . - This command is silently ignored on non-server and non-service links. + This command is silently ignored on non-server and non-service links + and shouldn't be used by regular IRC clients. + . + The ERROR message is also sent before terminating a regular client + connection. + + References: + - RFC 2812, 3.7.4 "Error message" - METADATA METADATA @@ -529,8 +781,27 @@ Dummy Commands ~~~~~~~~~~~~~~ - SUMMON + SUMMON [ []] + . + This command was intended to call people into IRC who are directly + connected to the terminal console of the IRC server -- but is + deprecated today. Therefore ngIRCd doesn't really implement this + command and always returns an error message, regardless of the + parameters given. + + References: + - RFC 2812, 4.5 "Summon message" - USERS + USERS [] + . + This command was intended to list users directly logged in into the + console of the IRC server -- but is deprecated today. Therefore ngIRCd + doesn't really implement this command and always returns an error + message, regardless of the parameters given. + + References: + - RFC 2812, 4.6 "Users" - GET