Magic Smoke Web Installation

logo

Prerequisites

You need a (web-)server that has PHP and MySQL installed: Hint: you can check what modules are active in your PHP installation by creating a script file (eg. test.php) that contains only this line: <? phpinfo(); ?> . When you install this file on the web server and then open its URL in a browser it will show you an overview of all PHP functionality. If it returns an empty page, the file was not processed by PHP and you still need to configure the web server.

Preparation

  1. create a database on MySQL (eg. create database smokedb)
  2. create a database user (eg. create user smokeuser)
  3. give this user full access to this database (eg. grant all on smokedb.* to smokeuser)
  4. create a configuration (see below)
  5. create templates (see below)
All files needed for Web-Installation are in the www-subdirectory.

Configuration

Copy the config.php.template file to config.php, then modify it to suit your needs.

Database Configuration

Magic Smoke is designed to work with multiple database engines. However, currently only MySQL is supported (this does not support mysqli or pdo_mysql).

The $db variable needs to be assigned with the correct engine to open the database. Currently only the MysqlEngine exists. This is an example configuration: 

// create engine: server, user, password
$db = new MysqlEngine("localhost","smokeuser","");
// set database name
$db->setDbName("smokedb");
// set table-prefix (optional)
$db->setPrefix("smoke_");
//set this to one of the supported MySQL storage engines for DB creation
$db->setStorageEngine("InnoDB");
The three parameters to the MysqlEngine constructor are: first the host the database server runs on. Use "hostname:port" if it runs on a non-standard port or ":/path/to/socket" if you want to use the local socket on a Unix system. The second parameter is the username for the database server and the third one the password (empty if no password is necessary).

The setDbName call is used to set the database that is used by Magic Smoke. The setPrefix call can optionally be used to set a prefix for all table names -- this way a single database can be used for multiple installations of Magic Smoke or even different applications (if the other applications are guaranteed to not touch Magic Smokes tables).

The setStorageEngine call can be used to set the table storage engine used by MySQL. Magic Smoke relies on MySQL using a transactional table type. The default is "InnoDB". It is not recommended that you change the default unless you know exactly what you are doing.

Admin Configuration

There is one option stored in the DB-Engine that is only used for database creation and recovery: 
$db->setAdminPassCode("Admin","SmokeInMyEye");
This call sets the web-user and web-passcode for the admin.php script. After installing the system this line should be commented to prevent anyone from destroying the database or installing more admin users.

Client Authentication and Session Configuration

The remainder of the config file contains settings for the dedicated client: 
//Authentication algorithm
// possible: md5, sha1, sha256, hmac-md5, hmac-sha1, hmac-sha256
$ClientAuthAlgo="hmac-sha1";
//hash algorithm library -- the PHP extension/module used for calculation
// possible: string (md5, sha1 only), hash, mhash
$HashLib="hash";

//Initial timeout from start of session request to session authentication
// usually 300s (5min) is a good value
$ClientAuthTimeout=300;
//Authenticated session timeout - how long an authenticated session lasts
// this should usually be a few hours (3600s per hour)
$ClientSessionTimeout=2*3600;
$ClientAuthAlgo contains the algorithm that is used to authenticate the client. You have to make sure that the algorithm selected is a) available in PHP, b) secure enough for your application, and c) available in all clients that are supposed to connect. The algorithms are:
md5Uses the MD5 hash algorith described in RFC1321. Please note that this algorithm is regarded as broken and should not be used.
sha1Uses the SHA-1 hash algorithm described eg. in RFC3174. Please note that this algorithm is theoretically broken, although the use of this algorithm in Magic Smoke should still be secure for a few years.
sha256Uses the SHA-256 hash algorithm of the SHA-2 hash family. This algorithm is currently recommended as replacement for SHA-1. However, it is currently not supported by any client.
hmac-md5, hmac-sha1, hmac-sha256Uses the same hash algorithms in HMAC mode (see RFC2104). This use is more secure than the plain use of the algorithms. It is recommended to use HMAC.

$HashLib defines what PHP extension is used for calculation of hash values:
stringDoesn't use any extension and instead uses the string functions md5 and sha1. This mode does not support sha256 or any of the hmac-modes.
hashUses the "hash" extension. This extension supports all modes listed above.
mhashUses the "mhash" extension. This extension supports all modes listed above.

The $ClientAuthTimeout and $ClientSessionTimeout set the two session timeouts. The first timeout defines how long the authentication handshake of the client may last before the handshake is terminated. The second value defines how long a session may be active before it is automatically closed.

Creating Templates

The www/template/* directories contain collections of template files. These are used to generate the user interface that users get to see.

Please read the chapter about Template Design and create your own set of templates (or customize an existing one).

Then modify the template line in your config file, eg.: 

$template="./template/mytemplate/";

Installation

  1. copy the www directory including your configuration and templates to the web server
  2. navigate to admin.php in your browser, enter the admin name and passcode you configured
  3. click to create the database
  4. create an initial admin user in the database
  5. close the browser
  6. link the index.php script from your other pages, so that customers can find it
  7. continue with the client installation