Skip to content

Commit e76c55a

Browse files
karalabekaralabe
authored
Merge pull request #2805 from karalabe/readme-running-geth
README: expand with "Running Geth" section
2 parents c7442ef + ca21106 commit e76c55a

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

‎README.md

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,197 @@ The go-ethereum project comes with several wrappers/executables found in the `cm
5454
| `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. |
5555
| `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`). |
5656

57+
## Running geth
58+
59+
Going through all the possible command line flags is out of scope here (please consult our
60+
[CLI Wiki page](https://github.com/ethereum/go-ethereum/wiki/Command-Line-Options)), but we've
61+
enumerated a few common parameter combos to get you up to speed quickly on how you can run your
62+
own Geth instance.
63+
64+
### Full node on the main Ethereum network
65+
66+
By far the most common scenario is people wanting to simply interact with the Ethereum network:
67+
create accounts; transfer funds; deploy and interact with contracts. For this particular use-case
68+
the user doesn't care about years-old historical data, so we can fast-sync quickly to the current
69+
state of the network. To do so:
70+
71+
```
72+
$ geth --fast --cache=512 console
73+
```
74+
75+
This command will:
76+
77+
* Start geth in fast sync mode (`--fast`), causing it to download more data in exchange for avoiding
78+
processing the entire history of the Ethereum network, which is very CPU intensive.
79+
* Bump the memory allowance of the database to 512MB (`--cache=512`), which can help significantly in
80+
sync times especially for HDD users. This flag is optional and you can set it as high or as low as
81+
you'd like, though we'd recommend the 512MB - 2GB range.
82+
* Start up Geth's built-in interactive [JavaScript console](https://github.com/ethereum/go-ethereum/wiki/JavaScript-Console),
83+
(via the trailing `console` subcommand) through which you can invoke all official [`web3` methods](https://github.com/ethereum/wiki/wiki/JavaScript-API)
84+
as well as Geth's own [management APIs](https://github.com/ethereum/go-ethereum/wiki/Management-APIs).
85+
This too is optional and if you leave it out you can always attach to an already running Geth instance
86+
with `geth --attach`.
87+
88+
### Full node on the Ethereum test network
89+
90+
Transitioning towards developers, if you'd like to play around with creating Ethereum contracts, you
91+
almost certainly would like to do that without any real money involved until you get the hang of the
92+
entire system. In other words, instead of attaching to the main network, you want to join the **test**
93+
network with your node, which is fully equivalent to the main network, but with play-Ether only.
94+
95+
```
96+
$ geth --testnet --fast --cache=512 console
97+
```
98+
99+
The `--fast`, `--cache` flags and `console` subcommand have the exact same meaning as above and they
100+
are equially useful on the testnet too. Please see above for their explanations if you've skipped to
101+
here.
102+
103+
Specifying the `--testnet` flag however will reconfigure your Geth instance a bit:
104+
105+
* Instead of using the default data directory (`~/.ethereum` on Linux for example), Geth will nest
106+
itself one level deeper into a `testnet` subfolder (`~/.ethereum/testnet` on Linux).
107+
* Instead of connecting the main Ethereum network, the client will connect to the test network,
108+
which uses different P2P bootnodes, different network IDs and genesis states.
109+
110+
*Note: Although there are some internal protective measures to prevent transactions from crossing
111+
over between the main network and test network (different starting nonces), you should make sure to
112+
always use separate accounts for play-money and real-money. Unless you manually move accounts, Geth
113+
will by default correctly separate the two networks and will not make any accounts available between
114+
them.*
115+
116+
### Programatically interfacing Geth nodes
117+
118+
As a developer, sooner rather than later you'll want to start interacting with Geth and the Ethereum
119+
network via your own programs and not manually through the console. To aid this, Geth has built in
120+
support for a JSON-RPC based APIs ([standard APIs](https://github.com/ethereum/wiki/wiki/JSON-RPC) and
121+
[Geth specific APIs](https://github.com/ethereum/go-ethereum/wiki/Management-APIs)). These can be
122+
exposed via HTTP, WebSockets and IPC (unix sockets on unix based platroms, and named pipes on Windows).
123+
124+
The IPC interface is enabled by default and exposes all the APIs supported by Geth, whereas the HTTP
125+
and WS interfaces need to manually be enabled and only expose a subset of APIs due to security reasons.
126+
These can be turned on/off and configured as you'd expect.
127+
128+
HTTP based JSON-RPC API options:
129+
130+
* `--rpc` Enable the HTTP-RPC server
131+
* `--rpcaddr` HTTP-RPC server listening interface (default: "localhost")
132+
* `--rpcport` HTTP-RPC server listening port (default: 8545)
133+
* `--rpcapi` API's offered over the HTTP-RPC interface (default: "eth,net,web3")
134+
* `--rpccorsdomain` Comma separated list of domains from which to accept cross origin requests (browser enforced)
135+
* `--ws` Enable the WS-RPC server
136+
* `--wsaddr` WS-RPC server listening interface (default: "localhost")
137+
* `--wsport` WS-RPC server listening port (default: 8546)
138+
* `--wsapi` API's offered over the WS-RPC interface (default: "eth,net,web3")
139+
* `--wsorigins` Origins from which to accept websockets requests
140+
* `--ipcdisable` Disable the IPC-RPC server
141+
* `--ipcapi` API's offered over the IPC-RPC interface (default: "admin,debug,eth,miner,net,personal,shh,txpool,web3")
142+
* `--ipcpath` Filename for IPC socket/pipe within the datadir (explicit paths escape it)
143+
144+
You'll need to use your own programming environments' capabilities (libraries, tools, etc) to connect
145+
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)
146+
on all transports. You can reuse the same connection for multiple requests!
147+
148+
**Note: Please understand the security implications of opening up an HTTP/WS based transport before
149+
doing so! Hackers on the internet are actively trying to subvert Ethereum nodes with exposed APIs!
150+
Further, all browser tabs can access locally running webservers, so malicious webpages could try to
151+
subvert locally available APIs!**
152+
153+
### Operating a private network
154+
155+
Maintaining your own private network is more involved as a lot of configurations taken for granted in
156+
the official networks need to be manually set up.
157+
158+
#### Defining the private genesis state
159+
160+
First, you'll need to create the genesis state of your networks, which all nodes need to be aware of
161+
and agree upon. This consists of a small JSON file (e.g. call it `genesis.json`):
162+
163+
```json
164+
{
165+
"alloc" : {},
166+
"coinbase" : "0x0000000000000000000000000000000000000000",
167+
"difficulty" : "0x20000",
168+
"extraData" : "",
169+
"gasLimit" : "0x2fefd8",
170+
"nonce" : "0x0000000000000042",
171+
"mixhash" : "0x0000000000000000000000000000000000000000000000000000000000000000",
172+
"parentHash" : "0x0000000000000000000000000000000000000000000000000000000000000000",
173+
"timestamp" : "0x00"
174+
}
175+
```
176+
177+
The above fields should be fine for most purposes, although we'd recommend changing the `nonce` to
178+
some random value so you prevent unknown remote nodes from being able to connect to you. If you'd
179+
like to pre-fund some accounts for easier testing, you can populate the `alloc` field with account
180+
configs:
181+
182+
```json
183+
"alloc": {
184+
"0x0000000000000000000000000000000000000001": {"balance": "111111111"},
185+
"0x0000000000000000000000000000000000000002": {"balance": "222222222"}
186+
}
187+
```
188+
189+
With the genesis state defined in the above JSON file, you'll need to initialize **every** Geth node
190+
with it prior to starting it up to ensure all blockchain parameters are correctly set:
191+
192+
```
193+
$ geth init path/to/genesis.json
194+
```
195+
196+
#### Creating the rendezvous point
197+
198+
With all nodes that you want to run initialized to the desired genesis state, you'll need to start a
199+
bootstrap node that others can use to find each other in your network and/or over the internet. The
200+
clean way is to configure and run a dedicated bootnode:
201+
202+
```
203+
$ bootnode --genkey=boot.key
204+
$ bootnode --nodekey=boot.key
205+
```
206+
207+
With the bootnode online, it will display an [`enode` URL](https://github.com/ethereum/wiki/wiki/enode-url-format)
208+
that other nodes can use to connect to it and exchange peer information. Make sure to replace the
209+
displayed IP address information (most probably `[::]`) with your externally accessible IP to get the
210+
actual `enode` URL.
211+
212+
*Note: You could also use a full fledged Geth node as a bootnode, but it's the less recommended way.*
213+
214+
#### Starting up your member nodes
215+
216+
With the bootnode operational and externally reachable (you can try `telnet <ip> <port>` to ensure
217+
it's indeed reachable), start every subsequent Geth node pointed to the bootnode for peer discovery
218+
via the `--bootnodes` flag. It will probably also be desirable to keep the data directory of your
219+
private network separated, so do also specify a custom `--datadir` flag.
220+
221+
```
222+
$ geth --datadir=path/to/custom/data/folder --bootnodes=<bootnode-enode-url-from-above>
223+
```
224+
225+
*Note: Since your network will be completely cut off from the main and test networks, you'll also
226+
need to configure a miner to process transactions and create new blocks for you.*
227+
228+
#### Running a private miner
229+
230+
Mining on the public Ethereum network is a complex task as it's only feasible using GPUs, requiring
231+
an OpenCL or CUDA enabled `ethminer` instance. For information on such a setup, please consult the
232+
[EtherMining subreddit](https://www.reddit.com/r/EtherMining/) and the [Genoil miner](https://github.com/Genoil/cpp-ethereum)
233+
repository.
234+
235+
In a private network setting however, a single CPU miner instance is more than enough for practical
236+
purposes as it can produce a stable stream of blocks at the correct intervals without needing heavy
237+
resources (consider running on a single thread, no need for multiple ones either). To start a Geth
238+
instance for mining, run it with all your usual flags, extended by:
239+
240+
```
241+
$ geth <usual-flags> --mine --minerthreads=1 --etherbase=0x0000000000000000000000000000000000000000
242+
```
243+
244+
Which will start mining bocks and transactions on a single CPU thread, crediting all proceedings to
245+
the account specified by `--etherbase`. You can further tune the mining by changing the default gas
246+
limit blocks converge to (`--targetgaslimit`) and the price transactions are accepted at (`--gasprice`).
247+
57248
## Contribution
58249

59250
Thank you for considering to help out with the source code! We welcome contributions from

0 commit comments

Comments
 (0)