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:
- Logon to the user account that you want to use for AltServe.
Do not use the server's root account.
- 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.
- Run AltServe from the shell and confirm that it is
functioning correctly (logon from a client).
- 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:
| | altserve | The Altserve executable file.
|
| | altserve.txt | This readme documentation.
|
| | boot | A 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:
- 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.
- 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.
- 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.
- 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.
- 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:
- 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.)
- 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.
- 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:
- Be sure you really want to do this. There is no way to recover the
files.
- Shut down your AltServe process. See above.
- 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.)
- Shut down AltME on your client computer.
- 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.
|
