Configuration
From Inspire IRCd (InspIRCd)
Configuration of InspIRCd is done by editing the configuration text file, usually called inspircd.conf. The inspircd.conf file is formatted like a html document, which for most people is somewhat different to what they are used to. The format of an instruction within the configuration file looks like the following:
<tagname variable="value">
There may be one or more variables in the tag, each of which must have exactly one value. A variable must be followed immediately by an equals sign and then its value in quotes, with no spaces between the two, as shown in this example. The tagname must contain only alphabetical characters.
NOTE: In 1.1, you may place a linefeed within a value:
<tagname variable="value first part second part of value">
Note however that most settings do not allow linefeeds, and the ircd will error if you try and use a linefeed in a field which does not want it.
You do not require closing tags as in XML (</tagname>).
For an example of this, and crossreferences to this page, please see the Annotated Configuration section.
The configuration options in the current version of inspircd are as follows:
<server>
<server name="test.chatspike.net" description="ChatSpike InspIRCd test server" network="ChatSpike">
This tag indicates the servername of your server, a description for your server, and your network name. The network name will be given to clients when they connect, and is used by clients such as mIRC to determine which 'perform' should be run. You may only have one <server> tag.
<admin>
<admin name="Mr Person" nick="Person" email="mr@person.org">
These are the administrative details of your server, shown when the /ADMIN command is typed by a user. You may only have one <admin> tag.
<bind>
<bind address="" port="6667">
The <bind> tag indicates the ports which your server should listen on. If you want the server to listen on all available ip addresses, you must leave the address field blank as shown above. If you want inspircd to listen on only one ip address, specify the ip address in the address field. You must use IP addresses and not hostnames. You may have as many of these as you wish.
<bind address="" port="7000" type="servers">
This format of <bind> tag specifies a port which will listen for servers. As with the other format of bind tag above you may specify an ip address.
You may also specify port ranges to bind to, for example:
<bind address="1.2.3.4" port="7000-7005">
Will bind to all ports in the range 7000 to 7005.
You may also seperate individual ports with commas or use a combination of the two:
<bind address="1.2.3.4" port="7001,7005,7006-7010">
The <bind> tag can make use of encrypted and compressed communication. using the following examples:
<bind address="" port="6667" ssl="openssl">
<bind address="" port="6667" ssl="gnutls">
<bind address="" port="6667" transport="zip">
IPV6
If you have built InspIRCd to support IPV6 connections, you may bind either of an IPV4 or an IPV6 address here by specifying it as the address. Note that if your server is built as an IPV6 server then if you leave the address blank, all IPV6 addresses on your server will be bound, but no IPV4 addresses will be bound. If you do this you must then manually specify any IPV4 addresses you also want to bind to.
<power>
<power diepass="XXXXX" restartpass="XXXXX" pause="5">
This tag specifies the passwords needed for /DIE and /RESTART. The pause variable indicates how many seconds to wait after the 'server is shutting down' notice to wait before actually terminating the server. You may have only one of these tags, and this tag is non-optional. By default in some configurations (including Win32) this is commented by default as leaving a default value is a security risk. Please ensure you set this tag appropriately.
<link>
<link name="other.server.org" ipaddr="foomatic.bazqux.org" port="7000" sendpass="XXX" recvpass="XXX" autoconnect="120" hidden="no" failover="other2.server.org" transport="transporttype" bind="1.2.3.4">
This tag specifies a server which your server may attempt to link to. To initiate the link you must currently use /CONNECT. Upon connecting, your server will send the password specified in sendpass, and expect the password in recvpass in return. It will connect outwards on the port you specify which is a TCP port number. The name of the server does not have to match the hostname you specify, but it must match the link tag in the opposite server's configuration. You may have as many of these as you wish.
The optional autoconnect value, if set, causes the server to automatically try and connect this connection (outbound), retrying every X seconds (using the interval you provide as the parameter). As the internal timeout for a connection is 30 seconds, you should not set this below 31 seconds.
The hidden value is optional, and if set to yes, true or 1 will cause the server's IP address or hostname to be hidden from all opers. This hiding will conceal the IP address in /STATS c, and also when connecting the server, unless the connection fails due to a bad password or invalid server name (which therefore does not match the <link> block). To clarify: with this option set, only the server name (e.g. in the example above, 'other.server.org' will ever be shown to opers, and not the hostname, 'foomatic.bazqux.org'.
The values failover, transport and bind are all optional, and if defined are used for the following:
- bind Will bind any outgoing connections to the given IP address. This is mainly of use to multi-homed servers.
- transport Will use a specified module as the transport layer protocol. Valid entries in this field are gnutls, openssl or zip, for m_ssl_gnutls, m_ssl_openssl and m_ziplinks respectively.
- failover Indicates another server name to try if this one should fail to connect. See the documentation on Linking To Other Servers for more information.
<uline>
<uline server="services.beastie.com"> <uline server="stats.beastie.com" silent="yes">
This tag indicates that one or more servers in your network are U lined. In IRC terms, U-lining a server means that the server has extra permissions, usually those associated with network service bots. For a more detailed description of u-lined servers historically and how this related to inspircd, please click the link above. You may have zero or more of these tags.
'Silent' is an optional parameter which, when set to yes, supresses snomasks +CQ for that server.
 | Warning: Unlike other ircds, u:lining a server allows ALL users on that server to operoverride modes. This should only be used for services and protected oper servers! |
<connect>
<connect allow="*" timeout="60" flood="10" pingfreq="120" threshold="5" sendq="131074" recvq="4096" globalmax="3" localmax="3" port="6660">
These tags indicate that you wish to allow or deny clients from connecting to your irc server. The default, if none of these are defined, is to deny access to everyone. Use the allow variable to allow an ip mask or hostname, or replace it with a deny variable to deny access to an ip mask or hostname. You may also place an optional password value onto an allow tag, to indicate the users should be allowed access but only if they specify the correct server password when connecting. The timeout variable indicates how long the server will wait for the user to register when they connect. If there is no registration within timeout seconds, the connection is dropped, which stops malicious users holding open connections to your server which they do not intend to use. This is seperate from PING checks. The flood variable indicates how many lines may build up in the users sendq before they are disconnected for flooding. There are four ways the flood checking works. You can be disconnected for either:
- Sending more than "flood" lines in one burst, which causes the ircd to drop you immediately,
- Sending more than "flood" lines per "threshold" seconds, which causes the ircd to drop you should you reach "flood" amount of lines.
- Sending more than "recvq" bytes to your buffer at once before the ircd can process the data.
- Attempting to receive more than "sendq" bytes at once from the ircd.
You may optionally include the pingfreq variable as shown above, which indicates how often connections to this group are pinged to check their state. If you do not include this variable, the default of 120 seconds is used.
The optional port value determines which port the connect tag is handling. If left out the connect tag covers all bound ports else only incoming connections on the specified port will match.
- The localmax and globalmax values can be used to enforce local and global session limits on connections. The session limits are counted against all users, but applied only to users within the class. For example, if you had a class 'A' which has a session limit of 3, and a class 'B' which has a session limit of 5, and somehow, two users managed to get into class B which also match class A, there is only one connection left for this IP now in A, but if they can connect again to B, there are three. If these values are omitted, the default of 3 (for both values) is used.
Please note that connect tags are read from top to bottom, the earier tags having precedence over the later ones, so if you deny a wide mask first, this takes precedence over a later tag which may allow the users.
<class>
<class name="Shutdown" commands="DIE RESTART REHASH">
These tags define classes. A class is a named group of one or more commands which may be used to build an oper type. The commands you place in these classes are arbitary, you are not forced to place for example all your services commands together, or group kline with kill, in short, you can create any grouping you wish. You may have as many of these tags as you want.
As of version 1.0 beta 6, if you put a command called '*' (without the quotes) into a class, then the class covers ALL possible commands. USE WITH CARE! For example:
<class name="Everything" commands="*">
<type>
<type name="GlobalOp" classes="OperChat BanControl HostCloak Modular" host="globalop.chatspike.net">
These tags define oper types. An oper type is a named group of one or more classes. When this type of oper successfully gains their permissions, they will gain the hostname specified by the host variable (if defined -- if this field is not defined, the host will be unchanged on oper-up), and will have access to all the commands given in all of their classes. You may have as many of these tags as you want.
Type names can not include a space. If you wish for an type name to display with a space use a _ in the configuration.
<type name="Global_Op" classes="OperChat BanControl HostCloak Modular" host="globalop.chatspike.net">
<oper>
<oper name="helper" password="helper" host="*@*" type="Helper">
These tags define actual opers. Each oper may have only one oper type defined by the type variable. You may enter the same tag twice with different hosts, to make an oper with more than one hostname, or, you may seperate multiple hostnames with spaces, for example:
<oper name="oper" password="iam1337!" host="*@secret.place.com *@home.com" type="ReallyALamer">
The opers password is plaintext, unless you load either the m_md5 module or the m_sha256 module along with m_oper_hash.
<oper name="helper" hash="md5" password="fde5d67bfb6dc4b598291cc2ce35ee4a" host="*@*" type="Helper"> or <oper name="helper" hash="sha256" password="e81d3b0e9d82feaaf5f6e55bdff24731d7eee08632ffa63801e6397290c5d20a" host="*@*" type="Helper">
To generate an encrypted password use mkpasswd
Please note that type IS case sensitive, if you fail to correctly set this, your oper command WILL fail.
<files>
<files motd="/path/to/motd" rules="/path/to/rules">
This tag, which you may have only one of in your config file, specifies the pathname to the message of the day file (which is just a plain text file) and to the rules file displayed when /RULES is typed. The path may be specified relative to the configuration directory, or it may be a full pathname from the root of the filesystem.
<module>
<module name="m_silence.so">
This tag specifies that you wish to load a module. There may be as many of these tags as you wish, and all modules will be looked for in the modules directory you specified when running ./configure.
<options>
<options prefixquit="Quit: " loglevel="debug" netbuffersize="10240" maxwho="32" noservices="no" allowhalfop="yes" moduledir="/path/to/modules" somaxconn="128" userstats="oclgk" customversion="" maxtargets="20" hidesplits="no" hidewhois="" flatlinks="no" hideulines="no" nouserdns="no" syntaxhints="no" cyclehosts="yes" ircumsgprefix="no" announcets="yes" hostintopic="yes" announceinvites="yes" quietbursts="no" hidekills="no" exemptchanops="" morronbanner="">
This tag specifies a group of miscellaneous options. It contains a great many options, which are documented in sub-sections below:
prefixquit
- The prefixquit value is a value which is placed before every quit message. It has multiple uses, the primary one being to prevent spoofing of kill messages, but if you so desire you could advertise your network here. Not much point, they are already ON your network but heh, everyone to their own.
loglevel
- The loglevel tag specifies the logging level. The usual setting is default. Only use verbose or debug if you are debugging a module. verbose and debug can disclose sensitive information and also generate very huge logs, and should never be used on a production network. The loglevel sparse and none which are below default log less details to the log, which you might find useful if you are low on disk space or quota.
netbuffersize
- The netbuffersize variable defines the size of the buffer which receives data from clients. This is in complement to the per-connect-group flood limits. If you for example set this to 10k (10240) then if a user sends more than 10k at once, and the server receives more than 10k of data in one recv() call, the user will be disconnected from the server for flooding. Increasing the netbuffersize increases performance, but takes more memory.
maxwho
- The maxwho variable indicates the maximum number of replies that WHO may generate. On most irc networks with over 1000 users, doing a /WHO 0 or /WHO * (depending upon the ircd type) will disconnect the user and consume lots of server resources. This limits the users ability to flood themselves off.
noservices
- The noservices variable is used on networks which do not have services and will never have services. If you set this variable to 'yes', the first user into every channel is transparently given +q, if the m_chanprotect module is loaded, in the same way the first user into a channel is transparently given +o. This means that founders exist to give out +a etc, when the correct modules are loaded, without needing services to grant the initial +q. Please note that in this situation there may only ever be one channel founder, and when the channel empties and its channel record is destroyed, record of who the founder is is lost as well. This is suited well for networks whose policies do not account for channel or nickname ownership. If you set this variable to 'no', the ircd will operate in the same manner as unrealircd or bahamut, only giving +q when a server sends an SAMODE for it.
qaprefixes
- This option when set to on, provides users with the modes +q or +a the prefixes ~ or & used in unreal. If off, the prefixes will not be shown. This is only useful on networks running the m_chanprotect module.
deprotectself
- When this options is on, users with the +q or +a have the option to remove the mode from themselves. The default setting is to not enable this feature as it allows even the founder to take away their founder status without using services.
somaxconn
- The optional somaxconn value is the maximum number of sockets that may be waiting in the accept queue. This usually allows the ircd to soak up more connections in a shorter space of time when increased but please be aware there is a system defined maximum value to this, the same way there is a system defined maximum number of file descriptors. Some systems may only allow this to be up to 5 (ugh) while others such as FreeBSD will default to a much nicer 128. If this value is omitted, the system defined constant SOMAXCONN is used in its place.
softlimit
- This optional feature allows a defined softlimit to be set on the server. This can not be higher than the ./configure limit, but may be changed during runtime and put in effect by a rehash. This is useful for keeping a soft limit of fd's lower than the ./configure value keeping a reserve for emergency use and releasing them by raising the softlimit.
userstats
- The userstats field is optional and specifies which stats characters in /STATS may be requested by non-operators. Stats characters in this field are case sensitive and are allowed to users independent of if they are in a module or the core.
operspywhois
- If this is set then when an IRC operator uses /WHOIS on a user they will see all channels, even ones if channels are secret (+s), private (+p) or if the target user is invisible +i.
customversion
- The customversion field is optional and if you specify this configuration item, and it is not set to an empty value, then when a user does a /VERSION command on the ircd, this string will be displayed as the second portion of the output, replacing the system 'uname', compile flags and socket engine/dns engine names. You may use this to enhance security, or simply for vanity.
maxtargets
- The maxtargets field is optional, and if not defined, defaults to 20. It indicates the maximum number of multiple targets which may be given to commands such as PRIVMSG, KICK etc.
hidesplits
- If set to 'yes', 'true' or '1', the optional hidesplits field will hide split server names from non-opers. This is similar (practically identical) to how ircu handles netsplits, showing normal users only '*.net *.split' instead of the real server names as a security measure. The actual security benifits of this feature are debated in great length on some networks, but you can decide for yourself if you want this feature or not
hidebans
- When set to 'yes', will hide gline, kline, zline and qline quit messages from non-opers. For example, user A who is not an oper will just see (G-Lined) while user B who is an oper will see the text (G-Lined: Reason here) instead.
tempdir
- This is an optional setting, which, if defined will change the temporary location modules are copied to before loading them. You may need to use this option if /tmp is noexec on your system.
hidewhois
- The optional hidewhois field can be set to any arbitary text, and if defined, will replace the users server in any WHOIS performed by a non-oper. Most networks which enable this will probably set it to, for example, *.network.net. As with the hidesplits option above, the actual security benefits of such a feature are greatly debated, and there are many opinions as to wether this actually improves security or not.
flatlinks
- The flatlinks field is optional, and if set to 'true', 'yes' or '1' while m_spanningtree.so is loaded, will cause /MAP and /LINKS to be flattened for non-opers.
hideulines
- hideulines, when specified, and you are using m_spanningtree.so, will conceal U-lined servers in /LINKS and /MAP for non opers. Please be aware that this will also hide any leaf servers of a U-lined server, e.g. jupes.
nouserdns
- When users connect to your server it will try and resolve the users hostname using the specified dns server in the <dns> tag. This can consume alot of CPU and bandwith for very busy irc servers. Turn this option on and no user dns lookups will be performed for connecting users. Do beware that no users will resolve and this may not be suitable for all irc servers, it is recommended to run a local nameserver when possible to minimize dns load.
syntaxhints
- Turn this option on to give users not providing enough parameters for a command, a syntax hint using the RPL_TEXT numeric as well as the standard ERR_NEEDMOREPARAMS.
cyclehosts
- When a user's hostname changes this option will make it appear as if the user quit and then rejoins with their new host. This prevents clients from becoming confused by host changes, especially in the case of bots, and it is recommended that this option is enabled.
ircumsgprefix
- Provides undernet style of prefixed channel NOTICEs and PRIVMSGs. With this option turned on the outgoing text will be prefixed with the used prefix. Eg. 'NOTICE @#test :@ this is a test' as opposed to the standard 'NOTICE @#test :this is a test'.
announcets
- When this option is enabled, then if a channel's timestamp is updated the users on the channel will be informed of the change via a server notice to the channel with the old and new TS values in the timestamp.
allowhalfop
- The allowhalfop variable enables or disables halfop support (channel mode +h). This may be moved into a module at some point in the future. Those of you who desire only the basic level of RFC compliance, without 'spangly bits' will wish to turn this option off by setting its value to 'no'.
moduledir
- The moduledir variable is optional and specifies the path to read modules from. If this is not defined, the value specified at compile time is defaulted to (which is normally the modules/ dir within your inspircd install)
hostintopic
- If this value is set to yes (which is the default from 1.1.2 onwards) then the full nick!user@host information is stored for any topic changes. Note that if one server has this enabled and another doesnt, the server without the feature enabled will still accept the full nick!user@host but will only send out the nick for any local changes.
announceinvites
- If this option is set to yes (the default), then invites are announced to the channel when a user invites annother user. If you consider this to be unnecessary noise, explicitly set this to no.
quietbursts
- If this option is set to no (the default), then when there is a link made from another server the bursts will be announced as joins to opers with the correct snomasks, if you consider this to be unncecessary noise, explicitly set this to yes
hidekills
- If this option is set, the string it is set to will be used as the prefix for all KILL messages, masking the original sender of the KILL. i.e.:
[01:59:57] * w00t2 (viroteck@test-d57df912.karoo.KCOM.COM) Quit (Killed (*.lol.hax (Drone!)))
instead of:
[01:59:57] * w00t2 (viroteck@test-d57df912.karoo.KCOM.COM) Quit (Killed (SomeOper (Drone!)))
exemptchanops
- Exempt Channel ops from the effects of channel modes. A valid configuration for this setting is in the format exemptchanops="modeshere" or blank for the default behavior of no exemptions. (currently only modes SfgNc are supported)
moronbanner
- The NOTICE to show to users who are glined, zlined, klined or qlined when they are disconnected. This is totally freeform, you may place any text here you wish.
<badip>
<badip ipmask="69.69.69.69" reason="No porn here thanks.">
These tags are used to define a z-line in your config file. You can define these from IRC with the /ZLINE command. You may use glob patterns in these tags.
<badnick>
<badnick nick="*[rxHO]*" reason="Script kiddiot.">
These tags are used to define banned nick masks, which you can also define on irc with the /QLINE command. You may use glob patterns in these tags if you wish.
NOTE: An interesting new feature of inspircd is that when you set a Q:Line, any users matching the nick will be disconnected. They will not be allowed back onto the network again using the same nickname that still matches the Q:Line mask, and must choose another before being allowed back to the server.
<badhost>
<badhost host="*@localhost" reason="No irc from localhost!">
These tags are used to define banned hostnames (K-Lines) which you may define over irc using the /KLINE command. You may use glob patterns in these tags if you wish to do so.
Note that K-Lines set with the /KLINE command will NOT be saved if the IRCd is resarted, however, K-Lines set in the configuration files will.
<exception>
<exception host="*@ircop.host.com" reason="Opers hostname">
These tags are used to define hostnames (E-Lines) which will not be affected by Klines / Glines / Zlines. This is the same as the /ELINE command on IRC, but exceptions added with /ELINE will not be saved over IRCd restarts. You may use glob patterns in these tags if you wish to do so.
<die>
<die value="anything here">
This tag if included will cause your irc server to bail on startup with the provided message. It is mainly used to make sure that config files are properly edited before use.
<dns>
<dns server="127.0.0.1" timeout="5">
This tag specifies what nameserver the ircd will attempt to use. The timeout value indicates how long to wait for a response from the DNS server.
For optimal performance of your irc network, each server which runs inspircd should also be running a copy of BIND. This should be a recent copy (you know, one without exploits, they do exist!) and should be listening on localhost (127.0.0.1). You should then make your queries to this, and it should be set as a caching nameserver. This way, you can return most of your queries extremely quickly. Home routers are not recommended as DNS servers!
<pid>
<pid file="/path/to/inspircd.pid">
This tag specifies a path to the PID file, which can be used to monitor an inspircd server and/or control its state from the shell. If this value is not defined, the default value of inspircd.pid is used. Paths can be relative to the config dir, or a full path from the filesystem root.
<banlist>
<banlist chan="*" limit="32">
This tag indicates that all channels matching the glob pattern given will have a banlist which is limited to 'limit' entries. In this case, all your channels will have a limit of 32. The banlist tags are read from top to bottom and when a matching tag is found, that ban limit is used for the channel. For example you may have a channel which reguarly gets frequented by spammers, trolls and other such online lowlife, and require a bigger banlist, and you would be able to increase the size of the banlist for this channel. If the server cannot find a matching banlist tag for a channel, it defaults to a hardcoded default of 64 entries. The official way to set a global limit is to use a tag similar to the one above which matches all channels which have not already been specified individually.
<channels>
<channels users="20"
opers="60">
This tag indicates the maximum amount of channels that a user or oper is allowed to be in at any one time.
<disabled>
<disabled commands="TOPIC MODE">
This optional tag provides a list of commands which are not available to non-operators. When a non-operator attempts to use a disabled command they will receive a 421 numeric as shown below:
TOPIC This command has been disabled.
The disabled commands only take effect once the user is fully 'registered' (e.g. after USER/NICK/PASS) so disabling NICK does not prevent connections. Please be careful of which commands you disable as disabling some commands can break the dialog boxes of many popular clients such as mIRC and xchat.
<include>
<include file="file.conf">
This optional tag allows you to include another config file allowing you to keep your configuration tidy. The configuration file you include will be treated as part of the configuration file which includes it, in simple terms the inclusion is transparent. All paths to config files are relative to the directory of the main config file inspircd.conf, unless the filename starts with a forward slash (/) in which case it is treated as an absolute path.
<insane>
<insane hostmasks="no" ipmasks="no" nickmasks="no" trigger="95.5">
This optional tag allows you to specify how wide a gline, eline, kline, zline or qline can be before it is forbidden from being set. By setting hostmasks="yes", you can allow all G, K, E lines, no matter how many users the ban would cover. This is not recommended! By setting ipmasks="yes", you can allow all Z lines, no matter how many users these cover too. Needless to say we don't recommend you do this, or, set nickmasks="yes", which will allow any qline.
The trigger value indicates how wide any mask will be before it is prevented from being set. The default value is 95.5% if this tag is not defined in your configuration file, meaning that if your network has 1000 users, a gline matching over 955 of them will be prevented from being added.
Please note that remote servers (and services) are exempt from these restrictions and expected to enforce their own policies locally!
<whowas>
<whowas groupsize="10" maxgroups="100000" maxkeep="3d">
This tag lets you define the behaviour of the /whowas command of your server. The following values can be defined:
- groupsize - Controls the maximum entries per nick shown when performing a /whowas nick. Setting this to 0 disables whowas completely.
- maxgroups - The maximum number of nickgroups that can be added to the list. If max is reached, oldest group will be deleted first like a FIFO. A groupsize of 3 and a maxgroups of 5000 will allow for 5000 nicks to be stored with a history of 3, thus giving a total of 3 * 5000 = 15000 entries. A setting of 0 disables whowas completely.
- maxkeep - The maximum time a nick is kept in the whowas list before being pruned. Time may be specified in seconds, or in the following format: 1y2w3d4h5m6s meaning one year, two weeks, three days, 4 hours, 5 minutes and 6 seconds. All fields in this format are optional. Minimum is 1 hour, if less InspIRCd will default back to 1 hour.
<timesync>
<timesync enable="no" master="no">
Time sychronization options for m_spanningtree linking:
- enable - If this value is 'yes', 'true', or '1', time synchronization is enabled on this server. This means any servers you are linked to will automatically synchronize time, however you should use ntpd instead where possible, NOT this option.
- master - If this value is set to yes, then this server will act as the authoritative time source for the whole network. All other servers will respect its time without question, and match their times to it. only one server should have the master value set to 'yes'.
Other tags
Any other tags you find in the config file are implemented by modules. You should search this wiki for documentation on the modules to learn how to configure them. A good place to start that search is our Modules List.
