Previous Up Next
StockManiac Manual StockManiac Manual Developer Guide

Administrator Guide

This part of the manual describes how to install StockManiac and how to perform administrative work.

Table of Contents

  • Security
  • Introduction

    OK. You got a release of StockManiac and, of course, you would like to install and start managing your stocks (and become rich soon ;-) ).

    To make this short and simple: the first chapter contains the software requirements. Most of this software is pretty much 'standard'. So it ships with many recent Linux distributions and other free Operating Systems. If you have one of those platforms, there should be no problem to match this list. If not. I'am pretty sure this software is available for your platform. It may just need some handwork.

    Anyway, on a recent Linux distribution you can skip most of the chapter. Except 'Finance::Quote'. This may not ship with your Distribution. So you have to download and install it manually some way or the other.

    The second chapter contains a step-by-step installation procedure. Follow through and you should end up with a nice copy of StockManiac... now go ahead!


    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

    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.


    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.


    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 tarballs are quite platform independend and should work on any Unix style operating system. Maybe even Windows (never tested). Installing them, however, requires a certain amount of manual work...

    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
    you may install one or all of them on one or more computers. Daemon and GUI may run on different computers. The only requirement is that both can connect to the same database.

    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
    and you're done (provided all dependencies are met). Proceed with FIXME: link to (create MySQL database and add account)'.

    Installing from Tarball

    The file you downloaded should look like

    Now move this file to somewhere inside the DocumentRoot of your web server.

    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
    went there, uncompress and remove the package. (you don't need it anymore)
    $ cd /var/www/html
    $ tar -xzvf stockmaniac-gui-<VERSION>.tar.gz
    $ rm -f stockmaniac-gui-<VERSION>.tar.gz
    this will create a directory 'stockmaniac'. So go in there...
    $ cd stockmaniac
    and proceed from here.

    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
    it should look similar to
    $ 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
    of course you may tweak the user, group and/or mode to match with your system. Important is that your webserver can write files in these directories. Else it usually results in a empty page when you try to logon the first time.

    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/ as

    1. define('PATH_CACHE''/tmp/StockManiac');
    Please make sure that this directory exists and that nothing deletes it (some systems occasional wipe out /tmp). If unsure change it to another directory (ie. /var/tmp/StockManiac might be better). Important is that:
    • the webserver can read/write it
    • it is outside of any DocumentRoot of your webserver
    Now you're done with the basic stuff.

    You may do further adjustments to 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
    Now StockManiac needs an SQL account to connect to the database. Best is to create a somewhat restricted one in order to improve installation security.

    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
        -> 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)
    Query OK, 0 rows affected, 1 warning (0.06 sec)
    mysql> exit
    I recommend to set a very long password as its not for use by humans. Ie a MD5 or SHA1 sum generated from lots of data junk is good.

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

    config/                (-> tarball install)
    /etc/stockmaniac/      (-> RedHat/Fedora RPM install)
    Move on to the code directory. You need to fill the database.
    $ cd install.d                            (-> tarball install)
    $ cd /usr/share/stockmaniac/install.d     (-> RedHat/Fedora RPM install)
    You will find a couple sql files here:
    $ 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 first one (mysql-structure.sql) will just create an empty set of tables. This is recommended way if you want to use StockManiac with your own data in production.

    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
    Now you should be able to logon and start using StockManiac. Impatient people may just skip to the Test Section below.

    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.


    • 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
    You should run this command each time Finance::Quote is updated (which does not happen every week).

    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/ at around line 64.

    If you want US $ then just change:

    If you want some other currency, you'll need to know the official symbol. You may look at yahoo! Finance or some other appropriate place. Then replace "USD" with whatever you prefer.


    • 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


    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

    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
    If you have used mysql-testdata.sql previously it will be:
    username: admin
    password: admin
    username: demo1
    password: demo
    username: demo2
    password: demo
    Now the main page of StockManiac should come up. Either filled with some test data or just empty, in case you have choosen the structure dump.

    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.


    • 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


    This chapter does only cover the most critical topics when using StockManiac. It is very far away from being something like a HOWTO secure my WebServer and Database server discussion

    Webserver and Database security is a very complex topic that I don't want to discuss here. There are many sites and newsgroups out there discussing these things.

    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.


    • 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.


    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!


    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
    There is a re-design planed that will take this into account.

    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...).
    If you see a weekness (and a way to solve it) please let me know.

    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 file allows it and the RPM packages actually do it.

    Previous Up Next
    StockManiac Manual StockManiac Manual Developer Guide

    Documentation generated on Sun, 22 Aug 2010 11:20:08 +0200 by phpDocumentor 1.4.3