From f7b51243ce9425bb0a520ae194e2a232dfd53d3a Mon Sep 17 00:00:00 2001 From: Joseph Cook <33655003+jmcook1186@users.noreply.github.com> Date: Mon, 18 Jul 2022 15:44:45 +0100 Subject: [PATCH] docs: update RPC server page to describe transport protocols (#25292) Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> Co-authored-by: Sina Mahmoodi --- docs/_rpc/server.md | 171 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 132 insertions(+), 39 deletions(-) diff --git a/docs/_rpc/server.md b/docs/_rpc/server.md index 9918f7093b..5021a7b8d7 100644 --- a/docs/_rpc/server.md +++ b/docs/_rpc/server.md @@ -3,8 +3,17 @@ title: JSON-RPC Server sort_key: A --- -Geth supports all standard web3 JSON-RPC APIs. You can find documentation for -these APIs on the [Ethereum Wiki JSON-RPC page][web3-rpc]. +Interacting with Geth requires sending requests to specific JSON-RPC API +methods. Geth supports all standard [JSON-RPC API][web3-rpc] endpoints. +The RPC requests must be sent to the node and the response returned to the client +using some transport protocol. This page outlines the available transport protocols +in Geth, providing the information users require to choose a transport protocol for +a specific user scenario. + +{:toc} +- this will be removed by the toc + +## Introduction JSON-RPC is provided on multiple transports. Geth supports JSON-RPC over HTTP, WebSocket and Unix Domain Sockets. Transports must be enabled through @@ -18,72 +27,156 @@ For example, the `eth_call` method resides in the `eth` namespace. Access to RPC methods can be enabled on a per-namespace basis. Find documentation for individual namespaces in the sidebar. +## Transports + +There are three transport protocols available in Geth: IPC, HTTP and Websockets. + ### HTTP Server -To enable the HTTP server, use the `--http` flag. +[HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP) is a unidirectional transport protocol +that connects a client and server. The client sends a request to the server, and the server +returns a response back to the client. An HTTP connection is closed after the response for a given +request is sent. - geth --http +HTTP is supported in every browser as well as almost all programming toolchains. Due to its ubiquity +it has become the most widely used transport for interacting with Geth. To start a HTTP server in Geth, include the `--http` flag: -By default, geth accepts connections from the loopback interface (127.0.0.1). -The default listening port is 8545. You can customize address and port using the -`--http.port` and `--http.addr` flags. +```sh +geth --http +``` - geth --http --http.port 3334 +If no other commands are provided, Geth falls back to its default behaviour of accepting connections +from the local loopback interface (127.0.0.1). The default listening port is 8545. The ip address and +listening port can be customized using the `--http.addr` and `--http.port` flags: -JSON-RPC method namespaces must be whitelisted in order to be available through -the HTTP server. An RPC error with error code `-32602` is generated if you call a -namespace that isn't whitelisted. The default whitelist allows access to the "eth", "net" -and "web3" namespaces. To overwrite the default whitelist and enable access to other APIs -like account management ("personal") and debugging ("debug"), they must be configured via the -`--http.api` flag. We do not recommend enabling such APIs over HTTP, however, -since access to these methods increases the attack surface. +```sh +geth --http --http.port 3334 +``` - geth --http --http.api personal,eth,net,web3 +Not all of the JSON-RPC method namespaces are enabled for HTTP requests by default. +Instead, they have to be whitelisted explicitly when Geth is started. Calling non-whitelisted +RPC namespaces returns an RPC error with code `-32602`. -Since the HTTP server is reachable from any local application, additional -protection is built into the server to prevent misuse of the API from web pages. -If you want enable access to the API from a web page, you must configure the -server to accept Cross-Origin requests with the `--http.corsdomain` flag. +The default whitelist allows access to the `eth`, `net` and `web3` namespaces. To enable access +to other APIs like account management (`personal`) and debugging (`debug`), they must be configured +using the `--http.api` flag. Enabling these APIs over HTTP is **not recommended** because access +to these methods increases the attack surface. -Example: if you want to use [Remix][remix] with geth, allow requests from the -remix domain. +```sh +geth --http --http.api personal,eth,net,web3 +``` - geth --http --http.corsdomain https://remix.ethereum.org +Since the HTTP server is reachable from any local application, additional protection is built into +the server to prevent misuse of the API from web pages. To enable access to the API from a web page +(for example to use the online IDE, [Remix](https://remix.ethereum.org)), the server needs to be +configured to accept Cross-Origin requests. This is achieved using the `--http.corsdomain` flag. -Use `--http.corsdomain '*'` to enable access from any origin. +```sh +geth --http --http.corsdomain https://remix.ethereum.org +``` + +The `--http.corsdomain` command also acceptsd wildcards that enable access to the RPC from any +origin: + +```sh +--http.corsdomain '*' +``` ### WebSocket Server -Configuration of the WebSocket endpoint is similar to the HTTP transport. To -enable WebSocket access, use `--ws` flag. The default WebSocket port is 8546. +Websocket is a bidirectional transport protocol. A Websocket connection is maintained by client and server +until it is explicitly terminated by one. Most modern browsers support Websocket which means +it has good tooling. + +Because Websocket is bidirectional, servers can push events to clients. That makes Websocket a good +choice for use-cases involving [event subscription](https://geth.ethereum.org/docs/rpc/pubsub). Another +benefit of Websocket is that after the handshake procedure, the overhead of individual messages is low, +making it good for sending high number of requests. + +Configuration of the WebSocket endpoint in Geth follows the same pattern as the HTTP transport. +WebSocket access can be enabled using the `--ws` flag. If no additional information is provided, +Geth falls back to its default behaviour which is to establish the Websocket on port 8546. The `--ws.addr`, `--ws.port` and `--ws.api` flags can be used to customize settings -for the WebSocket server. +for the WebSocket server. For example, to start Geth with a Websocket connection for RPC using +the custom port 3334 and whitelisting the `eth`, `net` and `web3` namespaces: - geth --ws --ws.port 3334 --ws.api eth,net,web3 +```sh +geth --ws --ws.port 3334 --ws.api eth,net,web3 +``` -Cross-Origin request protection also applies to the WebSocket server. Use the -`--ws.origins` flag to allow access to the server from web pages: +Cross-Origin request protection also applies to the WebSocket server. The +`--ws.origins` flag can be used to allow access to the server from web pages: - geth --ws --ws.origins http://myapp.example.com +```sh +geth --ws --ws.origins http://myapp.example.com +``` + +As with `--http.corsdomain`, using the wildcard `--ws.origins '*'` allows access from any origin. + +{% include note.html content=" By default, **account unlocking is forbidden when HTTP or +Websocket access is enabled** (i.e. by passing `--http` or `ws` flag). This is because an +attacker that manages to access the node via the externally-exposed HTTP/WS port can then +control the unlocked account. It is possible to force account unlock by including the +`--allow-insecure-unlock` flag but this is unsafe and **not recommended** except for expert +users that completely understand how it can be used safely. +This is not a hypothetical risk: **there are bots that continually scan for http-enabled +Ethereum nodes to attack**" %} -As with `--http.corsdomain`, using `--ws.origins '*'` allows access from any origin. ### IPC Server -JSON-RPC APIs are also provided on a UNIX domain socket. This server is enabled -by default and has access to all JSON-RPC namespaces. +IPC is normally available for use in local environments where the node and the console +exist on the same machine. Geth creates a pipe in the computers local file system +(at `ipcpath`) that configures a connection between node and console. The `geth.ipc` file can +also be used by other processes on the same machine to interact with Geth. + +On UNIX-based systems (Linux, OSX) the IPC is a UNIX domain socket. On Windows IPC is +provided using named pipes. The IPC server is enabled by default and has access to all +JSON-RPC namespaces. The listening socket is placed into the data directory by default. On Linux and macOS, the default location of the geth socket is - ~/.ethereum/geth.ipc +```sh +~/.ethereum/geth.ipc +``` On Windows, IPC is provided via named pipes. The default location of the geth pipe is: - \\.\pipe\geth.ipc - -You can configure the location of the socket using the `--ipcpath` flag. IPC can -be disabled using the `--ipcdisable` flag. +```sh +\\.\pipe\geth.ipc +``` + +The location of the socket can be customized using the `--ipcpath` flag. IPC can be disabled +using the `--ipcdisable` flag. + +## Choosing a transport protocol + +The following table summarizes the relative strengths and weaknesses of each transport +protocol so that users can make informed decisions about which to use. + +| | HTTP | WS | IPC | +| :----------------------------------:|:-----------:|:--------:|:-------:| +| Event subscription | N | **Y** | **Y** | +| Remote connection | **Y** | **Y** | N | +| Per-message metadata overhead | high | low | low | + +As a general rule IPC is most secure because it is limited to interactions on the +local machine and cannot be exposed to external traffic. It can also be used +to subscribe to events. HTTP is a familiar and idempotent transport that closes +connections between requests and can therefore have lower overall overheads if the number +of requests is fairly low. Websockets provides a continuous open channel that can enable +event subscriptions and streaming and handle large volumes of requests with smaller per-message +overheads. + + +## Summary + +RPC requests to a Geth node can be made using three different transport protocols. The +protocols are enabled at startup using their respective flags. The right choice of transport +protocol depends on the specific use case. + [web3-rpc]: https://github.com/ethereum/execution-apis [remix]: https://remix.ethereum.org +[rpc]: https://www.ibm.com/docs/en/aix/7.1?topic=concepts-remote-procedure-call