Dead Souls - Installation FAQ

By Cratylus @ Frontiers, February 2006. Updated November 2008.

# 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?
- Migrating from Windows to UNIX fails horribly.
- 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 the driver 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?
- How do I compile a 64 bit driver?
- When I log out after starting the mud, problems happen.
- I put the mud in a Linux startup script, but it won't start when I reboot!
- 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://dead-souls.net/code/dead_souls.zip

Download the latest alpha version here:

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

The alpha version often 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)

Patches are deprecated in favor of liveupgrade. For exceptional situations, however, or for very old muds that still need them, they are here:

- 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. See if any upgrades are available by typing: liveupgrade all
13. If files are downloaded, apply the upgrades by typing: liveupgrade apply
14. If you get nothing but a repeating message, cancel the upgrade by typing: liveupgrade cancel
15. Start reading the guide and the handbook and the manual.

#

# Migrating from Windows to UNIX fails horribly (Back to Top)

The main problem you're likely running into is that Windows and UNIX handle text files differently. In particular, object persistence files (.o files) saved under Windows may have additional characters that the UNIX driver won't tolerate. The UNIX command "dos2unix" might help...or it might not. You might need to use the .o files from the default distribution (sadly losing whatever was in your old ones).

It may also be that your Windows driver is much older than the driver for the UNIX version you're migrating to. It might be a good idea to hunt down the source code for the specific lib release you're using (for example, 2.1.1) and compile that for your driver.

The short and sad answer is that such a migration can go wrong in so many ways that it's beyond the scope of help this document, or I as maintainer, can provide.

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

There are a few common reasons for this.

- If your friends can't connect, read this: http://dead-souls.net/ds-admin-faq.html#129
- If your mud seems superslow when you start it, just be patient. It is building up a list of the files in your mud, and this can make it seem like you are hung or crashed.
- 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 for more than a few minutes, 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 you're seeing errors about stuff like economy.o, and your computer uses a non-English version of Windows, you may be running into a character-set problem. On the UNIX version of DS, this is pretty easy to fix with a runtime variable. On Windows, I am not sure it is possible. What is happening is that the mud expects numbers in the form: 3.15 rather than 3,15 and is unable to handle your computer's way of notating the decimal. I do not know the fix for this: if you find it, please share it with us.
- 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.
- If you are using Ubuntu, you may need to install compiler tools and bison:
  apt-get install libc6-dev
  apt-get install bison
- 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 the driver source. This may be "v22.2b14" or it may be "fluffos-2.*"
- 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.
- Start reading the guide and the handbook and the manual.

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

- If the configure script complains about not finding a C compiler, but you know you have one, try: apt-get install libc6-dev
- If the configure script complains about not finding bison or yacc and you are the server admin: apt-get install bison
- If your mud seems superslow when you start it, just be patient. It is building up a list of the files in your mud, and this can make it seem like you are hung or crashed.
- 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"
- If you are using a 64 bit Linux SMP kernel, and when you try to log in the login freezes, try this: http://lpmuds.net/forum/index.php?topic=490.msg2274#msg2274
- 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.
- 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.10
- 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.10
  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 might 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, you will probably need to change your apt-get source (System->Administration->Software Sources) then apt-get install bison and apt-get install libc6-dev
- 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 the driver 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 driver 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)

Patches used to be provided, but this was a cumbersome and tedious process. There is now a liveupgrade command for painless upgrading.

The upgrade for both Windows and UNIX is the same. Basically a Dead Souls liveupgrade is a pretty unsophisticated system. It just copies over new files over old files.

Obviously, this kind of updating is intended for muds that do not do extensive lib system rewrites. For example, if your mud creation has been limited to individual home directories and the domains/ directories, then an upgrade should be mostly 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 liveupgrade command 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.

How do I compile a 64 bit driver?

Assuming you are using a 64-bit AMD processor and running a 64-bit OS on it, you can enable the compilation of a 64-bit driver by editing fluffos*/build.FluffOS and changing:

ENABLE_M64=0
to

ENABLE_M64=1

Then re-do the compile with:

make distclean
./configure
make install

If this fails, you are probably either not running a 64-bit AMD processor, or not running a 64-bit OS on it.

# 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.
I put the mud in a Linux startup script, but it won't start when I reboot!
An apparent peculiarity of Fedora is that if the command line specified in your start script
doesn't redirect stderr and stdout to /dev/null, the program fails to run. Also, if you don't
properly background it, you may end up hanging the computer and preventing anything
else from running.
Therefore, in your start script, your command line should have redirection and backgrounding.
It might look something like this:
/mud/ds/bin/startmud > /dev/null 2>&1 &
Other recent Linux distributions may have the same quirk.

# 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 December 2007