From 0eb0616b6614d369a7b4e6e4946401d6047b182d Mon Sep 17 00:00:00 2001 From: Roy Lee Date: Wed, 3 Nov 2021 20:41:34 -0700 Subject: [PATCH] [lbry] docs: update README.md --- README.md | 109 +++++++++++++++++++++++++++++----------- doc.go | 6 +-- docs/configuration.md | 72 +++++++++++++------------- docs/configuring_tor.md | 2 +- docs/json_rpc_api.md | 6 +-- docs/mining.md | 2 +- sample-lbcd.conf | 28 +++++------ 7 files changed, 139 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 470c69a9..16800c6f 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,19 @@ -lbcd -==== +# lbcd [![Build Status](https://github.com/lbryio/lbcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/lbryio/lbcd/actions) [![Coverage Status](https://coveralls.io/repos/github/lbryio/lbcd/badge.svg?branch=master)](https://coveralls.io/github/lbryio/lbcd?branch=master) [![ISC License](https://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -lbcd is a full node implementation of LBRY's blockchain written in Go (golang). +`lbcd` is a full node implementation of LBRY's blockchain written in Go (golang). -This project is currently under active development and is in a Beta state while we -ensure it matches LBRYcrd's functionality. The intention is that it properly downloads, validates, and serves the block chain using the exact -rules (including consensus bugs) for block acceptance as LBRYcrd. We have -taken great care to avoid lbcd causing a fork to the blockchain. +This project is currently under active development and is in a Beta state while +we ensure it matches LBRYcrd's functionality. The intention is that it properly +downloads, validates, and serves the block chain using the exact rules +(including consensus bugs) for block acceptance as LBRYcrd. +We have taken great care to avoid lbcd causing a fork to the blockchain. -Note: lbcd does *NOT* include -wallet functionality. That functionality is provided by the +Note: `lbcd` does *NOT* include wallet functionality. That functionality is provided by the [lbcwallet](https://github.com/lbryio/lbcwallet) and the [LBRY SDK](https://github.com/lbryio/lbry-sdk). ## Security @@ -23,44 +22,98 @@ We take security seriously. Please contact [security](mailto:security@lbry.com) Our PGP key is [here](https://lbry.com/faq/pgp-key) if you need it. We maintain a mailing list for notifications of upgrades, security issues, -and soft/hard forks. To join, visit https://lbry.com/forklist +and soft/hard forks. To join, visit [fork list](https://lbry.com/forklist) ## Requirements -All common operating systems are supported. lbcd requires at least 8GB of RAM -and at least 100GB of disk storage. Both RAM and disk requirements increase slowly over time. +All common operating systems are supported. lbcd requires at least 8GB of RAM +and at least 100GB of disk storage. Both RAM and disk requirements increase slowly over time. Using a fast NVMe disk is recommended. -lbcd is not immune to data loss. It expects a clean shutdown -via SIGINT or SIGTERM. SIGKILL, immediate VM kills, and sudden power loss -can cause data corruption, thus requiring chain resynchronization for recovery. +`lbcd` is not immune to data loss. It expects a clean shutdown via SIGINT or +SIGTERM. SIGKILL, immediate VM kills, and sudden power loss can cause data +corruption, thus requiring chain resynchronization for recovery. -For compilation, [Go](http://golang.org) 1.16 or newer is required. +For compilation, [Go](http://golang.org) 1.16 or newer is required. ## Installation -Acquire binary files from https://github.com/lbryio/lbcd/releases +Acquire binary files from [releases](https://github.com/lbryio/lbcd/releases) -#### To build from Source on Linux/BSD/MacOSX/POSIX: +### To build from Source on Linux/BSD/MacOSX/POSIX -- Install Go according to its [installation instructions](http://golang.org/doc/install). -- Use your favorite git tool to acquire the lbcd source. -- lbcd has no non-Go dependencies; it can be built by simply running `go build .` -- lbcctl can be built similarly: +Install Go according to its [installation instructions](http://golang.org/doc/install). -Both [GoLand](https://www.jetbrains.com/go/) +``` sh +git clone https://github.com/lbryio/lbcd +cd lbcd + +# Build lbcd +go build . + +# Build lbcctl +go build ./cmd/lbcctl +``` + +Both [GoLand](https://www.jetbrains.com/go/) and [VS Code](https://code.visualstudio.com/docs/languages/go) IDEs are supported. ## Usage -By default, data and logs are stored in `~/.lbcd/` +By default, data and logs are stored in ``: -To enable RPC access a username and password is required. Example: +- Linux: `~/.lbcd/` +- MacOS: `/Users//Library/Application Support/Lbcd/` + +To enable RPC access a username and password is required. Example: + +``` sh +./lbcd --txindex --rpcuser=rpcuser --rpcpass=rpcpass ``` -./lbcd --notls --rpcuser=x --rpcpass=y --txindex & -./lbcctl --notls --rpcuser=x --rpcpass=y getblocktemplate + +Interact with lbcd via RPC using `lbcctl` + +``` sh +./lbcctl --rpcuser=rpcuser --rpcpass=rpcpass getblockcount +./lbcctl --rpcuser=rpcuser --rpcpass=rpcpass getblocktemplate ``` - + +By default, the RPCs are served over TLS. `lbcd` generates (if not exists) `rpc.cert` and +`rpc.key` under `` where `lbcctl` would search and use them. + +The RPCs can also be served without TLS *(on localhost only)* using (`--notls`) + +``` sh +./lbcd --txindex --rpcuser=rpcuser --rpcpass=rpcpass --notls +./lbcctl --rpcuser=rpcuser --rpcpass=rpcpass --notls getblockcount +``` + +## Working with Different Networks + +By default, `lbcd` and `lbcctl` use the following ports for different networks respectively: + +| Network | RPC Port | Network Port | +| ------- | -------- | ------------ | +| mainnet | 9245 | 9246 | +| testnet | 19245 | 19246 | +| regtest | 29245 | 29246 | + +Running `lbcd` and `lbcctl` with `--testnet` or `--regtest` would use different chain params as well as default RPC and Network ports. + +``` sh +./lbcd --txindex --rpcuser=rpcuser --rpcpass=rpcpass --regtest +./lbcctl --rpcuser=rpcuser --rpcpass=rpcpass --regtest getblockcount +``` + +The default Network and RPC ports of `lbcd` can be overriden using `--listen` and `--rpclisten` +`lbcctl` can also connect to RPC server specified by `--rpcserver` + +``` sh +./lbcd --txindex --rpcuser=rpcuser --rpcpass=rpcpass --regtest --listen=127.0.0.1:29248 --rpclisten=127.0.0.1:29247 +./lbcctl --rpcuser=rpcuser --rpcpass=rpcpass --regtest --rpcserver=127.0.0.1:29247 getblockcount +``` + +Note: Wallet related RPCs are provided by [lbcwallet](https://github.com/lbryio/lbcwallet). ## Contributing diff --git a/doc.go b/doc.go index 94ccbaab..8ec48b5d 100644 --- a/doc.go +++ b/doc.go @@ -73,8 +73,8 @@ Application Options: fee to the given amount in thousands of bytes per minute (default: 15) --listen= Add an interface/port to listen for connections - (default all interfaces port: 8333, testnet: - 18333, signet: 38333) + (default all interfaces port: 9246, testnet: + 19246, regtest: 29246, signet: 39246) --logdir= Directory to log output --maxorphantx= Max number of orphan transactions to keep in memory (default: 100) @@ -125,7 +125,7 @@ Application Options: --rpclimitpass= Password for limited RPC connections --rpclimituser= Username for limited RPC connections --rpclisten= Add an interface/port to listen for RPC - connections (default port: 8334, testnet: 18334) + connections (default port: 9245, testnet: 19245, regtest: 29245) --rpcmaxclients= Max number of RPC clients for standard connections (default: 10) --rpcmaxconcurrentreqs= Max number of concurrent RPC requests that may be diff --git a/docs/configuration.md b/docs/configuration.md index 5ece75e8..1a02007b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -16,29 +16,29 @@ interfaces as a couple of the examples below illustrate. Command Line Examples: -|Flags|Comment| -|----------|------------| -|--listen=|all interfaces on default port which is changed by `--testnet` and `--regtest` (**default**)| -|--listen=0.0.0.0|all IPv4 interfaces on default port which is changed by `--testnet` and `--regtest`| -|--listen=::|all IPv6 interfaces on default port which is changed by `--testnet` and `--regtest`| -|--listen=:8333|all interfaces on port 8333| -|--listen=0.0.0.0:8333|all IPv4 interfaces on port 8333| -|--listen=[::]:8333|all IPv6 interfaces on port 8333| -|--listen=127.0.0.1:8333|only IPv4 localhost on port 8333| -|--listen=[::1]:8333|only IPv6 localhost on port 8333| -|--listen=:8336|all interfaces on non-standard port 8336| -|--listen=0.0.0.0:8336|all IPv4 interfaces on non-standard port 8336| -|--listen=[::]:8336|all IPv6 interfaces on non-standard port 8336| -|--listen=127.0.0.1:8337 --listen=[::1]:8333|IPv4 localhost on port 8337 and IPv6 localhost on port 8333| -|--listen=:8333 --listen=:8337|all interfaces on ports 8333 and 8337| +| Flags | Comment | +| ------------------------------------------- | -------------------------------------------------------------------------------------------- | +| --listen= | all interfaces on default port which is changed by `--testnet` and `--regtest` (**default**) | +| --listen=0.0.0.0 | all IPv4 interfaces on default port which is changed by `--testnet` and `--regtest` | +| --listen=:: | all IPv6 interfaces on default port which is changed by `--testnet` and `--regtest` | +| --listen=:9246 | all interfaces on port 9246 | +| --listen=0.0.0.0:9246 | all IPv4 interfaces on port 9246 | +| --listen=[::]:9246 | all IPv6 interfaces on port 9246 | +| --listen=127.0.0.1:9246 | only IPv4 localhost on port 9246 | +| --listen=[::1]:9246 | only IPv6 localhost on port 9246 | +| --listen=:9247 | all interfaces on non-standard port 9247 | +| --listen=0.0.0.0:9247 | all IPv4 interfaces on non-standard port 9247 | +| --listen=[::]:9247 | all IPv6 interfaces on non-standard port 9247 | +| --listen=127.0.0.1:9248 --listen=[::1]:9246 | IPv4 localhost on port 9248 and IPv6 localhost on port 9246 | +| --listen=:9246 --listen=:9248 | all interfaces on ports 9246 and 9248 | The following config file would configure lbcd to only listen on localhost for both IPv4 and IPv6: ```text [Application Options] -listen=127.0.0.1:8333 -listen=[::1]:8333 +listen=127.0.0.1:9246 +listen=[::1]:9246 ``` In addition, if you are starting lbcd with TLS and want to make it @@ -76,21 +76,21 @@ A few things to note regarding the RPC server: Command Line Examples: -|Flags|Comment| -|----------|------------| -|--rpclisten=|all interfaces on default port which is changed by `--testnet`| -|--rpclisten=0.0.0.0|all IPv4 interfaces on default port which is changed by `--testnet`| -|--rpclisten=::|all IPv6 interfaces on default port which is changed by `--testnet`| -|--rpclisten=:8334|all interfaces on port 8334| -|--rpclisten=0.0.0.0:8334|all IPv4 interfaces on port 8334| -|--rpclisten=[::]:8334|all IPv6 interfaces on port 8334| -|--rpclisten=127.0.0.1:8334|only IPv4 localhost on port 8334| -|--rpclisten=[::1]:8334|only IPv6 localhost on port 8334| -|--rpclisten=:8336|all interfaces on non-standard port 8336| -|--rpclisten=0.0.0.0:8336|all IPv4 interfaces on non-standard port 8336| -|--rpclisten=[::]:8336|all IPv6 interfaces on non-standard port 8336| -|--rpclisten=127.0.0.1:8337 --listen=[::1]:8334|IPv4 localhost on port 8337 and IPv6 localhost on port 8334| -|--rpclisten=:8334 --listen=:8337|all interfaces on ports 8334 and 8337| +| Flags | Comment | +| ---------------------------------------------- | ------------------------------------------------------------------- | +| --rpclisten= | all interfaces on default port which is changed by `--testnet` | +| --rpclisten=0.0.0.0 | all IPv4 interfaces on default port which is changed by `--testnet` | +| --rpclisten=:: | all IPv6 interfaces on default port which is changed by `--testnet` | +| --rpclisten=:9245 | all interfaces on port 9245 | +| --rpclisten=0.0.0.0:9245 | all IPv4 interfaces on port 9245 | +| --rpclisten=[::]:9245 | all IPv6 interfaces on port 9245 | +| --rpclisten=127.0.0.1:9245 | only IPv4 localhost on port 9245 | +| --rpclisten=[::1]:9245 | only IPv6 localhost on port 9245 | +| --rpclisten=:9247 | all interfaces on non-standard port 9247 | +| --rpclisten=0.0.0.0:9247 | all IPv4 interfaces on non-standard port 9247 | +| --rpclisten=[::]:9247 | all IPv6 interfaces on non-standard port 9247 | +| --rpclisten=127.0.0.1:9248 --listen=[::1]:9245 | IPv4 localhost on port 9248 and IPv6 localhost on port 9245 | +| --rpclisten=:9245 --listen=:9248 | all interfaces on ports 9245 and 9248 | The following config file would configure the lbcd RPC server to listen to all interfaces on the default port, including external interfaces, for both IPv4 and IPv6: @@ -113,10 +113,10 @@ peer-to-peer port should be forwarded unless you specifically want to allow RPC access to your lbcd from external sources such as in more advanced network configurations. You can disable UPnP with the `--noupnp` daemon option. -|Name|Port| -|----|----| -|Default peer-to-peer port|TCP 9246| -|Default RPC port|TCP 9245| +| Name | Port | +| ------------------------- | -------- | +| Default peer-to-peer port | TCP 9246 | +| Default RPC port | TCP 9245 | ## Using bootstrap.dat diff --git a/docs/configuring_tor.md b/docs/configuring_tor.md index 6f8f821a..84bc0efd 100644 --- a/docs/configuring_tor.md +++ b/docs/configuring_tor.md @@ -60,7 +60,7 @@ address. ```text HiddenServiceDir /var/tor/lbcd -HiddenServicePort 8333 127.0.0.1:8333 +HiddenServicePort 9246 127.0.0.1:9246 ``` Once Tor is configured to provide the hidden service and you have obtained your diff --git a/docs/json_rpc_api.md b/docs/json_rpc_api.md index f902b39d..17ccba64 100644 --- a/docs/json_rpc_api.md +++ b/docs/json_rpc_api.md @@ -242,8 +242,8 @@ the method name for further details such as parameter and return information. | Description | Returns information about manually added (persistent) peers. | | Returns (dns=false) | `["ip:port", ...]` | | Returns (dns=true) | `[ (json array of objects)`
  `{ (json object)`
    `"addednode": "ip_or_domain", (string) the ip address or domain of the added peer`
    `"connected": true or false, (boolean) whether or not the peer is currently connected`
    `"addresses": [ (json array or objects) DNS lookup and connection information about the peer`
      `{ (json object)`
        `"address": "ip", (string) the ip address for this DNS entry`
        `"connected": "inbound/outbound/false" (string) the connection 'direction' (if connected)`
      `}, ...`
    `]`
  `}, ...`
`]` | -| Example Return (dns=false) | `["192.168.0.10:8333", "mydomain.org:8333"]` | -| Example Return (dns=true) | `[`
  `{`
    `"addednode": "mydomain.org:8333",`
    `"connected": true,`
    `"addresses": [`
      `{`
        `"address": "1.2.3.4",`
        `"connected": "outbound"`
      `},`
      `{`
        `"address": "5.6.7.8",`
        `"connected": "false"`
      `}`
    `]`
  `}`
`]` | +| Example Return (dns=false) | `["192.168.0.10:9246", "mydomain.org:9246"]` | +| Example Return (dns=true) | `[`
  `{`
    `"addednode": "mydomain.org:9246",`
    `"connected": true,`
    `"addresses": [`
      `{`
        `"address": "1.2.3.4",`
        `"connected": "outbound"`
      `},`
      `{`
        `"address": "5.6.7.8",`
        `"connected": "false"`
      `}`
    `]`
  `}`
`]` | [Return to Overview](#MethodOverview)
*** @@ -427,7 +427,7 @@ the method name for further details such as parameter and return information. | Parameters | None | | Description | Returns data about each connected network peer as an array of json objects. | | Returns | `[`
  `{`
    `"addr": "host:port", (string) the ip address and port of the peer`
    `"services": "00000001", (string) the services supported by the peer`
    `"lastrecv": n, (numeric) time the last message was received in seconds since 1 Jan 1970 GMT`
    `"lastsend": n, (numeric) time the last message was sent in seconds since 1 Jan 1970 GMT`
    `"bytessent": n, (numeric) total bytes sent`
    `"bytesrecv": n, (numeric) total bytes received`
    `"conntime": n, (numeric) time the connection was made in seconds since 1 Jan 1970 GMT`
    `"pingtime": n, (numeric) number of microseconds the last ping took`
    `"pingwait": n, (numeric) number of microseconds a queued ping has been waiting for a response`
    `"version": n, (numeric) the protocol version of the peer`
    `"subver": "useragent", (string) the user agent of the peer`
    `"inbound": true_or_false, (boolean) whether or not the peer is an inbound connection`
    `"startingheight": n, (numeric) the latest block height the peer knew about when the connection was established`
    `"currentheight": n, (numeric) the latest block height the peer is known to have relayed since connected`
    `"syncnode": true_or_false, (boolean) whether or not the peer is the sync peer`
  `}, ...`
`]` | -| Example Return | `[`
  `{`
    `"addr": "178.172.xxx.xxx:8333",`
    `"services": "00000001",`
    `"lastrecv": 1388183523,`
    `"lastsend": 1388185470,`
    `"bytessent": 287592965,`
    `"bytesrecv": 780340,`
    `"conntime": 1388182973,`
    `"pingtime": 405551,`
    `"pingwait": 183023,`
    `"version": 70001,`
    `"subver": "/lbcd:0.4.0/",`
    `"inbound": false,`
    `"startingheight": 276921,`
    `"currentheight": 276955,`
    `"syncnode": true,`
  `}`
`]` | +| Example Return | `[`
  `{`
    `"addr": "178.172.xxx.xxx:9246",`
    `"services": "00000001",`
    `"lastrecv": 1388183523,`
    `"lastsend": 1388185470,`
    `"bytessent": 287592965,`
    `"bytesrecv": 780340,`
    `"conntime": 1388182973,`
    `"pingtime": 405551,`
    `"pingwait": 183023,`
    `"version": 70001,`
    `"subver": "/lbcd:0.4.0/",`
    `"inbound": false,`
    `"startingheight": 276921,`
    `"currentheight": 276955,`
    `"syncnode": true,`
  `}`
`]` | [Return to Overview](#MethodOverview)
*** diff --git a/docs/mining.md b/docs/mining.md index 2d258733..226d560b 100644 --- a/docs/mining.md +++ b/docs/mining.md @@ -27,6 +27,6 @@ certificate into the default system Certificate Authority list. ## Set your mining software url to use https -`cgminer -o https://127.0.0.1:8334 -u rpcuser -p rpcpassword` +`cgminer -o https://127.0.0.1:9245 -u rpcuser -p rpcpassword` Alternatively, you can disable TLS with the `--notls` option for the server. diff --git a/sample-lbcd.conf b/sample-lbcd.conf index 66501a08..dbff2949 100644 --- a/sample-lbcd.conf +++ b/sample-lbcd.conf @@ -86,9 +86,9 @@ ; You may specify each IP address with or without a port. The default port will ; be added automatically if one is not specified here. ; addpeer=192.168.1.1 -; addpeer=10.0.0.2:8333 +; addpeer=10.0.0.2:9246 ; addpeer=fe80::1 -; addpeer=[fe80::2]:8333 +; addpeer=[fe80::2]:9246 ; Add persistent peers that you ONLY want to connect to as desired. One peer ; per line. You may specify each IP address with or without a port. The @@ -96,9 +96,9 @@ ; NOTE: Specifying this option has other side effects as described above in ; the 'addpeer' versus 'connect' summary section. ; connect=192.168.1.1 -; connect=10.0.0.2:8333 +; connect=10.0.0.2:9246 ; connect=fe80::1 -; connect=[fe80::2]:8333 +; connect=[fe80::2]:9246 ; Maximum number of inbound and outbound peers. ; maxpeers=125 @@ -135,16 +135,16 @@ ; listen=0.0.0.0 ; All ipv6 interfaces on default port: ; listen=:: -; All interfaces on port 8333: -; listen=:8333 -; All ipv4 interfaces on port 8333: -; listen=0.0.0.0:8333 -; All ipv6 interfaces on port 8333: -; listen=[::]:8333 -; Only ipv4 localhost on port 8333: -; listen=127.0.0.1:8333 -; Only ipv6 localhost on port 8333: -; listen=[::1]:8333 +; All interfaces on port 9246: +; listen=:9246 +; All ipv4 interfaces on port 9246: +; listen=0.0.0.0:9246 +; All ipv6 interfaces on port 9246: +; listen=[::]:9246 +; Only ipv4 localhost on port 9246: +; listen=127.0.0.1:9246 +; Only ipv6 localhost on port 9246: +; listen=[::1]:9246 ; Only ipv4 localhost on non-standard port 8336: ; listen=127.0.0.1:8336 ; All interfaces on non-standard port 8336: