mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-25 14:15:50 +00:00
Migrate content syntax via script
The changes in this commit were auto-generated by running tool/migrate.sh Following this commit, the Dactyl build no longer works but the Redocly build (mostly) should.
This commit is contained in:
mDuo13
@@ -8,11 +8,11 @@ labels:
|
||||
# Health Check
|
||||
[[Source]](https://github.com/XRPLF/rippled/blob/de0c52738785de8bf837f9124da65c7905e7bb5a/src/ripple/overlay/impl/OverlayImpl.cpp#L1084-L1168 "Source")
|
||||
|
||||
The Health Check is a special [peer port method](peer-port-methods.html) for reporting on the health of an individual `rippled` server. This method is intended for use in automated monitoring to recognize outages and prompt automated or manual interventions such as restarting the server. [New in: rippled 1.6.0][]
|
||||
The Health Check is a special [peer port method](index.md) for reporting on the health of an individual `rippled` server. This method is intended for use in automated monitoring to recognize outages and prompt automated or manual interventions such as restarting the server. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.6.0" %}New in: rippled 1.6.0{% /badge %}
|
||||
|
||||
This method checks several metrics to see if they are in ranges generally considered healthy. If all metrics are in normal ranges, this method reports that the server is healthy. If any metric is outside normal ranges, this method reports that the server is unhealthy and reports the metric(s) that are unhealthy. Since some metrics may rapidly fluctuate into and out of unhealthy ranges, you should not raise alerts unless the health check fails multiple times in a row.
|
||||
|
||||
**Note:** Since the health check is a [peer port method](peer-port-methods.html), it is not available when testing the server in [stand-alone mode][].
|
||||
**Note:** Since the health check is a [peer port method](index.md), it is not available when testing the server in [stand-alone mode][].
|
||||
|
||||
|
||||
## Request Format
|
||||
@@ -30,10 +30,9 @@ To request the Health Check information, make the following HTTP request:
|
||||
|
||||
## Example Response
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
|
||||
*Healthy*
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Healthy" %}
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
Server: rippled-1.6.0-b8
|
||||
@@ -45,9 +44,9 @@ Transfer-Encoding: chunked
|
||||
"info": {}
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
*Warning*
|
||||
|
||||
{% tab label="Warning" %}
|
||||
```json
|
||||
HTTP/1.1 503 Service Unavailable
|
||||
Server: rippled-1.6.0
|
||||
@@ -62,9 +61,9 @@ Transfer-Encoding: chunked
|
||||
}
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
*Critical*
|
||||
|
||||
{% tab label="Critical" %}
|
||||
```json
|
||||
HTTP/1.1 500 Internal Server Error
|
||||
Server: rippled-1.6.0
|
||||
@@ -80,8 +79,9 @@ Transfer-Encoding: chunked
|
||||
}
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
{% /tabs %}
|
||||
|
||||
## Response Format
|
||||
|
||||
@@ -99,18 +99,14 @@ The `info` object may contain the following fields:
|
||||
|
||||
| `Field` | Value | Description |
|
||||
|:--------------------|:--------|:---------------------------------------------|
|
||||
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, the server is [amendment blocked](amendments.html#amendment-blocked-servers) and must be upgraded to remain synced with the network; this state is critical. If the server is not amendment blocked, this field is omitted. |
|
||||
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, the server is [amendment blocked](../../../concepts/networks-and-servers/amendments.md#amendment-blocked-servers) and must be upgraded to remain synced with the network; this state is critical. If the server is not amendment blocked, this field is omitted. |
|
||||
| `load_factor` | Number | _(May be omitted)_ A measure of the overall load the server is under. This reflects I/O, CPU, and memory limitations. This is a warning if the load factor is over 100, or critical if the load factor is 1000 or higher. |
|
||||
| `peers` | Number | _(May be omitted)_ The number of [peer servers](peer-protocol.html) this server is connected to. This is a warning if connected to 7 or fewer peers, and critical if connected to zero peers. |
|
||||
| `server_state` | String | _(May be omitted)_ The current [server state](rippled-server-states.html). This is a warning if the server is in the `tracking`, `syncing`, or `connected` states. This is critical if the server is in the `disconnected` state. |
|
||||
| `validated_ledger` | Number | _(May be omitted)_ The number of seconds since the last time a ledger was validated by [consensus](consensus.html). If there is no validated ledger available ([as during the initial sync period when starting the server](server-doesnt-sync.html#normal-syncing-behavior)), this is the value `-1` and is considered a warning. This metric is also a warning if the last validated ledger was at least 7 seconds ago, or critical if the last validated ledger was at least 20 seconds ago. |
|
||||
| `peers` | Number | _(May be omitted)_ The number of [peer servers](../../../concepts/networks-and-servers/peer-protocol.md) this server is connected to. This is a warning if connected to 7 or fewer peers, and critical if connected to zero peers. |
|
||||
| `server_state` | String | _(May be omitted)_ The current [server state](../api-conventions/rippled-server-states.md). This is a warning if the server is in the `tracking`, `syncing`, or `connected` states. This is critical if the server is in the `disconnected` state. |
|
||||
| `validated_ledger` | Number | _(May be omitted)_ The number of seconds since the last time a ledger was validated by [consensus](../../../concepts/consensus-protocol/index.md). If there is no validated ledger available ([as during the initial sync period when starting the server](../../../infrastructure/troubleshooting/server-doesnt-sync.md#normal-syncing-behavior)), this is the value `-1` and is considered a warning. This metric is also a warning if the last validated ledger was at least 7 seconds ago, or critical if the last validated ledger was at least 20 seconds ago. |
|
||||
|
||||
## See Also
|
||||
|
||||
For guidance interpreting the results of the health check, see [Health Check Interventions](health-check-interventions.html).
|
||||
For guidance interpreting the results of the health check, see [Health Check Interventions](../../../infrastructure/troubleshooting/health-check-interventions.md).
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
{% raw-partial file="/_snippets/common-links.md" /%}
|
||||
|
||||
@@ -1,11 +1,15 @@
|
||||
---
|
||||
html: peer-port-methods.html
|
||||
parent: http-websocket-apis.html
|
||||
template: pagetype-category.html.jinja
|
||||
metadata:
|
||||
indexPage: true
|
||||
blurb: Special API methods for sharing network topology and status metrics, served on the XRPL Peer Protocol port.
|
||||
---
|
||||
# Peer Port Methods
|
||||
|
||||
Separate from the [WebSocket / HTTP APIs](http-websocket-apis.html), `rippled` servers provide a few special API methods from the same port they use for XRP Ledger [peer protocol](peer-protocol.html) communications. These methods provide status information about the server itself and its connectivity to the peer-to-peer network, and are intended mainly for monitoring and administration.
|
||||
Separate from the [WebSocket / HTTP APIs](../index.md), `rippled` servers provide a few special API methods from the same port they use for XRP Ledger [peer protocol](../../../concepts/networks-and-servers/peer-protocol.md) communications. These methods provide status information about the server itself and its connectivity to the peer-to-peer network, and are intended mainly for monitoring and administration.
|
||||
|
||||
**Security:** Most `rippled` servers use a self-signed TLS certificate to respond to peer port requests. 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, or configure the server with a TLS certificate signed by a known Certificate Authority.
|
||||
**Security:** Most `rippled` servers use a self-signed TLS certificate to respond to peer port requests. 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, or configure the server with a TLS certificate signed by a known Certificate Authority.
|
||||
|
||||
|
||||
{% child-pages /%}
|
||||
|
||||
@@ -8,7 +8,7 @@ labels:
|
||||
---
|
||||
# Peer Crawler
|
||||
|
||||
The Peer Crawler is a special [peer port method](peer-port-methods.html) for reporting on the health and topology of the peer-to-peer network. This API method is available by default on a non-privileged basis through the [Peer Protocol](peer-protocol.html) port, which is also used for `rippled` servers' peer-to-peer communications about consensus, ledger history, and other necessary information.
|
||||
The Peer Crawler is a special [peer port method](index.md) for reporting on the health and topology of the peer-to-peer network. This API method is available by default on a non-privileged basis through the [Peer Protocol](../../../concepts/networks-and-servers/peer-protocol.md) port, which is also used for `rippled` servers' peer-to-peer communications about consensus, ledger history, and other necessary information.
|
||||
|
||||
The information reported by the peer crawler is effectively public, and can be used to report on the overall XRP Ledger network, its health, and topology.
|
||||
|
||||
@@ -34,18 +34,18 @@ The JSON object has the following fields:
|
||||
|:-----------------|:-------|:-------------------------------------------------|
|
||||
| `counts` | Object | _(May be omitted)_ Stats about this server's health, similar to the response from the [get_counts method][]. The default configuration does not report this field. Information reported includes: how large the ledger and transaction databases are, the cache hit rate for the in-application caches, and how many objects of various types are cached in memory. Types of objects that may be stored in memory include ledgers (`Ledger`), transactions (`STTx`), validation messages (`STValidation`), and more. |
|
||||
| `overlay` | Object | _(May be omitted)_ Information about the peer servers currently connected to this one, similar to the response from the [peers method][]. Contains one field, `active`, which is an array of objects (see below). |
|
||||
| `server` | Object | _(May be omitted)_ Information about this server. Contains public fields from the [server_state method][], including what `rippled` version you are running (`build_version`), which [ledger versions](ledger-history.html) your server has available (`complete_ledgers`), and the amount of load your server is experiencing. [Updated in: rippled 1.2.1][] |
|
||||
| `unl` | Object | _(May be omitted)_ Information about the validators and validator list sites this server is configured to trust, similar to the response from the [validators method][] and [validator_list_sites method][]. [Updated in: rippled 1.2.1][] |
|
||||
| `version` | Number | Indicates the version of this peer crawler response format. The current peer crawler version number is `2`. [Updated in: rippled 1.2.1][] |
|
||||
| `server` | Object | _(May be omitted)_ Information about this server. Contains public fields from the [server_state method][], including what `rippled` version you are running (`build_version`), which [ledger versions](../../../concepts/networks-and-servers/ledger-history.md) your server has available (`complete_ledgers`), and the amount of load your server is experiencing. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.2.1" %}Updated in: rippled 1.2.1{% /badge %} |
|
||||
| `unl` | Object | _(May be omitted)_ Information about the validators and validator list sites this server is configured to trust, similar to the response from the [validators method][] and [validator_list_sites method][]. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.2.1" %}Updated in: rippled 1.2.1{% /badge %} |
|
||||
| `version` | Number | Indicates the version of this peer crawler response format. The current peer crawler version number is `2`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.2.1" %}Updated in: rippled 1.2.1{% /badge %} |
|
||||
|
||||
Each member of the `overlay.active` array is an object with the following fields:
|
||||
|
||||
| `Field` | Value | Description |
|
||||
|:-------------|:-------------------------|:-----------------------------------|
|
||||
| `complete_ledgers` | String | The range of [ledger versions](ledger-history.html) this peer has available. |
|
||||
| `complete_shards` | String | _(May be omitted)_ The range of [ledger history shards](history-sharding.html) this peer has available. |
|
||||
| `ip` | String (IPv4 Address) | _(May be omitted)_ The IP address of this connected peer. Omitted if the peer is configured as a validator or a [private peer](peer-protocol.html#private-peers). [Updated in: rippled 1.2.1][] |
|
||||
| `port` | String (Number) | _(May be omitted)_ The port number on the peer server that serves RTXP. Typically `51235`. Omitted if the peer is configured as a validator or a [private peer](peer-protocol.html#private-peers). [Updated in: rippled 1.2.1][] |
|
||||
| `complete_ledgers` | String | The range of [ledger versions](../../../concepts/networks-and-servers/ledger-history.md) this peer has available. |
|
||||
| `complete_shards` | String | _(May be omitted)_ The range of [ledger history shards](../../../infrastructure/configuration/data-retention/history-sharding.md) this peer has available. |
|
||||
| `ip` | String (IPv4 Address) | _(May be omitted)_ The IP address of this connected peer. Omitted if the peer is configured as a validator or a [private peer](../../../concepts/networks-and-servers/peer-protocol.md#private-peers). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.2.1" %}Updated in: rippled 1.2.1{% /badge %} |
|
||||
| `port` | String (Number) | _(May be omitted)_ The port number on the peer server that serves RTXP. Typically `51235`. Omitted if the peer is configured as a validator or a [private peer](../../../concepts/networks-and-servers/peer-protocol.md#private-peers). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.2.1" %}Updated in: rippled 1.2.1{% /badge %} |
|
||||
| `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 by the peer server's [server_info method][].) |
|
||||
| `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 connected to this peer. |
|
||||
@@ -55,39 +55,31 @@ Each member of the `overlay.active` array is an object with the following fields
|
||||
|
||||
Request:
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
|
||||
*HTTP*
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="HTTP" %}
|
||||
```
|
||||
GET https://localhost:51235/crawl
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
*cURL*
|
||||
|
||||
{% tab label="cURL" %}
|
||||
```
|
||||
curl --insecure https://localhost:51235/crawl
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
{% /tabs %}
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
200 OK
|
||||
|
||||
{% include '_api-examples/peer-crawler/crawl.json' %}
|
||||
```
|
||||
{% code-snippet file="/_api-examples/peer-crawler/crawl.json" language="json" prefix="200 OK\n\n" /%}
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- [Peer Protocol](peer-protocol.html)
|
||||
- [Configure the Peer Crawler](configure-the-peer-crawler.html)
|
||||
- [Peer Protocol](../../../concepts/networks-and-servers/peer-protocol.md)
|
||||
- [Configure the Peer Crawler](../../../infrastructure/configuration/peering/configure-the-peer-crawler.md)
|
||||
- [Validator History Service](https://github.com/ripple/validator-history-service) is an example of a service that uses the peer crawler for ingesting, aggregating, storing, and disbursing validation related data.
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
{% raw-partial file="/_snippets/common-links.md" /%}
|
||||
|
||||
@@ -8,9 +8,9 @@ labels:
|
||||
---
|
||||
# Validator List Method
|
||||
|
||||
The validator list method is a special API endpoint that fetches a current, trusted validator list a `rippled` server is using. This often represents the exact list of validators a server trusts. [New in: rippled 1.5.0][]
|
||||
The validator list method is a special API endpoint that fetches a current, trusted validator list a `rippled` server is using. This often represents the exact list of validators a server trusts. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}New in: rippled 1.5.0{% /badge %}
|
||||
|
||||
Like the [Peer Crawler](peer-crawler.html), the validator list method is available by default on a non-privileged basis through the [Peer Protocol](peer-protocol.html) port, which is also used for `rippled` servers' peer-to-peer communications.
|
||||
Like the [Peer Crawler](peer-crawler.md), the validator list method is available by default on a non-privileged basis through the [Peer Protocol](../../../concepts/networks-and-servers/peer-protocol.md) port, which is also used for `rippled` servers' peer-to-peer communications.
|
||||
|
||||
## Request Format
|
||||
|
||||
@@ -41,14 +41,14 @@ The JSON object has the following fields:
|
||||
| `blob` | String | Base64-encoded JSON data representing the validator list. |
|
||||
| `signature` | String | The signature of the `blob` data, in hexadecimal. |
|
||||
| `version` | Number | The version of the validator list protocol this object uses. The current version is **1**. A higher version number indicates backwards-incompatible changes with a previous version of the validator list protocol. |
|
||||
| `public_key` | String | The public key used to verify this validator list data, in hexadecimal. This is a 32-byte Ed25519 public key prefixed with the byte `0xED`. [New in: rippled 1.7.0][] |
|
||||
| `public_key` | String | The public key used to verify this validator list data, in hexadecimal. This is a 32-byte Ed25519 public key prefixed with the byte `0xED`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.7.0" %}New in: rippled 1.7.0{% /badge %} |
|
||||
|
||||
### Manifest Data
|
||||
[[Source]](https://github.com/XRPLF/rippled/blob/97712107b71a8e2089d2e3fcef9ebf5362951110/src/ripple/app/misc/impl/Manifest.cpp#L43-L66 "Source")
|
||||
|
||||
A "manifest" contains information uniquely identifying a person or organization involved in the consensus process, either a **validator** or a **list publisher**. A validator's manifest contains the _public_ information from that [validator's token](run-rippled-as-a-validator.html#3-enable-validation-on-your-rippled-server). A list publisher's manifest provides information about the list publisher. Both are typically encoded to binary in the XRP Ledger's standard [binary serialization format](serialization.html). (There is no standard JSON representation of a manifest.)
|
||||
A "manifest" contains information uniquely identifying a person or organization involved in the consensus process, either a **validator** or a **list publisher**. A validator's manifest contains the _public_ information from that [validator's token](../../../infrastructure/configuration/server-modes/run-rippled-as-a-validator.md#3-enable-validation-on-your-rippled-server). A list publisher's manifest provides information about the list publisher. Both are typically encoded to binary in the XRP Ledger's standard [binary serialization format](../../protocol/binary-format.md). (There is no standard JSON representation of a manifest.)
|
||||
|
||||
One of the main purposes of manifests relates to rotating validator keys. When a validator changes its ephemeral key pair, the validator publishes a new manifest to share its new ephemeral public key, using the validator's master key pair to sign the manifest to prove its authenticity. A validator uses its ephemeral key pair to sign validations as part of the [consensus process](consensus.html) and uses its master key pair only to sign new manifests. (The manifest is incorporated into a validator token, alongside private data, that [the validator administrator adds to the `rippled.cfg` config file](run-rippled-as-a-validator.html#3-enable-validation-on-your-rippled-server).)
|
||||
One of the main purposes of manifests relates to rotating validator keys. When a validator changes its ephemeral key pair, the validator publishes a new manifest to share its new ephemeral public key, using the validator's master key pair to sign the manifest to prove its authenticity. A validator uses its ephemeral key pair to sign validations as part of the [consensus process](../../../concepts/consensus-protocol/index.md) and uses its master key pair only to sign new manifests. (The manifest is incorporated into a validator token, alongside private data, that [the validator administrator adds to the `rippled.cfg` config file](../../../infrastructure/configuration/server-modes/run-rippled-as-a-validator.md#3-enable-validation-on-your-rippled-server).)
|
||||
|
||||
The data encoded in a manifest is as follows:
|
||||
|
||||
@@ -62,7 +62,7 @@ The data encoded in a manifest is as follows:
|
||||
| `sfSigningPubKey` | Blob | _(Optional)_ The ephemeral public key of the key pair that this person or organization is currently using. This must be a 33-byte secp256k1 public key. |
|
||||
| `sfSignature` | Blob | _(Optional)_ A signature of this manifest data from the ephemeral key pair. |
|
||||
|
||||
The `sfMasterSignature` and `sfSignature` signatures are created from signing the [serialized](serialization.html) binary data of the manifest, excluding the signature fields (`sfMasterSignature` and `sfSignature`) themselves.
|
||||
The `sfMasterSignature` and `sfSignature` signatures are created from signing the [serialized](../../protocol/binary-format.md) binary data of the manifest, excluding the signature fields (`sfMasterSignature` and `sfSignature`) themselves.
|
||||
|
||||
|
||||
### Blob Data
|
||||
@@ -85,45 +85,36 @@ Each member of the `validators` array has the following fields:
|
||||
|
||||
#### Example Decoded Blob
|
||||
|
||||
```json
|
||||
{% include '_api-examples/vl/vl-blob.json' %}
|
||||
```
|
||||
{% code-snippet file="/_api-examples/vl/vl-blob.json" language="json" /%}
|
||||
|
||||
## Example
|
||||
|
||||
Request:
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
|
||||
*HTTP*
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="HTTP" %}
|
||||
```
|
||||
GET https://localhost:51235/vl/ED2677ABFFD1B33AC6FBC3062B71F1E8397C1505E1C42C64D11AD1B28FF73F4734
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
*cURL*
|
||||
|
||||
{% tab label="cURL" %}
|
||||
```
|
||||
curl --insecure https://localhost:51235/vl/ED2677ABFFD1B33AC6FBC3062B71F1E8397C1505E1C42C64D11AD1B28FF73F4734
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
{% /tabs %}
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
200 OK
|
||||
|
||||
{% include '_api-examples/vl/vl.json' %}
|
||||
```
|
||||
{% code-snippet file="/_api-examples/vl/vl.json" language="json" prefix="200 OK\n\n" /%}
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- [Peer Protocol](peer-protocol.html)
|
||||
- [Consensus](consensus.html)
|
||||
- [Peer Protocol](../../../concepts/networks-and-servers/peer-protocol.md)
|
||||
- [Consensus](../../../concepts/consensus-protocol/index.md)
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
{% raw-partial file="/_snippets/common-links.md" /%}
|
||||
|
||||
Reference in New Issue
Block a user