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 [<server>]
 220         .
 221         Show the version, birth & online time of the current IRC server.
 222         If <server> has been given, it shows the INFO of the specific <server>.
 223
 224 - ISON
 225         ISON <nicknames>
 226         .
 227         Queries the server to see if the clients in the space-separated list
 228         <nicknames> are currently on the network.
 229         .
 230         The server returns only the <nicknames> that are on the network in a
 231         space-separated list. If none of the clients are on the network the
 232         server returns an empty list.
 233
 234 - LINKS
 235         LINKS [<remote server> [<server mask>]]
 236         .
 237         Lists all server links matching <server mask>, if given,
 238         on <remote server>, or the current server if omitted.
 239
 240 - LUSERS
 241         LUSERS [<mask> [<server>]]
 242         .
 243         Return statistics about the size of the network. If called with no
 244         arguments, the statistics will reflect the entire network.
 245         .
 246         If <mask> is given, it will return only statistics reflecting the
 247         masked subset of the network.
 248         If <server> is given, the command will be forwarded to <server>
 249         for evaluation.
 250
 251 - MOTD
 252         MOTD [<server>]
 253         .
 254         Show "Message Of The Day" of the current server or specified <server>.
 255
 256 - NAMES
 257         NAMES [<channels> [<server>]]
 258         .
 259         Returns a list of who is on the comma-separated list of <channels>,
 260         by channel name.
 261         .
 262         If <channels> is omitted, all users are shown, grouped by channel name
 263         with all users who are not on a channel being shown as part of channel
 264         "*".
 265         If <server> is specified, the command is sent to <server> for
 266         evaluation.
 267
 268 - STATS
 269         STATS <flag> [<server>]
 270         .
 271         Returns statistics about the current server, or of a specified <server>.
 272         .
 273         STATS flags:
 274         .
 275         g = G-Lines (Network-wide bans)
 276         k = K-Lines (Server-local bans)
 277         l = Link status (Parent server and own link)
 278         m = IRC command status (usage count)
 279         u = Server uptime
 280
 281 - TIME
 282         TIME [<server>]
 283         .
 284         Show the local time of the current server, or of a specified <server>.
 285
 286 - TRACE
 287         TRACE [<server>]
 288         .
 289         Trace a path across the IRC network of the current server, or if given
 290         of a specific <server>, in a similar method to traceroute.
 291
 292 - USERHOST
 293         USERHOST <nicknames>
 294         .
 295         Show the user-host of <nicknames> (seperated by space).
 296         "-" means <nick> is away,
 297         "+" means <nick> is available,
 298         "*" indicates your connection.
 299
 300 - VERSION
 301         VERSION [<server>]
 302         .
 303         Show the ngIRCd version of the current server, or specified <server>.
 304
 305 - WHO
 306         WHO [<target> ["o"]]
 307         .
 308         Returns a list of users who match <target> (nick, hostmask or channel).
 309         .
 310         If the flag "o" is given, the server will only return information about
 311         IRC Operators.
 312
 313 - WHOIS
 314         WHOIS [<server>] <nicknames>
 315         .
 316         Returns information about the comma-separated list of <nicknames>.
 317         .
 318         If <server> is given, the command is forwarded to it for processing.
 319
 320 - WHOWAS
 321         WHOWAS <nickname> [<count> [<server>]]
 322         .
 323         Used to return information about <nicknames> that are no longer in use
 324         (due to client disconnection, or nickname changes).
 325         .
 326         If given, the server will return information from the last <count> times
 327         the nickname has been used.
 328         If <server> is given, the command is forwarded to it for processing.
 329
 330
 331 Channel Commands
 332 ~~~~~~~~~~~~~~~~
 333
 334 - INVITE
 335         INVITE <nick> <channel>
 336         .
 337         Invites <nick> to <channel>.
 338         <channel> does not have to exist, but if it does, only members of the
 339         channel are allowed to invite other clients.
 340         .
 341         If the <channel> mode "+i" is set, only <channel> operators may invite
 342         other clients.
 343
 344 - JOIN
 345         JOIN <channels> [<channel-keys>]
 346         .
 347         Makes the client join the <channels> (comma-separated list), specifying
 348         the passwords, if needed, in the comma-separated <channel-keys> list.
 349         A <channel-key> is only needed, if the <channel> mode "+k" is set.
 350         .
 351         If the channel(s) do not exist, then they will be created.
 352
 353 - KICK
 354         KICK <channel> <nick> [<kick-message>]
 355         .
 356         Remove <nick> from <channel>, optional with a <kick-message>.
 357         .
 358         Only <channel> operators are able to KICK.
 359
 360 - LIST
 361         LIST [<channels> [<server>]]
 362         .
 363         List all visible <channels> (comma-seperated list) on the current
 364         server.
 365         If <server> is given, the command will be forwarded to <server> for
 366         evaluation.
 367
 368 - PART
 369         PART <channels> [<part-message>]
 370         .
 371         Leave <channels> (comma-separated list), optional with a
 372         <part-message>.
 373
 374 - TOPIC
 375         TOPIC <channel> <topic>
 376         .
 377         Set a <topic> for <channel>.
 378         .
 379         Only <channel> operators are able to set a <topic>.
 380
 381
 382 Administrative Commands
 383 ~~~~~~~~~~~~~~~~~~~~~~~
 384
 385 - CONNECT
 386         CONNECT <target server> [<port> [<remote server> [<mypwd> <peerpwd>]]]
 387         .
 388         Instructs the current server, or <remote server> if specified,
 389         to connect to <target server>.
 390         .
 391         To connect <remote server> you need to have remote oper status.
 392         If <port> is omitted, it uses the server port of the configuration.
 393         If <mypwd> and <peerpwd> is given, it uses those passwords instead
 394         of the ones in the configuration.
 395
 396 - DIE
 397         DIE
 398         .
 399         Instructs the server to shut down.
 400
 401 - DISCONNECT
 402         DISCONNECT [<remote server>]
 403         .
 404         Disconnects the current server, or <remote server> if specified.
 405         To disconnect a <remote server> you need to have remote oper status.
 406
 407 - GLINE
 408         GLINE <nick!user@hostmask> <seconds> :<reason>
 409         .
 410         This command provides timed G-Lines (Network-wide bans).
 411         If a client matches a G-Line, it cannot connect to any server on
 412         the IRC network. If you put 0 as <seconds>, it makes the G-Line
 413         permanent.
 414         .
 415         To remove a G-Line, type "GLINE <nick!user@hostmask>".
 416         To list the G-Lines, type "STATS g".
 417
 418 - KILL
 419         KILL <nick> <reason>
 420         .
 421         Forcibly removes <nick> from the IRC network with a <reason>.
 422
 423 - KLINE
 424         KLINE <nick!user@hostmask> <seconds> :<reason>
 425         .
 426         This command provides timed K-Lines (Server-local bans).
 427         If a client matches a K-Line, it cannot connect to the issued server.
 428         If you put 0 as <seconds>, it makes the K-Line permanent.
 429         .
 430         To remove a K-Line, type "KLINE <nick!user@hostmask>".
 431         To list the K-Lines, type "STATS k".
 432
 433 - OPER
 434         OPER <user> <password>
 435         .
 436         Authenticates <user> as an IRC operator on the current server/network.
 437
 438 - REHASH
 439         REHASH
 440         .
 441         Causes the server to re-read and re-process its configuration file(s).
 442
 443 - RESTART
 444         RESTART
 445         .
 446         Restart the server.
 447
 448 - WALLOPS
 449         WALLOPS <message>
 450         .
 451         Sends <message> to all users with user mode "+w".
 452
 453
 454 IRC Service Commands
 455 ~~~~~~~~~~~~~~~~~~~~
 456
 457 - SERVICE
 458
 459 - SERVLIST
 460
 461 - SQUERY
 462
 463 - SVSNICK
 464
 465
 466 Server Protocol Commands
 467 ~~~~~~~~~~~~~~~~~~~~~~~~
 468
 469 - CHANINFO
 470         CHANINFO <channel> +<modes> [[<key> <limit>] <topic>]
 471         .
 472         CHANINFO is used by servers to inform each other about a channel:
 473         its modes, channel key, user limits and its topic.
 474         .
 475         See doc/Protocol.txt for more information.
 476
 477 - ERROR
 478         ERROR [<message> [<> [...]]]
 479         .
 480         Return an error message to the server. The first parameter, if given,
 481         will be logged by the server, all further parameters are silently
 482         ignored.
 483         .
 484         This command is silently ignored on non-server and non-service links.
 485
 486 - METADATA
 487         METADATA <target> <key> <value>
 488         .
 489         The METADATA command is used on server-links to update "metadata"
 490         information of clients, like the hostname, the info text ("real name"),
 491         or the user name.
 492         .
 493         See doc/Protocol.txt for more information.
 494
 495 - NJOIN
 496
 497 - SERVER
 498
 499 - SQUIT
 500         SQUIT <server>
 501         .
 502         Disconnects an IRC Server from the network.
 503
 504
 505 Dummy Commands
 506 ~~~~~~~~~~~~~~
 507
 508 - SUMMON
 509
 510 - USERS
 511
 512 - GET
 513
 514 - POST