From bac45dab382be0b092e1996c055ba4f92f150dd6 Mon Sep 17 00:00:00 2001 From: konrad Date: Sun, 15 Jul 2007 20:09:21 +0000 Subject: [PATCH] added some docu git-svn-id: https://silmor.de/svn/softmagic/smoke/trunk@15 6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33 --- doc/build_prog.html | 5 ++ doc/index.html | 11 ++-- doc/install_web.html | 129 ++++++++++++++++++++++++++++++++++++++++++++---- doc/prog_protocol.html | 1 + doc/template.html | 51 +++++++++++++++++++ 5 files changed, 182 insertions(+), 15 deletions(-) create mode 100644 doc/template.html diff --git a/doc/build_prog.html b/doc/build_prog.html index 4eac305..63c139c 100644 --- a/doc/build_prog.html +++ b/doc/build_prog.html @@ -25,3 +25,8 @@ sh$ make This will build the msmoke binary (under Windows it will be located in the release folder), which can be used immediately. +

Shipping

+ +When installing Magic Smoke on another computer you have to make sure that all required libraries are there too. You can find out what these libraries are using standard tools, like ldd (Unix/Linux), objdump -x or dumpbin /depends on Windows, or otool -L on MacOS. Additional to those you need to copy libssl for OpenSSL.

+ +(to be continued) \ No newline at end of file diff --git a/doc/index.html b/doc/index.html index d3b0f1e..f59a222 100644 --- a/doc/index.html +++ b/doc/index.html @@ -11,16 +11,17 @@ to be written:

-

Building Magic Smoke

+

Building/Installing Magic Smoke

Programmers Manual

diff --git a/doc/install_web.html b/doc/install_web.html index 94a606c..99f4a06 100644 --- a/doc/install_web.html +++ b/doc/install_web.html @@ -3,29 +3,138 @@

Magic Smoke Web Installation

+logo

Prerequisites

-You need a web-server that has PHP and MySQL installed: +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

-*create DB -*create templates +
    +
  1. create a database on MySQL (eg. create database smokedb)
    2. +
  2. create a database user (eg. create user smokeuser)
    3. +
  3. give this user full access to this database (eg. grant all on smokedb.* to smokeuser)
    4. +
  4. create a configuration (see below)
    5. +
  5. create templates (see below)
    6. +
+ +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

-*copy stuff -*init DB -*create initial user +
    +
  1. copy the www directory including your configuration and templates to the web server
    2. +
  2. navigate to admin.php in your browser, enter the admin name and passcode you configured
    3. +
  3. click to create the database
    4. +
  4. create an initial admin user in the database
    5. +
  5. close the browser
    6. +
  6. link the index.php script from your other pages, so that customers can find it
    7. +
  7. continue with the client installation
    8. +
+ + \ No newline at end of file diff --git a/doc/prog_protocol.html b/doc/prog_protocol.html index 857a368..1504870 100644 --- a/doc/prog_protocol.html +++ b/doc/prog_protocol.html @@ -2,6 +2,7 @@ Magic Smoke Protocol Documentation

Magic Smoke Protocol Documentation

+logo
The Magic Smoke Protocol is used between the Magic Smoke Server and Client. It is based on HTTP and XML. Only POST requests are allowed.

diff --git a/doc/template.html b/doc/template.html new file mode 100644 index 0000000..3c75b0a --- /dev/null +++ b/doc/template.html @@ -0,0 +1,51 @@ + +Magic Smoke Template Design + + +

Magic Smoke Template Design

+logo
+ +The web user interface is constructed with templates with just a few dynamic values filled in. Thos templates are found in the www/template/* directories. These templates are normal HTML (actually: you chose the version of HTML that is used) with some special constructs to fill in the blanks.

+ +In order to create your own templates copy one of the template directories and start to modify the files in there. Usually it should be enough to change the layout.html template. If you use relative links inside your templates they will be interpreted as relative to the index.php script.

+ +

Syntax

+ +The most important element of templates are variables. Variables can be set by the template itself, or by the script. Wherever the value of a variable needs to be inserted it is simply placed between two "@" characters, eg. "Variable XYZ contains @XYZ@". These value replacements can occur anywhere in the text, whereas all other syntactical elements must appear on a line of their own.

+ +Variables can be set and unset using the special #set and #unset commands: +

+#set:VARIABLE=value
+#set:LONGVARIABLE:
+some values containing anything
+#endset
+
+ +The first version of the set-syntax just assigns everything behind the "=" to the variable named before it. The second version of the set-syntax assigns everything between the #set and #unset lines without replacing any values or interpreting any syntax.

+ +Conditional parts of the template text can be put between #if and #endif: +

+#if:VARIABLE==value
+text that only appears if VARIABLE contains value
+#endif
+
+All comparisons are made as string comparisons (this eg. means "2" is greater than "100") with both the variable and the comparison value trimmed. Possible operators are: + + + + + + + +
==matches if the variable contains exactly this value
<matches if the variable is smaller than this value
>matches if the variable is greater than this value
<=matches if the variable is smaller or equal to this value
>=matches if the variable is greater or equal to this value
!= or <>matches if the variable does not contain this value
+ +

Template Files

+ +

layout.html

+ +This is the main template that contains the static parts of all pages displayed by Magic Smoke.

+ +The only variable inside it is @PAGE@ which is replaced by the context created using one of the other templates. + + + \ No newline at end of file -- 1.7.2.5