Requirements 
 License 

 Installation 
 IRC usage 
 Server connects 
 DCC sends 
 Logging 

 Format 
 Reference 
 Example 

 Roadmap 
 Download 
 Config parser 
 Visions & ideas 

Configuration directive reference

Index of currently documented configuration directives:

• advertise_delay
• channel
• client_lookups
• compress_command
• dcc_largefiles_mincps
• dcc_largefiles_threshold
• dcc_maxlistqueue
• dcc_maxlistxfers
• dcc_maxqueue
• dcc_maxuserqueue
• dcc_maxuserxfers
• dcc_maxxfers
• dcc_mincps
• dcc_ports
• dcc_timeout
• dir_overview
• email_address
• find_trigger
• hintsfile
• include_extensions
• ignored_users
• join_attempts
• join_retrydelay
• keep_uncompressed_list
• list_header
• logfile
• loglevel
• network
• nickname
• onkick_rejoin_attempts
• part_finishdccs
• part_timeout
• password
• ports
• priority
• realname
• rejoin_on_kick_attempts
• server
• server_connect_attempts
• server_connect_delay
• server_connect_timeout
• server_timeout
• serverroot
• visible_address

advertise_delay directive

Syntax:	advertise_delay delay in seconds
Default:	900
Context:	Inside a channel directive's subsection
Example:	advertise_delay 1800

MetalServe posts advertisements to the IRC channels so that users know that it serves files. The advertise_delay directive sets the delay between these advertisements.

Setting this value too low will easily get you kicked and/or banned from IRC channels since you'll get on the IRC users' nerves.

channel directive

Syntax:	channel channel name or channel channel name {     ... }
Default:	None
Context:	Global (with the special keyword default) or inside a network subsection
Example:	see the example configfile

The channel directive can appear:

• either in combination with the special keyword default, in which case the subsection which must be present describes the defaults for other channel directives in the configuration file,

• or together with the name of a channel inside a network subsection, in which case it represents an IRC channel within this network of IRC servers, that is to be joined by MetalServe. The directive may open a subsection which contains directives that override default values.

For each configured IRC network, at least one channel directive must be specified.

client_lookups directive

Syntax:	client_lookups [on|off|yes|no]
Default:	off / no
Context:	Global
Example:	client_lookups on

The client_lookups directive specifies whether MetalServe should look up (and display/log) the hostname of connecting IRC clients or leave their IP addresses unresolved. Hostnames tell you more about the origin of your clients, but introduce an additional delay until a client's request is satisfied.

This option takes either "on" or "yes" as argument to be enabled, or "off" or "no" to be disabled.

compress_command directive

Syntax:	compress_command command string
Default:	none
Context:	Global
Example:	compress_command zip -9 -l "%a" "%t"

The compress_command directive specifies a command to be executed by makelist as soon as the file list generation completes. command_string may contain two placeholders: %a will be replaced with the archive name (without an extension which is subject to be added by the compressor itself) and %l will be replaced with the list filename.

This directive should be used when the generated filelist reaches a size where compression really starts to make sense (think of 56 kbit/s modem users having to download a 1 Megabyte filelist). Most clients including AutoGet support .zip-compressed file lists, therefore you should specify "zip" and not "tar"/ "gzip" as compressor.

If a compress_command directive is specified, MetalServe by default deletes the uncompressed textfile. You can modify this behaviour using the keep_uncompressed_list directive.

dcc_largefiles_mincps directive

Syntax:	dcc_largefiles_mincps minimum cps
Default:	None
Context:	Global
Example:	dcc_largefiles_mincps 1000

The dcc_largefiles_mincps directive works exactly like the dcc_mincps directive, but is applied to "large files" only. The file size threshold that makes a file a "large file" is configured using the dcc_largefiles_threshold directive.

The idea is that you may want that only users with an acceptable large Internet connection (DSL, Cable or faster) can download really large files such as eg. MPEG video files.

dcc_largefiles_threshold directive

Syntax:	dcc_largefiles_threshold file size in KB
Default:	10240
Context:	Global
Example:	dcc_largefiles_threshold 10240

The dcc_largefiles_threshold directive specifies the threshold value MetalServe uses to determine whether a file is considered a "large file" or not. If a file is a "large file", the minimum CPS limit configured with the dcc_largefiles_mincps directive will be in effect, otherwise the limit set by the dcc_mincps directive.

Please note that while there is a default value of 10240 KB for this directive, there are no default values for both dcc_largefiles_mincps and dcc_mincps directives. MetalServe will thus by default never abort a transfer because it thinks it's going too slow.

dcc_maxlistqueue directive

Syntax:	dcc_maxlistqueue queue length
Default:	30
Context:	Global
Example:	dcc_maxlistqueue 20

The dcc_maxlistqueue directive sets the length of the filelist request queue. This value determines how many "waiting positions" are available for users requesting your filelist, when the number of filelist send slots, configured with the dcc_maxlistxfers directive, has been exhausted.

For a detailed discussion of this and related configuration directives, see DCC sends.

dcc_maxlistxfers directive

Syntax:	dcc_maxlistxfers number of concurrent list xfers
Default:	2
Context:	Global
Example:	dcc_maxlistxfers 3

The dcc_maxlistxfers directive sets the number of send slots available for the transfer of your file list. When additional requests come in and all send slots are in use, the request will be queued in the filelist request queue, whose length can be set with the dcc_maxlistqueue directive.

For a detailed discussion of this and related configuration directives, see DCC sends.

dcc_maxqueue directive

Syntax:	dcc_maxqueue queue length
Default:	20
Context:	Global
Example:	dcc_maxqueue 20

The dcc_maxqueue directive sets the length of the file request queue. This value determines how many "waiting positions" are available for users requesting files other than your filelist (for which special directives are available), when the number of send slots, configured with the dcc_maxxfers directive, has been exhausted.

For a detailed discussion of this and related configuration directives, see DCC sends.

dcc_maxuserqueue directive

Syntax:	dcc_maxuserqueue queue entries per user
Default:	3
Context:	Global
Example:	dcc_maxuserqueue 5

The dcc_maxuserqueue directive restricts the number of requests a specific user can place in the file request queue. If a user files a request and has reached this limit, his request will be denied and other users' requests will be accepted into the queue instead. The (obvious) idea is to keep single users from dominating your DCC queue and give everyone a fair chance.

The value specified here must be lower than the value specified at the dcc_maxqueue directive or MetalServe will complain.

For a detailed discussion of this and related configuration directives, see DCC sends.

dcc_maxuserxfers directive

Syntax:	dcc_maxuserxfers number of concurrent xfers per user
Default:	1
Context:	Global
Example:	dcc_maxuserxfers 2

The dcc_maxuserxfers directive restricts the number of parallel file transfers to a single user. If a send slot becomes available and the user has already reached this limit, the slot will be assigned to a different user. The (obvious) idea is to keep single users from dominating your DCC sends and give everyone a fair chance.

The value specified here must be lower than the value specified at the dcc_maxxfers directive or MetalServe will complain.

For a detailed discussion of this and related configuration directives, see DCC sends.

dcc_maxxfers directive

Syntax:	dcc_maxxfers number of concurrent xfers
Default:	2
Context:	Global
Example:	dcc_maxxfers 1

The dcc_maxxfers directive sets the number of send slots available for the transfer of files other than your filelist. When additional requests come in and all send slots are in use, the request will be queued in the file request queue, whose length can be set with the dcc_maxqueue directive.

For a detailed discussion of this and related configuration directives, see DCC sends.

dcc_mincps directive

Syntax:	dcc_mincps minimum CPS
Default:	none
Context:	Global
Example:	dcc_mincps 500

The dcc_mincps directive sets a minimum CPS restriction that must be fulfilled for DCC transfers to finish. If a transfer repeatedly drops below this configured value, MetalServe will abort the transfer.

While there is no minimum CPS limit configured by default, you may use the directive to keep users with an unbearable slow Internet connection from using your send slots forever.

dcc_ports directive

Syntax:	dcc_ports minport-maxport
Default:	1024-65535
Context:	Global
Example:	dcc_ports 1024-1100

The dcc_ports directive restricts the range of TCP ports that will be used by MetalServe for DCC sends to clients requesting files. This may be useful on firewalls where a certain surveyable range of ports is opened.

If this option is not specified, MetalServe will use the entire high port range (ie. everything above port 1023).

dcc_timeout directive

Syntax:	dcc_timeout value in seconds
Default:	120 seconds
Context:	Global
Example:	dcc_timeout 180

The dcc_timeout directive specifies the amount of time MetalServe should wait when a DCC connection appears to stall. If no activity occurs on the connection and the specified time in seconds has passed, the connection is assumed to have died and will be closed.

The value specified here should be high enough to accomodate typical Internet conditions that can cause a connection to stall for some time. You should not specify a lower value than the default of 120 seconds.

dir_overview directive

Syntax:	dir_overview [on|off|yes|no]
Default:	on / yes
Context:	Global
Example:	dir_overview off

The dir_overview directive specifies whether makelist should include an overview of the scanned directories in front of the actual file listing. This overview is useful especially in large file lists when the first directory level represents a genre as you can sometimes argue over what genre an album should belong to.

email_address directive

Syntax:	email_address email address
Default:	none
Context:	Global
Example:	email_address foo@bar.com

The email_address directive specifies the email address that MetalServe should use to log on to the configured IRC network(s). This is what users see when they /WHOIS the IRC user represented by MetalServe.

Some IRC networks may require by policy that you specify a valid email address here, so you should check twice before you specify something else.

An email_address directive must appear in the configuration file.

find_trigger directive

Syntax:	find_trigger [on|off|yes|no]
Default:	on / yes
Context:	Inside a channel directive's subsection
Example:	find_trigger off

The find_trigger directive specifies whether MetalServe should process @find and @locator searches IRC users post in the channels MetalServe is serving in. MetalServe will search your filelist using the keywords the users specified and send him the first five matches through a private message.

You should only disable this option if MetalServe is drowning too much CPU time with this type of searches. Not all clients may use client-side scripts such as AutoGet for mIRC on the Windows platform, which provides filelist search and management facilities.

hintsfile directive

Syntax:	hintsfile filename or hintsfile syslog[:facility] or hintsfile none or
Default:	/var/lib/metalserve/hints.txt
Context:	Global
Example:	hintsfile syslog:local4

The hintsfile directive specifies the destination file for "hints" submitted by users via the @<nickname>-hint command.

If a filename is specified you should make sure that the specified file can be written to by the user MetalServe runs under.

If the special keyword syslog is specified, it may be followed by a colon and the desired syslog facility (eg. local4, refer to your system's "syslog.conf" manpage).

The special keyword none disables the "hints" facility (ie. users won't be able to notify you of broken files), but we strongly recommend to leave it enabled so users can help you in improving the quality of the files offered (unless, of course, the mechanism is abused).

Included in the MetalServe distribution is a shell script that simply mails the contents of the "hints" file to a configured EMail address and resets it afterwards. You could run this script eg. as a cron job every night so that you get a mail once a day if any hints were submitted. The script can be found under /bin/mail_hints.sh.

ignored_users directive

Syntax:	ignored_users nickname1 nickname2 ...
Default:	none
Context:	Global
Example:	ignored_users Stalker1 Stalker2

The ignored_users directive takes a list of IRC nicknames to be ignored. This option may be used to exclude certain abusive users from being served. Currently only nicknames can be specified, in the future userid@hostmask combinations may be accepted as well to make this option as efficient as K-lines on the IRC server side (and prevent users from singly changing nicknames).

If no ignored_users directive is specified, all files will be included.

include_extensions directive

Syntax:	include_extensions extension extension ...
Default:	none
Context:	Global
Example:	include_extensions .mp3 .mpg .avi

The include_extensions directive takes a list of filename extensions as argument which describe the file types which are exclusively to be included. Files with extensions that do not appear in this list will be ignored by makelist.

If no include_extensions directive is specified, all files will be included.

join_attempts directive

Syntax:	join_attempts number of attempts
Default:	5
Context:	Global
Example:	join_attempts 2

MetalServe by default attempts to join those channels on an IRC network that were configured using channel directives. However, joining may fail, eg. if the channel's user limit has been reached. In such a case, it makes sense to retry to join the channel at a later point in time.

This directive therefore specifies an upper limit as to the number of attempts MetalServe will perform in order to join a given channel. If all attempts have failed, MetalServe will give up and consider the channel to be disabled. The delay between the join attempts can be configured with the join_retrydelay directive.

Note that this directives differs from the onkick_rejoin_attempts directive in that the latter only applies to the case of rejoining a channel after being KICKed out of it.

join_retrydelay directive

Syntax:	join_retrydelay delay in seconds
Default:	60
Context:	Global
Example:	join_retrydelay 120

This directive configures the delay between the attempts to join or rejoin a channel (see the join_attempts and onkick_rejoin_attempts directives).

Valid values range between 0 and 86400 seconds (24 hours).

keep_uncompressed_list directive

Syntax:	keep_uncompressed_list [on|off|yes|no]
Default:	off / no
Context:	Global
Example:	keep_uncompressed_list on

The keep_uncompressed_list directive specifies whether MetalServe should keep and offer the filelist also in its original uncompressed textfile form, if compression of the filelist was enabled using the compress_command directive. By default Metalserve deletes the uncompressed textfile.

This directive has no effect if no compress_command directive was specified.

list_header directive

Syntax:	list_header directory
Default:	none
Context:	Global
Example:	list_header /var/lib/metalserve/header.txt

The list_header directive specifies the filename of an auxiliary text file to be included as a list header, in between MetalServe's own header and the directory/files listing.

What you put into this file is up to you, but it doesn't really make sense to include fancy ASCII graphics since the font used by the viewer of download clients such as AutoGet is often a proportional one, giving the logo a rather distorted look.

Note that you do not need to include a blank line at the end of your header as makelist will add one itself before a seperator line is written.

logfile directive

Syntax:	logfile filename or logfile syslog[:facility] or logfile none or
Default:	/var/log/metalserve.log
Context:	Global
Example:	logfile /usr/local/metalserve/metalserve.log

The logfile directive enables the logging of more or less important messages (influenced by the loglevel parameter) to the specified logfile, syslog or disables all logging.

If the special keyword syslog is specified, it may be followed by a colon and the desired syslog facility (eg. local4, refer to your system's "syslog.conf" manpage).

The special keyword none disables any logging.

Specifying none is a bad idea, but we won't prevent you from shooting yourself in the foot!
If a filename is specified, MetalServe must have appropriate permissions in order to be able to write to it!

See also Logging.

loglevel directive

Syntax:	loglevel [critical|error|warning|notice|info|debug]
Default:	warning
Context:	Global
Example:	loglevel debug

The loglevel directive specifies the minimum required severity for a message to be logged. Lowering the specified severity level will increase the amount of messages logged and vice versa.

Valid arguments for the severity level are in descending order of severity and ascending order of verboseness: critical, error, warning, notice, info, debug.

See also Logging.

network directive

Syntax:	network network name {     channel ...     ...     server ...     ... }
Default:	None
Context:	Global
Example:	see the example configfile

The network directive opens a subsection of directives related to a network of IRC servers. The directive's argument is a network name like Undernet, EFNet, IRCNet etc. The subsection opened by this directive must contain at least one channel and at least one server directive.

Each network directives configures a seperate IRC network, at least from MetalServe's point of view, and there must be a least one network directive in the configuration file or MetalServe will complain.

nickname directive

Syntax:	nickname nickname alternative1 alternative2 ...
Default:	none
Context:	Global
Example:	nickname ICWeener ICWeener2

The nickname directive specifies the preferred nickname and desired alternatives that MetalServe should use to log on to the configured IRC network(s). For each IRC network, MetalServe will try the nicknames in the specified order. This means that it is possible that you serve on different IRC networks with different nicknames at the same time.

If MetalServe can not successfully log on to an IRC network with any of the specified nicknames, it will give up on that IRC network (and maybe retry later, see the network directive). If it can't log on to any of the configured IRC networks, it will log an error message and exit, as in that case you should really consider different and/or more nicknames.

Nicknames are subject to the usual IRC restrictions: nicknames must consist of 1 to 9 characters. The first character must be a letter, the other characters can be letters, numbers or any of the special characters '-', '[', ']', '\', '`', '^', '{' or '}'. IRC servers will complain if you specify an invalid nickname.

If you plan to serve in channels where advertisements are not welcome, you should probably choose a nickname that somehow indicates to other users that you're serving. For example, you could include "DCC" in your nicknames.

A nickname directive must appear in the configuration file.

onkick_rejoin_attempts directive

Syntax:	onkick_rejoin_attempts number of attempts
Default:	1
Context:	Global
Example:	onkick_rejoin_attempts 0

MetalServe may be KICKed off of one of the channels it was configured to join for some good or not so good reason. Since machines can't "react" to the reason being specified for the kick (if specified at all), this parameter configures how to be have in such a case.

A non-zero value from 1 to 5 specifies the maximum number of attempts made in order to rejoin the channel, with join_retrydelay seconds between each attempt. A value of zero specifies that MetalServe should not attempt to rejoin the channel at all.

Note that this directives differs from the join_attempts directive in that it only applies when MetalServe is kicked off a channel.

part_finishdccs directive

Syntax:	part_finishdccs [on|off|yes|no]
Default:	on / yes
Context:	Global
Example:	part_finishdccs off

The part_finishdccs directive specifies whether a user's ongoing DCC transfers are finished or cancelled, when he PARTs (leaves) a channel for a longer time than specified with the part_timeout option.

This option takes either "on" or "yes" as argument to be enabled, or "off" or "no" to be disabled.

part_timeout directive

Syntax:	part_timeout value in seconds
Default:	120 seconds
Context:	Global
Example:	part_timeout 180

The part_timeout directive specifies the amount of time a user may be missing from a channel until his and his queued file requests are removed, and his ongoing DCC sends are cancelled (unless part_finishdccs is enabled).

The idea is that users have to stay in the channel as long as they have requests open and/or transfers in progress. The value specified here should be high enough to accomodate users reconnecting after being disconnected by their Internet providers or suffering from IRC netsplits. You should not specify a lower value than the default of 120 seconds.

password directive

Syntax:	password server password
Default:	none
Context:	Inside a server directive's subsection
Example:	password TopSecret

The password directive specifies a password that must be sent by MetalServe in order to be accepted by the associated IRC server.

Server passwords are rather rare, yet there may be some "private" IRC networks that realize their privacy by means of server passwords. However, you will probably never need to specify this directive.

ports directive

Syntax:	ports minport-maxport
Default:	6660-6669
Context:	Inside a server directive's subsection
Example:	ports 6666-6669

The ports directive specifies the TCP port range that the associated IRC server is listening on for client connections. IRC servers usually listen on other ports besides the default port 6667, mostly ports in the range 6660-6669 (which is why this range is the default), but the actual used range varies.

If a server listens on a single port only, you can specify just that port number (ie. you do not need to construct a range with the port being both minport and maxport). Note that you can specify only one continous port range, it is eg. not possible to specify ports 6660-6667 and port 6669.

priority directive

Syntax:	priority priority between -19 and 20
Default:	0
Context:	Inside a channel or server directive's subsection
Example:	priority 2

The priority directive can be used to order the list of channels or IRC servers within a configured IRC network and give preference to certain servers over others. MetalServe will respect this setting when the IRC server restricts the number of channels that can be joined at a given time resp. when it determines which server of an IRC network it connects to (and which server to try if the selected server fails).

realname directive

Syntax:	realname real name
Default:	none
Context:	Global
Example:	realname John Sinclair

The realname directive specifies the real name that MetalServe should use to log on to the configured IRC network(s). This is what users see when they /WHOIS the IRC user represented by MetalServe.

Some IRC networks may require by policy that you specify your real name, so you should check twice before you specify something else.

A realname directive must appear in the configuration file.

server directive

Syntax:	server hostname or server hostname {     ... }
Default:	None
Context:	Global (with the special keyword default) or inside a network subsection
Example:	see the example configfile

The server directive can appear:

• either in combination with the special keyword default, in which case the subsection which must be present describes the defaults for other server directives in the configuration file,

• or together with the hostname of a server inside a network subsection, in which case it represents a IRC server belonging to this network. The directive may open a subsection which contains directives that override default values.

For each configured IRC network, at least one server directive must be specified.

A list of IRC networks and their servers can be found at irchelp.org.

server_connect_attempts directive

Syntax:	server_connect_attempts max. number of attempts
Default:	5
Context:	Global
Example:	server_connect_attempts 3

The server_connect_attempts directive specifies the maximum number of attempts MetalServe will perform in order to connect to each IRC server. If this limit has been reached, the server will be disabled. If a fatal error occurs, eg. the server's hostname could not be resolved, the server is disabled immediately.

server_connect_timeout directive

Syntax:	server_connect_timeout value in seconds
Default:	30 seconds
Context:	Global
Example:	server_connect_timeout 60

The server_connect_timeout directive specifies the amount of time MetalServe will wait for a connection to an IRC server to be established. After the specified time in seconds has passed, MetalServe will abort the connection to this server and try another server within the same IRC network.

Do not confuse this directive with the server_timeout directive.

server_timeout directive

Syntax:	server_timeout value in seconds
Default:	300 seconds
Context:	Global
Example:	server_timeout 180

The server_timeout directive specifies the amount of time MetalServe should wait when a server connection appears to stall. If no activity occurs on the connection and the specified time in seconds has passed, the connection is assumed to have died and will be closed.

Usually IRC servers periodically send PINGs to IRC clients to determine whether clients are still alive. MetalServe responds to these requests properly with a PONG. If no PINGs arrive, however, the configured server_timeout will become effective.

Do not confuse this directive with the server_connect_timeout directive.

serverroot directive

Syntax:	serverroot directory
Default:	none
Context:	Global
Example:	serverroot /space/music

The serverroot directive specifies the root directory containing the files to be included in the file list and to be served by MetalServe.

All files within this directory and its subdirectories will be scanned by makelist and offered by metalserved, unless further restrictions are made with the include_extensions directive.

A serverroot directive must appear in the configuration file.

visible_address directive

Syntax:	visible_address hostname or IP address or visible_address interface interface or visible_address default
Default:	Use hostname from gethostname() call
Context:	Global
Example:	visible_address foo.bar.org or visible_address interface ppp0

The visible_address directive specifies the IP address or hostname that should be sent to the IRC servers and clients. The determined address must be externally reachable or you can give up the idea of serving files at all.

By default, or if the special keyword default is specified, MetalServe will take the system's configured hostname as returned by the gethostname() call. This name is usually set at boot time with a call of the hostname command.

You can override this behaviour by specifying a hostname or an IP address. If the latter is specified, MetalServe will try to lookup the first associated hostname and only use the IP address if the lookup fails.

Alternatively you may specify the special keyword interface followed by the name of a network interface. MetalServe will then determine the interface's current IP address whenever a server connection attempt is made (and use that address for subsequent client connections). This setup is especially suited for users with Internet connections with dynamic IP addresses.