Skip to content

Latest commit

 

History

History
1629 lines (1286 loc) · 29.8 KB

README.md

File metadata and controls

1629 lines (1286 loc) · 29.8 KB
Raw

#Packaging (Not mandatory)

You can directly use a release (https://github.com/Stratehm/stratum-proxy/releases) and go to the Installation and Usage section.

The packaging of the application is done through Maven and will generate a ZIP which contains the program and all its dependencies.

The proxy is is generated as a JAR file called stratum-proxy.jar (contained in the ZIP file) which can be launched on any platform with a JVM installed with version >= 7 (Java Virtual Machine)

To build the package, you must have a JDK installed in version >= 7 and maven 3

##Packaging

Advice: It is highly recommended to install NodeJS before building the package. It will speed up the Javascript Optimization phase. If not installed, the packing will still work but may be really long (since the Javascript Optimization phase will use the Java Rhino Javascript Engine which is slower). If NodeJS is not installed, set the MAVEN_OPTS environment variable before packaging with the following parameters: -Xmx512M -Xss2M

On Windows:

cd /directory/which/contain/pom.xmlFileOfTheProject

mvn clean package

On Linux:

cd /directory/which/contain/pom.xmlFileOfTheProject

mvn clean package

The package is then present in the "target" directory.

#Installation and Usage

##Installation

The latest JVM (Java Virtual Machine) can be downloaded here: http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html Install the JVM for your operating system (if not already done)

Then unzip the zip file in a directory and launch the proxy through the following command line:

java -jar stratum-proxy.jar proxyOptions

##Usage

java -jar stratum-proxy.jar --help

##Raspberry Pi Installation (Raspbian) Once your OS is setup on the Raspberry Pi (Raspbian), perform the following (replace the version number with the last available: https://github.com/Stratehm/stratum-proxy/releases):

  1. Install JDK and Screen onto the Raspberry Pi
    sudo apt-get update && sudo apt-get install oracle-java7-jdk screen

  2. Download stratum-proxy to the /opt folder
    cd /opt
    sudo wget https://github.com/Stratehm/stratum-proxy/releases/download/x.x.x/stratum-proxy-x.x.x.zip

  3. Unzip the stratum-proxy zip
    sudo unzip stratum-proxy-x.x.x.zip
    sudo rm -rf stratum-proxy-x.x.x.zip
    sudo mv /opt/stratum-proxy-x.x.x /opt/stratum-proxy
    cd /opt/stratum-proxy

  4. Configure the proxy by creating/editing the file stratum-proxy.conf

  5. Test the stratum-proxy by running it
    sudo java -jar stratum-proxy.jar

  6. Set it to automatically start-up, in a seperate screen, by adding the following line to the file /etc/rc.local
    sudo /usr/bin/screen -dmS proxy /usr/bin/java -jar /opt/stratum-proxy/stratum-proxy.jar -f /opt/stratum-proxy/stratum-proxy.conf

##Configuration File

In order to use a configuration file instead of the command line parameters, use the following command line options:

java -jar stratum-proxy.jar -f /path/to/the/configuration/file

When -f option is used, all other command line options are discarded and only the configuration file is used.

The files stratum-proxy-minimal-sample.conf and stratum-proxy-full-sample.conf in the package can be used to build your own configuration file.

##WebClient

A WebClient is available at the address: http://127.0.0.1:8888 (The port can be changed with --rest-listen-port or apiListenAddress of configuration file).

GUI example

##API Details

An API is available. Methods parameters or result are in JSON. By default, the methods can be accessed at the URL http://hostIp:8888/proxy/.

The Content-Type of HTTP requests has to be application/json, else a 415 Unsupported Media Type error may be returned.

Here after is the API methods description:

Api Version: 1.0

APIs

/

Overview

API to manage the proxy

POST /address/ban

banIp

Ban the given ip address.

Parameters
  • body
Parameter Required Description Data Type
body false AddressDTO
Response

StatusDTO

Errors
Status Code Reason Response Model

POST /address/kick

kickAddress

Kick all connections with the given address.

Parameters
  • body
Parameter Required Description Data Type
body false AddressDTO
Response

StatusDTO

Errors
Status Code Reason Response Model

GET /user/ban/list

listBannedUsers

List all banned users.

Parameters
Response

List[string]

Errors
Status Code Reason Response Model

POST /address/unban

unbanAddress

Unban the given ip address.

Parameters
  • body
Parameter Required Description Data Type
body false AddressDTO
Response

StatusDTO

Errors
Status Code Reason Response Model

POST /connection/kick

kickConnection

Kill the connection with the given address and port.

Parameters
  • body
Parameter Required Description Data Type
body false ConnectionIdentifierDTO
Response

StatusDTO

Errors
Status Code Reason Response Model

GET /pool/list

getPoolsList

Return the list of all pools.

Parameters
Response

List[PoolDetailsDTO]

Errors
Status Code Reason Response Model

POST /pool/add

addPool

Add a pool.

Parameters
  • body
Parameter Required Description Data Type
body false AddPoolDTO
Response

StatusDTO

Errors
Status Code Reason Response Model
500 Failed to add the pool. StatusDTO
500 Pool added but not started. StatusDTO

POST /pool/remove

removePool

Remove a pool.

Parameters
  • body
Parameter Required Description Data Type
body false RemovePoolDTO
Response

StatusDTO

Errors
Status Code Reason Response Model
404 Pool not found. StatusDTO

POST /pool/disable

disablePool

Disable a pool.

Parameters
  • body
Parameter Required Description Data Type
body false PoolNameDTO
Response

StatusDTO

Errors
Status Code Reason Response Model
500 Failed to start the pool. StatusDTO
404 Pool not found. StatusDTO

POST /pool/enable

enablePool

Enable a pool.

Parameters
  • body
Parameter Required Description Data Type
body false PoolNameDTO
Response

StatusDTO

Errors
Status Code Reason Response Model
404 Pool not found. StatusDTO
500 Failed to start the pool. StatusDTO

POST /pool/priority

setPoolPriority

Change the priority of a pool.

Parameters
  • body
Parameter Required Description Data Type
body false ChangePriorityDTO
Response

StatusDTO

Errors
Status Code Reason Response Model
404 Pool not found. StatusDTO
400 Bad parameter sent. StatusDTO

POST /pool/update

updatePool

Update a pool.

Parameters
  • body
Parameter Required Description Data Type
body false UpdatePoolDTO
Response

StatusDTO

Errors
Status Code Reason Response Model
500 Failed to update the pool. StatusDTO
400 Bad parameter sent. StatusDTO
404 Pool not found. StatusDTO

POST /log/level

setLogLevel

Change the log level.

Parameters
  • body
Parameter Required Description Data Type
body false LogLevelDTO
Response

StatusDTO

Errors
Status Code Reason Response Model
400 Log level not known. StatusDTO

GET /log/level

getLogLevel

Return the log level.

Parameters
Response

LogLevelDTO

Errors
Status Code Reason Response Model

POST /log/since

getLogSince

Return log message since the given timestamp.

Parameters
  • body
Parameter Required Description Data Type
body false TimestampDTO
Response

List[LogEntry]

Errors
Status Code Reason Response Model
400 Timestamp is empty. -

GET /misc/version

getProxyVersion

Return the version of the proxy.

Parameters
Response

ProxyVersionDTO

Errors
Status Code Reason Response Model

GET /summary

getSummary

Return a summary of the current state of the proxy.

Parameters
Response

SummaryDTO

Errors
Status Code Reason Response Model

POST /user/unban

unbanUser

Unban a user.

Parameters
  • body
Parameter Required Description Data Type
body false UserNameDTO
Response

StatusDTO

Errors
Status Code Reason Response Model

POST /user/ban

banUser

Ban the given username until the proxy restart. The user will not be authorized to reconnect.

Parameters
  • body
Parameter Required Description Data Type
body false UserNameDTO
Response

StatusDTO

Errors
Status Code Reason Response Model

POST /user/kick

kickUser

Kick the given username. Kill all connections where the user has been seen (WARN: this may kill connections supporting other users)

Parameters
  • body
Parameter Required Description Data Type
body false UserNameDTO
Response

StatusDTO

Errors
Status Code Reason Response Model

GET /user/list

getUsersList

Get the list of users that has been connected at least once since the proxy is started.

Parameters
Response

List[UserDetailsDTO]

Errors
Status Code Reason Response Model

POST /hashrate/pool

getPoolHashrateHistory

Return the hashrate history of a pool.

Parameters
  • query
Parameter Required Description Data Type
start false Allow to filter returned values on the given start timestamp (UTC from Epoch in seconds) long
end false Allow to filter returned values on the given end timestamp (UTC from Epoch in seconds) long
- body
Parameter Required Description Data Type
body false PoolNameDTO
Response

List[HashrateModel]

Errors
Status Code Reason Response Model
500 Error during pool hashrate history response build. -
404 Pool not found. -

POST /hashrate/user

getUserHashrateHistory

Return the hashrate history of a user.

Parameters
  • query
Parameter Required Description Data Type
start false Allow to filter returned values on the given start timestamp (UTC from Epoch in seconds) long
end false Allow to filter returned values on the given end timestamp (UTC from Epoch in seconds) long
- body
Parameter Required Description Data Type
body false UserNameDTO
Response

List[HashrateModel]

Errors
Status Code Reason Response Model

POST /address/ban/list

listBannedAddress

List all banned addresses.

Parameters
  • body
Parameter Required Description Data Type
body false AddressDTO
Response

List[string]

Errors
Status Code Reason Response Model

GET /connection/list

getConnectionsList

Return the list of all worker connections.

Parameters
Response

List[WorkerConnectionDTO]

Errors
Status Code Reason Response Model

Data Types

AddPoolDTO

name type description
username string -
poolHost string -
poolName string -
workerNameSeparator string -
appendWorkerNames boolean -
isEnabled boolean -
weight int -
useWorkerPassword boolean -
enableExtranonceSubscribe boolean -
priority int -
password string -

AddressDTO

name type description
address string -

ChangePriorityDTO

name type description
poolName string -
priority int -

ConnectionIdentifierDTO

name type description
address string -
port int -

HashrateModel

name type description
acceptedHashrate long -
rejectedHashrate long -
name string -
captureTime long -

LogEntry

name type description
message string -
timestamp long -

LogLevelDTO

name type description
logLevel string -

PoolDetailsDTO

name type description
lastStopCause string -
extranonce2Size int -
username string -
numberOfWorkerConnections int -
lastPoolMessage string -
isActiveSince long -
appendWorkerNames boolean -
rejectedHashesPerSeconds long -
isReadySince long -
isReady boolean -
isEnabled boolean -
acceptedHashesPerSeconds long -
weight int -
rejectedDifficulty double -
difficulty string -
isActive boolean -
isExtranonceSubscribeEnabled boolean -
useWorkerPassword boolean -
workerNamesSeparator string -
workerExtranonce2Size int -
host string -
name string -
extranonce1 string -
password string -
priority int -
lastStopDate long -
isStable boolean -
numberOfDisconnections int -
acceptedDifficulty double -
uptime long -

PoolNameDTO

name type description
poolName string -

ProxyVersionDTO

name type description
fullName string -
proxyVersion string -

RemovePoolDTO

name type description
poolName string -
keepHistory boolean -

StatusDTO

name type description
message string -
status string -

SummaryDTO

name type description
poolUptime long -
acceptedHashrate long -
hashrate long -
rejectedHashrate long -
currentPoolName string -
totalErrors int -

TimestampDTO

name type description
timestamp long -

UpdatePoolDTO

name type description
username string -
appendWorkerNames boolean -
weight int -
useWorkerPassword boolean -
workerNamesSeparator string -
isExtranonceSubscribeEnabled boolean -
host string -
name string -
priority int -
password string -

UserDetailsDTO

name type description
rejectedHashesPerSeconds long -
firstConnectionDate long -
acceptedHashesPerSeconds long -
rejectedDifficulty double -
lastShareSubmitted long -
name string -
acceptedShareNumber long -
connections Array[WorkerConnectionDTO] -
rejectedShareNumber long -
acceptedDifficulty double -

UserNameDTO

name type description
username string -

WorkerConnectionDTO

name type description
poolName string -
isActiveSince long -
rejectedHashesPerSeconds long -
remotePort string -
acceptedHashesPerSeconds long -
connectionType string -
workerVersion string -
isExtranonceNotificationSupported boolean -
authorizedUsers Array[string] -
remoteHost string -

#License

GPLv3

Of course, if you want make a little donation, you are welcome :)

BTC: 19wv8FQKv3NkwTdzBCQn1AGsb9ghqBPWXi