Configuration

From the makers of InspIRCd.
Jump to: navigation, search

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>).

This file is not being split into multiple files like the confs are in the tarball or Git, however I will mention what file each block is in if it isn't in inspircd.conf.

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" id="97K" network="ChatSpike">

This section is where you enter the details of your server/network, most of which are visible to your users.

  • name: Hostname of your server. Does not need to resolve, but does need to be correct syntax (something.somethingelse.tld).
  • description: Server description. Spaces are allowed.
  • id: The SID to use for this server. This should not be uncommented unless there is a SID conflict. This must be three characters long. The first character must be a digit [0-9], the remaining two chars may be letters [A-Z] or digits.
  • network: Network name given on connect to clients. Should be the same on all servers on the network and not contain spaces.

<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.

  • name: Real Name
  • nick: Nickname (preferably what you use on the network).
  • email: email address. Does not have to be valid but should be for the users to be able to contact you.


<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:

NOTE: On InspIRCd 1.x use ssl="" for client ports and transport="" for server ports (even if they are using SSL). This has changed since InspIRCd 2.0 and only ssl="" is used (transport="" is removed!)

Using OpenSSL:

 <bind address="" port="6667" ssl="openssl">

Using gnutls:

 <bind address="" port="6667" ssl="gnutls">

Using Compression:

 <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">
  • diepass: Password for opers to use if they need to shutdown (die) a server.
  • restartpass: Password for opers to use if they need to restart a server.

<link> - links.conf

<link name="other.server.org" ipaddr="foomatic.bazqux.org" port="7000"
 allowmask="69.58.44.0/24" autoconnect="120" failover="other2.server.org" timeout="300"
 transport="transporttype" bind="1.2.3.4" statshidden="no" hidden="no" sendpass="XXX" recvpass="XXX">

This tag specifies a server which your server may attempt to link to. NOTE: The m_spanningtree.so module MUST be loaded to link to another server.

  • name: The name of the remote server. This must match the <server:name> value of the remote server.
  • ipaddr: The IP address of the remote server. This can also be a hostname, but hostname must resolve.
  • port: The port to connect to this server on. It must be bound as a server port on both servers.
  • allowmask: Range of IP addresses to allow for this link. Can be a CIDR (see example).
  • autoconnect: Time to wait to attempt to autoconnect to remote server (in seconds).
  • failover: If defined, if this link fails, what is the next link that is tried.
  • timeout: If defined, this option defines how long the server will wait to consider the connect attempt failed and try the failover (see above).
  • transport: If defined, this states extra modules that can be used in the connection. Options are: "openssl" and "gnutls" for encryption (they are compatible with each other) and "zip" for compression. You must use the same (or a compatible) transport on both sides of the link. You will need to load the m_ssl_openssl.so module for openssl, m_ssl_gnutls.so for gnutls or m_ziplinks.so for zip.
  • bind: Local IP address to bind to.
  • statshidden: Defines if IP is shown to opers when /stats c is invoked.
  • hidden: If this is set to yes, this server and it's "child" servers will not be shown when users do a /map or /links
  • passwords (sendpass and recvpass): The passwords we send and recieve. The remote server will have these passwords reversed.

<uline> - links.conf

<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.

  • silent: If set to yes, this setting indicates whether the ulined server should generate connect and quit notices or not.

<connect>

<connect allow="*" maxchans="30" timeout="10" 
pingfreq="120" sendq="131074" recvq="4096" 
localmax="3" globalmax="3" port="6660"
useident="no" limit="5000" modes="+x">

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.

  • allow: What IP addres/host to allow for this block.
  • maxchans: Maximum number of channels a user in this class can be in at one time. This overrides every other maxchans setting.
  • timeout: How long (in seconds) the server will wait before disconnecting a user if they do not do anything on connect. (Note, this is a client-side thing, if the client does not send /nick, /user or /pass)
  • pingfreq: How often (in seconds) the server tries to ping connecting clients.
  • sendq: Amount of data (in bytes) that the server is allowed to send to the user before they are dropped.
  • recvq: Amount of data (in bytes) allowed in a clients queue before they are dropped.
  • localmax: Maximum local connections per IP (or CIDR mask, see below).
  • globalmax: Maximum global (network-wide) connections per IP (or CIDR mask, see below).
  • port: Optional. If specified, the port that users must be connected to to be eligible for this <connect> block.
  • useident: Defines if users in this class MUST respond to a ident query or not.
  • limit: How many users are allowed in this class total.
  • modes: Usermodes that are set on users in this block on connect. Enabling this option requires that the m_conn_umodes module be loaded. This entry is highly recommended to use for/with IP Cloaking/masking. For the example to work, this also requires that the m_cloaking module be loaded.


Please note that connect tags are read from top to bottom, the earlier 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.

<cidr>

<cidr ipv4clone="32" ipv6clone="128">

This tag defines how wide detection of clones and flooding is. By default this is set to only define a clone or a flooder as multiple connections from only one IP address, but you can expand this. Here is a good chart that shows how many IP's the different CIDR's correspond to: http://en.wikipedia.org/wiki/CIDR#Prefix_aggregation

By default this is set to a singular IP for both IPv4 and IPv6 and it is set as high as it can go. This emulates the behavior of InspIRCd 1.1.

<class> - opers.conf

<class name="Shutdown" commands="DIE RESTART REHASH" 
privs="users/auspex channels/auspex servers/auspex users/mass-message channels/high-join-limit"
usermodes="*" chanmodes="*">

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.

There are also now privs which allow you to see certain things and have certain privledges as a oper. These are documented in the opers.conf.example.

Two other new variables were added to the <class> tag, those are usermodes and channelmodes. These define what oper-only usermodes and channelmodes certain classes can set. For example, if you want a specific class to only be able to set permanent channels, make the channelmodes variable look like this: channelmodes="P"

If you put a command called '*' (without the quotes) into a class, then the class covers ALL possible commands, modes and privs. USE WITH CARE! For example:

<class name="Everything" commands="*" privs="*" usermodes="*" chanmodes="*">

<type> - opers.conf

<type name="GlobalOp" classes="OperChat BanControl HostCloak Modular" vhost="globalop.chatspike.net"
modes="+s +cCqQ">
  • name: Name of type. Used in actual olines below. Cannot contain spaces. If you would like a space, use the _ character instead and it will translate to a space on whois.
  • classes: classes (above blocks) that this type belongs to.
  • vhost: host oper gets on oper-up. This is optional.
  • modes: usermodes besides +o that are set on a oper of this type when they oper up. Used for snomasks and other things. Requires that m_opermodes.so be loaded.
NOTE: when you specify <type:swhois> and <oper:swhois>, the oper block takes precedence over the type block.

<oper> - opers.conf

<oper name="Brain" password="s3cret" host="ident@dialup15.isp.com *@localhost *@server.com *@3ffe::0/16"
type="NetAdmin">
  • name: oper login that is used to oper up (/oper name password). Remember: This is case sensitive.
  • password: case-sensitive, unhashed...yea...self-explanatory.
  • host: What hostnames/IP's are allowed to oper up with this oline. Multiple options can be separated by spaces and CIDR's are allowed. You CAN use just * or *@* for this section, but it is not recommended for security reasons.
  • type: What oper type this oline is. See the block above for list of types. NOTE: This is case-sensitive as well.
<oper name="Brain" hash="sha256" host="ident@dialup15.isp.com *@localhost *@server.com *@3ffe::0/16"
password="1ec1c26b50d5d3c58d9583181af8076655fe00756bf7285940ba3670f99fcba0"type="NetAdmin">
  • All other variables are the same as the ones above except:
  • hash: what hash this password is hashed with. requires the module for selected hash (m_md5.so, m_sha256.so or m_ripemd160.so) be loaded and the password hashing module (m_password_hash.so) loaded. Options here are: "md5", "sha256" and "ripemd160". Create hashed password with: /mkpasswd <hash> <password>
  • password: a hash of your password (see above option) hashed with /mkpasswd <hash> <password> . See m_password_hash in modules.conf for more information about password hashing.
NOTE: when you specify <type:swhois> and <oper:swhois>, the oper block takes precedence over the type block

<files>

<files  motd="/path/to/motd" rules="/path/to/rules">
  • motd: Path to your motd file. Path is relative to the conf directory.
  • rules: Path to your rules file. Path is relative to the conf directory. This is optional and is displayed when a user does /rules on the network.

NOTE: You can not executable or remote include motd and rules files currently.

<module> - modules.conf

<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: " suffixquit="" prefixpart="\"" suffixpart="\""
syntaxhints="no" cyclehosts="yes" ircumsgprefix="no" announcets="yes"
hostintopic="yes" pingwarning="15" serverpingfreq="60" allowhalfop="yes" defaultmodes="nt"
moronbanner="You're banned! Email haha@abuse.com with the ERROR line below for help."
exemptchanops="" invitebypassmodes="yes">

This tag specifies a group of miscellaneous options.

  • prefixquit: What (if anything) a users' quit message should be prefixed with.
  • suffixquit: What (if anything) a users' quit message should be suffixed with.
  • prefixpart: What (if anything) a users' part message should be prefixed with.
  • suffixpart: What (if anything) a users' part message should be suffixed with.
  • syntaxhints: If enabled, if a user fails to send the correct parameters for a command, the ircd will give back some help text of what the correct parameters are.
  • cyclehosts: If enabled, when a user gets a host set, it will cycle them in all their channels. If not, it will simply change their host without cycling them.
  • ircumsgprefix: Use undernet-style message prefixing for NOTICE and PRIVMSG. If enabled, it will add users' prefix to the line, if not, it will just message the user normally.
  • announcets: If set to yes, when the TimeStamp on a channel changes, all users in channel will be sent a NOTICE about it.
  • hostintopic: If enabled, channels will show the host of the topicsetter in the topic. If set to no, it will only show the nick of the topicsetter.
  • pingwarning: If a server does not respond to a ping within x seconds, it will send a notice to opers with snomask +l informing that the server is about to ping timeout.
  • serverpingfreq: How often pings are sent between servers (in seconds).
  • allowhalfop: Allows the use of +h channelmode (halfops).
  • defaultmodes: What modes are set on a empty channel when a user joins it and it is unregistered. This is similar to Asuka's autochanmodes.
  • moronbanner: This is the text that is sent to a user when they are banned from the server.
  • exemptchanops: Defines what channel modes channel operators are exempt from. Supported modes are +TCGfcSFBgN. Defaults to off.
  • invitebypassmodes: This allows /invite to bypass other channel modes. (Such as +k, +j, +l, etc)

<performance>

<performance netbuffersize="10240" maxwho="128" somaxconn="128"
softlimit="12800" quietbursts="yes" nouserdns="no">

A few options relating to how the IRCd performs.

  • netbuffersize: Size of the buffer used to recieve data from clients. The ircd may only read this amount of text in 1 go at any time.
  • maxwho: Maximum number of results to show in a /who query. It is not recommended to set this above 1024.
  • somaxconn: The maximum number of connections that may be waiting in the accept queue. This is *NOT* the total maximum number of connections per server. Some systems may only allow this to be up to 5, while others (such as linux and *BSD) default to 128.
  • softlimit: This optional feature allows a defined softlimit for connections. If defined, it sets a soft max connections value. Must be lower than ./configure maxclients.
  • quietbursts: When syncing or splitting from a network, a server can generate a lot of connect and quit messages to opers with +C and +Q snomasks. Setting this to yes squelches those messages, which makes it easier for opers, but degrades the functionality of bots like BOPM during netsplits.
  • nouserdns: If enabled, no DNS lookups will be performed on connecting users. This can save a lot of resources on very busy servers.

<security>

<security announceinvites="dynamic" hidemodes="eI" hideulines="no"
flatlinks="no" hidewhois="" hidebans="no" hidekills="" hidesplits="no"
maxtargets="20" customversion="" operspywhois="no" 
restrictbannedusers="yes" genericoper="no" userstats="Pu">

A few options relating to security.

  • announceinvites: If this option is set, then invites are announced to the channel when a user invites another user. If you consider this to be unnecessary noise, set this to 'none'. To announce to all ops, set this to 'ops' and to announce to all users, set the value to 'all'. The value 'dynamic' will make the messages go to every user who has power of INVITE on the channel. This is the recommended setting.
  • hidemodes: If enabled, then the listmodes given will be hidden from users below halfop. This is not recommended to be set on +b as it may break some functionality in popular clients such as mIRC.
  • hideulines: If this value is set to yes, U-lined servers will be hidden from non-opers in /links and /map.
  • flatlinks: If this value is set to yes, /map and /links will be flattened when shown to non-opers.
  • hidewhois: When defined, the given text will be used in place of the server a user is on when whoised by a non-oper. Most networks will want to set this to something like "*.netname.net" to conceal the actual server a user is on.
  • hidebans: If this value is set to yes, when a user is banned ([gkz]lined) only opers will see the ban message when the user is removed from the server.
  • hidekills: If defined, replaces who set a /kill with a custom string.
  • hidesplits: If enabled, non-opers will not be able to see which servers split in a netsplit, they will only be able to see that one occurred (If their client has netsplit detection).
  • maxtargets: Maximum number of targets per command. (Commands like /notice, /privmsg, /kick, etc)
  • customversion: Displays a custom string when a user /version's the ircd. This may be set for security reasons or vanity reasons.
  • operspywhois: If this is set to yes, when a oper /whois 's a user, it will show all channels the user is in including +s and +p channels.
  • restrictbannedusers: If this is set to yes, InspIRCd will not allow users banned on a channel to change nickname or message channels they are banned on.
  • genericoper: Setting this value to yes makes all opers on this server appear as 'is an IRC operator' in their WHOIS, regardless of their oper type, however oper types are still used internally. This only affects the display in WHOIS.
  • userstats: /stats commands that users can run (opers can run all).

<limits>

<limits maxnick="31" maxchan="64" maxmodes="20"
maxident="11" maxquit="255" maxtopic="307"
maxkick="255" maxgecos="128" maxaway="200">

This block is used to set the size limits of different things on the network. These options were previously only settable in ./configure. The values should match network-wide otherwise issues will occur. The highest "safe" value you can set any of these options to is 500, but it is recommended that you keep them somewhat near their defaults (or lower).

  • maxnick: Maximum length of a nickname.
  • maxchan: Maximum length of a channel name.
  • maxmodes: Maximum number of mode changes per line.
  • maxident: Maximum length of a ident/username.
  • maxquit: Maximum length of a quit message.
  • maxtopic: Maximum length of a channel topic.
  • maxkick: Maximum length of a kick message.
  • maxgecos: Maximum length of a GECOS (realname).
  • maxaway: Maximum length of an away message.

<log>

<log method="file" type="* -USERINPUT -USEROUTPUT -m_spanningtree" level="default" target="ircd.log">
  • method: What sort of backend to log to. Currently "file" works out-of-box, and you need to load m_sqllog and a SQL provider module for a "sql" method.
  • type: What data to log to this file. Different types are available here: LogTypes
  • level: How much of the type of data selected should be logged. Available options are: default, debug, sparse, and verbose.
  • target: What filename to log to. Log files are kept in bin/ by default. You can specify your own directory by making this value the absolute path to the file. Of course, if you do change the path, the user running the IRCd needs to have write access to that file/directory.

<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.

<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" usermodes="" chanmodes="" fakenonexistant="yes">

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.
  • commands: The commands to disable.
  • usermodes/chanmodes: Usermodes and channelmodes to disable. These will basically show like when a user tries to set a mode that doesn't exist.
  • fakenonexistant: Instead of mentioning that the disabled command is disabled, it will just say: "No such command".

<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.

As of InspIRCd 1.2, InspIRCd support executable includes which can be used to basically create remote includes. A configuration file can also be generated from a script on-the-fly each time as well. Here's a example of how to do remote includes:

<include executable="/usr/bin/wget -q -O - http://mynet.net/inspircd.conf">

As you can probably see, the syntax for this is: <include executable="/path/to/executable parameters">

<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.


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.