# BYOND Host Administrator's Guide

## Contents

Overview
Installation
Administration
Security
Integration with the Web

## Overview

Running a BYOND host server is similar to running a web server, except instead of serving up web documents, it serves up BYOND worlds. You might do this for your own personal worlds or as a host provider for others.

The main difference between a BYOND world and a web document is that a BYOND world is inherently designed to be used simultaneously by multiple people. When multipel users connect to a world through a host server, they do not each download a copy of the world. Rather, they all find themselves in the same world, running on the host machine.

Of course, you don't need to run a host server in order to host BYOND worlds. You can just manually run BYOND worlds either in Dream Seeker or Dream Daemon. A host server allows you or others to update the world files from a remote location or to have worlds start up and shut down automatically as they are used.

The host server itself is entirely written in DM. It runs in Dream Daemon, typically on a fixed port and is usually registered in BYOND Hub as `byond://YourKey.Host.SilverGate` or whatever name you give it.

A single host server may be used to serve up any number of sites and any number of worlds within those sites. Each site is identified by the BYOND key of its primary owner. Continuing with the example above, the world named "MyWorld" in a site owned by "James Byond" would be accessed via `byond://YourKey.Host.SilverGate/JamesByond/MyWorld`. This works whether the world file is `MyWorld.dmb` or `MyWorld/MyWorld.dmb`. Capitalization in the URL is arbitrary.

If you intend to be a big host provider with multiple sites, it would be good to register a personal host pointer for each site you host. For example you could register a hub entry called `YourKey.Space.JamesByond` which points to the login URL `byond://YourKey.Host.SilverGate/JamesByond`. The advantage of this is that you can move the site from one host machine to another and the user (James Byond) doesn't have to even be aware of it. He just continues to use his personal URL and you can point this to any particular place you want.

Note that the games being hosted will typically have their own hub entry, so players will not usually be aware of either the `YourKey.Host` URL or the `YourKey.Space` URL. For example, a hub entry could be created with the name `JamesByond.MyWorld` and this would point to the login URL `byond://YourKey.Space.JamesByond/MyWorld`.

This may seem overly complicated, but this chain of hub entries gives the the host provider and the site administrator the ability to change things internally without disruption. For example, if the host provider needs to move the site to another machine, this can be done without bothering the site admins, and if a site admin moves a world from one host provider to another, this can be done without having to advertise a new URL to all the players.

That said, there is no requirement that you register any hub entries, especially when you are just testing. You can access the host server directly by its Internet address. For example, if you are running the host server on your own machine on port 6000, you can connect to a world directly via a URL such as `byond://localhost:6000/JamesByond/MyWorld`.

## Installation

Installing a host server is easy. Just go to Dantom.HostServer. This will install everything you need.

If you wish to run multiple host servers on your machine, you will need to copy the files in `MyHub/dantom/hostserver` once for each server you wish to run. Otherwise, you can just run directly from the location where Dream Seeker put it.

If you are hosting on a UNIX machine, the BYOND software installation comes with a host server, so you can set it up right when you install BYOND. In UNIX, you've got a very cool extra option known as -suid. In this case, the host server runs as the root system user and is capable of hosting worlds out of the home directories of other users. This is a lot like web hosting in a UNIX environment. We'll have more to say about that in another section of this document, because it turns out that some of the host tools work nicely through the web and can be used to administer a web-site just as well as a BYOND site.

## Administration

Administration of the host server is basically a matter of setting up a few options and creating or removing sites.

The manager of a host site is known as the root. When the host system is installed, a special site is created for the root. The main thing that it contains is the root administration tool. To access it, you must be listed in the system or user cfg/admin.txt configuration file. (The host does this for you automatically when you run it directly in Dream Seeker the first time.)

If you like doing things by hand, you can just edit hostconf.txt in a text editor and copy files around yourself. That's all the root administration tool does for you. The comments inside hostconf.txt provide many hints about what to do.

Another alternative is to copy the admin tool (root.dmb) into a CGI directory and administer your host server through the web. It'll ask you for the path to your host the first time, but otherwise, everything should be the same.

## Security

In the simplest setup, all hosted worlds run as the same system user. On a windows platform, that's your only option. In UNIX, you can do some fancy stuff that we'll get into below.

Since users can upload any arbitrary `.dmb` program, this would be a huge security hazard if not for BYOND's safe mode execution. (Even people who don't intend to cause problems can make mistakes, especially with hackers, who do want to cause problems, connecting to the worlds.)

In safe mode, Dream Daemon only allows the `.dmb` to access files within the designated safe directory. The host server sets this to be the top-level directory for each host site, so each site can access its own files and not those of others. In DM code, this top directory can be referred to by starting a file path with tilde (e.g. ~/data/file.sav).

Safe mode does not allow any use of the `shell()` instruction, so it is not possible for a `.dmb` program to execute other commands or programs on the computer. The vast majority of BYOND worlds never need to use anything but safe mode.

### The suid Option

On a UNIX platform, you have access to an option known as `suid`. When a world gets started up, it normally runs as the same system user as the host server. With `suid` mode, it sets the user id to the owner of the `.dmb` file. For that to work, the host server has to run as root, so the basic prerequisit is that you have root access to the host machine.

In `suid` mode, sites are no longer stored directly in `host/home`. Instead, a symbolic link is stored there. By default, this points to the home directory of the system user associated with the site. This allows each user to have direct access to their files through the UNIX shell or whatever other services the system provides.

Since the operating system provides its own security restrictions on what each system user may do, and since you can assign a different system user to each hosted site, in `suid` mode you are free to turn off safe mode and grant full trusted mode execution. Most worlds don't need it, but some specialized worlds might need to use `shell()`.

## Integration with the Web

When hosting on a web-enabled UNIX platform (using `suid` mode), it is nice to have both BYOND and web space in the same account. The site and root administration tools can be copied into a CGI-enabled web directory for use through the web. There might also be any number of interesting uses of a dual BYOND-web hosting system, since it is possible for web applications to interact with BYOND worlds (see world.Export() and Dantom.CGI).

For execution of CGI-enabled .dmb's through the web to work, you have to also run a web server. Since there are a lot of different possibilities, we'll just discuss the setup we have personally used.

CGI, by the way, is the common term for applications that respond to an HTTP request, typically spitting out a bunch of HTML to be displayed by the user's web browser.

### Enabling CGI

Some websites are set up with all CGI applications in a separate directory, such as `cgi-bin`. Others allow you to run CGI's right out of the document directory. In the latter case, the server has to know how to recognize a CGI program so it doesn't just send the contents to the browser. In Apache, you can edit httpd.conf and add `.dmb` to the list in the `AddHandler` directive. You may also want to add `index.dmb` to the `DirectoryIndex` list. If all else fails, just rename your `.dmb`'s to `.cgi` and things should work in a normal setup.

### Initial Files

When the host server creates a new account, it copies the contents of `host/shared` and (if enabled) `host/shared-web` into the site's top directory. You should move files around in `host/shared-web` to match the desired location of files. For example, if your site supports CGI apps in the documents directory and if it expects documents to be in `~/public_html/`, then you should rename `host/shared-web/web/` to `host/shared-web/public_html`.

### Trouble-Shooting

If `.dmb` CGI apps are not working, here are a few things to check.

- The `.dmb` file must have execute permission turned on (`chmod +x file.dmb`).
- The first line of a CGI-enabled `.dmb` must be something like `"#!/usr/local/byond/bin/DreamDaemon -CGI -logself -trusted"`. This is known as the executor. You can see it (and even edit it) in a text editor or with `head -n 1 file.dmb`. If you have DreamDaemon installed somewhere else, either create a symbolic link from this standard location, or change the executor.
- Of course, double-check that your web server has CGI execution enabled in the location of the `.dmb`.
- Also make sure the web server is running CGI applications with the system user id of the site owner. This requires the web server to be run as root or, if you are only hosting one web-enabled site, as the user id of that site.
- Check the `.log` file if there is one. Any failures reported there might help fix the problem.