Welcome to WebGuys Instant Message System. WebGuys Instant Message System is free software. Please see the file COPYING for details. For documentation, please see the files in the doc subdirectory. For building and installation instructions please see the INSTALL file. Introduction ============ The WebGuys Instant Message System (wimd) or Whacky-Chat!, is designed to be a server for small groups of individuals that need to easily communicate short messages to each other without resorting to email. Quick Start =========== To get wimd up and running quickly, do this: ./configure make make install /etc/rc.d/init.d/wimd start This should start up a server on port 2980 on the local machine. You'll need to install a client separately to start using the server. Installation ============ wimd requires the following to compile: * g++ 2.8.1 or a recent version of egcs * libstdc++ 2.7.2 or later * a mostly POSIX-like environment that includes POSIX threads wimd has be compiled and tested on RedHat Linux 5.1, 5.2 and 6.0, as well as IRIX 6.2. To start, follow these steps: 1) ./configure This configure takes the following non-standard options: * --enable-debug Adds -g to the source file compilations * --with-controldir=DIR This is the location where wimd.pw, wimd.conf and wimd.motd will be placed by the installer * --with-initdir=DIR Location of the System V style init directory. Usually either /etc/rc.d/init.d or /etc/init.d 2) make This should proceed without incident, unless there are unusual warnings generated by your compiler. If something goes wrong, send me some email. 3) make install You will probably have to be root in order to complete this step 4) Edit config files Before you run your server for the first time, you will want to set the options properly. These are the control files for wimd: * wimd.conf This is the main file, and sets the location of the password and message of the day file, as well as some logging network settings. * wimd.pw This is the password file, and it must contain entries. There are no built-in accounts to the server, so this is a vital step. The distribution version of this file contains two accounts, admin (1000) and test (1001). The admin user has management privileges, and the test user does not. The file doc/wimd-protocol.txt explains what the privileged commands are. This file can be edited by hand or you can use the addwimduser.pl script to do it. The format of the file is explained below. * wimd.motd The message-of-the-day file is optional. The contents of this file will be printed out as *MOTD messages at the beginning of each client connection. 5) /etc/rc.d/init.d/wimd start By using the System V init script, you will be able to easily have the wimd server started at each boot up. You will need to add links in the run level directories that you wish to start up wimd in. The recommended levels are 3 and 5. The wimd server should now be installed and ready for use. Administration ============== As with any network service, there are some items that will require the attention of an administrator from time to time. Items such as adding or removing users and possibly creating additional servers for example. There are three control files used by the server, and their formats are as follows: * wimd.conf - The main configuration file, which contains name/value pairs in the form of name=value. It can contain the following settings: * PORT - The network port opened by the server. This value can be in the range of 0-65535, but ports 0-1024 require the wimd binary be setuid root for access. The default is 2980, as assigned by the IANA. * LOGLEVEL - The amount of logging produced by the server. This can be any of: 0 (no logging), 3 (errors only), 5 (notices and errors), 6 (info, notice, error), 7 (debug, info, notice, error) Level 3 is recommended, and 7 is discouraged, as the volume is quite large. * PWPATH - The path to the password file, this defaults to `/etc/wimd.pw'. * MOTDPATH - The path to the message of the day file. * KICKUSERS - Sets what happens if a user logs in more than once. If set to 1, the user that logged in first is kicked off, and the second takes their place. If set to 0, the second user is denied access. The example file includes comments about each setting. Comments begin with the `#' character. * wimd.pw - This is the password file and contains lines as entries much like a UNIX password file. An example line looks like the following: test:6VhIdj5UM3oSk:1001:1::foo@bar.com The fields are: ::::: Passwords are stored in encrypted form using the crypt(3) command with a random salt. Nicknames should not contain spaces. The group can be one of 0 (privileged user) or 1 (normal user). Privileged users are able to access the AUTH commands outlined the the protocol file. User ids *MUST* be unique! * wimd.motd - This file contains a note to be printed out to each user when they connect. It can contain multiple lines and comments starting with the `#' character. The output of the server can be very useful in diagnosing a problem. The wimd server is capable of emitting a large volume of information when set on debug logging. However, most sites will be happy with only errors and or notices and errors. Some of the kinds of information available at each level include: * ERROR - file or network I/O failures. * NOTICE - User connections and disconnections, and successful logins. * INFO - login processing, user messages, and command processing. * NOTICE - startup and shutdown of server objects, server startup and shutdown * DEBUG - network message sizes and errors All wimd syslog messages are sent to the LOG_DAEMON facility, and can be captured to a special file for analysis. An entry in your syslog.conf file can achieve this: daemon.* /var/log/daemonlog Messages appear in the following format: Jun 15 11:19:59 mr-burns wimd[1799]: NOTICE: Initialization Complete. Each message is preceded by its level, i.e. ERROR, INFO, NOTICE... as above. The tools/msg.pl utility can display message traffic on your server as an example of parsing the syslog output. If your system supports the LOG_CONS option to syslog, and the server is not being run in daemon mode, all messages will be displayed on standard out, as well as syslog. The following command-line options are supported by the server: * -d - start the server as a daemon. * -p - use this port number overriding config file setting * -c - use this config file instead of `/etc/wimd.conf' The default init script starts the server with the -d option. Client Development ================== Client developers should first read the file doc/wimd-protocol.txt to gain understanding of the client-server protocol. This file also includes some caveats on implementing a client. Another source of inspiration is the Tcl/Tk client. This client runs on UNIX, Windows, and MacOS, so it should be available to any user. Even if Tcl is not familiar, the interface of this client should be used as a guideline for new clients. Clients implemented for other platforms should try to maintain a clean, easy-to-use interface, but there are no specific restrictions on the look of the client. There is a need for native clients for all major platform, so if you would like to contribute, please do so. Future ====== Some of the things we're working on: * Better documentation for the current version, including more maintenance comments in the source code. * Server 2.0 - much more sophisticated, with new codebase and protocol. * Native clients - Clients using native windowing system and OS tools for the following platforms: BeOS, Windows, Gnome, KDE, Xlib, others. * Integrating with other messaging products. * Compliance with the IETF's Instant Messaging and Presence Protocol. See: http://www.ietf.org/html.charters/impp-charter.html Contact ======= For more information about this software visit: http://www.webguys.com/wimd.html LocalWords: MOTDPATH KICKUSERS VhIdj UM oSk AUTH ids daemonlog