]> arthur.barton.de Git - ngircd-alex.git/blob - doc/Commands.txt
Commands.txt: Update description of the "TIME" command
[ngircd-alex.git] / doc / Commands.txt
1
2                      ngIRCd - Next Generation IRC Server
3                            http://ngircd.barton.de/
4
5                (c)2001-2013 Alexander Barton and Contributors.
6                ngIRCd is free software and published under the
7                    terms of the GNU General Public License.
8
9                               -- Commands.txt --
10
11
12 This file lists all commands available on ngIRCd. It is written in a format
13 that is human readable as well as machine parseable and therefore can be used
14 as "help text file" of the daemon.
15
16 In short, the daemon reads this file on startup and parses it as following
17 when an user issues a "HELP <cmd>" command:
18
19  1. Search the file for a line "- <cmd>",
20  2. Output all subsequent lines that start with a TAB (ASCII 9) character
21     to the client using NOTICE commands, treat lines containing a single "."
22     after the TAB as empty lines.
23  3. Break at the first line not starting with a TAB character.
24
25 This format allows to have information to each command stored in this file
26 which will not be sent to an IRC user requesting help which enables us to
27 have additional annotations stored here which further describe the origin,
28 implementation details, or limits of the specific command which are not
29 relevant to an end-user but administrators and developers.
30
31 A special "Intro" block is returned to the user when the HELP command is
32 used without a command name:
33
34
35 - Intro
36         This is ngIRCd, a server software for Internet Relay Chat (IRC)
37         networks. You can find more information about ngIRCd on its homepage:
38                 <http://ngircd.barton.de>
39         .
40         Use "HELP COMMANDS" to get a list of all available commands and
41         "HELP <command-name>" to get help for a specific IRC command, for
42         example "HELP quit" or "HELP privmsg".
43
44
45 Connection Handling Commands
46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47
48 - CAP
49         CAP LS
50         CAP LIST
51         CAP REQ <capabilities>
52         CAP ACK <capabilities>
53         CAP NAK <capabilities>
54         CAP CLEAR
55         CAP END
56         .
57         List, request, and clear "IRC Capabilities".
58         .
59         Using this command, an IRC client can request additional "IRC
60         capabilities" during login or later on, which influences the
61         communication between server and client. Normally, these commands
62         aren't directly used by humans, but automatically by their client
63         software. And please note that issuing such commands manually can
64         irritate the client software used, because of the "non-standard"
65         behavior of the server!
66         .
67         - CAP LS: list all available capabilities.
68         - CAP LIST: list active capabilities of this connection.
69         - CAP REQ: Request particular capabilities.
70         - CAP ACK: Acknowledge a set of capabilities to be enabled/disabled.
71         - CAP NAK: Reject a set of capabilities.
72         - CAP CLEAR: Clear all set capabilities.
73         - CAP END: Indicate end of capability negotiation during login,
74           ignored in an fully registered session.
75
76         Please note that the <capabilities> must be given in a single
77         parameter but whitespace separated, therefore a command could look
78         like this: "CAP REQ :capability1 capability2 capability3" for example.
79
80         References:
81          - <http://ircv3.atheme.org/specification/capability-negotiation-3.1>
82          - <http://ngircd.barton.de/doc/Capabilities.txt>
83          - doc/Capabilities.txt
84
85 - CHARCONV
86         CHARCONV <client-charset>
87         .
88         Set client character set encoding to <client-charset>.
89         .
90         After receiving such a command, the server translates all message
91         data received from the client using the set <client-charset> to the
92         server encoding (UTF-8), and all message data which is to be sent to
93         the client from the server encoding (UTF-8) to <client-charset>.
94         .
95         This enables older clients and clients using "strange" character sets
96         to transparently participate in channels and direct messages to
97         clients using UTF-8, which should be the default today.
98
99         References:
100          - <http://ngircd.barton.de/doc/Protocol.txt>
101          - doc/Protocol.txt
102
103 - NICK
104         NICK <nick>
105         .
106         Change your nickname to <nick>.
107
108 - PASS
109         PASS <password> <version> <flags> [<options>]
110         .
111         Set a connection <password>. This command must be sent before the
112         NICK/USER registration combination.
113         .
114         See doc/Protocol.txt for more info.
115
116 - PING
117         PING <server1> [<server2>]
118         .
119         Tests the presence of a connection. A PING message results in a PONG
120         reply. If <server2> is specified, the message gets passed on to it.
121
122 - PONG
123         PONG <server1> [<server2>]
124         .
125         This command is a reply to the PING command and works in much the
126         same way.
127
128 - QUIT
129         QUIT [<quit-message>]
130         .
131         End IRC session and disconnect from the server.
132         .
133         If a <quit-message> has been given, it is displayed to all the
134         channels that you are a member of when leaving.
135
136 - USER
137         USER <user> <modes> <realname>
138         .
139         This command is used at the beginning of a connection to specify the
140         <user>name, hostname, <realname> and initial user <modes> of the
141         connecting client.
142         .
143         <realname> may contain spaces, and thus must be prefixed with a colon.
144
145 - WEBIRC
146         See doc/Protocol.txt
147
148
149 General Commands
150 ~~~~~~~~~~~~~~~~
151
152 - AWAY
153         AWAY [<message>]
154         .
155         Provides the server with a message to automatically send in reply to a
156         PRIVMSG directed at the user, but not to a channel they are on.
157         .
158         If <message> is omitted, the away status is removed.
159
160 - HELP
161         HELP [<command>]
162         .
163         Show help information for a specific IRC <command>. The <command> name
164         is case-insensitive.
165         .
166         Use the command "HELP Commands" to get a list of all available commands.
167
168         The HELP command isn't specified by any RFC but implemented by most
169         daemons. If no help text could be read in, ngIRCd outputs a list of all
170         implemented commands when receiving a plain "HELP" command as well as
171         on "HELP Commands".
172
173         ngIRCd replies using "NOTICE" commands like ircd 2.10/2.11; other
174         implementations are using numerics 704, 705, and 706.
175
176
177 - MODE
178         MODE <nickname> <flags> (user)
179         MODE <channel> <flags> [<args>]
180         .
181         The MODE command is dual-purpose. It can be used to set both (user) and
182         <channel> modes.
183         .
184         See doc/Modes.txt for more information.
185
186 - NOTICE
187         NOTICE <target> <notice>
188         .
189         Send <notice> to <target> (nick or channel).
190         .
191         This command works similarly to PRIVMSG, except automatic replies must
192         never be sent in reply to NOTICE messages.
193
194 - PRIVMSG
195         PRIVMSG <target> <message>
196         .
197         Send <message> to <target> (nick or channel).
198         .
199         Common IRC clients use MSG as PRIVMSG alias.
200         (Some clients use "QUERY <nick> [<message>]" to open a private chat.)
201
202
203 Status and Informational Commands
204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
205
206 - ADMIN
207         ADMIN [<target>]
208         .
209         Show administrative information about an IRC server in the network.
210         .
211         <target> can be a server name, the nickname of a client connected to
212         a specific server, or a mask matching a server name in the network.
213         The server of the current connecion is used when <target> is omitted.
214
215         References:
216          - RFC 2812, 3.4.9 "Admin command"
217
218 - INFO
219         INFO [<target>]
220         .
221         Show the version, birth & online time of an IRC server in the network.
222         .
223         <target> can be a server name, the nickname of a client connected to
224         a specific server, or a mask matching a server name in the network.
225         The server of the current connecion is used when <target> is omitted.
226
227         References:
228          - RFC 2812, 3.4.10 "Info command"
229
230 - ISON
231         ISON <nickname> [<nickname> [...]]
232         .
233         Query online status of a list of nicknames. The server replies with
234         a list only containing nicknes actually connected to a server in
235         the network. If no nicknames of the given list are online, an empty
236         list is returned to the client requesting the information.
237
238         Please note that "all" IRC daemons even parse separate nicknames in
239         a single parameter (like ":nick1 nick2"), and therefore ngIRCd
240         implements this behaviour, too.
241
242         References:
243          - RFC 2812, 4.9 "Ison message"
244
245 - LINKS
246         LINKS [[<target>] [<mask>]
247         .
248         List all servers currently registered in the network matching <mask>,
249         or all servers if <mask> has been omitted, as seen by the server
250         specified by <target> or the local server when <target> is omitted.
251         .
252         <target> can be a server name, the nickname of a client connected to
253         a specific server, or a mask matching a server name in the network.
254
255         References:
256          - RFC 2812, 3.4.5 "Links message"
257
258 - LUSERS
259         LUSERS [<mask> [<target>]]
260         .
261         Return statistics about the number of clients (users, servers,
262         services, ...) in the network as seen by the server <target>.
263         .
264         <target> can be a server name, the nickname of a client connected to
265         a specific server, or a mask matching a server name in the network.
266         The server of the current connecion is used when <target> is omitted.
267
268         Please note that ngIRCd ignores the <mask> parameter entirely: it
269         is not possible to get information for a part of the network only.
270
271         References:
272          - RFC 2812, 3.4.2 "Lusers message"
273
274 - MOTD
275         MOTD [<target>]
276         .
277         Show the "Message of the Day" (MOTD) of an IRC server in the network.
278         .
279         <target> can be a server name, the nickname of a client connected to
280         a specific server, or a mask matching a server name in the network.
281         The server of the current connecion is used when <target> is omitted.
282
283         References:
284          - RFC 2812, 3.4.1 "Motd message"
285
286 - NAMES
287         NAMES [<channel>[,<channel>[,...]] [<target>]]
288         .
289         Show the list of users that are members of a particular <channel>
290         (and that are visible for the client requesting this information) as
291         seen by the server <target>. More than one <channel> can be given
292         separated by "," (but not whitespaces!).
293         .
294         If <channel> has been omitted, all visible users are shown, grouped
295         by channel name, and all visible users not being members of at least
296         one channel are shown as members of the pseudo channel "*".
297         .
298         <target> can be a server name, the nickname of a client connected to
299         a specific server, or a mask matching a server name in the network.
300         The server of the current connecion is used when <target> is omitted.
301
302         References:
303          - RFC 2812, 3.2.5 "Names message"
304
305 - STATS
306         STATS [<query> [<target>]]
307         .
308         Show statistics and other information of type <query> of a particular
309         IRC server in the network.
310         .
311         The following <query> types are supported (case-insensitive):
312         .
313          - g  Network-wide bans ("G-Lines").
314          - k  Server-local bans ("K-Lines").
315          - l  Link status (parent server and own link only).
316          - m  Command usage count.
317          - u  Server uptime.
318         .
319         <target> can be a server name, the nickname of a client connected to
320         a specific server, or a mask matching a server name in the network.
321         The server of the current connecion is used when <target> is omitted.
322
323         References:
324          - RFC 2812, 3.4.4 "Stats message"
325
326 - TIME
327         TIME [<target>]
328         .
329         Show the local time of an IRC server in the network.
330         .
331         <target> can be a server name, the nickname of a client connected to
332         a specific server, or a mask matching a server name in the network.
333         The server of the current connecion is used when <target> is omitted.
334
335         References
336          - RFC 2812, 3.4.6 "Time message"
337
338 - TRACE
339         TRACE [<server>]
340         .
341         Trace a path across the IRC network of the current server, or if given
342         of a specific <server>, in a similar method to traceroute.
343
344 - USERHOST
345         USERHOST <nicknames>
346         .
347         Show the user-host of <nicknames> (seperated by space).
348         "-" means <nick> is away,
349         "+" means <nick> is available,
350         "*" indicates your connection.
351
352 - VERSION
353         VERSION [<server>]
354         .
355         Show the ngIRCd version of the current server, or specified <server>.
356
357 - WHO
358         WHO [<target> ["o"]]
359         .
360         Returns a list of users who match <target> (nick, hostmask or channel).
361         .
362         If the flag "o" is given, the server will only return information about
363         IRC Operators.
364
365 - WHOIS
366         WHOIS [<server>] <nicknames>
367         .
368         Returns information about the comma-separated list of <nicknames>.
369         .
370         If <server> is given, the command is forwarded to it for processing.
371
372 - WHOWAS
373         WHOWAS <nickname> [<count> [<server>]]
374         .
375         Used to return information about <nicknames> that are no longer in use
376         (due to client disconnection, or nickname changes).
377         .
378         If given, the server will return information from the last <count> times
379         the nickname has been used.
380         If <server> is given, the command is forwarded to it for processing.
381
382
383 Channel Commands
384 ~~~~~~~~~~~~~~~~
385
386 - INVITE
387         INVITE <nick> <channel>
388         .
389         Invites <nick> to <channel>.
390         <channel> does not have to exist, but if it does, only members of the
391         channel are allowed to invite other clients.
392         .
393         If the <channel> mode "+i" is set, only <channel> operators may invite
394         other clients.
395
396 - JOIN
397         JOIN <channels> [<channel-keys>]
398         .
399         Makes the client join the <channels> (comma-separated list), specifying
400         the passwords, if needed, in the comma-separated <channel-keys> list.
401         A <channel-key> is only needed, if the <channel> mode "+k" is set.
402         .
403         If the channel(s) do not exist, then they will be created.
404
405 - KICK
406         KICK <channel> <nick> [<kick-message>]
407         .
408         Remove <nick> from <channel>, optional with a <kick-message>.
409         .
410         Only <channel> operators are able to KICK.
411
412 - LIST
413         LIST [<channels> [<server>]]
414         .
415         List all visible <channels> (comma-seperated list) on the current
416         server.
417         If <server> is given, the command will be forwarded to <server> for
418         evaluation.
419
420 - PART
421         PART <channels> [<part-message>]
422         .
423         Leave <channels> (comma-separated list), optional with a
424         <part-message>.
425
426 - TOPIC
427         TOPIC <channel> <topic>
428         .
429         Set a <topic> for <channel>.
430         .
431         Only <channel> operators are able to set a <topic>.
432
433
434 Administrative Commands
435 ~~~~~~~~~~~~~~~~~~~~~~~
436
437 - CONNECT
438         CONNECT <target server> [<port> [<remote server> [<mypwd> <peerpwd>]]]
439         .
440         Instructs the current server, or <remote server> if specified,
441         to connect to <target server>.
442         .
443         To connect <remote server> you need to have remote oper status.
444         If <port> is omitted, it uses the server port of the configuration.
445         If <mypwd> and <peerpwd> is given, it uses those passwords instead
446         of the ones in the configuration.
447
448 - DIE
449         DIE
450         .
451         Instructs the server to shut down.
452
453 - DISCONNECT
454         DISCONNECT [<remote server>]
455         .
456         Disconnects the current server, or <remote server> if specified.
457         To disconnect a <remote server> you need to have remote oper status.
458
459 - GLINE
460         GLINE <nick!user@hostmask> <seconds> :<reason>
461         .
462         This command provides timed G-Lines (Network-wide bans).
463         If a client matches a G-Line, it cannot connect to any server on
464         the IRC network. If you put 0 as <seconds>, it makes the G-Line
465         permanent.
466         .
467         To remove a G-Line, type "GLINE <nick!user@hostmask>".
468         To list the G-Lines, type "STATS g".
469
470 - KILL
471         KILL <nick> <reason>
472         .
473         Forcibly removes <nick> from the IRC network with a <reason>.
474
475 - KLINE
476         KLINE <nick!user@hostmask> <seconds> :<reason>
477         .
478         This command provides timed K-Lines (Server-local bans).
479         If a client matches a K-Line, it cannot connect to the issued server.
480         If you put 0 as <seconds>, it makes the K-Line permanent.
481         .
482         To remove a K-Line, type "KLINE <nick!user@hostmask>".
483         To list the K-Lines, type "STATS k".
484
485 - OPER
486         OPER <user> <password>
487         .
488         Authenticates <user> as an IRC operator on the current server/network.
489
490 - REHASH
491         REHASH
492         .
493         Causes the server to re-read and re-process its configuration file(s).
494
495 - RESTART
496         RESTART
497         .
498         Restart the server.
499
500 - WALLOPS
501         WALLOPS <message>
502         .
503         Sends <message> to all users with user mode "+w".
504
505
506 IRC Service Commands
507 ~~~~~~~~~~~~~~~~~~~~
508
509 - SERVICE
510
511 - SERVLIST
512
513 - SQUERY
514
515 - SVSNICK
516
517
518 Server Protocol Commands
519 ~~~~~~~~~~~~~~~~~~~~~~~~
520
521 - CHANINFO
522         CHANINFO <channel> +<modes> [[<key> <limit>] <topic>]
523         .
524         CHANINFO is used by servers to inform each other about a channel:
525         its modes, channel key, user limits and its topic.
526         .
527         See doc/Protocol.txt for more information.
528
529 - ERROR
530         ERROR [<message> [<> [...]]]
531         .
532         Return an error message to the server. The first parameter, if given,
533         will be logged by the server, all further parameters are silently
534         ignored.
535         .
536         This command is silently ignored on non-server and non-service links.
537
538 - METADATA
539         METADATA <target> <key> <value>
540         .
541         The METADATA command is used on server-links to update "metadata"
542         information of clients, like the hostname, the info text ("real name"),
543         or the user name.
544         .
545         See doc/Protocol.txt for more information.
546
547 - NJOIN
548
549 - SERVER
550
551 - SQUIT
552         SQUIT <server>
553         .
554         Disconnects an IRC Server from the network.
555
556
557 Dummy Commands
558 ~~~~~~~~~~~~~~
559
560 - SUMMON
561
562 - USERS
563
564 - GET
565
566 - POST