Universe Server

This page reflects Historical Content. Information is outdated, does not apply to Cloud Services.

Welcome to the Universe Server documentation.

The server

Installation (Windows)

To install the Universe Server under windows, simply run the installation program and install it where you like. Then just start the universed.exe program.

Installation (Unix)

The Unix version of the Active Worlds UniServer is available for SunSparc computers running Solaris and x86 computers running Linux Red Hat 6.0 or later. Note that other versions of Linux may work but are not officially supported at this time.

Once you have received the Active Worlds UniServer from Activeworlds, transfer the file to your Unix host. The UniServer for Unix comes as a gzipped .tar archive.

Create a new directory to store the server files, and place the server file there. For this example, assume the name of the file is "awulnx28.tar.gz":

- mkdir ~/uniserver

- mv awulnx28.tar.gz ~/uniserver

- cd ~/uniserver

Unpack the file:

- gunzip awulnx28.tar.gz

- tar xvf awulnx28.tar

The tar file unpacks into the following files:

- atdump

- atload

- citdump

- citload

- ejdump

- ejload

- emaildump

- emailload

- gramdump

- gramload

- licdump

- licload

- universed

- universe.ini

Installing the license code

After unpacking the installation, you will need to place your UniServer license code file in the installation directory. The license file must be present in the directory in order for the UniServer to start. Your license file is provided to you by Activeworlds, Inc. at the time you purchased your UniServer or Galaxerver. Please do not change the name of the file, it must be named 'license' in order for the UniServer to run.

Once the license file is placed into the installation directory, you can run the universe. To do this, type the command universed on the command line at hit Enter. If the universe starts successfully, you will be returned to the command line with no output. See an example screen shot

As shown in the screen shot, you can use the universe log files for troubleshooting and monitoring purposes. You can run the tail command to see the last few lines of the log file.

Use the Admin tool to connect to your universe and administer backups, worlds, and more. The administration tool for world servers is included with the installer for the Windows version of the World Server, but must be downloaded separately here if you are using the Solaris or Linux versions of the World Server

Once the UniServer is installed and running on your system, you can open the Activeworlds browser and connect to the universe to administer citizens, worlds, configure options and set universe attributes.

After the installation

Login on your universe as tourist and create the first citizen account (by clicking the Immigrate button) that will be used for administration. From this account, you may create the license for the first world you will start.

Configuration

This section will explain you how to configure the Universe Server.

The universe.ini file

The universe section

Example of universe section:

[universe]

host=hostname.domain.com

port=5670

This section contains the host and the port that the server will listen. If this you don't configure this section, the default settings will be used (0.0.0.0:5670).

The citizen section

These are the defaults settings used if this section is empty or even unexisting:

[citizen]

bot_limit=3

allow_changes=1

international=0

bot_limit - The default bot limit for registering citizens.

allow_changes - Allow/disallow the use of the Options > Citizen form.

international - Allow/disallow the use of the special characters for registering citizens. Notice that users won't be able to login if their names use " , [ or ] .

The registration section

If you wish to charge citizenships in this universe, you need to configure this section. This is an example of settings:

[billing]

host=www.myuniverse.com

port=80

url=path/to/AwSkipJack.php

notify=charges@myuniverse.com

notify_file=/tmp/notify

log=billing.log

term=366

trial=14

charge=19.95

mcharge=19.95

acharge=19.95

The host=, port=, and url= fields specify the server and URL to which the UniServer should POST the completed credit card request and wait for a response. When using a SkipJack account, the host is your web server, and the url is the path to the AwSkipJack.php file on your web server.

In 3.4 the charge= field has been replaced by mcharge= and acharge=. These values contain the amount to charge per citizenship in US dollars. mcharge is used for monthly registrations, acharge= for annual. If charge= is specified it is used as the default for mcharge= and acharge=.

The trial= field specifies the free trial period in days. This value is passed to the URL specified by host=, port=, and url= and is otherwised not used. It is up to the billing app to offset the billing if needed.

The term= field specifies the length of a citizenship in days. After this many days pass, the citizenship expires and the user will need to renew with another credit card charge in order to continue using their citizenship. The user will automatically begin to receive warnings in the browser on login if their citizenship expires in less than 30 days.

The notify= field specifies an optional email address to which the UniServer can send an automated notification whenever someone registers. Note that this mechanism requires that the ability to send email be correctly set up for the UniServer. The notify_file= field specifies the temporary file to use for the notify email.

The mail section (Unix)

This section will make users able to use the password reminder. This section is also required to enable the registration charge.

[mail]

command=/usr/lib/sendmail

template=mail.txt

file=/tmp/awmail.txt

The command= field specifies the system command to invoke for sending email. The template= field specifies the name of a text file containing a template for the password email message (see below). Finally, the file= field specifies the location where the UniServer should temporarily store the final email message for sending.

When a user invokes the password mail back feature, the UniServer first creates the email message to be sent and stores it in the temporary file, then issues the following command to the system:

[command] [email address] < [temp file]

Given the sample configuration above, the actual command might look like this:

/usr/lib/sendmail username@myisp.com < /tmp/awmail.txt

Note that sendmail must have already been properly configured by the system administrator to send email or this mechanism will not work.

The mail section (Windows)

Please read The mail section (Unix) first.

Sending email from a Windows UniServer requires the use of some extra utilities that are shipped with the Windows version. As a result the [mail] section of the universe.ini will look a bit different under Windows. A typical Windows mail configuration might look like:

[mail]

command=mailpw -from=support@yourdomain.com -subject="Your Password" -host=smtp.yourdomain.com

template=mail.txt

file=mail.tmp

This configuration will invoke the mailpw.exe utility to send the password email under Windows. If the -host= option is set to point at a valid SMTP server, this procedure should work. Be sure to change the support email address from the default example preset in the universe.ini file.

The log and logging section

The log section allows you to configure how the server will write the log file. Example of settings:

[log]

file=universe.log

size=60000

telegrams=1

The file= field specifies the file where the logs will be wrote. The size= field is the maximum size of the file (in bytes). The telegrams= specifies if the telegram should be logged (1 = Yes, 0 = No).

The logging section may contain additional settings:

[logging]

status=300

extra=1

The status= field specifies the number of second between each STATUS lines. The STATUS lines contains the number of users, bots and worlds connected. If you set this option to 300, the STATUS lines will be logged every 5 minuts (300 seconds). The extra= field specifies if the logs should contain the extra informations (OS Version, video mode, vendor code, ...) (1 = Yes, 0 = No).

The registration

The billing.log file

The log= field specifies the location and name for the billing log file. Whenever a user attempts to register a citizenship it is recorded in this log. A typical billing log entry might look like:

Sun 02/18/01 10:31:40 89.28.145.109:2339 BILL 'AWLD' 'Rocketman' 243192 '432140124212****' 'Adam Jones' ' ' '20 Aspen Ln' 'Springfield' 'PA' '12345' '326-6547' '5' '2002' - Y484789AUTH/TKT YY [0]

This entry gives the date and time at which the transaction occurred and the IP address and port from which it originated. After the BILL comes the optional browser vendor code which is useful if you have multiple distributors for your browser and you need to give credit to distributors for registrations received from their browsers. Then comes the citizen name, numer, part of the credit card number, followed by the billing name, address, telephone number, and credit card expiration date. The last portion of the entry is the response code from the credit card service, followed by an error code for the entire transaction as it was returned to the user's browser. A [0] indicates the transaction succeeded, the charge was accepted, and the citizenship was created.

Some possible billing error codes include:

[46] - Timeout. The UniServer timed out waiting for a response from the credit card script. This can occur if the web server hosting the script is having problems, or the credit card service is having a problem with their server, or if there is a problem with the internet connection anywhere between the servers.

[48] - Invalid response received (from credit card service). The most common cause for this is a problem in the credit card processing script on your web server, or a configuration problem on the web server hosting the script.

[51] - Unable to connect. The UniServer was not able to establish a connection with the billing host. Verify that your internet connection is okay and that the web server hosting the billing script is alive and responding. An easy way to do this is to open a web browser and type in the URL directly to your billing script.

[55] - The credit card was declined. Some part of the information was invalid, usually either the name, number, or expiration date. This is by far the most common error code.

If you are receiving an error code that is not listed above, contact the Activeworlds support.

Blocking fraud

One frustrating aspect of administering a universe that accepts credit card transactions is fraud. On the internet it is relatively easy for unscrupulous users to acquire stolen credit card numbers and use them to register a citizenship. If the number has not yet been reported stolen, the charge may be approved, and you will not find out until later that the number was stolen, possibly requiring you to conduct an expensive refund process.

If you are having problems with fraud from a particular location or locations on the internet, you can have the UniServer automatically block any further registrations received from those IP addresses. To do this, simply create a file called "block.txt" and place it in your UniServer directory. Place any IP addresses you want to block from registration in this file, one per line. To block an entire "class C" address block, specify the last digit as 0. For example:

24.141.29.168

24.200.111.0

The first line rejects any registration attempts coming from the IP address 24.141.29.168. The second line blocks registration attempts coming from any IP address in the range 24.200.111.1 to 24.200.111.255.

It is not necessary to restart the UniServer after adding new entries to the block.txt file.

A more extreme approach would be to block the IP address out from accessing UniServer at all, see also: Ejections.

The E-Mail

Password mail back also requires a template file describing the contents of the email message that is sent to the user. A typical template file might look like this:

From: Universe Support <support@universe.com>

Reply-To: support@yourdomain.com

To: %.*s

Subject: your password

Your password is '%.*s'.

If you did not request your password, please accept our apologies and disregard this message.

Regards,

GreatUniverse, Inc.

The contents of this file can be pretty much anything you want, but placement of the headers at the top is the most important, as well as the locations of the two %.*s sequences. The first %.*s is where the user's email address is placed, and the second %.*s is where the user's password is placed.

The email template file cannot be longer than 2048 bytes.

The universe attributes

The Universe Attributes are read-only for all users except universe administrators.

The Minimum browser is the minimum browser build number that will function within this universe. Any attempt to run a browser with a build number lower than this will result in a forced upgrade.

The Latest browser is the build number of the currently released version 3.0 or later browser. Users running a version 3.0 browser with a build number that is lower than the latest browser but greater than the minimum will receive an upgrade notification.

The Latest 2.2 browser is the build number of the current version 2.2 browser. Users running a version 2.2 browser with a build number that is lower than the latest 2.2 browser but greater than the minimum will receive an upgrade notification.

The Beta browser is the build number of the latest browser that has been released to beta testers. You must be on the Active Worlds beta program in order to receive an upgrade to this version.

You can find out the build number of your browser from the About Box (select About... from the Help Menu.)

The Minimum world is the minimum world server build number that will function within this universe. World servers with build numbers lower than this value will not be able to start.

The Latest world is the world server build number that all worlds running within this universe should be using. World servers version 3.2 and later with build numbers lower than this value will print an upgrade notice in their events logs on startup.

The Beta world is the build number of the latest beta world server. World servers version 3.2 and later with build numbers greater than the latest world value but lower than this value will print an upgrade notice in their events logs on startup.

The Default start world is the world that all new users start out in, as well as anyone else who has not yet chosen a home world.

The Universe welcome message is a message from the Immigration Officer printed to all users when they first enter the universe. If this message is changed, any users currently in the universe will see the new message right away. In this manner the universe welcome message can also be used to send urgent messages to all users in the universe at any time.

The Search Tab URL is the address of a web page to be displayed in the browser's search tab. If no URL is specified, the search tab will be disabled.

The Allow Tourists option specifies whether or not tourists are allowed to access the universe. If this option is disabled, then all users must provide a valid citizen name and password before first entering the universe. The tourist option from the login menu will also be disabled.

The Notepad URL has not been announced by Activeworlds and has no known effect.

The Personal Avatars path and Textures Path are the URL where the PAVs are located.