OpenNap Reference Manual

Version 0.43

Table of Contents


Napster is a distributed file sharing service which allows users to transfer files directly between their clients. A centralized server keeps track of all available files and provides clients the ability to search the index of available files. In addition, instant messages (private chat) and group chat services similar to IRC are also provided.

OpenNap is an Open Source effort to create a version of the proprietary Napster server.

The most current version of this document can be obtained here.


Unix Platforms

After you have unpacked the source, or obtained the CVS version, run the provided configure script. The following options are of note: Once you have run the configure script, simply type make. At this point you may wish to run make install to install OpenNap in the default location, but this is not required for the server to run.

Win32 Platforms


OpenNap uses several different configuration files. Typically they are stored in /usr/local/share/opennap for UNIX platforms, and C:\opennap for Win32 platforms.


The bans file contains a persistent list of server-wide bans. The server will read this upon startup, and then dump its current list when it shuts down. If you need to edit this file, you must shut down the server prior to editing it, or your changes will be lost.

Each line in this file should be of the form:

	<target> <nick> <when> "<reason>" [timeout]
where target is what is banned, nick is the user that issued the ban, when is the time at which the ban was set (in seconds since Jan 1, 1970 0:00 UTC), and reason is the reason for the ban.

Optionally, timeout may be specified which gives the time at which the ban expires and should be removed.


This file contains a list of regular expressions, one per line, which are matched against every file that a client attempts to share. If a file matches any of the regular expressions, it will not be indexed by the server. No error message is sent back to the client, and no log message will be printed. The file is just silently ignored.

Lines that begin with a hash (#) are considered to be a comment, and are ignored.

See the sample.block file as a basis to start your own configuration.


Configuration directives are one per line, of the form:

var value

Each of the values is a string, integer, or list, depending on the variable.

Type: boolean
Default: yes

Controls whether or not clients are allowed to share files via the server.

Type: boolean
Default: off

When set to on, opennap will automatically attempt to link to all servers listed in the servers file when it starts up for the first time.

Type: boolean
Default: off

When set to on, the server will automatically register a nickname the first time it is used. When off, nicknames will only be registered when the client explicitly requests it. Also see registered_only, register_interval.

Type: integer
Default: 102400

Sets the maximum number of bytes that can be queued for a client connection. If this threshold is reached, it is assumed that the client is either dead, or the network link can not sustain the level of output, and the server automatically closes down the client connection. This is necessary so that dead clients don't consume all of the servers memory.

Type: integer
Default: 1

The zlib compression level to use when compressing server to server connections. 0 means no compression, 1 is least effort, 9 is best compression. The higher the number, the more cpu it will consume. Level 1 compresses text by about 50%, which is good enough for most applications.

Type: integer
Default: 120

Specifies the number of seconds after initial login to the server for which the client is exempt from being killed for not sharing enough when the server is full (see eject_limit). This should be large enough to allow a client to start sharing files before getting killed.

Type: integer
Default: 0

When eject_when_full is set, only consider clients sharing less that this number of files. By default, only clients not sharing any files will ejected, but you can use this option to also eject clients which are sharing only a few files.

Type: boolean
Default: off

If set to on, the server will disconnect the longest connected client which is not sharing any files when the server is full (eg., when it has reached max_connections clients). This allows room to be made for those clients which are sharing files. Also see eject_limit.

Note: mods+ are exempt and can always log in even if they are sharing no files. file_count_threshold
Type: integer
Default: 5000

When a indexed file search token (one word) contains more than this number of matching files, the server will warn in its log output. This gives the ability to add this term to the list of filtered words.

Type: integer
Default: 0

This variable, along with flood_time, allow for server-side flood protection. When set to a value greater than zero, the server will not allow clients to issue more than this number of commands in flood_time seconds. Any client attempting to send commands faster than the allowed limit is throttled back.

Type: integer
Default: 100

See flood_commands.

Type: boolean
Default: on

When enabled, opennap will automatically kill an existing connection if the same user logs in from the same IP address.


Type: boolean
Default: true

Controls whether or not the filename extensions of shared files are included in the searchable index.

Also see index_path_depth.

Type: integer
Default: 2

Controls how many levels of directory are included when adding shared files to the searchable index. Often times the leading parts of the path are completely useless for searching (eg., C:\Program Files\My Music\Rock\) and just consumes a lot of memory. This variable counts from the end of the path backwards, so the higher the value, the more of the beginning of the path it will include.

Also see index_ignore_suffix.

Type: boolean
Default: on

When set, opennap requires all channel names to begin with # or &.

Type: string

By default, the server will listen on all interfaces on the system. You can force it to listen only on a single interface by specifying the ip address of the interface in this option.

Type: boolean
Default: off

When set to on, opennap will log changes in user levels to a file.

Type: integer
Default: 0

Specifies how often (in seconds) clients from the same IP address are allowed to connect to the server. This allows you to ignore clients which are reconnecting too fast. A value of 0 disables the check. Also see register_interval.

Type: integer
Default: 60

If a client has not completed the login process after this number of seconds, it will be disconnected. This is to prevent malicious parties from trying to open up many sockets to the server.

Type: integer
Default: 500

Because of the limit imposed by client_queue_length, the number of files returned by a browse command is limited to this number. If this is too large, clients will be disconnected when they browse a user with many files.

Type: integer
Default: 32

Specifies the max number of characters allowed in a channel name.

Type: integer
Default: 32

Specifies the max number of characters allowed in the client version string.

Type: integer
Default: 0

When set to a value greater than 0, the server will only allow this many connections from the same ip address. Also see login_interval.

Type: integer
Default: 2048

When set to a value greater than 0, the server will disconnect any client that sends a command longer than this value. Clients that trigger this are either attempting to flood the server or are out of sync.

Type: integer
Default: 0

When set to a value greater than 0, the server will only allow this many clients to log into the server.

Type: integer
Default: 32

When set to a value greater than 0, the server will only allow each user to have this many entries on their hotlist.

Type: integer
Default: 32

When set to a value greater than 0, this server will only allow each user to have this many entries on their ignore list.

Type: integer
Default: 19

If set to a value greater than 0, this specifies the max number of characters allowed in a nickname.

Type: integer
Default: 64

If set to a value greater than 0, this specifies the max number of characters allowed in the "reason" strings for such commands as ban, kick and kill.

Type: integer
Default: 100

If set to a value greater than 0, this specifies the max number of search results that are returned to a client.

Type: integer
Default: 3

Specifies the maximum number of pending searches a user is allowed to have. Once this threshold is reached, no more searches can be issued until one of the others has completed.

Type: integer
Default: 5000

If set to a value greater than 0, this specifies the max number of files that any client may share.

Type: integer
Default: 90

Specifies the maximum number of seconds of difference in clock time between two servers in order for them to be able to link. Note that if this value is set too large, users can gain ops in channels even if they were not the first user to join the channel.

A value of 0 will turn off this check completely.

Type: integer
Default: 64

If set to a value greater than 0, this specifies the max number of characters allowed in a channel topic.

Type: integer
Default: 5

If set to a value greater than 0, this specifies the max number of channels a user is allowed to join.

Type: integer
Default: 2678400 (31 days)

Specifies the time in seconds of after which unused accounts are expired and returned to the pool of available nicknames.

Type: integer
Default: 600

Specifies the interval (in seconds) of how often to sping peer (linked) servers.

Type: integer
Default: 0

Specifices how often (in seconds) clients from the same IP address are allowed to register new nicknames. This can be used in conjunction with auto_register to block web/clone clients which attempt to log in with random nicknames.

Type: boolean
Default: off

When set to on, the server only allows logins from registered clients. Also see auto_register, register_interval.

Type: boolean
Default: on

This variable controls whether or not the server supports remote browsing (where the client being browsed is not on the same server). In large networks, remote browsing can account for significant cross server traffic, increasing lag. Napster BETA 8 adds support for clients to directly browse eachother outside of the servers, which is the recommended approach.

Type: string
Default: value of server_name

Sets the IP address this server listens on to be reported to Napigator

Type: string
Default: value of server_name

Sets the name of the server reported to Napigator

Type: string
Default: value of server_ports

Sets the TCP port this server listens on to be reported to Napigator

Type: boolean
Default: off

If set, disallow the automatic registration of new nicknames by clients as they log in for the first time. The only way to create new nicknames (accounts) is then to use the administrator commands to register, or by editing the users file directly (when the server is not running). This option is typically used with the registered_only option to run a private, access-controlled server where users need accounts before they can log in.

Type: integer
Default: 180

When servers are linked, searches will be timed out if no response has been received after this many seconds. This forces the server to send the final ack to the client.

Type: string
Default: none

Allows you to specify an alternate name by which the server refers to itself. This is useful for connecting a "hidden" hub (routing-only) server, or if you just want to use a shortcut for the full dns name.

Type: string
Default: depends on hostname

Specifies the server's DNS name.

Default: 8888
Type: list

This option specifies a list of TCP ports which the server should listen on for client connections. Each port number should be separated by whitespace.

Type: integer
Default: 1024000

Specifies the maximum number of bytes that can be queued for a server connection before it is considered dead.

Type: integer
Default: 60

Specifies how often (in seconds) the server should send updates about server statistics (users/files/gigs) to the clients.

Type: integer
Default: 8889

Specifies the TCP port on which the server should listen to reports stats. Typically used by Napigator. If this port is set to -1, the server will not listen for stats reporting at all.

Type: string

Sets the DNS/IP address of the Napigator server to report stats.

Also see report_name, report_ip, report_port, stat_server_port, stat_server_user, stat_server_pass.

Type: string
Default: none

Sets the password for your napigator account to list live server stats.

Type: string
Default: none

Sets the username for your napigator account to list live server stats.

Type: boolean
Default: off

When set to on, the server will only allow privileged users to create new channels.

Type: integer
Default: 1800

Specifies the interval in seconds of how often the server should write out its database files to disk. This is important in case the server crashes prematurely, so that data loss is minimal.

Type: string
Default: ALL

Sets the default usermode for mods+ users.

Type: integer
Default: 30

If the clock on a remote server is more than this many seconds out of sync, opennap will print a warning message. Also see max_time_delta.

A value of 0 turns off the warning completely.

Type: integer
Default: 300

Specifies the number of seconds after a user logs out that information on the client's ip address and server is kept in cache, so that mods+ may perform a whowas command. Note: this only controls how often the cache is purged, so some nicks may appear to be older than this amount.

UNIX Specific Configuration Options

Type: integer
Default: depends on OS

Sets the maximum number of file descriptors available to the server process. Generally this is used to increase the default number availble. Note that in order to increase the default maximum, the server needs to be run as root (OpenNap will drop privileges and run as the uid/gid specified by the configure arguments).

Type: boolean
Default: off

On supported systems, this will cause the server to lock all of its memory pages into real memory, thus avoiding swapping to disk.

Type: integer
Default: varies depending on OS

Sets the maximum amount of memory the process may consume. Also see max_rss_size.

Type: integer
Default: varies depending on OS

Sets the maxiumum amount of real memory a process is allowed to consume. Any excess will be swapped to disk. Also see max_data_size.


The channels file specifies all predefined channels on the server. Each line in this file should be of the form:
	<channel> <limit> <level> "<topic>"
where channel is the channel name, limit is the maximum number of users allowed in the channel (0 for no limit), level is the minimum user level required to enter the channel and topic is the default topic for the channel.

NOTE: typically you edit this file once before starting your server. You should never edit it while the server is running or your changes will be lost. The server always writes out its state when it shuts down, because new information about the channel may have been set. If you want to edit it by hand, you should first shut down your server.


This file allows you specify a list of words that should not be indexed when clients share files. This is most commonly used to weed out very common words such as `mp3' or `the' to save on server resources, since it is expected that none of these words will be very useful when searching. Note that the file is still indexed, you just can't use these particular words to find that file.

In certain cases, a file may contain no valid words and thus won't be able to be found via the search mechanism. However, the file will show up when browsing the client's filelist, and therefore can still be downloaded.


The servers file contains a list of servers which are allowed to link. Each line in this file is of the form:
	<server_name> <remote_pass> <local_pass> <port> [alias]
where server_name is the DNS name of the remote server (the remote server should have its server_name set to this value), remote_pass is the password expected from the remote server to authenticate (prove its identity), and local_pass is the password your server uses to authenticate to the remote server.

port is the TCP port on the server to connect to.

alias is an optional string which will be used to refer to this server instead of its DNS name. This is useful for defining hub servers where you might not want the DNS name to be revealed to users, or you want to use a different name instead of the ip address (if you don't have a reverse DNS record).

Note: lines that begin with a pound sign (#) or any space character (tab, etc.) are ignored.


This section describes how to administer the OpenNap server through the use of a connected client. It is assumed by the time you get here that you have set up at least one Elite level (server owner) account on your server (this is done by the setup program if you installed it that way). The first thing you want to do is log into your server with this account. When you log in, you should see a message from the server on your client, something like:
	server_name set you to level Elite (4).
where server_name is the name of your server. This message will let you know that you have fill privilege to access administrative commands on this server.

Clients such as TekNap already have all of the OpenNap extensions built into it. Others, such as the official Napster client do not (it was not inteded to be used by administrators). If you client is missing functions to directly access these administration commands, not to worry, OpenNap has a way of getting around this. OpenNap provides to pseudo-users, ChanServ for channel related commands, and OperServ for server related commands. For both of these, you can access their functionality by sending a privmsg (instant) message to either of these users (in most clients this will be either /msg user or /tell user).


You can administer chat channels either by using your client's built in functions, or by sending private (instant) messages to the user ChanServ. Note that most all of the following that actually affect the channel require the user issuing the command to be a channel operator.


/msg chanserv ban #channel nick ["reason"]

Places a ban on channel such that nick is prevented from joining. You can optionally give a reason for the ban that will be displayed to the user (Note: if you specify the reason, it MUST be quoted with double-quotes (") or else the server will only show the first word of the reason).


/msg chanserv banclear #channel

Removes all bans from the channel.


/msg chanserv banlist #channel

Displays the list of bans for the channel. Note: this does not work for the official Windows Napster client since it doesn't have support for displaying it.


/msg chanserv clear #channel

Kicks all users in the channel out of the channel, only leaving yourself.


/msg chanserv deop #channel nick

Removes user nick as a channel operator and makes him/her a normal channel user.


/msg chanserv help

Displays a summary of all available commands.


/msg chanserv invite #channel nick

Send an invitation to user nick allowing them to join a channel which is set +INVITE.


/msg chanserv kick #channel nick ["reason"]

Kick user nick out of the channel. A reason can optionally be given. Note: if reason is given, it MUST be quoted with double-quotes (") or else the server will only display the first word.


/msg chanserv level #channel [level]

Displays/sets the minimum required user level to be allowed to join a channel.


/msg chanserv limit #channel [numusers]

Displays/sets the maximum number of users allowed to join a channel.


/msg chanserv mode #channel [mode [mode ...]]

Displays/sets the channel mode. If no modes are given, it returns what the current channel mode is. Acceptable modes are:

To set a channel mode, prefix it with a plus-sign (+). To unset a channel mode, prefix it with a minus-sign (-). You can specify however many different modes on the same command as you like.


/msg chanserv muzzle #channel nick

Prevent user nick from being able to send messages to the channel.


/msg chanserv op #channel [nick [nick ...]]

If no nicknames are given, it returns a list of the current channel operators. If given one or more nicknames, each user will be given channel operator status (and thus the ability to execute any of the other channel admin commands).


/msg chanserv topic #channel [topic]

Display/set the channel topic.


/msg chanserv unban #channel nick

Remove channel ban against nick, allowing him/her to join the channel again.


/msg chanserv unmuzzle #channel nick

Allow a previously muzzled user to send messages to the channel.


/msg chanserv unvoice #channel nick

Remove the ability to speak in a +MODERATED channel.


/msg chanserv voice #channel nick

Give the ability for a user to speak in a +MODERATED channel


/msg chanserv wallop #channel text

Send a message to all channel operators on the channel (that is not seen by other users in the channel).


NickServ is a pseudo-user which provides access to registered user accounts. You can /msg (or /tell) it with the following commands.


/msg nickserv ghost user password

This command allows you to kill a ghost which is holding your nickame so that you can log in again. user is the nick which is ghosting, and password is the password for that account.


/msg nickserv register password

Allows a user to register a nickname that has not been previously registered, such that no other user may use the nickname without the corresponding password.


/msg nickserv usermode [flags]

See usermode.


OperServ is a pseudo-user which allows mods+ level users to execute server administration command. This is primarily intended for those clients which do not have built in support for these commands, but there is no restriction on its use.


/msg operserv cloak

Toggles invisibility to normal users. When cloaked, normal users do not see your real nickname when you perform actions such as kill, ban, etc. Instead, it will display Operator. Other mods+ users still see the real nickname.


/msg operserv config var [value]

Display/set a server configuration variable. When value is missing, OpenNap displays the value of var. If value is specified, it sets the configuration variable.


/msg operserv connect server [remote_server]

Links the server running on server. If remote_server is specified, it tries to make a connection from remote_server to server instead of from the local server.


/msg operserv connect server

De-links a server from the cluster.


/msg operserv killserver server

Causes the specified server to shut down (terminates the OpenNap process).


/msg operserv links

Display a list of all linked servers.


/msg operserv reconfig var

Resets the configuration variable var to its default value.


/msg operserv rehash [server]

Causes the server to reload its configuration files.


/msg operserv server nick

Displays which server a particular user is logged in through.


/msg operserv stats server

Displays stats about the server (uptime, bytes send/recv'd, etc).


/msg operserv usermode [mode [mode ...]]

Toggles the various server messages. Each message the server sends to mods+ is given a type so that if you don't want to see a particular type of message, you can simply turn it off and still see the other messages.

To stop messages of a particular type, simply prefix the mode with a minus-sign (-). If you wish to only see a particular subset of messages, specify the ones you want with no prefix. You can also use the keyword ALL in conjunction with -<MODE> if you want "all but..."


/msg operserv whowas nick

Displays information about a user that has recently logged out. Information is kept cached for who_was_time seconds.

Getting Help

If after reading this manual thoroughly you are not able to get something working, there are a number of options available for getting help.

Web Forums

IRC Chat

You can chat in realtime with other people involved in the OpenNap project on the following channels.

Mailing Lists



An admin is a special user level which allows you to execute all of the moderator functions, plus the following:

Channel Operator

A channel operator, also known as a chanop or just op, is a user that is allowed to administer a chat channel. See ChanServ for a list of available commands. Channel operators have no special privileges outside of the channel they are opped in.

Channel operator status is given either when a user is the first user to join a chat channel, or another channel operator makes a user a channel operator using the op command. All channel operators are equivalent, meaning that if you op a user, they can immediately deop you (remove your channel operator privilege).

Note that being a channel operator is not a user level. Most channel operators are only normal users.


An elite user is generally a server owner (the person who actually runs the OpenNap software on their computer). They can basically do whatever they want. Don't step on their toes, these are the people providing you the service!


A ghost is when a client gets disconnected from the server but the server doesn't realize it so it thinks you are still logged in. When this happens, the server will kill your ghost if you come back from the same ip address. However, if you are using a dialup this will likely not be the case. You can use the ghost command via NickServ to kill your ghost.


Leech is a term for someone who is a freeloader. This user level is given to those users which are misbehaving in some way. When you are leeched, you can not do the following things:


A moderator, or "mod" for short, has the ability to execute some of the administrative functions on the server. A moderator can: In addition, moderators have the ability to execute all ChanServ functions to adminster chat channels.


All users which have level of Moderator or higher.


Message Of The Day. This is the text the server sends to your client when you first log in.

(Server) Split

Term used to describe when two linked servers become disconnected from one another (you can generally tell when this happens because if you are in a chat channel you will see a bunch of users leave at the same time).


A term meaning server ping, or how long it takes a server to see your data and respond.


A user is a plain-old-joe. This is what the vast majority of users are. It gives you access to create channels and chat.

(User) Level

Each user on a OpenNap server has a level associated with them that tells the server which commands it may execute. When you first log into a server, you start out at level User. In addition, the following user levels are also defined:
Last updated September 22, 2001.