Logo

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

allowed_clients

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

always_stream

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.

binding_host

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

directory_format

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.

enable_browsing

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.

errorlog

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.

file_format

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.

hostname

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.

logfile

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.

maximum_connections

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.

mime_file

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.

play_all_text

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

play_recursively_text

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

plugin_directory

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

port

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

recursive_randomize

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

read_time

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

root

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.

shoutcast_streaming

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

song_format

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

sort_order

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.

stats_program

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.

stats_arguments

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.

theme

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

theme_directory

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

truncate_log_files

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.

use_client_host

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.

user

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.