docs/opennap-readme.txt

   1 opennap v0.44 (BETA)
   2 the open source (TM) napster server
   3 ===================================
   4 September 30, 2001
   5
   6 http://opennap.sourceforge.net
   7 IRC: #opennap on EFNet
   8 Email: opennap-dev@lists.sourceforge.net
   9
  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)
  14         * BSDI
  15         * FreeBSD
  16         * Solaris
  17         * IRIX
  18         * OS/2
  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)
  22
  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
  31 clients.
  32
  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
  37
  38 What's included?
  39 * opennap server
  40 * metaserver for directing clients to server groups
  41 * protocol specification
  42 * SOURCE CODE!
  43
  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.
  47
  48 * For a description of the napster protocol, please see the file 'napster.txt'
  49   included with this distribution.
  50
  51 * INSTALLATION
  52
  53   To install, simply run the `setup' utility (provided with the binary
  54   distributions, or built from source).
  55
  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:
  59
  60         C:\opennap                      Win32 platforms (Win 95/98/NT/2000)
  61
  62         -or-
  63
  64         /usr/local/share/opennap        Unix platforms
  65
  66   If you wish to install OpenNap in another location, simply enter the new
  67   directory when `setup' prompts you.
  68
  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)
  74
  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
  80   option as such:
  81
  82         opennap -c PATH
  83
  84   where PATH is the _full_ path to the config file.
  85
  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).
  90
  91 * Linking Servers
  92
  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
  96       being able to join.
  97
  98         edit /usr/local/share/opennap/servers (c:\opennap\servers on Win32)
  99         add:
 100                 <server name> <password> <local_password>
 101
 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
 106         other server).
 107
 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.
 111
 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>
 117
 118 * Server to Server messages
 119
 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
 124 client commands with
 125         :user
 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.
 130
 131 * Extensions to messages
 132
 133 200     search [CLIENT]
 134
 135         TYPE <mime-type>
 136
 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
 143                 database.
 144
 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.
 149
 150         FILENAME EXCLUDES "..."
 151
 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.)
 159
 160         [ SIZE | DURATION ] ["AT LEAST" | "EQUAL TO" | "AT BEST"] <integer>
 161
 162                 allows matching on the file size and song length in addition
 163                 to the other file attributes
 164
 165 612     ban user/ip [CLIENT]
 166
 167         Format: <user|ip> [ "reason" [timeout] ]
 168
 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.
 172
 173 * Non-standard messages
 174
 175 The following messages are not present in the official napster servers, but
 176 are implemented as additional functionality in the opennap server.
 177
 178 10000   client quit [SERVER]
 179
 180         <nick>
 181
 182         the message is sent to peer servers when a client connection has
 183         closed
 184
 185 10010   server login [SERVER]
 186
 187         <server-name> <nonce> <compression>
 188
 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
 192
 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
 196
 197 10011   server login ack [SERVER]
 198
 199         <hash-response>
 200
 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
 205
 206 10012   request server link list [CLIENT]
 207
 208         Format: <empty>
 209
 210         client requests the current server link info
 211
 212 10013   user ip [SERVER] (deprecated, this info is now appended to msg 2)
 213
 214         <user> <ip> <port> <server>
 215
 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>
 220
 221 10014   registration info [SERVER]
 222
 223         <user> <pass> <level> <email> <created> <last-seen>
 224
 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
 230
 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.
 236
 237 10018   encapsulated message [SERVER]
 238
 239         :<sender> <recip> <message>
 240
 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.
 244
 245 10019   server link info [SERVER]
 246
 247         <server> <port> <server> <port> <hops>
 248
 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
 253         the others are.
 254
 255 10020   server quit [SERVER]
 256
 257         :<server> <server> "<reason>"
 258
 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.
 262
 263 10021   notify mods [SERVER]
 264
 265         :<server> <loglevel> "<message>"
 266
 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.
 270
 271 10022   server to server pong [SERVER]
 272
 273         Format: :<server> <recip> [args]
 274
 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.
 281
 282 10023   time check [SERVER]
 283
 284         Format: <time>
 285
 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
 288         too far out of sync.
 289
 290 10024   remote whois notification [SERVER]
 291
 292         Format: :<sender> <target>
 293
 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.
 298
 299 10100   server connect [CLIENT]
 300
 301         <server> [ <remote_server> ]
 302
 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.
 306
 307 10101   server disconnect [CLIENT]
 308
 309         <server> <reason> [ "<remote-server>" ]
 310
 311         delink current server from <server>.
 312         must be admin or high level to execute this command
 313
 314 10110   kill server [CLIENT]
 315
 316         <server> "<reason>"
 317
 318         cause the server to shutdown.  must be elite level to execute
 319         this command.
 320
 321 10111   remove server [CLIENT] (DEPRECATED, not currently used)
 322
 323         <server> "<reason>"
 324
 325         reqeusts that <server> be removed from the table of allowed links.
 326         must be elite to execute this command
 327
 328 10112   show server links [CLIENT, SERVER]
 329
 330         client: no data
 331         server: <host> <host> <hops>
 332
 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).
 336
 337 10115   show server stats [CLIENT, SERVER]
 338
 339         client: no data
 340         server: <clients> <servers> <files> <gigs> <channels> <time>
 341         <uptime> <memory> <numusers>
 342
 343         This command is used by administrators to get information about the
 344         state of the server.
 345
 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
 357
 358 10116   server ping [DEPRECATED]
 359
 360         note: there is now a defined command for this in napster.txt
 361
 362 10117   rehash (reload) configuration files [CLIENT]
 363
 364         Format: [server]
 365
 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.
 369
 370 10118   display client information statistics [CLIENT, SERVER]
 371
 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.
 376
 377         Format (server): "<version>" <count>
 378
 379         The server's list is terminated by a 10118 message with a 0 length.
 380
 381 10119   display which server a user is on [CLIENT]
 382
 383         Format: <user>
 384
 385         server will return an message detailing which server
 386         the particular user is on.  only mods+ can execute this command.
 387
 388 10120   ping all peer servers [CLIENT]
 389
 390         Format: (empty)
 391
 392         Causes a server to sping all of its peer servers and report the
 393         results.
 394
 395 10121   who was [CLIENT]
 396
 397         Format: <nick>
 398
 399         Displays info about a user that has recently logged out.
 400
 401 10122   mass kill by ip [CLIENT]
 402
 403         Format: <ip> ["reason"]
 404
 405         Disconnect all connections originating from <ip>
 406
 407 10123   server command histogram [CLIENT, SERVER]
 408
 409         Client: {empty}
 410         Server: <numeric> <count> <bytes>
 411
 412         Displays a histogram of the number of commands and bytes received
 413         for each supported protocol numeric.
 414
 415 10124   end server histogram [SERVER]
 416
 417         Format: <last_unknown> <unknown_count> <unknown_bytes> <total_count>
 418                 <total_bytes>
 419
 420         Terminates the list of 10123 messages.
 421
 422 10203   set user mode [CLIENT]
 423
 424         [-]{ALL,MUZZLE,BAN,KILL,PORT,WALLOP} [ ... ]
 425
 426 10204   set channel op [CLIENT]
 427
 428         Format: <channel> <user> [user ...]
 429
 430         enable <user> to kick/ban users on <channel>
 431
 432 10205   remove channel op [CLIENT]
 433
 434         Format: <channel> <user> [user ...]
 435
 436         remove <user> as operator on <channel>
 437
 438 10206   channel op list [CLIENT]
 439
 440         Format: <channel>
 441
 442         returns the list of defined channel operators for the given channel
 443
 444 10207   drop channel [CLIENT]
 445
 446         Format: <channel> [ "<reason>" ]
 447
 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.
 451
 452 10208   send message to channel ops [CLIENT]
 453
 454         Format: <channel> <message>
 455
 456         sends <message> to all operators and mods+ on <channel>
 457
 458 10209   change channel mode [CLIENT, SERVER]
 459
 460         Format: <channel> [mode]
 461
 462         if specified, [mode] is of the form
 463
 464                 (+|-)STRING
 465
 466         where STRING is one of
 467
 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
 472
 473 10210   invite user to a channel [CLIENT, SERVER]
 474
 475         Format: <channel> <user>
 476
 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.
 480
 481 10211   give voice to speak in moderated channel [CLIENT]
 482
 483         Format: <channel> [user [user ...]]
 484
 485 10212   remove voice to speak in moderated channel [CLIENT]
 486
 487         Format: <channel> [user [user ...]]
 488
 489 10213   muzzle a user in a specific channel [CLIENT]
 490
 491         Format: <channel> <user> ["reason"]
 492
 493 10214   unmuzzle a user in specific channel [CLIENT]
 494
 495         Format: <channel> <user> ["reason"]
 496
 497 10300   share generic media file [CLIENT]
 498
 499         Format: "<filename>" <size> <md5> <major-content-type>
 500
 501         <content-type> is the major MIME type defined for what the data is.
 502                         should be one of:
 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
 507
 508         Examples:
 509
 510         "C:\IMAGES\Grand Canyon.jpg" 54187 bc938fdc0ef63772bfbdbf57aabb0860-54187 image
 511         "\home\drscholl\src\opennap-0.11.tar.gz" 102161 51c07734811a26853b1a2a87b67c68a1-102161 application
 512
 513 10301   new browse [CLIENT] (deprecated)
 514
 515         Format: <nick>
 516
 517 10302   new browse result [CLIENT] (deprecated)
 518
 519         Format: <nick> "<path>" <filename> <md5> <size> <bitrate>
 520                 <frequency> <time> [ <filename> ... ]
 521
 522 * References
 523
 524 RFC1459, the IRC protocol was helpful in implementing many features.
 525
 526 http://www.onelist.com/community/napdev/ is a useful community (mailing list)
 527 for discussion of the napster protocol.