<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org" />
<title>The CoffeeMud CM1 Server</title>
<link rel="StyleSheet" href="style.css" type="text/css" media="screen" />
<!-- Modified by Josh Mueller, 2006-5-5, fix validation errors, add index, and fix spelling errors -->
</head>
<body>
<center>
<table border="1" cellpadding="10" cellspacing="0" width="90%">
<tbody>
<tr>
<td colspan="2" align="left" bgcolor="#dfdfdf" width="100%">
<h1>The CoffeeMud CM1 Server</h1>
</td>
</tr>
<tr>
<td align="left" valign="top" width="20%">
<ul>
<li><a href="CM1Server.html#security">Security</a></li>
<li><a href="#connect">Configuration</a></li>
<li><a href="#protocol">Protocol</a></li>
</ul>
</td>
<td align="left" valign="top">
<p>The CoffeeMud CM1 Server
is a control and monitoring service for your mud. It allows
external applications and tools to access, monitor, and alter your mud
in a safe, secure, and formalized manner.</p>
<p>There frankly isn't much you can do with it now (Well,
there IS, but it is neither well documented yet, nor is there a proper
client). However, the intention is for this to act as a build
port for external tools or even external game clients.</p>
<h2><a name="security">Security</a></h2>
<p>The CM1 Server may be
bound to 127.0.0.1 (localhost) - this means it will not accept external
connections.</p>
<p>The access available to unauthorized clients is limited to a
small number of trivial commands.</p>
<p>Connections that use LOGIN command to be authorized as users
are limited by their user security level.</p>
<p>Connections that use the REGISTER command to be authorized are
limited to communication commands.</p>
<h2><a name="configuration">Configuration</a></h2>
<p>The default installation
of CoffeeMud will run a single CM1Server, determined by the line
'RUNCM1SERVER=true' in
'CoffeeMud.ini', and configured by the ini file defined by
'CM1CONFIG=/web/cm1.ini'. Either setting can cause the server not
to start.</p>
<p>The INI fils for the cm1
server lives in the 'web/' directory off the CoffeeMud root. The file
is called cm1.ini, and contains the following entries:</p>
<ul>
<li> <b>PORT</b>=xx
: <b>[REQUIRED]</b> <em>(e.g.25)</em>
<p>Sets the port number
the server will listen for CM1 requests on; this cannot be the same
port as the main MUD server or web servers. Identical to MUD server
usage. There is normally no good reason to change from 25, as that is
what email clients will expect.</p>
</li>
<li> <b>BIND</b>=addr
: <em>(e.g.127.0.0.1)</em>
<p>Causes the server to
be bound to a specific address; this is useful on multi-homed machines
or if you wish to prevent public access to the pages. Identical to MUD
server usage.</p>
</li>
<li><span style="font-weight: bold;">IDLETIMEOUTMINS</span>=xx
: <b>[REQUIRED]</b> <span style="font-style: italic;">(e.g. 10)</span><br />
<br />
The maximum amount of time the cm1 server will tolerate idleness before
kicking a connection out. This is in minutes.<br />
</li>
<li><span style="font-weight: bold;">MAXTHREADS</span>=xx
: <b>[REQUIRED]</b> <span style="font-style: italic;">(e.g. 10)</span><br />
<br />
The maximum number of threads that your server will spawn to handle
connections.<br />
</li>
<li><span style="font-weight: bold;">QUEUESIZE</span>=xx
: <b>[REQUIRED]</b> <span style="font-style: italic;">(e.g. 512)</span><br />
<br />
The maximum number of requests to queue up for processing, when all
threads are active.<br />
</li>
</ul>
<h2><a name="protocol">Protocol</a></h2>
By default, the CM1
server listens on port port 27733. The interface is standard
ascii, so
you can test the service by telnetting to it. However, no formal
telnet codes are supported.<br />
<br />
After connecting to the server, the client will receive a single line
greeting, the phrase:<br />
<br />
<span style="font-weight: bold;">CONNECTED TO CM1SERVER0@27733<br />
<br />
</span>After this, all output from the server will be be
according to the following rules:<br />
1. Output will begin with a bracket [<br />
2. The first bracket will be followed by the string OK, FAIL, MESSAGE,
or BLOCK.<br />
3. All output, except for BLOCK, will be terminated by a closing bracket
] and a carriage-return followed by a linefeed: \r\n<br />
4. All output, except for BLOCK, is guaranteed to not contain any
carriage-return or linefeed characters.<br />
5. All output, except for [MESSAGE, will only be generated in response
to input.<br />
<br style="font-weight: bold;" />
<span style="font-weight: bold;">[OK...]</span><br />
An output string beginning with OK may be followed by a space, and one
or more parameters, space delimited. This denotes that the
command executed successfully.<br />
<br />
<span style="font-weight: bold;">[FAIL...]</span><br />
An output string beginning with FAIL will be followed by a space, and a
string describing the nature of the failure. This denotes that
the command failed to execute successfully, usually because of bad
input, but for other reasons also.<br />
<br />
<span style="font-weight: bold;">[MESSAGE...]</span><br />
An output string beginning with MESSAGE will be followed by a space,
and a one or more parameters, space delimited. This is the only
string that need not be in direct response to a command, but according
to a request for event notification.<br />
<br />
<span style="font-weight: bold;">[BLOCK <end of block
string>]</span><br />
An output string beginning with BLOCK will be followed by a space, and
a random string. All ouput from the end of this output line to
the next occurrence of the given end of block string is the full
intended output. This output may contain other end of line
characters, which are part of the output string.<br />
<br />
All input commands are terminated by some combination of
carriage-return, linefeed, or both, except when the BLOCK command is
used.<br />
<br />
<br />
<br />
</td>
</tr>
</tbody>
</table>
<br />
</center>
</body>
</html>
