From 7f34978b2bba9ed9c29b0d723044dd58ffb678c9 Mon Sep 17 00:00:00 2001 From: Joe Date: Thu, 28 Jul 2022 17:00:12 +0100 Subject: [PATCH] content updates --- content/docs/fundamentals/Backup--restore.md | 29 +- content/docs/fundamentals/cross-compile.md | 167 ------- .../docs/fundamentals/node-architecture.md | 20 +- content/docs/fundamentals/security.md | 34 ++ .../Backup--restore.md | 0 .../Installing-Geth.md | 0 .../docs/getting_started/consensus-clients.md | 70 +-- .../docs/getting_started/getting_started.md | 452 ++++++++++++++++++ content/docs/install_build/Installing-Geth.md | 356 -------------- content/docs/install_build/cross-compile.md | 167 ------- 10 files changed, 529 insertions(+), 766 deletions(-) delete mode 100644 content/docs/fundamentals/cross-compile.md create mode 100644 content/docs/fundamentals/security.md rename content/docs/{install_build => getting_started}/Backup--restore.md (100%) rename content/docs/{fundamentals => getting_started}/Installing-Geth.md (100%) create mode 100644 content/docs/getting_started/getting_started.md delete mode 100644 content/docs/install_build/Installing-Geth.md delete mode 100644 content/docs/install_build/cross-compile.md diff --git a/content/docs/fundamentals/Backup--restore.md b/content/docs/fundamentals/Backup--restore.md index 6d038572d1..1534d360a4 100644 --- a/content/docs/fundamentals/Backup--restore.md +++ b/content/docs/fundamentals/Backup--restore.md @@ -1,34 +1,36 @@ --- title: Backup & Restore -sort_key: C --- -Most important info first: **REMEMBER YOUR PASSWORD** and **BACKUP YOUR KEYSTORE**. +**Keep secure backups of your keystore and password!** ## Data Directory -Everything `geth` persists gets written inside its data directory. The default data -directory locations are platform specific: +All data relating to a specific Geth instance gets written inside a data directory. +The default data directory locations are platform specific: * Mac: `~/Library/Ethereum` * Linux: `~/.ethereum` * Windows: `%LOCALAPPDATA%\Ethereum` Accounts are stored in the `keystore` subdirectory. The contents of this directories -should be transportable between nodes, platforms, implementations (C++, Go, Python). +should be transportable between nodes, platforms, and client implementations. To configure the location of the data directory, the `--datadir` parameter can be specified. See [CLI Options](../interface/command-line-options) for more details. +There may exist multiple data directories for multiple networks (e.g. a separate directory +for Ethereum Mainnet and the Goerli testnet). Each would have subdirectories for their +blockchain data and keystore. -Note the [ethash dag](../interface/mining) is stored at `~/.ethash` (Mac/Linux) or -`%APPDATA%\Ethash` (Windows) so that it can be reused by all clients. You can store this -in a different location by using a symbolic link. +It is important to backup the files in the keystore securely. These files are encrypted +using an account password. This needs to be securely backed up too. There is no way to +decrypt the keys without the password! ## Cleanup Geth's blockchain and state databases can be removed with: -``` +```sh geth removedb ``` @@ -39,14 +41,14 @@ directories that can be re-created on synchronisation and does not touch the key Export the blockchain in binary format with: -``` +```sh geth export ``` Or if you want to back up portions of the chain over time, a first and last block can be specified. For example, to back up the first epoch: -``` +```sh geth export 0 29999 ``` @@ -55,11 +57,8 @@ truncated. Import binary-format blockchain exports with: -``` +```sh geth import ``` -_See https://eth.wiki/en/howto/blockchain-import-and-export-instructions for more info_ - - And finally: **REMEMBER YOUR PASSWORD** and **BACKUP YOUR KEYSTORE** diff --git a/content/docs/fundamentals/cross-compile.md b/content/docs/fundamentals/cross-compile.md deleted file mode 100644 index 55af4e6652..0000000000 --- a/content/docs/fundamentals/cross-compile.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Cross-Compiling Geth -sort_key: C ---- - -**Note: All of these and much more have been merged into the project Makefile. You can -cross build via `make geth--` without needing to know any of these details -from below.** - -Developers usually have a preferred platform that they feel most comfortable working in, -with all the necessary tools, libraries and environments set up for an optimal workflow. -However, there's often need to build for either a different CPU architecture, or an -entirely different operating system; but maintaining a development environment for each -and switching between the them quickly becomes unwieldy. - -Here we present a very simple way to cross compile Ethereum to various operating systems -and architectures using a minimal set of prerequisites and a completely containerized -approach, guaranteeing that your development environment remains clean even after the -complex requirements and mechanisms of a cross compilation. - -The currently supported target platforms are: - - - ARMv7 Android and iOS - - 32 bit, 64 bit and ARMv5 Linux - - 32 bit and 64 bit Mac OSX - - 32 bit and 64 bit Windows - -Please note, that cross compilation does not replace a release build. Although resulting -binaries can usually run perfectly on the desired platform, compiling on a native system -with the specialized tools provided by the official vendor can often result in more a -finely optimized code. - -## Cross compilation environment - -Although the `go-ethereum` project is written in Go, it does include a bit of C code -shared between all implementations to ensure that all perform equally well, including a -dependency to the GNU Multiple Precision Arithmetic Library. Because of these, Go cannot -by itself compile to a different platform than the host. To overcome this limitation, we -will use [`xgo`](https://github.com/karalabe/xgo), a Go cross compiler package based on -Docker containers that has been architected specifically to allow both embedded C snippets -as well as simpler external C dependencies during compilation. - -The `xgo` project has two simple dependencies: Docker (to ensure that the build -environment is completely contained) and Go. On most platforms these should be available -from the official package repositories. For manually installing them, please consult their -install guides at [Docker](https://docs.docker.com/installation/) and -[Go](https://golang.org/doc/install) respectively. This guide assumes that these two -dependencies are met. - -To install and/or update xgo, simply type: - - $ go get -u github.com/karalabe/xgo - -You can test whether `xgo` is functioning correctly by requesting it to cross -compile itself and verifying that all cross compilations succeeded or not. - - $ xgo github.com/karalabe/xgo - ... - - $ ls -al - -rwxr-xr-x 1 root root 2792436 Sep 14 16:45 xgo-android-21-arm - -rwxr-xr-x 1 root root 2353212 Sep 14 16:45 xgo-darwin-386 - -rwxr-xr-x 1 root root 2906128 Sep 14 16:45 xgo-darwin-amd64 - -rwxr-xr-x 1 root root 2388288 Sep 14 16:45 xgo-linux-386 - -rwxr-xr-x 1 root root 2960560 Sep 14 16:45 xgo-linux-amd64 - -rwxr-xr-x 1 root root 2437864 Sep 14 16:45 xgo-linux-arm - -rwxr-xr-x 1 root root 2551808 Sep 14 16:45 xgo-windows-386.exe - -rwxr-xr-x 1 root root 3130368 Sep 14 16:45 xgo-windows-amd64.exe - - -## Building Ethereum - -Cross compiling Ethereum is analogous to the above example, but an additional flags is -required to satisfy the dependencies: - - - `--deps` is used to inject arbitrary C dependency packages and pre-build them - -Injecting the GNU Arithmetic Library dependency and selecting `geth` would be: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - github.com/ethereum/go-ethereum/cmd/geth - ... - - $ ls -al - -rwxr-xr-x 1 root root 23213372 Sep 14 17:59 geth-android-21-arm - -rwxr-xr-x 1 root root 14373980 Sep 14 17:59 geth-darwin-386 - -rwxr-xr-x 1 root root 17373676 Sep 14 17:59 geth-darwin-amd64 - -rwxr-xr-x 1 root root 21098910 Sep 14 17:59 geth-linux-386 - -rwxr-xr-x 1 root root 25049693 Sep 14 17:59 geth-linux-amd64 - -rwxr-xr-x 1 root root 20578535 Sep 14 17:59 geth-linux-arm - -rwxr-xr-x 1 root root 16351260 Sep 14 17:59 geth-windows-386.exe - -rwxr-xr-x 1 root root 19418071 Sep 14 17:59 geth-windows-amd64.exe - - -As the cross compiler needs to build all the dependencies as well as the main project -itself for each platform, it may take a while for the build to complete (approximately 3-4 -minutes on a Core i7 3770K machine). - -### Fine tuning the build - -By default Go, and inherently `xgo`, checks out and tries to build the master branch of a -source repository. However, more often than not, you'll probably want to build a different -branch from possibly an entirely different remote repository. These can be controlled via -the `--remote` and `--branch` flags. - -To build the `develop` branch of the official `go-ethereum` repository instead of the -default `master` branch, you just need to specify it as an additional command line flag -(`--branch`): - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --branch=develop \ - github.com/ethereum/go-ethereum/cmd/geth - -Additionally, during development you will most probably want to not only build a custom -branch, but also one originating from your own fork of the repository instead of the -upstream one. This can be done via the `--remote` flag: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --remote=https://github.com/karalabe/go-ethereum \ - --branch=rpi-staging \ - github.com/ethereum/go-ethereum/cmd/geth - -By default `xgo` builds binaries for all supported platforms and architectures, with -Android binaries defaulting to the highest released Android NDK platform. To limit the -build targets or compile to a different Android platform, use the `--targets` CLI -parameter. - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --targets=android-16/arm,windows/* \ - github.com/ethereum/go-ethereum/cmd/geth - -### Building locally - -If you would like to cross compile your local development version, simply specify a local -path (starting with `.` or `/`), and `xgo` will use all local code from `GOPATH`, only -downloading missing dependencies. In such a case of course, the `--branch`, `--remote` and -`--pkg` arguments are no-op: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - ./cmd/geth - -## Using the Makefile - -Having understood the gist of `xgo` based cross compilation, you do not need to actually -memorize and maintain these commands, as they have been incorporated into the official -[Makefile](https://github.com/ethereum/go-ethereum/blob/master/Makefile) and can be -invoked with a trivial `make` request: - - * `make geth-cross`: Cross compiles to every supported OS and architecture - * `make geth-`: Cross compiles supported architectures of a particular OS (e.g. `linux`) - * `make geth--`: Cross compiles to a specific OS/architecture (e.g. `linux`, `arm`) - -We advise using the `make` based commands opposed to manually invoking `xgo` as we do -maintain the Makefile actively whereas we cannot guarantee that this document will be -always readily updated to latest advancements. - -### Tuning the cross builds - -A few of the `xgo` build options have also been surfaced directly into the Makefile to -allow fine tuning builds to work around either upstream Go issues, or to enable some -fancier mechanics. - - - `make ... GO=`: Use a specific Go runtime (e.g. `1.5.1`, `1.5-develop`, `develop`) - - `make ... MODE=`: Build a specific target type (e.g. `exe`, `c-archive`). - -Please note that these are not yet fully finalized, so they may or may not change in the -future as our code and the Go runtime features change. diff --git a/content/docs/fundamentals/node-architecture.md b/content/docs/fundamentals/node-architecture.md index 9ad8662e1e..4dcf68b005 100644 --- a/content/docs/fundamentals/node-architecture.md +++ b/content/docs/fundamentals/node-architecture.md @@ -3,13 +3,15 @@ Geth is an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients). Originally, an execution client alone was enough to run a full Ethereum node. -However, ever since Ethereum turned off proof-of-work and implemented proof-of-stake, -Geth must to be coupled to another piece of software called a -[“consensus client”](https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients). +However, ever since Ethereum turned off [proof-of-work](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/) and implemented [proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/), +Geth has needed to be coupled to another piece of software called a +[“consensus client”](https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients) in order to +keep track of the Ethereum blockchain. -The execution client is responsible for transaction handling, transaction gossip, state management and -the Ethereum Virtual Machine (EVM). However, Geth is **not** responsible for block building, block gossiping -or handling consensus logic. These are in the remit of the consensus client. +The execution client is responsible for transaction handling, transaction gossip, state management and supporting +the Ethereum Virtual Machine ([EVM])(https://ethereum.org/en/developers/docs/evm/). However, Geth is **not** +responsible for block building, block gossiping or handling consensus logic. These are in the remit of the +consensus client. The relationship between the two Ethereum clients is shown in the schematic below. The two clients each connect to their own respective peer-to-peer (P2P) networks. This is because the execution clients gossip @@ -23,8 +25,8 @@ Geth to be executed. Executing the transactions locally is how the client valida do not violate any Ethereum rules and that the proposed update to Ethereum’s state is correct. Likewise, when the node is selected to be a block producer the consensus client must be able to request bundles of transactions from Geth to include in the new block. This inter-client communication is handled by a local -RPC connection using the engine API which is part of the JSON-RPC API exposed by Geth. - +RPC connection using the [engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md) +which is exposed internally over port 8551 by default. ## What does Geth do? @@ -43,4 +45,4 @@ In summary, Geth is: - home to the Ethereum Virtual Machine, Ethereum's state and transaction pool. - +Read more about [proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/). diff --git a/content/docs/fundamentals/security.md b/content/docs/fundamentals/security.md new file mode 100644 index 0000000000..698d0523e1 --- /dev/null +++ b/content/docs/fundamentals/security.md @@ -0,0 +1,34 @@ +--- +title: Security +root: .. +--- + +## Downloading Geth + +Download Geth using the links on our [Downloads](/downloads) page. The SHA256 hashes of the downloaded files +can be compared to ours to ensure precise consistency with our releases. This protects against malicious code being +inadvertently downloaded from an adversarial source. The same measures should also be taken to download trusted +consensus client software. + +## Networking security + +The local machine's firewall settings should: + +* Block all traffic to `8545`, or whatever custom port has been defined for JSON-RPC requests to the node, except for traffic from explicitly defined trusted machines. +* Allow traffic on `TCP 30303` or whichever custom port has been defined for peer-to-peer communications. This allows the node to connect to peers. +* Allow traffic on `UDP 30303` or whichever custom port has been defined for peer-to-peer communications. This allows node discovery. + +## Account security + +Account security comes down to keeping private keys and account passwords backed up and inaccessible to adversaries. This is something that users take responsibility for. Geth provides an encrypted store for keys that are unlocked using an account password. If the key files or the passwors are lost, the account is impossible to access and the funds are effectively lost forever. If access to the unencrypted keys is obtained by an adversary they gain control of any funds associated with the account. + +Geth has built-in account management tools that are sufficiently secure for most purposes. However, Clef is recommended as an external account management and signing tool. It can be run decoupled from Geth and can even be run on dedicated secure external hardware such as a VM or a secure USB drive. This is considered best practise because the user is required to manually review all actions that touch sensitive data, except where specific predefined rules are implemented. Signing is done locally to Clef rather than giving key access to a node. + +Geth allows account unlocking by passing account passwords at startup. This unlocks the account all the while that Geth is running. This is not allowed when `http` traffic is enabled, even with appropriate firewall setings. The combination of `http` and `-unlock` poses too much of a security risk because an attacker able to access the node over the exposed HTTP port would be able to make JSON-RPC requests to the node from the unlocked account, including sending funds to other addresses. + +**back up your keystore and passwords safely and securely!** + + +## Other security considerations + +Even with a perfectly secure node, users can still be manipulated by attackers into exposing security weaknesses or inadvertently interact with insecure smart contracts. For an overview, please see the Ethereum [security best practise webpage](https://ethereum.org/en/security) and this introduction to [smart contract security](https://ethereum.org/en/developers/docs/smart-contracts/security). \ No newline at end of file diff --git a/content/docs/install_build/Backup--restore.md b/content/docs/getting_started/Backup--restore.md similarity index 100% rename from content/docs/install_build/Backup--restore.md rename to content/docs/getting_started/Backup--restore.md diff --git a/content/docs/fundamentals/Installing-Geth.md b/content/docs/getting_started/Installing-Geth.md similarity index 100% rename from content/docs/fundamentals/Installing-Geth.md rename to content/docs/getting_started/Installing-Geth.md diff --git a/content/docs/getting_started/consensus-clients.md b/content/docs/getting_started/consensus-clients.md index 363997036e..17cb109d0f 100644 --- a/content/docs/getting_started/consensus-clients.md +++ b/content/docs/getting_started/consensus-clients.md @@ -3,19 +3,13 @@ title: Connecting to Consensus Clients sort_key: A3 --- -Geth is an [execution client][ex-client-link]. Historically, an execution client alone has been enough to run a full Ethereum node. -However, Ethereum will soon swap its consensus mechanism from [proof-of-work][pow-link] (PoW) to -[proof-of-stake][pos-link] (PoS) in a transition known as [The Merge](/docs/interface/merge). +Geth is an [execution client][ex-client-link]. Historically, an execution client alone was enough to +run a full Ethereum node. However, ever since Ethereum swapped from [proof-of-work][pow-link] (PoW) to +[proof-of-stake][pos-link] (PoS) based consensus, Geth has needed to be coupled to another piece of +software called a ["consensus client"][con-client-link]. -When that happens, Geth will not be able to track the Ethereum chain on its own. Instead, it will need to -be coupled to another piece of software called a ["consensus client"][con-client-link]. For Geth users that -intend to continue to run full nodes after The Merge, it is sensible to start running a consensus client now, -so that The Merge can happen smoothly. There are five consensus clients available, all of which connect to Geth in the same way. - -This page will outline how Geth can be set up with a consensus client in advance of The Merge (or to interact with an alread-merged testnet). - -{% include note.html content=" It is recommended to practise connecting a consensus client to Geth on a testnet such as Sepolia or Goerli but to -wait until merge-ready releases are available before doing it on Ethereum Mainnet." %} +There are four consensus clients available, all of which connect to Geth in the same way. This page will +outline how Geth can be set up with a consensus client. ## Configuring Geth @@ -33,10 +27,6 @@ The authorization must then be applied to a specific address/port. This is achie `*` to `--authrpc.vhosts` so that incoming requests from virtual hosts are accepted by Geth because it only applies to the port authenticated using `jwtsecret`. -The Merge itself will be triggered using a terminal total difficulty (TTD). The specific value for the TTD has not yet -been decided. When it is decided, Geth needs to know what it is in order to merge successfully. This will most likely be -included in a new release, so Geth will have to be stopped, updated and restarted in advance of The Merge. - A complete command to start Geth so that it can connect to a consensus client looks as follows: ```shell @@ -56,7 +46,8 @@ There are currently four consensus clients that can be run alongside Geth. These [Teku](https://pegasys.tech/teku): written in Java -It is recommended to consider [client diversity][client-div-link] when choosing a consensus client. Instructions for installing each client are provided in the documentation linked in the list above. +It is recommended to consider [client diversity][client-div-link] when choosing a consensus client. +Instructions for installing each client are provided in the documentation linked in the list above. The consensus client must be started with the right port configuration to establish an RPC connection to the local Geth instance. In the example above, `localhost:8551` was authorized @@ -73,49 +64,24 @@ More information on this can be found in the documentation for each consensus cl ## Validators -After The Merge, miners are no longer responsible for securing the Ethereum blockchain. Instead, this becomes the responsibility -of validators that have staked at least 32 ETH into a deposit contract and run validator software. Each of the consensus clients -have their own validator software that is described in detail in their respective documentation. The easiest way to handle -staking and validator key generation is to use the Ethereum Foundation [Staking Launchpad][launchpad-link]. The launchpad is also -available for [Prater][prater-launchpad-link], [Ropsten][ropsten-launchpad-link] and [Kiln][kiln-launchpad-link] testnets. It is -also highly recommended to review the [Merge readiness checklist][checklist-link]. +Validators are responsible for securing the Ethereum blockchain. Validators have staked at least 32 ETH into a +deposit contract and run validator software. Each of the consensus clients have their own validator software that +is described in detail in their respective documentation. The easiest way to handle staking and validator +key generation is to use the Ethereum Foundation [Staking Launchpad][launchpad-link]. The Launchpad guides users +through the process of generating validator keys and connecting the validator to the consensus client. ## Using Geth -After the merge, Geth will follow the head of the chain via its connection to the consensus client. However, Geth is still -the portal for users to send transactions to Ethereum. Overall, Geth will not change very much from a user-perspective. -The Geth Javascript console is still available for this purpose, and the majority of the [JSON-RPC API](/docs/rpc/server) will -remain available via web3js or HTTP requests with commands as json payloads. These options are explained in more detail on the -[Javascript Console page](/docs/interface/javascript-console). The Javascript console can be started using the following command -in a separate terminal (assuming Geth's IPC file is saved in `datadir`): +Geth is the portal for users to send transactions to Ethereum. The Geth Javascript console is available +for this purpose, and the majority of the [JSON-RPC API](/docs/rpc/server) will remain available via web3js +or HTTP requests with commands as json payloads. These options are explained in more detail on the +[Javascript Console page](/docs/interface/javascript-console). The Javascript console can be started +using the following command in a separate terminal (assuming Geth's IPC file is saved in `datadir`): ```shell geth attach datadir/geth.ipc ``` - -## Testnets - -Ethereum Mainnet has not yet undergone The Merge, but some public testnets have. This means that running Geth alone is no longer -enough to interact with merged testnets. This includes two testnets that were purpose built to test The Merge (Kiln, Kintsugi) and -the long-standing public PoW chain, Ropsten, as well as the relatively new testnet Sepolia. If Geth is connected to these merged networks alone it will simply stall when it syncs as far -as the merge block, awaiting information from a consensus client. Therefore, any activity on these testnets requires Geth to be -connected to a consensus client. There are many instructional articles that exlain how to connect to these testnets using Geth in -combination with various consensus clients, for example: - -[Connecting to Kiln using Teku](https://github.com/chrishobcroft/TestingTheMerge/blob/main/geku.md) - -[Connecting to Kiln using Lighthouse](https://github.com/remyroy/ethstaker/blob/main/merge-devnet.md) - -[Connecting to Kiln using Prysm](https://hackmd.io/@prysmaticlabs/B1Q2SluWq) - -[Connecting to Ropsten using Lighthouse](https://github.com/remyroy/ethstaker/blob/main/merge-ropsten.md) - - -The Merge testing will soon progress to merging the Goerli testnet. Once this has happened Geth will require a connection -to a consensus client to work on those networks too. - - ## Summary As The Merge approaches it is important for Geth users to prepare by installing and running a consensus client. Otherwise, Geth will stop diff --git a/content/docs/getting_started/getting_started.md b/content/docs/getting_started/getting_started.md new file mode 100644 index 0000000000..448e8eb5aa --- /dev/null +++ b/content/docs/getting_started/getting_started.md @@ -0,0 +1,452 @@ +--- +title: Getting Started with Geth +permalink: docs/getting-started +sort_key: A +--- + +This page explains how to set up Geth and execute some basic tasks using the command line tools. +In order to use Geth, the software must first be installed. There are several ways Geth can be +installed depending on the operating system and the user's choice of installation method, for +example using a package manager, container or building from source. Instructions for installing +Geth can be found on the ["Install and Build"](install-and-build/installing-geth) pages. +The tutorial on this page assumes Geth and the associated developer tools have been installed successfully. + +This page provides step-by-step instructions covering the fundamentals of using Geth. This includes +generating accounts, joining an Ethereum network, syncing the blockchain and sending ether between accounts. +It is considered best-practice to use [Clef](/docs/clef/Introduction) for account management - this +is explained in the [Geth with Clef](/docs/getting-started/geth_with_clef) tutorial. In this +introductory tutorial, Geth's built-in account management tools are used instead. + +{:toc} +- this will be removed by the toc + +## Prerequisites + +In order to get the most value from the tutorials on this page, the following skills are +necessary: + +- Experience using the command line +- Basic knowledge about Ethereum and testnets +- Basic knowledge about HTTP and JavaScript + +Users that need to revisit these fundamentals can find helpful resources relating to the command +line [here][cli], Ethereum and its testnets [here](https://ethereum.org/en/developers/tutorials/), +http [here](https://developer.mozilla.org/en-US/docs/Web/HTTP) and +Javascript [here](https://www.javascript.com/learn). + +{% include note.html content="If Geth was installed from source on Linux, `make` saves the +binaries for Geth and the associated tools in `/build/bin`. To run these programs it is +convenient to move them to the top level project directory (e.g. running `mv ./build/bin/* ./`) +from `/go-ethereum`. Then `./` must be prepended to the commands in the code snippets in order to +execute a particular program, e.g. `./geth` instead of simply `geth`. If the executables are not +moved then either navigate to the `bin` directory to run them (e.g. `cd ./build/bin` and `./geth`) +or provide their path (e.g. `./build/bin/geth`). These instructions can be ignored for other installations." %} + +## Background + +Geth is an Ethereum client written in Go. This means running Geth turns a computer into an Ethereum node. +Ethereum is a peer-to-peer network where information is shared directly between nodes rather than being +managed by a central server. Nodes compete to generate new blocks of transactions to send to its peers +because they are rewarded for doing so in Ethereum's native token, ether (ETH). On receiving a new block, +each node checks that it is valid and adds it to their database. The sequence of discrete blocks is called +a "blockchain". The information provided in each block is used by Geth to update its "state" - the ether +balance of each account on Ethereum. There are two types of account: externally-owned accounts (EOAs) and +contract accounts. Contract accounts execute contract code when they receive transactions. EOAs are accounts +that users manage locally in order to sign and submit transactions. Each EOA is a public-private key pair, +where the public key is used to derive a unique address for the user and the private key is used to protect +the account and securely sign messages. Therefore, in order to use Ethereum, it is first necessary to generate +an EOA (hereafter, "account"). This tutorial will guide the user through creating an account, funding it +with ether and sending some to another address. + +Read more about Ethereum accounts [here](https://ethereum.org/en/developers/docs/accounts/). + + +## Step 1: Generating accounts + +To generate a new account in Geth: + +```sh +geth account new +``` + +This returns a prompt for a password. Once provided, a new account will be created and added to the +default keystore (`/datadir/keystore`). A custom keystore can also be provided by passing `--keystore `. +In this tutorial the keys will be stored in a new data directory `geth-tutorial`. Create that diredctory, then run: + +```sh +geth account new --keystore geth-tutorial/keystore +``` +The following will be returned to the console, confirming the new account has been created and +added to the keystore. + +```terminal +Your new account is locked with a password. Please give a password. Do not forget this password. +Password: +Repeat password: + +Your new key was generated + +Public address of the key: 0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC +Path of the secret key file: /home/go-ethereum/geth-tutorial/keystore/UTC--2022-07-25T08-27-59.433905560Z--ca57F3b40B42FCce3c37B8D18aDBca5260ca72EC + +- You can share your public address with anyone. Others need it to interact with you. +- You must NEVER share the secret key with anyone! The key controls access to your funds! +- You must BACKUP your key file! Without the key, it's impossible to access account funds! +- You must REMEMBER your password! Without the password, it's impossible to decrypt the key! +``` + +It is important to save the account address and the password somewhere secure. They will be used +again later in this tutorial. Please note that the account address shown in the code snippets +above and later in this tutorials are examples - those generated by followers of this tutorial +will be different. The account generated above can be used as the main account throughout the +remainder of this tutorial. However in order to demonstrate transactions between accounts it is +also necessary to have a second account. A second account can be added to the same keystore by +precisely repeating the previous steps, providing the same password. + +Notice that the path to the secret key includes a long filename that starts `UTC--`. This is the +name of the file that contains the keys for the new account. It is **extremely important** that +this file stays secure because it contains the secret key used to control access to any funds +associated with the account. The file should be backed up securely along with the password +used to encrypt it. If the file or the password is lost, then so is access to the funds in +the account. If someone else gains access to the keyfile and password, they have access to any +assets in the account. + +## Step 2: Start Geth + +Geth is the Ethereum client that will connect the computer to the Ethereum network. +In this tutorial the network is Goerli, an Ethereum testnet. Testnets are used to test +Ethereum client software and smart contracts in an environment where no real-world value +is at risk. To start Geth, run the Geth executable file passing argument that define the +data directory (where Geth should save blockchain data), the network ID and the sync mode. +For this tutorial, snap sync is recommended +(see [here](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/) for reasons why). + +The following command should be run in the terminal: + +```shell +geth --datadir geth-tutorial --goerli --syncmode snap +``` +Running the above command starts Geth. The terminal should rapidly fill with status updates that look like the following: + +```terminal +INFO [02-10|13:59:06.649] Starting Geth on goerli testnet... +INFO [02-10|13:59:06.649] Dropping default light client cache provided=1024 updated=128 +INFO [02-10|13:59:06.652] Maximum peer count ETH=50 LES=0 total=50 +INFO [02-10|13:59:06.660] Set global gas cap cap=50,000,000 +INFO [02-10|13:59:06.661] Allocated cache and file handles database=/.../geth-tutorial/geth/chaindata cache=64.00MiB handles=5120 +INFO [02-10|13:59:06.855] Persisted trie from memory database nodes=361 size=51.17KiB time="643.54µs" gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B +INFO [02-10|13:59:06.855] Initialised chain configuration config="{ChainID: 5 Homestead: 0 DAO: nil DAOSupport: true EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0 Constantinople: 0 Petersburg: 0 Istanbul: 1561651, Muir Glacier: nil, Berlin: 4460644, London: 5062605, Arrow Glacier: nil, MergeFork: nil, Engine: clique}" +INFO [02-10|13:59:06.862] Added trusted checkpoint block=5,799,935 hash=2de018..c32427 +INFO [02-10|13:59:06.863] Loaded most recent local header number=6,340,934 hash=483cf5..858315 td=9,321,576 age=2d9h29m +INFO [02-10|13:59:06.867] Configured checkpoint oracle address=0x18CA0E045F0D772a851BC7e48357Bcaab0a0795D signers=5 threshold=2 +INFO [02-10|13:59:06.867] Gasprice oracle is ignoring threshold set threshold=2 +WARN [02-10|13:59:06.869] Unclean shutdown detected booted=2022-02-08T04:25:08+0100 age=2d9h33m +INFO [02-10|13:59:06.870] Starting peer-to-peer node instance=Geth/v1.10.15-stable/darwin-amd64/go1.17.5 +INFO [02-10|13:59:06.995] New local node record seq=1,644,272,735,880 id=d4ffcd252d322a89 ip=127.0.0.1 udp=30303 tcp=30303 +INFO [02-10|13:59:06.996] Started P2P networking self=enode://4b80ebd341b5308f7a6b61d91aa0ea31bd5fc9e0a6a5483e59fd4ea84e0646b13ecd289e31e00821ccedece0bf4b9189c474371af7393093138f546ac23ef93e@127.0.0.1:30303 +INFO [02-10|13:59:06.997] IPC endpoint opened url=/.../geth-tutorial/geth.ipc +WARN [02-10|13:59:06.998] Light client mode is an experimental feature +INFO [02-10|13:59:08.793] Block synchronisation started +``` + +This indicates that Geth has started up and is searching for peers to connect to. Once it finds peers +it can request block headers from them, starting at the genesis block for the Goerli blockchain. +Geth continues to download blocks sequentially, saving the data in files in `/go-ethereum/geth-tutorial/geth/chaindata/`. +This is confirmed by the logs printed to the terminal. There should be a rapidly-growing sequence of logs in the +terminal with the following syntax: + +```terminal + +INFO [04-29][15:54:09.238] Looking for peers peercount=2 tried=0 static=0 +INFO [04-29][15:54:19.393] Imported new block headers count=2 elapsed=1.127ms number=996288 hash=09f1e3..718c47 age=13h9m5s +INFO [04-29][15:54:19:656] Imported new block receipts count=698 elapsed=4.464ms number=994566 hash=56dc44..007c93 age=13h9m9s + +``` + +These logs indicate that Geth is running as expected. + +If there is no error message reported to the terminal, everything is OK. Geth must be running in +order for a user to interact with the Ethereum network. If this terminal is closed down then Geth +must be restarted again. Geth can be started and stopped easily, but it must be running for any +interaction with Ethereum to take place. To shut down Geth, simply press `CTRL+C` in the Geth terminal. +To start it again, run the previous command `geth --datadir ... ..`. + +{% include note.html content="Snap syncing Goerli will take some time and until the sync is finished +you can't use the node to transfer funds. You can also try doing a [light sync](interface/les) +which will be much quicker but depends on light servers being available to serve your node the data it needs." %} + +## Step 3: Get Testnet Ether + +In order to make some transactions, the user must fund their account with ether. On Ethereum mainnet, +ether can only be obtained in three ways: 1) by receiving it as a reward for mining/validating; 2) +receiving it in a transfer from another Ethereum user or contract; 3) receiving it from an exchange, +having paid for it with fiat money. On Ethereum testnets, the ether has no real world value so it +can be made freely available via faucets. Faucets allow users to request a transfer of testnet ether +to their account. + +The address generated by `geth account new` can be pasted into the Paradigm Multifaucet faucet +[here](https://fauceth.komputing.org/?chain=1115511). This requires a Twitter login as proof of +personhood. The faucets adds ether to the given address on multiple testnets simultaneously, +including Goerli. In the next steps Geth will be used to check that the ether has been sent to +the given address and send some of it to the second address created earlier. + + +## Step 4: Interact with Geth + +For interacting with the blockchain, Geth provides JSON-RPC APIs. +[JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) is a way to execute specific tasks +by sending instructions to Geth in the form of [JSON](https://www.json.org/json-en.html) objects. +RPC stands for "Remote Procedure Call" and it refers to the ability to send these JSON-encoded +instructions from locations outside of those managed by Geth. It is possible to interact with Geth +by sending these JSON encoded instructions directly to Geth using tools such as Curl. However, +this is somewhat user-unfriendly and error-prone, especially for more complex instructions. For this +reason, there are a set of libraries built on top of JSON-RPC that provide a more user-friendly +interface for interacting with Geth. One of the most widely used is Web3.js. + +Geth provides a Javascript console that exposes the Web3.js API. This means that with Geth running in +one terminal, a Javascript environment can be opened in another allowing the user to interact with +Geth using Web3.js. There are three transport protocols that can be used to connect the Javascript +environment to Geth: + +- IPC (Inter-Process Communication): Provides unrestricted access to all APIs, but only works when the +- console is run on the same host as the Geth node. + +- HTTP: By default provides access to the `eth`, `web3` and `net` method namespaces. + +- Websocket: By default provides access to the `eth`, `web3` and `net` method namespaces. + +This tutorial will use the IPC option. To do this, the path to Geth's `ipc` file must be known. +By default, this is the `datadir`, in this case `geth-tutorial`. In a new terminal, the following +command can be run to start the Javascript console and connect it to Geth using the `geth.ipc` +file from the datadir: + +```shell +geth attach geth-tutorial/geth.ipc +``` + +The following welcome message will be displayed in the Javascript console: + +```terminal +Welcome to the Geth JavaScript console! + +instance: Geth/v1.10.15-stable/darwin-amd64/go1.17.5 +at block: 6354736 (Thu Feb 10 2022 14:01:46 GMT+0100 (WAT)) + datadir: /home/go-ethereum/geth-tutorial + modules: admin:1.0 clique:1.0 debug:1.0 eth:1.0 miner:1.0 net:1.0 personal:1.0 rpc:1.0 txpool:1.0 web3:1.0 + +To exit, press ctrl-d or type exit +``` + +The console is now active and connected to Geth. It can now be used to interact with the Ethereum (Goerli) network. + + +### List of accounts + +Earlier in this tutorial, at least one account was created using `geth account new`. The following +command will display the addresses of those two accounts and any others that might have been added +to the keystore before or since. + +```javascript +eth.accounts +``` + +```terminal +["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", "0xce8dba5e4157c2b284d8853afeeea259344c1653"] +``` + + +### Checking account balance. + +Having confirmed that the two addresses created earlier are indeed in the keystore and accessible +through the Javascript console, it is possible to retrieve information about how much ether they +own. The Goerli faucet should have sent 1 ETH to the address provided, meaning that the balance +of one of the accounts should be 1 ether and the other should be 0. The following command displays +the account balance in the console: + +```javascript +web3.fromWei(eth.getBalance("0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC"), "ether") +``` + +There are actually two instructions sent in the above command. The inner one is the `getBalance` +function from the `eth` namespace. This takes the account address as its only argument. By default, +this returns the account balance in units of Wei. There are 1018 Wei to one ether. To +present the result in units of ether, `getBalance` is wrapped in the `fromWei` function from the +`web3` namespace. Running this command should provide the following result (for the account that +received faucet funds): + +```terminal +1 +``` + +Repeating the command for the other new account that was not funded from the faucet should yield: + +```terminal +0 +``` + +### Send ether to another account + +The command `eth.sendTransaction` can be used to send some ether from one address to another. +This command takes three arguments: `from`, `to` and `value`. These define the sender and +recipient addresses (as strings) and the amount of Wei to transfer. It is far less error prone +to enter the transaction value in units of ether rather than Wei, so the value field can take the +return value from the `toWei` function. The following command, run in the Javascript console, +sends 0.1 ether from one of the accounts in the keystore to the other. Note that the addresses +here are examples - the user must replace the address in the `from` field with the address +currently owning 1 ether, and the address in the `to` field with the address currently holding 0 ether. + +```javascript +eth.sendTransaction({ + from: "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", + to: "0xce8dba5e4157c2b284d8853afeeea259344c1653", + value: web3.toWei(0.1, "ether") +}) +``` + +This command will return an error message indicating that `authentication is needed: password or unlock`. +This is a security feature that prevents unauthorized access to sensitive account operations. +There are two ways to unlock the account. The first is to start Geth with the account permanently +unlocked (by passing `--unlock
` at startup). This is not recommended because the account +remains unlocked all the time Geth is running, creating a security weakness. Instead, it is better +to temporarily unlock the account for the specific transaction. This requires using the `sendTransaction` +method from the `personal` namespace instead of the `eth` namespace. The password can be provided as a +string in the method call as follows: + +```sh +personal.sendTransaction({ + from: "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", + to: "0xce8dba5e4157c2b284d8853afeeea259344c1653", + value: web3.toWei(0.1, "ether") +}, "password") +``` + +In the Javascript console, the transaction hash is displayed. This will be used in the next section +to retrieve the transaction details. + +```terminal +"0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb" +``` + +It is also advised to check the account balances using Geth by repeating the instructions from earlier. +At this point in the tutorial, the two accounts in the keystore should have balances just below 0.9 +ether (because 0.1 ether has been transferred out and some small amount paid in transaction gas) and 0.1 ether. + +### Checking the transaction hash + +The transaction hash is a unique identifier for this specific transaction that can be used later to +retrieve the transaction details. For example, the transaction details can be viewed by pasting this +hash into the [Goerli block explorer](https://goerli.etherscan.io/). The same information can also +be retrieved directly from the Geth node. The hash returned in the previous step can be provided as +an argument to `eth.getTransaction` to return the transaction information: + +```javascript +eth.getTransaction("0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb") +``` + +This returns the following response (although the actual values for each field will vary because they +are specific to each transaction): + +```terminal +{ + accessList: [], + blockHash: "0x1c5d3f8dd997b302935391b57dc3e4fffd1fa2088ef2836d51f844f993eb39c4", + blockNumber: 6355150, + chainId: "0x5", + from: "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", + gas: 21000, + gasPrice: 2425000023, + hash: "0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb", + input: "0x", + maxFeePerGas: 2425000057, + maxPriorityFeePerGas: 2424999967, + nonce: 3, + r: "0x66e5d23ad156e04363e68b986d3a09e879f7fe6c84993cef800bc3b7ba8af072", + s: "0x647ff82be943ea4738600c831c4a19879f212eb77e32896c05055174045da1bc", + to: "0xce8dba5e4157c2b284d8853afeeea259344c1653", + transactionIndex: 630, + type: "0x2", + v: "0x0", + value: 10000000000000000 +} +``` + +## Using Curl + +Up to this point this tutorial has interacted with Geth using the convenience library Web3.js. +This library enables the user to send instructions to Geth using a more user-friendly interface +compared to sending raw JSON objects. However, it is also possible for the user to send these JSON +objects directly to Geth's exposed HTTP port. Curl is a command line tool that sends HTTP requests. +This part of the tutorial demonstrates how to check account balances and send a transaction using Curl. +This requires Geth to expose an HTTP port to listen for requests. This can be configured at startup +by passing the `--http` flag. If no other commands are passed with it, `--http` will expose the +default `localhost:8545` port. + +### Checking account balance + +The command below returns the balance of the given account. This is a HTTP POST request to the local +port 8545. The `-H` flag is for header information. It is used here to define the format of the incoming +payload, which is JSON. The `--data` flag defines the content of the payload, which is a JSON object. +That JSON object contains four fields: `jsonrpc` defines the spec version for the JSON-RPC API, `method` +is the specific function being invoked, `params` are the function arguments, and `id` is used for ordering +transactions. The two arguments passed to `eth_getBalance` are the account address whose balance to check +and the block to query (here `latest` is used to check the balance in the most recently mined block). + +```shell +curl -X POST http://127.0.0.1:8545 \ + -H "Content-Type: application/json" \ + --data '{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec","latest"], "id":1}' +``` + +A successful call will return a response like the one below: + +```terminal +{"jsonrpc":"2.0","id":1,"result":"0xc7d54951f87f7c0"} +``` + +The balance is in the `result` field in the returned JSON object. However, it is denominated in Wei and +presented as a hexadecimal string. There are many options for converting this value to a decimal in units +of ether, for example by opening a Python console and running: + +```python +0xc7d54951f87f7c0 / 1e18 +``` +This returns the balance in ether: + +```terminal +0.8999684999998321 +``` + +### Checking the account list + +The curl command below returns the list of all accounts. + +```shell +curl -X POST http://127.0.0.1:8545 \ + -H "Content-Type: application/json" \ + --data '{"jsonrpc":"2.0", "method":"eth_accounts","params":[], "id":1}' +``` + +The following information is returned to the terminal: + +```terminal +{"jsonrpc":"2.0","id":1,"result":["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec"]} +``` + +### Sending Transactions + +It is possible to send transactions using raw curl requests too, but this requires unlocking the sender +account. It is recommended to do this using Clef to manage access to accounts or to use `ipc` instead. The +combination of HTTP and unlocked accounts pose a security risk. + +## Summary + +This tutorial has demonstrated how to generate accounts using Geth's built-in account management tool, +fund them with testnet ether and use those accounts to interact with Ethereum (Goerli) through a Geth +node. Checking account balances, sending transactions and retrieving transaction details were explained using +the web3.js library via the Geth console and using the JSON-RPC directly using Curl. Note that this is an +entry-level tutorial designed to help users get familiar with basic Geth processes, we strongly recommend +following this with the [Geth with Clef](/docs/getting-started/geth_with_clef) tutorial which will help to +adopt more secure account management practices than those outlined here. + + +[cli]: https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line diff --git a/content/docs/install_build/Installing-Geth.md b/content/docs/install_build/Installing-Geth.md deleted file mode 100644 index f82d577cca..0000000000 --- a/content/docs/install_build/Installing-Geth.md +++ /dev/null @@ -1,356 +0,0 @@ ---- -title: Installing Geth -sort_key: A ---- - -There are several ways to install Geth, including via a package manager, downloading a pre-built bundle, running as a docker container or building from downloaded source code. On this page the various installation options are explained for several major operating systems. Users prioritizing ease of installation should choose to use a package manager or prebuilt bundle. Users prioritizing customization should build from source. It is important to run the latest version of Geth because each release includes bugfixes and improvement over the previous versions. The stable releases are recommended for most users because they have been fully tested. A list of stable releases can be found [here][geth-releases]. Instructions for updating existing Geth installations are also provided in each section. - - -{:toc} - -- this will be removed by the toc - -## Package managers - -### MacOS via Homebrew - -The easiest way to install go-ethereum is to use the Geth Homebrew tap. The first step is to check that Homebrew is installed. The following command should return a version number. - -```shell -brew -v -``` - -If a version number is returned, then Homebrew is installed. If not, Homebrew can be installed by following the instructions [here][brew]. With Homebrew installed, the following commands add the Geth tap and install Geth: - - -```shell -brew tap ethereum/ethereum -brew install ethereum -``` - -The previous command installs the latest stable release. Developers that wish to install the most up-to-date version can install the Geth repository's master branch by adding the `--devel` parameter to the install command: - -```shell -brew install ethereum --devel -``` - -These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. - -Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands: - -```shell -brew update -brew upgrade -brew reinstall ethereum -``` - -When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline. - - -### Ubuntu via PPAs - -The easiest way to install Geth on Ubuntu-based distributions is with the built-in launchpad PPAs (Personal Package Archives). A single PPA repository is provided, containing stable and development releases for Ubuntu versions `xenial`, `trusty`, `impish`, `focal`, `bionic`. - -The following command enables the launchpad repository: - -```shell -sudo add-apt-repository -y ppa:ethereum/ethereum -``` - -Then, to install the stable version of go-ethereum: - -```shell -sudo apt-get update -sudo apt-get install ethereum -``` - -Or, alternatively the develop version: - -```shell -sudo apt-get update -sudo apt-get install ethereum-unstable -``` - -These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. - - -Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands: - -```shell -sudo apt-get update -sudo apt-get install ethereum -sudo apt-get upgrade geth -``` - -When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline. - - -### Windows - -The easiest way to install Geth is to download a pre-compiled binary from the [downloads][geth-dl] page. The page provides an installer as well as a zip file containing the Geth source code. The install wizard offers the user the option to install Geth, or Geth and the developer tools. The installer adds `geth` to the system's `PATH` automatically. The zip file contains the command `.exe` files that can be run from the command prompt. The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. - -Updating an existing Geth installation can be achieved by stopping the node, downloading and installing the latest version following the instructions above. When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline. - -### FreeBSD via pkg - -Geth can be installed on FreeBSD using the package manager `pkg`. The following command downloads and installs Geth: - -```shell -pkg install go-ethereum -``` - -These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. - -The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. - - -Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands: - -```shell -pkg upgrade -``` - -When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline. - - -### FreeBSD via ports - -Installing Geth using ports, simply requires navigating to the `net-p2p/go-ethereum` ports directory and running `make install` as root: - -```shell -cd /usr/ports/net-p2p/go-ethereum -make install -``` - -These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. - -The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. - - -Updating an existing Geth installation can be achieved by stopping the node and running the following command: - -```shell -portsnap fetch -``` - -When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline. - -### Arch Linux via pacman - -The Geth package is available from the [community repo][geth-archlinux]. It can be installed by running: - -```shell -pacman -S geth -``` - -These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/bin/`. - -The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. - -Updating an existing Geth installation can be achieved by stopping the node and running the following command: - -```shell -sudo pacman -Sy -``` - -When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline. - -## Standalone bundle - -Stable releases and development builds are provided as standalone bundles. These are useful for users who: a) wish to install a specific version of Geth (e.g., for reproducible environments); b) wish to install on machines without internet access (e.g. air-gapped computers); or c) wish to avoid automatic updates and instead prefer to manually install software. - -The following standalone bundles are available: - -- 32bit, 64bit, ARMv5, ARMv6, ARMv7 and ARM64 archives (`.tar.gz`) on Linux -- 64bit archives (`.tar.gz`) on macOS -- 32bit and 64bit archives (`.zip`) and installers (`.exe`) on Windows - - -Some archives contain only Geth, while other archives containing Geth and the various developer tools (`clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`). More information about these executables is available at the [`README`][geth-readme-exe]. - -The standalone bundles can be downloaded from the [Geth Downloads][geth-dl] page. To update an existing installation, download and manually install the latest version. - -## Docker container - -A Docker image with recent snapshot builds from our `develop` branch is maintained on DockerHub to support users who prefer to run containerized processes. There four different Docker images available for running the latest stable or development versions of Geth. - -- `ethereum/client-go:latest` is the latest development version of Geth (default) -- `ethereum/client-go:stable` is the latest stable version of Geth -- `ethereum/client-go:{version}` is the stable version of Geth at a specific version number -- `ethereum/client-go:release-{version}` is the latest stable version of Geth at a specific version family - -Pulling an image and starting a node is achieved by running these commands: - -```shell -docker pull ethereum/client-go -docker run -it -p 30303:30303 ethereum/client-go -``` - -There are also four different Docker images for running the latest stable or development versions of miscellaneous Ethereum tools. - -- `ethereum/client-go:alltools-latest` is the latest development version of the Ethereum tools -- `ethereum/client-go:alltools-stable` is the latest stable version of the Ethereum tools -- `ethereum/client-go:alltools-{version}` is the stable version of the Ethereum tools at a specific version number -- `ethereum/client-go:alltools-release-{version}` is the latest stable version of the Ethereum tools at a specific version family - -The image has the following ports automatically exposed: - -- `8545` TCP, used by the HTTP based JSON RPC API -- `8546` TCP, used by the WebSocket based JSON RPC API -- `8547` TCP, used by the GraphQL API -- `30303` TCP and UDP, used by the P2P protocol running the network - - -**Note:** if you are running an Ethereum client inside a Docker container, you should mount a data volume as the client's data directory (located at `/root/.ethereum` inside the container) to ensure that downloaded data is preserved between restarts and/or container life-cycles. - - -Updating Geth to the latest version simply requires stopping the container, pulling the latest version from Docker and running it: - -```shell -docker stop ethereum/client-go -docker pull ethereum/client-go:latest -docker run -it -p 30303:30303 ethereum/client-go -``` - -## Build from source code - -### Most Linux systems and macOS - -Geth is written in [Go][go], so building from source code requires the most recent version of Go to be installed. Instructions for installing Go are available at the [Go installation page][go-install] and necessary bundles can be downloaded from the [Go download page][go-dl]. - -With Go installed, Geth can be downloaded into a `GOPATH` workspace via: - - -```shell -go get -d github.com/ethereum/go-ethereum -``` - -You can also install specific versions via: - -```shell -go get -d github.com/ethereum/go-ethereum@v1.9.21 -``` - - -The above commands do not build any executables. To do that you can either build one specifically: - -```shell -go install github.com/ethereum/go-ethereum/cmd/geth -``` - - -Alternatively, the following command, run in the project root directory (`ethereum/go-ethereum`) in the GO workspace, builds the entire project and installs Geth and all the developer tools: - - -```shell -go install ./... -``` - -For macOS users, errors related to macOS header files are usually fixed by installing XCode Command Line Tools with `xcode-select --install`. -Another common error is: `go: cannot use path@version syntax in GOPATH mode`. This and other similar errors can often be fixed by enabling gomodules using `export GO111MODULE=on`. - -Updating an existing Geth installation can be achieved using `go get`: - -```shell -go get -u github.com/ethereum/go-ethereum -``` - - -### Windows - -The Chocolatey package manager provides an easy way to install the required build tools. Chocolatey can be installed by following these [instructions][chocolatey]. Then, to install the build tool the following commands can be run in an Administrator command prompt: - - -``` -C:\Windows\system32> choco install git -C:\Windows\system32> choco install golang -C:\Windows\system32> choco install mingw -``` - -Installing these packages sets up the path environment variables. To get the new path a new command prompt must be opened. To install Geth, a Go workspace directory must first be created, then the Geth source code can be created and built. - -``` -C:\Users\xxx> mkdir src\github.com\ethereum -C:\Users\xxx> git clone https://github.com/ethereum/go-ethereum src\github.com\ethereum\go-ethereum -C:\Users\xxx> cd src\github.com\ethereum\go-ethereum -C:\Users\xxx\src\github.com\ethereum\go-ethereum> go get -u -v golang.org/x/net/context -C:\Users\xxx\src\github.com\ethereum\go-ethereum> go install -v ./cmd/... -``` - -### FreeBSD - -To build Geth from source code on FreeBSD, the Geth Github repository can be cloned into a local directory. - - -```shell -git clone https://github.com/ethereum/go-ethereum -``` - -Then, the Go compiler can be used to build Geth: - -```shell -pkg install go -``` - - -If the Go version currently installed is >= 1.5, Geth can be built using the following command: - -```shell -cd go-ethereum -make geth -``` - -If the installed Go version is < 1.5 (quarterly packages, for example), the following command can be used instead: - -```shell -cd go-ethereum -CC=clang make geth -``` - -To start the node, the followijng command can be run: - -```shell -build/bin/geth -``` - -### Building without a Go workflow - -Geth can also be built without using Go workspaces. In this case, the repository should be cloned to a local repository. Then, the command -`make geth` configures everything for a temporary build and cleans up afterwards. This method of building only works on UNIX-like operating systems, and a Go installation is still required. - -```shell -git clone https://github.com/ethereum/go-ethereum.git -cd go-ethereum -make geth -``` - -These commands create a Geth executable file in the `go-ethereum/build/bin` folder that can be moved and run from another directory if required. The binary is standalone and doesn't require any additional files. - -To update an existing Geth installation simply stop the node, navigate to the project root directory and pull the latest version from the Geth Github repository. then rebuild and restart the node. - -```shell -cd go-ethereum -git pull -make geth -``` - -Additionally all the developer tools provided with Geth (`clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`) can be compiled by running `make all`. More information about these tools can be found [here][geth-readme-exe]. - -Instructions for cross-compiling to another architecture are available in the [cross-compilation guide](./cross-compile). - -To build a stable release, e.g. v1.9.21, the command `git checkout v1.9.21` retrieves that specific version. Executing that command before running `make geth` switches Geth to a stable branch. - - - -[brew]: https://brew.sh/ -[go]: https://golang.org/ -[go-dl]: https://golang.org/dl/ -[go-install]: https://golang.org/doc/install -[chocolatey]: https://chocolatey.org -[geth-releases]: https://github.com/ethereum/go-ethereum/releases -[geth-readme-exe]: https://github.com/ethereum/go-ethereum#executables -[geth-cl-options]: https://geth.ethereum.org/docs/interface/command-line-options -[geth-archlinux]: https://www.archlinux.org/packages/community/x86_64/geth/ -[geth-dl]: ../../downloads/ - - diff --git a/content/docs/install_build/cross-compile.md b/content/docs/install_build/cross-compile.md deleted file mode 100644 index 55af4e6652..0000000000 --- a/content/docs/install_build/cross-compile.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Cross-Compiling Geth -sort_key: C ---- - -**Note: All of these and much more have been merged into the project Makefile. You can -cross build via `make geth--` without needing to know any of these details -from below.** - -Developers usually have a preferred platform that they feel most comfortable working in, -with all the necessary tools, libraries and environments set up for an optimal workflow. -However, there's often need to build for either a different CPU architecture, or an -entirely different operating system; but maintaining a development environment for each -and switching between the them quickly becomes unwieldy. - -Here we present a very simple way to cross compile Ethereum to various operating systems -and architectures using a minimal set of prerequisites and a completely containerized -approach, guaranteeing that your development environment remains clean even after the -complex requirements and mechanisms of a cross compilation. - -The currently supported target platforms are: - - - ARMv7 Android and iOS - - 32 bit, 64 bit and ARMv5 Linux - - 32 bit and 64 bit Mac OSX - - 32 bit and 64 bit Windows - -Please note, that cross compilation does not replace a release build. Although resulting -binaries can usually run perfectly on the desired platform, compiling on a native system -with the specialized tools provided by the official vendor can often result in more a -finely optimized code. - -## Cross compilation environment - -Although the `go-ethereum` project is written in Go, it does include a bit of C code -shared between all implementations to ensure that all perform equally well, including a -dependency to the GNU Multiple Precision Arithmetic Library. Because of these, Go cannot -by itself compile to a different platform than the host. To overcome this limitation, we -will use [`xgo`](https://github.com/karalabe/xgo), a Go cross compiler package based on -Docker containers that has been architected specifically to allow both embedded C snippets -as well as simpler external C dependencies during compilation. - -The `xgo` project has two simple dependencies: Docker (to ensure that the build -environment is completely contained) and Go. On most platforms these should be available -from the official package repositories. For manually installing them, please consult their -install guides at [Docker](https://docs.docker.com/installation/) and -[Go](https://golang.org/doc/install) respectively. This guide assumes that these two -dependencies are met. - -To install and/or update xgo, simply type: - - $ go get -u github.com/karalabe/xgo - -You can test whether `xgo` is functioning correctly by requesting it to cross -compile itself and verifying that all cross compilations succeeded or not. - - $ xgo github.com/karalabe/xgo - ... - - $ ls -al - -rwxr-xr-x 1 root root 2792436 Sep 14 16:45 xgo-android-21-arm - -rwxr-xr-x 1 root root 2353212 Sep 14 16:45 xgo-darwin-386 - -rwxr-xr-x 1 root root 2906128 Sep 14 16:45 xgo-darwin-amd64 - -rwxr-xr-x 1 root root 2388288 Sep 14 16:45 xgo-linux-386 - -rwxr-xr-x 1 root root 2960560 Sep 14 16:45 xgo-linux-amd64 - -rwxr-xr-x 1 root root 2437864 Sep 14 16:45 xgo-linux-arm - -rwxr-xr-x 1 root root 2551808 Sep 14 16:45 xgo-windows-386.exe - -rwxr-xr-x 1 root root 3130368 Sep 14 16:45 xgo-windows-amd64.exe - - -## Building Ethereum - -Cross compiling Ethereum is analogous to the above example, but an additional flags is -required to satisfy the dependencies: - - - `--deps` is used to inject arbitrary C dependency packages and pre-build them - -Injecting the GNU Arithmetic Library dependency and selecting `geth` would be: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - github.com/ethereum/go-ethereum/cmd/geth - ... - - $ ls -al - -rwxr-xr-x 1 root root 23213372 Sep 14 17:59 geth-android-21-arm - -rwxr-xr-x 1 root root 14373980 Sep 14 17:59 geth-darwin-386 - -rwxr-xr-x 1 root root 17373676 Sep 14 17:59 geth-darwin-amd64 - -rwxr-xr-x 1 root root 21098910 Sep 14 17:59 geth-linux-386 - -rwxr-xr-x 1 root root 25049693 Sep 14 17:59 geth-linux-amd64 - -rwxr-xr-x 1 root root 20578535 Sep 14 17:59 geth-linux-arm - -rwxr-xr-x 1 root root 16351260 Sep 14 17:59 geth-windows-386.exe - -rwxr-xr-x 1 root root 19418071 Sep 14 17:59 geth-windows-amd64.exe - - -As the cross compiler needs to build all the dependencies as well as the main project -itself for each platform, it may take a while for the build to complete (approximately 3-4 -minutes on a Core i7 3770K machine). - -### Fine tuning the build - -By default Go, and inherently `xgo`, checks out and tries to build the master branch of a -source repository. However, more often than not, you'll probably want to build a different -branch from possibly an entirely different remote repository. These can be controlled via -the `--remote` and `--branch` flags. - -To build the `develop` branch of the official `go-ethereum` repository instead of the -default `master` branch, you just need to specify it as an additional command line flag -(`--branch`): - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --branch=develop \ - github.com/ethereum/go-ethereum/cmd/geth - -Additionally, during development you will most probably want to not only build a custom -branch, but also one originating from your own fork of the repository instead of the -upstream one. This can be done via the `--remote` flag: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --remote=https://github.com/karalabe/go-ethereum \ - --branch=rpi-staging \ - github.com/ethereum/go-ethereum/cmd/geth - -By default `xgo` builds binaries for all supported platforms and architectures, with -Android binaries defaulting to the highest released Android NDK platform. To limit the -build targets or compile to a different Android platform, use the `--targets` CLI -parameter. - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --targets=android-16/arm,windows/* \ - github.com/ethereum/go-ethereum/cmd/geth - -### Building locally - -If you would like to cross compile your local development version, simply specify a local -path (starting with `.` or `/`), and `xgo` will use all local code from `GOPATH`, only -downloading missing dependencies. In such a case of course, the `--branch`, `--remote` and -`--pkg` arguments are no-op: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - ./cmd/geth - -## Using the Makefile - -Having understood the gist of `xgo` based cross compilation, you do not need to actually -memorize and maintain these commands, as they have been incorporated into the official -[Makefile](https://github.com/ethereum/go-ethereum/blob/master/Makefile) and can be -invoked with a trivial `make` request: - - * `make geth-cross`: Cross compiles to every supported OS and architecture - * `make geth-`: Cross compiles supported architectures of a particular OS (e.g. `linux`) - * `make geth--`: Cross compiles to a specific OS/architecture (e.g. `linux`, `arm`) - -We advise using the `make` based commands opposed to manually invoking `xgo` as we do -maintain the Makefile actively whereas we cannot guarantee that this document will be -always readily updated to latest advancements. - -### Tuning the cross builds - -A few of the `xgo` build options have also been surfaced directly into the Makefile to -allow fine tuning builds to work around either upstream Go issues, or to enable some -fancier mechanics. - - - `make ... GO=`: Use a specific Go runtime (e.g. `1.5.1`, `1.5-develop`, `develop`) - - `make ... MODE=`: Build a specific target type (e.g. `exe`, `c-archive`). - -Please note that these are not yet fully finalized, so they may or may not change in the -future as our code and the Go runtime features change.