diff --git a/docs/03-server-config.adoc b/docs/03-server-config.adoc index e115265f..6bdcb26e 100644 --- a/docs/03-server-config.adoc +++ b/docs/03-server-config.adoc @@ -1,7 +1,7 @@ == Server Configuration Dshackle server tries to load its configuration from `/etc/dshackle/dshackle.yaml`, if it can't find a file at that path -it tries to load file `dshackle.yaml` from current working directory. If none of them found server fails to run with an error. +it tries to load file `dshackle.yaml` from current working directory.If none of them found server fails to run with an error. .Example dshackle.yaml configuration: [source,yaml] @@ -69,8 +69,8 @@ proxy: - id: eth blockchain: ethereum -upstreams: - config: "upstreams.yaml" +cluster: + include: "upstreams.yaml" ---- With that configuration Dshackle starts a JSON RPC proxy: diff --git a/docs/04-upstream-config.adoc b/docs/04-upstream-config.adoc index 91ecb2e7..edbb206a 100644 --- a/docs/04-upstream-config.adoc +++ b/docs/04-upstream-config.adoc @@ -32,7 +32,8 @@ Run it with `-reindex` option, or set `txindex=1` in the config. ---- version: v1 -defaults: +cluster: + defaults: - chains: - ethereum options: @@ -41,36 +42,35 @@ defaults: - kovan options: min-peers: 2 - -upstreams: - - id: us-nodes - chain: auto - connection: - grpc: - host: 35.226.252.117 - port: 443 - tls: - ca: ca.crt - certificate: client.crt - key: client.p8.key - - id: infura-eth - chain: ethereum - labels: - provider: infura - options: - disable-validation: true - connection: - ethereum: - rpc: - url: "https://mainnet.infura.io/v3/${INFURA_USER}" - basic-auth: - username: ${INFURA_USER} - password: ${INFURA_PASSWD} - ws: - url: "wss://mainnet.infura.io/ws/v3/${INFURA_USER}" - basic-auth: - username: ${INFURA_USER} - password: ${INFURA_PASSWD} + upstreams: + - id: us-nodes + chain: auto + connection: + grpc: + host: 35.226.252.117 + port: 443 + tls: + ca: ca.crt + certificate: client.crt + key: client.p8.key + - id: infura-eth + chain: ethereum + labels: + provider: infura + options: + disable-validation: true + connection: + ethereum: + rpc: + url: "https://mainnet.infura.io/v3/${INFURA_USER}" + basic-auth: + username: ${INFURA_USER} + password: ${INFURA_PASSWD} + ws: + url: "wss://mainnet.infura.io/ws/v3/${INFURA_USER}" + basic-auth: + username: ${INFURA_USER} + password: ${INFURA_PASSWD} ---- There're two main segments for upstreams configuration: @@ -81,21 +81,21 @@ There're two main segments for upstreams configuration: In the example above we have: - default configuration for _Ethereum Mainnet_ which accepts upstream as valid when it not in fast synchronization mode - and has at least 10 peers. For _Kovan Testnet_ nodes the requirements are much relieved +and has at least 10 peers.For _Kovan Testnet_ nodes the requirements are much relieved - as upstreams it has 2 configurations - * balancer connects to another Dshackle/another machine by using gRPC protocol - ** accepts (i.e. proxies) any blockchain available on that remote - ** verifies TLS certificate of the server - ** uses client certificate for authentication, i.e. remote server is accepting only clients authenticated by a - certificate - * connects to Infura provided _Ethereum Mainnet_ - ** configuration is using placeholders for `${INFURA_USER}` and `${INFURA_PASSWD}` which will be replaced with - corresponding environment variables values - ** uses Basic Authentication to authenticate requests on Infura - ** label `[provider: infura]` is set for that particular upstream, which can be selected during a request. For example for - some requests you may want to use nodes with that label only, i.e. _"send that tx to infura nodes only"_, - or _"read only from archive node, with label [archive: true]"_ - ** upstream validation (peers, sync status, etc) is disabled for that particular upstream +* balancer connects to another Dshackle/another machine by using gRPC protocol +** accepts (i.e. proxies) any blockchain available on that remote +** verifies TLS certificate of the server +** uses client certificate for authentication, i.e. remote server is accepting only clients authenticated by a +certificate +* connects to Infura provided _Ethereum Mainnet_ +** configuration is using placeholders for `${INFURA_USER}` and `${INFURA_PASSWD}` which will be replaced with +corresponding environment variables values +** uses Basic Authentication to authenticate requests on Infura +** label `[provider: infura]` is set for that particular upstream, which can be selected during a request.For example for +some requests you may want to use nodes with that label only, i.e. _"send that tx to infura nodes only"_, +or _"read only from archive node, with label [archive: true]"_ +** upstream validation (peers, sync status, etc) is disabled for that particular upstream === Configuration options diff --git a/docs/07-authentication.adoc b/docs/07-authentication.adoc index 43bd6f5e..05909b43 100644 --- a/docs/07-authentication.adoc +++ b/docs/07-authentication.adoc @@ -3,11 +3,11 @@ === Server authentication Dshackle server supports both server and client certificate authentication, and it's strongly recommended to use TLS to -connect to Dshackle server. More to that, the server uses gRPC, which is based on HTTP/2, and most of 3rd party tools and +connect to Dshackle server.More to that, the server uses gRPC, which is based on HTTP/2, and most of 3rd party tools and libraries expect it to be encrypted. Please note that for most of use cases for Dshackle, which is designed to be an internal load balancer, a self-signed -Certificates would be enough. In the example below, a https://github.com/square/certstrap[certstrap] tool is used to +Certificates would be enough.In the example below, a https://github.com/square/certstrap[certstrap] tool is used to generate certificates, but the traditional `openssl` tool can be used as well. ==== Setup Server certificate @@ -90,7 +90,7 @@ openssl pkcs8 -topk8 -inform PEM -outform PEM -in out/$CLIENT_ID.key -out out/$C In addition to files mentioned above you got few new files in `out` directory, including: - `client-ca.myhost.dev.crt` a certificate to validate connecting clients, all their keys much be signed by that - certificate. Server don't need a private key for that certificate because it's used for verification only. +certificate.Server don't need a private key for that certificate because it's used for verification only. - `client_1.crt` certificate for a client that will connect to the server - `client_1.p8.key` private key for that certificate, needed by client @@ -131,24 +131,25 @@ tls: enabled: false ---- -At this case we run another server on port 3449 in unsecure mode. But to connect to an upstream is still uses a TLS +At this case we run another server on port 3449 in unsecure mode.But to connect to an upstream is still uses a TLS certificate as described below [source,yaml] ---- version: v1 -upstreams: - - id: ds - chain: auto - provider: dshackle - connection: - grpc: - host: 127.0.0.1 - port: 2449 - tls: - ca: ca.myhost.dev.crt - certificate: client_1.crt - key: client_1.p8.key +cluster: + upstreams: + - id: ds + chain: auto + provider: dshackle + connection: + grpc: + host: 127.0.0.1 + port: 2449 + tls: + ca: ca.myhost.dev.crt + certificate: client_1.crt + key: client_1.p8.key ---- Now if you run second server it will connect to first server ("upstream") running on port 2449, will verify upstream with certificate `ca.myhost.dev.crt` and authenticate itself by using pair of `client_1.crt` and `client_1.p8.key`