X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?p=ngircd-alex.git;a=blobdiff_plain;f=doc%2FCommands.txt;h=50a52d58d56c92cec5a40d3f65fb9312f2b0cd34;hp=627efa5b2f04759bd7f41a2a6431dbf51578b9dd;hb=b8482fd3cfdb429aec75575958f4d5d4e9ae22df;hpb=35452b31579174e0714ff7912a5857b82c787804 diff --git a/doc/Commands.txt b/doc/Commands.txt index 627efa5b..50a52d58 100644 --- a/doc/Commands.txt +++ b/doc/Commands.txt @@ -78,7 +78,7 @@ Connection Handling Commands like this: "CAP REQ :capability1 capability2 capability3" for example. References: - - + - - - doc/Capabilities.txt @@ -97,53 +97,123 @@ Connection Handling Commands clients using UTF-8, which should be the default today. References: - - - - doc/Protocol.txt + - IRC+, + - IRC+, 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) + - IRC+, + - IRC+, doc/Protocol.txt - PING - PING [] + PING [] + . + Tests the presence of a connection to a client or server. . - Tests the presence of a connection. A PING message results in a PONG - reply. If is specified, the message gets passed on to it. + If no has been given, the local server is used. User clients + can only use other servers as , no user clients. + . + 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 forwarded 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: + - IRC+, + - IRC+, doc/Protocol.txt General Commands @@ -157,6 +227,9 @@ General Commands . If is omitted, the away status is removed. + References: + - RFC 2812, 4.1 "Away" + - HELP HELP [] . @@ -173,32 +246,102 @@ General Commands ngIRCd replies using "NOTICE" commands like ircd 2.10/2.11; other implementations are using numerics 704, 705, and 706. - - MODE - MODE (user) - MODE [] + MODE [{+|-}[] [{+|-}[] [...]]] + MODE [{+|-}[] [ [ [...]]] [{+|-}[] [ [ [...]]] [...]]] + . + Set and get user and channel modes. . - The MODE command is dual-purpose. It can be used to set both (user) and - modes. + When no mode parameters are given, the currently set user or channel + modes are returned. Otherwise the modes are adjusted accordingly + and the changes will be reported back to the client. . - See doc/Modes.txt for more information. + All user and channel "modes" are indicated by single case-sensitive + characters. + . + Please note that a user can only get and set his own modes, and not + all user "levels" are allowed to change all channel modes ... + . + The mode parameters can become quite complex, especially when dealing + with channel modes that require additional arguments: + . + {+|-} -- set or unset one or more modes. + + - -- set some modes and unset others. + + -- set (at least) two modes with arguments. + . + Some examples: + . + MODE nick +i -- set user to "invisible". + MODE #chan +tn -- set "topic lock" and "no external messages". + MODE #chan -t +l 50 -- remove "topic lock", set "user limit" to 50. + MODE #chan +ov nick1 nick2 -- set "channel op" and "voice" mode + to nick1 and nick2 in channel #chan. + . + A complete list of all modes supported by ngIRCd can be found online + here: . + + References: + - RFC 2811, 4. "Channel Modes" + - RFC 2812, 3.1.5 "User mode message" + - RFC 2812, 3.2.3 "Channel mode message" + - + - doc/Modes.txt - 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 a to a given , which can be a user or a + channel, and report all errors. + . + 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. . - Send to (nick or channel). + In addition, IRC Ops can use these two forms to specify the : . - Common IRC clients use MSG as PRIVMSG alias. - (Some clients use "QUERY []" to open a private chat.) + - # + - # + . + 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 +353,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 +365,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 +374,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 +406,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. @@ -278,7 +421,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.1 "Motd message" @@ -297,7 +440,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.2.5 "Names message" @@ -308,17 +451,21 @@ Status and Informational Commands Show statistics and other information of type of a particular IRC server in the network. . - The following types are supported (case-insensitive): + The following types are supported (case-insensitive where + applicable): . - g Network-wide bans ("G-Lines"). - k Server-local bans ("K-Lines"). - - l Link status (parent server and own link only). + - L Link status (servers and user links). + - l Link status (servers and own link). - m Command 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 connecion is used when is omitted. + The server of the current connection is used when is omitted. + . + To use "STATS L" the user must be an IRC Operator. References: - RFC 2812, 3.4.4 "Stats message" @@ -330,22 +477,31 @@ 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.6 "Time message" - TRACE - TRACE [] + TRACE [] + . + Find the route to a specific server and send information about its + peers. Each server that processes this command reports back to the + sender about it: the replies from pass-through servers form a chain + which shows the route to the destination. . - Trace a path across the IRC network of the current server, or if given - of a specific , in a similar method to traceroute. + 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.8 "Trace message" - USERHOST USERHOST [ [...]] . Show flags and the hostmasks (@) of the s, - seperated by spaces. The following flags are used: + separated by spaces. The following flags are used: . - "-" The client is "away" (the mode "+a" is set on this client). - "+" Client seems to be available, at least it isn't marked "away". @@ -361,7 +517,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: in normal operation, the version number ends in a dot (".", for example "ngIRCd-20.1."). If it ends in ".1" (for example @@ -393,7 +549,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. + server of the current connection is used when is omitted. References: - RFC 2812, 3.6.2 "Whois query" @@ -409,7 +565,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. + server of the current connection is used when is omitted. References: - RFC 2812, 3.6.3 "Whowas" @@ -419,129 +575,244 @@ 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 [] + JOIN {[,[,...]] [[,[,...]]] | 0} . - Makes the client join the (comma-separated list), specifying - the passwords, if needed, in the comma-separated list. - A is only needed, if the mode "+k" is set. + Makes the client join the (comma-separated list), specifying + the channel keys ("passwords"). A is only needed if the + has the mode "+k" set. . If the channel(s) do not exist, then they will be created. + . + Using "JOIN 0" parts all channels at once. + + References: + - RFC 2812, 3.2.1 "Join message" (client protocol) + - RFC 2813, 4.2.1 "Join message" (server protocol) - 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 [ []] + LIST [[,[,...]] []] + . + List all visible (comma-separated list). . - List all visible (comma-seperated list) on the current - server. If is given, the command will be forwarded to for evaluation. + References: + - RFC 2812, 3.2.6 "List message" + - PART - PART [] + PART [,[,...]] [] . - Leave (comma-separated list), optional with a - . + Leave (comma-separated list), optionally with sending a + to all the other channel members. + + References: + - RFC 2812, 3.2.2 "Part message" - TOPIC - TOPIC + TOPIC [] . - Set a for . + Change or view the topic of a channel. . - Only operators are able to set a . + The topic for channel is returned if there is no + given. If the parameter is present, the topic for that + channel will be changed, if this action is allowed for the user + requesting it. If the parameter is an empty string, the + topic for that channel will be removed. + + References: + - RFC 2812, 3.2.4 "Topic message" Administrative Commands ~~~~~~~~~~~~~~~~~~~~~~~ - CONNECT - CONNECT [ [ [ ]]] + CONNECT [ [ [ ]]] + . + Instructs the current server, or if specified, + to connect to the server named , which must be configured + in the server configuration file. . - Instructs the current server, or if specified, - to connect to . + To use this command, the user must be an IRC Operator. To establish + a connection on a , you must have remote IRC operator + privileges. . - To connect you need to have remote oper status. - If is omitted, it uses the server port of the configuration. - If and is given, it uses those passwords instead - of the ones in the configuration. + If , and are given, these values override + the ones specified in the server configuration file. + + References: + - RFC 2812, 3.4.7 "Connect message" - DIE - DIE + DIE [] . Instructs the server to shut down. + . + The optional (and non-standard) text is sent to each client + connected to this server before all connections are closed. + . + To use this command, the user must be an IRC Operator. + + References: + - RFC 2812, 4.3 "Die message" - DISCONNECT - DISCONNECT [] + DISCONNECT + . + Disconnect and disable a locally linked server. . - Disconnects the current server, or if specified. - To disconnect a you need to have remote oper status. + To use this command, the user must be an IRC Operator. + + References: + - This command is not specified in the IRC RFCs, it is an extension + of ngIRCd. - GLINE - GLINE : + GLINE [ :] + . + This command provides timed G-Lines (network-wide bans). . - This command provides timed G-Lines (Network-wide bans). If a client matches a G-Line, it cannot connect to any server on - the IRC network. If you put 0 as , it makes the G-Line - permanent. + the IRC network for seconds. When is 0, it make + the G-Line permanent. + . + If no and no is given, the G-Line is removed. + . + To use this command, the user must be an IRC Operator. . - To remove a G-Line, type "GLINE ". - To list the G-Lines, type "STATS g". + "STATS g" can be used to list all currently active G-Lines. + + References: + - This command is not specified in the IRC RFCs, it is an extension + of ngIRCd. - KILL - KILL + KILL . - Forcibly removes from the IRC network with a . + Forcibly remove all users with a given from the IRC + network and display the given to them. + . + This command is used internally between servers, too, for example + to disconnect duplicate 's after a "net split". + . + To use this command, the user must be an IRC Operator. + + References: + - RFC 2812, 3.7.1 "Kill message" - KLINE - KLINE : + KLINE [ :] + . + This command provides timed K-Lines (server-local bans). . - This command provides timed K-Lines (Server-local bans). - If a client matches a K-Line, it cannot connect to the issued server. - If you put 0 as , it makes the K-Line permanent. + If a client matches a K-Line, it cannot connect to this server for + seconds. When is 0, it makes the K-Line permanent. . - To remove a K-Line, type "KLINE ". - To list the K-Lines, type "STATS k". + If no and no is given, the K-Line is removed. + . + To use this command, the user must be an IRC Operator. + . + "STATS k" can be used to list all currently active K-Lines. + + References: + - This command is not specified in the IRC RFCs, it is an extension + of ngIRCd. - OPER - OPER + OPER . - Authenticates as an IRC operator on the current server/network. + Authenticates a user named as an IRC operator on the current + server/network. + . + This operator must be configured in the server configuration. + . + Please note that is NOT related to a nickname at all! + + References: + - RFC 2812, 3.1.4 "Oper message" - REHASH REHASH . Causes the server to re-read and re-process its configuration file(s). + . + While rehashing, no new connections are accepted, but all already + established connections stay connected. + . + To use this command, the user must be an IRC Operator. + + References: + - RFC 2812, 4.2 "Rehash message" - RESTART RESTART . Restart the server. + . + While restarting, all connections are reset and no new connections + are accepted. + . + To use this command, the user must be an IRC Operator. + + References: + - RFC 2812, 4.4 "Restart message" - WALLOPS WALLOPS . Sends to all users with user mode "+w". + . + To use this command, the user must be an IRC Operator. + References: + - RFC 2812, 4.7 "Operwall message" 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 [ []] @@ -558,8 +829,39 @@ IRC Service Commands - 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 @@ -571,16 +873,27 @@ Server Protocol Commands CHANINFO is used by servers to inform each other about a channel: its modes, channel key, user limits and its topic. . - See doc/Protocol.txt for more information. + The CHANINFO command is allowed on server-links only. + + References: + - IRC+, + - IRC+, doc/Protocol.txt - 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 @@ -589,17 +902,49 @@ Server Protocol Commands information of clients, like the hostname, the info text ("real name"), or the user name. . - See doc/Protocol.txt for more information. + The METADATA command is allowed on server-links only. + + References: + - IRC+, + - IRC+, doc/Protocol.txt - NJOIN + NJOIN [][,[][,...]] + . + The NJOIN command is used on server-links to add users with + and to a while peering. + . + The NJOIN command is allowed on server-links only. + + References: + - RFC 2813, 4.2.2 "Njoin message" - SERVER + SERVER + SERVER + SERVER + . + The first form registers the local connection as a new server in the + network, the second (RFC 1459) and third (RFC 2812) form announce a + new remote server in the network. + . + The SERVER command is allowed on unregistered or server-links only. + + References: + - RFC 1459, 4.1.4 "Server message" + - RFC 2813, 4.1.2 "Server message" - SQUIT - SQUIT + SQUIT . Disconnects an IRC Server from the network. + . + This command is used on server-links, but can be used by IRC Operators + to forcefully disconnect servers from the network, too. + References: + - RFC 2812, 3.1.8 "Squit" + - RFC 2813, 4.1.6 "Server quit message" Dummy Commands ~~~~~~~~~~~~~~ @@ -617,7 +962,30 @@ Dummy Commands - 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 + GET [...] + . + Fake HTTP GET command. When received, the connection is shut down + immediately again to protect against crazy web browsers ... + + References: + - ngIRCd GIT commit 33e8c2480649 - POST + POST [...] + . + Fake HTTP POST command. When received, the connection is shut down + immediately again to protect against crazy web browsers ... + + References: + - ngIRCd GIT commit 33e8c2480649