2. EWE Administration

This document describes how to administer a EWE server as of Version 1.0.

2.1. Concepts

This section describes basic concepts of EWE. The purpose of EWE is to provide a framework for managing web sites, databases, geolocation, user authorizations, cookies, and sessions.

2.1.1. EWE Web Pages

A distinction is made between EWE pages and non-EWE pages. The web pages supplied with EWE allow for basic EWE functionality but do not implement an actual web site. The pages for the web site are non-EWE pages and will not be affected by EWE settings unless they are altered to use the EWE framework, in which case they are considered EWE-enabled pages.

2.1.2. Users

EWE users are the means of authentication for access to EWE features. Users can be associated with individual sites or with EWE itself. The first user created when EWE is installed is given all privileges and is associated with EWE - not a site. User accounts are uniquely named entities with associated information, including password, email(s), privileges, and so forth. Users can identify themselves either by user account name or by any email associated with that name. They must prove they have authorization by providing a password for that user account.

Because EWE can manage multiple web sites, user accounts are identified with both a name (or email) and a site. The same name on two different sites is considered two different accounts. In other words, users are not "shared" across different sites, or between sites and the EWE installation.

2.1.3. Privileges

Administrative tasks are only available to users for whom those tasks have been authorized. The first user account (created as part of the EWE installation) is granted all rights, which allows them to perform any administrative task on that server. They can create new users and also grant/deny authorizations to other users. The following privileges can be associated with a user.

Privilege	Description
EWEPRIV_ALL	Grants all privileges
EWEPRIV_ADDUSERS	Add new users. Allows creation of new user accounts.
EWEPRIV_ADMINPANEL	Allow access to admin panel. Users with this privilege can use the Administrative control panel. Note that does not necessarily grant them the ability to use any of the features provided by the panel.
EWEPRIV_ADDSITES	Add new sites. Reserved for future use.
EWEPRIV_BYPASS	Bypass resource protections
EWEPRIV_FILES	User can manage his files
EWEPRIV_GEOLOCATION	Modify geolocation. Allows user to change geolocation information.
EWEPRIV_GETPHP	Get PHP information. Allows user to view configuration information about on this server.
EWEPRIV_GETSITES	Get site information. Reserved for future use.
EWEPRIV_GETUSERS	Get User information. Users with this privilege can list other user accounts and see their settings, including emails and granted privileges.
EWEPRIV_MODALERTS	Modify alerts. Allows user to manage alert emails.
EWEPRIV_MODIFYDB	Modify database. Allows user to update or delete data in any EWE database.
EWEPRIV_MODIFYIMAGES	Modify general images. Users with this privilege can alter the images used on EWE pages.
EWEPRIV_MODIFYLANGUAGES	Modify languages. Allows user to modify language information, including associated images, enabled/disabled status, etc.
EWEPRIV_MODIFYMODULES	Install/uninstall/configure modules.
EWEPRIV_MODIFYTEXT	Modify text and translations. Users with this privilege can alter text shown on EWE pages, including translations of that text.
EWEPRIV_MODSERVER	Modify server. Allows user to make server modifications.
EWEPRIV_MODSETTINGS	Modify settings. Allows the user to alter Server settings.
EWEPRIV_READDB	Read database. Allows user to query data in any EWE database.
EWEPRIV_SETBLACKLIST	Manage blacklists. Allows user to manage blacklists.
EWEPRIV_SETBOTS	Manage bots. Allows user to manage bot IPs.
EWEPRIV_SETPHP	User can set PHP settings
EWEPRIV_SETSITES	Change site information. Reserved for future use.
EWEPRIV_SETUSERS	Change User information. Users with this privilege can alter the attributes of any user account.
EWEPRIV_SERVER	Get server information. Allows user to see server information.
EWEPRIV_WHITELIST	User can manage whitelist for his account

The EWEPRIV_ALL privilege grants all other privileges. Note that a user account can have multiple privileges even if more than one allows some action. As long as an account has at least one of the necessary privileges the user can perform that action. Thus, if a user has both EWEPRIV_MODIFYTEXT and EWEPRIV_ALL privileges, both of those privileges allow the user to modify the text. As long as the account has either, or both, privileges then the user is authorized to perform that function. It is also possible for a given function to require that a user have multiple privileges, in which case the user account would have to have each of the required privileges to be able to perform the function in question.

Obviously, the EWEPRIV_ALL privilege is dangerous in the wrong hands and should only be granted to users who can be trusted to manage the EWE server. As a general rule, users should not be granted any more privileges than are absolutely necessary for them to perform whatever task(s) they have been assigned. This will reduce the possibility of mistakes by well-intentioned individuals, as well as attacks by malicious users. For this reason, new user accounts are created without any privileges by default. Privileges must be explicitly granted by someone with appropriate privileges themselves.

2.1.4. Geolocation

EWE optionally supports geolocation data. This is accessed through the EWE geolocation services. If geolocation services are not required for any of the sites associated with the EWE installation, the geolocation data need not be installed. There are three EWE install archives that can be downloaded. Only one contains geolocation data. The geolocation data that is provided is the MaxMind, Inc. GeoLite2 dataset, which is free under the Creative Commons Attribution 4.0 License.

Using the admin panel, updated data from MaxMind can be reloaded. Further, if you purchase the full data set from MaxMind, you can download that and reload from that dataset. The Maxmind *.csv files go into the geolocation folder in the EWE folder structure. These files can be deleted after the data is reloaded to save disk space. However, if the files are deleted, the database cannot be reloaded if something goes wrong with the tables, unless the files are first replaced. Note: only the *.csv files are necessary.

2.1.5. Database organization

The EWE database tables can be distributed among different databases and/or servers. The database specified in the _ewedb.php file (set up during installation) is considered the Primary Database. By default, all tables reside within this database. However, for larger sites, it may be beneficial to spread the database load across different database servers to avoid performance issues.

The administrator can create different "database sets" which are named specifications for databases. Each database set consists of a server, database, user, and password which indicates where to connect for tables associated with that database set's name. The Database Sets feature on the Admin panel can be used to manage these database sets. This is a general feature available to all pages using EWE, but certain names are reserved for general EWE use. Any database set name starting with "ewe$" is reserved for EWE use and should not be defined by the administrator or programmers. Any module name may also be used for a database set name. The following table defines the currently used reserved names.

Name	Tables	Description
ewe$dictionary	password_dictionary	Dictionary/word lists.
ewe$files	download_detail downloads file_system*	User file tables.
ewe$geolocation	geolocation*	Geolocation tables.
ewe$logging	alerts events* intrusion site_errors*	Events and logging tables.
ewe$text	bots countries errors* exposed* event_names hook_names languages privileges* states text_name* continents	Text and translation tables.
ewe$user	alerts exposed users_* whitelist_* privileges	User-related tables (other than user files).
ewe$server	blacklist* databases hooks modules phpsettings preferences name_exclusions siteadmin sites tasks url_redirect	All tables other than "databases" and those listed above.

The "databases" table is always kept in the primary database.

2.1.6 Files

EWE provides several means of managing file access - downloads, redirection, view counting, and metrics. The various features are described in the following subsections.

2.1.6.1 Downloads

Files can be made available for downloads. These files are available via the base/downloads.php page which means they can be placed in a folder outside of the document root tree, but there is no restrictions on access. If someone knows the id, they can download the file. Because access is indirect, any/all types of file can be made available. PHP files are translated by PHP before the page is displayed (not downloaded). Likewise, images and HTML files are displayed directly by the browser, rather than downloaded. The number of downloads/views is tracked. Server options allow you to track either the number of accesses for each file, or to keep a history of all accesses. A download link for a given file can be embedded in a PHP page. The download count can be set to any value via the Server class.

2.1.6.2 File Views

You can track the number of times a PHP page was viewed by using the Page Views feature. This requires that a call be made to the appropriate server method somewhere within the PHP page. This allows the view to be restricted to a limited set of specific pages, but the pages have to be modified to add or remove the view tracking. When only a few pages are to be tracked, this may be the most server-efficient means of doing so. The number of views can be queried and displayed, if desired. The view count can be set to 0 via the Server class, but not to an arbitrary non-zero value.

2.1.6.3 Metrics

Metrics are provided via the EWEMetrics module, covered under Modules. The benefits include more detailed tracking information, including IPs used to access pages, page execution time, and numbers of views. However, this places a higher demand upon the database since each page access will generate a minimum of two additional database operations. It only applies to pages that use the EWE framework.

2.1.6.4 Redirection

Redirection is a means of providing redirection to server resources, however it is more efficient to do this through the web server (e.g. the .htaccess file). Only PHP pages can be redirected by EWE.

2.1.6.5 User File Systems

This feature of EWE provides a lightweight virtual file system that can give users a way to store and manage personal files. It is separate from the actual file system on the host computer, other than that the files in the user file system can be stored in a location in the host computer's file system, if desired.

The user file system table is used for all users, although each one has a separate virtual file system. Files can be shared, or not, by setting the appropriate protection codes for each file. Note that users with the EWEPRIV_BYPASS privilege can view any file regardless of its protection code. File protection can be viewed as a set concentric circles, each one providing more restrictive access to the file. These circles of protection, from outermost to innermost, are:

World: This applies to anyone attempting to access the file. If the world is given Read access, for instance, anyone can read that file, whether or not they fit into any of the following categories.
Server: This applies to any logged-in user of any site managed by EWE on this server.
Site: This applies to any logged-in user on the same site as the user who owns the file.
Friends: This applies to any logged-in user considered a "friend" of the user who owns the file. Note: This is reserved for future use.
Group: This is reserved for future use.
User: This applies to the file's owner.

Thus, if the User has Delete protection, but no other circle does, then only the user (owner) can delete the file. If Delete protection is granted to the Site level, then any user on that site can delete it, even if they are not the owner.

There are different types of file access that are allowed for each of the above circles.

Read (R): Allows reading the file.
Write (W): Allows writing to the file.
Delete (D): Allows deleting the file.
Control (C): Allows altering the file, such as changing the file protection or file name.

By default, the owner user is granted all access (RWDC), and all other levels are granted read-only (R) access.

A file system "device" specifies where files for a file system are stored. This must be specified as a file path, but that path can be virtual - such as a fuse link to AWS S3 storage. Any number of file system devices can be specified. If there is more than one, one will be chosen at random whenever a new file is added to the file system. This will spread the file load across these different locations. It is important for most host file systems that not too many files are created in a single folder or the system may slow down. Thus, the more files you expect to exist in the file system, the more devices you should create. Devices can be marked "public" or "private". When a device is being chosen at random, it is chosen from those marked public. Marking a device as private will take it out of consideration for new files, but any files already existing on that device will remain there.

There is a default file system device that is used if you do not specify one. It points to the files folder in the EWE folder structure. It cannot be deleted or changed. However, it is ignored when creating new files if at least one public file system device exists. It is recommended that, if you are going to use this feature, that you define one or more devices and that they point to a folder(s) on your server that are not in the document root so that people cannot navigate directly to them via a browser. Otherwise, any file protections are meaningless.

User File Systems and devices can be managed via the "File System" option on the Admin table, or programmatically via the File_Systems class.

2.1.7. Automation

The Automation Manager is a means of queing up tasks to be run automatically on the server. They can be one-shot or recurring. Typically, this is handled via cron jobs on Linux. However, that may not be available in all circumstances. Jobs are the command files or programs to run. The queue of these jobs can be viewed and manipulated via the Admin Panel.

To work automatically, the automation manager must be started on the server whenever it boots up. It is designed to run detached. The file to run is classes/automationman.php. In order to operate autonomously, PHP must be set up to allow the exec function to run. If either of these conditions cannot be met, jobs can be queued up but they won't run when scheduled (or at all). The EWE admin can compensate for this by manually executing waiting tasks in the queue, via the Admin panel. As of this version, EWE has no essential tasks that need to be run by the automation manager, but this may not hold true in the future - especially in regard to modules.

2.1.8. Recovering access to EWE

If you lose access to EWE, such as by forgetting the password to the admin account, you can regain access by following these steps.

Create a file named reset.php and place it in the EWE root directory. The file should look similar to this:
<?php
$resetuser='username';
$resetsite=0;
$resetip='192.168.0.50';
?>

The first variable indicates the name of the account to regain access to. The second variable indicates the site that the user belongs to (0 indicates EWE itself). The third variable is optional but highly recommended. This indicates that the account password cannot be reset except from the specified IP. If the IP isn't specified, the password can be reset from any IP.
Access the login page. Remember to use ?admin to change a EWE server user password.
Whatever password you enter will be what the user's password is set to. Note that there are no restrictions to the password in this process, whether in length or makeup.
As soon as the password is changed, delete the reset.php file so that no one else can change the password. Not doing this will leave your EWE installation vulnerable to attack.

2.1.9. Multi-server configurations

It is possible to manage multiple physical servers with EWE. Simply make sure EWE is installed on each server and that the _ewedb.php file is updated to point to the appropriate database. Note that if _ewedb.php points to a local database on each server, the effect will be multiple independent EWE servers/sites. If users are then sent to the different servers for the same site, via load-balancing for instance, each server will operate as a separate instance of the site with issues of a user exiting on one instance but not another, or having different passwords for the different servers. Since the user won't know which physical server he is on, this will be highly confusing to them. Note that failover across servers will require that you set up PHP to use memcached with sessions.

If you wish to host a given site with more than one server, _ewedb.php on each server must refer to the same remote database server. The database can reside on one of the EWE servers, so long as all the other servers' _ewedb.php points to this server. Likewise, if a multi-server site intends to dynamically manage files via the user file system feature, the devices for the file system must point to the remote file server. On Linux, this is most easily done via the fuse package.

2.1.10. Managing multiple sites with one EWE installation

It is possible to manage multiple sites with EWE. There are two ways to manage this: 1) have the web server direct all sites to a single document folder and allow EWE to redirect based on which site is being visited, or 2) have the web server direct each site to its own document folder. See the installation instructions for details.

2.2. Administrative Functions - The Admin Panel

The EWE Admin Panel provides a user-friendly way to access Server configuration and other features. A user must have the EWEPRIV_ADMINPANEL privilege to even see the Admin panel. Some options may not be shown if the user doesn't have the privileges necessary for those options. To use the Admin panel, one must be logged into the initial user account or an account with the appropriate privileges. If a user needs to login to the EWE server, they will need to log out first, and then go to the login.php file in the EWE base folder, using the "?admin" parameter. For instance:
/ewe/base/login.php?admin
On that page, enter a valid username and password. The Admin Panel resembles the following: