Contact Sales

Configuration

Configuration options

Up until 23.05 version of Farm Proxy the only way to configure was editing the .toml file from the Linux console. With 24.06 the possibility to use GUI comes handy for most of the users. However, you can still use the terminal and ignore whole GUI component. There are some changes in how to propagate the configuration file to the Farm Proxy (read below). GUI on the other hand does that for you just based on actions performed within your browser. Simply upload your old configuration file or create a config file from a template or from a scratch and apply the changes without issuing any Linux commands within the console. Whereas GUI is easy to use for less tech savvy users, it allows configuration of just basic set of options. Should you need any non-standard option, you will have to add it from the console. You can still use the GUI after manual update of the config file in this case. Your manual updates to the configuration file will be kept.

GUI is accessible via browser - http://[your-host]:7777/.

There are 3 docker containers - farm-proxy, farm-proxy-configurator and farm-proxy-gui. Together with .env file they orchestrate the configuration. GUI manages the config files, validates and stores user's changes. It contains templates (example files provided by us) and profiles (actual config files). Configurator reads the active profile file and propagates it to farm-proxy via API call. In previous version of farm-proxy it was sufficient to update the .toml file and restart the farm-proxy container. Now - the restart won't help - you have to start the farm-proxy-configurator. After start it will read the file specified in the .env file and reconfigure Farm Proxy on the fly. farm-proxy-configurator is a container launched automatically from GUI or manually from the console, which reads the configuration, propagates it to Farm Proxy and stops. You will almost never see it using docker ps command.

Upgrading users

For those upgrading:

  1. Using GUI - you have two options - choose Upload Your File option when creating a new profile via GUI and make this profile active. Second option is to copy your existing configuration file to ~/farm-proxy/config folder, refresh the GUI and make this profile Active. It will be applied automatically. From now on you can make your updates via GUI.
  2. Using console - copy our config file to ~/farm-proxy/config/active_profile.toml. Issue the docker compose up farm-proxy-configurator command to apply the configuration. After every future update of active_profile.toml file this command needs to be used to apply it. Be aware - should you start using GUI, active_profile.toml file will get overwritten. If you keep your master copy of this file as active_profile.toml you could lose it.

New users

  1. Using GUI - create a new profile from template or completely empty and follow the configuration screens to input all the necessary configuration options. Make this profile active and it will be immediately applied to the Farm Proxy.
  2. Using console - create new active_profile.toml file in ~/farm-proxy/config folder. You can copy any of the provided templates from the ./template sub-folder as the template. Once done issue the docker compose up farm-proxy-configurator command to apply the changes. Nobody gets it right on the first try. Output of the issued command should tell you in case you've made mistake in the .toml syntax or configuration. You need to issue this command every time you make changes into the configuration file. Be aware - should you start using GUI, active_profile.toml file will get overwritten. If you keep your master config file as active_profile.toml you could lose it.

Farm Proxy configuration details

Braiins Farm Proxy configuration can be split into two main categories - routing configuration and configuration of the accompanying programs (which are BOS Scanner, Prometheus and Grafana).

Routing configuration

Routing configuration is done in the TOML files using a specific structure. The structure of the config file corresponds to the diagram of hashrate routing and uses the terminology explained in Introduction section. Configuration is explained in example setups in the further text.

Braiins Farm Proxy has 3 predefined templates which are allocated in the directory ./farm-proxy/config/templates:

  • 01_minimal.toml: the smallest configuration file you can have with one server and one target without any backup.
  • 02_simple.toml: recommended setup for a small operation. One server, one target with a backup and setting of Braiins Pool username for Braiins OS users to correctly apply the return of the Braiins Pool fee.
  • 03_full.toml: example for bigger farms with two servers (some farms prefer separate servers for each container), two targets with hashrate split configured as 70/30. Example how to use identity pass through.

Routing configuration consists of 5 segments: Server, Target, Routing, Routing Goal and Routing Goal Level.

Server

Server is a template for downstream connections. Each server can be utilized only in a single routing domain (currently we support only one routing domain anyway).

[[server]]
name = "s1"
port = 3333
braiinspool_bos_bonus = "Braiins Pool username"
  • name: name of the server. It is visible as a value of "server" dimension in all downstream related metrics (submits, shares, connections) in Grafana monitoring.
  • port: defines port Braiins Farm Proxy will open and accept miner's connections on. Make sure to update .env file if you plan on using different port range than 3333-3339.
  • braiinspool_bos_bonus: Braiins Pool username for which Braiins OS bonus is applied.

Target

Target is a definition of upstream connection. It can be shared among multiple routing domains (currently we support only one routing domain anyway).

[[target]]
name = "Braiins Pool"
url = "stratum+tcp://stratum.braiins.com:3333"
user_identity = "userName.workerName"
  • name: name of the target. It is visible as a value of "upstream" dimension in all upstream related metrics (submits, shares, connections) in Grafana monitoring.
  • url: URL of the mining pool. You can use any pool.
  • user_identity: identity under which hashrate shall be submitted. The userName must exist on the target pool otherwise the pool does not have a key to link your hashrate to your account. Be careful of using special characters as some pools don't support them (e.g. underscore).

Routing domain

Routing domain links servers and targets together via hierarchy of individual routing goals.

[[routing]]
name = "RD"
from = ["S1"]

[[routing.goal]]
name = "Primary Goal"
hr_weight = 100

[[routing.goal.level]]
targets = ["Primary Pool"]

[[routing.goal.level]]
targets = ["Backup Pool"]
  • from: List of servers whose hashrate is allocated in this Routing Domain (currently only one domain is allowed, so all servers should be listed here).
  • routing.goal: List of routing rules. Attribute name of the goal is visible in the Grafana dashboard for upstream related measures. Attribute hr_weight stands for hashrate distribution ratio preference. Beware of the weight and not the percentage. For example, the ratio of weights 3:1 will distribute the hashrate into target endpoints approx. 75% of hashrate goes into target with weight 3 and 25% of hashrate goes into target with weight 1 (Note: Proxy splits the hashrate based on the miner connections, so the split is approximate. Hashrate coming from a single miner cannot be divided to more targets.). In the example configurations further down, you can see how to distribute hashrate into several targets.
  • routing.goal.level lists the targets which should be applied as upstream endpoints. Multiple targets can be used on a single level - in that case Proxy chooses the one with best latency. It is advised to use at least two levels where second level will be backup target for cases when first target is not working. Up to 3 levels are allowed.

In case the miner uses Braiins OS on his devices, routing of dev-fee is done automatically.

Workers configuration

To point the farm's hashrate to the Braiins Farm Proxy, the workers have to be reconfigured. The URL of the Pool in the worker's firmware configuration has to be set as:

  • Stratum V1: stratum+tcp://[farm-proxy-url]:[server_port]
  • Stratum V2: stratum2+tcp://[farm-proxy-url]:[server_port]/[public_key]

It is recommended to have a backup pool connection on your miner too in case Braiins Farm Proxy is not working.

Example Configurations

To make a better understanding of Braiins Farm Proxy usage and configuration, let's go through 3 examples.

  • Minimal configuration: the easiest possible configuration, one server, one target pool. It is not suitable for the real world for its simplicity but it describes the logic of the configuration.
# Minimal sample configuration
[[server]]
name = "S1"
port = 3333

[[target]]
name = "Braiins Pool"
url = "stratum+tcp://stratum.braiins.com:3333"
user_identity = "braiinstest.fp" #make sure to use your own user name here.

[[routing]]
from = ["S1"]
[[routing.goal]]
name = "Primary Goal"
[[routing.goal.level]]
targets = ["Braiins Pool"]
  • Basic configuration: Recommended setup for a small operation. The primary target is Braiins Pool on port 3333, with the first backup using port 443 on the same pool. A second backup uses a different pool entirely for additional redundancy. The farm has 700 ASIC machines and its desired aggregation is 100, which means there should be between 6 and 7 upstream connections to the target. The farm's revenue is increased by utilizing BOS firmware and mining on Braiins Pool.
# Basic sample configuration
[[server]]
name = "S1"
port = 3333

[[target]]
name = "Braiins Pool Primary"
url = "stratum+tcp://stratum.braiins.com:3333"
user_identity = "braiinstest.fp"
aggregation = 100

[[target]]
name = "Braiins Pool Backup"
url = "stratum+tcp://stratum.braiins.com:443"
user_identity = "braiinstest.fp"
aggregation = 100

[[target]]
name = "Backup Pool"
url = "stratum+tcp://pool.viabtc.com:3333"
user_identity = "userName.workerName"
aggregation = 100

[[routing]]
from = ["S1"]
[[routing.goal]]
name = "Goal 1"
# Primary
[[routing.goal.level]]
targets = ["Braiins Pool Primary"]
# Back-up 1 (different port)
[[routing.goal.level]]
targets = ["Braiins Pool Backup"]
# Back-up 2 (different pool)
[[routing.goal.level]]
targets = ["Backup Pool"]
  • Multiple owners of the workers: The farm has two locations with servers listening on ports 3333 and 3334. They are split to mine to Braiins Pool and SomeOtherPool (which requires maximal extranonce to be 4). This example configuration is suitable in the case that the workers have 2 owners or locations and thus multiple servers are defined and used. Multiple instances of Braiins Farm Proxy (let's say in our example it's 2 Raspberry Pi machines) with 2 different configurations can be used instead. We have to use special extranonce settings on the server in order to use target with extranonce_size=4 (as the difference between target and server has to be 2 - by using use_empty_extranonce1 the difference can be lowered to 1).
# Advanced sample configuration
[[server]]
name = "S1"
port = 3333
extranonce_size = 3
use_empty_extranonce1 = true #this does not work with Avalon miners

[[server]]
name = "S2"
port = 3334
extranonce_size = 3
use_empty_extranonce1 = true #this does not work with Avalon miners

[[target]]
name = "Braiins Pool Primary"
url = "stratum+tcp://stratum.braiins.com:3333"
user_identity = "braiinstest.fp"

[[target]]
name = "Braiins Pool Backup"
url = "stratum+tcp://stratum.braiins.com:443"
user_identity = "braiinstest.fp"

[[target]]
name = "SomeOtherPool-1"
url = "stratum+tcp://stratum.someotherpool.com:3333"
user_identity = "someOtherUser.fp"
extranonce_size = 4

[[target]]
name = "SomeOtherPool-2"
url = "stratum+tcp://stratum.someotherpool.com:443"
user_identity = "someOtherUser.fp"
extranonce_size = 4

[[routing]]
from = ["S1","S2"]
[[routing.goal]]
name = "Goal Braiins"
# Primary Braiins Pool
[[routing.goal.level]]
targets = ["Braiins Pool Primary"]
# Backup Braiins Pool (different port)
[[routing.goal.level]]
targets = ["Braiins Pool Backup"]
#
[[routing.goal]]
name = "Goal SomeOtherPool"
# Primary
[[routing.goal.level]]
targets = ["SomeOtherPool-1"]
# Back-up
[[routing.goal.level]]
targets = ["SomeOtherPool-2"]
  • Diversification of pools: A farm which allocates hashrate into 3 pools using 1 Braiins Farm Proxy instance with 1 server and multiple upstream target endpoints with hashrate allocation 5:4:1 ~ approx. 50% of hashrate goes to the goal "Goal Braiins", 40% of hashrate goes to the goal "Goal SomeOther" and 10% goes to the goal "Goal SomeAnother".
# Diversification of pools
[[server]]
name = "S1"
port = 3333
extranonce_size = 3
use_empty_extranonce1 = true

[[target]]
name = "Braiins Pool Primary"
url = "stratum+tcp://stratum.braiins.com:3333"
user_identity = "braiinstest.fp"

[[target]]
name = "Braiins Pool Backup"
url = "stratum+tcp://stratum.braiins.com:443"
user_identity = "braiinstest.fp"

[[target]]
name = "SomeOtherPool-1"
url = "stratum+tcp://stratum.someotherpool.com:3333"
user_identity = "someOtherUser.proxy"
extranonce_size = 4

[[target]]
name = "SomeOtherPool-2"
url = "stratum+tcp://stratum.someotherpool.com:443"
user_identity = "someOtherUser.proxy"
extranonce_size = 4

[[target]]
name = "SomeAnother-1"
url = "stratum+tcp://stratum.someanother.com:3333"
user_identity = "someAnotherUser.proxy"

[[target]]
name = "SomeAnother-2"
url = "stratum+tcp://stratum.someanother:443"
user_identity = "someAnotherUser.proxy"

[[routing]]
from = ["S1"]
[[routing.goal]]
name = "Goal Braiins"
hr_weight = 5
# Primary Braiins Pool
[[routing.goal.level]]
targets = ["Braiins Pool Primary"]
# Backup Braiins Pool (different port)
[[routing.goal.level]]
targets = ["Braiins Pool Backup"]
#
[[routing.goal]]
name = "Goal SomeOther"
hr_weight = 4
# Primary SomeOtherPool
[[routing.goal.level]]
targets = ["SomeOtherPool-1"]
# Back-up SomeOtherPool
[[routing.goal.level]]
targets = ["SomeOtherPool-2"]
#
[[routing.goal]]
name = "Goal SomeAnother"
hr_weight = 1
# Primary SomeAnother
[[routing.goal.level]]
targets = ["SomeAnother-1"]
# Back-up SomeAnother
[[routing.goal.level]]
targets = ["SomeAnother-2"]
  • Different location of the mining operation: Mining farms with several physical mining containers or buildings in different locations would use a Braiins Farm Proxy instance in each of the locations or for each container with one downstream server and one upstream target with different worker identifiers at each location / container to differentiate the hashrate from each location / container.

Attention: It is recommended to use minimal extranonce_size = 4 in the server section. From practice lower extranonce_size can produce duplicate submits when hashing with some miners. This fact is probably connected either to the version rolling or nTime rolling. You can go lower with this setting, but check the rejection rate in that case. Setting of use_empty_extranonce1 to true might help

Configuration parameters

List of both mandatory and optional parameters available in the Braiins Farm Proxy configuration. Parameters are assigned to the corresponding configuration sections.

Server

  • name: string: case-sensitive with minimal length 1 (mandatory), name of the server,
  • port: integer (mandatory), port dedicated to the Braiins Farm Proxy, has to be within the port range exposed by docker container and defined in ~/farm-proxy/.env file,
  • extranonce_size: integer (optional), extranonce provided to the downstream device (ASIC), must be at least by 2 less than extranonce_size of the target, default is 4, which is also recommended as minimum,
  • validates_hash_rate: boolean (true/false, optional), parameter defining if the proxy has to validate submit from downstream (and reject invalid hashrate), default is true,
  • use_empty_extranonce1: boolean (true/false, optional), parameter defining if 1 more byte of extra nonce can be used (Avalon devices don't support it, but if you are mining on a pool with a max extranonce_size = 4, you can try to set use_empty_extranonce1 = true and extranonce_size = 3 - however check of rejection rate on miners is recommended in this case), default is false,
  • submission_rate: real (optional), desired downstream submission rate (miner → proxy) defined as number of submits per one seconds, default is 0.2 (1 submit per 5 seconds), affects difficulty distributed to the miners, lower submission rate will save some local network capacities,
  • braiinspool_bos_bonus: string (case-sensitive) with minimal length 0 (optional), Braiins Pool username for which discount on Pool Fee (Braiins OS bonus) is applied,

Target

  • name: string: case-sensitive with minimal length 1 (mandatory), name of the target endpoint,
  • url: string (mandatory), URL of the mining pool, if port is not provided 3333 is used,
  • user_identity: string: case-sensitive with minimal length 1 (mandatory),
  • identity_pass_through: boolean (true/false, optional), propagation of an individual worker identity to the target pool, results in hashrate reported under individual worker names instead of workername configured in user_identity, however hashrate will fluctuate a lot due to aggregation, default is false,
  • extranonce_size: integer (optional), extranonce enforced to the target pool, must be at least by 2 higher than extranonce_size of the server, default is 6 (most of the pools allow 8 except of Braiins Pool - 6, and Nicehash - 3 at the time of writing),
  • aggregation: integer (optional), number of aggregated workers (ASICs) per one upstream connection, default is 50 (saving 98% of traffic), don't use more than 100,

Routing

  • name: string: case-sensitive with minimal length 1 (mandatory), name of the routing domain,
  • from: list (mandatory), list of servers which are used as aggregation proxies.

Routing goal

  • name: string: case-sensitive with minimal length 1 (mandatory), name of the routing goal,
  • hr_weight: integer (optional), weight for the preferred ratio of hashrate distribution.

Routing goal level

  • targets: list (mandatory), list of targets which are applied as target endpoints in the routing domain.

Accompanying configuration

Other configuration is predefined in the file .env, which specifies environment variables used by docker-compose.yml. This file is essential for running Braiins Farm Proxy as a multi-container Docker stack. By isolation of all variables into the .env file the docker compose file should remain entirely untouched (except of some specific needs). Docker compose file consists of the configuration of these services:

  • Farm Proxy: performs the magic, does not have a frontend
  • Farm Proxy Configurator: pushes new configuration to Farm Proxy, does not have a frontend
  • Farm Proxy GUI: configuration management for Farm Proxy, runs on port 7777, it can be accessed in your browser, e.g. http://[your-host]:7777/
  • Prometheus: runs on port 9090, it can be accessed in your browser, e.g. http://[your-host]:9090/
  • Grafana: runs on port 3000, it can be accessed in your browser, e.g. http://[your-host]:3000/

Grafana is crucial for the monitoring of mining with Braiins Farm Proxy. Prometheus feeds Grafana with data and can be useful in case the user wants to build their own graphs for Grafana dashboards.

Content of the .envfile:

GRAFANA_PORT=3000
PROMETHEUS_PORT=9090
#multiple port ranges can be used, e.g. 3333-3339,3343-3349
MINING_PORTS=3333-3339
GUI_PORT=7777
# Profile file name located in config subdirectory
FP_CONFIG_PROFILE="active_profile.toml"

Some examples for manipulating the docker_compose.yml file (make sure to backup the file as it gets overwritten with each new update):

  • usage of multiple Farm Proxies - it might be useful to remove Prometheus and/or Grafana from each instance and have a dedicated node collecting metrics from each of the Farm Proxy node. Useful especially if the Farm Proxy runs on RaspberryPi, where extensive usage of Prometheus leads to unresponsive device. prometheus.yml file is located in ~/farm-proxy/monitoring/prometheus/ folder and can be used as an example for you own prometheus.yml collecting metrics from all the Farm Proxy instances. You can keep the Prometheus running on each of the Farm Proxy node as well and run special Grafana instance to access those.
  • monitoring of resources - usage of Node exporter to monitor resources of the node or Cadvisor to monitor each Docker container requires update of docker compose file and also prometheus.yml. See the guides on the internet how to incorporate these containers into your stack.
  • running several Farm Proxies - since only one routing domain is allowed, you can adjust whole stack to accommodate more Farm Proxy instances. Each of them will require unique docker container name, unique set of exposed ports, configuration + prometheus.yml will require updates to read metrics from the new farm proxy instances. You will lose the GUI support for them as well.
  • removal of Farm Proxy GUI - the GUI itself should not take many resources, but if you don't need it at all, you are fine to remove it from the docker compose file.

Attention: We don't provide support or advise on changes mentioned above. You will need to investigate and troubleshoot them by yourself.

Pools set up

To point the farm's hashrate to the Braiins Farm Proxy, the workers have to be reconfigured. The URL of the Pool in the worker's firmware configuration has to be set as:

  • Stratum V1: stratum+tcp://[farm-proxy-url]:[server_port]
  • Stratum V2: stratum2+tcp://[farm-proxy-url]:[server_port]/[public_key]

It is recommended to have a backup pool connection on your miner too in case Braiins Farm Proxy is not working.

Was this helpful?