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
GitHub
parent
09d03493b9
commit
f7b51243ce
|
|
@ -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
|
||||
```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.
|
||||
|
||||
You can configure the location of the socket using the `--ipcpath` flag. IPC can
|
||||
be disabled using the `--ipcdisable` flag.
|
||||
|
||||
[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
|
||||
|
|
|
|||
Loading…
Reference in New Issue