melange chat server for linux --> printable docu
Author: Christian Walter
Description: melange chat server for linux, online documentation --> printable docu
Keywords: doc, docu, printable, melange, chat, server, linux, java, client, free, download, vienna, christian, walter

##

####

- ###

  ###

  ###

    Melange Chat Server & Client Documentation
        (printable version 1.10)
    © 1998, 1999 by Christian Walter, All rights reserved.
    NOTE: For a more detailed documentation, please see the ONLINE documentation.

    Table of content
    Extracting, Compiling
    Configuration & Starting

    General behaviour
    Configuration file syntax
    User commands
    Admin commands
    Credits

    Extracting, Compiling, Installing Melange - step by step
    NOTE: This steps are described more detailed in the ONLINE documentation.

    1. Download melange from www.terminal.at/melange/download.
    2. Extract melange by typing "tar xfz melange-xxxx.tar.gz".
    3. If you downloaded a binary package, you may want to step over to step #10.

    Compiling the server
    4. Change to the server directory of the package.
    5. If you WANT, you can change some default settings in melange.h now.
       (You do not need to do this, every parameter can be changed via commandline or in the configfile later.)
    6. Type make to get a list of the supported languages.
    7. Compile the server by following the instructions on the screen, eg. typing make eng at the shell for the English version.
    8. Install the server by typing make install at the shell.

    Compiling the client
    8. Change to the client directory of the package.
    9. Compile the client with a java-compiler (eg. JDK) by
       typing javac -O MClientStandard.java at the shell.

       Note: You will receive a warning saying:
       MClientStandard.java uses deprecated API. Recompile with "-deprecation" for details.
       This is not an error, just ignore this warning.
       (If you want to know, why it occurs, please contact the ONLINE documentation.)

    Installing the client
    10. Edit the example.html and change the hostname
        and all other parameters in this file. (See here for details).
    11. Create a subdirectory in your webserver directory and move all
        files from the Melange client directory there.
    12. IMPORTANT: If you want to use the java-client, the webserver
        must be the same machine, where melange will run on.

    Configuration
    13. Edit the configuration file now. (by default, it has been installed to /etc/melange.conf.
        The syntax for the commands in this file, could be found here.

    Starting
    14. Now you should be ready to start the server. You do this by typing at
        the shell:

        melange [optional] <-p portnumber> [optional] <-c adminfile> &

        For example, if you want to start melange on port 4616 using the configfile
        at /usr/local/myconfig.conf type: melange -p 4616 -c /usr/local/myconfig.con
    15. Test if the server is running, by opening a telnet connection.
        At the shell, type (default): telnet yourmachine 6666
    16. Open a java-enabled browser and connect to your webserver.
        Open the URL, where you put the example.html at, and
        everything should work.

        Good luck !

    General behaviour

    At startup two so called "SYSTEM" channels are available:

    Channel 0: This is the channel where all users go when they connect.
    Channel 1: Anonymous channel. In this channel, the name of the sender
               of a message is not shown. This channel is really good for
    	   all bad guys.

    These two channels can not be deleted by normal users. You can add additional
    SYSTEM-channels at startup using the SYSCHANNEL command in the configuration file.
    You can also set the ANONYMOUS parameter to no there, with the effect, that
    users are not allowed to go to the anonymous channel. New channels can be opened
    by any user. It's simply done by joining a channel which does not exist.
    The id of this channel has to be below the maxchannel value, by default this value
    is set to 1000. This means there can be 1000 simultaneous channels by default.
    Due to the the internal program design, it doesn't matter how many channels are open,
    the server will not use more bytes of your memory, or slow down either.
    The user who opened the channel first, is the owner of this channel.
    If he leaves or moves to another channel, the channel is closed again.
    (This is to avoid empty channels, and to avoid that one user opens and locks
    all 1000 channels available). A user can only own one channel simultaneous !
    If you don't want users to open new channels, use the ALLOWCHANNELS
    parameter in the configfile. In the configfile, you can also change
    the LOGFILE, the KICKOUTTIME, the SECURITY PROFILE and you can bann hosts permanently.
    Implemented in version 1.10 there is the GROUP-SYSTEM now. Every channel can now be associated to
    a specific group and only those users, who are in the same group can join
    these channels. If you don't associate any channel to a group all channels
    belong to the so called "system-group", and the behaviour of melange is
    exactly the same as in the old versions. Also new in version 1.10 is the
    possibility to use unique nicknames. If this feature is enabled a user
    who connects to the server will be in a situation which could
    compared to a special channel. He is not able to chat or do anything, but
    to login into the "real" chat using the /LOGIN command.
    See here for details.

    Configuration file syntax

COMMAND | PARAMETER | DESCRIPTION | VERSION
PASSWD | password | Set the password for the administrator login here. If you don't use this command, or if you leave the default password (default: changethis) unchanged, you will not be able to use the administrator commands, once the server is running. That means, if you want to use commands like user kick out, you have to set YOUR password here ! | 0.92
ANONYMOUS | yes/no | If you set this parameter to no, no user is allowed to change to the anonymous channel. Use this command, if you don't want your guests to use the anonymous channel. Default is yes. | 0.93-2
ALLOWCHANNELS | yes/no | If you set this parameter to no, no user is allowed to open a new channel. If it is set to no, only the chat-administrator can do this. Default is yes. | 0.93-2
UNIQUE | yes/no | If you set this parameter to yes, every user has to chose a unique nickname. Default is no. | 1.10
GUESTLOGIN | yes/no | If you set this parameter to yes and the UNIQUE parameter is also enabled, users can use the nickname guest instead of a unique nickname. If it's disabled really EVERY user has to have a different nickname. Default is yes. | 1.10
CHANGENICKS | yes/no | Use this command to allow/disallow users to change their nicknames once they are connected. If you don't want to allow your guest to change their names set this parameter to no. Default is yes. | 1.10
KICKOUTTIME | time | Use this parameter, if you want to change the time (in sec) a host is banned (and can therefore not connect to the server), after he has been kicked out by the administrator. The default setting is 3600 (1 hour). If you set this value to 0, a user can immediatly connect again, after he has been kicked out. | 0.94
IDLETIME | time | Using this command, you can change the default value of the IDLETIME parameter. (Default is 0, this means off). This paramter sets the time after a user is kicked out of the chat if he doesn't say a word for time seconds. If the time is set to 0 users will not be kicked out even if they don't say a word for days. NOTE: Users are not kicked exactly at the time you set via time but when the first new user after time is over connects to the chat. (This is to speed up the server). The admin user will NEVER be kicked out of the chat-system. | 1.10
LOGFILE | filename | Use this parameter if you want to use another logfile than the default one (default is: /var/log/melange.log). This is also usefull, if you are running more than one server, and want to have seperate logfiles. | 0.94
MSGLOGFILE | filename or ON | Use this parameter if you want to enable an additional logfile which logs only the messages (instead of all sysmessages, commands, servermessages, etc. in the default logfile) and if a user connects/disconnects to the server. If you specify a filename, this name is used, if you only set the parameter to ON the default logfile is used. (default is: /var/log/melange_msg.log). | 1.10
LOGLEVEL | level | Use this parameter to set the Loglevel at startup. Currently levels 0 to 4 are supported, where 0 doesn't write anything to the logfile, 4 logs every data received from the server (should only be used for debugging). Levels 1-3 are the "default" level, where 3 logs every small warning, 1 nearly no warning. Default is 3. | 0.99a
SYSCHANNEL | cid and name | By default there are two system channels available at startup. (These are MAIN (0) and ANONYMOUS (1)). If you want to create additional system channels, which should be available at startup use this command. You can use this command as often as you need. For example: SYSCHANNEL 10 hello, will create a channel with channel id 10, and with channelname "hello". | 0.93-2
GROUP | GroupID, GroupPassword | Use this parameter to create a group with the GroupID groupID and the group's password GroupPassword. | 1.10
SETGROUP | cid, grpid | Use this parameter to change the group of a system-channel with the channel-number cid to the groupID given with the grpid. NOTE: The system-channels must already exist at this time, that means you have to use the associated SYSCHANNEL parameter before the SETGROUP parameter. | 1.10
SYSMSG | on/off | This parameter enables or disables the "system-messages" feature. This feature is used and needed by the "real-time" clients. If you want to use such clients, make sure you set this parameter to on. | 1.01
PROFILE | allow/deny | This parameter is used to set the default security profile for your server. If you set this parameter to deny, nobody can connect to your server. (You have to specify who is allowed to connect, seperatly). This is usefull, if you want to run the chatserver for a team/group and don't want others to be allowed to connect. The default value is allow. In this case everybody can connect to the server. (You have to specify who is not allowed to connect, seperatly). This value must be set before the first ALLOW/DENY commands. | 0.94
ALLOW | mask | If you set the PROFILE to deny, you have to specify who is allowed to connect to the server. (Other, nobody can connect, and this does not make much sense). You do this by setting a mask. A desciption of the mask, can be found later on this page. You can use this command as often as you need (to specify more than one host). | 0.94
DENY | mask | Similar to the ALLOW command, if you set the PROFILE to allow, you CAN specify host who are NOT allowed to connect to the server. (If you don't use this command, everybody can connect). You do this by setting a mask. A desciption of the mask, can be found later on this page. You can use this command as often as you need (to specify more than one host). | 0.94

#####

###

    DESCRIPTION OF THE ALLOW/DENY HOST MASK
    You use the mask to specify host(s) to be allowed/not allowed to connect to your server.
    A mask can be a hostname (e.g. max.meier.com) or an IP (e.g. 192.192.192.192). It can
    also include wildcards. For example, if you don't want to chat with persons
    from Microsoft you can use DENY microsoft.com. NOTE: There are
    no * or ? or some other wildcards used. Melange uses a substring search to test if a host is
    allowed or not allowed to connect. For example if you use DENY xyz no host which has the substring
    xyz in his name can connect. It does also work with IPs. For example if you set
    DENY 192.168.0 no host with an IP between 192.168.0.0 and 192.168.0.255 can connect, also
    no host between 0.192.168.0 and 255.192.168.0. If you use DENY 192.168.0. (Note: there is a dot at the end !)
    only the hosts between 192.168.0.0 and 192.168.0.255 are not allowed to connect.

    User commands

COMMAND | PARAMETER | VERSION
/ADMIN | command cmd, parameter p | 0.91
This is the command for the administrator features. For details, how to use this features, see the administrator- features page. |
/FINGER (.f) | none | 0.90-2
Lists all users inside the chat, showing their nickname, their user id (line) the channel they are in, and where they come from. |
/GROUP | GroupId grpid, Password passwd | 1.10
To become a member of a specific group (NOTE: you can only belong to one group at the same time) you have to use this command. grpid is the number of the group you want to join and passwd is the group's password. If you want to leave the group you currently belong to, type /GROUP system. (NOTE: You don't need a password for the system group, of course !) |
/HELP (.he) | none | 0.90-2
Displays a list of all commands available. |
/INVITE | UserID uid | 0.93
Invite a user to your channel. To use this command, you have to be the owner of the channel. Usually no user can join your channel if it is locked. If you want a user to come into your channel, while it is locked, use this command. The user specified by uid is then allowed to join your channel, although it is private. |
/JOIN (.c) | ChannelID cid OR Channelname name | 0.90-2
This is one of the most important commands. It's used for joining, or opening a channel. If you use the command with a Channel ID or a channelname of an existing channel, you join/move to this channel (If the channel you tried to join is locked, you receive an error-message, instead). If you use this command with a Channel ID or channelname of an NON-existing channel, you create this channel and move into it. You are then the owner of this channel and can use commands like /TOPIC /KICK /OWN /LOCK /INVITE etc. If you are the owner of a channel and you move to another channel, or if you leave the chat, your channel is closed. To avoid this, you could change the owner of your channel before. |
/KICK | UserID uid | 0.91
Kick a user out of your channel. To use this command, you have to be the owner of the channel. The user, you kick out is not thrown out of the chat, but thrown back to Channel 0 (MAIN). |
/LIST (.a) | none | 0.90-2
List all channels available. This commands displays all open channels, their channel IDs, their owners and if they are locked. |
/LOCK (.l) | none | 0.90-2
Lock/Unlock a channel. To use this command, you have to be the owner of the channel you are in. If you lock a channel, no other users can change to/join your channel (If you don't invite them explicitly before). If you use this command a second time, the channel is unlocked/open again, and everybody can join it. |
/LOGIN | nickname | 1.10
If the unique-nickname feature is enabled, you have to use this command to get into the chat. When you connect to the server you are at first not able to do most things, you even can't chat with other persons. After you found a nickname which is not already in use by another person you can enter the chat using this /LOGIN command. If the guestlogin feature is enabled, instead of an unique nickname you can use the name guest to enter the chat. (NOTE: There may be more persons with this nickname). |
/ME (.id) | none | 0.90-2
Displays your name, your user id, the channel you are in, the channel name and the group you belong to. |
/MSG or /NOTICE (.p) | UserID uid, Message msg | 0.90-2
Sends a private message msg to the user specified by uid. The user the message is sent to, has to bee in the same channels as the sender. |
/NICK (.n) | Nickname nickname | 0.90-2
If you want to change your nickname, use this command. |
/OWN (.o) | UserID uid | 0.90-2
Change the owner of a channel. To use this command, you have to be the owner of the channel you are in. The user specified by uid is then the new owner of your channel. Note, the user you want to give the ownership to, has to be in the same channel ! |
/QUIT (.qu) | none | 0.90-2
Say goodbye and leave the chat. |
/SETGROUP | GroupID grpid | 1.10
If you are the owner of the channel you are currently in, you can use this command to change the channel's group. (Note: Only groupmembers can join channels which are not owned by the SYSTEM [default])). For example if you type /SETGROUP 10 only those users, who belong to group 10 can join the channel. If you want to make the channel be open for everbody again, type /SETGROUP system. Afterwards everybody can join this channel again (if it's not locked, of course). |
/SQUELCH (.s) | UserID uid | 0.90-2
Squelch/Unsquelch a user. If you squelch a user, no messages from this person, even if they are yelled, are displayed. If you use the command a second time with the same user id, the user is unsquelched again, and you can see his messages again. |
/TIME | none | 0.99a
Displays current date and time of day, using "normal" time format AND Internettime (BMT, Biel Mean Time), which is good for making dates :) |
/TOPIC (.r) | Channelname name | 0.90-2
If you create a new channel, your channel is called "Channel cid" by default, where cid stands for the channel ID of your channel. If you want to change your channel's name to something else, use this command. For example /TOPIC hansi will change your channel's name to "hansi". |
/UP | none | 0.94
Displays server uptime. |
/VER (.v) | none | 0.90-2
Displays server's version. |
/YELL (.y) | Message msg | 0.90-2
Cross channel yelling. If you use this command, all users in all channels (even if they are locked) can see your message. Only those persons, who squelched the user who yells, can't see the message. (But if you use this command too often, don't forget that the chat-admin can kick you out and/or bann your host !) |
/WHOIS (.w) | none | 0.90-2
Lists all users in your channel with their User ID (line), and if you squelched them or not. |

### Admin commands

COMMAND | PARAMETER | VERSION
/ADMIN login | password pwd | 0.91
Become chat administrator. You have to to this, before you can use any of the other admin commands. The password pwd is the password you specifed in the melange.conf file. |
/ADMIN help | none | 1.10
Displays a list showing all administrator commands available. |
/ADMIN whois | none | 1.10
Like the standard /WHOIS command, but the /ADMIN WHOIS command lists all users in the chat even those who are connecting (These are people which are already connected to the chat-server but have to chose a unique nicknames via the /LOGIN command before they could start to chat) (C-FLAG). This command also displays some additional info about the user: If they are channel owner (O-FLAG), if they are administrator (A-FLAG), to which group they belong, in which channel they are and their IDLE-time. |
/ADMIN list | none | 1.10
Like the /LIST command, but it shows ALL channels, including the channels which belong to ANOTHER GROUP. (The default /LIST command only shows public channels and the channels which belong to the same group the user is in.) |
/ADMIN join | ChannelID cid | 0.92
Join an existing channel, even if the channel you want to go to, is locked or belongs to another group. |
/ADMIN own | UserId uid | 0.92
Change the owner of the channel you are currently in. If you type SYSTEM instead of the UserID, the channel is owned by the chatserver itself (like the channels MAIN (0) and ANONYM (1)), that means, this channel can not be deleted by normal chat users. Simliar you change make a SYSTEM-channel a normal user-channel by setting the owner to a UserID. |
/ADMIN topic | Channelname name | 0.92
Change the name of the channel you are currently in, even if you are not the channel's owner. It does also work with SYSTEM-Channels. |
/ADMIN close | ChannelId cid | 1.10
Close the channel given via cid, even if you are not the owner or the channel is locked or a system-channel. |
/ADMIN syschannel | ChannelName cname | 1.10
You can use this command to create a new system-channel with the name given with the cname parameter. |
/ADMIN kick | UserID uid | 0.91
Kick the user with the UserID uid out of the chat. After a user has been kicked out, he is not able to connect immediatly. By setting the KICKOUTTIME parameter in the configuration file, you can change the time, he has to wait before he is allowed to come in again. |
/ADMIN kickouttime | BannTime t | 0.94
Using this command, you can change the default value of the KICKOUTTIME parameter in the configuration file, whithout the need of restarting the server. This paramter sets the time, a user is not allowed to connect to the server after he has been kicked out by the administrator. t is the time in seconds. |
/ADMIN idletime | IdleTime t | 1.10
Using this command, you can change the default value of the IDLETIME parameter in the configuration file, whithout the need of restarting the server. This paramter sets the time after a user is kicked out of the chat if he doesn't say a word for IdleTime seconds. If the time is set to 0 users will not be kicked out even if they don't say a word for days. NOTE: Users are not kicked exactly at the time you set via IdleTime but when the first new user after IdleTime is over connects to the chat. (This is to speed up the server). The admin user will NEVER be kicked out of the chat-system. |
/ADMIN loglevel | Loglevel level | 0.99a
Use this command to change the current loglevel without restarting the server. It is the same as the Loglevel parameter in the configuration file. Currently loglevel 0 to 4 are supported (0 ... no logfile output, 4 ... debugging mode) |
/ADMIN sysmsg | Sysmsg on/off | 1.01
Use this command to enable/disable the "system messages" feature while the server is running. On enables this messages, off disables the messages. This feature is used and needed by the "real-time" clients. If you use such clients, make sure you enable this parameter. It is the same as the Sysmsg parameter in the configuration file. |
/ADMIN unique | UniqueNicks yes/no | 1.10
Use this command to enable/disable unqiue nicknames. If this parameter is enabled, users who connect to the server have to choose a nickname which is not in use already, before they can connect to the chat-channels via the /LOGIN command. It is the same as the UNIQUE parameter in the configuration file. |
/ADMIN changenicks | ChangeNicks yes/no | 1.10
Use this command to allow/disallow users to change their nicknames once they are connected. If you don't want to allow your guest to change their names set this parameter to no. It is the same as the CHANGENICKS parameter in the configuration file. |
/ADMIN guestlogin | GuestLogin yes/no | 1.10
If the UNIQUE nickname paramter is enabled every users has to have a unique nickname. If the UNIQUE paramter is enabled you can use this parameter to enabled a guest-login. If users don't know a unique nickname they can use the nickname guest. There can be more the one user with this nickname ! It is the same as the GUESTLOGIN parameter in the configuration file. |
/ADMIN group | [Group groupnum] | 1.10
If this command is called without the OPTIONAL groupnum parameter it lists all groups available and the associated passwords. If the command is used with the groupnum parameter it lists all users of this group who are connected in the moment, no matter in which channel. |
/GRPADMIN | param1, param2 | 1.10
Used to administrate the groups. (NOTE: The command is called /GRPADMIN - not /ADMIN grpadmin although you need to be administrator to use this command !) There are three ways for using this command: Adding a group: Type /GRPADMIN groupnumber password to create a new group. Change password: Type /GRPADMIN groupnumber new-password to change the group password. Delete a group: Type /GRPADMIN groupnumber REMOVE to remove a group. It is the same as the GROUP parameter in the configuration file. |
/ADMIN stat | none | 0.99a
Displays the status and the current parameter settings of the server. It shows the loglevel, the name of the logfile, the port it is running on, the host table etc. Depending on the default security profile you selected in the melange configuration file, the host table stores the currently banned hosts, or the currently "trusted" hosts (these are the hosts, which are allowed to connect). If the default security profile is allow (this is also the default setting), it is also displayed if the hosts are permanently banned, or if they are banned after a user has been kicked out. In the first case, the string (permanently banned) is displayed in addition. Replaces the /ADMIN security command used in previous version. |
/ADMIN deny (same as allow,add) | Hostmask mask | 0.94
If the default security profile is allow, everybody is allowed to connect to the server. You can bann hosts, by defining a DENY mask in the configuration file. With this command, you can also add hosts to the host table while the server is running, without the need of restarting it. You do this by specifying a hostmask, which has the same form as in the configfile. If you don't know what it looks like, take a look here. |
/ADMIN allow (same as deny,add) | Hostmask mask | 0.94
If the default security profile is deny, you can add additional "trusted" hosts to the host table, without restarting the server. Trusted hosts are the hosts which are allowed to connect to Melange. You specify the hosts using the same hostmask as used in the configuration file. If you don't know what it looks like, take a look here. |
/ADMIN add (same as allow, deny) | Hostmask mask | 0.99a
This command is the same as /ADMIN allow and /ADMIN deny. All these commands add a hostmask to the host table. The reason for the existence of allow, deny and add is to use the same command names used in the configfile and to make it easier to remember the right syntax. Internal all of them are handled equal. |
/ADMIN remove | Hostmask mask | 0.94
Using this command, you can remove a hostmask from the host table of currently banned or trusted hosts, without restarting the server. |
/ADMIN shutdown | Password pwd | 0.99a
Shuts down the chat server in a controlled way, eg. all client connections are closed before shutdown. To avoid unwanted shutdowns you have to give the administrator password as a parameter, eg. /ADMIN shutdown mypassword |

###

###

    HINT: With these admin features you can also delete every channel.
    Just go to the channel you want to destroy, change the owner of this channel
    to your UserID uid and leave the channel.

    Credits
    Michael Kohn - Melange's JAVA-Chat client is based on his work.
    			    (http://www.inlink.com/~naken)
    Sven Lankes - for many tips, help and ideas
    Frank Stolze - SOLARIS - Makefile
    Pietro Femmino' - Italian language File
    Oliver Mueller - French language File
    Christopher Hicks - Tips, idea for the "printable" documentation
    Rick Bradley - The PERL-CGI script for a login-system.
    David Diaz i Torrico - Catalan language file
    William Johnson, Steven Narmontas and all the others for their tips and ideas to improve melange. THANKS !

    *** MELANGE CHAT SERVER 1.10 - PRINTABLE DOC - EOF ***