Requirements 
 License 

 Installation 
 IRC usage 
 Server connects 
 DCC sends 
 Logging 

 Format 
 Reference 
 Example 

 Roadmap 
 Download 
 Config parser 
 Visions & ideas 

Configuration file format

While the actual configuration directives themselves are documented in the the Configuration directive reference, this page contains some general, yet important information about the MetalServe configuration file:

• File locations
• General format
• Argument syntax
• Quoting & Escaping
• Contexts

File locations

All configuration is done via a configuration file that can be located either at the central location /etc/metalserve.conf, or ~/.metalserve.conf in the home directory of the user running MetalServe. The first location will always override the second.

General format

The file is a human-editable ASCII file which contains configuration directives which tell MetalServe how to act and react. The format partly resembles the configuration file of bind, the popular domain name server (DNS server) software from the Internet Software Consortium.

Lines that start with a # character are treated as comments and ignored by MetalServe, as are blank lines (lines that contain only spaces or tabs). Configuration directives consist of a single word, followed by a space, followed by either one or multiple arguments, or an opening brace on the next line starting a subsection (and thus a different Context):

# This is a comment and will be ignored
directive argument or

directive argument another_argument or

directive
{
	another_directive argument
	yet_another_directive argument another_argument
}

Argument syntax

As for the syntax of the arguments to a configuration directive, there are currently four general formats defined, that could be required by the particular directive:

1. some directives may require simply a string
2. some directives require a list of strings seperated by "Space", either arbitrary strings (eg. nicknames) or one or more special keywords (eg. option keywords, similar to the Apache Webserver's "Options" directive).
3. some option directives require a switch keyword (either yes or on, enabling the option, or no resp. off, disabling the option).
4. some directives require some other keyword, eg. the loglevel directive.
5. and some directives require an integer value (that is, a number).

Examples:

1. serverroot /space/music
2. ignored_users user1 user2
3. client_lookups on
4. loglevel notice
5. part_timeout 120

Quoting & Escaping

Since Space is used to seperate arguments, Space characters within an argument itself require special treatment: you can quote the entire argument, ie. add double quotes to its beginning and its end. Everything between two consecutive double quotes characters will form a single argument, including any Space characters. The double quotes themselves will be removed by the parser.

You can however also prefix the Space character with a Backslash character \. The Backslash does two things: for one hand, it prevents the immediately following character from being interpreted. On the other hand, the entire escape sequence is replaced as follows:

So, to give you an example:

serverroot "/space/music"
ignored_users foo bar "some other user"

• serverroot with the argument /space/music
• ignored_users with the three arguments foo, bar and some other user.

Naturally it doesn't make much sense to specify a nickname with Spaces in it as argument to the ignored_users directive since the IRC protocol prohibits this. We just needed a directive accepting multiple arguments for this example.

Contexts

Some configuration directives can have different meanings depending on the context they appear in. For most directives this is of no relevance, since they can appear within the global context only. Some directives however can appear in different contexts, depending on their location in the configfile.

As in most cases, an example says more than thousand words. Consider the following possible excerpt from a configuration file:

server default
{
	find_trigger on
}

network somenet
{
	server irc.somenet.foo
	{
		find_trigger off
	}
}

So what practical difference does the context make? This depends on the particular configuration directive. In the example above, the only purpose of a server directive in the global context can be to define default properties for further server directives, therefore no server name is specified but the special keyword default. find_trigger is set to be enabled by default.

The second server directive however lies within the context of the particular IRC network "somenet". The second find_trigger directive in turn lies within the context of the IRC server "irc.somenet.foo" and its argument off overrides the previously specified default.

Further details about context and which configuration directives are subject to a different meaning depending on the context can be found at the discussion of those directives that can change the context by "opening" subsections: currently network, server and channel). Also consider the included example configuration file for a sophisticated configuration which demonstrates the concept of different contexts quite impressively.