|
|
|
|
|
|
|
This README contains details about the cgminer RPC API
|
|
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
running cgminer and reply with a string and then close the socket each time
|
|
|
|
If you add the "--api-network" option, it will accept API requests from any
|
|
|
|
network attached computer.
|
|
|
|
|
|
|
|
You can only access the comands that reply with data in this mode.
|
|
|
|
By default, you cannot access any privileged command that affects the miner -
|
|
|
|
you will receive an access denied status message see --api-allow below.
|
|
|
|
|
|
|
|
You can specify IP addresses/prefixes that are only allowed to access the API
|
|
|
|
with the "--api-allow" option e.g. --api-allow W:192.168.0.1,10.0.0/24
|
|
|
|
will allow 192.168.0.1 or any address matching 10.0.0.*, but nothing else
|
|
|
|
IP addresses are automatically padded with extra '.0's as needed
|
|
|
|
Without a /prefix is the same as specifying /32
|
|
|
|
0/0 means all IP addresses.
|
|
|
|
The 'W:' on the front gives that address/subnet privileged access to commands
|
|
|
|
that modify cgminer (thus all API commands)
|
|
|
|
Without it those commands return an access denied status.
|
|
|
|
See --api-groups below to define other groups like W:
|
|
|
|
Privileged access is checked in the order the IP addresses were supplied to
|
|
|
|
"--api-allow"
|
|
|
|
The first match determines the privilege level.
|
|
|
|
Using the "--api-allow" option overides the "--api-network" option if they
|
|
|
|
are both specified
|
|
|
|
With "--api-allow", 127.0.0.1 is not by default given access unless specified
|
|
|
|
|
|
|
|
More groups (like the privileged group W:) can be defined using the
|
|
|
|
--api-groups command
|
|
|
|
Valid groups are only the letters A-Z (except R & W are predefined) and are
|
|
|
|
not case sensitive
|
|
|
|
The R: group is the same as not privileged access
|
|
|
|
The W: group is (as stated) privileged access (thus all API commands)
|
|
|
|
To give an IP address/subnet access to a group you use the group letter
|
|
|
|
in front of the IP address instead of W: e.g. P:192.168.0/32
|
|
|
|
An IP address/subnet can only be a member of one group
|
|
|
|
A sample API group would be:
|
|
|
|
--api-groups P:switchpool:enablepool:addpool:disablepool:removepool:*
|
|
|
|
This would create a group 'P' that can do all current pool commands and all
|
|
|
|
non-priviliged commands - the '*' means all non-priviledged commands
|
|
|
|
Without the '*' the group would only have access to the pool commands
|
|
|
|
Defining multiple groups example:
|
|
|
|
--api-groups Q:quit:restart:*,S:save
|
|
|
|
This would define 2 groups:
|
|
|
|
Q: that can 'quit' and 'restart' as well as all non-priviledged commands
|
|
|
|
S: that can only 'save' and no other commands
|
|
|
|
|
|
|
|
The RPC API request can be either simple text or JSON.
|
|
|
|
|
|
|
|
If the request is JSON (starts with '{'), it will reply with a JSON formatted
|
|
|
|
response, otherwise it replies with text formatted as described further below.
|
|
|
|
|
|
|
|
The JSON request format required is '{"command":"CMD","parameter":"PARAM"}'
|
|
|
|
(though of course parameter is not required for all requests)
|
|
|
|
where "CMD" is from the "Request" column below and "PARAM" would be e.g.
|
|
|
|
the CPU/GPU number if required.
|
|
|
|
|
|
|
|
An example request in both formats to set GPU 0 fan to 80%:
|
|
|
|
gpufan|0,80
|
|
|
|
{"command":"gpufan","parameter":"0,80"}
|
|
|
|
|
|
|
|
The format of each reply (unless stated otherwise) is a STATUS section
|
|
|
|
followed by an optional detail section
|
|
|
|
|
|
|
|
From API version 1.7 onwards, reply strings in JSON and Text have the
|
|
|
|
necessary escaping as required to avoid ambiguity - they didn't before 1.7
|
|
|
|
For JSON the 2 characters '"' and '\' are escaped with a '\' before them
|
|
|
|
For Text the 4 characters '|' ',' '=' and '\' are escaped the same way
|
|
|
|
|
|
|
|
Only user entered information will contain characters that require being
|
|
|
|
escaped, such as Pool URL, User and Password or the Config save filename,
|
|
|
|
when they are returned in messages or as their values by the API
|
|
|
|
|
|
|
|
For API version 1.4 and later:
|
|
|
|
|
|
|
|
The STATUS section is:
|
|
|
|
|
|
|
|
STATUS=X,When=NNN,Code=N,Msg=string,Description=string|
|
|
|
|
|
|
|
|
STATUS=X Where X is one of:
|
|
|
|
W - Warning
|
|
|
|
I - Informational
|
|
|
|
S - Success
|
|
|
|
E - Error
|
|
|
|
F - Fatal (code bug)
|
|
|
|
|
|
|
|
When=NNN
|
|
|
|
Standard long time of request in seconds
|
|
|
|
|
|
|
|
Code=N
|
|
|
|
Each unique reply has a unigue Code (See api.c - #define MSG_NNNNNN)
|
|
|
|
|
|
|
|
Msg=string
|
|
|
|
Message matching the Code value N
|
|
|
|
|
|
|
|
Description=string
|
|
|
|
This defaults to the cgminer version but is the value of --api-description
|
|
|
|
if it was specified at runtime.
|
|
|
|
|
|
|
|
For API version 1.10 and later:
|
|
|
|
|
|
|
|
The list of requests - a (*) means it requires privileged access - and replies are:
|
|
|
|
|
|
|
|
Request Reply Section Details
|
|
|
|
------- ------------- -------
|
|
|
|
version VERSION CGMiner=cgminer, version
|
|
|
|
API=API| version
|
|
|
|
|
|
|
|
config CONFIG Some miner configuration information:
|
|
|
|
GPU Count=N, <- the number of GPUs
|
|
|
|
PGA Count=N, <- the number of PGAs
|
|
|
|
CPU Count=N, <- the number of CPUs
|
|
|
|
Pool Count=N, <- the number of Pools
|
|
|
|
ADL=X, <- Y or N if ADL is compiled in the code
|
|
|
|
ADL in use=X, <- Y or N if any GPU has ADL
|
|
|
|
Strategy=Name, <- the current pool strategy
|
|
|
|
Log Interval=N, <- log interval (--log N)
|
|
|
|
Device Code=GPU ICA | <- spaced list of compiled devices
|
|
|
|
|
|
|
|
summary SUMMARY The status summary of the miner
|
|
|
|
e.g. Elapsed=NNN,Found Blocks=N,Getworks=N,...|
|
|
|
|
|
|
|
|
pools POOLS The status of each pool
|
|
|
|
e.g. Pool=0,URL=http://pool.com:6311,Status=Alive,...|
|
|
|
|
|
|
|
|
devs DEVS Each available GPU, PGA and CPU with their details
|
|
|
|
e.g. GPU=0,Accepted=NN,MHS av=NNN,...,Intensity=D|
|
|
|
|
Last Share Time=NNN, <- standand long time in seconds
|
|
|
|
(or 0 if none) of last accepted share
|
|
|
|
Last Share Pool=N, <- pool number (or -1 if none)
|
|
|
|
Will not report PGAs if PGA mining is disabled
|
|
|
|
Will not report CPUs if CPU mining is disabled
|
|
|
|
|
|
|
|
gpu|N GPU The details of a single GPU number N in the same
|
|
|
|
format and details as for DEVS
|
|
|
|
|
|
|
|
pga|N PGA The details of a single PGA number N in the same
|
|
|
|
format and details as for DEVS
|
|
|
|
This is only available if PGA mining is enabled
|
|
|
|
Use 'pgacount' or 'config' first to see if there are any
|
|
|
|
|
|
|
|
cpu|N CPU The details of a single CPU number N in the same
|
|
|
|
format and details as for DEVS
|
|
|
|
This is only available if CPU mining is enabled
|
|
|
|
Use 'cpucount' or 'config' first to see if there are any
|
|
|
|
|
|
|
|
gpucount GPUS Count=N| <- the number of GPUs
|
|
|
|
|
|
|
|
pgacount PGAS Count=N| <- the number of PGAs
|
|
|
|
Always returns 0 if PGA mining is disabled
|
|
|
|
|
|
|
|
cpucount CPUS Count=N| <- the number of CPUs
|
|
|
|
Always returns 0 if CPU mining is disabled
|
|
|
|
|
|
|
|
switchpool|N (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of switching pool N to the
|
|
|
|
highest priority (the pool is also enabled)
|
|
|
|
The Msg includes the pool URL
|
|
|
|
|
|
|
|
enablepool|N (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of enabling pool N
|
|
|
|
The Msg includes the pool URL
|
|
|
|
|
|
|
|
addpool|URL,USR,PASS (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of attempting to add pool N
|
|
|
|
The Msg includes the pool URL
|
|
|
|
Use '\\' to get a '\' and '\,' to include a comma
|
|
|
|
inside URL, USR or PASS
|
|
|
|
|
|
|
|
disablepool|N (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of disabling pool N
|
|
|
|
The Msg includes the pool URL
|
|
|
|
|
|
|
|
removepool|N (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of removing pool N
|
|
|
|
The Msg includes the pool URL
|
|
|
|
N.B. all details for the pool will be lost
|
|
|
|
|
|
|
|
gpuenable|N (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of the enable request
|
|
|
|
|
|
|
|
gpudisable|N (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of the disable request
|
|
|
|
|
|
|
|
gpurestart|N (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of the restart request
|
|
|
|
|
|
|
|
gpuintensity|N,I (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of setting GPU N intensity to I
|
|
|
|
|
|
|
|
gpumem|N,V (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of setting GPU N memoryclock to V MHz
|
|
|
|
|
|
|
|
gpuengine|N,V (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of setting GPU N clock to V MHz
|
|
|
|
|
|
|
|
gpufan|N,V (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of setting GPU N fan speed to V%
|
|
|
|
|
|
|
|
gpuvddc|N,V (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of setting GPU N vddc to V
|
|
|
|
|
|
|
|
save|filename (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating success or failure saving the cgminer config
|
|
|
|
to filename
|
|
|
|
The filename is optional and will use the cgminer
|
|
|
|
default if not specified
|
|
|
|
|
|
|
|
quit (*) none There is no status section but just a single "BYE"
|
|
|
|
reply before cgminer quits
|
|
|
|
|
|
|
|
notify NOTIFY The last status and history count of each devices problem
|
|
|
|
This lists all devices including those not supported
|
|
|
|
by the 'devs' command
|
|
|
|
e.g. NOTIFY=0,Name=GPU,ID=0,Last Well=1332432290,...|
|
|
|
|
|
|
|
|
privileged (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating an error if you do not have privileged access
|
|
|
|
to the API and success if you do have privilege
|
|
|
|
The command doesn't change anything in cgminer
|
|
|
|
|
|
|
|
pgaenable|N (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of the enable request
|
|
|
|
You cannot enable a PGA if it's status is not WELL
|
|
|
|
This is only available if PGA mining is enabled
|
|
|
|
|
|
|
|
pgadisable|N (*)
|
|
|
|
none There is no reply section just the STATUS section
|
|
|
|
stating the results of the disable request
|
|
|
|
This is only available if PGA mining is enabled
|
|
|
|
|
|
|
|
devdetails DEVDETAILS Each device with a list of their static details
|
|
|
|
This lists all devices including those not supported
|
|
|
|
by the 'devs' command
|
|
|
|
e.g. DEVDETAILS=0,Name=GPU,ID=0,Driver=opencl,...|
|
|
|
|
|
|
|
|
restart (*) none There is no status section but just a single "RESTART"
|
|
|
|
reply before cgminer restarts
|
|
|
|
|
|
|
|
stats STATS Each device or pool that has 1 or more getworks
|
|
|
|
with a list of stats regarding getwork times
|
|
|
|
The values returned by stats may change in future
|
|
|
|
versions thus would not normally be displayed
|
|
|
|
Device drivers are also able to add stats to the
|
|
|
|
end of the details returned
|
|
|
|
|
|
|
|
check|cmd COMMAND Exists=Y/N, <- 'cmd' exists in this version
|
|
|
|
Access=Y/N| <- you have access to use 'cmd'
|
|
|
|
|
|
|
|
When you enable, disable or restart a GPU or PGA, you will also get Thread messages
|
|
|
|
in the cgminer status window
|
|
|
|
|
|
|
|
When you switch to a different pool to the current one, you will get a
|
|
|
|
'Switching to URL' message in the cgminer status windows
|
|
|
|
|
|
|
|
Obviously, the JSON format is simply just the names as given before the '='
|
|
|
|
with the values after the '='
|
|
|
|
|
|
|
|
If you enable cgminer debug (-D or --debug) you will also get messages showing
|
|
|
|
details of the requests received and the replies
|
|
|
|
|
|
|
|
There are included 4 program examples for accessing the API:
|
|
|
|
|
|
|
|
api-example.php - a php script to access the API
|
|
|
|
usAge: php api-example.php command
|
|
|
|
by default it sends a 'summary' request to the miner at 127.0.0.1:4028
|
|
|
|
If you specify a command it will send that request instead
|
|
|
|
You must modify the line "$socket = getsock('127.0.0.1', 4028);" at the
|
|
|
|
beginning of "function request($cmd)" to change where it looks for cgminer
|
|
|
|
|
|
|
|
API.java/API.class
|
|
|
|
a java program to access the API (with source code)
|
|
|
|
usAge is: java API command address port
|
|
|
|
Any missing or blank parameters are replaced as if you entered:
|
|
|
|
java API summary 127.0.0.1 4028
|
|
|
|
|
|
|
|
api-example.c - a 'C' program to access the API (with source code)
|
|
|
|
usAge: api-example [command [ip/host [port]]]
|
|
|
|
again, as above, missing or blank parameters are replaced as if you entered:
|
|
|
|
api-example summary 127.0.0.1 4028
|
|
|
|
|
|
|
|
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
|
|
|
|
and also to use the option to display a multi-rig summary
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
Feature Changelog for external applications using the API:
|
|
|
|
|
|
|
|
|
|
|
|
API V1.14
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'stats' - more icarus timing stats added
|
|
|
|
'notify' - include new device comms error counter
|
|
|
|
|
|
|
|
The internal code for handling data was rewritten (~25% of the code)
|
|
|
|
Completely backward compatible
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.13 (cgminer v2.4.4)
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'check'
|
|
|
|
|
|
|
|
Support was added to cgminer for API access groups with the --api-groups option
|
|
|
|
It's 100% backward compatible with previous --api-access commands
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.12 (cgminer v2.4.3)
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'stats' - more pool stats added
|
|
|
|
|
|
|
|
Support for the ModMinerQuad FPGA was added
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.11 (cgminer v2.4.2)
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'save' no longer requires a filename (use default if not specified)
|
|
|
|
|
|
|
|
'save' incorrectly returned status E (error) on success before.
|
|
|
|
It now correctly returns S (success)
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.10 (cgminer v2.4.1)
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'stats'
|
|
|
|
|
|
|
|
N.B. the 'stats' command can change at any time so any specific content
|
|
|
|
present should not be relied upon.
|
|
|
|
The data content is mainly used for debugging purposes or hidden options
|
|
|
|
in cgminer and can change as development work requires
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'pools' added "Last Share Time"
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.9 (cgminer v2.4.0)
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'restart'
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'notify' corrected invalid JSON
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.8 (cgminer v2.3.5)
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'devdetails'
|
|
|
|
|
|
|
|
Support for the ZTex FPGA was added
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.7 (cgminer v2.3.4)
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'removepool'
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'pools' added "User"
|
|
|
|
|
|
|
|
From API version 1.7 onwards, reply strings in JSON and Text have the
|
|
|
|
necessary escaping as required to avoid ambiguity
|
|
|
|
For JSON the 2 characters '"' and '\' are escaped with a '\' before them
|
|
|
|
For Text the 4 characters '|' ',' '=' and '\' are escaped the same way
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.6 (cgminer v2.3.2)
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'pga'
|
|
|
|
'pgaenable'
|
|
|
|
'pgadisable'
|
|
|
|
'pgacount'
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'devs' now includes Icarus and Bitforce FPGA devices
|
|
|
|
'notify' added "*" to the front of the name of all numeric error fields
|
|
|
|
'config' correct "Log Interval" to use numeric (not text) type for JSON
|
|
|
|
|
|
|
|
Support for Icarus and Bitforce FPGAs was added
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.5 was not released
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.4 (Kano's interim release of cgminer v2.3.1)
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'notify'
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'config' added "Device Code" and "OS"
|
|
|
|
|
|
|
|
Added "When" to the STATUS reply section of all commands
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.3 (cgminer v2.3.1-2)
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'addpool'
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'devs'/'gpu' added "Total MH" for each device
|
|
|
|
'summary' added "Total MH"
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.2 (cgminer v2.3.0)
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'enablepool'
|
|
|
|
'disablepool'
|
|
|
|
'privileged'
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'config' added "Log Interval"
|
|
|
|
|
|
|
|
Starting with API V1.2, any attempt to access a command that requires
|
|
|
|
privileged security, from an IP address that does not have privileged
|
|
|
|
security, will return an "Access denied" Error Status
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.1 (cgminer v2.2.4)
|
|
|
|
|
|
|
|
There were no changes to the API commands in cgminer v2.2.4,
|
|
|
|
however support was added to cgminer for IP address restrictions
|
|
|
|
with the --api-allow option
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.1 (cgminer v2.2.2)
|
|
|
|
|
|
|
|
Prior to V1.1, devs/gpu incorrectly reported GPU0 Intensity for all GPUs
|
|
|
|
|
|
|
|
Modified API commands:
|
|
|
|
'devs'/'gpu' added "Last Share Pool" and "Last Share Time" for each device
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V1.0 (cgminer v2.2.0)
|
|
|
|
|
|
|
|
Remove default CPU support
|
|
|
|
|
|
|
|
Added API commands:
|
|
|
|
'config'
|
|
|
|
'gpucount'
|
|
|
|
'cpucount'
|
|
|
|
'switchpool'
|
|
|
|
'gpuintensity'
|
|
|
|
'gpumem'
|
|
|
|
'gpuengine'
|
|
|
|
'gpufan'
|
|
|
|
'gpuvddc'
|
|
|
|
'save'
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
API V0.7 (cgminer v2.1.0)
|
|
|
|
|
|
|
|
Initial release of the API in the main cgminer git
|
|
|
|
|
|
|
|
Commands:
|
|
|
|
'version'
|
|
|
|
'devs'
|
|
|
|
'pools'
|
|
|
|
'summary'
|
|
|
|
'gpuenable'
|
|
|
|
'gpudisable'
|
|
|
|
'gpurestart'
|
|
|
|
'gpu'
|
|
|
|
'cpu'
|
|
|
|
'gpucount'
|
|
|
|
'cpucount'
|
|
|
|
'quit'
|
|
|
|
|