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 connection 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 connection 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 nicknames 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 connection 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 connection 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 connection 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 connection 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 connection 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 <nickname> [<nickname> [...]]
 346         .
 347         Show flags and the hostmasks (<user>@<host>) of the <nickname>s,
 348         separated by spaces. The following flags are used:
 349         .
 350          - "-"  The client is "away" (the mode "+a" is set on this client).
 351          - "+"  Client seems to be available, at least it isn't marked "away".
 352          - "*"  The client is an IRC operator (the mode "+o" is set).
 353
 354         References:
 355          - RFC 2812, 4.8 "Userhost message"
 356
 357 - VERSION
 358         VERSION [<target>]
 359         .
 360         Show version information about a particular IRC server in the network.
 361         .
 362         <target> can be a server name, the nickname of a client connected to
 363         a specific server, or a mask matching a server name in the network.
 364         The server of the current connection is used when <target> is omitted.
 365         .
 366         Please note: in normal operation, the version number ends in a dot
 367         (".", for example "ngIRCd-20.1."). If it ends in ".1" (for example
 368         "ngIRCd-20.1.1", same version than before!), the server is running in
 369         debug-mode; and if it ends in ".2", the "network sniffer" is active!
 370         Keep your privacy in mind ...
 371
 372         References:
 373          - RFC 2812, 3.4.3 "Version message"
 374
 375 - WHO
 376         WHO [<mask> ["o"]]
 377         .
 378         Show a list of users who match the <mask>, or all visible users when
 379         the <mask> has been omitted. (Special case: the <mask> "0" is
 380         equivalent to "*")
 381         .
 382         If the flag "o" is given, the server will only return information about
 383         IRC Operators.
 384
 385         References:
 386          - RFC 2812, 3.6.1 "Who query"
 387
 388 - WHOIS
 389         WHOIS [<target>] <mask>[,<mask>[,...]]
 390         .
 391         Query information about users matching the <mask> parameter(s) as seen
 392         by the server <target>; up to 3 <masks> are supported.
 393         .
 394         <target> can be a server name, the nickname of a client connected to a
 395         specific server, or a mask matching a server name in the network. The
 396         server of the current connection is used when <target> is omitted.
 397
 398         References:
 399          - RFC 2812, 3.6.2 "Whois query"
 400
 401 - WHOWAS
 402         WHOWAS <nickname>[,<nickname>[,...]] [<count> [<target>]]
 403         .
 404         Query information about nicknames no longer in use in the network,
 405         either because of nickname changes or disconnects. The history is
 406         searched backwards, returning the most recent entry first. If there
 407         are multiple entries, up to <count> entries will be shown (or all of
 408         them, if no <count> has been given).
 409         .
 410         <target> can be a server name, the nickname of a client connected to a
 411         specific server, or a mask matching a server name in the network. The
 412         server of the current connection is used when <target> is omitted.
 413
 414         References:
 415          - RFC 2812, 3.6.3 "Whowas"
 416
 417
 418 Channel Commands
 419 ~~~~~~~~~~~~~~~~
 420
 421 - INVITE
 422         INVITE <nickname> <channel>
 423         .
 424         Invite <nickname> to join channel <channel>.
 425         .
 426         <channel> does not have to exist, but if it does, only members of the
 427         channel are allowed to invite other users. If the channel mode "+i"
 428         is set, only channel "half-ops" (and above) may invite other clients,
 429         and if channel mode "+V" is set, nobody can invite other users.
 430
 431         References:
 432          - RFC 2812, 3.2.7 "Invite message"
 433
 434 - JOIN
 435         JOIN <channels> [<channel-keys>]
 436         .
 437         Makes the client join the <channels> (comma-separated list), specifying
 438         the passwords, if needed, in the comma-separated <channel-keys> list.
 439         A <channel-key> is only needed, if the <channel> mode "+k" is set.
 440         .
 441         If the channel(s) do not exist, then they will be created.
 442
 443 - KICK
 444         KICK <channel>[,<channel>[,...]] <nickname>[,<nickname>[,...]] [<reason>]
 445         .
 446         Remove users(s) with <nickname>(s) from <channel>(s).
 447         .
 448         There must be either exactly one <channel> parameter and multiple
 449         <nickname> parameters, or as many <channel> parameters as there are
 450         <nickname> parameters. The <reason> is shown to the users being
 451         kicked, and the nickname of the current user is used when <reason>
 452         is omitted.
 453
 454         References:
 455          - RFC 2812, 3.2.8 "Kick command"
 456
 457 - LIST
 458         LIST [<channels> [<server>]]
 459         .
 460         List all visible <channels> (comma-seperated list) on the current
 461         server.
 462         If <server> is given, the command will be forwarded to <server> for
 463         evaluation.
 464
 465 - PART
 466         PART <channels> [<part-message>]
 467         .
 468         Leave <channels> (comma-separated list), optional with a
 469         <part-message>.
 470
 471 - TOPIC
 472         TOPIC <channel> <topic>
 473         .
 474         Set a <topic> for <channel>.
 475         .
 476         Only <channel> operators are able to set a <topic>.
 477
 478
 479 Administrative Commands
 480 ~~~~~~~~~~~~~~~~~~~~~~~
 481
 482 - CONNECT
 483         CONNECT <target server> [<port> [<remote server> [<mypwd> <peerpwd>]]]
 484         .
 485         Instructs the current server, or <remote server> if specified,
 486         to connect to <target server>.
 487         .
 488         To connect <remote server> you need to have remote oper status.
 489         If <port> is omitted, it uses the server port of the configuration.
 490         If <mypwd> and <peerpwd> is given, it uses those passwords instead
 491         of the ones in the configuration.
 492
 493 - DIE
 494         DIE
 495         .
 496         Instructs the server to shut down.
 497
 498 - DISCONNECT
 499         DISCONNECT [<remote server>]
 500         .
 501         Disconnects the current server, or <remote server> if specified.
 502         To disconnect a <remote server> you need to have remote oper status.
 503
 504 - GLINE
 505         GLINE <nick!user@hostmask> <seconds> :<reason>
 506         .
 507         This command provides timed G-Lines (Network-wide bans).
 508         If a client matches a G-Line, it cannot connect to any server on
 509         the IRC network. If you put 0 as <seconds>, it makes the G-Line
 510         permanent.
 511         .
 512         To remove a G-Line, type "GLINE <nick!user@hostmask>".
 513         To list the G-Lines, type "STATS g".
 514
 515 - KILL
 516         KILL <nickname> <reason>
 517         .
 518         Forcibly remove all users with a given <nickname> from the IRC
 519         network and display the given <reason> to them.
 520         .
 521         This command is used internally between servers, too, for example
 522         to disconnect duplicate <nickname>'s after a "net split".
 523
 524         References:
 525          - RFC 2812, 3.7.1 "Kill message"
 526
 527 - KLINE
 528         KLINE <nick!user@hostmask> <seconds> :<reason>
 529         .
 530         This command provides timed K-Lines (Server-local bans).
 531         If a client matches a K-Line, it cannot connect to the issued server.
 532         If you put 0 as <seconds>, it makes the K-Line permanent.
 533         .
 534         To remove a K-Line, type "KLINE <nick!user@hostmask>".
 535         To list the K-Lines, type "STATS k".
 536
 537 - OPER
 538         OPER <user> <password>
 539         .
 540         Authenticates <user> as an IRC operator on the current server/network.
 541
 542 - REHASH
 543         REHASH
 544         .
 545         Causes the server to re-read and re-process its configuration file(s).
 546
 547 - RESTART
 548         RESTART
 549         .
 550         Restart the server.
 551
 552 - WALLOPS
 553         WALLOPS <message>
 554         .
 555         Sends <message> to all users with user mode "+w".
 556
 557
 558 IRC Service Commands
 559 ~~~~~~~~~~~~~~~~~~~~
 560
 561 - SERVICE
 562
 563 - SERVLIST
 564         SERVLIST [<mask> [<type>]]
 565         .
 566         List all IRC services currently registered in the network.
 567         .
 568         The optional <mask> and <type> parameters can be used to limit the
 569         listing to services matching the <mask> and that are of type <type>.
 570         .
 571         Please note that ngIRCd doesn't use any service types at the moment
 572         and therefore all services are of type "0".
 573
 574         References:
 575          - RFC 2812, 3.5.1 "Servlist message"
 576
 577 - SQUERY
 578
 579 - SVSNICK
 580
 581
 582 Server Protocol Commands
 583 ~~~~~~~~~~~~~~~~~~~~~~~~
 584
 585 - CHANINFO
 586         CHANINFO <channel> +<modes> [[<key> <limit>] <topic>]
 587         .
 588         CHANINFO is used by servers to inform each other about a channel:
 589         its modes, channel key, user limits and its topic.
 590         .
 591         See doc/Protocol.txt for more information.
 592
 593 - ERROR
 594         ERROR [<message> [<> [...]]]
 595         .
 596         Return an error message to the server. The first parameter, if given,
 597         will be logged by the server, all further parameters are silently
 598         ignored.
 599         .
 600         This command is silently ignored on non-server and non-service links.
 601
 602 - METADATA
 603         METADATA <target> <key> <value>
 604         .
 605         The METADATA command is used on server-links to update "metadata"
 606         information of clients, like the hostname, the info text ("real name"),
 607         or the user name.
 608         .
 609         See doc/Protocol.txt for more information.
 610
 611 - NJOIN
 612
 613 - SERVER
 614
 615 - SQUIT
 616         SQUIT <server>
 617         .
 618         Disconnects an IRC Server from the network.
 619
 620
 621 Dummy Commands
 622 ~~~~~~~~~~~~~~
 623
 624 - SUMMON
 625         SUMMON <user> [<target> [<channel>]]
 626         .
 627         This command was intended to call people into IRC who are directly
 628         connected to the terminal console of the IRC server -- but is
 629         deprecated today. Therefore ngIRCd doesn't really implement this
 630         command and always returns an error message, regardless of the
 631         parameters given.
 632
 633         References:
 634          - RFC 2812, 4.5 "Summon message"
 635
 636 - USERS
 637         USERS [<target>]
 638         .
 639         This command was intended to list users directly logged in into the
 640         console of the IRC server -- but is deprecated today. Therefore ngIRCd
 641         doesn't really implement this command and always returns an error
 642         message, regardless of the parameters given.
 643
 644         References:
 645          - RFC 2812, 4.6 "Users"
 646
 647 - GET
 648
 649 - POST