Dead Souls - Installation FAQ

By Cratylus @ Frontiers, February 2006. Updated March 2007.

IMPORTANT NOTE: After installation, check the HOTFIX PAGE for late-breaking patches.

NOTE: As of June 6 2006 the Windows version IS AVAILABLE AGAIN.

# FAQ Index

- Is this FAQ really necessary?
- Where do I get Dead Souls?
- Where are the separate UNIX and Windows versions?
- Where do I get patches?
- Should I apply the available patches during an install?
- How do I install the Windows version of Dead Souls?
- Hold up, these Windows instructions aren't working
- How do I install the UNIX version of Dead Souls?
- I'm having trouble getting Dead Souls for UNIX to work
- Why does compiling MudOS for Dead Souls throw so many warnings?
- Why is there a windows-format mudos.cfg in /secure/cfg? I'm running unix.
- How do I enable database support?
- How do I upgrade from one version of Dead Souls to another?
- When I log out after starting the mud, problems happen.
- Ok, it's running. Now what?

# Is this FAQ really necessary? (Back to Top)

Normally, no. If you just follow the instructions included in the Dead Souls packages, you'll be fine 90% of the time. However, a non-trivial number of folks have run into difficult circumstances. For those folks, this document is meant to illuminate how the install process works, why some things are as they are, and suggest some solutions to the more common obstacles.

# Where do I get Dead Souls? (Back to Top)

You should only ever download from the site listed below. Some other sites tend to mirror these or copy data, then fail to update their data regularly. The following will always have the most recent versions.

Download the stable version from the following:

- http://lpmuds.net/files/deadsouls/ds2.4.zip

Download the latest version here:

- http://dead-souls.net/code/alpha/

The alpha version has lots of neat new stuff. Some of the new stuff is still not 100% production quality. If new features that are still under development are upsetting to you, you may be better off using the "stable" version instead.

# Where are the separate UNIX and Windows versions? (Back to Top)

Starting in Dead Souls 2.0r22 the two separate versions have been merged into one distribution download file. Now it doesn't matter whether you want to use Dead Souls on Windows or UNIX, there's just one file to download, and it contains everything you need for both operating systems.

This merge accomplishes the following:

- Ensures 100% identical lib versions for the different OSes.
- Limits the clutter involved with releasing new versions.
- Lowers the amount of labor and time involved in releasing new versions.
- Simplifies installation and upgrades for new users.

# Where do I get patches? (Back to Top)

- http://dead-souls.net/code/patches/

# Should I apply the available patches during an install? (Back to Top)

No. Patches are for already-installed Dead Souls muds. A new Dead Souls install does not need and must not use patches. If you're upgrading from one Dead Souls version to another, please read the upgrade section further down in this document.

# How do I install Dead Souls in Windows? (Back to Top)

NOTE: If you are using Windows, USE THESE INSTRUCTIONS. There is no benefit in trying to download Cygwin and modify the UNIX source code and trying to get it to compile in Windows, unless you know exactly what you're doing. Yes, people have tried to do this and complained.

First make sure you are running Windows NT 4, Windows 2000 or above, Then:

1. unzip the distribution file
2. move and rename it so that it is c:\ds, and that the folders c:\ds\win32 and c:\ds\lib are where the binary and library files are, respectively.
3. run c:\ds\runmud.bat
4. if you lack a favorite telnet client, open a command line window by clicking on Start->Run... and entering: cmd
5. connect to your Windows computer by telnetting to port 6666. If you are using the command window, type: telnet localhost 6666
6. Enter the name you want your admin to have, and answer the questions provided. Make sure you are the first person to log in, because that first person is automatically made admin.
7. When you finish entering the admin's info, the mud will automatically reboot.
8. log in as your admin character.
9. change your mud's name with the admintool command. Navigate to the "driver" menu (as of this writing, it's option 4, and then the "change the MUD's name" option (as of this writing, it's option r). Enter the name desired, allow the mud to shut down.
10. log in again after the mud reboots.
11. check the HOTFIX PAGE for late-breaking fixes.
12. start reading the guide and the handbook and the manual.

# Hold up, these Windows instructions aren't working (Back to Top)

There are a few common reasons for this.

- A recent fix may be available. Check the HOTFIX PAGE for late-breaking fixes.
- Download only from the sites mentioned above. Those are the only ones sure to have the latest version. Other sites can be out of date.
- On at least one occasion, Winzip has somehow corrupted the archive as it was extracted. Try using another decompression utility, like winrar.
- Most Windows PC's these days have firewall software installed. If you try to connect but aren't able to, there's a good chance your connection is being blocked by your firewall. Disable your firewall temporarily and try to reconnect. If the problem goes away, you know now that you have to somehow configure your firewall to allow incoming TCP connections on port 6666.
  Note: You may also have to permit outbound TCP connections to port 23 on IP address 149.152.218.102 if you want your mud to join the Intermud3 network.
- You might not be using c:\ds as your base directory. Make sure you are. Putting the mud files on another drive or another folder will cause the mud not to run.
- Trying to use Windows 98, 95, Me, or 3.x will simply not work. Sorry. Those are not server class operating systems and they use technology incompatible with the mud's requirements.
- If you connect to the mud for the first time, but then it hangs, look in c:\ds\lib\log\runtime and c:\ds\lib\log\catch. Those are error log files. If you see stuff about files or directories not existing, then the problem is probably that your decompression program didn't unpack the files right. Start over. Download winrar and use that to uncompress.
- If the mud starts but you get lots of bizarre errors, there may be a couple of reasons for this:
  - If the c:\ filesystem is NTFS, and the user you logged in as does not own the ds:\ folder, things will fail in odd ways. What is happening is that the mud is trying to write files in a folder it doesn't have permission to, and things get all hosed up. Make sure you have read/write privileges to the c:\ds folder.
  - Zip problems. Some unzipping utilities are known to incorrectly decompress zip files. Specifically, sometimes an archive that contains empty folders will not write those empty folders to your disk. This could cause problems for the mud. If you get lots of errors and things don't work right, and you are sure that you have read/write access to c:\ds, then try reinstalling but with a different unzip utility.

# How do I install Dead Souls in a Linux/UNIX box? (Back to Top)

- Login to your shell. Follow the instructions provided by your hosting service or your unix documentation to know how to do this.
- Download the distribution package. For example: wget http://dead-souls.net/code/dead_souls_alpha.zip
- DO NOT use fileroller (a GUI based app) to decompress the package. If you ignore this warning you are very likely to end up with really confusing errors and problems. Instead use the normal unix command line. For example: unzip -d ds dead_souls_alpha.zip
- NOTE: If you don't use the "-d" flag to specify the name of the new directory you want to create, the archive may dump everything into your current working directory, which may look ugly if that's not your intention.
- Don't use an existing driver binary, even if it's from a previous (or even the same) Dead Souls distribution. If you're doing a fresh install, always, always, always do the complete and exact installation procedure, including the driver compile. If what you're looking to do is an upgrade, read the upgrade section further down in this document. Once we're set on those requirements and you've uncompressed the tarball, we can continue with the installation procedure.
- cd to the directory where all mud files reside. Called $MUDHOME in the rest of these UNIX instructions. You can determine your current directory by typing pwd at the shell prompt.
- cd to v22.2b14
- type: ./configure
- type: make
- type: make install
- If the previous step fails, just manually copy the "driver" file into $MUDHOME/bin/
- edit $MUDHOME/bin/mudos.cfg (provided). The two lines to change are mudlib directory and binary directory. For example, if your $MUDHOME is /home/joe/mud, then the mudlib directory line will look like this:
  /home/joe/mud/lib
  and bin:
  /home/joe/mud/bin
- edit $MUDHOME/bin/startmud (provided) and change the $MUDHOME definition.
- manually run the mud: $MUDHOME/bin/driver $MUDHOME/bin/mudos.cfg . If you properly edited the startmud script, you can just type: ./startmud
- telnet to your machine, using the port specified in mudos.cfg. For example: telnet localhost 6666
- Create a new user. Just answer the questions. Make sure you are the first person to log in, because that person is automatically given admin privileges.
- You'll get booted out. Reboot the MUD, telnet back in, and you're now running Your Very Own MUD. If startmud is running, the MUD should restart automatically.
- check the HOTFIX PAGE for late-breaking fixes.

# I'm having trouble getting Dead Souls for UNIX to work (Back to Top)

- First, stop using Fedora. Ha ha just kidding.
- If you get this: "make: *** No rule to make target `obj/malloc.o', needed by `driver'. Stop.", just type "make" again, or "make -j 1"
- Some hosting providers give you a robust environment that requires UNIX expertise to handle. For example, I know of folks that use Genesis Muds to host, and run into all sorts of file permission conflicts, umask issues, etc. While I'm happy to provide guidance to some degree, you do have to take it upon yourself to become familiar with the OS you're using. As much as I want to be helpful to you on this, getting you up to speed on being a UNIX server admin is way beyond the scope of this little document. Whomever it is that you pay money to, ask them for documentation. Sorry if it sounds rude....there's only so much I can take responsibility for.
- Your compiler may be trying to run a distributed "make" by default. That's a no-go for MudOS. Try disabling that at compile time by using this instead of the normal make command line:
  make -j 1
  make install
- A recent fix may be available. Check the HOTFIX PAGE for late-breaking fixes.
- Some versions of Linux, specifically those running in 64-bit mode or smp mode, are incompatible with the default memory allocation DS MudOS uses. If you keep getting segmentation faults complaining about malloc, this is probably what is happening. To correct this, you will need to edit v22.2b14/local_options and make these lines:

  #undef SYSMALLOC
  #define SMALLOC
  #define DO_MSTATS

  look like this:

  #define SYSMALLOC
  #undef SMALLOC
  #undef DO_MSTATS

  then:

  make clean
  make -j 1

  The memory allocation for 2.3a1 and above is already set for 64bit/smp compatibility, so this editing should not be needed if the version you are installing is sufficiently recent.

- Download only from the sites mentioned above. Those are the only ones sure to have the latest version. Other sites can be out of date.
- Most of the problems with unix installs involve permissions conflicts. If you uncompress the package as root user, for example, then try to run it as an unprivileged user, the process won't be able to read and write to the directories it uses, and errors will result. If you uncompressed as root and want to run it as another user (in this example, username: joe), then you'll want to cd to the directory that contains the mud directory and issue a chown command, like this:
  su - root
  cd /home/joe
  chown -R joe ds2.1
- If you don't follow the instructions, and instead use a previously compiled driver, you may skip a step which copies a unix-compatible mudos.cfg file over the default Windows-compatible mudos.cfg. To correct this, copy the template config into the proper directory:
  cd /home/joe/ds2.1
  cp bin/mudos.cfg.orig lib/secure/cfg/mudos.cfg
- Then edit lib/secure/cfg/mudos.cfg to point to the correct bin and lib directories.
- Another problem that can occur if you use an older driver is that the lib may expect options or features that the older driver doesn't support. If this is what's happening, you need to start over, but this time actually follow the instructions exactly, step by step.
- If you get a bunch of errors about a missing log directory, you probably used fileroller to uncompress the tarball. Fileroller is apparently the default uncompression utility for Fedora. Other Linux distros may also use it. Start your installation over and this time use the command line as directed in the installation instructions.
- If the driver compile fails complaining about extra_ref in parser.c, then you probably followed older instructions, and not the instructions included in the latest package. You should no longer use ./build.MudOS (unless you know exactly the ramifications of what you're doing). Instead use the ./configure script as per the current instructions, which you should follow closely.
- If the driver craps out complaining about a hosed up swap file, you're probably running Fedora, and you probably haven't changed your hostname from the original "localhost.localdomain" or whatever nonsense they use. What mudos expects is that when it asks your machine for its hostname, that it receive something like "alpha", and not something like "alpha.bravo". If your machine is under the impression that its name is localhost.localdomain, it will supply that name to mudos, which will eventually choke on it.
  If you're good at C, you can edit lines 66 and 76 of v22.2b14/swap.c and correct this behavior. But the common sense fix is to stop being a noob and give your computer a proper hostname already.
- Some hosting services may provide you unix shells so tightly restricted that you cannot successfully compile the mudos driver. You may need to submit a problem ticket with your hosting service to resolve the issue. Let them know that the source compiles fine on various versions of SuSE and Fedora, as well as Solaris 8, 9, and 10, various BSD's, and even IRIX (!). If you can get them to give me a free temporary account for testing purposes, I'll take a look and see if I can help.
- If you've tried everything but the compile keeps breaking, try compiling as root (obviously a last resort, and just for testing).
- On Ubuntu, before running the compile, try typing: export CC=gcc-3.4
- If you get errors complaining about not finding bison or yacc, what this means is that compiling the driver requires these tools, and the configure script can't find them. They are either in a non-standard location, or your host simply does not have them installed. If you run the host box, either install bison (or yacc), or add their path to your PATH environment variable. If you are not the host computer admin, politely explain to the admins that you can't compile without bison (or yacc) and could they please install it for you.

# Why does compiling MudOS for Dead Souls throw so many warnings? (Back to Top)

Beats me. This is one of those complaints I don't really know how to respond to. At the end of the compile, you'll have a driver that works. It's been tested on GCC 2, 3, and 4. It's worked for Fedora Linux, SuSE Linux, and various other versions of UNIX and UNIX-clone environments. It works. Ignore the compile schmutz.

# Why is there a windows-format mudos.cfg in /secure/cfg? I'm running unix. (Back to Top)

This is a symptom of my obsession to have the Windows lib and the unix lib be absolutely identical. During a fresh install, this file is overwritten with a unix version, if you follow the install instructions.

# How do I enable database support? (Back to Top)

I don't know. I don't understand databases at all, so it's pointless for me to try to get that MudOS functionality working. If you develop a procedure for it, please share it with me and I will document it so others can benefit from your leetness. I might suggest that it's probably easier to do this using LPC sockets in the lib, rather than trying to do it using driver-level support. If you don't know what that means, you'll need to play around with Dead Souls for a while, get the hang of it, and then revisit the question.

# How do I upgrade from one version of Dead Souls to another? (Back to Top)

For your convenience, patches are available to move from one minor revision of Dead Souls to another. But there isn't a patch for every possible upgrade. There is a patch to upgrade from ds2.0r12 to ds2.0r14, for example, but there is no patch to upgrade from ds2.0r10 to ds2.0r14. As of now, there are no plans to make patches to upgrade from one version of Dead Souls to another. For example, do not expect a ds2.0 -> ds2.1 patch.

The upgrade for both Windows and UNIX is the same. Basically a Dead Souls patch is a pretty unsophisticated upgrade system. In the case of the UNIX patch, you use the tar command to copy the patch files over your existing lib directory.

In the case of the Windows patch, it is a folder called lib which you copy over your mud's c:\ds\lib folder. Sometimes just overwriting is insufficient to fully bring up a previous release to the current release. In such cases, a daemon called update.c is included, which contains instructions for detailed modification of specific files. These instructions are read by the mud and executed automatically after reboot.

Obviously, this kind of update patching is intended for muds that do not do extensive lib system rewrites. For example, if you are running ds2.0r21, and your mud creation has been limited to individual home directories and the domains/ directories, then an upgrade to ds2.0r22 and beyond will be utterly painless.

On the other hand, if you've done extensive customizing of the player object, simulated efun subsystem, daemons, and so forth, then you may run into problems after an update. The typical update patch does include some changes to the player object, for example, so the indiscriminate overwriting of the previous information with the updated files means that your work basically disappears.

For this reason it is critical always to perform a full backup of all your mud files before implementing a patch upgrade. Carefully follow the instructions included in the patch releases to ensure optimal effect. Because these instructions are not expected to be static, the details will not be included in this document. Read the /doc/RELEASE_NOTES file to know what has changed between releases and to determine whether an upgrade is worth the risk. Please note that RELEASE_NOTES contains an overview of major changes. It does not document every difference between versions.

# When I log out after starting the mud, problems happen. (Back to Top)

If you're running a modern UNIX, you have two main options for running the mud in a "backgrounded" way that survives your logout.

nohup

The first is the nohup command. This is a sort of legacy command from modem days, but it does the job of keeping processes running even if there's no terminal attached. To use nohup in this way, your commands might be something like this:

cd /usr/games/ds/bin
nohup ./driver ./mudos.cfg 1>/dev/null 2>/dev/null &

The /dev/null redirects output to a null device. If you don't do this, nohup will save all stdout/stderr output to a file, and this may fill up diskspace more quickly than you expect, so make sure to use the /dev/null redirecton to avoid this problem.

If your startmud script has been correctly edited (it's important that it have the correct MUDHOME directory specified, in this case, "/usr/games/ds"), then the command lines might be:

cd /usr/games/bin
nohup ./startmud 1>/dev/null 2>/dev/null &

The advantage to using the startmud script is that if you shutdown the mud from inside the game, it will automatically restart. The disadvantage is that you need to log into the shell and kill the script if you want to actually shut down the mud and keep it down. A potential risk when using startmud is that if you have not edited it correctly, or if there is a problem with the mud, you may have the script fire off a continuous loop of trying to restart the mud. Not only is this ugly to look at and inconvenient until fixed, it may also anger the person who runs the computer you're doing this on, as it may chew up resources. So, if you use the startmud script, *make sure it works* before running it in background mode with nohup.

In at least one case, using nohup this was did not work for someone. I never received a clear explanation of why this was, but for them, the following technique worked.

screen

This command ought to be default in any UNIX anywhere, but alas, it sometimes is not. If it's not available on your system, you can try to download the source from here: ftp://ftp.gnu.org/gnu/screen/

What this program does is let you run console applications in a virtual terminal, so that you can detach from the terminal, work on something else, then reattach to resume the program already in progress. Rather than pausing it, screen just runs whatever it is in a sort of backgrounded way. Way cool. In the following example, I refer to the "Ctrl" key like this: <Ctrl> . When you need to press That key and another key in combination, the notation I use looks like this: <Ctrl>-a, which means "hold down the 'Ctrl' key, and then press the 'A' key".

To run Dead Souls in a screen session, it might look like this:

cd /usr/games/ds
screen -S deadsouls
./startmud
<Ctrl>-a
d

You may wonder what that 'd' is doing all by itself there. What <Ctrl>-a does is tell your screen session to pay attention to the next key you press, because that is a screen action it needs to take. In this case, the key is 'd', which means "detach". When in a screen session, if you type <Ctrl>-a then d, you drop out of the screen session and resume whatever terminal you were in before you invoked screen. Your application will be happily chugging along in the virtual console you left behind. To reconnect to the screen session you detached from, the command would look like this:

screen -r deadsouls

The full grooviness of the screen command is beyond the scope of this FAQ. For more info on it, at the UNIX shell type: man screen

Microsoft Windows
If you're running Windows, then you'll need to figure out how to make Dead Souls run as a service. One way is to download and use these scripts contributed by Saquivor @ Eternal Souls.
Another is to mess around with your windows services and do it manually. Unfortunately, I am not a Windows server person, so you'll need to search Google for the appropriate docs.

# Ok, it's running. Now what? (Back to Top)

Log in and read the following:

- The in-game Player's Handbook
- Read the Dead Souls Admin FAQ.
- Read the Dead Souls Creator's FAQ.
- Read the Quick Creation System Example Page.
- Read the Debugging Guide.
- Read the Editor Tutorial.
- The in-game Creator's Manual.
- The in-game Administrator's Guidebook.

# The End (Back to Top)

Return to Dead Souls Homepage

Last Updated August 2006