Ethereal Realms is a concept web-based chat
system, originally based on two chat sites which are now both defunct. This
system emulates what features and functionality those sites possessed while
adding to the initial design and scope as time progressed.
Released under the GNU General Public License[1]
(GPL), this project also has the secondary aim of creating an advanced
role-play and gallery environment that will can be shared and modified freely
throughout the community.
Ethereal Realms has also moved well beyond the original mandate of offering chat
capabilities. This includes the addition of threaded message boards, web polls,
homepage management and full featured collaborative galleries. While these
additions are not necessarily core to the role-play aspect of the site, they do
compliment the existing feature set and provides communities a method of
remaining self-sufficient.
./ethereal/conf/ethereal_base.tmpl
./ethereal/conf/ethereal_data.tmpl
./ethereal/conf/ethereal_functions.tmpl
./ethereal/conf/ethereal_schema.tmpl
./ethereal/conf/ethereal_views.tmpl
./ethereal/main/registration.pl
./ethereal/main/js/forecast.pl
./ethereal/main/post/colours.pl
./ethereal/main/post/private.pl
./ethereal/mgmt/admin/system.pl
./ethereal/mgmt/config/home.pl
./ethereal/mgmt/config/ignore.pl
./ethereal/mgmt/config/gallery.pl
./ethereal/mgmt/config/puppet.pl
./ethereal/mgmt/config/puppeteer.pl
./ethereal/mgmt/config/realm.pl
./ethereal/mgmt/commandline/convert.pl
./ethereal/mgmt/commandline/erealms.pl
./ethereal/mgmt/commandline/locate_tags.pl
./ethereal/mgmt/commandline/publish.pl
./ethereal/mgmt/commandline/queue.pl
./ethereal/mgmt/commandline/reverse.pl
./ethereal/mgmt/commandline/spel.pl
./ethereal/mgmt/commandline/thumb.pl
./ethereal/mgmt/commandline/update_comm.pl
./ethereal/mgmt/Ethereal/Audit.pm
./ethereal/mgmt/Ethereal/Comm.pm
./ethereal/mgmt/Ethereal/Database.pm
./ethereal/mgmt/Ethereal/Filter.pm
./ethereal/mgmt/Ethereal/Home.pm
./ethereal/mgmt/Ethereal/Image.pm
./ethereal/mgmt/Ethereal/Leech.pm
./ethereal/mgmt/Ethereal/Login.pm
./ethereal/mgmt/Ethereal/Mail.pm
./ethereal/mgmt/Ethereal/Option.pm
./ethereal/mgmt/Ethereal/Param.pm
./ethereal/mgmt/Ethereal/Post.pm
./ethereal/mgmt/Ethereal/Pull.pm
./ethereal/mgmt/Ethereal/Rotate.pm
./ethereal/mgmt/Ethereal/Spel.pm
./ethereal/mgmt/Ethereal/Table.pm
./ethereal/mgmt/Ethereal/Template.pm
./ethereal/mgmt/Ethereal/ Weather.pm
./ethereal/mgmt/Ethereal/Who.pm
How do I change images in realm select?
How do I change images in toolbars?
How do I change news items displayed?
How do I change the puppet list?
How do I change the realm list?
How do I fine tune gallery image settings?
How do I show/remove forum lists?
How do I show/remove news lists?
I am missing files in my install?
I cannot change realms after install?
Just installed Ethereal Realms password?!?
Problems with Image::Magick, help?
The ./conf/config.pl script does not work?
Why do users, realms and mail expire?
Ethereal Realms is designed to be a
self-contained series of scripts. This
path and all elements within demonstrate this concept as everything required to
run the site is located within. This
means the installation[2],
execution[3],
operation/maintenance[4],
and run-time information[5]
critical to the use of the site are all here.
This directory contains four sub-directories. The first of which is covered below:
This directory exists for the deployment
and management of sites using Ethereal Realms code. New to version 4.0.0 of the code is the
ability to hosts multiple sites[6]
under one roof and is managed centrally through the script contained within.
This is the core script used in the
deployment and management of sites. By
default, this script cannot be executed directly as different locations in the
interpreter would generate errors. In
order to correct this issue this script has two requirements:
Once this script is employed, you can
add/remove, upgrade and manage new sites.
The script will also confirm the existence of critical modules required
for the use of the site and display the proper connection string to use with
your scripts in order to effectively make use of the database.
Please note that this script is in fact a
command-line script. You cannot make
use of a web-browser to configure[8]
the site.
This file includes the basic configuration
of the site itself. Information such
as the database and http user names will be stored within this file. Please note that this file should not be
made publicly available.
This file contains all necessary messages
and words used in the operation of the config.pl script. Due to the nature of the script it is
necessary to not be dependant on a database which may not be operational at the
moment.
Any file of the .tmpl extension exists to
generate the base template of a sites configuration. With the addition of macros, these files
contain all of the necessary database code[9]
used in generation. During the process
the macros are replaced with the proper information which will be appended to
the site prior to use.
See ./ethereal/conf/ethereal_base.tmpl
for more details.
See ./ethereal/conf/ethereal_base.tmpl
for more details.
See ./ethereal/conf/ethereal_base.tmpl
for more details.
See ./ethereal/conf/ethereal_base.tmpl
for more details.
While the previous path dealt with the low level management of the site, this one exists to cater to the needs of the general users. Every script within are user scripts, designed to created user interfaces, pull information and share if it need be.
These scripts are designed to be used directly under mod_perl[10] a critical Apache[11] module used in accelerating Perl scripts at the expense of memory usage. These scripts are not true mod_perl modules however in order to maintain compatibility with sites that cannot run under this system.
This is a script designed to display biographical
information, contact information or redirect to a puppets home page if the
users have so decided to allow it. In
realms, this functionality is enhanced as to allow for quick access to private
messaging, ignoring and watching if currently in offline mode.
./ethereal/main/board.pl Aliases: board, sysboard.pl
Message board functionality for Ethereal
Realms, using a simplified threaded model expanded for ease of use. These are embedded within every public realm
and can be accessed in various ways.
Additionally a special realm[12]
can be established to hold the systems forums.
A new portal designed exclusively for
contributors which allow access to all contributor components[13]
without using a unified native interface.
With the addition of this portal it became possible to make use of
Ethereal Realms without the rest of the chat component in place.
./ethereal/main/gallery.pl Aliases: gallery
This script is the client side portion of
galleries, currently featuring text and image works. Script includes searching capabilities, with
multiple views for quickly finding works or simply browsing through an
individual’s gallery.
For users currently authenticated to the
system, one has the ability to rate and comment on works displayed. This interface is also designed in such a
matter to make it friendly to web spiders giving the works within the chance to
be indexed in search engines.
./ethereal/main/gate.pl Aliases: go, portal.pl, ./ethereal/main/ssi/static.pl
The primary function of the portal is to
authenticate users and direct them to a screen that will show them access to
available features, functionality and allow them to access individual
realms. The realm resembles the
interface provided with the .contrib.pl script except that it bridges to users
to realms instead of works.
A view-only script that is generally used
in conjunction with the puppet configuration panel and allows users to see
gummies allowed on the site. This script
can also be employed to view injected gummies, which behave very much like
emoticons on instant messengers.
The Global who script is a front-end
allowing users to see realm activity globally.
There exists variants to this interface, one which will display
information more pertinent to the administrators of a site and the other used
to display initially at realm level.
Internal mail system for Ethereal Realms,
that allows for users to send messages directly to another user without having
to making their identities known. This
feature can also be used to capture messages normally send through Email[14],
alleviating the load on mail systems if need be.
Realms can be accessed in one of two modes,
for users who wish to re-create a message-board style of role play they would
normally enabled offline mode. This
script similar to the realm.pl handles all the necessary complexities.
This is a front-end interface for the
polling system used by the site, which works by taking in votes and displaying
the current results on request.
./ethereal/main/realm.pl Aliases: stream.pl
The Realm script handles the primary
interaction between the users with their realms. This script will also act as a portal for
realm specific functionality such as private messaging, enhanced biographical
information and forums.
./ethereal/main/registration.pl Aliases: confirmation.pl
Ethereal Realms requires that users are registered
in order to recall settings, handles and customizations. This script handles the tasks of collecting
initial information and making sure that the details provided such as the Email
address are valid through the confirmation aspect of the script.
If and when a user forgets their password,
this script can come to their aid. All
they will require is their username and a new password[15]
will be generated for them. For users
of elevated status such as an administrator[16]
or supervisor[17]
this script cannot be used.
./ethereal/main/weblog.pl Aliases: ./ethereal/main/ssi/quicklog.pl
Though the use of a weblog-style interface
this script allows administrators to pass on information to the rest of the
site. Extracts of the news headings can
also be displayed within realms or through the use of SSI scripts.
./ethereal/main/webring.pl Aliases: ring.pl
A web ring system has been incorporated
into Ethereal Realms in order to link all hosted realms together. This script acts as the intelligence
required to link and lists all of the realms within the ring itself.
Scripts within this directory exist to export certain aspects of the site outside of Ethereal Realms itself. This allows hosts and users to display a realms current weather, list who is on and display banners currently being rotated out.
All of this can be done through the use of JavaScript. Also with the use of CSS[18] the user has the option of changing the look and feel of the displayed object to look exactly how they wish it too.
This script displays the weather forecasts used in realms. Hosts can pass on the appropriate link as need be.
The use of RSS feeds on the site can be extended to display that information though JavaScript.
This is the rotation script used specifically in rotating items outside of Ethereal Realms.
These scripts are used while interacting
through a realm. As a result of this,
the bulk of these scripts will have the same access control measures put into
place as to prevent unauthorized access.
The colour guide displays every colour
allowed within a realm allowing the user to make a better selection of fonts
when playing within that setting.
An advanced die roller that while supporting a multitude of systems can use templates to support on system and catering to a realms specific role-play system. Rolls can be made in publicly or sent privately based on the user’s preference.
This script is the primary private message sub-system that will allow sending messages in private to people of the same realm or public realms if configured to do as such. Administrators can also use this interface as to send messages globally to all realms at once.
Realm specific variant of the global who is on that will originally display everyone in a specific realm then move to all public realms if requested.
Allows for the expansion of posts into an
external window in order to allow for easier modification and spell checking[19].
Ethereal Realms has created scripts that are made to function in conjunction with Server Side Includes (SSI). This allows dynamic content to be mixed in with seemingly static pages, without requiring people to use scripts directly.
The above directory does not contain any scripts;
instead it acts as a container for allowed SSI scripts that can be made
available publicly. To prevent a script
from being used as a SSI element, simply have that link revoked.
This directory acts as a separate container
for scripts that sites may not to have loaded to be under mod_perl or
equivalent web acceleration processes.
This also allows one to selectively export directories within this tree
granting a more granular control over the scripts themselves.
This contains all of the administrative scripts which require administrative level users to make changes to the system. These scripts allow changing anything from user’s properties to the look and feel of the site.
This
path is normally exported for use by administrators. Without access to these scripts it becomes
nearly impossible to make use of the site at all.
This script is similar in principle to global who is on, except that this script has the additional capabilities of seeing addition details. This includes the listing of all associated usernames, warning levels and any active realm currently active.
This administrative script creates a tabbed
user interface that allows controlling all administrative aspects of the
site. From realm creation to changes in
the specific wording of a button, this script will allow such changes to be
made. The administrator can also actions
taken on the site, this audit entry viewer can become a very useful ally to
determine where things have gone wrong.
This directory contains these configuration scripts do not require administrative access in order to be used. However, their access levels vary from requiring supervisory/moderator access for their use to simply being available to all.
This
path is normally exported for use by users.
Without access to these scripts it becomes nearly impossible to make use
of the site at all.
The homepage component of Ethereal Realms
which allows contributors to access files and images stored on the local server. In addition to straight file access, the
script allows for mass uploads, removals
and image resizing.
This script allows the ignoring users on
multiple levels, including simply replacing their title information.
Interface used to manage galleries, works
and gallery news entries for any contributor of the site. This interface is collaborative in nature and
can allow users who are not generally considered a contributor to access
existing galleries in a limited fashion.
This is the puppet configuration script
that handles the creation, cloning, modification and removal of puppets to be
used throughout the site itself.
Puppets are used as pen-names in galleries and employed when making
comments to works or posting in a forum, these are essentially one of many user
avatars.
Puppeteer configuration panel, also known
as the user details page, allows a user to change user specific information
from one interface. This includes
password, Email address changes and contact information updates etc.
This supervisory/moderator level script deals with realm specific management as required for public and/or hybrid realms. The management of every detail of the realm is done exclusively through this interface.
For administrators additional options may
also appear, as certain features are considered to volatile for general
experimentation and requires an administrator to undo.
Scripts in this directory are to be used at the command line level only and do not carry with them the ability to interact as a CGI script and are used exclusively for maintenance/update tasks. In certain cases the scripts heavily tailored to Ethereal Realms specifically and may require modification before use.
In certain cases these scripts are no longer being actively used and no longer work. If this is the case and you are in dire need of employing them you may wish to contact the developer.
This is a primitive tool that can be used in the migration of SQL dumps from MySQL databases to PostgreSQL. It is used as a pipe from a process to generally a file.
Primary command-line utility used by Ethereal Realms for all of required maintenance. This script can also be used to terminate streams, rotate banners in realms and synchronize Email addresses with mailing-lists.
This script is used in the location of
stale and unused tags in the database.
When called it will display the proper SQL required to have these tags
removed from the database. This
script is generally not required for sites outside of Ethereal Realms itself as
the code is not generally actively being changed.
Used on the site in order to publish all text works in galleries. This also allows for a global update of all works to new matching templates saving time and resources.
The queue is a simple script designed to serialize maintenance scripts[20]. Unfortunately this script does not always work as intended, however when it does the system can conduct complex maintenance without the worry of other administrative scripts interrupting its process or causing a fatal lock at database level.
Generates the necessary reverse indexes used in established galleries. Most sites not already on 4.0.0 and already using galleries will either be required to use this script or have all users resubmit their works before the search engine can be used.
This is a spell checking server-side daemon which will interact with ispell or the more modern aspell and allow the system to run spell-checking in scripts in an accelerated manner.
The thumbnail generator script is used to regenerate all thumbnails and supporting images based on new imposed rules.
This script will update the communications panel with links instead of macros. This change was done as of Ethereal Realms 4.0.0 in order to provide hosts with a greater flexibility on which links are displayed in the site proper.
Additional Server Side Includes are added here. These cannot normally be accessed from the outside world and have to be linked to the exported ./ssi directory located in the ./ethereal/main/ directory structure.
Allows a user to display the FAQ and have it accessible to users. This is the only interface available for the FAQ.
Similar to the JavaScript equivalent except there is no processing client side when the user makes use of the page.
Modules on Ethereal Realms exist to perform
certain tasks and cut down on code and complexity. The following modules come default with
Ethereal Realms and are core to its use, however there are other modules required
for operation which can be installed separately.
Auditing modules used to store records of administrative and supervisory tasks done within the system.
This module handles all the composition of
posts and writing of that information to the database. Secondly it provides the interface with which
people interact with at realm level.
This module is designed primarily to hide most of the work used to access and work with the database and handle things from making a database handle to retrieving documents. With the introduction of Ethereal Realms 4.0.0 this module will also make use of BerkelyDB[21] databases in addition to PostgreSQL in order to create a faster cache for frequently accessed information.
A safer, centralized method of filtering HTML based on a few factors. This includes a somewhat primitive version of HTML tag closing for those that tend to forget.
Home page module, currently only used for the storage and removal of images and files on the system accessed through the Home Page or Gallery configuration panels.
This module is basically a wrapper Image::Magick[22] that simplifies common tasks such as thumbnail generation, resizing of images and determining key information.
This module is new to Ethereal Realms 4.0.0
and allows galleries to retrieve massive amounts of images from web pages. This leeching module can be employed on any
site without authentication and has a memory necessary in pulling several
hundreds of images without a hitch.
This module exists as the central authentication method for the site.
This is a mail handling module, allowing for the standardization and separation of the mailing process from the scripts. This module will make use of both SMTP and a Sendmail[23] wrapper in order to guarantee the transmission of Email.
This is the options handling module used in determining exactly what the user has selected and what it means for the database.
This module handles all aspects of the parameters sent back and forth between browser and server. Instance of the class also acts as an associative hash for easier retrieval of values.
Handles the display of posts to the various viewing method
Module used to retrieve posts for users.
This module deals with the rotation of ads and other material as dictated by administrators.
Spell checking module, which will work in
conjunction with the spell checking daemon.
The typo in the name is done on purpose.
Default table creation, used extensively in
the scripts along with Template.pm as to simplify design implementations. Recent releases of the code have rendered
this module almost exclusively useless at the user and supervisory level.
This module makes use of templates to
generate interfaces and widgets on the site, removing a great deal of
repetition from the attribute code.
This module handles the parsing of the
METAR[24]
weather reports and will also retrieve them as needed for use in weather
forecasts on the system and individual realms.
Primary module used in all instances which
list users actively in a realm.
This directory will always be shipped empty. When in use the database module will make use of it to place local caches of information specifically designed to speed things up client side and reduce database load.
In all cases the files within will contain the sites short name and then pertinent information. This allows an administrator to quickly remove any stale files if and when a site is removed from the system.
This directory would contain authentication and parameter information for every user currently on the site. Maintenance scripts will remove stale entries as it also maintains the database.
This directory contains a cache of all hashes used in the display of information. Files here are only generated when an administrator views the existing attributes and templates and their individual sites.
Same as above, however this is related to realm specific settings.
Versions prior to the above version will encounter problems when attempting to upgrade to this latest version due to massive changes at the template and attributes level. Names have been changed, moved around, re-organized and cleaned up in order to create a more streamlined release.
However, this had a side effect of causing conflicts between the old design and the new. In addition, the move to Cascading Style Sheets have changed the way many of these designs can be changed. As a result, it is highly recommend that people create an alternate site and upgrade the sites in parallel.
Galleries have also been changed heavily in order to support new features. These require a significant amount of changes, which are not easy to achieve and may be easier to ask users to move their galleries over in time.
Due to the above reason IT IS NOT RECOMMENDED TO ATTEMPT A DIRECT UPGRADE FROM VERSIONS PRIOR.
There currently exists two separate methods for using Ethereal Realms. The first, which is the preferred method, is to host the scripts on a dedicated server with little or nothing else running on the server. The more access you have in this case the better.
The alternate method is to make use of a shared hosting site. This is not recommended under any circumstances as the sites performance will be horribly crippled and administration in general becomes more difficult. However it is possible and requires a different process in the configuration of the site.
Make sure that you have the latest version
of Ethereal Realms ready to be installed.
This documentation will always reflect the most current release and may
not be in synch with older methods of installing the scripts. The most versions of the script are always
available through this link: http://www.ethereal-realms.org/download/pub/ethereal/ethereal-latest.tar.gz
Under no circumstance should you open the
archived file on a Windows based operating system and transfer the contents to
its new home. This will cause several
needed symbolic links in being lost and may severely hinder your ability to use
the site.
Make sure that you have command line access to the server which will be hosting Ethereal Realms. Command line access is required for installation, maintenance and management of all sites under the system. Without command line access the system will slowly begin to degrade in performance which could lead to crashes.
Ensure that you have Perl installed with the Config::IniFiles module prior to beginning the installation. For those of you making of shared hosting arrangements you may need to request that the module be installed for you.
Lastly, you will require access to the PostgreSQL[25] database. Not all shared hosts offer this database engine so you may need to shop around for it.
HTMLDoc[26] is a program that is used to translate HTML files into Adobe Acrobat compatible PDF files. You may want to have this installed, especially if galleries are on your priority list for things to be operational. While there is a commercial version available, there are free versions with the absence of support, for the needs of Ethereal Realms you do not need a support license.
Note: For most shared hosts you cannot create the required schemas for the database. This will have to be requested specifically. Fortunately the installer will not create things automatically, so simply record the name you chose and have that created when the time is right.
Copy the latest archived version of Ethereal Realms your downloaded previously into a temporary directory. The files will be copied to their new location once the archive has been open.
Open the archive:
tar
-zxvpf ethereal-X_X_X.tar.gz
Move into the newly created directory structure:
cd
./ethereal
Copy the included Javascript and Cascading Style Sheet documents to the directory which hosts your domains root:
cp -R
./webroot/css /www/path/here
cp -R
./webroot/js /www/path/here
Alternatively copy the images over as well:
cp -R ./webroot/img /www/path/here
cp -R ./webroot/gummies /www/path/here
cp -R
./webroot/inject /www/path/here
Move over the files used for the script to a location of your choice. The preference is somewhere that is not directly accessible by the webserver.
cp -R ./ethereal /ethereal/base/path/here
Note: The above makes no real difference as the server will be told where these files are located. Optionally, if you feel comfortable with the installation process you can remove the archive and temporary location of the originals.
Move to the new location for the script files.
cd /ethereal/base/path/here
Move one step deeper into the ./conf path in order to begin installation:
cd ./conf
Run the configuration script:
perl -w config.pl
The following output will be displayed. Answer each section appropriately:
Initializing configuration:
Admin:
Database administrative login? [postgres][27]
Database administrative password? [SOMEPASS]
Database:
Host address? [localhost][28]
Host port number? [5432]
Host database? [ethereal][29]
Script:
Script database username? [ethereal]
Script database password? [SOMEPASS]
Scripts will belong to which user? [www][30]
Scripts will belong to which group? [www]
Script permissions? [0775]
Root location of scripts? [/ethereal/base/path/here]
Location of Ethereal Realms libraries? Should be list directory where ./Ethereal is located. [/ethereal/base/path/here/mgmt][31]
Location of Perl interpreter? [/usr/bin/perl]
Location of 'psql' utility? [/usr/local/bin/psql]
Work directory for completed .sql files? [./work]
Writing settings to file... Done!
Do you wish to set the interpreter in the
scripts? [no][32]
Do you wish to check for the existence of all necessary modules? [no][33]
Testing for existence of modules
Archive::Zip...Found!
Calendar::Simple...Found!
CGI...Found!
CGI::Carp...Found!
Cwd...Found!
DBI...Found!
DBD::Pg...Found!
Digest::MD5...Found!
LWP::Simple...Found!
LWP::UserAgent...Found!
IO::Socket...Found!
Image::Magick...Found!
IPC::Open2...Found!
MIME::Entity...Found!
Net::SMTP...Found!
Number::Format...Found!
POSIX...Found!
Symbol...Found!
Text::Wrap...Found!
XML::RSS...Found!
Math::Trig...Found!
Lingua::Stem...Found!
Lingua::EN::Tagger...Found!
Time::HiRes...Found!
Done! [Enter]
Ethereal Realms will exist once the modules have been checked. Repeat the above minus setting configuration until you have all the modules properly installed. Once complete rerun the script:
perl -w config.pl
Checking configuration... Done!
Do you wish to reset file? [no]
Do you wish to check for the existence of all necessary modules? [no]
DBI connect('dbname=ethereal;
host=localhost;
port=5432;
user=postgres;
password=SOMEPASS','',...) failed: could not translate host name "localhost" to address: Name or service not known
at config.pl line 1151
Testing database connection...REMOTE FAILED...LOCAL SUCCESS...[34]
-= Database Changes =-
Based on your method of connection acheived, it will be necessary to
modify the ./Ethereal/Database.pm file in order to connect without failure.
Adapt line 122 of the file and replace it with the following:
* For a REMOTE connection use the following lines:
$database = DBI->connect("DBI:Pg:dbname=$dbname; host=$host; port=$port; user=$user; password=$pass")
or $self->ErrExit($cgi, "Database error \#$DBI::err : $DBI::errstr");
* For a LOCAL connection use the following:
$database = DBI->connect("DBI:Pg:dbname=$dbname; user=$user; ")
or $self->ErrExit($cgi, "Database error \#$DBI::err : $DBI::errstr");
Done! [Enter]
-= Action Menu =- Select desired operation from the menu below. For first time users please note that the only option allowed will be to create a new site required to begin using Ethereal Realms.
-=Sites=-
[C]reate a new Site
[D]elete a site[35]
[M]odify existing attributes of a site
-=Database=-
[G]enerate a new release
Action: [] C
-= Create a new site =- Welcome to the Site Creation section. In order to create a new site simply answer the questions prompted, which are needed for the creation process.
Full name [] Ethereal Realms
Short name [] ethereal
Domain Name [] ethereal-realms.org
Root http:// directory [] /home/ethereal/www
MD5 Password [ab8f9d279f3a8309a9f9ef50d9c330db][36]
Shared memory [ethe][37]
Site active for use [yes]
Fallback default [no] yes
* *
Full name: Ethereal Realms
Short name: ethereal
Domain Name: ethereal-realms.org
Root http:// directory: /home/ethereal/www
MD5 Password: ab8f9d279f3a8309a9f9ef50d9c330db
Shared memory: ethe
Site active for use: yes
Fallback default: yes
Continue with operation? [yes]
> cat /somesite.sql | psql -h localhost -p
5432 -U postgres
The last line generated is exactly what will need to run in order to proceed with the installation. If you do not have sufficient access to the system in order to complete this operation have an administrator proceed with this step.
Note: This is where the difference between the admin user and database will become apparent. While the SQL will be installed by the administrator the privileges will be changed to meet the needs of the script user and this is why that it is important to keep track of this.
Alternatively if you have more then one domain for the site you will need to make the scripts aware of this fact. Follow the additional prompts below to correct the issue.
-= Action Menu =- Select desired operation from the menu below. For first time users please note that the only option allowed will be to create a new site required to begin using Ethereal Realms.
-=Sites=-
[C]reate a new Site
[D]elete a site
[M]odify existing attributes of a site
-=Database=-
[G]enerate a new release
Action: []M
-= Modify a Site =- Simply follow the prompts to change information.
[1] ethereal
Change following site [0] 1
-=Confirm=-
Full name: Ethereal Realms
Short name: ethereal
Domain Name: ethereal-realms.org
Root http:// directory: /tmp
MD5 Password: e95740232612b126afff4b7343bc1d3b
Shared memory: ethr
Site active for use: yes
Fallback default: yes
Full name [Ethereal Realms]
Domain Name [ethereal-realms.org]
Root http:// directory [/tmp] /home/martin/www
MD5 Password [e95740232612b126afff4b7343bc1d3b]
Shared memory [ethr]
Site active for use [yes]
Fallback default [yes]
-=Aliases=-
Maintain alias ethereal-realms.org [yes]
Create new alias (type 'done' to end) [done] erealms.org
Create new alias (type 'done' to end) [done]
Done! [Enter]
This will complete the base install for Ethereal Realms and all that remains now to make the site aware of the script and begin using the site.
Dedicated hosting sites are a bit simpler. In order to proceed add in the following entries into the global section of the httpd.conf file located in the configuration directory for Apache:
#
# ETHEREAL REALMS
#
# Main folder
#
ScriptAlias /ethereal/[38] /ethereal/base/path/here/main/
ScriptAlias /erealms/ /ethereal/base/path/here/main/
<Directory /ethereal/base/path/here/main/>
# Base settings
AllowOverride None
Options +ExecCGI FollowSymLinks
# Apache Mod_Perl directives – Uncomment to use
#SetHandler perl-script
#Apache Registry
#PerlHandler Apache::Registry
#PerlSendHeader On
# Permissions
Order allow,deny
Allow from all
</Directory>
# Administration scripts
#
ScriptAlias /ethereal/admin/ /ethereal/base/path/here/mgmt/admin/
ScriptAlias /erealms/admin/ /ethereal/base/path/here/mgmt/admin/
<Directory "/ethereal/base/path/here/mgmt/admin/">
# Base settings
AllowOverride None
Options +ExecCGI FollowSymLinks
# Permissions
Order allow,deny
Allow from all
</Directory>
# Configurations scripts
#
ScriptAlias /ethereal/config/ /ethereal/base/path/here/mgmt/config/
ScriptAlias /erealms/config/ /ethereal/base/path/here/mgmt/config/
<Directory "/home/oracles/ethereal/mgmt/config/">
# Base settings
AllowOverride None
Options +ExecCGI FollowSymLinks
# Permissions
Order allow,deny
Allow from all
</Directory>
Restart your Apache server to have these changes take effect:
apachectl -restart
Lastly you can test the script by attempting to access it from your web browser at:
http://www.somesite.org/ethereal/admin/system.pl
Move to the directory structure where copied the Cascading Style Sheets. JavaScript and images:
cd /www/path/here
Create a new directory structure[39]:
mkdir ./ethereal ./ethereal/admin ./ethereal/config \
./ethereal/js ./ethereal/post ./ethereal/ssi
Create links[40] in all key folders:
ln /ethereal/base/path/here/main/* ./ethereal/
ln /ethereal/base/path/here/main/js/* ./ethereal/js/
ln /ethereal/base/path/here/main/post/* ./ethereal/post/
ln /ethereal/base/path/here/main/admin/* ./ethereal/admin/
ln /ethereal/base/path/here/mgmt/config/* ./ethereal/config/
Create additional links to complete the ensemble:
ln /ethereal/base/path/here/main/board.pl ./ethereal/board
ln /ethereal/base/path/here/main/board.pl ./ethereal/sysboard.pl
ln /ethereal/base/path/here/main/gate.pl ./ethereal/portal.pl go
ln /ethereal/base/path/here/main/gallery.pl ./ethereal/gallery
ln /ethereal/base/path/here/main/gummies.pl ./ethereal/gummies
ln /ethereal/base/path/here/main/realm.pl ./ethereal/stream.pl
ln /ethereal/base/path/here/main/registration.pl ./ethereal/confirmation.pl
Additionally, you can do the following for ssi if desired:
ln
/ethereal/base/path/here/main/weblog.pl
./ethereal/ssi/quicklog.pl
ln
/ethereal/base/path/here/main/weblog.pl
./ethereal/ssi/extlog.pl
ln
/ethereal/base/path/here/main/gate.pl
./ethereal/ssi/static.pl
ln /ethereal/base/path/here/mgmt/ssi/* ./ethereal/ssi/
The next step is to create a new .htaccess[41] file in the ./ethereal directory with the following contents:
# Main options
Options +ExecCGI[42] +FollowSymlinks
# CGI Variant
SetHandler cgi-script[43]
In some extreme cases you may need to add some translation since the server will refuse you the right to use +ExecCGI directive. Instead use this entry in your .htaccess with every single entry on one line:
#
# Regular Expression matching redirects
RedirectMatch permanent /ethereal/board/(.*) http://www/ethereal/board.pl/$
RedirectMatch permanent /ethereal/gallery/(.*) http://www/ethereal/gallery.pl/$
RedirectMatch permanent /ethereal/go/(.*) http://www/ethereal/gate.pl/$
Lastly you can test the script by attempting to access it from your web browser at:
http://www.somesite.org/ethereal/admin/system.pl
This is an excerpt of the Frequently Asked Questions currently displayed on Ethereal Realms. Of course these will be dated as of the date of release of this version of code, for an up-to-date please lookup the Ethereal Realms page directly.
If you wish to change the highlight images in the realm selection portion of the site, then change 'r_on' and 'r_off' variables in '/Template/WebDescription' to match the desired values.
The rest can be managed directly from '/Attribute/Portal/TmplRealmItem' or in rare cases from '/Template/WebPortal.'
Toolbars are the JavaScript enabled sections which allow a user to implement HTML formatting with little knowledge of the mark-up language. While the initial images are changed directly using the appropriate macro such as '/Template/RealmZoom' and '/Attribute/Configuration/TmplFormat', the additional changes are done through modification of the JavaScript code itself.
Simply change the relevant links in the format.js file provided with the Ethereal Realms release and all image changes will be complete.
Behaviour of the news items displayed in realms can be dynamically changed. When the '/Attribute/SystemSetPortalNewsItem' is set to '0' the system will only display items which are recent. Otherwise, if a non-zero value is provided, the system will show up to that amount of entries.
The '/Attribute/System/SetPortalPuppet' tag must be set to 1 in order to generate the condensed line. Reversion to 0 will cause the larger scrolling list to appear.
The '/Attribute/System/SetPortalPuppet' tag must be set to 1 in order to generate the JavaScript functionality of the realms selection. Reversion to 0 will cause the larger scrolling list to appear.
There are six attributes which can be set at the system level in order to fine tune the look, size and format of thumbnails/images used on the site. Listed below:
SetImgBackground: The background colour of the full dimension thumbnails. Default: Transparent
SetImgQuality: Compression level used. Default: 30
SetImgType: Format of image used. Default: GIF
SetImgView: Viewing images maximum size. Default: 640
SetImgFull: Maximum size of an image. Default: 800
SetThumbnail: Thumbnail size. Current: 200
Caching on Ethereal Realms is done through Berkeley DB and requires some minor changes to the Ethereal::Database module file. Before you proceed, realize that you will need to create/use a directory structure which will allow the web user name and group to access these files directly.
Note: It may also help if the maintenance script user has enough rights to remove stale files from time to time.
If you are attempting to implement caching under a multi-server system (more then one web server) you will need to make sure that the servers share the same cached information. This can be done through a network share or for those with money some sort of SAN.
To make use of this feature modify lines 68-70 in the Database.pm file. This file MUST be the same that is used by the scripts otherwise the changes will not take effect.
Change the lines to look like the ones below:
DBAUTH => '/path/to/db/auth', # Path for auth cache
DBHASH => '/path/to/db/hash', # Path for system tags
DBROOM => '/path/to/db/room', # Path for room tags
Alternatively, to disable you'd reset all of these to 'undef.' That will stop the cache files from being used even if they are present.
To create the hashes an administrator will need to access each series of attributes and the templates as to create the initial set. The files will update automatically as changes are made.
The '/Attribute/System/SetPortalForum' tag must be set to 1 in order for the appropriate macro to be generated.
The '/Attribute/System/SetPortalNews' tag must be set to 1 in order for the appropriate macro to be generated.
Note: Setting the amount of items displayed is not done through the above attribute.
Note: Upgrades from version 3.0.0- to 3.1.0+ are not advised.
Note: Upgrades from versions prior to 4.0.0 to above are not advised.
While upgrades are not necessary recommended, there are several scripts which exist to upgrade certain components of the site to 4.0.0+ and above. Most of which located in ./mgmt/commandline and are listed below:
locate_tags.pl - Used to locate unused tags on a system and remove them;
publish.pl - Used to generate PDF documents for all written prose in a given gallery; and
reverse.pl - Used to regenerate the gallery reverse indexes used in 4.0.0+;
thumbail.pl - Used to regenerate all thumbnails and images in galleries to bring them up to 4.0.0+ specs;
update_comm.pl - Used to adapt all comm panels to the new GENPARAM linking system.
New with version 4.0.0 of the scripts is
the addition of an installer script for the site. This installer script exists
to support the virtual hosting capabilities. However, it will also make sure
all modules are installed, change the execute path of Perl and setup the search
path for the Ethereal:: modules necessary for use of the scripts.
This script located in the ./conf directory and is executed at the command line by typing perl ./conf/config.pl. New to this script is the ability to upgrade sites to a new version. To upgrade using this script, simply drop in an upgrade file (example: ethereal-upgrade_360_400.sql) and rename it to upgrade.tmpl. This new file will prompt the system to give you the option to bring the system up to date.
Note: You can in theory use this script once configured to upgrade a database from 3.4.0 to 4.0.0+. However this will require you to update using all available updates first and this process has not been tested. Making use of the traditional manual updates may be preferable.
Note: Sites not making use of virtual hosting cannot effectively make use of this script.
Under no circumstance should you open the archived file on a Windows based operating system and transfer the contents to its new home. This will cause several needed symbolic links in being lost and may severely hinder your ability to use the site.
There is a known issue where escaped characters in database dumps may not remain as such. This causes issue in the JavaScript code found under /Templates/WebDescription and can be easily corrected by using the following lines:
var re = / \(\d+\)$/;
var spc = /\W+/g;
This will re-enable the regular expressions critical to the operation of the code itself.
The password for the user 'admin' is simple 'password' and as a general rule it is considered wise to change this as soon as humanly possible.
Image::Magick is critical for the use of advanced features used in contributor scripts. Unfortunately, there is little one can do on this matter; Image::Magick is required for all image related actions including determining the size of images.
This script requires Config::IniFiles, DBI, Digest::MD5, File::Copy in order to work properly. This will not work if modules are missing, especially the first, the script will complain that it cannot find specific files in the search path.
Macro's are keywords the system will recognize and replace with appropriate material. These range from simple name fill-in to the more complex addition of user interface widgets. A brief list is as follows:
M-SERIES - Dropping in words and phrases;
L-SERIES - Dropping in urls and links;
LST-SERIES - Drops in generated lists of elements such as the realms list on the portal; and
W-SERIES - Drops in a user widget such as a drop-down menu, text area and such.
Note: Some older templates do not make use of this precise naming scheme, however their function should become clear upon examination.
Templates are areas of text which contain macro and are expanded to form into a finished end product. There are two sets of templates. Templates which reside in the 'Templates' section of the administrative section are considered major templates independent of other attributes.
Lastly templates under 'Attributes' combined with others similar and will generally always begin with 'Tmpl.' These work the same however and are left together to make modifications easier.
Note: Some templates use other templates to generate their macros. The LSTREALMS macro in WebPortal for example uses another template within the Portal grouping to generate the listing.
Berkeley DB are single file databases which can carry information using various methods from hashing to binary search trees. These files have the additional capability of being implemented directly into Perl cutting out a lot of overhead when used.
Ethereal Realms uses this format of database in order to cache frequently accessed information cutting down on database load. For more information on this matter look up the 'How do I make use of cache' question in this FAQ.
The system as a whole is required to expire certain information in order to keep the database from getting bloated. However, the lapse in time requires for the expiry of such features can be controlled individually. Modifications to the '/Attribute/System/SetTimeout*' attributes will set the expiry time in days for each listed component.
Note: The use of the commandline tools are requires for any maintenance to be conducted.
The code and this documentation are covered
under separate licenses. The
Acceptable Use Policy and Hosting Guidelines are also covered under the same
copyright and license as this document.
Copyright (C) 2005 Martin Foster.
Permission is granted to copy, distribute and/or modify this document under the
terms of the GNU Free Documentation License, Version 1.2 or any later version
published by the Free Software Foundation; with no Invariant Sections, no
Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included
in the section entitled "GNU Free Documentation License".
Copyright (C) 2000-2005 Martin Foster
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU
General Public License along with this program; if not, write to the Free
Software Foundation, Inc.,
[1] See http://www.gnu.org/licenses/licenses.html#GPL
for more details.
[2] This exists in the form of the config.pl script which manages most of the complexity involved in the installation of the scripts/database.
[3] In the form of end-user scripts located mainly under the ./main directory.
[4] Maintenance scripts for the most part exist under the ./mgmt directory.
[5] The ./db directory can contain local cache files to reduce database requests.
[6] Every site exists under its own schema in the database, while the core information relevant to all exists in public.
[7] Available through the CPAN network.
[8] This script was designed and tested to Unix-like operating systems only.
[9] Really just straight out SQL statements and little else.
[10] See http://perl.apache.org/
for more details.
[11] See http://www.apache.org/ for
more details.
[12] Normally this is a hybrid realm and the realm name must be specified under /Attributes/System.
[13] Home pages and galleries are considered contributor components.
[14] This option can be changed through the User Details script.
[15] Ethereal Realms does not keep the password in clear text, as a result it is impossible to recover a password without breaking the cipher.
[16] Managers of the system.
[17] Managers of realms.
[18] See http://www.w3schools.com/css/css_intro.asp
for more details.
[19] The spell checker requires the use of a daemon to function. Without this process checking spelling mistakes cannot be done.
[20] This script is normally employed with cron.
[21] See http://www.sleepycat.com/products/bdb.html
for more details.
[22] See http://www.imagemagick.org/
for more details.
[23] See http://www.sendmail.org for more details.
[24] See http://www.nws.noaa.gov/tg/siteloc.shtml
for more details.
[25] Visit http://www.postgresql.org for more details.
[26] Visit http://www.easysw.com/htmldoc/
for more details.
[27] This is generally the user under which the user has been created. In certain cases the administrative login and password will be the same as the script because of limited access to the system.
[28] Localhost will suffice in all cases where the PostgreSQL server is on the same machine as the web server.
[29] This is whatever you create it as, the example uses the assumed default.
[30] The web user and group and used to set permissions properly. If you are using a shared host use your username and group since most shared hosts require that permission set.
[31] This can be a trap for some users. You can’t specify the full path as Perl will look for Ethereal prior to the name so simply specify the full path up to the ./Ethereal directory.
[32] Saying yes here will rewrite all your scripts. This is highly recommended for the initial install.
[33] You want the script to check for the existence of all modules. If one module is missing the script will exit with a sample command line script on how to have it installed. For users of shared hosts, simply note the modules and have them do it.
[34] This is critical to pay attention to. Depending on which method failed or passed you will have to change your Database.pm file to use the appropriate format.
[35] You cannot remove all your sites. If only one is left the script will ignore your request.
[36] This is a legacy component which is no longer required. Simply say yes on the matter and have it done with.
[37] This is a legacy component which is no longer required. Simply say yes on the matter and have it done with.
[38] Add in any additional names that may be requested as the ./ethereal and ./erealms exist for legacy reasons.
[39] This structure will only contain links to the actual files and prevent pervasive access to key files.
[40] Makes use of hard links which differ from symbolic links and bypass a lot of security on shared hosts.
[41] This files allows you to override certain directives from the Apache web server.
[42] Will tell the server that all files in here regardless of extension are executed.
[43] Informs the server that these files are to be treated as CGI scripts.
[44] See http://www.gnu.org/licenses/licenses.html#FDL
for more details.
[45] See http://www.gnu.org/licenses/licenses.html#GPL
for more details.