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 <itz.s1na@gmail.com>
This commit is contained in:
Joseph Cook 2022-07-18 15:44:45 +01:00 committed by GitHub
parent 09d03493b9
commit f7b51243ce
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 132 additions and 39 deletions

View File

@ -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