AltME AltME User Guide - AltServe Operation
Updated: 8-Jan-2010


Chapter Contents:

Return to Contents

Copyright 2006, Safeworlds Inc.

Introduction

AltServe was designed to allow businesses and organizations to run private AltME worlds from a server, rather than from a client. All of the data and files for your world will reside on that server, so it is not necessary that a client computer always be active.

The AltServe server can be located within your organization on a local area network, or it can be remotely located anywhere on the Internet. The information on your server can be made as secure as you need it to be (using the normal Unix permissions system).

The Linux and BSD operating systems are currently supported.

AltServe Activation and Static IP Address

Before AltServe can become active, Safeworlds must enable your world name with the proper activation code. This is done when AltServe is purchased, and the IP address / port number for your server must be provided. This allows your AltME clients to connect to your server.

Note that the IP address for the server must be static. Dynamic IP addresses are not supported for AltServe. Should you require a change to the IP address for your server, please contact Safeworlds.

Requirements

  • Linux or OpenBSD x86 with libc6. This is a very common, widely supported Linux configuration.

  • 300 MHz CPU or better with at least 64 MB of memory.

  • Shell access via SSH to configure AltServe. (But, once installed no access is required. All other changes are made from the client.)

  • An available TCP/IP port and configuration of your firewall to allow connections on that port (e.g. port 5405).

  • Access to rc.d server startup scripts to auto-start AltServe on boot.

  • No root access or root permissions are required to run AltServe. However, to setup the above rc.d scripts will require root or sudo capabilities.

Fast Setup Summary

Installing AltServe is easy. You can have your new world online in a few minutes. No special configuration is required.

Here is a short summary of the setup process:

  1. Logon to the user account that you want to use for AltServe. Do not use the server's root account.
  2. Unarchive the distribution files to the directory where you want your world to run. This directory must be read/write accessible to the account you will be using.
  3. Run AltServe from the shell and confirm that it is functioning correctly (logon from a client).
  4. Add a startup script to your system's bootstrap sequence (e.g. in /etc/rc.d/rc.local) to restart the world each time your server is started.
Important: do not edit the files created by AltServe. This can cause problems for your world. See the warning below.

The full details of the above setup will be covered below.

Logon to User Account

When AltServe starts for the first time, it will create a few special files and directories. In order for those files and directories to have the correct ownership and permissions, you must start AltME the first time as the correct user.

Do not start AltServe from another user or from root or its files will not be properly accessible when you start AltServe later under a user account.

If you accidently start it under the wrong account, use the chown command to recursively change the permissions to the correct user and group accounts. For example the line below:

chown -R altuser.altuser alt-dir
will recursively change the user and group ownership for all the files and directories in the alt-dir.

Unarchive the Distribution

Download (or otherwise copy) the AltServe distribution file to the directory where you want to install the software. Unarchive the tar.gz file with a command such as:

tar -xzf altserve.tar.gz
This will create the necessary directory and files. If it does not, you can try:

gunzip altserve.tar.gz
tar -xf altserve.tar
If that does not work, check your OS documentation or contact us and we can provide a binary executable file directly.

Now switch to the altserve directory with the line:

cd altserve
The distribution only contains these files:

 altserveThe Altserve executable file.
 altserve.txtThis readme documentation.
 bootA sample boot script for autostarting AltServe on boot.

The first time you run AltServe, it will automatically create all necessary directories and files. (This is why you must be logged on as the correct user.)

Testing AltServe

There are two steps in testing that your AltServe works correctly.

First, just run AltServe and see if it loads properly in your version of the operating system:

./altserve
You should see the banner lines:

AltServe 1.1.25 by SafeWorlds
Copyright 2006 SafeWorlds, Inc.
http://www.altme.com
and other usage information (which you can ignore). If you don't see this banner, then something is wrong with either your distribution files (try downloading them again) or your operating system. Please contact us if necessary.

Now you are ready to start your world. Be sure you are logged in under the user account you want to use. (See the note above.) Now type a line of the form:

./altserve -s worldname -p portnum
where worldname is the name of your world, and the portnum is the TCP port you provided when you purchased and activated this copy of AltServe. For example, your actual line might look like:

./altserve -s "a-world" -p 5401
AltServe will respond by printing the banner information as shown above, but will not return to the prompt. The server is now running.

If you see an error message then you may already have the server running or the port number you selected is already in use by some other process. If you need to change port numbers, please contact us.

Verifying AltServe Access

With AltServe running as described above, open your web browser and go to www.altme.com/check.html. Type in your world name and click "check". If the information displayed looks correct, click "check world". The resulting page will tell you if your world is running and reachable.

If your world is not running or does not show as reachable, then go to the Troubleshooting section below.

Next, run AltME on a client computer. Type in your world name, then the user name "master" and the password "pass". If your world is running properly, you should see an empty world with your Master username.

Change Your Password!

You must change the password for your Master user, or your system will not be secure.

To change the password, logon to your world as in the prior section. Right click on your Master user in the user list (in the table on the left) and change the password. Click the save button and confirm the password.

Make sure you enter a password that you will remember! We recommend that you write it down somewhere safe, just in case! Now, exit your AltME world (on your client) and try logging on as Master again just to confirm that you've got it right.

Stopping AltServe

You can stop the AltServe you started above by pressing CTRL-C. CTRL-C will do a proper shutdown of the AltServe process.

If you need to stop an AltServe that you created earlier from another shell (such as one that was started at system boot time) you can use the kill command to send it a signal, as you would any process on your server (use the ps -ax command to see the list). You can also kill all AltServe processes with the killall command. These commands are part of your operating system, and may only be accessible from superuser (root) mode.

Autostarting a World at Boot Time

You will probably want your AltServe world to start automatically whenever your server is rebooted. To do so, you will need to add a small script to your server's boot sequence. This is easy to do.

Note that these changes will require administrative (superuser) permissions, so if you do not have that level of control, you will need to request your administrator make the changes.

Create a text file that contains the line:

su -lc '/.../altserve -s world -p port &' user > /dev/null
This command tells your system to execute a command line under a specific user account. This is how you can start your world under a the user account you used above and not as the root user.

In the command the first part is the path to the AltServe program. That is followed by your world name and port number (as discussed earlier). Then, set the user part to the user account name you are using for AltServe (the same one as above).

Here is an actual example:

su -lc '/home/host/altserve -s "abc" -p 5400 &' bob > /dev/null
Save the file as "start" in your altserve directory. Make the file into an executable script with:

chmod +x start
Now, go to your /etc/rc.d directory and add a line like this to the end of your rc.local file:

/home/host/start
Of course, use the actual path to the start file you saved above.

Now, when your server is rebooted, your AltServe world be started automatically as well. If you want, try rebooting your server now to verify that it works.

If you have multiple AltServe worlds, just add additional su lines to your start file in a format similar to that shown above.

If you want to start AltServe from a shell session, then be able to logoff without AltServe stopping, you can use the same procedure. Simply, logon to your computer as root or su to root, then run the start file to launch AltServe (as the correct user account). You can then logoff and the AltServe will continue to run.

Moving an Existing World

If you run your AltME world from a client computer or on another server, you can move it to a new server fairly easily.

Here are the steps to follow:

  1. Shut down the source AltME world. You cannot have users doing things when you move the world. To do this use the kill or killall commands.
  2. On the source system find where you installed AltME (or AltServe) and open the Servers directory (folder). Locate the directory (folder) for the world you want to move.
  3. Copy the entire directory and all its files to the Servers directory on the new computer (such as where you put AltServe). To do this, it is often easiest to use zip or tar.gz to gather all the necessary files together and transfer them to the new computer. Be sure that you are using the correct user account on the new computer.
  4. Start the world on the new computer. If you are using AltServe, you must have previously activated it with the IP address of the new computer. If you are moving your AltServe to a new computer, please contact us about changing the IP address for your world.
  5. Logon as a user to confirm that the world is working correctly. Send yourself a chat message or make some other change to verify that things are working smoothly and that you are seeing updates properly.

Very Important Notes

To keep your world running smoothly:

  1. Unless instructed in our documentation, never attempt to remove or change files that are found in your world's server directory. This can create synchronization problems with your client computers. (This happens because the communications with the client computers is highly optimized in the form of incremental differences.)
  2. Do not start a second instance of the same world on another computer, without first moving the server directory. Otherwise, your client computers may become confused about the status of their AltME messages and other AltME application data.
  3. To "clean out" an existing world, delete the users and groups as necessary, but do not simply delete the server directory for the world unless you request your users to delete the same world directory and files from their computers too. Often, it is easier to just start a new world with using a new name.

To Completely Restart a World

If you want to completely wipe out your world, both on your server and your client, then restart your world, here's how:

  1. Be sure you really want to do this. There is no way to recover the files.
  2. Shut down your AltServe process. See above.
  3. Find the directory for your world in the servers directory where you installed AltServe. Delete all the files (you can use rm -rf to force recursive deletion of all files.)
  4. Shut down AltME on your client computer.
  5. Find the directory for your world in the worlds directory where you installed AltME. Delete all the files.
Now, start your again world just as instructed to above.

Very Important

If you do the above, it is important that you delete (or move) the client files and directories related to your world from all the computer that you use. If you do not, you may see little "fragments" of the prior world that do not exist in your new world. That can be confusing to your users.

Security and Privacy

AltServe encrypts all communication packets that pass over the Internet, so when you send a message the message is kept private. The same is true for all other AltME data, such as checklists, user info, and more.

However, when stored on your server and client, data files are not encrypted. This is done for backup reasons. If you backup your server, when you later need to restore that data, you may need to gain access to the information stored in your world (an old chat session, for example). If those files were encrypted, then it would be difficult, if not impossible, for you to gain access to that critical backup information. Your backup would be worthless.

This means that the privacy of your AltServe files (including all data shared in your world) must be controlled in the same way you control other confidential information on your server, by using directory and file permissions (the same way you protect secure web pages or email files on your server).

To keep your world files private, you must restrict who has permission to access your server, or at least who has permission to access the directories where your world files are stored. It is your responsibility to set this up to your own level of privacy requirements. See the documentation for your operating system on how this can be done.


Return to Contents

Copyright 2010 Safeworlds, Inc.
AltME is a trademark of SafeWorlds, Inc.

Send Us Comments