chris@1: chris@1: chris@1: chris@1: ]> chris@1: chris@1: sonews Usenet News Server chris@1: chris@1: sonews is NNTP server than can provide chris@1: access to both local and global Usenets newsgroups. It is written in chris@1: Java and uses a relational chris@1: database as backend. chris@1: chris@1: chris@4: 2009/07/28: chris@4: sonews/1.0.0 chris@4: (binary tarball, chris@4: source tarball) new major release. chris@4: A lot of refactoring was done to make the code more robust and chris@4: maintainable. Of course, several bugs were fixed, too ;) chris@4: The 0.5.x line moves from unstable to testing in the DEB repository although chris@4: the 1.0.x seems no less stable. If in doubt choose 1.0.x. chris@4: chris@4: chris@2: 2009/07/01: chris@2: sonews/0.5.1 chris@2: (binary tarball, chris@2: source tarball) bugfix chris@2: release. chris@2: Broken Cancel-mechanism and broken buildscript fixed. chris@2: See chris@2: changelog for more details. chris@2: chris@2: chris@1: 2009/06/29: chris@1: sonews/0.5.0 chris@1: (binary tarball, chris@1: source tarball) final chris@1: released. chris@1: The setup is a little clumsy but the software is stable and works well. chris@1: chris@1: chris@1: chris@1: Introduction chris@1: sonews is a RCF3977 compliant NNTP Usenet server. chris@1: It is written in Java and uses a relation database management system chris@1: (RDBMS) as backend (currently chris@1: PostgreSQL and chris@1: MySQL). chris@1: sonews is highly multithreaded and uses Java NIO asynchronous sockets chris@1: to handle thousands of concurrent connections. chris@1: sonews is Free and Open Source Software (FOSS) licensed under the chris@1: terms of the chris@1: GNU General Public License chris@1: Version 3 (or later). chris@1: chris@1: chris@1: History chris@1: Ancestor of sonews is probably the Neat NNTP Daemon (n3tpd) chris@1: although there is very little code in sonews that can be identified chris@1: as direct derivation. chris@1: sonews was developed as diploma thesis project of Christian Lins at chris@1: StarOffice development chris@1: in Hamburg and is now a Free Software project. chris@1: chris@1: chris@1: chris@1: Roadmap chris@3: chris@4: For sonews/1.1.x a plugin API for storage backends and command handlers chris@4: is planned. chris@4: See Bugtracker for chris@4: issues with target sonews/1.1.x. chris@3: chris@1: chris@1: chris@1: chris@1: chris@1: Installation and initial setup chris@1: chris@1: Download & Installation chris@1: chris@1: Debian based systems chris@1: You can install sonews with chris@1: APT chris@1: easily. chris@1: Add the following line to /etc/apt/sources.list: chris@4: deb http://packages.xerxys.info/debian/ testing main # for sonews/0.5.x chris@4: deb http://packages.xerxys.info/debian/ unstable main # for sonews/1.0.x chris@1: And add the GPG-Key for package authentification, see chris@1: Xerxys Debian Repository chris@1: for more details. chris@1: Then force an update of your local package list: chris@3: # apt-get update chris@1: To install sonews and all prerequisites issue the following command: chris@3: # apt-get install sonews chris@1: This method should work for all recent Debian-based distributions chris@1: (Debian, Ubuntu, etc.). chris@1: chris@1: chris@1: chris@1: Other *nix systems chris@1: See Files Section for recent binary and source tarballs. chris@1: Use the binary archive and extract it in a directory of your choice. Make sure your system chris@1: provides the necessary prerequisites: chris@1: chris@1: chris@1: Java6 compatible runtime (JRE) chris@1: chris@1: chris@1: Java Mail API implementation, e.g. Sun Java Mail. chris@1: GNU JavaMail has a broken POP3 Provider and does not work with sonews. chris@1: chris@1: chris@1: JSP Servlet Container (e.g. chris@1: Kitten) [optional] chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Initial database setup chris@1: Before you start sonews, you must prepare the database. Currently sonews is known chris@1: to work with PostgreSQL and MySQL. chris@1: It is highly recommended to create an own database for every sonews instance, e.g. chris@1: called 'sonews'. Additionally, it is recommended to create a unique database user chris@1: for sonews, e.g. 'sonewsuser'. Please do not use the root user for sonews! chris@1: The sonews user needs rights for SELECT, INSERT and UPDATE statements. chris@1: Refer to the database's manual for instructions. chris@1: You will find the SQL Schema definitions in the helpers subdirectory of chris@1: the source and binary distributions. You can create the tables manually using chris@1: this templates or you can use the setup helper: chris@3: user@debian$ sonews setup chris@1: or on other *nix systems: chris@3: user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup chris@1: The tool will ask for some information about your database environment, chris@1: connect to the database, create the tables and creates a default bootstrap chris@1: config file called sonews.conf. chris@1: chris@1: chris@1: chris@1: chris@1: Running sonews chris@1: chris@1: Configuration chris@1: There is a bootstrap configuration in /etc/sonews/sonews.conf and a regular configuration chris@1: in the database table config. chris@1: There are various configuration values that can be adapted: chris@1: chris@1: chris@1: sonews.article.maxsize chris@1: chris@1: Maximum allowed body size of a news message given in kilobytes. Please note that chris@1: for MySQL the ‘max_allowed_packet’ configuration variable must chris@1: be set to a value higher than ‘sonews.article.maxsize’ otherwise posting chris@1: of large mails will fail. chris@1: chris@1: chris@1: chris@1: sonews.debug chris@1: chris@1: chris@1: If set to true every(!) data going through sonews' socket chris@3: is written to sonews.log. After a high traffic night the logfile can be chris@1: several gigabytes large, so be careful with this setting. chris@1: chris@1: chris@1: chris@1: chris@1: sonews.hostname chris@1: chris@3: chris@3: Canonical name of the server instance. This variable is part of chris@3: the server's hello message to the client and used to generate chris@3: Message-Ids. chris@3: It is highly recommended to set sonews.hostname to the full chris@3: qualified domain name (FQDN) of the host machine. chris@3: chris@1: chris@1: chris@1: chris@1: sonews.timeout chris@1: chris@3: chris@3: Socket timeout for client connections in seconds. Default as chris@3: recommended in RFC3977 is 180 seconds. chris@3: chris@1: chris@1: chris@1: chris@1: sonews.port chris@1: chris@3: chris@3: Listening port of sonews daemon. This value can be overridden chris@3: with the -p command line argument. chris@3: chris@3: chris@3: chris@3: chris@3: sonews.xdaemon.host chris@3: chris@3: chris@3: Hostname or IP address of the client machine that is allowed to chris@3: use the XDAEMON command. Default: localhost chris@3: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Command line arguments chris@1: If you like to start sonews directly, you can use one of the following chris@1: arguments: chris@1: java -jar sonews.jar [arguments] chris@1: where arguments: chris@1: -c|-config <path to config file> if custom config file preferred chris@1: -dumpjdbcdriver Prints out a list of available JDBC drivers chris@1: -feed Enables feed daemon for pulling news from peer servers chris@1: -h|-help This output chris@1: -mlgw Enables the Mailinglist Gateway poller chris@1: -p portnumber Port on which sonews is listening for incoming connections. chris@3: Overrides port settings in config file and database. chris@1: chris@1: chris@1: chris@1: Webinterface chris@1: The package sonews-web provides an optional webinterface that can be used to chris@1: review statistical information and configuration values of sonews. chris@3: sonews-web start|stop chris@1: The webinterface uses the the lightweight Servlet Container Kitten and is chris@1: per default listening on HTTP-Port 8080 (go to http://localhost:8080/sonews). chris@1: chris@3: chris@3: chris@3: Newsgroup configuration chris@3: chris@3: Currently some manual work is necessary to create a newsgroup hosted chris@3: by a sonews instance. chris@3: chris@3: chris@3: One possibility is to talk via Telnet to the sonews instance and chris@3: use the non-standard command XDAEMON. chris@3: telnet localhost 119 chris@3: XDAEMON GROUPADD local.test 0 chris@3: Please note that the XDAEMON command has restricted access and is only chris@3: available via local connections (default, can be changed with config chris@3: value sonews.xdaemon.host). chris@3: chris@3: chris@3: You can also use the web interface to create newsgroups. chris@3: chris@3: chris@1: chris@1: chris@1: chris@1: Development chris@1: You're welcome to create patches with bugfixes or additional features. The chris@1: Mercurial DSCM makes this step an easy task. chris@1: Just clone the public Mercurial repository: chris@3: hg clone http://code.xerxys.info:8000/hg/sonews/ sonews-trunk chris@1: Then make your changes, create a bundle of changesets and send this to me via email. chris@1: Or ask for push access to the public repository. chris@1: chris@1: There is a nightly generated Javadoc API documentation that will help chris@1: you to get in touch with the sonews source. chris@1: chris@1: Some debugging hints: if the server blocks and does not longer respond you chris@1: probably found a deadlock. Do not kill the process with "kill -9 <pid>" chris@1: but send a SIGQUIT signal with "kill -3 <pid>" and the Java VM will output chris@1: a stracktrace of all threads. This output is the most valuable information to chris@1: fix the deadlock. chris@1: chris@1: chris@1: Contributors chris@1: Maintainer and project lead: chris@1: Christian Lins (contact christian.lins (at) fh-osnabrueck.de) chris@1: chris@1: chris@1: chris@1: Sponsors chris@1: The author thanks Sun Microsystems for fully chris@1: financing the first version of sonews. A really free software supporting company! chris@1: If you like to support sonews with a donation of any kind (hardware, books, money, donuts,...), chris@1: feel free to contact the project leader. chris@1: A friendly email or a bug report is most welcome, too :-) chris@1: chris@1: chris@1: chris@1: chris@1: Links and further information chris@1: chris@1: chris@1: Bugtracker, register necessary, see project 'sonews'. chris@1: chris@1: chris@1: Sun Microsystems, friendly sponsor. chris@1: chris@1: chris@1: University of Applied Sciences Osnabrueck chris@1: chris@1: chris@1: chris@1: