Changes 2014-03-14
..................

- Added miner overview config
- Added bulk pool add

Intention/Purpose
-----------------

The cgminer API frontend allows you to control several aspects of your minerfarm, after installing the frontend on a webserver that has access to your miner network.

Supported (tested) Version
--------------------------

CGMiner 3.7.2
API 1.32

HOWTO
-----

Extract arcive into /var/www or whatever your DOCROOT is.

Database: api.db into a directory which can't be reached from docroot or rename it to .htapi.db since Apache will refuse to give .ht files to browsers.

Configure in application/config/database.php
$db['default']['hostname'] = 'sqlite:./../.htapi.db'; point to the directory where .htapi.db hides

For your webfrondend to contact the miner API, you have to have at least these settings in your cgminer.conf:

"api-listen" : true,
"api-mcast-port" : "4028",
"api-network" : true,
"api-port" : "4028",
"api-allow" : "W:0/0",
"api-description" : "<Change to unique miner description>" 

!Warning! "api-allow" : "W:0/0" allows ANY host to access your miner!

In order to have only a single IP (of your webserver that runs the frondend) accessing your miner API, just set it to that IP "W:192.168.1.1" 
You also can have a network range allowing access using: "W:192.168.1.0/24"

When you load your site and have no IP numbers set, an error might be displayed.

Click on [MANAGE] and add one or more IPs to the textfield, one IP number per line
Click send and the IP numbers should be written to the database
Now click on [Back] and the miners should be contracted and hopefully send reply back to the frondend

In the frondend you can now monitor the status of your miners. To manage your pools, expand the display by clicking on the headline. In the pools-table you now have the options to Disable, Switch, Enable or Remove pools.
Above this table, you can add new pools by entering the details and click [+ add].
(Note: you need to have writeaccess ("W:" to your miner for these actions to work)

For each pool, you see four buttons. These allow you to

- [Rem]ove
- [Sw]itch
- [En]able
- [Dis]able

your pools. Enabled pools will be switched automatically when a lower priority pool fails (goes down).

When you click [save], the frontend tells the miner to save the actual running config under default filename (.cgminer/cgminer.conf) so your setting stay on rebooting the miner.

Changing the miners's overview
----------------------------

To change the miners's overview, go to [CONFIG] and you will meet a table with all fields currently shown.
To add fields, select one or more from the multiple-choices-form below the table
Hold ctrl while clicking to select/unselect multiple options.

Press [send] to write your changes to the config and click [^Back] to go back to your miner's overview.

Bulk adding pools
-----------------

You are now able to add one pools to all your miners at once. However this requires your workers to be set up in a certain format:

Enter the username.worker followed by a # what will cause the script to count from 1 to the number of your miners.
Therefore workers at that pool must have all the same name, just followed a number starting at 1

Enter into the field:
user.worker#

Produces per miner:
user.worker1
user.worker2
user.workerN

All must have the same password

P2Pools:
--------

When using p2pools, that require you to enter your payout address, just enter the address WITHOUT # your miners will then use all the same username, not adherencing a number.

!IMPORTANT! when you click [save] at the bulk-add formular, the configs of all miners will be saved!

Unfortunately as of now, you still have to enable/switch all added pools manually, but at least the new feature spares you to enter the same url/user/password multiple times.

Protecting your frontend
------------------------

As of now, the frondend has no login, so if you need a login, please stick with Basic-Auth (.htaccess) for now.

Known issues
------------

Overview messing up:
Sometimes it happens, that cgminer will report all pools as active, what causes the overview table to mess up showing all configured pools.
This is something, cgminer-API sends and not caused by our tool. As of now we don't know a solution for that yet but to hide all extra pools that are reported as active. We however decided not to hide what the API tells us.

Display collapsing when more than one miner view is expanded:
We will implement the display with javascript/ajax soon, what allows us to auto-refresh and keep expanded displays open

Further addition/TODO
---------------------

backend cron
javascript/ajax
statistics
config backup
multicast?