2 the open source (TM) napster server
3 ===================================
6 http://opennap.sourceforge.net
8 Email: opennap-dev@lists.sourceforge.net
10 opennap is an Open Source(TM) server implementation of the popular
11 Napster protocol. It is written in ANSI C and was designed to run on Unix
12 platforms. So far this server has been tested on:
13 * Linux (i386, alpha, sparc, ppc)
19 * Windows 95/98/NT/2000 (MS VC++, CYGWIN)
20 Minimal porting should be required for compilation on other Unix variants
21 (if you do a port, please send patches to drscholl@users.sourceforge.net)
23 Since Napster is not an open specification, much of the internals of the
24 servers are specific to this implementation. In particular, I don't expect
25 that this server will interoperate with the official Napster servers once they
26 are linked together. Given that I can't run tcpdump between those servers,
27 I can't see how they are communicating. I'm hoping that with the proliferation
28 of servers outside of napster.com, they might be willing to open up their
29 specification to make sure all the clients can interoperate. However, this
30 server should be compliant with the several currently available Unix Napster
33 Main differences from the official napster servers:
34 * servers can be linked together fully (chat and search)
35 * channel operators can be defined to moderate specific channels
36 * source code is freely available
40 * metaserver for directing clients to server groups
41 * protocol specification
44 There is also a mailing list opennap-admin@lists.sourceforge.net for people
45 running live servers to share information not directly related to the
46 development of the server.
48 * For a description of the napster protocol, please see the file 'napster.txt'
49 included with this distribution.
53 To install, simply run the `setup' utility (provided with the binary
54 distributions, or built from source).
56 The installation process involves picking a directory where to install
57 OpenNap and creating an initial account for administering the server. By
58 default, OpenNap will look for its configuration files in:
60 C:\opennap Win32 platforms (Win 95/98/NT/2000)
64 /usr/local/share/opennap Unix platforms
66 If you wish to install OpenNap in another location, simply enter the new
67 directory when `setup' prompts you.
69 The next step is to create an initial user account for the owner of the
70 server. `setup' will prompt you for the nickname to use, the password for
71 the account and your email address (note that you ARE NOT required to
72 enter a real email address if you don't want to--simply use the default
73 email@here.com if you like)
75 IF you installed OpenNap in a different directory than the default,
76 `setup' will create a config file for you so that opennap knows that it
77 is installed in the directory you chose. However, in order for opennap to
78 find this config file, you will have to tell it where the config file is
79 when you start the server. You do this by specifyin the -c command line
84 where PATH is the _full_ path to the config file.
86 (NOTE: for Win32 users, `setup' will create a `launch.bat' script in the
87 directory you chose to install in which contains the above command so that
88 you can simply run the batch file to start the server. Just make sure you
89 copy the opennap.exe executable into that directory first).
93 1. you need to add the dns name of the server you wish to allow to connect
94 to your server in the database. This needs to be done on both
95 ends, as it does mutual authentication to prevent bogus servers from
98 edit /usr/local/share/opennap/servers (c:\opennap\servers on Win32)
100 <server name> <password> <local_password>
102 where <server name> is the dns name of the server, and <password>
103 is the password for that server to gain access. <local_password> is
104 the password your server uses to authenticate itself to the other
105 server (so the two password fields should be swapped on the
108 2. connect to your server and gain elite access, and execute the
109 `server connect' command (currently only BWap has support for
110 the opennap commands), specifying the host and port to connect to.
112 In BWap, you would do:
113 /admin connect <server>
114 In the windows client or other client which does not natively support
115 the opennap extensions, you can do:
116 /msg operserv connect <server>
118 * Server to Server messages
120 There are many cases where client commands need to be passed to peer servers
121 in order to maintain database consistency across all servers. However, most
122 of the commands that the clients use don't specify the user who performed
123 the action. This implementation borrows from the IRC protcol and prefixes
126 to indicate to peer servers which user issued the command. Commands which
127 already specify the user name, such as the login request (2), are not
128 prefixed. Each request handler should have a comment at the beginning
129 specifying what input it expects.
131 * Extensions to messages
137 OpenNap supports other media types besides mp3. By default,
138 searches will only match mp3 files. A client can however
139 search for other media types by specifying a
140 partial MIME content-type (audio, video, text, application,
141 image). (See message 10300 for adding media to the database).
142 The special keyword `any' will match any media type in the
145 The results of the search are returned as with mp3, except
146 the fields for bitrate, sample frequency and length are
147 meaningless (and are set to 0 in this implmentation). The
148 client can then download as they would any other mp3 file.
150 FILENAME EXCLUDES "..."
152 allows filtering search results by excluded all files which
153 match words in an exclude list. this must be used in
154 conjunction with FILENAME CONTAINS "...".
155 (NOTE: as of Napster 2.0 BETA 8, words in the
156 FILENAME CONTAINS string which are prefixed with a minus
157 sign (-) are considered to be exclusive. You are better
158 off implementing it this way for compatibility.)
160 [ SIZE | DURATION ] ["AT LEAST" | "EQUAL TO" | "AT BEST"] <integer>
162 allows matching on the file size and song length in addition
163 to the other file attributes
165 612 ban user/ip [CLIENT]
167 Format: <user|ip> [ "reason" [timeout] ]
169 opennap adds the optional `timeout' fields which specifies the time,
170 in seconds, that the ban should be enforced. Note that if `timeout'
171 is present, the `reason' field MUST be present, even if empty.
173 * Non-standard messages
175 The following messages are not present in the official napster servers, but
176 are implemented as additional functionality in the opennap server.
178 10000 client quit [SERVER]
182 the message is sent to peer servers when a client connection has
185 10010 server login [SERVER]
187 <server-name> <nonce> <compression>
189 <server-name> the dns name of the server wishing to connect
190 <nonce> a random string to use for authentication
191 <compression> the maximum zip (LZ77) compression level
193 this message is sent when a connection wishes to identify itself as
194 a peer server. when a server receives this message, it will send its
195 own login command to the peer to initial mutual authentication
197 10011 server login ack [SERVER]
201 to authenticate itself, the server will hash the value
202 <peer-nonce><nonce><server-pass>
203 using the MD5 algorithm. this allows the servers to mutually
204 authenticate without the plaintext passwords traversing the network
206 10012 request server link list [CLIENT]
210 client requests the current server link info
212 10013 user ip [SERVER] (deprecated, this info is now appended to msg 2)
214 <user> <ip> <port> <server>
216 this message is used for a server to pass the ip address of a
217 locally connected client to its peer servers, since that information
218 is not available in the login message. <ip> is an unsigned long
219 integer specifying the ip address for <user>
221 10014 registration info [SERVER]
223 <user> <pass> <level> <email> <created> <last-seen>
225 <pass> user's password
226 <level> user's default level
227 <email> user's email address
228 <created> time at which the account was created
229 <last-seen> last time the user logged into a server
231 When a server detects that the user table is out of sync between
232 servers, it will send its notion of what the entry should look like
233 to all the other servers. If a receiving server has a matching
234 user, it checks the <created> time to see which is the oldest
235 entry and updates accordingly.
237 10018 encapsulated message [SERVER]
239 :<sender> <recip> <message>
241 This command allows a server to send a private message to a user on
242 a remote server. <message> should be a well-formed Napster message,
243 complete with tag and length header.
245 10019 server link info [SERVER]
247 <server> <port> <server> <port> <hops>
249 This message is used by servers to share information about the
250 topology of the linked servers. when a server joins, a message is
251 sent to all other nodes in the cluster. <hops> is incremented each
252 time the message is relayed so that each server knows how far away
255 10020 server quit [SERVER]
257 :<server> <server> "<reason>"
259 This message is used to notify other servers in the group that a
260 server has delinked. The server with the peer connection to the
261 server that has quit should send this message.
263 10021 notify mods [SERVER]
265 :<server> <loglevel> "<message>"
267 allows a server to send a message to all logged in moderators.
268 primarily used to propogate ban messages when not all servers
269 see the connection or login.
271 10022 server to server pong [SERVER]
273 Format: :<server> <recip> [args]
275 This numeric is generated by a server in response to a 750 command
276 from another server. The 750 was originally intended for a client
277 to ping its local server, but doesn't contain enough information to
278 use it as a pong response when crossing a server link. [args] is
279 optionally copied from the [args] in the 750 message, typically used
280 to keep client state.
282 10023 time check [SERVER]
286 upon linking, servers should send their idea of the current local
287 time to the peer server in order to them to make sure they are not
290 10024 remote whois notification [SERVER]
292 Format: :<sender> <target>
294 This message is used to notify a remote client that a local client
295 has performed a whois request. Mods+ are notified when a client
296 does a whois request, and using a separate message allows the
297 recipient client to turn off the notifications if requested.
299 10100 server connect [CLIENT]
301 <server> [ <remote_server> ]
303 Attempts to link the current server to <server>. If
304 <remote_server> is given, then that server attempts to make the
305 link instead of the local server.
307 10101 server disconnect [CLIENT]
309 <server> <reason> [ "<remote-server>" ]
311 delink current server from <server>.
312 must be admin or high level to execute this command
314 10110 kill server [CLIENT]
318 cause the server to shutdown. must be elite level to execute
321 10111 remove server [CLIENT] (DEPRECATED, not currently used)
325 reqeusts that <server> be removed from the table of allowed links.
326 must be elite to execute this command
328 10112 show server links [CLIENT, SERVER]
331 server: <host> <host> <hops>
333 This command is used to show information about the links a
334 server has to other servers. The list is terminated by a 10112
335 message with no data (0 length).
337 10115 show server stats [CLIENT, SERVER]
340 server: <clients> <servers> <files> <gigs> <channels> <time>
341 <uptime> <memory> <numusers>
343 This command is used by administrators to get information about the
346 <clients> number of locally connected clients
347 <servers> number of locally connected servers
348 <users> total number of global users
349 <files> number of files in the db
350 <gigs> total size of all files shared
351 <channels> number of active channels
352 <time> time at which the server was started
353 <uptime> number of seconds of uptime
354 <memory> if debugging is enabled, this will show the memory
355 currently in use, otherwise it will be -1
356 <numusers> number of registered users
358 10116 server ping [DEPRECATED]
360 note: there is now a defined command for this in napster.txt
362 10117 rehash (reload) configuration files [CLIENT]
366 Causes [server] to reread its configuration file and reload the
367 motd into memory. If [server] is not specified, the server to which
368 the client is connected is affected.
370 10118 display client information statistics [CLIENT, SERVER]
372 If compiled with --enable-version-stats, the server will dump its
373 lists of known clients and the number of logins for each. It does
374 not keep track of unique ips, so this just gives a rough estimate
375 on the popularity of various clients.
377 Format (server): "<version>" <count>
379 The server's list is terminated by a 10118 message with a 0 length.
381 10119 display which server a user is on [CLIENT]
385 server will return an message detailing which server
386 the particular user is on. only mods+ can execute this command.
388 10120 ping all peer servers [CLIENT]
392 Causes a server to sping all of its peer servers and report the
395 10121 who was [CLIENT]
399 Displays info about a user that has recently logged out.
401 10122 mass kill by ip [CLIENT]
403 Format: <ip> ["reason"]
405 Disconnect all connections originating from <ip>
407 10123 server command histogram [CLIENT, SERVER]
410 Server: <numeric> <count> <bytes>
412 Displays a histogram of the number of commands and bytes received
413 for each supported protocol numeric.
415 10124 end server histogram [SERVER]
417 Format: <last_unknown> <unknown_count> <unknown_bytes> <total_count>
420 Terminates the list of 10123 messages.
422 10203 set user mode [CLIENT]
424 [-]{ALL,MUZZLE,BAN,KILL,PORT,WALLOP} [ ... ]
426 10204 set channel op [CLIENT]
428 Format: <channel> <user> [user ...]
430 enable <user> to kick/ban users on <channel>
432 10205 remove channel op [CLIENT]
434 Format: <channel> <user> [user ...]
436 remove <user> as operator on <channel>
438 10206 channel op list [CLIENT]
442 returns the list of defined channel operators for the given channel
444 10207 drop channel [CLIENT]
446 Format: <channel> [ "<reason>" ]
448 marks the specified channel as being user created such that its
449 state is not stored in the persistent channels file and will
450 disappear once all users part from it.
452 10208 send message to channel ops [CLIENT]
454 Format: <channel> <message>
456 sends <message> to all operators and mods+ on <channel>
458 10209 change channel mode [CLIENT, SERVER]
460 Format: <channel> [mode]
462 if specified, [mode] is of the form
466 where STRING is one of
468 PRIVATE - makes the channel not show up in the list
469 MODERATED - only ops and mods+ can speak in public
470 INVITE - channel is invite only
471 TOPIC - if set, any user may change the topic
473 10210 invite user to a channel [CLIENT, SERVER]
475 Format: <channel> <user>
477 when a channel is +INVITE, this sends an invitation to a user to
478 join the specified channel. the user issuing the invite must be
479 a member of the channel.
481 10211 give voice to speak in moderated channel [CLIENT]
483 Format: <channel> [user [user ...]]
485 10212 remove voice to speak in moderated channel [CLIENT]
487 Format: <channel> [user [user ...]]
489 10213 muzzle a user in a specific channel [CLIENT]
491 Format: <channel> <user> ["reason"]
493 10214 unmuzzle a user in specific channel [CLIENT]
495 Format: <channel> <user> ["reason"]
497 10300 share generic media file [CLIENT]
499 Format: "<filename>" <size> <md5> <major-content-type>
501 <content-type> is the major MIME type defined for what the data is.
503 audio, video, text, image, application, mp3
504 NOTE: mp3 is a separate type here since the original
505 napster protocol was designed for sharing mp3 files.
506 "audio" refers to other types of audio files
510 "C:\IMAGES\Grand Canyon.jpg" 54187 bc938fdc0ef63772bfbdbf57aabb0860-54187 image
511 "\home\drscholl\src\opennap-0.11.tar.gz" 102161 51c07734811a26853b1a2a87b67c68a1-102161 application
513 10301 new browse [CLIENT] (deprecated)
517 10302 new browse result [CLIENT] (deprecated)
519 Format: <nick> "<path>" <filename> <md5> <size> <bitrate>
520 <frequency> <time> [ <filename> ... ]
524 RFC1459, the IRC protocol was helpful in implementing many features.
526 http://www.onelist.com/community/napdev/ is a useful community (mailing list)
527 for discussion of the napster protocol.