cleannap Reference Manual

Table of Contents


cleannap is a cross platform Napster protocol server that is designed to be fast, efficient, and easy to code for. Unlike OpenNap, cleannap uses server modules to make it easy for anyone to add features such as keeping statistics, blocking files, or linking with other servers. It is coded in C++ and will eventually have GUI components that make server configuration, monitoring, and administration much easier. Although it is still in Alpha at the moment, most of the code is actually done. Several key features along code optimization and security features have yet to be added. The GUI components are still in the planning stages and will be released once the server code is in its beta stage.

This manual is a work in progress.  It is nowhere near complete and will be added on to as things happen.  Currently, the setup process may be a bit difficult for non-developers, but eventually an installation program will be provided with cleannap that will make things much easier.


Windows Systems (from binaries)

First, create a directory for cleannap to reside in (eg. "C:\cleannap\"). Since the program has already been compiled, simply extract all of the files in the archive to that directory.

Windows Systems (from source)

To compile cleannap from the source code under Windows, use the MSVC++ projected files packaged with this release to compile the program. Create a directory for cleannap (eg. "C:\cleannap\"), and copy all of the following files into that directory: cleannap.exe, *.dll, bans, channels, config, modules, motd, users. These will all be located in the root directory of the cleannap source after it is built.

Linux Systems (from RPM)

To install cleannap from a binary RPM, move to the directory where you downloaded the .rpm file. Then type the following command at the command prompt:

      rpm -ivh cleannap-0.1.6-1.rpm

This will install cleannap into the directory /usr/local/cleannap/. It can be easily moved from here if you like with no changes to any files. Just be sure to keep all the files together.

Linux Systems (from source)

To compile and install cleannap from the source code in Linux, follow these instructions:
  1. Untar the source archive into a empty directory of your choice. The command to do this is usually:

          tar -zxvf cleannap-0.1.6.tar.gz

  2. Compile the sourse using the following command at the command prompt:


  3. Use the following command at the command prompt to install cleannap to "/usr/local/cleannap":

          make install
Alternatively, you can move the following files to a directory of your choice for the same effect: cleannap, *.so, bans, channels, config, modules, motd, and users.

Other Systems

cleannap was designed to run on both POSIX Linux systems and 32-bit windows systems.  At this point in development, those are the only systems it has been tested on.  There is a good chance it will work on all POSIX Unix systems, but anything beyond that may require some tweaking to get it to work.  As cleannap progresses in its testing stages, it will be setup to be compatible with more systems.


cleannap comes with several configuration files: config, bans, channels, modules, motd, and users.  All of these files are optional except the users file.  All of the files can be left as they are provided in the distribution, but it would be a good idea to customize the config file so the settings fit your server's application.  Below is a description of each of the configuration files and how to use them.

config file

The config file contains various settings that control cleannap's operation.  Settings are contained in key-value pairs.  If any settings are omitted, default values will be supplied.  If the config file doesn't exist, default values will be supplied for all of the settings.  Below is a list of all the settings in the config file:

max_connections: the maximum number of users that can be connected to the server simultaneously.  On Linux systems, this should not be higher than the system's hard connection limit (can be determined by reading the /proc/sys/fs/file-max file).  Default setting is 1024.

server_name: the official name of the server.  This will be presented to the user on login, but has little practical use.

server_port: the port number which users will connect to and on which the server will listen for new connections.  In general this is set to 8888, but can be set to any other port greater than 1024.  Default setting is 8888.

registered_only: If the value is 1, users must be registered (in the users database) or they cannot login.  It also means that users cannot register their own accounts.  If the value is 0, users may register their own accounts.  Default setting is 0.

auto_register: If the value is 1, when a user logs in without an account on will be automatically created for him.  If the value is 0, users must explicity request an account before it will be created.  Default value is 1.  This setting is ignored if registered_only is 1.

max_username: User names may not be any longer than this.  Default setting is 20.

max_join: The maximum number of channels a user may be a member of at any one time.  Default value is 5.

max_hotlist: The maximum number of hotlist entries a user may have in his hotlist.  Default setting is 30.

max_ignore: The maximum number of entries a user may have in his "ignored users" list.  Default setting is 30.

max_share: The maximum number of files a user may share.  Set this to 0 if you want to disable file sharing.  Default is 5000.

max_browse: The maximum number of files a user will recieve from a browse request.  Reducing this valid reduces server bandwidth, and can speed things up.  Default is 5000 (same as max_share).

max_search: The maximum number of search results that will be returned from a file search.  Default value is 500.

max_queued: The maximum number of bytes a user may have in his outgoing message queue.  If the user's message queue goes beyond this limit (usually up to 200*max_browse).  Higher values can cause higher memory usage when there are "ghosted" users (disconnected, but not known by the server to be), but generally has no effect.  Default value is 1024000.

stat_click: The amount of time (in seconds) at which all connected clients should be sent stats updates (number of users, files shared, etc).  Increasing the number will increase performance, but will make stats less accurate.

max_lag: Maximum amount of time the server should wait before processing high priority (latency-sensitive) messages in milliseconds. All messages except ones that take a long time or consume resources are considered "high priority". Sharing/unsharing files, searching, and browsing are considered "low priority". This lower this value is set, the lower the latency to the users for most commands. However, lowering this number can also dramatically increase CPU load and make low priority messages take much longer to process. Default value: 100.

hammer_time: If a user attempts to reconnect to the server after recently attempting to reconnect in this amount of time (in seconds), the user will be temporarily blocked from connecting. This is useful for preventing users from "hammering" the server by repeatedly disconnecting and reconnecting to the server (consuming resources). See hammer_count below. Default value: 180.

hammer_count: Number of reconnects a reconnecting user is allowed before he is considered "hammering". See above.

bans database

The bans file contains a list of all users who are currently banned from the server.  Lines that begin with the # character are considered comments and are ignored.  Each of the entries in this file are in the following format:

<username> <banner> <ban time> ["<reason>"]

<username> is the nick of the banned user, <banner> is the nick of the mod who set the ban, <ban time> is a Unix timestamp (in seconds) for when the ban was set, and <reason> is an optional reason for why the ban was set.

channels database

The channels file contains a list of all chat channels registered on the server.  Lines beginning with the : character are considered comments and are ignored.  Entries in this database should be in the following format:

<channel name> "<current topic>"

<channel name> is the name of the channel (usually starting with the # character.  The <current topic> field is the current topic of the channel.

modules database

The modules file contains a list of server modules that the server should load on startup.  See the Server Modules for more details on server modules.  Lines beginning with the # character are considered comments and are ignored.  Each entry in this file is in the following format:

<module name> "<module filename>"

<module name> is the name of the module, which is used to identify the module.  This value may be anything you like.  The <module filename> field is the path the actual module.  If the file is in the same directory as cleannap, no path information is required.  On Windows machines, modules will have a .dll extension.  On Linux machines, they will have a .so extension.

motd file

This file contains a text message called the Message of the Day which is displayed to users when they login.  Lines that start with the # character are considered comments and are ignored.  This is a good place to post the list of moderators, and rules you may have on your server.

users database

The users file contains a list of all registered users on the server.  Lines that begin with the # character are considered comments and are ignored.  Each entry is in the following format:

<username> <password> <userlevel> <time registered> <last seen>

<username> is the nick of the user, <password> is the user's password, <userlevel> is the user's permission level, <time registered> is a Unix timestamp (in seconds) for when the user registered, and <last seen> is a Unix timestamp (in seconds) for when the user last logged into the server.  The <password> is encrypted using standard MD5 encryption.  The <userlevel> is a number between 0 and 4.  Each value represents one of the following user levels:

0:   Leech
1:   User
2:   Moderator
3:   Admin
4:   Elite

The Leech level (0) is designated to users that are somehow abusive.  They can be kicked from channels by anyone.  The User level (1) is the standard level given to ordinary users.  Users with the Moderator (2) level can perform any type of channel administration, and a limited amount of server level administration operations such as banning and kicking users.  Users with the Admin level (3), can do almost everything except change configuation variables, and a few other highly privileged operations.  Users with the Elite level (4) are generally server operators and have full permissions.

Getting Started

Once you have installed and configured cleannap, there is just one thing left to do.  Start the server by typing "./cleannap" at the command prompt (or double-click on the executable on Windows systems).  Using your favorite Napster client, log in to the server with the username "Admin" and the password "password."  Using the 10200 command (format for this command is: ), register an account for yourself.  Log out of the "Admin" account, and log in with your new account.  For security, it would be a good idea to delete (nuke) the "Admin" account.  Study the administrative commands in the Napster protocol and in your Napster client.  Eventually, an program will be included with cleannap that will help set things up automatically.

If you want to run cleannap on a remote system and want to be able to logout after stating it, a good way to do it is using the following command:

      nohup ./cleannap >/dev/null &

Server Modules

cleannap comes with the ability to load server modules at load time that can do anything from adding file filtering to keeping real time stats posted on the web.  Whenever a message is received by the server from a user, it is first sent to all registered modules.  The module can then do anything with that data that it wants to.  Modules can send messages back to the server (as if it were the user sending them.  Once the module is finished processing the message, it can either allow the message to be further processed by the server or discard it.  A complete guide to cleannap server modules will be available on the cleannap soon with directions on how to create your own.

Napster Protocol

cleannap operates on an extension of the Napster protocol used in the OpenNap Napster protocol server.  A very full description of this protocol can be found packaged with this software in the "napster.txt" file, or can be downloaded at  The original Napster protocol was never published, but much of it has been reverse-engineered by DrScholl of OpenNap and others.