HTTP server

A working web server with the ability to connect to a SQL database is required in order to run StockManiac. I use Apache for the development. It's available for a large number of platforms. Just have a look at the Apache Project Site

there, you can get the source, binaries and a lot documentation. If you don't want to use apache (I really don't know why) then each other web server that can deal with PHP should do as well. But this has never been tested. So feedback is very welcome (except for IIS! I just don't want to try with this weird software nor do any kind of development with/for it).

SQL Database

StockManiac does only work with MySQL. Support for other SQL databases, such as PostgreSQL, is on the long term todo list in my mind. I just can't tell when this will become implemented. So for now you need access to a MySQL server. Or just install one if you don't have it. You can get it right from http://www.mysql.org

From v0.9.1 onwards you have to have MySQL v4.1.x. The development systems runs at v5.1.37 right now. Note that StockManiac releases are not being tested in MySQL v4.x any longer.

Versions up to v0.9.0 still work on MySQL v3.23.x and v4.0.x.

MySQL ships with many distributions. Likely that you have it already.

PHP

This is the most critical part when talking about version numbers. At least you need to have PHP5. The project started off with PHP4 but this is no longer tested and therefor very unlikely to work.

Development is done with PHP 5.2.x. But it should still run on any 5.x release as I do not use very recently introduced functions.

Note that a number of - more or less - standard extension are required to run StockManiac. Here are the essentials:

• php-mysql
• php-gd
• php-xmlrpc

Get php from the PHP project if it is not shipped with your distribution. Most likely you have it already or can install it easily with your distributions package manager.

Hardware

My WebServer, that is also holding the database, is a Intel Celeron 2 GHz box with 1 GByte of Memory. This appears to be more than fast enough.

The older Celeron 500/196 MByte Memory box became too slow. The main reason is not StockManiac: I am also running eGroupWare on it, which requires a lot of memory.

On the last day with the Celeron 500 I had roughly ~100000 Quote records and ~50000 NewsItem records. The GUI was not blazing fast, but had acceptable response times (with StockManiac v0.9.7). Depending on your amount of data, a similar or faster box will do fine.

The Celeron 2GHz/1GByte Memory box is a bit of overkill when StockManiac is the only application

Decide which package to use

First of all make sure that all software from above is either installed and configured or available through package management (the later might even obsolete this step).

StockManiac is distributed in various formats. Just take the one that fits best to your operationg system. Right now, there are

• tarballs
• RPM packages for Fedora/RedHat based systems (check what has been build and released on the download page, I am also happy to accept contributed package builds for other distributions)

The Fedora/RedHat RPMs were designed according to the Fedora Project Packaging guidelines. Installation and later upgrades are completely automatic (maybe I can get it into fedora-extras someday).

All packages (tarballs, RPMs, ...) follow the same naming convention:

	stockmaniac-gui-<VERSION>.<ext>     --> the web application
	stockmaniac-daemon-<VERSION>.<ext>  --> the stockmaniacd daemon
	...
	stockmaniac-manual-<VERSION>.<ext>  --> the manual

Get the latest StockManiac release from the SourceForge File Release System and proceed...

Installing with RPM

With a certain degree of luck you will find ready-to-go RPM packages for your version of Fedora/RedHat. Just do

$ rpm -ivh stockmaniac-gui-<VERSION>.rpm

Installing from Tarball

The file you downloaded should look like

stockmaniac-gui-<VERSION>.tar.gz

Don't know where the DocumentRoot is? Just read the web server documentation. In the example I use the path were RedHat/Fedora puts it by default.

$ mv stockmaniac-gui-<VERSION>.tar.gz /var/www/html

$ cd /var/www/html
$ tar -xzvf stockmaniac-gui-<VERSION>.tar.gz
$ rm -f stockmaniac-gui-<VERSION>.tar.gz

$ cd stockmaniac

adjust permissions and create cache

Now make sure that your web server can write compiled templates and pages to the cache directories. On many ditributions this is done by something similar to this:

$ chown apache.apache templates_c templates_cache
$ chmod 770 templates_c templates_cache

$ ls -lad templates_c*
drwxrwx---  3 apache apache 4096 Mar  3 15:50 templates_c
drwxrwx---  3 apache apache 4096 Feb  5 14:44 templates_cache

The cache directory is required to store PHP session data as well as rendered graphs and templates.

The default for PHP sessions is /tmp on most systems. But since StockManiac sessions might contain sensitive information (I try to avoid that) you might want to use another less public directory. The constant is defined in config/path.inc.php as

• the webserver can read/write it
• it is outside of any DocumentRoot of your webserver

You may do further adjustments to path.inc.php in order to integrate StockManiac better into your specific environment. Now is a good time. Otherwise just proceed...

Create the MySQL database

First you have to have a empty database. This is easy:

$ mysql -u root -p
< key in the root password >

mysql> CREATE DATABASE <Database>;
Query OK, 1 row affected (0.04 sec)

mysql> exit
Bye
$

The easiest way to do this is by using the stockmaniac-admin tool which ships with the daemon package. Use the --create-gui-account option and follow the instructions. Its interactive.

Less easy is creating the account manually. The GUI only needs standard data manipulation privileges on all tables. More advanced statements, ie for manipulating the table structure (CREATE, ALTER, DROP, ...) are *not* required. Create the account like this:

$ mysql -u root -p
< key in the root password >

mysql> GRANT
    -> SELECT,INSERT,UPDATE,DELETE
    -> ON <Database>.*
    -> TO <Username>@<Hostname>;
Query OK, 0 rows affected (0.35 sec)

mysql> SET PASSWORD FOR <Username>@<Hostname> = PASSWORD('XXXXXXXXXXXXX');
Query OK, 0 rows affected (0.09 sec)

mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected, 1 warning (0.06 sec)

mysql> exit
Bye
$

Now that you have an SQL account, put the credentials in:

config/stockmaniac.inc.php                (-> tarball install)
/etc/stockmaniac/stockmaniac.inc.php      (-> RedHat/Fedora RPM install)

$ cd install.d                            (-> tarball install)
$ cd /usr/share/stockmaniac/install.d     (-> RedHat/Fedora RPM install)

$ ls -l
total 24
-rwxrwxr-x    1 ebest    ebest  7321 Jan 23 10:39 mysql-structure.sql
-rwxrwxr-x    1 ebest    ebest  7321 Jan 23 10:39 mysql-testdata.sql

The second file (mysql-testdata.sql) will create the tables and pre-load them with sample data. This is if you want to play around with StockManiac first. Of course, you may drop the testdata at any time and load the structure dump for real usage (or just use two databases and switch the config file...).

Oh, and developers may use this as reference data when testing and/or implementing new features.

So just run one of them:

$ mysql -p -u root <Database> < mysql-structure.sql

$ mysql -p -u root <Database> < mysql-testdata.sql

More patient fellows may do a short logon test to verify the correctness of all previous steps and then proceed with the rest of the setup process. Ie if the login page shows up without any error, its a good sign. :-)

Migrate to a higher Version

If you are installing from scratch, just skip this topic.

If you are using StockManiac already, you probably have a database with a lot of orders, stocks, positions, quotes, ... etc...

When a new version is released you probably like to upgrade. But you certainly do not like to re-create your database and key in all data again, from scratch. Therefore migration is the way you want to go.

All you have to do to migrate your data is: install and configure the new release as explained above (in case of RPM: rpm -Uvh ... is usully sufficient).

Then point your browser to the login page. Once you are authenticated StockManiac will detect a discrepancy in your database version. Thus, it will automatically redirect you to the built-in migration tool.

The migration tool will give some details about the discrepancy. Also it shows what migration scripts are required (and found) and in which order they will run. In addition it mentions some issues to think about before doing the migration. It is always good to read that.

You will be asked to give your OK before anything is done.

During the migration process you might want to make sure that nobody can access your webserver (as StockManiac may produce some unpredictable errors when someone tries to work on a half-migrated database). A good way to lock others out is to create a temporay .htaccess file that protects the StockManiac directory for the time being.

Note:

• the migration will often do structural changes on your database. So you need a mySQL login that has permission to do so. The tool will ask for one. You may use root here. The password is not stored anywhere.
• each StockManiac release will include all older migration scripts. At least from v0.8.0 on (the migration process has been redesigned completely between v0.7.0 and v0.8.0).
• you can NOT migrate from any release previous v0.7.0 to v0.8.0 or above. You have to go to v0.7.0 first!
• please *always* read the Release Notes and the ChangeLog file

Update Quote Sources

If you like automatic quote updates, you probably want to install the daemon package too.

Anyhow, the GUI needs to know which quote sources are available so you can fine-tune the retrieval. This information is cached in the database and the stockmaniac-admin tool can fill it. Like so:

stockmaniac-admin --update-sources

Set Currency

Right now StockManiac does not support multiple currencies. It simply does not care about currency at all. As a consequence it just assumes that all incoming numbers (quotes, charges, dividend, ...) are of one and the same currency.

You are free to adjust this one currency. The default is euro (EUR) and its hardcoded deep down in the daemon, at StockManiac/Quote.pm at around line 64.

If you want US $ then just change:

$self->{'FQ'}->set_currency('EUR');

$self->{'FQ'}->set_currency('USD');

ATTENTION:

• change this ONLY if your database is still EMPTY! (no transactions, no quotes, no positions, no anything, ...)
• otherwise StockManiac will add apples and oranges together, the result is everything but useful

Test

Take a browser and key in the name (or address) of your web server followed by the path to StockManiac. The URL is perhaps http://localhost/stockmaniac or http://127.0.0.1/stockmaniac.

Now, you should see StockManiac's login page.

Next, key in the username and password combination. From v0.9.0 onwards this will be the default admin account that is contained in the dumps or has been created during the migration.

username: admin
password: kj87Ju

username: admin
password: admin

username: demo1
password: demo

username: demo2
password: demo

Then proceed to the new Settings tool and change the password right away. Do this for all accounts. From that point on the installation is secure and can be exposed to the public.

Accounts that have the 'admin' flag enabled have the exclusive right to reset other account passwords. On reset StockManiac will create a random password which the administrator must distribute to the individual user.

The user should take that password to login, then proceed to the Setting tool and change it immediately. Every user is only allowed to change his own password.

Now, you're done. Enjoy StockManiac!

In case something does not work, it is probably not yet installed/configured properly. Perhaps you already know what is. If not just read this file again.

If it works, you are really done.

Note:

• all accounts existing before v0.9.0 still have an empty password. This means they can not login because StockManiac does not accept empty passwords.
• use a admin account to manually reset passwords for these users

Hardening the Installation

StockManiac is a web application written in PHP. As such it suffers from all the common issues associated with that.

However, there are certain steps you can perform in order to make your installation more robust:

PHP itself has a number of options to limit what scripts can do. Together with apache you can apply some of them on a per-directory basis. Most notable are probably 'open_basedir' and 'upload_tmp_dir'.

Use open_basedir to define areas where StockManiac can open/close/change/... files. That does *not* prevent an attacker from exploiting a bug. But if he is successful he will be limited to the few defined areas at least. Thus he can't explore the rest of your system that easily.

Upload_tmp_dir is usually configured to /tmp by default. Thus an attacker can write your system temp through StockManiac. Create a separate directory which can only be used (read) by apache - nobody else. This must also be within the bounderies set in open_basedir.

Hint:

• The RPM packages set these things by default. Have a look inside to see how exactly.

Make sure all souce code files are owned by root. Apache should *never* be owner of installation files. There should be *no* write privileges on group and others.

Use a restricted SQL account for the GUI as well as an even more restricted one for the Daemon. This should at least prevent an attacker from further exploring your MySQL server. Such accounts can be created with the stockmaniac-admin tool.

If you are really concerned about security (I am not saying paranoid): separate the webserver from the database server and from the host that runs the daemon. Of course, this requires additional hardware and is an advanced topic - so I do not dig deeper into it.

SSL

Since StockManiac might hold a lot data about your financial situation I urge everyone to use it *only* via SSL. Else your data will flow unencrypted through the network/internet. Almost everyone would be able to sniff it. Probably this is not what you want.

So choose a web server that supports SSL and configure it... but be aware that SSL wont make your browser or computer more secure. There could always be something like a 'keyboard sniffer' on your client machine. So *think* about that while walking into the next Internet Cafe!

MySQL

Set a root password. Check what accounts are actually existing. Do not leave backup dumps in /tmp/ ... etc...

Use the stockmaniac-admin (FIXME: link it) utility to create restricted accounts for the gui, the daemon and for backups.

Consider running the database on a separate [virtual] machine which is doing nothing except running the SQL service.

Issues to think about

ISSUE 1

From version v0.9.5 onwards StockManiac contains a basic protection against SQL Injection attacks. It escapes just everything that is coming in via $_REQUEST.

Of course, this is not a sufficient solution. As there are other posibilities to sneak something in. It's just a quick implementation until I have time to do it right. For that reason

StockManiac IS considered VULNERABLE TO SQL-INJECTION

Until that happens please be aware of it. For now, a practicable solution is to protect the installation with a '.htaccess' file. That will at least limit down the number of potential attackers.

Further you should give accounts only to people you can trust.

Please do not hesitate to report any vulnerability you find.

ISSUE 2

Cross-Site-Scripting (also called XSS): StockManiac does hardly do any input validation (except sql escaping, see above). So it is possible to sneak HTML or JavaScript code into the database.

Could that be exploited to run XSS attacks?

YES - user A could sneak in some code to collect Session IDs of the users B, C and D. Then he's able to login to their accounts.

One thing I can say is that StockManiac does *not* use any JavaScript code itself. So you may just turn it off in your browser. The other immediate solution is similar to the above: give accounts only to people you can trust.

This issue will be addressed during the upcoming design phase as well.

For now, all reports/ideas/suggestions on this are appreciated.

ISSUE 3

The new password handling (in versions >= 0.9.0) works like this:

• the user has to key in the password once (were it passes the network as plain text - if SSL is not used)
• StockManiac verifies the password against an MD5 hash, stored in the User table.
• if the password is correctn, an this-user-has-authenticated-successfully mark is added to the session - thus: no hash is stored in the session
• the hash is not available inside the program. So e.g. plugins can not access it (well, unless they query the database directly...).

ISSUE 4

Right now compiled templates are stored in the templates_c directory inside StockManiac. Anyone can browse that through the web without authentication. I am not certain if this is a security hole.

It might be good advice to move it outside the DocumentRoot. The path.inc.php file allows it and the RPM packages actually do it.