ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-17 10:15:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'crawl_command'

Browse Source
This commit is contained in:
mDuo13
2016-06-02 09:57:49 -07:00
parent 30fc1c3e8d b47ce67f7e
commit f2dd31d28f
2 changed files with 367 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
content/reference-rippled.md
View File

@@ -7,7 +7,9 @@ The core peer-to-peer server that manages the Ripple Consensus Ledger (RCL) is c
* [Transaction Reference](reference-transaction-format.html)
* JavaScript Client Library - [RippleAPI](reference-rippleapi.html)
# WebSocket and JSON-RPC APIs #
If you want to communicate directly with a `rippled` server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Alternatively, you can use [RippleAPI](reference-rippleapi.html), which is a simplified JavaScript client library, which communicates directly with a `rippled` server from [Node.js](http://nodejs.org/) or a web browser.
* The WebSocket API uses the [WebSocket protocol](http://www.html5rocks.com/en/tutorials/websockets/basics/), available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The `rippled` server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both.
@@ -24,7 +26,7 @@ The WebSocket and JSON-RPC APIs are still in development, and are subject to cha
## Connecting to rippled ##
Before you can run any commands against a `rippled` server, you must know which server you are connecting to. Most servers are configured not to accept requests directly from the outside network.
Before you can run any commands against a `rippled` server, you must know which server you are connecting to. Most servers are configured not to accept API requests directly from the outside network.
Alternatively, you can [run your own local copy of `rippled`](tutorial-rippled-setup.html). This is required if you want to access any of the [Admin Commands](#list-of-admin-commands). In this case, you should use whatever IP and port you configured the server to bind. (For example, `127.0.0.1:54321`) Additionally, to access admin functionality, you must connect from a port/IP address marked as admin in the config file.
@@ -11116,6 +11118,182 @@ The response follows the [standard format](#response-formatting), with a success
* Any of the [universal error types](#universal-errors).
# Peer Protocol #
Servers in the Ripple Consensus Ledger communicate to each other using the Ripple peer protocol, also known as RTXP. Peer servers connect via HTTPS and then perform an [HTTP upgrade](https://tools.ietf.org/html/rfc7230#section-6.7) to RTXP. (For more information, see the [Overlay Network](https://github.com/ripple/rippled/blob/906ef761bab95f80b0a7e0cab3b4c594b226cf57/src/ripple/overlay/README.md#handshake) article in the [`rippled` repository](https://github.com/ripple/rippled).)
## Configuring the Peer Protocol ##
In order to participate in the Ripple Consensus Ledger, `rippled` servers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted, unless they are [clustered](tutorial-rippled-setup.html#clustering) with the current server.)
Ideally, the server should be able to send _and_ receive connections on the peer port. You should forward the port used for the peer protocol through your firewall to the `rippled` server. The [default `rippled` configuration file](https://github.com/ripple/rippled/blob/develop/doc/rippled-example.cfg) listens for incoming peer protocol connections on port 51235 on all network interfaces. You can change the port used by editing the appropriate stanza in your `rippled.cfg` file.
Example:
```
[port_peer]
port = 51235
ip = 0.0.0.0
protocol = peer
```
## Peer Crawler ##
The Peer Crawler asks a `rippled` server to report information about the other `rippled` servers it is connected to as peers. The [`peers` command](#peers) in the [WebSocket and JSON-RPC APIs](#websocket-and-json-rpc-apis) also returns a similar, more comprehensive set of information, but requires [administrative access](#connecting-to-rippled) to the server. The Peer Crawler response is available to other servers on a non-privileged basis through the Peer Protocol (RTXP) port.
#### Request Format ####
To request the Peer Crawler information, make the following HTTP request:
* **Protocol:** https
* **HTTP Method:** GET
* **Host:** (any `rippled` server, by hostname or IP address)
* **Port:** (port number where the `rippled` server uses the Peer Protocol, typically 51235)
* **Path:** `/crawl`
* **Notes:** Most `rippled` servers use a self-signed certificate to respond to the request. By default, most tools (including web browsers) flag or block such responses for being untrusted. You must ignore the certificate checking (for example, if using cURL, add the `--insecure` flag) to display a response from those servers.
#### Response Format ####
The response has the status code **200 OK** and a JSON object in the message body.
The JSON object has the following fields:
| Field | Value | Description |
|----------------|--------|-------------|
| `overlay.active` | Array | Array of Peer Objects, where each member is a peer that is connected to this server. |
Each member of the `active` array is a Peer Object with the following fields:
| Field | Value | Description |
|-------------|--------|-------------|
| `ip` | String (IPv4 Address) | The IP address of this connected peer. |
| `port` | String (Number) | The port number on the peer server that serves RTXP. Typically 51235. |
| `public_key` | String (Base-64 Encoded) | The public key of the ECDSA key pair used by this peer to sign RTXP messages. (This is the same data as the `pubkey_node` reported in the peer server's [`server_info` command](#server-info).) |
| `type` | String | The value `in` or `out`, indicating whether the TCP connection to the peer is incoming or outgoing. |
| `uptime` | Number | The number of seconds the server has been has been connected to this peer. |
| `version` | String | The `rippled` version number the peer reports to be using. |
#### Example ####
Request:
<!-- MULTICODE_BLOCK_START -->
*HTTP*
```
GET https://s1.ripple.com:51235/crawl
```
*cURL*
```
curl -k https://s1.ripple.com:51235/crawl
```
<!-- MULTICODE_BLOCK_END -->
Response:
```json
200 OK
{
"overlay": {
"active": [{
"ip": "208.43.252.243",
"port": "51235",
"public_key": "A2GayQNaj7qbqLFiCFW2UXtAnEPghP/KWVqix2gUa6dM",
"type": "out",
"uptime": 107926,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "184.172.237.226",
"port": "51235",
"public_key": "Asv/wKq/dqMWbP2M4eR+QvkuojYMLRXhKhIPnW40bsaF",
"type": "out",
"uptime": 247376,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "54.186.73.52",
"port": "51235",
"public_key": "AjikFnq0P2XybCyREr2KPiqXqJteqwPwVRVbVK+93+3o",
"type": "out",
"uptime": 328776,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "169.53.155.59",
"port": "51235",
"public_key": "AyIcVhAhOGnP0vtfCt+HKUrx9B2fDvP/4XUkOtVQ37g/",
"type": "out",
"uptime": 328776,
"version": "rippled-0.31.1"
}, {
"ip": "169.53.155.44",
"port": "51235",
"public_key": "AuVZszWXgMgM8YuTVhQsGE9OciEeBD8aMVe1mFid3n63",
"type": "out",
"uptime": 328776,
"version": "rippled-0.32.0-b12"
}, {
"ip": "184.173.45.39",
"port": "51235",
"public_key": "Ao2GbGbp2QYQ2B4S9ckCtON7CsZdXqdK5Yon4x7qmWFm",
"type": "out",
"uptime": 63336,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "169.53.155.34",
"port": "51235",
"public_key": "A3inNJsIQzO7z7SS7uB9DyvN0wsiS9it/RGY/kNx6KEG",
"type": "out",
"uptime": 328776,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "169.53.155.45",
"port": "51235",
"public_key": "AglUUjwXTC2kUlK41WjDs2eAVN0SnlMpzYA9lEgB0UGP",
"type": "out",
"uptime": 65443,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "99.110.49.91",
"port": "51301",
"public_key": "AuQDH0o+4fpl2n+pR5U0Y4FTj0oGr4iEKe0MObPcSYj9",
"type": "out",
"uptime": 328776,
"version": "rippled-0.32.0-b9"
}, {
"ip": "169.53.155.36",
"port": "51235",
"public_key": "AsR4xub7MLg2Zl5Fwd/n7dTz7mhbBoSyCc/v9bnubrVy",
"type": "out",
"uptime": 328776,
"version": "rippled-0.31.0-rc1"
}]
}
}
```
### Concealing Peer Information ###
You can use the `[peer_private]` stanza of the `rippled` config file to request that peer servers do not report your IP address in the Peer Crawler response. You cannot force peers you do not control to follow this request, if they run custom software. However, you can use this to hide the IP addresses of `rippled` servers you control that _only_ connect to peers you control (using `[ips_fixed]` and a firewall). This can help to protect important [validating servers](tutorial-rippled-setup.html#types-of-rippled-servers).
Example:
```
# Configuration on a private server that only connects through
# a second rippled server at IP address 10.1.10.55
[ips_fixed]
10.1.10.55
[peer_private]
1
```
<!---- rippled release notes links ---->
[version 0.26.0]: https://github.com/ripple/rippled/releases/tag/0.26.0
[version 0.26.1]: https://github.com/ripple/rippled/releases/tag/0.26.1

189
reference-rippled.html
View File

@@ -229,6 +229,10 @@
<li class="level-2"><a href="#json">json</a></li>
<li class="level-2"><a href="#connect">connect</a></li>
<li class="level-2"><a href="#stop">stop</a></li>
<li class="level-1"><a href="#peer-protocol">Peer Protocol</a></li>
<li class="level-2"><a href="#configuring-the-peer-protocol">Configuring the Peer Protocol</a></li>
<li class="level-2"><a href="#peer-crawler">Peer Crawler</a></li>
<li class="level-3"><a href="#concealing-peer-information">Concealing Peer Information</a></li>
</ul>
</div>
@@ -256,7 +260,7 @@
<p>The WebSocket and JSON-RPC APIs are still in development, and are subject to change. If you want to be notified of upcoming changes and future versions of <code>rippled</code>, subscribe to the Ripple Server mailing list:</p>
<p><a href="https://groups.google.com/forum/#!forum/ripple-server">https://groups.google.com/forum/#!forum/ripple-server</a></p>
<h2 id="connecting-to-rippled">Connecting to rippled</h2>
<p>Before you can run any commands against a <code>rippled</code> server, you must know which server you are connecting to. Most servers are configured not to accept requests directly from the outside network.</p>
<p>Before you can run any commands against a <code>rippled</code> server, you must know which server you are connecting to. Most servers are configured not to accept API requests directly from the outside network.</p>
<p>Alternatively, you can <a href="tutorial-rippled-setup.html">run your own local copy of <code>rippled</code></a>. This is required if you want to access any of the <a href="#list-of-admin-commands">Admin Commands</a>. In this case, you should use whatever IP and port you configured the server to bind. (For example, <code>127.0.0.1:54321</code>) Additionally, to access admin functionality, you must connect from a port/IP address marked as admin in the config file.</p>
<p>The <a href="https://github.com/ripple/rippled/blob/d7def5509d8338b1e46c0adf309b5912e5168af0/doc/rippled-example.cfg#L831-L854">example config file</a> listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.</p>
<h3 id="websocket-api">WebSocket API</h3>
@@ -12771,6 +12775,189 @@ Connecting to 127.0.0.1:5005
<ul>
<li>Any of the <a href="#universal-errors">universal error types</a>.</li>
</ul>
<h1 id="peer-protocol">Peer Protocol</h1>
<p>Servers in the Ripple Consensus Ledger communicate to each other using the Ripple peer protocol, also known as RTXP. Peer servers connect via HTTPS and then perform an <a href="https://tools.ietf.org/html/rfc7230#section-6.7">HTTP upgrade</a> to RTXP. (For more information, see the <a href="https://github.com/ripple/rippled/blob/906ef761bab95f80b0a7e0cab3b4c594b226cf57/src/ripple/overlay/README.md#handshake">Overlay Network</a> article in the <a href="https://github.com/ripple/rippled"><code>rippled</code> repository</a>.)</p>
<h2 id="configuring-the-peer-protocol">Configuring the Peer Protocol</h2>
<p>In order to participate in the Ripple Consensus Ledger, <code>rippled</code> servers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted, unless they are <a href="tutorial-rippled-setup.html#clustering">clustered</a> with the current server.)</p>
<p>Ideally, the server should be able to send <em>and</em> receive connections on the peer port. You should forward the port used for the peer protocol through your firewall to the <code>rippled</code> server. The <a href="https://github.com/ripple/rippled/blob/develop/doc/rippled-example.cfg">default <code>rippled</code> configuration file</a> listens for incoming peer protocol connections on port 51235 on all network interfaces. You can change the port used by editing the appropriate stanza in your <code>rippled.cfg</code> file.</p>
<p>Example:</p>
<pre><code>[port_peer]
port = 51235
ip = 0.0.0.0
protocol = peer
</code></pre>
<h2 id="peer-crawler">Peer Crawler</h2>
<p>The Peer Crawler asks a <code>rippled</code> server to report information about the other <code>rippled</code> servers it is connected to as peers. The <a href="#peers"><code>peers</code> command</a> in the <a href="#websocket-and-json-rpc-apis">WebSocket and JSON-RPC APIs</a> also returns a similar, more comprehensive set of information, but requires <a href="#connecting-to-rippled">administrative access</a> to the server. The Peer Crawler response is available to other servers on a non-privileged basis through the Peer Protocol (RTXP) port.</p>
<h4 id="request-format-51">Request Format</h4>
<p>To request the Peer Crawler information, make the following HTTP request:</p>
<ul>
<li><strong>Protocol:</strong> https</li>
<li><strong>HTTP Method:</strong> GET</li>
<li><strong>Host:</strong> (any <code>rippled</code> server, by hostname or IP address)</li>
<li><strong>Port:</strong> (port number where the <code>rippled</code> server uses the Peer Protocol, typically 51235)</li>
<li><strong>Path:</strong> <code>/crawl</code></li>
<li><strong>Notes:</strong> Most <code>rippled</code> servers use a self-signed certificate to respond to the request. By default, most tools (including web browsers) flag or block such responses for being untrusted. You must ignore the certificate checking (for example, if using cURL, add the <code>--insecure</code> flag) to display a response from those servers.</li>
</ul>
<h4 id="response-format-49">Response Format</h4>
<p>The response has the status code <strong>200 OK</strong> and a JSON object in the message body.</p>
<p>The JSON object has the following fields:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>overlay.active</code></td>
<td>Array</td>
<td>Array of Peer Objects, where each member is a peer that is connected to this server.</td>
</tr>
</tbody>
</table>
<p>Each member of the <code>active</code> array is a Peer Object with the following fields:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>ip</code></td>
<td>String (IPv4 Address)</td>
<td>The IP address of this connected peer.</td>
</tr>
<tr>
<td><code>port</code></td>
<td>String (Number)</td>
<td>The port number on the peer server that serves RTXP. Typically 51235.</td>
</tr>
<tr>
<td><code>public_key</code></td>
<td>String (Base-64 Encoded)</td>
<td>The public key of the ECDSA key pair used by this peer to sign RTXP messages. (This is the same data as the <code>pubkey_node</code> reported in the peer server's <a href="#server-info"><code>server_info</code> command</a>.)</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>The value <code>in</code> or <code>out</code>, indicating whether the TCP connection to the peer is incoming or outgoing.</td>
</tr>
<tr>
<td><code>uptime</code></td>
<td>Number</td>
<td>The number of seconds the server has been has been connected to this peer.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>The <code>rippled</code> version number the peer reports to be using.</td>
</tr>
</tbody>
</table>
<h4 id="example">Example</h4>
<p>Request:</p>
<div class="multicode" id="code-101"><ul class="codetabs"><li><a href="#code-101-0">HTTP</a></li><li><a href="#code-101-1">cURL</a></li></ul>
<div class="code_sample" id="code-101-0" style="position: static;"><pre><code>GET https://s1.ripple.com:51235/crawl
</code></pre></div>
<div class="code_sample" id="code-101-1" style="position: static;"><pre><code>curl -k https://s1.ripple.com:51235/crawl
</code></pre></div>
</div>
<p>Response:</p>
<pre><code class="json">200 OK
{
"overlay": {
"active": [{
"ip": "208.43.252.243",
"port": "51235",
"public_key": "A2GayQNaj7qbqLFiCFW2UXtAnEPghP/KWVqix2gUa6dM",
"type": "out",
"uptime": 107926,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "184.172.237.226",
"port": "51235",
"public_key": "Asv/wKq/dqMWbP2M4eR+QvkuojYMLRXhKhIPnW40bsaF",
"type": "out",
"uptime": 247376,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "54.186.73.52",
"port": "51235",
"public_key": "AjikFnq0P2XybCyREr2KPiqXqJteqwPwVRVbVK+93+3o",
"type": "out",
"uptime": 328776,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "169.53.155.59",
"port": "51235",
"public_key": "AyIcVhAhOGnP0vtfCt+HKUrx9B2fDvP/4XUkOtVQ37g/",
"type": "out",
"uptime": 328776,
"version": "rippled-0.31.1"
}, {
"ip": "169.53.155.44",
"port": "51235",
"public_key": "AuVZszWXgMgM8YuTVhQsGE9OciEeBD8aMVe1mFid3n63",
"type": "out",
"uptime": 328776,
"version": "rippled-0.32.0-b12"
}, {
"ip": "184.173.45.39",
"port": "51235",
"public_key": "Ao2GbGbp2QYQ2B4S9ckCtON7CsZdXqdK5Yon4x7qmWFm",
"type": "out",
"uptime": 63336,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "169.53.155.34",
"port": "51235",
"public_key": "A3inNJsIQzO7z7SS7uB9DyvN0wsiS9it/RGY/kNx6KEG",
"type": "out",
"uptime": 328776,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "169.53.155.45",
"port": "51235",
"public_key": "AglUUjwXTC2kUlK41WjDs2eAVN0SnlMpzYA9lEgB0UGP",
"type": "out",
"uptime": 65443,
"version": "rippled-0.31.0-rc1"
}, {
"ip": "99.110.49.91",
"port": "51301",
"public_key": "AuQDH0o+4fpl2n+pR5U0Y4FTj0oGr4iEKe0MObPcSYj9",
"type": "out",
"uptime": 328776,
"version": "rippled-0.32.0-b9"
}, {
"ip": "169.53.155.36",
"port": "51235",
"public_key": "AsR4xub7MLg2Zl5Fwd/n7dTz7mhbBoSyCc/v9bnubrVy",
"type": "out",
"uptime": 328776,
"version": "rippled-0.31.0-rc1"
}]
}
}
</code></pre>
<h3 id="concealing-peer-information">Concealing Peer Information</h3>
<p>You can use the <code>[peer_private]</code> stanza of the <code>rippled</code> config file to request that peer servers do not report your IP address in the Peer Crawler response. You cannot force peers you do not control to follow this request, if they run custom software. However, you can use this to hide the IP addresses of <code>rippled</code> servers you control that <em>only</em> connect to peers you control (using <code>[ips_fixed]</code> and a firewall). This can help to protect important <a href="tutorial-rippled-setup.html#types-of-rippled-servers">validating servers</a>.</p>
<p>Example:</p>
<pre><code># Configuration on a private server that only connects through
# a second rippled server at IP address 10.1.10.55
[ips_fixed]
10.1.10.55
[peer_private]
1
</code></pre>
<!---- rippled release notes links ---->
</div>
</main>