README for imc2-0.10
This is IMC2 version 0.10 (that's 0 point ten :). It includes the much-awaited
(?) ICE patches.
IMPORTANT: Your IMC config file MUST contain InfoName and InfoEmail lines
before IMC will start up. You may want to configure other Info lines as well.
See README.info for details on what these lines need to contain.
What is IMC2?
-------------------------------------------------
IMC2 is a replacement for James Seng's IMC addon for Merc/Envy/ROM
based MUDs. It was written with three basic goals in mind:
o to generate a completely new codebase, placed under the GPL
o allow portability between mud types
o a new protocol, circumventing various problems in the existing IMC
code
IMC2 has various features, including:
o supports rinfo, rwho, rtell, rreply, rbeep, imclist, rwhois, rquery,
rfinger
o ICE allows dynamic creation and removal of inter-mud channels, and
allows control over who can participate in channels you own
o inter-mud mail is now in (note to someone@anothermud)
o core code is not tied to any particular mud flavour
o loop elimination - IMC connections can form loops without causing echoing
o code maintains a list of active muds on IMC plus ping times to them
o backward compatibility - will connect to muds using James Seng's
IMC code
o forward compatibility - new packet types can be forwarded without
recompiling
o modularity - since the core code is mud-independent, the code is
usable on just about anything, including no mud at all! (see
router.c for an example of this)
o ease of use - adding new packet types or modifying the behavior of
existing types does not require an indepth knowledge of the protocol
o easy configuration - imc.conf is human-readable, and all
configuration can be done from within the mud without rebooting.
o invisibility state (including wizi/incog) is preserved between muds
o immortal commands: rconnect, rdisconnect, rignore, rsockets,
imc (config editing)
o colour between muds, independent of the particular method used by each
Installation
--------------------------------------------------
To begin with; if you have WWW access you probably want to see
http://www.toof.net/~imc/, which may be more up-to-date than this file.
These installations are fairly generic; specific installation instructions
are provided for:
- ROM 2.4
- Envy 2.0 and 2.2
- Merc 2.2
- Smaug 1.01c
- Ack! 4.1
- Circle 3.0bpl12
Provided are the following files:
imc-config.h: user-configurable options for IMC
imc.h: exported functions and data for all of the core IMC code
imc.c: the core IMC2 forwarder
imc-interp.c: packet interpretation
imc-version.c: text <-> packet interpreter, with support for versioning
imc-mail.c: mail reception/transmission routines
imc-util.c: utility functions
imc-events.c: event handling code
imc-config.c: config loading/saving/online editing code
imc-mercbase.c: interface files for Merc-derived muds
imc-mercbase.h: interface header files
(imc-mercbase.[ch] now include Circle support, too, but I'm not renaming it ;)
ice.c: common ICE code
ice.h: common ICE headers
icec.c: ICE client core code
icec.h: icec definitions
icec-mercbase.c: interface files for the ICE client, similar to imc-mercbase
icec-mercbase.h: definitions for the .c
The other files are for various utilities that are not directly needed to run
IMC:
router.c: a router-only interface file (used by hubs)
iced.c: the ICE daemon, which runs typically on a hub
iced.h: header file for iced.c
webserver.c: interface code to act as the server half of a CGI<->IMC
gateway
webclient.c: CGI code which talks to webserver.c
- Add imc.c, imc-interp.c, imc-version,c imc-mail.c, imc-util.c,
imc-events.c, and imc-config.c to your Makefile, so that they get
linked in with the final server binary. Also add whatever interface
file you will be using (most probably, imc-mercbase.c)
- Create an interface file to suit your own system. The following codebases
use the prewritten interface file, imc-mercbase.c (which you probably
want to tweak) :
ROM 2.4
Envy 2.0 and 2.2 (other version should work with minimal changes)
Merc 2.2 (2.1 should work with minimal changes)
Smaug 1.01c (Smaug will have integrated IMC as part of a future release)
Ack! 4.1 (includes an earlier release of IMC. Patches to 4.1 to the current
release are available separately from the IMC ftp site)
Circle 3.0bpl11. I'm not familiar with Circle code myself; these patches
were provided by Trevor <tman@iname.com> and queries about the
Circle-specific bits of the code should probably go to him.
For these codebases, you will need to uncomment the appropriate #define at
the top of imc-mercbase.h. You will also want to edit the .c and .h
appropriately if your mud supports color.
The next section concerns changes to the main mud code. Patches for stock
code are available in the appropriate subdirectory off install/ (eg.
install/Rom24/ for Rom 2.4)
- Add a call to imc_startup during the mud startup code, and a call to
imc_shutdown during shutdown. If your mud uses hotreboot, copyover,
or similar, then call imc_shutdown before starting the new binary, and
allow the startup to call imc_startup as normal.
- Add a call to icec_startup after the call to imc_startup.
- Add code to regularly call imc_idle(0,0) from the main game loop.
Alternatively, use imc_fill_fdsets/imc_idle_select directly (if you know
what you're doing)
- Configure imc-config.h to taste. The defaults should work fine, but
there are some #defines you can tune at the top of this file -
especially if you have compilation problems with missing system functions.
- Recompile. I only have access to a Linux system, so you may need to change
the includes used (especially in imc.c). Please email me any changes you
have to make to get it compiling on your system.
(it seems to work okay on Solaris/SunOS now, but don't quote me on that)
- Find a site to connect to. I maintain 2 IMC hubs; see the
file README.hub for more details.
Config files
--------------------------------------------------
You probably don't need to read this section unless you are running a router
or some other setup where you can't edit the config file using the imc_command
function in imc-comm.c.
The format of the config file is fairly straightforward. Each line consists of
a keyword-value pair. Lines beginning with '#' are ignored.
Valid keywords are:
. Version : value is the config file version number. This should
always be the first entry in the config file. Current config
files are Version 1.
. LocalName : value is the local IMC name of the mud
. LocalPort : value is the local IMC port of the mud
. Connection : value specifies a direct IMC connection; see below for format
The format of the Connection value consists of 8 fields, separated by colons.
The 8 fields are:
- Remote mud name. This must match whatever the remote mud has its LocalName
set to.
- Remote mud hostname
- Remote mud IMC port (ie. the LocalPort on the other mud)
- Client password
- Server password
- rcvstamp value (internal routing config)
- noforward value (internal routing config)
- Flags
The client and server passwords must match on both ends.
The flags field may be blank, or may be a series of whitespace separated flag
names. Currently the following flags are supported:
o client: only accept connections from this mud, don't ever try to make them
o noauto: don't try to connect on startup
o reconnect: automatically try to reconnect every 30 minutes if a connection
is lost to this mud (2 minute delay for the first attempt).
o broadcast: if a packet is destined for this mud specifically, then broadcast
it anyway. Normally in this case the packet is sent only to the mud; if
there is a faster or more reliable link to the mud elsewhere you probably
want to use this option as a backup.
o deny: don't _ever_ allow connections to this mud. Useful if (for
example) a mud is crashing due to an IMC bug, and you need to cut it off.
o new: temporary flag used in hubswitching, should never be set manually
o hub: all connections which are hub connections will be given this flag,
when a hub, or a mud acting as a hub, is detected.
o noswitch: sometimes it is not desirable to switch to a specific hub.
it may be unstable, on the other side of the world, on the other side
of a firewall or have a very slow or troublesome internet connection.
creating an entry in the config file with the NOSWITCH and NOAUTO flags
will keep the hub from being used in the hub switching process.
For example, here is a sample config file for a mud called MudA running on
host1, IMC port 9005:
# Lines beginning with # are comments, and ignored.
#
LocalName MudA
LocalPort 9005
# Name:Host:Port:password:password:rcvstamp:noforward:flags
Connection MudB:host2:9005:secret1:secret2:0:0:noauto
Connection MudC:host3:4005:xyzzy:aabbaa:0:0:none
For MudC the config file would look something like:
# Lines beginning with # are comments, and ignored.
#
LocalName MudC
LocalPort 4005
# Name:Host:Port:password:password:rcvstamp:noforward:flags
Connection MudA:host1:9005:secret1:secret2:0:0:none
Rcvstamp and noforward are used to optimise routing on muds with multiple
connections. Basically, any packet received gets the rcvstamp of whichever
connection it arrived on (locally generated packets get a stamp of 0). If the
packet is a broadcast packet, it is only forwarded to those muds where
(packet_stamp & connection_noforward_value)==0. In practice, this means
you should set the rcvstamp/noforward values of all your hub connections to
the same value (eg. 1) if you have more than one hub connection.
The location of the config file is determined at runtime by whatever is passed
to imc_startup(). All IMC files are appended to the prefix passed to
imc_startup, so for example passing a prefix of "imc/" will use files
"imc/config", "imc/rignores", and so on. Be sure to create any directories
required before starting up!
Additional info on this config file is in README.info.
Other notes
--------------------------------------------------
The home site for IMC2 is at http://www.toof.net/~imc/
The most recent version can be downloaded from
ftp://toof.net/pub/imc/
There is also a mailing list set up for IMC2: send mail to
majordomo@toof.net with 'subscribe imc2' in the body of the
message to subscribe, and send mail to the actual list at
imc2@toof.net
router.c is a small IMC router, which should serve as an example of how to
write an IMC system without a mud attached to it. This is the code that
currently runs on my IMC hub.
webclient.c and webserver.c comprise a primitive IMC->CGI gateway. webserver.c
is the server, which remains permanently connected to IMC; webclient.c is
a CGI program that asks webserver.c to make IMC requests and return the
results. Please -read- the code before you use it. A copy of this code is
running at http://www.toof.net/~imc/webclient.cgi
Feel free to add your own packet types, but I'd appreciate it if you could
email me the format of them, so I can incorporate them into future releases
and try to standardise somewhat.
This package is placed under the GPL (see the top of imc.c, and the file
COPYING, for details); please respect it. While it isn't a requirement, I'd
appreciate email if you use this package.
Comments, questions, suggestions, patches, offers of money and/or hardware
<G>, etc, are always welcome via email. If you manage to get this package
working, please email me telling me what you had to change to do so :)
I can be contacted at oliver@jowett.manawatu.planet.co.nz or spectrum@toof.net
Todo
--------------------------------------------------
Currently in progress:
. automatic routing changes (tell neighbours what connections we have up, and
changes to that, and reconfigure our forwarding rules from them responding)
. hooks for host->ip and ip->host conversions via the mud's resolver
Shelved for now:
. rsocials (use socials over rchat/rimm/etc) [in progress, hah. this is messy]
Not so near:
. more efficient multicasting for local channels
. other suggestions?
Copyright/distribution stuff
--------------------------------------------------
[from imc.c]
* Copyright (C) 1996,1997 Oliver Jowett <oliver@jowett.manawatu.planet.co.nz>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program (see the file COPYING); if not, write to the
* Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
--
Oliver Jowett <oliver@jowett.manawatu.planet.co.nz> or <spectrum@toof.net>
aka Spectrum@(IMC in general) or Nemon@AR