|
|
@@ -1,6 +1,9 @@
|
|
|
|
|
|
This README contains details about the cgminer RPC API
|
|
|
|
|
|
+It also includes some detailed information at the end,
|
|
|
+about using miner.php
|
|
|
+
|
|
|
|
|
|
If you start cgminer with the "--api-listen" option, it will listen on a
|
|
|
simple TCP/IP socket for single string API requests from the same machine
|
|
|
@@ -316,7 +319,7 @@ api-example.c - a 'C' program to access the API (with source code)
|
|
|
|
|
|
miner.php - an example web page to access the API
|
|
|
This includes buttons and inputs to attempt access to the privileged commands
|
|
|
- Read the top of the file (miner.php) for details of how to tune the display
|
|
|
+ See the end of this API-README for details of how to tune the display
|
|
|
and also to use the option to display a multi-rig summary
|
|
|
|
|
|
----------
|
|
|
@@ -533,3 +536,507 @@ Commands:
|
|
|
'cpucount'
|
|
|
'quit'
|
|
|
|
|
|
+----------------------------------------
|
|
|
+
|
|
|
+miner.php
|
|
|
+=========
|
|
|
+
|
|
|
+miner.php is a PHP based interface to the cgminer RPC API
|
|
|
+(referred to simply as the API below)
|
|
|
+
|
|
|
+It can show rig details, summaries and input fields to allow you to change
|
|
|
+cgminer
|
|
|
+You can also create custom summary pages with it
|
|
|
+
|
|
|
+It has two levels to the security:
|
|
|
+1) cgminer can be configured to allow or disallow API access and access level
|
|
|
+ security for miner.php
|
|
|
+2) miner.php can be configured to allow or disallow privileged cgminer
|
|
|
+ access, if cgminer is configured to allow privileged access for miner.php
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+To use miner.php requires a web server with PHP
|
|
|
+
|
|
|
+Basics: On xubuntu 11.04, to install apache2 and php, the commands are:
|
|
|
+ sudo apt-get install apache2
|
|
|
+ sudo apt-get install php5
|
|
|
+ sudo /etc/init.d/apache2 reload
|
|
|
+
|
|
|
+On Fedora 17:
|
|
|
+ yum install httpd php
|
|
|
+ systemctl restart httpd.service
|
|
|
+ systemctl enable httpd.service --system
|
|
|
+
|
|
|
+On windows there are a few options.
|
|
|
+Try one of these (I've never used either one)
|
|
|
+ http://www.apachefriends.org/en/xampp.html
|
|
|
+ http://www.wampserver.com/en/
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+The basic cgminer option to enable the API is:
|
|
|
+
|
|
|
+ --api-listen
|
|
|
+
|
|
|
+or in your cgminer.conf
|
|
|
+
|
|
|
+ "api-listen" : true,
|
|
|
+
|
|
|
+(without the ',' on the end if it is the last item)
|
|
|
+
|
|
|
+If the web server is running on the cgminer computer, the above
|
|
|
+is the only change required to give miner.php basic access to
|
|
|
+the cgminer API
|
|
|
+
|
|
|
+-
|
|
|
+
|
|
|
+If the web server runs on a different computer to cgminer,
|
|
|
+you will also need to tell cgminer to allow the web server
|
|
|
+to access cgminer's API and tell miner.php where cgminer is
|
|
|
+
|
|
|
+Assuming a.b.c.d is the IP address of the web server, you
|
|
|
+would add the following to cgminer:
|
|
|
+
|
|
|
+ --api-listen --api-allow a.b.c.d
|
|
|
+
|
|
|
+or in your cgminer.conf
|
|
|
+
|
|
|
+ "api-listen" : true,
|
|
|
+ "api-allow" : "a.b.c.d",
|
|
|
+
|
|
|
+to tell cgminer to give the web server read access to the API
|
|
|
+
|
|
|
+You also need to tell miner.php where cgminer is.
|
|
|
+Assuming cgminer is at IP address e.f.g.h, then you would
|
|
|
+edit miner.php and change the line
|
|
|
+
|
|
|
+ $rigs = array('127.0.0.1:4028');
|
|
|
+
|
|
|
+to
|
|
|
+
|
|
|
+ $rigs = array('e.f.g.h:4028');
|
|
|
+
|
|
|
+See --api-network or --api-allow for more access details
|
|
|
+and how to give write access
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Once you have a web server with PHP running
|
|
|
+
|
|
|
+ copy your miner.php to the main web folder
|
|
|
+
|
|
|
+On Xubuntu 11.04
|
|
|
+ /var/www/
|
|
|
+
|
|
|
+On Fedora 17
|
|
|
+ /var/www/html/
|
|
|
+
|
|
|
+On Windows
|
|
|
+ see your windows Web/PHP documentation
|
|
|
+
|
|
|
+Assuming the IP address of the web server is a.b.c.d
|
|
|
+Then in your web browser go to:
|
|
|
+
|
|
|
+ http://a.b.c.d/miner.php
|
|
|
+
|
|
|
+Done :)
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+The rest of this documentation deals with the more complex
|
|
|
+functions of miner.php, using myminer.php, creaing custom
|
|
|
+summaries and displaying multiple cgminer rigs
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+If you create a file called myminer.php in the same web folder
|
|
|
+where you put miner.php, miner.php will load it when it runs
|
|
|
+
|
|
|
+This is useful, to put any changes you need to make to miner.php
|
|
|
+instead of changing miner.php
|
|
|
+Thus if you update/get a new miner.php, you won't lose the changes
|
|
|
+you have made if you put all your changes in myminer.php
|
|
|
+(and don't change miner.php at all)
|
|
|
+
|
|
|
+A simple example myminer.php that defines 2 rigs
|
|
|
+(that I will keep referring to further below) is:
|
|
|
+
|
|
|
+<?php
|
|
|
+#
|
|
|
+$rigs = array('192.168.0.100:4028:A', '192.168.0.102:4028:B');
|
|
|
+#
|
|
|
+?>
|
|
|
+
|
|
|
+Changes in myminer.php superscede what is in miner.php
|
|
|
+However, this is only valid for variables in miner.php before the
|
|
|
+2 lines where myminer.php is included by miner.php:
|
|
|
+
|
|
|
+ if (file_exists('myminer.php'))
|
|
|
+ include_once('myminer.php');
|
|
|
+
|
|
|
+Every variable in miner.php above those 2 lines, can be changed by
|
|
|
+simply defining them in your myminer.php
|
|
|
+
|
|
|
+So although miner.php originally contains the line
|
|
|
+
|
|
|
+ $rigs = array('127.0.0.1:4028');
|
|
|
+
|
|
|
+if you created the example myminer.php given above, it would actually
|
|
|
+change the value of $rigs that is used when miner.php is running
|
|
|
+i.e. you don't have to remove or comment out the $rigs line in miner.php
|
|
|
+It will be superceded by myminer.php
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+The example.php above also shows how to define more that one rig to
|
|
|
+be shown my miner.php
|
|
|
+
|
|
|
+Each rig string is 2 or 3 values seperated by colons ':'
|
|
|
+They are simply an IP address or host name, followed by the
|
|
|
+port number (usually 4028) and an optional Name string
|
|
|
+
|
|
|
+miner.php displays rig buttons that will show the defails of a single
|
|
|
+rig when you click on it - the button shows either the rig number,
|
|
|
+or the 'Name' string if you provide it
|
|
|
+
|
|
|
+PHP arrays contain each string seperated by a comma, but no comma after
|
|
|
+the last one
|
|
|
+
|
|
|
+So an example for 3 rigs would be:
|
|
|
+
|
|
|
+ $rigs = array('192.168.0.100:4028:A', '192.168.0.102:4028:B', '192.168.0.110:4028:C');
|
|
|
+
|
|
|
+Of course each of the rigs listed would also have to have the API
|
|
|
+running and be set to allow the web server to access the API - as
|
|
|
+explained before
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+So basically, any variable explained below can be put in myminer.php
|
|
|
+if you wanted to set it to something different to it's default value
|
|
|
+and did not want to change miner.php itself every time you updated it
|
|
|
+
|
|
|
+Below is each variable that can be changed and an explanation of each
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $readonly = false;
|
|
|
+
|
|
|
+Set $readonly to true to force miner.php to be readonly
|
|
|
+This means it won't allow you to change cgminer even if the cgminer API
|
|
|
+options allow it to
|
|
|
+
|
|
|
+If you set $readonly to false then it will check cgminer 'privileged'
|
|
|
+and will show input fields and buttons on the single rig page
|
|
|
+allowing you to change devices, pools and even quit or restart
|
|
|
+cgminer
|
|
|
+
|
|
|
+However, if the 'privileged' test fails, the code will set $readonly to
|
|
|
+true
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $notify = true;
|
|
|
+
|
|
|
+Set $notify to false to NOT attempt to display the notify command
|
|
|
+table of data
|
|
|
+
|
|
|
+Set $notify to true to attempt to display the notify command on
|
|
|
+the single rig page
|
|
|
+If your older version of cgminer returns an 'Invalid command'
|
|
|
+coz it doesn't have notify - it just shows the error status table
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $checklastshare = true;
|
|
|
+
|
|
|
+Set $checklastshare to true to do the following checks:
|
|
|
+If a device's last share is 12x expected ago then display as an error
|
|
|
+If a device's last share is 8x expected ago then display as a warning
|
|
|
+If either of the above is true, also display the whole line highlighted
|
|
|
+This assumes shares are 1 difficulty shares
|
|
|
+
|
|
|
+Set $checklastshare to false to not do the above checks
|
|
|
+
|
|
|
+'expected' is calculated from the device MH/s value
|
|
|
+So for example, a device that hashes at 380MH/s should (on average)
|
|
|
+find a share every 11.3s
|
|
|
+If the last share was found more than 11.3 x 12 seconds (135.6s) ago,
|
|
|
+it is considered an error and highlighted
|
|
|
+If the last share was found more than 11.3 x 8 seconds (90.4s) ago,
|
|
|
+it is considered a warning and highlighted
|
|
|
+
|
|
|
+The default highlighting is very subtle
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $poolinputs = false;
|
|
|
+
|
|
|
+Set $poolinputs to true to show the input fields for adding a pool
|
|
|
+and changing the pool priorities on a single rig page
|
|
|
+However, if $readonly is true, it will not display them
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $rigs = array('127.0.0.1:4028');
|
|
|
+
|
|
|
+Set $rigs to an array of your cgminer rigs that are running
|
|
|
+ format: 'IP:Port' or 'Host:Port' or 'Host:Port:Name'
|
|
|
+If you only have one rig, it will just show the detail of that rig
|
|
|
+If you have more than one rig it will show a summary of all the rigs
|
|
|
+ with buttons to show the details of each rig -
|
|
|
+ the button contents will be 'Name' rather than rig number, if you
|
|
|
+ specify 'Name'
|
|
|
+e.g. $rigs = array('127.0.0.1:4028','myrig.com:4028:Sugoi');
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $rigtotals = true;
|
|
|
+ $forcerigtotals = false;
|
|
|
+
|
|
|
+Set $rigtotals to true to display totals on the single rig page
|
|
|
+'false' means no totals (and ignores $forcerigtotals)
|
|
|
+
|
|
|
+If $rigtotals is true, all data is also right aligned
|
|
|
+With false, it's as before, left aligned
|
|
|
+
|
|
|
+This option is just here to allow people to set it to false
|
|
|
+if they prefer the old non-total display when viewing a single rig
|
|
|
+
|
|
|
+Also, if there is only one line shown in any section, then no
|
|
|
+total will be shown (to save screen space)
|
|
|
+You can force it to always show rig totals on the single rig page,
|
|
|
+even if there is only one line, by setting $forcerigtotals = true;
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $socksndtimeoutsec = 10;
|
|
|
+ $sockrcvtimeoutsec = 40;
|
|
|
+
|
|
|
+The numbers are integer seconds
|
|
|
+
|
|
|
+The defaults should be OK for most cases
|
|
|
+However, the longer SND is, the longer you have to wait while
|
|
|
+php hangs if the target cgminer isn't runnning or listening
|
|
|
+
|
|
|
+RCV should only ever be relevant if cgminer has hung but the
|
|
|
+API thread is still running, RCV would normally be >= SND
|
|
|
+
|
|
|
+Feel free to increase SND if your network is very slow
|
|
|
+or decrease RCV if that happens often to you
|
|
|
+
|
|
|
+Also, on some windows PHP, apparently the $usec is ignored
|
|
|
+(so usec can't be specified)
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $hidefields = array();
|
|
|
+
|
|
|
+List of fields NOT to be displayed
|
|
|
+You can use this to hide data you don't want to see or don't want
|
|
|
+shown on a public web page
|
|
|
+The list of sections are:
|
|
|
+ SUMMARY, POOL, PGA, GPU, NOTIFY, CONFIG, DEVDETAILS, DEVS
|
|
|
+See the web page for the list of field names (the table headers)
|
|
|
+It is an array of 'SECTION.Field Name' => 1
|
|
|
+
|
|
|
+This example would hide the slightly more sensitive pool information:
|
|
|
+Pool URL and pool username:
|
|
|
+ $hidefields = array('POOL.URL' => 1, 'POOL.User' => 1);
|
|
|
+
|
|
|
+If you just want to hide the pool username:
|
|
|
+ $hidefields = array('POOL.User' => 1);
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $ignorerefresh = false;
|
|
|
+ $changerefresh = true;
|
|
|
+ $autorefresh = 0;
|
|
|
+
|
|
|
+Auto-refresh of the page (in seconds) - integers only
|
|
|
+
|
|
|
+$ignorerefresh = true/false always ignore refresh parameters
|
|
|
+$changerefresh = true/false show buttons to change the value
|
|
|
+$autorefresh = default value, 0 means dont auto-refresh
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $placebuttons = 'top';
|
|
|
+
|
|
|
+Where to place the Refresh, Summary, Custom Pages, Quit, etc. buttons
|
|
|
+
|
|
|
+Valid values are: 'top' 'bot' 'both'
|
|
|
+ anything else means don't show them - case sensitive
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $miner_font_family = 'verdana,arial,sans';
|
|
|
+ $miner_font_size = '13pt';
|
|
|
+
|
|
|
+Change these to set the font and font size used on the web page
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $colouroverride = array();
|
|
|
+
|
|
|
+Use this to change the web page colour scheme
|
|
|
+
|
|
|
+See $colourtable in miner.php for the list of possible names to change
|
|
|
+
|
|
|
+Simply put in $colouroverride, just the colours you wish to change
|
|
|
+
|
|
|
+e.g. to change the colour of the header font and background
|
|
|
+you could do the following:
|
|
|
+
|
|
|
+ $colouroverride = array(
|
|
|
+ 'td.h color' => 'green',
|
|
|
+ 'td.h background' => 'blue'
|
|
|
+ );
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Default:
|
|
|
+ $allowcustompages = true;
|
|
|
+
|
|
|
+Should we allow custom pages?
|
|
|
+(or just completely ignore them and don't display the buttons)
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+OK this part is more complex: Custom Summary Pages
|
|
|
+
|
|
|
+A custom summary page in an array of 'section' => array('FieldA','FieldB'...)
|
|
|
+
|
|
|
+The section defines what data you want in the summary table and the Fields
|
|
|
+define what data you want shown from that section
|
|
|
+
|
|
|
+Standard sections are:
|
|
|
+ SUMMARY, POOL, PGA, GPU, NOTIFY, CONFIG, DEVDETAILS, DEVS, STATS
|
|
|
+
|
|
|
+Fields are the names as shown on the headers on the normal pages
|
|
|
+
|
|
|
+Fields can be 'name=new name' to display 'name' with a different heading
|
|
|
+'new name'
|
|
|
+
|
|
|
+There are also now joined sections:
|
|
|
+ SUMMARY+POOL, SUMMARY+DEVS, SUMMARY+CONFIG, DEVS+NOTIFY, DEVS+DEVDETAILS
|
|
|
+
|
|
|
+These sections are an SQL join of the two sections and the fields in them
|
|
|
+are named section.field where section. is the section the field comes from
|
|
|
+See the example further down
|
|
|
+
|
|
|
+Also note:
|
|
|
+- empty tables are not shown
|
|
|
+- empty columns (e.g. an unknown field) are not shown
|
|
|
+- missing field data shows as blank
|
|
|
+- the field name '*' matches all fields except in joined sections
|
|
|
+ (useful for STATS)
|
|
|
+
|
|
|
+There are 2 hard coded sections:
|
|
|
+ DATE - displays a date table like 'Summary'
|
|
|
+ RIGS - displays a rig table like 'Summary'
|
|
|
+
|
|
|
+Each custom summary requires a second array, that can be empty, listing fields
|
|
|
+to be totaled for each section
|
|
|
+If there is no matching total data, no total will show
|
|
|
+
|
|
|
+---------
|
|
|
+
|
|
|
+Looking at the Mobile example:
|
|
|
+
|
|
|
+ $mobilepage = array(
|
|
|
+ 'DATE' => null,
|
|
|
+ 'RIGS' => null,
|
|
|
+ 'SUMMARY' => array('Elapsed', 'MHS av', 'Found Blocks=Blks',
|
|
|
+ Accepted', 'Rejected=Rej', 'Utility'),
|
|
|
+ 'DEVS+NOTIFY' => array('DEVS.Name=Name', 'DEVS.ID=ID', 'DEVS.Status=Status',
|
|
|
+ 'DEVS.Temperature=Temp', 'DEVS.MHS av=MHS av',
|
|
|
+ 'DEVS.Accepted=Accept', 'DEVS.Rejected=Rej',
|
|
|
+ 'DEVS.Utility=Utility', 'NOTIFY.Last Not Well=Not Well'),
|
|
|
+ 'POOL' => array('POOL', 'Status', 'Accepted', 'Rejected=Rej', 'Last Share Time'));
|
|
|
+
|
|
|
+ $mobilesum = array(
|
|
|
+ 'SUMMARY' => array('MHS av', 'Found Blocks', 'Accepted', 'Rejected', 'Utility'),
|
|
|
+ 'DEVS+NOTIFY' => array('DEVS.MHS av', 'DEVS.Accepted', 'DEVS.Rejected', 'DEVS.Utility'),
|
|
|
+ 'POOL' => array('Accepted', 'Rejected'));
|
|
|
+
|
|
|
+ $customsummarypages = array('Mobile' => array($mobilepage, $mobilesum));
|
|
|
+
|
|
|
+This will show 5 tables (according to $mobilepage)
|
|
|
+Each table will have the chosen details for all the rigs specified in $rigs
|
|
|
+
|
|
|
+ DATE
|
|
|
+ A single box with the web server's current date and time
|
|
|
+
|
|
|
+ RIGS
|
|
|
+ A table of the rigs: description, time, versions etc
|
|
|
+
|
|
|
+ SUMMARY
|
|
|
+
|
|
|
+ This will use the API 'summary' command and show the selected fields:
|
|
|
+ Elapsed, MHS av, Found Blocks, Accepted, Rejected and Utility
|
|
|
+ However, 'Rejected=Rej' means that the header displayed for the 'Rejected'
|
|
|
+ field will be 'Rej', instead of 'Rejected' (to save space)
|
|
|
+ Same for 'Found Blocks=Blks' - to save space
|
|
|
+
|
|
|
+ DEVS+NOTIFY
|
|
|
+
|
|
|
+ This will list each of the devices on each rig and display the list of
|
|
|
+ fields as shown
|
|
|
+ It will also include the 'Last Not Well' field from the 'notify' command
|
|
|
+ so you know when the device was last not well
|
|
|
+
|
|
|
+ You will notice that you need to rename each field e.g. 'DEVS.Name=Name'
|
|
|
+ since each field name in the join between DEVS and NOTIFY is actually
|
|
|
+ section.fieldname, not just fieldname
|
|
|
+
|
|
|
+ The join code automatically adds 2 fields to each GPU device: 'Name' and 'ID'
|
|
|
+ They don't exist in the API 'devs' output but you can correctly calculate
|
|
|
+ them from the GPU device data
|
|
|
+ These two fields are used to join DEVS to NOTIFY i.e. find the NOTIFY
|
|
|
+ record that has the same Name and ID as the DEVS record and join them
|
|
|
+
|
|
|
+ POOL
|
|
|
+
|
|
|
+ This will use the API 'pools' command and show the selected fields:
|
|
|
+ POOL, Status, Accepted, Rejected, Last Share Time
|
|
|
+ Again, I renamed the 'Rejected' field using 'Rejected=Rej', to save space
|
|
|
+
|
|
|
+$mobilesum lists the sections and fields that should have a total
|
|
|
+You can't define them for 'DATE' or 'RIGS' since they are hard coded tables
|
|
|
+The example given:
|
|
|
+
|
|
|
+ SUMMARY
|
|
|
+ Show a total at the bottom of the columns for:
|
|
|
+ MHS av, Found Blocks, Accepted, Rejected, Utility
|
|
|
+
|
|
|
+ Firstly note that you use the original name i.e. for 'Rejected=Rej'
|
|
|
+ you use 'Rejected', not 'Rej' and not 'Rejected=Rej'
|
|
|
+
|
|
|
+ Secondly note that it simply adds up the fields
|
|
|
+ If you ask for a total of a string field you will get the numerical
|
|
|
+ sum of the string data
|
|
|
+
|
|
|
+ DEVS+NOTIFY
|
|
|
+
|
|
|
+ Simply note in this join example that you must use the original field
|
|
|
+ names which are section.fieldname, not just fieldname
|
|
|
+
|
|
|
+ POOL
|
|
|
+ Show a total at the bottom of the columns for:
|
|
|
+ Accepted and Rejected
|
|
|
+
|
|
|
+ Again remember to use the original field name 'Rejected'
|
Con Kolivas