lukechilds
/
electrumx
mirror of https://github.com/lukechilds/electrumx.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Improve documentation of the RPC interface

patch-2
Neil Booth 7 years ago
parent
c26227413e
commit
96b5c5ed4a
4 changed files with 208 additions and 191 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 2
      docs/PEER_DISCOVERY.rst
  2. 190
      docs/RPC-INTERFACE.rst
  3. 2
      docs/index.rst
  4. 205
      docs/rpc-interface.rst

2
docs/PEER_DISCOVERY.rst
View File

@ -1,3 +1,5 @@
.. _Peer Discovery:
Peer Discovery Peer Discovery
============== ==============

190
docs/RPC-INTERFACE.rst
View File

@ -1,190 +0,0 @@
RPC Interface
=============
You can query the status of a running server, and affect its behaviour
by sending JSON RPC commands to the LocalRPC port it is listening on.
This is best done using the electrumx_rpc.py script provided.
The general form of invocation is:
``electrumx_rpc.py [-p PORT] <command> [arg1 [arg2...]``
The port to send the commands to can be specified on the command line,
otherwise it is taken from the environment variable **RPC_PORT**, or
8000 is used if that is not set.
The following commands are available:
* **stop**
Flush all cached data to disk and shut down the server cleanly, as
if sending the KILL signal. Be patient - during initial sync
flushing all cached data to disk can take several minutes. This
command takes no arguments.
* **getinfo**
Returns a summary of server state. This command takes no arguments.
A typical result is as follows (with annotated comments):
.. code::
$ electrumx_rpc.py getinfo
{
"closing": 1, # The number of sessions being closed down
"daemon_height": 446231, # The daemon's height when last queried
"db_height": 446231, # The height to which the DB is processed
"errors": 1, # Errors across current sessions
"groups": 2, # The number of session groups
"logged": 0, # The number of sessions being logged
"paused": 0, # The number of paused sessions.
"peers": 62, # Number of peer servers
"pid": 126275, # The server's process ID
"requests": 0, # Number of unprocessed requests
"sessions": 85, # Number of current sessions (connections)
"subs": 6235, # Number of current address subscriptions
"txs_sent": 2 # Total transactions sent by ElectrumX
}
Clients that are slow to consume data sent to them are *paused*
until their socket buffer drains sufficiently, at which point
processing of requests resumes.
Each ill-formed request, or one that does not follow the Electrum
protocol, increments the error count of the session that sent it.
If the error count reaches a certain level (currently 10) that
client is disconnected.
Apart from very short intervals, typically after a new block or when
a client has just connected, the number of unprocessed requests
should normally be zero.
Sessions are put into groups, primarily as an anti-DoS measure.
Initially all connections made within a period of time are put in
the same group. High bandwidth usage by a member of a group
deprioritizes that session, and all members of its group to a lesser
extent. Low-priority sessions have their requests served after
higher priority sessions. ElectrumX will start delaying responses
to a session if it becomes sufficiently deprioritized.
* **sessions**
Returns a list of all current sessions. Takes no arguments.
.. code::
$ electrumx_rpc.py sessions
ID Flags Client Reqs Txs Subs Recv Recv KB Sent Sent KB Time Peer
0 S1 2.7.12 0 0 293 352 34 355 35 0:49:27 192.168.0.1:4093
1 T1 2.5.2 0 0 87 141 12 144 13 0:49:25 xxx.xx.xx.x:39272
2 T1 all_seeing_eye 0 0 0 10 0 13 2 0:49:25 xxx.xx.xxx.xx:57862
3 S1 all_seeing_eye 0 0 0 10 0 13 2 0:49:25 xxx.xx.xxx.xx:41315
4 S1 2.6.4 0 0 2,048 2,104 215 2,108 122 0:49:25 xxx.xx.xxx.xx:35287
...
435 R0 RPC 0 0 0 1 0 0 0 0:00:00 [::1]:1484
The columns show the session ID, flags (see below), how the client
identifies itself - typically the Electrum client version, the
number of unprocessed requests, the number of transactions sent, the
number of address subscriptions, the number of requests received and
the bandwidth used, the number of messages sent and the bandwidth
used, how long the client has been connected, and the client's IP
address.
The flags are:
* S an SSL connection
* T a TCP connection
* R a local RPC connection
* L a logged session
* C a connection that is being closed
* the non-negative number is the connection priority, with lower
numbers having higher priority. RPC connections have priority
0, normal connections have priority at least 1.
* **groups**
Returns a list of all current groups. Takes no arguments.
The output is quite similar to the **sessions** command.
* **disconnect**
Disconnects the given session IDs. Session IDs can be seen in the
logs or with the **sessions** RPC command.
.. code::
$ ./electrumx_rpc.py disconnect 2 3
[
"disconnected 2",
"disconnected 3"
]
ElectrumX initiates the socket close process for the passed
sessions. Whilst most connections close quickly, it can take
several minutes for Python to shut some SSL connections down.
* **log**
Toggles logging of the given session IDs. All incoming requests for
a logged session are written to the server log. Session IDs can be
seen in the logs or with the **sessions** RPC command.
.. code::
$ electrumx_rpc.py log 0 1 2 3 4 5
[
"log 0: False",
"log 1: False",
"log 2: False",
"log 3: True",
"log 4: True",
"unknown session: 5"
]
The return value shows this command turned off logging for sesssions
0, 1 and 2. It was turned on for sessions 3 and 4, and there was no
session 5.
* **peers**
Returns a list of peer electrum servers. This command takes no arguments.
Peer data is obtained via a peer discovery protocol documented in
`docs/PEER_DISCOVERY.rst`_.
* **add_peer**
Add a peer to the peers list. ElectrumX will schdule an immediate
connection attempt. This command takes a single argument: the
peer's "real name" as it used to advertise itself on IRC.
.. code::
$ ./electrumx_rpc.py add_peer "ecdsa.net v1.0 s110 t"
"peer 'ecdsa.net v1.0 s110 t' added"
* **daemon_url**
This command takes an optional argument that is interpreted
identically to the **DAEMON_URL** environment variable. If omitted,
the default argument value is the process's **DAEMON_URL**
environment variable.
This command replaces the daemon's URL at run-time, and also
forecefully rotates to the first URL in the list.
For example, in case ElectrumX has previously failed over to a
secondary daemon and you want to revert to the primary having
resolved the connectivity issue, invoking this command without an
argument will have that effect.
* **reorg**
Force a block chain reorg. This command takes an optional
argument - the number of blocks to reorg - which defaults to 3.
.. _docs/PEER_DISCOVERY.rst: https://github.com/kyuupichan/electrumx/blob/master/docs/PEER_DISCOVERY.rst

2
docs/index.rst
View File

@ -55,7 +55,7 @@ Documentation
ENVIRONMENT ENVIRONMENT
PROTOCOL PROTOCOL
PEER_DISCOVERY PEER_DISCOVERY
RPC-INTERFACE rpc-interface
ARCHITECTURE ARCHITECTURE
authors authors

205
docs/rpc-interface.rst
View File

@ -0,0 +1,205 @@
RPC Interface
=============
You can query the status of a running server, and affect its behaviour
by sending **JSON RPC** commands to the LocalRPC port it is listening
on. This is best done using the :file:`electrumx_rpc.py` script
provided.
The general form of invocation is::
electrumx_rpc.py [-p PORT] <command> [arg1 [arg2...]
The port to send the commands to can be specified on the command line,
otherwise the environment variable :envvar:`RPC_PORT` is used, and if
that is not set then **8000** is assumed.
The following commands are available:
add_peer
--------
Add a peer to the peers list. ElectrumX will schdule an immediate
connection attempt. This command takes a single argument: the peer's
"real name" as it used to advertise itself on IRC::
$ ./electrumx_rpc.py add_peer "ecdsa.net v1.0 s110 t"
"peer 'ecdsa.net v1.0 s110 t' added"
daemon_url
----------
This command takes an optional argument that is interpreted
identically to the :envvar:`DAEMON_URL` environment variable. If
omitted, the default argument value is the process's existing
:envvar:`DAEMON_URL` environment variable.
This command replaces the daemon's URL at run-time, and also
forecefully rotates to the first URL in the list.
For example, in case ElectrumX has previously failed over to a
secondary daemon and you want to revert to the primary having resolved
the connectivity issue, invoking this command without an argument will
have that effect.
disconnect
----------
Disconnect the given session IDs. Session IDs can be seen in the logs
or with the `sessions`_ RPC command::
$ ./electrumx_rpc.py disconnect 2 3
[
"disconnected 2",
"disconnected 3"
]
ElectrumX initiates the socket close process for the passed sessions.
Whilst most connections close quickly, it can take several minutes for
Python to shut some SSL connections down.
getinfo
-------
Return a summary of server state. This command takes no arguments.
A typical result is as follows (with annotated comments)::
$ electrumx_rpc.py getinfo
{
"closing": 1, # The number of sessions being closed down
"daemon": "192.168.0.2:8332/", # The daemon URL without auth info
"daemon_height": 520527, # The daemon's height when last queried
"db_height": 520527, # The height to which the DB is flushed
"errors": 0, # Errors across current sessions
"groups": 7, # The number of session groups
"logged": 0, # The number of sessions being logged
"paused": 0, # The number of paused sessions
"peers": { # Various categories of server peers
# as determined by :ref:`Peer Discovery`
"bad": 0, # Not responding or invalid height etc.
"good": 28, # Responding with good data
"never": 0, # Never managed to connect
"stale": 0, # Was "good" but not recently connected
"total": 28 # Sum of the above
},
"pid": 85861, # Server's process ID
"requests": 0, # Unprocessed requests across all sessions
"sessions": 43, # Total number of sessions
"subs": 84, # Script hash subscriptions across all sessions
"txs_sent": 4, # Transactions sent since server started
"uptime": "06h 48m 00s" # Time since server started
}
Each ill-formed request, or one that does not follow the Electrum
protocol, increments the error count of the session that sent it. If
the error count reaches a certain level (currently ``10``) that client
is disconnected.
:ref:`logging <session logging>` of sessions can be enabled by RPC.
Clients that are slow to consume data sent to them are :dfn:`paused`
until their socket buffer drains sufficiently, at which point
processing of requests resumes.
Apart from very short intervals, typically after a new block or when
a client has just connected, the number of unprocessed requests
should normally be zero.
Sessions are put into groups, primarily as an anti-DoS measure.
Initially all connections made within a period of time are put in the
same group. High bandwidth usage by a member of a group deprioritizes
that session, and all members of its group to a lesser extent.
Low-priority sessions have their requests served after higher priority
sessions. ElectrumX will start delaying responses to a session if it
becomes sufficiently deprioritized.
groups
------
Return a list of all current session groups. Takes no arguments.
The output is quite similar to the `sessions`_ command.
log
---
Toggle logging of the given session IDs. All incoming requests for a
logged session are written to the server log. Session IDs can be seen
in the logs or with the `sessions`_ RPC command::
$ electrumx_rpc.py log 0 1 2 3 4 5
[
"log 0: False",
"log 1: False",
"log 2: False",
"log 3: True",
"log 4: True",
"unknown session: 5"
]
The return value shows this command turned off logging for sesssions
0, 1 and 2. It was turned on for sessions 3 and 4, and there was no
session 5.
peers
-----
Return a list of peer Electrum servers serving the same coin network.
This command takes no arguments.
Peer data is obtained via a peer discovery protocol documented
:ref:`here <Peer Discovery>`.
reorg
-----
Force a block chain reorganisation, primarily for debugging purposes.
This command takes an optional argument - the number of blocks to
reorg - which defaults to 3.
That number of blocks will be backed up - using undo information
stored in ElectrumX's database - and then ElectrumX will move forwards
on the daemon's main chain to its current height.
sessions
--------
Return a list of all current sessions. Takes no arguments::
ID Flags Client Proto Reqs Txs Subs Recv Recv KB Sent Sent KB Time Peer
110 S1 2.9.4 0.10 0 0 0 403 28 442 37 06h41m41s xxx.xxx.xxx.xxx:xx
282 S1 3.1.5 1.1 0 0 0 380 25 417 40 06h21m38s xxx.xxx.xxx.xxx:xx
300 S1 2.9.4 0.10 0 0 0 381 25 418 34 06h19m35s xxx.xxx.xxx.xxx:xx
[...]
3313 S1 2.9.3 0.10 0 0 0 22 1 22 6 07s xxx.xxx.xxx.xxx:xx
4 R0 RPC RPC 0 0 0 1 0 0 0 00s [::1]:62479
The columns show information by session: the session ID, flags (see
below), how the client identifies itself - typically the Electrum
client version, the protocol version negotiated, the number of
unprocessed requests, the number of transactions sent, the number of
address subscriptions, the number of requests received and their total
size, the number of messages sent and their size, how long the client
has been connected, and the client's IP address (if anonymous logging
is disabled).
The flags are:
* ``S`` an SSL connection
* ``T`` a TCP connection
* ``R`` a local RPC connection
* ``L`` a logged session
* ``C`` a connection that is being closed
* the non-negative number is the connection "cost", with lower
numbers having higher priority. RPC connections have cost ``0``,
normal connections have cost at least ``1``.
stop
----
Flush all cached data to disk and shut down the server cleanly, as if
sending the `KILL` signal. Be patient - during initial sync flushing
all cached data to disk can take several minutes. This command takes
no arguments.
.. _session logging:
Write Preview
Loading…
Cancel
Save