diff options
| -rw-r--r-- | README.md | 191 |
1 files changed, 191 insertions, 0 deletions
@@ -54,6 +54,197 @@ The go-ethereum project comes with several wrappers/executables found in the `cm | `gethrpctest` | Developer utility tool to support our [ethereum/rpc-test](https://github.com/ethereum/rpc-tests) test suite which validates baseline conformity to the [Ethereum JSON RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC) specs. Please see the [test suite's readme](https://github.com/ethereum/rpc-tests/blob/master/README.md) for details. | | `rlpdump` | Developer utility tool to convert binary RLP ([Recursive Length Prefix](https://github.com/ethereum/wiki/wiki/RLP)) dumps (data encoding used by the Ethereum protocol both network as well as consensus wise) to user friendlier hierarchical representation (e.g. `rlpdump --hex CE0183FFFFFFC4C304050583616263`). | +## Running geth + +Going through all the possible command line flags is out of scope here (please consult our +[CLI Wiki page](https://github.com/ethereum/go-ethereum/wiki/Command-Line-Options)), but we've +enumerated a few common parameter combos to get you up to speed quickly on how you can run your +own Geth instance. + +### Full node on the main Ethereum network + +By far the most common scenario is people wanting to simply interact with the Ethereum network: +create accounts; transfer funds; deploy and interact with contracts. For this particular use-case +the user doesn't care about years-old historical data, so we can fast-sync quickly to the current +state of the network. To do so: + +``` +$ geth --fast --cache=512 console +``` + +This command will: + + * Start geth in fast sync mode (`--fast`), causing it to download more data in exchange for avoiding + processing the entire history of the Ethereum network, which is very CPU intensive. + * Bump the memory allowance of the database to 512MB (`--cache=512`), which can help significantly in + sync times especially for HDD users. This flag is optional and you can set it as high or as low as + you'd like, though we'd recommend the 512MB - 2GB range. + * Start up Geth's built-in interactive [JavaScript console](https://github.com/ethereum/go-ethereum/wiki/JavaScript-Console), + (via the trailing `console` subcommand) through which you can invoke all official [`web3` methods](https://github.com/ethereum/wiki/wiki/JavaScript-API) + as well as Geth's own [management APIs](https://github.com/ethereum/go-ethereum/wiki/Management-APIs). + This too is optional and if you leave it out you can always attach to an already running Geth instance + with `geth --attach`. + +### Full node on the Ethereum test network + +Transitioning towards developers, if you'd like to play around with creating Ethereum contracts, you +almost certainly would like to do that without any real money involved until you get the hang of the +entire system. In other words, instead of attaching to the main network, you want to join the **test** +network with your node, which is fully equivalent to the main network, but with play-Ether only. + +``` +$ geth --testnet --fast --cache=512 console +``` + +The `--fast`, `--cache` flags and `console` subcommand have the exact same meaning as above and they +are equially useful on the testnet too. Please see above for their explanations if you've skipped to +here. + +Specifying the `--testnet` flag however will reconfigure your Geth instance a bit: + + * Instead of using the default data directory (`~/.ethereum` on Linux for example), Geth will nest + itself one level deeper into a `testnet` subfolder (`~/.ethereum/testnet` on Linux). + * Instead of connecting the main Ethereum network, the client will connect to the test network, + which uses different P2P bootnodes, different network IDs and genesis states. + +*Note: Although there are some internal protective measures to prevent transactions from crossing +over between the main network and test network (different starting nonces), you should make sure to +always use separate accounts for play-money and real-money. Unless you manually move accounts, Geth +will by default correctly separate the two networks and will not make any accounts available between +them.* + +### Programatically interfacing Geth nodes + +As a developer, sooner rather than later you'll want to start interacting with Geth and the Ethereum +network via your own programs and not manually through the console. To aid this, Geth has built in +support for a JSON-RPC based APIs ([standard APIs](https://github.com/ethereum/wiki/wiki/JSON-RPC) and +[Geth specific APIs](https://github.com/ethereum/go-ethereum/wiki/Management-APIs)). These can be +exposed via HTTP, WebSockets and IPC (unix sockets on unix based platroms, and named pipes on Windows). + +The IPC interface is enabled by default and exposes all the APIs supported by Geth, whereas the HTTP +and WS interfaces need to manually be enabled and only expose a subset of APIs due to security reasons. +These can be turned on/off and configured as you'd expect. + +HTTP based JSON-RPC API options: + + * `--rpc` Enable the HTTP-RPC server + * `--rpcaddr` HTTP-RPC server listening interface (default: "localhost") + * `--rpcport` HTTP-RPC server listening port (default: 8545) + * `--rpcapi` API's offered over the HTTP-RPC interface (default: "eth,net,web3") + * `--rpccorsdomain` Comma separated list of domains from which to accept cross origin requests (browser enforced) + * `--ws` Enable the WS-RPC server + * `--wsaddr` WS-RPC server listening interface (default: "localhost") + * `--wsport` WS-RPC server listening port (default: 8546) + * `--wsapi` API's offered over the WS-RPC interface (default: "eth,net,web3") + * `--wsorigins` Origins from which to accept websockets requests + * `--ipcdisable` Disable the IPC-RPC server + * `--ipcapi` API's offered over the IPC-RPC interface (default: "admin,debug,eth,miner,net,personal,shh,txpool,web3") + * `--ipcpath` Filename for IPC socket/pipe within the datadir (explicit paths escape it) + +You'll need to use your own programming environments' capabilities (libraries, tools, etc) to connect +via HTTP, WS or IPC to a Geth node configured with the above flags and you'll need to speak [JSON-RPC](http://www.jsonrpc.org/specification) +on all transports. You can reuse the same connection for multiple requests! + +**Note: Please understand the security implications of opening up an HTTP/WS based transport before +doing so! Hackers on the internet are actively trying to subvert Ethereum nodes with exposed APIs! +Further, all browser tabs can access locally running webservers, so malicious webpages could try to +subvert locally available APIs!** + +### Operating a private network + +Maintaining your own private network is more involved as a lot of configurations taken for granted in +the official networks need to be manually set up. + +#### Defining the private genesis state + +First, you'll need to create the genesis state of your networks, which all nodes need to be aware of +and agree upon. This consists of a small JSON file (e.g. call it `genesis.json`): + +```json +{ + "alloc" : {}, + "coinbase" : "0x0000000000000000000000000000000000000000", + "difficulty" : "0x20000", + "extraData" : "", + "gasLimit" : "0x2fefd8", + "nonce" : "0x0000000000000042", + "mixhash" : "0x0000000000000000000000000000000000000000000000000000000000000000", + "parentHash" : "0x0000000000000000000000000000000000000000000000000000000000000000", + "timestamp" : "0x00" +} +``` + +The above fields should be fine for most purposes, although we'd recommend changing the `nonce` to +some random value so you prevent unknown remote nodes from being able to connect to you. If you'd +like to pre-fund some accounts for easier testing, you can populate the `alloc` field with account +configs: + +```json +"alloc": { + "0x0000000000000000000000000000000000000001": {"balance": "111111111"}, + "0x0000000000000000000000000000000000000002": {"balance": "222222222"} +} +``` + +With the genesis state defined in the above JSON file, you'll need to initialize **every** Geth node +with it prior to starting it up to ensure all blockchain parameters are correctly set: + +``` +$ geth init path/to/genesis.json +``` + +#### Creating the rendezvous point + +With all nodes that you want to run initialized to the desired genesis state, you'll need to start a +bootstrap node that others can use to find each other in your network and/or over the internet. The +clean way is to configure and run a dedicated bootnode: + +``` +$ bootnode --genkey=boot.key +$ bootnode --nodekey=boot.key +``` + +With the bootnode online, it will display an [`enode` URL](https://github.com/ethereum/wiki/wiki/enode-url-format) +that other nodes can use to connect to it and exchange peer information. Make sure to replace the +displayed IP address information (most probably `[::]`) with your externally accessible IP to get the +actual `enode` URL. + +*Note: You could also use a full fledged Geth node as a bootnode, but it's the less recommended way.* + +#### Starting up your member nodes + +With the bootnode operational and externally reachable (you can try `telnet <ip> <port>` to ensure +it's indeed reachable), start every subsequent Geth node pointed to the bootnode for peer discovery +via the `--bootnodes` flag. It will probably also be desirable to keep the data directory of your +private network separated, so do also specify a custom `--datadir` flag. + +``` +$ geth --datadir=path/to/custom/data/folder --bootnodes=<bootnode-enode-url-from-above> +``` + +*Note: Since your network will be completely cut off from the main and test networks, you'll also +need to configure a miner to process transactions and create new blocks for you.* + +#### Running a private miner + +Mining on the public Ethereum network is a complex task as it's only feasible using GPUs, requiring +an OpenCL or CUDA enabled `ethminer` instance. For information on such a setup, please consult the +[EtherMining subreddit](https://www.reddit.com/r/EtherMining/) and the [Genoil miner](https://github.com/Genoil/cpp-ethereum) +repository. + +In a private network setting however, a single CPU miner instance is more than enough for practical +purposes as it can produce a stable stream of blocks at the correct intervals without needing heavy +resources (consider running on a single thread, no need for multiple ones either). To start a Geth +instance for mining, run it with all your usual flags, extended by: + +``` +$ geth <usual-flags> --mine --minerthreads=1 --etherbase=0x0000000000000000000000000000000000000000 +``` + +Which will start mining bocks and transactions on a single CPU thread, crediting all proceedings to +the account specified by `--etherbase`. You can further tune the mining by changing the default gas +limit blocks converge to (`--targetgaslimit`) and the price transactions are accepted at (`--gasprice`). + ## Contribution Thank you for considering to help out with the source code! We welcome contributions from |