Dead Souls Admin FAQ, v2
Written by Cratylus @ Frontiers, October 2005
Updated January 2006
%^GREEN%^*** What's this FAQ about? ***%^RESET%^
The point of this document is to orient a new admin in
Dead Souls 2. Starting a MUD with a lib that is completely new to
you can be confusing and discouraging. Hopefully this FAQ will
make the experience less difficult.
%^GREEN%^*** How do I start?***%^RESET%^
Start by reading the Dead Souls FAQ for some background
on where this lib came from and what you can do with it.
%^GREEN%^*** What's the QCS?***%^RESET%^
Please see the QCS example page for an explanation of this
important Dead Souls system.
%^GREEN%^*** Is there a MUD somewhere running Dead Souls I can log into?***%^RESET%^
As a convenience to the curious, I have set up a "demo" mud
at dead-souls.net 6666 . To connect, either click on
this link with your browser, or open a terminal window
(or for windows users, Start -> Run ) and
type: telnet dead-souls.net 6666
When you log in, the system will read your playerfile for
a few seconds and then it will turn you into a creator. This
is so that you can examine code, try out the QCS, etc.
Please note that in the regular, non-demo version of the
mud, people are NOT automatically given creator status.
On the regular non-demo version of the mud, Only
the admin (basically, the first person to log on to the new mud)
gets automatic creatorship. Another difference is that the
demo mud is set to reboot every eight hours or so. The
default reboot interval on the regular version is weeks long.
After logging in, you will be transported
to your workroom. Some useful commands:
look
look at me
look at chest
open chest
look in chest
get tricorder from chest
read index in handbook
read chapter 1 in handbook
who
stat
wiz
create new npc generic
look at board
read 1 on board
home
%^GREEN%^*** I want to invite my friends to help me code. How do I
promote them to creator status?***%^RESET%^
As admin, you have access to the admintool
command. This opens a menu-driven admin system you
can use to manage some basic aspects of your new MUD.
Everything on admintool can be done with
commands, system calls, or file editing, but until
you get the hang of all that stuff, admintool
is a convenient shortcut.
In this example, you would type: admintool ,
then select option 3, then option l (that's a lowercase "L").
The oldfashioned way, if the new creator
were named dude, would be: encre dude
I know. But people like menus, so I made it.
%^GREEN%^*** What about intermud? How do I talk on that?***%^RESET%^
The intermud3 (or i3) network is available
to you, and you are probably already connected to it. Type
mudlist to see a list of other muds on the network.
By default, the "Dead Souls intermud channel" is
enabled for creators. Type: ds blah blah
and other Dead Souls muds on the i3 network will see
your message like this:
You@YourMud <ds> blah blah
To enable intergossip and intercre, read
/doc/README for instructions.
Please note that intercre is where you ask coding
and technical questions only. Random chatting is not
tolerated on that channel. Newbie questions that are
Dead Souls specific or that obviously have answers in
Dead Souls documentation will meet a hostile reception on
intercre.
Conversely, intergossip is mostly chat. Please
be warned that discussions on intergossip are usually
offensive, argumentative, and generally aggressive.
This hostility is especially sharp when you
are identified as a "newbie". You will almost certainly
be mocked and insulted no matter what you say, but
especially if your first messages betray you as
ignorant of intergossip standards and traditions. I
strongly recommend you lurk on this channel for a few
days before saying anything. Really, I recommend you
avoid it entirely.
%^GREEN%^*** I talk on intermud but nobody replies. What's up with that?***%^RESET%^
I3 uses a hub topology. All muds communicating on intermud
connect to the router to do so. If that router is down all
I3 communication stops, until it comes back up.
There's also the possibility that nobody who wants to
chat is listening.
%^GREEN%^*** What's this about a manual on Frontiers?***%^RESET%^
It's no longer relevant. All the docs
we were making available on Frontiers are now included
in Dead Souls, starting from version 1.9r9.
In your workroom is a chest. Open the
chest and the new Dead Souls Creators Manual is
inside. The text files are in /doc/manual .
%^GREEN%^*** How do I add limbs to a race?***%^RESET%^
Edit /secure/cfg/races/<race>, then remove the race from the
races daemon, then add re-add the race. If you want players
to be able to play as this race, make sure you add the
numeral 1 on the addrace command. For example:
addrace jabberwock 1
%^GREEN%^*** How do I make my friend an admin?***%^RESET%^
Use the groups menu in admintool, and select
"Modify a group". Select the ASSIST or SECURE group,
and enter the names of all the members it should have. If
I wanted to make xyzzy an assistant admin, I would edit the
ASSIST group and make the contents look like this:
cratylus:xyzzy
Xyzzy then needs to log out and log back in.
Obviously, Xyzzy needs to be a creator for this to be of any use,
so I would have encre'd him first.
%^GREEN%^*** I don't like how the who command output looks! How can I change it?***%^RESET%^
Believe it or not, I actually get questions like this. I also
get stuff like "my workroom is broken! fix it!"
If there is something broken about the lib itself, such as
an insta-death bug or a command that crashes the mud, I am
happy and eager to hear about it, so I can implement the fix
in the next lib release.
However, if the problem you're having is that the lib,
by design, behaves in a way not to your liking, this isn't something
I'm likely to "fix" for you. For example, if you want a "who"
command with a cooler look, that's up to you to make. You're
the one coding a mud, so you need to take it upon yourself to
understand the code and modify it to suit your tastes.
Similarly, "orcs are too strong!" or "advancing levels
should increase your eyesight" are issues you need to deal
with on your own, using the coding skills learned from reading the
Creators Manual.
%^GREEN%^*** All I did was change one thing in a file, and now it won't update. Help!***%^RESET%^
You should make it a habit to make backup copies of files
before editing them. That way, if you screw up the code, you can
just copy the backup to the original filename.
A convenient way to do this is the bk command. See
the debugging page for an example of its use.
If you are using Windows, you need to be aware of the
linefeed problem. unix text files and DOS text files have different
formatting. If you edit files in Notepad, then try to update them,
you may find that the file no longer updates, no matter what
you do. The difference is usually invisible to you, so you can't
tell why a file that looks exactly the same as before now won't
work.
Dead Souls expects unix-formatted text, and if you feed it
something else, the results aren't likely to be to your
satisfaction. Make sure you use an editor that respects unix
text. In Windows 2000, WordPad seems to do a reasonable job of not
completely screwing things. It does, however, add carriage
returns to your lines, so when you look at them in ed, you'll
see a bunch of "^M"'s all over the place.
If you still have trouble, take a look at the debugging page.
The mud editor is confusing the heck out of me. It's too hard to use.
Check out the MUD Editor tutorial. It should ease the pain a little.
%^GREEN%^Can you please make the FAQ easier to read? It's too long and complicated.***%^RESET%^
I'm a lib coder, not a web designer. Cut me slack. Or, edit it
for me and show me how it's done.
%^GREEN%^*** How can I change the colors of the channel messages?***%^RESET%^
The colors are specified in /secure/daemon/chat.c
%^GREEN%^*** How do I know what other muds use Dead Souls?***%^RESET%^
Go to the arch room. Type: arch
Then type: read screen
This shows a list of muds that used Dead Souls and
joined intermud at some point. To see a list that
also includes obvious test muds, type: read printout
%^GREEN%^*** I was hanging out in the Arch room and the loudspeaker went off. WTF?***%^RESET%^
Your mud receives all sorts of network requests from the
intermud network, such are remote who (asking who is logged on),
remote finger (info on users), locate (trying to find a user
somewhere on i3), etc. Whenever your mud receives such a request,
it is announced in the Arch room. Note that these are normal,
and do not represent an attempt to undermine your security.
%^GREEN%^*** I want to test the intermud channel but I don't want to spam the ds line.***%^RESET%^
Type: call me->AddChannel("ds_test")
Then type: ds_test test
The ds_test channel is specifically for communication
testing so that ds can remain spam free.
%^GREEN%^*** The web server and FTP server don't work***%^RESET%^
To enable them at mud boot time, uncomment the "inet" line in
/secure/cfg/preload.cfg
To enable it temporarily, type: update /secure/daemon/inet
These server do not use the standard ports. The internet standard
http port is 80 and for ftp it is 21. Your mud ftp and web servers
do not use these.
Instead, the network port for your web server is 5 less
than your mud's port, and the ftp port is 1 less.
This means that if your mud is reached by telnetting
to port 6666, your ftp server will be at 6665 and your web server
will be at 6661.
Please note that the web and ftp server are not supported. They work,
but whatever security risk they pose is entirely on you.
%^GREEN%^*** I tried to log in to the FTP server but I can't!***%^RESET%^
Make sure you use your mud name and mud password, not the
username and password of the computer you are on.
%^GREEN%^*** I can't do anything with FTP. It just hangs there.***%^RESET%^
FTP is a funny sort of protocol. If you don't have a direct
connection to an FTP server (for example, you are behind a
firewall), you have to use PASV (or passive) mode. Unfortunately,
at this time, PASV is not implemented in the mud FTP server.
%^GREEN%^*** The web server gives me a 404 but I know the directory is there.***%^RESET%^
Like the FTP server, the web server is a very simple program.
It does not do directory listings at all. If you request
a directory, and it can't find an "index.html" file, it
just errors out.
Let me make this point one final, excruciatingly clear time:
If you need a webserver, use apache. The mud www server is available
as a convenience, not as a production-quality standards-compliant
intarweb server.
%^GREEN%^*** Where can I get a Dead Souls mud hosted?***%^RESET%^
That's a heck of a good question. There are many mud hosting services
out there. I hear good things about Kyndig, but that isn't specific
to Dead Souls. A good host will have a high level of service, shell
and file transfer access, etc, for which you obviously will need
to pay money. There ain't no such thing as a free lunch.
%^GREEN%^*** I moved a command from one directory to another. How do I get the new location recognized?***%^RESET%^
First, run update on the command in question.
then:
If it's not a verb: update /daemon/command
If it's a verb: update /daemon/verbs
%^GREEN%^*** The mudtime is all wrong!***%^RESET%^
The mudtime command tells you what time it is in the game, not what time
it is in the real world.
%^GREEN%^*** The time of day is all wrong!***%^RESET%^
If you used admintool to change your timezone and the time of day is still
wrong, you may be using an OS with timekeeping that Dead Souls doesn't
understand. If this is so, figure out how many hours off you are, and
enter that value into the EXTRA_TIME_OFFSET parameter in /secure/include/config.h
%^GREEN%^*** Hey this is supposed to run on Windows but it doesn't!***%^RESET%^
There are three main causes for this:
1) You are using Windows 98, Me, or below. That's unsupported and won't work.
2) You edited secure/cfg/mudos.cfg with a Windows-style editor and now the driver can't read it.
Copy the original mudos.cfg over the hosed one. If you need to change the mud's name,
don't edit mudos.cfg. Use the admintool command.
3) You are trying to run Dead Souls in a directory other than c:\ds
%^GREEN%^*** What happened to the roommaker and thingmaker?***%^RESET%^
They produced code that was often incompatible with QCS. They are no
longer supported.
%^GREEN%^*** I keep getting 'Connection to address server (localhost 9999) refused.' ***%^RESET%^
This is a harmless error. Dead Souls uses a program called addr_server to
try to resolve hostnames. However, hostname resolution is not important
to running the mud, so it's not automatically configured. If you run
addr_server with a specific port as an argument, and edit mudos.cfg to
point to that port for the addr_server, then reboot the mud, then you
will probably have hostname resolution in your mud.
However, not all OS'es handle name resolution the same, so this may not
work, even if you do everything exactly right. Either way, it doesn't
affect the mud.
%^GREEN%^*** Every now and then I use a QCS command and it fails, then I try again later and it works. WTF?***%^RESET%^
This is a rather frustrating issue, because it happens very rarely
and when it does, the error data is limited. Please email me a log
of what happened so I can analyze it.
%^GREEN%^*** When I log in, everything is screwed up, and I can't do anything!***%^RESET%^
This happens sometimes when you log out while carrying an object
with broken code. If for example, you are wearing a vest, and then you
edit the code for it, but it doesn't work anymore, then you log out,
what happens is the next time you log in the mud will try to restore an
item in your inventory that throws an error, and your login
gets stuck halfway.
If you find that when you log in things are all screwed up for
you, use the rescue login feature. For me, this means I would
login as cratylus_rescue instead of cratylus. My inventory
will get wiped before my playerfile is loaded, and I'll
be able to log in with no problems.
%^GREEN%^*** Can I charge players a fee for playing on my mud?***%^RESET%^
NO.
Dead Souls uses MudOS, and MudOS has a license that specifically
and strictly forbids its use in a commercial way. I don't care how
you use the lib, but if you use it with MudOS, you need to comply
with MudOS licensing. If you were to port Dead Souls to some other
driver that allows commercial use, then you'd be all set.
%^GREEN%^*** Can people donate money to me for the mud?***%^RESET%^
Yes.
So long as there is no quid-pro-quo, or anything
about the transaction that is legally regarded as "commercial",
receiving money from people for the purpose of running the
mud is ok. However, I am not a lawyer, so read the MudOS
license yourself.
%^GREEN%^*** I found a bug. For real. Can you please fix it?***%^RESET%^
Email me: <put my name here>@comcast.net
Please include a detailed description of the bug, and the exact
error text and commands that produced it. A log file or
screencap would be helpful.
%^GREEN%^*** How are files organized in Dead Souls?***%^RESET%^
cd / and ls to view the top level directory. The
list may be largely meaningless to you, so let's review it here:
cfg/
General configuration files for timezone and such.
cmds/
Main location of commands that don't require special access
privileges. Commands are different from verbs in that they tend
not to manipulate your environment, but rather deal with
the player's relationship to the system and/or files.
daemon/
Daemons are files that provide access to data files in an
organized way. For example, adding an occupational class
(like, say, assassin) to the game needs to be done in a
precise way in order for it not to break things. By sending
the data to the daemon first, you can be sure that the
new system configuration is entered properly. Daemons also
provide a means to access data, like "how much is silver
worth compared to gold", that is uniform across the mud, and
prevents accidental overwrites of data files by multiple
editors.
doc/
General documentation.
domains/
This is where MUD game areas go when they are complete
and ready for general play by the public. Once here, only
admins have write access to the files.
ftp/
The base for the MUD ftpd. Using the ftpd is probably dangerous
in terms of your system security, and I discourage it, but if
you are determined to have mud ftp access for your creators,
this is one way. See /secure/lib/net for the actual server. It
may or may not work. I won't support it.
include/
Include files provide a set of constants for your files. For
example, if you include <damage_types.h>, you can specify in
the code for your chainmail that it protects against
the damage type "BLADE" at a certain level.
lib/
This is the heart of the Dead Souls lib. This is the location
of the files that your objects, be they swords, shoes, or
handguns, will use as their configuration base.
log/
Log files.
news/
Announcements are made here. For example, in /news/creator
you can post a notice that you have added a teleportation
spell, and when your creators log on, they will see the message.
obj/
Contains some important templates, especially some for the QCS.
open/
Legacy directory. Kept for compatibility. Historically this
directory has served as a place where creators can put code
for others to freely modify.
realms/
This is where creator home directories are.
save/
Files that describe properties of the MUD's systems live
here. The number of limbs that a bat has, for example,
is in races.o. In classes.o you'll find the skill ranges
for fighters. Do not edit these files. They must be
modified by daemons only, or you risk corrupting them.
secure/
This directory will be described in a separate section below.
shadows/
Shadows are a controversial feature of LPC. This directory
is designed for shadow objects, but they should be very
rarely, if ever used. Basically shadow objects are objects
that attach themselves to another object, intercepting
function calls. For obvious reasons this is a security
risk, so unless you really really know what you're doing,
avoid them.
spells/
Pretty self explanatory. The spells daemon looks for spells here.
tmp/
A directory anyone can write to. Generally for swapping
data between objects, systems, or people.
verbs/
Another controversial topic. Verbs are a kind of command. For
example, go and sit and open are verbs. Specifically, verbs
are commands that interact with the user's environment. The
idea is that throw my first red rock at the green goblin
should work, and should work the same everywhere on the
MUD. Verbs are a source of debate among some people, because
to folks accustomed to add_action commands, verbs seem
excessively complex.
www/
Like the ftp directory, but for the MUD webserver.
Ok now let's take a quick look at the /secure directory: ls /secure
As you can see, /secure seems to have many of the same directories
that the root filesystem has.
The reason a /secure directory is needed is that
there are files that should not be readable by everyone, and
there are files that must be writable only by a few. The MUD security
system uses the /secure directory as a means to control access to
such files.
For example, the average creator has no business
accessing the player data files of other creators or players. Therefore
/secure/save/creators and /secure/save/players is offlimits to them.
A directory without a counterpart in / is /secure/sefun. This
is where simulated external functions reside.
%^GREEN%^*** What are sefuns and efuns?***%^RESET%^
First let me explain that the driver has built-in
functions that are available to the mud. For example,
type eval return find_player("cratylus") , but replace my name
with yours. Your player object pointer will be found and returned
to you (more or less. strictly speaking it's more complicated).
The driver provides this function. Because it is "external"
to the mudlib, that is, it's in the driver and not the lib,
it is called an external function, or more commonly, "efun". The
idea is that certain actions you ask the mud to perform are
so common that they are made available MUD-wide.
Efuns are ridiculously useful and powerful, and because
they are in the driver as compiled code, very fast. A near-complete
set of efun documentation is available in /doc/efun.
However, the driver does not contain every possible
MUD-wide function you might want. For example, there is a
tell_object() efun, which lets you send a message to an object
such as a player. The syntax is something like this:
tell_object(find_player("cratylus"),"Hi.");
Which doesn't look like much, but believe me, this
kind of stuff adds up. I wanted to make this simpler, so I
used what is called a sefun, or a simulated efun. It is
a function that is available lib-wide, but it isn't in
the driver. Instead it is provided by the lib itself (the
master daemon, specifically). By adding the appropriate code
in /secure/sefun/ I have now made available a tell_player() sefun,
which works like this:
tell_player("cratylus","Hi.")
This simplification of code will become more obviously
useful to you as you get more coding under your belt. Most
sefuns are documented in /doc/sefun.
%^GREEN%^*** Whew! Ok now I know where stuff is. What's next?***%^RESET%^
You probably want to examine how objects are written.
Type goto /domains/town/room/road and wander around town
a bit. If you want to see the code for something, for example,
the beggar, about beggar should do it, provided the beggar is
in the room.
To see the filenames of the objects around you,
type scan here, or scan me to scan your own inventory.
If you've never coded before, this is the hard part.
To understand what you're looking at when you run commands like
more /domains/town/weap/orcslayer.c you need to get comfortable
with LPC.
The brute force way of doing this is copying stuff
and then changing the descriptions, thus making new stuff.
This will work, but you'll waste time looking for examples of
exactly what you want to do..and you may not find them.
Instead, learning LPC will let you create whatever
you want, without relying on templates.
This means that now you must read the LPC Basic
manual, then the LPC Intermediate manual. As admin, your
creators will expect you to know what's in there.
On your person or in the chest in your workroom is
the Creators Manual. Read both the Players Handbook and
the Creators Manual from cover to cover.
%^GREEN%^*** Oh, man, you're kidding! Those are, like, books! Can't I
just start making stuff?***%^RESET%^
Well...ok. But you need to go through the docs
soon, ok? In the meantime, read the QCS chapters in the
Creators Manual to get you quick-started in the creation
process. Remember you need to be holding your Creator
Staff in order to access the QCS commands.
Other useful tools in your chest are a remote
control and a medical tricorder.
%^GREEN%^*** Everything is su-u-u-u-p-e-e-r-r-r s-s-l-o-o-o-o-w-w-w***%^RESET%^
First, make sure you are using the latest available version of
Dead Souls (check here or here). Older versions of Dead Souls
are known to have nasty memory leaks.
Next, see if you have runaway objects. An object can be coded
to do really unpleasant stuff like replicate itself over and
over until it brings the mud to its knees. Find out how many
objects are loaded by typing: eval return sizeof(objects())
If the count is in the thousands, and only a few people are
logged on, you've got a runaway. Most often this involves
NPC's doing stuff you didn't expect. Destroy all loaded npc's
with the following command:
eval return filter(objects(), (: inherits("/lib/npc",$1) :))->eventDestruct()
If the lag clears up, you found the culprit. If not, see if
the callouts list is clogged with the command: callouts
If all else fails, reboot the mud and ask for help on the ds line.
Please note that the rage virus (especially if unleashed
in the menagerie) is notorious for redlining the mud. Having
hundreds of NPC's all engaging in simultaneous combat
while infecting each other with a rapidly spreading hostility
virus can be expected to impact overall performance. So please try
to avoid the rage virus unless you are specifically stress testing
your system.
%^GREEN%^*** Is Dead Souls secure?***%^RESET%^
The short answer is no, nothing I know of is "secure" in the
sense that you don't need to continually pay attention to it. If the
question is "Is Dead Souls particularly unsafe to run?" then the
answer is no. Just like any other Internet program you use, Dead Souls
is not an obvious security risk, so long as it is not used carelessly.
And, obviously, games of any kind, including Dead Souls, should never
be installed on any mission-critical, national security, public
safety, or health care server.
Dead Souls security involves two separate spheres:
1) The binary executable and the system that runs it.
2) The mudlib and the code that you use and create.
The first sphere is probably most important. Presumably
you plan to run a mud on a computer that does other things too,
and you want to keep those things separate from your mud. The
most important thing to do is to avoid running Dead Souls as a
privileged user. In the case of Windows, this means that the
program should not be run by Administrator or anyone in the
Administrator group.
For unix users, this means that the driver should not run
under uid 0 (root).
The reason for this precaution is that if some genius
hacker manages to exploit some unknown weakness in the program,
it is better that the process they hack doesn't have full admin
privileges to the box.
This caution has little to do with Dead Souls specifically.
It is a warning I'd give to anyone planning to run any kind of network
server. You should take your own security seriously, and
if you do not understand your own security situation, you need to take
a step back and ask yourself if running a mud at all is a good idea.
Sphere 2 is lib security. In older muds, file and directory
privileges were handled by attributes on the files. If a file's
user id (UID) matched a user's UID, then that user had full access
to it. Such systems often had complex systems that evaluated
effective UID (EUID) based on the file's attributes, its parent
directory, the user's ID, possibly group id, etc. This is an
entirely valid security model, but because of its complexity,
it tended to be exploited easily and often. If you don't
stay 100% on top of such a system (just like any OS), there's
no way to be sure you won't rooted.
With stack security, privilege management is much, much
easier. A file's privilege is based solely on its location. If
a user doesn't have read access to /foo/bar/ then she can't read
or modify /foo/bar/file.c. If someone with privs to that location
copies the file to somewhere else, then the privs of that new location
are in force on the file.
The "stack" part of stack security comes from the mud
evaluating the privileges of all the objects involved in the
access request. If you're unprivileged and you manage to get a
privileged object to make the access request for you, the access
will fail, because you are unprivileged, and you are still part
of the function call stack (i.e., the list of instructions that
form a chain between the command and the intended event).
Granular (more detailed) modification of user privileges
can be done by changing files in /secure/cfg to grant
users and groups specific privileges.
- Cratylus
Dead Souls Homepage
