# first section is usage
# second section is that config maker will put into config
# third section is full help

module ircd
:%*
:
:This module provides RFC2810...RFC2813 compatible IRC daemon with\
 multi-charset support extension (if it's enabled in config) and with\
 cyclic network scheme possibility (if it's enabled in config).
 
 Server name for the network is taken from %^nick%^ variable on the start.
 
 Available flags for %_network%_ subrecords on clients:
    k  - means this is a KILL record or quarantined server;
    a  - means this is an exemption from KILL record;
    d  - means this is a restricted class;
    o  - means this is an Operator;
    h  - means this is a Local Operator;
    s  - means this is a local service;
    u  - means this is a known server on that network;
    *  - means this is a hub where we have an autoconnect to.
 Flags e, v, f, m, i, q are reserved for future usage.
 The %_network%_ subrecord on client that is a KILL record may contain an\
 optional KILL comment which will be sent to client. Note that KILL comment\
 should not contain any colon ('%^:%^'), otherwise part before first colon\
 will be skipped.
 
 Field "hub" on server record contains mask(s) for servers that server can\
 introduce. Mask "!some.server" means wrong path (L:line analog).

function ircd
:ircd ["-"encoding] [host"/"]<1024-65535>["%%"flags]
:
:Opens listening port for IRC protocol connections. Optional %_encoding%_\
 is starting charset for client connections. Optional %_host%_ is hostname\
 on which port is listening and if omitted then listening is opened on\
 every IPv4 local address. Optional %_flags%_ are chars for mandatory\
 connection chain first links (see technical documentation for more details\
 about connection chain).

function ircd-set-channel-topic
:ircd-set-channel-topic network channel [time who] topic
:
:

set ircd-default-class
:%* <string>
:Default class parameters string.
:This variable defines parameters for connections which are not match to\
 any other private or global client mask. It is a string which consists of\
 five numbers: maximum number of links from this [user@]host on the server,\
 maximum number of links from this [user@]host in this network, maximum\
 number of connections in this default class, ping frequency in seconds,\
 and sendQ for each client.
 Default: "2 2 100 90 1000".

set ircd-serverclass-pingf
:%* <seconds>
:Ping frequency for server links.
:This variable defines as often idle neighbour servers will be pinged to\
 check if they are alive.
 Default: 30.

set ircd-flags-first
:%* <string>
:Raw stream handling server flags.
:This variable defines which flags will be probed to apply to raw stream\
 on server link (i.e. before text parser/splitter to lines). You have to\
 include here any filter that requires raw stream - zip compression for\
 example.
 Default: "Z".

set ircd-flags-post
:%* <string>
:Text stream handling server flags.
:This variable defines which flags from %gPASS%n handshake will be probed to\
 apply to each line of IRC protocol. You have to include here any filter\
 that makes some network-specific protocol conversions to make difference\
 and compatibility with other servers in network.
 Default: "CIPU".

set ircd-description-string
:%* <string>
:Server common description.
:This variable presents definition of the server which will be visible\
 across network. It should contain some geographic information.
 Default: "".

set ircd-admin-info
:%* <string>
:Server administrative info.
:This variable presents details of the institution and/or network which\
 this server belongs to.
 Default: "Not configured.".

set ircd-admin-email
:%* <string>
:Server administration e-mail.
:This variable defines electronic contact to server administration and\
 it is imperative to have it valid so users can find you in case of any\
 troubles.
 Default: "lame@lame.org".

set ircd-hold-period
:%* <seconds>
:Period of keeping nicks on hold due to network splits.
:This variable defines how long nicks will be kept unavailable after some\
 server was disconnected from network. Such unavailability is required to\
 prevent nick collisions after the server reconnect.
 Default: 900.

set ircd-motd-file
:%* /path/to/file
:Path to MOTD file.
:This variable defines where file containing MOTD for the server lies. It\
 can contain full path to the file or path relative to starting config.
 Default: "ircd.motd".

set ircd-max-matches
:%* <number>
:Max number of replies on LIST or NAMES.
:This variable defines how many replies will be sent to requestor on %gLIST%n or\
 %gNAMES%n query. When number of replies exceeds this value, %gERR_TOOMANYMATCHES%n\
 will be sent to the client.
 Default: 500.

set ircd-max-whois
:%* <number>
:Max targets to show on WHOIS.
:This variable defines how many replies can be requested with %gWHOIS%n query. If\
 there are too many matches then %gERR_TOOMANYTARGETS%n will be sent to requestor.
 Default: 3.

set ircd-squit-youngest
:%* <yes|no>
:Send SQUIT to youngest link on duplicate SERVER rather than to announcer.
:This variable defines behavior when duplicate SERVER is introduced and that\
 introduce involves server which does not support cyclic network scheme. If\
 this variable is sent to %^yes%^ then youngest link will be disconnected on\
 such issue. If set to %^no%^ then server that introduces duplicate will be\
 disconnected instead.
 Default: yes.

set ircd-statm-empty-too
:%* <yes|no>
:Show commands never used on stat m reply.
:If this variable is set to %^yes%^ then command that were never used will\
 be shown in %gSTATS m%n reply.
 Default: no.

set ircd-trace-users
:%* <yes|no>
:Want opers see all users in TRACE reply.
:If this variable is set to %^yes%^ then %gTRACE%n reply will include all local\
 users on last iteration if request was made by IRC operator.
 Default: yes.

set ircd-public-topic
:%* <yes|no>
:
:Set to %^yes%^ to grant access to topic outside of channel which have neither\
 mode +n nor +t. Note: topic is still partially accessible with LIST command.
 Default: yes.

set ircd-idle-from-msg
:%* <yes|no>
:Only PRIVMSG can reset idle time.
:If this variable is set to %^yes%^ then idle time is reset only when client\
 sends %gPRIVMSG%n to server. If it is set to %^no%^ then any message except\
 for %gPING%n/%gPONG%n pair will also reset idle time on client.
 Default: no.

set ircd-default-invisible
:%* <yes|no>
:Users will be automatically attributed with user mode "i".
:If this variable is set to %^yes%^ then local user after succesful registering\
 will be attributed with user mode %c+i%n.
 Default: yes.

set ircd-wallop-only-opers
:%* <yes|no>
:Only OPERs can get WALLOP messages.
:If set to %^yes%^ then non-opers will not get WALLOP messages despite of\
 "w" user mode.
 Default: no.

set ircd-no-spare-invites
:%* <yes|no>
:Don't allow setting +I for channels without +i.
:If this variable is set to %^yes%^ then any %gMODE%n %c<channel>%n %g+I%n\
 request for channel without %c+i%n will be ignored.
 Default: no.

set ircd-strict-modecmd
:%* <yes|no>
:Users should always use '+' or '-' for MODE changing.
:If set to %^yes%^ then message such as %gMODE%n %c<channel>%n %gt%n will result\
 in usage error. If set to %^no%^ then such message will be treaten as %gMODE%n\
 %c<channel>%n %g+t%n instead.
 Default: yes.

set ircd-ignore-mkey-arg
:%* <yes|no>
:Don't check argument of MODE #chan -k with key for #chan.
:If this variable is set to %^no%^ then %gMODE%n %c<channel>%n %g-k xxx%n on a\
 channel with key %cyyy%n will result in %gERR_KEYSET%n. If set to %^yes%^ then\
 such request will be considered valid.
 Default: no.

set ircd-max-bans
:%* <number>
:Max targets in each list (bans, exempts, invites).
:This variable defines how big list of bans each channel can hold. Each attempt\
 over this limit will result in %gERR_BANLISTFULL%n. The same variable defines\
 the same behavior for exempts list and invites list, separately.
 Default: 30.

set ircd-max-channels
:%* <number>
:Max channels an user can join.
:This variable defines how many channels user allowed to join. When this limit\
 is reached, user attempt to join will be refused.
 Default: 20.

ss-ircd +hub
:+hub server mask
:
:Allows %_server%_ to introduce other servers to us. The %_mask%_ is simple\
 pattern to filter introduced servers: if the %_server%_ introduces some\
 server that matches none of added masks then it will be unlinked for such\
 behavior.

ss-ircd -hub
:-hub server mask
:
:Removes all matched masks from %_server%_ which were previously added using\
 command %c+hub%n.

ss-ircd class
:class name [ul/loc uh/glob u/class pingfreq sendq]
:
:Shows or changes parameters on class %_name%_. If %_parameters%_ argument is\
 not given then shows existing parameters. If %_parameters%_ argument is\
 given then command replaces any existing parameters. See also %yhelp set\
 ircd-default-class%n.

flood-type ircd-errors
:
:
:If set then each corrected error on server link will be checked against this\
 and if too many errors happened then link will be SQUITed in that reason. Note\
 that you should keep this value the same on all servers in your network.

# ircd help. must be in category "=ircd"
=ircd admin
:ADMIN [<target>]
:ADMIN    - query administrative information from server
:With no arguments, ADMIN shows the information that was set by the\
 administrator of the server. This information can take any form that\
 will fit in three lines of text but is usually a list of contacts\
 for the persons that run the server.
 
 With a second argument, the administrative information for the\
 specified server is displayed.

=ircd away
:AWAY [<text>]
:AWAY     - set or remove "away" status
:Without an argument, it will set you back. With an argument,\
 it will set you as AWAY with the specified message.

=ircd charset
:CHARSET [<charset>]
:CHARSET  - query or change character set in use
:Without an argument, it will show you character set currently in use.\
 With an argument, it will attempt to change it to a specified one.

=ircd connect
:CONNECT <target server> <port> [<remote server>]
:CONNECT  - request server to connect to another server
:When <remote server> is specified, CONNECT asks <remote server> to\
 connect to <target server>.
 
 When <remote server> is not specified, CONNECT tries to connect\
 your server to <target server>.
 
 <target server> must be configured to connect with <remote server> or\
 your server in order to success.

=ircd die
:DIE
:DIE      - request server to shutdown
:Terminates the IRC server.

=ircd help
:HELP [<command>]
:HELP     - request a help on protocol command
:If <command> is not specified then shows you list of commands available\
 to you. If <command> is specified then shows you brief description of\
 arguments and purpose of the command.

=ircd info
:INFO [<target>]
:INFO     - query build information details from server
:INFO displays the copyright, authors and contributors list for ircd.\
 If an argument is supplied, the information for the server specified will\
 be returned.

=ircd invite
:INVITE <nickname> <channel>
:INVITE   - invite someone to enter a channel
:INVITE sends a notice to the user that you have asked him/her to come\
 to the specified channel. If the channel has mode +i, this will allow\
 the user to bypass this mode.

=ircd ison
:ISON <nickname>[ ...]
:ISON     - query presence of users in network
:ISON will return a list of users who are present on the network from\
 the list specified.

=ircd join
:JOIN <channel> [,<channel> ...] [<key> [,<key> ... ]] | 0
:JOIN     - enter some channel
:The JOIN command allows you to enter a public chat area known as\
 a channel. Network wide channel name is started with a '#', a local\
 server channel name is started with an '&', safe channel name is\
 started with an '!', modeless channel name is started with a '+'.\
 More than one channel may be specified, separated with commas (no spaces).
 
 If the channel has a key set, the 2nd argument must be given to enter.\
 This allows channels to be password protected.

=ircd kick
:KICK <channel>[,<channel> ...] <user>[,<user> ...] [<reason>]
:KICK     - force someone out of some channel
:The KICK command will remove the specified user from the specified\
 channel, using the optional kick message. You must be a channel operator\
 to use this command.

=ircd kill
:KILL <nickname> <reason>
:KILL     - force someone out of network
:Disconnects user <nick> from the IRC server he/she is connected to\
 with specified <reason>.

=ircd links
:LINKS [[<remote server> ]<server mask>]
:LINKS    - query servers list a server connected to
:LINKS shows a list of all servers linked to the host server.
 
 With a mask parameter, LINKS will just show servers matching that\
 parameter. With the <remote server> parameter, LINKS will request\
 the LINKS data from the remote server, matching the mask given.

=ircd list
:LIST [<channel>[,<channel> ...] [<target>]]
:LIST     - query list of channels currently formed in network
:Without any arguments, LIST will give an entire list of all channels\
 which are not set as secret (+s). The list will be in the form:
 
 <channel> <amount of users> :[topic]
 
 If an argument supplied is a channel name, LIST will give just\
 the statistics for the given channel.
 
 If <target> argument is also supplied and is a server, the request\
 will be forwarded to that server.

=ircd lusers
:LUSERS [<mask>[ <target>]]
:LUSERS   - query summary of servers and users
:LUSERS will display client count statistics. If <target> is specified\
 and is a server, it will request the information from that server.\
 If <mask> parameter is specified, only servers matched that mask will\
 be included in calculation.

=ircd mode
:MODE <target> [modes...]
:MODE     - query or change modes on some channel or yourself
:MODE with a single parameter will return current mode. If <target> is\
 yourself, it will return your user mode. If <target> is a channel, it\
 will return you that channel mode. If <modes> specified and is either\
 'b', 'e', 'I' or similar mode letter and you are permitted to get the\
 channel modes, it will show you list of corresponding masks set on the\
 channel. Otherwise if you are permitted to make changes on target and\
 <modes> either starts from '+' to set mode, or '-' to unset mode, it\
 will attempt to apply the change to the target. Modes supported are:
 
  User modes:
 
 i  - is 'invisible' (not shown in /who or /whois outside of channel).
 o  - is an IRC Operator.
 O  - is a Local IRC Operator (with reduced privilege).
 r  - has a restricted connection.
 w  - can see oper and server wallops.
 z  - is connected via SSL (cannot be set or unset).
 
  Channel modes:
 
 O  - give "channel creator" status (for "safe channels" only).
 o  - give/take channel operator privilege
 v  - give/take the voice privilege;
 
 a  - toggle the anonymous channel flag;
 i  - toggle the invite-only channel flag;
 m  - toggle the moderated channel flag (only opped/voiced users may talk in channel);
 n  - toggle the "no external messages" flag (only channel members may talk in channel);
 q  - toggle the quiet channel flag (no one may talk);
 p  - toggle the private channel flag;
 s  - toggle the secret channel flag (channel will not be shown in /whois and /list);
 r  - toggle the server reop channel flag;
 t  - toggle the topic settable by channel operator only flag;
 
 k  - set/remove the channel key (password), parameter - password;
 l  - set/remove the user limit to channel, parameter - user limit;
 
 b  - set/remove ban mask to keep users out, parameter - nick!ident@host mask;
 e  - set/remove an exception mask to override a ban mask, parameter - nick!ident@host mask;
 I  - set/remove an invitation mask to automatically override the invite-only flag, parameter - nick!ident@host mask;

=ircd motd
:MOTD [<target>]
:MOTD     - query contents of MOTD file
:MOTD will display the message of the day. If an argument is supplied,\
 the server specified will be queried for it.

=ircd names
:NAMES [<channel>[,<channel> ...] [<target>]]
:NAMES    - query users which are currently present on channel
:With no channel argument, NAMES shows the names (nicks) of all clients\
 logged in to the network that do not have +i flag.
 
 With the <channel> argument, it displays the nicks on that channel, also\
 respecting the +i flag of each client. If the channel specified is a\
 channel that the issuing client is currently in, all nicks are listed.
 
 If <target> argument is also supplied and is a server, the request\
 will be forwarded to that server.

=ircd nick
:NICK <new nick>
:NICK     - change nickname used
:NICK will change nickname of client issuing the command, in case if\
 such change is possible.

=ircd notice
:NOTICE <msgtarget> <text to be sent>
:NOTICE   - send a message to user or to channel
:NOTICE will send a notice message to the user or channel specified.
 
 The nick can be extended to fit into the following syntax:
 
 username@servername
 
 This syntax is used to securely send a notice to a service or a bot.

=ircd oper
:OPER <name> <password>
:OPER     - get operator privileges on your server
:A normal user uses the OPER command to obtain operator privileges.\
 The combination of <name> and <password> are REQUIRED to gain\
 Operator privileges.

=ircd part
:PART <channel>[,<channel> ...] [<Part Message>]
:PART     - leave some channel
:It will exit the client from the specified channel. More than one channel\
 may be specified, separated with commas (no spaces).
 
 An optional part message may be given to be displayed to the channel.

=ircd ping
:PING <server1> [<server2>]
:PING     - request a reply from a server
:PING will request a PONG. If only <server1> is provided then the request\
 will be sent to <server1>. If <server2> is also provided then the request\
 will be sent to <server2>, and <server1> will be the target for PONG\
 reply. If user or operator issues this command, the PONG target will\
 always be nick that issued the PING.

=ircd pong
:PONG <source> [<target>]
:PONG     - reply to a PING request from server
:PONG is an reply to the PING. <source> is a client who sends PONG. If\
 <target> is also provided, PONG will be forwarded to it. If user or\
 operator issues this command, the <source> is always assumed to be\
 nick that issued the PONG.

=ircd privmsg
:PRIVMSG <msgtarget> <text to be sent>
:PRIVMSG  - send a message to user or to channel
:PRIVMSG will send a standard message to the user or channel specified.
 
 The nick can be extended to fit into the following syntax:
 
 username@servername
 
 This syntax is used to securely send a notice to a service or a bot.

=ircd quit
:QUIT [<Quit Message>]
:QUIT     - disconnect from server
:QUIT sends a message to the IRC server letting it know you would\
 like to disconnect. Optional quit message will be displayed to the\
 users in the channels you were in when you are disconnected.

=ircd rehash
:REHASH
:REHASH   - request server to reload configuration
:Receiving this request, server will reload all configuration.

=ircd restart
:RESTART
:RESTART  - request server to restart
:Receiving this request, server will completely shutdown, and then start\
 again with the same parameters.

=ircd servlist
:SERVLIST [<mask>[ <type>]]
:SERVLIST - query a list of services present in the network
:SERVLIST command lists services currently connected to the network and\
 visible to the user issuing the command. The optional parameters may be\
 used to restrict the result of the query.

=ircd stats
:STATS [<letter>[ <target>]]
:STATS    - query miscellaneous statistics from server
:Queries server <target> (or your own server if no <target> parameter\
 is given) for info corresponding to <letter>.
 
 LETTER
 ------ (^ = Can be configured to be oper only.)
 ^ c - Shows info on servers configured to connect
 ^ h - Shows configured hub masks
   l - Shows a list of the server's connections
   m - Shows commands supported and their usage count
   o - Shows a list of configured privileged users (operators)
   u - Shows server uptime
 
 Other STATS infos may also be configured by server administartor.

=ircd squery
:SQUERY <servicename> <text to be sent>
:SQUERY   - send a message to a service
:SQUERY will send a message to a service specified.
 
 The <servicename> can be extended to fit into the following syntax:
 
 servicename@servername
 
 This syntax is used to securely send the message.

=ircd squit
:SQUIT <server> <comment>
:SQUIT    - request a disconnection from a server
:SQUIT requests <server> to be disconnected from the server it is seen\
 from. Optional <comment> will be logged to &SERVERS channel.

=ircd summon
:SUMMON <user> [<server> [<channel>]]
:SUMMON   - request a local user to enter IRC network
:SUMMON command can be used to give users who are on a host running an\
 IRC server a message asking them to please join IRC. This message is\
 only sent if the target server (a) has SUMMON enabled, (b) the user is\
 logged in and (c) the server process can write to the user's tty.
 
 If no <server> parameter is given it tries to summon <user> from the\
 server the client is connected to is assumed as the target.

=ircd time
:TIME [<target>]
:TIME     - query current time from server
:
 If an argument is supplied, the information for the server specified will\
 be returned.

=ircd topic
:TOPIC <channel> [<topic>]
:TOPIC    - query or change topic on a channel
:With only a <channel> argument, TOPIC shows the current topic of the\
 specified channel.
 
 With a second argument, it changes the topic on that channel to provided\
 topic. If the channel is +t, only channel operators may change the topic.

=ircd trace
:TRACE [<target>]
:TRACE    - query connection path to the target
:With no argument, TRACE gives a list of all clients connected to the\
 local server, both users and operators.
 
 With one argument which is a server, TRACE displays the path to the\
 specified server, and all servers, opers and -i users on that server.
 
 Non-operators can only see themselves, operators and servers.
 
 With one argument which is a client, TRACE displays the path to that\
 client, and that client's information.

=ircd userhost
:USERHOST <nickname>[ ...]
:USERHOST - query connection information for users
:USERHOST displays the username, hostname, operator status, and presence\
 of valid ident of the specified nickname.
 
 If you use USERHOST on yourself, your IP will be shown in place of hostname.

=ircd users
:USERS [<target>]
:USERS    - query local users logged in on server host
:USERS command returns a list of users logged into the server host in\
 a format similar to the UNIX commands who(1), rusers(1) and finger(1).

=ircd version
:VERSION [<target>]
:VERSION  - query version string and flags from server
:VERSION will display the server version and compilation flags. If an\
 argument is supplied, the information for the server specified will\
 be returned, otherwise information for the server you are connected\
 to will be returned.

=ircd who
:WHO [<mask>[ "o"]]
:WHO      - query info about user status in newtork or channel
:

=ircd whois
:WHOIS [<target>] <mask>[,<mask>...]
:WHOIS    - query connection infrormation for a client
:WHOIS will display detailed user information for the specified nick.\
 If the first parameter is specified, WHOIS will send the request to\
 the specified server.

=ircd whowas
:WHOWAS <nickname>[,<nickname>...] [<count>[ <target>]]
:WHOWAS   - query information about gone client from server history database
:WHOWAS will show you the last known host and whois information for the\
 specified nick. Depending on the number of times they have connected to\
 the network, there may be more than one listing for a specific user.\
 That number may be limited by specified <count>. If <target> is also\
 supplied and is a server name, the request will be forwarded to that\
 server.
