The Configuration File

Where is it?

GNUMP3d is configured exclusively through the use of a configuration file.

By default GNUMP3d will read the system-wide configuration file "/etc/gnump3d/gnump3d.conf" however it will read the file "~/.gnump3drc" in preference to the system wide file if it exists.

If you wish to use a different configuration file then you may specify one with the command line option "--config fileName".

What can I configure?

Each of the configuration file options of the current version are listed below, alphabetically, along with an brief explaination of what they mean.

More detailed information is included within the configuration file itself, as this is extensively commented.

Please note that only the 'user', 'root', and 'port' are strictly necessary - the rest of the values can probably be left as-is, unless you have a special requirement..


This value allows you to set client IP addresses which are always allowed to connect to your server. This is the logical counterpart to 'denied_clients'.


When the server builds up links to files there are two ways they can be formed, a straight link to the file, or a link to a playlist containing that file.

The two are subtly different. When a playlist is formed, via 'always_stream=1' the song may begin playing immediately, without this the file will typically be downloaded in its entirity to the client and then played.

It is recommended this option is enabled for most cases.


If your machine has multiple ethernet interfaces then this setting will allow you to control which interface the server listens upon.


This is a format string which is documented within the configuration file itself; it allows you to specify a template which will be used in the output file for each directory name which is found.


This value allows you to disable browsing your servers GUI interface. This would be ideal if you just wished your clients to be restricted to random playing of songs.


The name of the file to write all error messages to. When the server is ran in debug mode (with '\-\-debug' specified upon the command line) this file is not used, instead the output is sent to the console.


This is a format string which is documented within the configuration file itself; it allows you to specify a template which will be used to generate the output for each file which is found.


The hostname setting allows you to control the hostname which is used in all the generated links within the GUI. It may be useful if the server has multiple DNS names.


The name of the file to write all accesses to. The logfile is written in the Apache common logfile format so it may be analysed by common tools, including the gnump3d-top script.


This gives the maximum number of simultaneous connections which the server will handle. Any additional connections will be served a simple error page and denied access.


As part of it's role the server is a fully featured HTTP server, which is capable of serving, or streaming, audio and video files. To set the type of file correctly when serving it a registry is used.

The mime.types file is that registry, and this setting should be used to point to the file you're using.


This setting contains the text which is displayed for the 'play all' links.


This setting controls the text which is displayed for the recursive playlist links.


When the server is installed upon your system a collection of plugins are also installed, as some of these represent core features of the server.

This setting allows you to tell the server where these plugins are located upon your system. (This should be set by the installation script in versions 2.3 or higher).


The port upon which the server listens, this may be any port which is not already in use upon your machine.


This option controls whether recursive playlists are randomized, or sent in filename order.


This setting controls how long the server should listen for a request from incoming clients. The default of 10 seconds should be sufficient.


The root directory where the media content is served from. This should be the directory containing the MP3/OGG/Movie files which you wish to share.

Note that if your server is running under an assumed userid, (see the 'user'configuration value), then that user must have permission to read the files in the root directory.


If this setting is enabled then shoutcast meta data will be mixed in with any songs which are streamed.


This is another template string which is used to control what information is displayed for audio files, (for example the name of the song, or the name and artist of a song).

Much more details may be found in the configuration file itself, along with a few examples..


This setting allows you to control the order in which songs are listed upon the index pages. This is especially useful within directories which contain a large number of files.


This option allows you to specify the path to the companion program gnump3d-top

When the server is asked to display the most popular directories, songs, users, etc, it actually invokes this script which presents the output for you.


This option allows you to specify additional options to pass to the gnump3d-top program when it is invoked by the server.

See the man page for gnump3d-top for more details of supported options.


The servers appearance may be changed by use of a collection of template files, these are known as themes. This option allows you to specify which theme is presented by default. (Clients may choose their own theme via the preferences user interface).


The directory where the themes exist may be specified here, if you're installing the software in an unusual configuration.


When the server starts it normally appends all new logging information to the existing logfiles which might be present. With this setting you may force the server to truncate the files first.


This setting controls whether the client's 'Host:' header will be used, if it is sent. This can be useful if you're performing SSH tunelling operations, or working on a server with more than one hostname.


If there is a user value specified then the server will become that user, after creating the listening socket. This is important for security reasons.

However please ensure that the user the server becomes once starting has read and execute permissions for the directory containing your music archive, and write permissions for the logfiles you choose.