From 333231e8a55ebe62905d95e61261faf348ee630c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Thu, 15 Feb 2024 13:14:27 +0100 Subject: [PATCH] docs: Add gRPC proxy chapter --- docs/node/README.mdx | 6 +- docs/node/grpc.mdx | 296 ++++++++++++++++++ .../copy-state-from-one-node-to-the-other.md | 2 +- .../advanced/sync-node-using-state-sync.md | 2 +- docs/node/run-your-node/archive-node.md | 2 +- docs/node/run-your-node/ias-proxy.md | 2 +- .../run-your-node/keymanager-node/README.md | 2 +- ...lidator-node.md => non-validator-node.mdx} | 6 + .../run-your-node/paratime-client-node.mdx | 4 +- docs/node/run-your-node/paratime-node.mdx | 4 +- .../prerequisites/hardware-recommendations.md | 2 +- docs/node/run-your-node/validator-node.mdx | 15 +- docs/node/{web3.md => web3.mdx} | 10 + sidebarNode.ts | 5 + 14 files changed, 340 insertions(+), 18 deletions(-) create mode 100644 docs/node/grpc.mdx rename docs/node/run-your-node/{non-validator-node.md => non-validator-node.mdx} (94%) rename docs/node/{web3.md => web3.mdx} (97%) diff --git a/docs/node/README.mdx b/docs/node/README.mdx index 8180918aee..cdd44385e0 100644 --- a/docs/node/README.mdx +++ b/docs/node/README.mdx @@ -67,7 +67,7 @@ to use. [trusted execution environment (TEE)]: ./run-your-node/prerequisites/set-up-trusted-execution-environment-tee.md [Run a ParaTime node]: ./run-your-node/paratime-node.mdx [ParaTime client node]: ./run-your-node/paratime-node.mdx -[Non-validator node]: ./run-your-node/non-validator-node.md +[Non-validator node]: ./run-your-node/non-validator-node.mdx ## Quick Navigation @@ -76,6 +76,8 @@ to use. findSidebarItem('/node/testnet/'), findSidebarItem('/node/run-your-node/prerequisites'), findSidebarItem('/node/run-your-node/validator-node'), - findSidebarItem('/node/run-your-node/non-validator-node'), + findSidebarItem('/node/run-your-node/paratime-node'), + findSidebarItem('/node/run-your-node/paratime-client-node'), findSidebarItem('/node/web3'), + findSidebarItem('/node/grpc'), ]} /> diff --git a/docs/node/grpc.mdx b/docs/node/grpc.mdx new file mode 100644 index 0000000000..72cd601f6f --- /dev/null +++ b/docs/node/grpc.mdx @@ -0,0 +1,296 @@ +--- +description: gRPC proxy for Oasis node +--- + +import DocCardList from '@theme/DocCardList'; +import {findSidebarItem} from '@site/src/sidebarUtils'; + +# gRPC proxy for your Oasis node + +The Oasis node API is exposed via the [gRPC protocol]. It enables communication +with external applications such as the Oasis CLI, dApps running in your browser +that need to perform actions on the consensus layer or a ParaTime, services for +monitoring and controlling your node and similar. + +:::tip Web3 gateway + +The Oasis gRPC **is not related to the standardized Web3 JSON-RPC API**. For +EVM-compatible dApps configure a [Web3 gateway] instead which is also compatible +with other Ethereum tooling. + +::: + +The gRPC proxy may perform the following: + +- makes gRPC available to in-browser applications via gRPC-Web, +- filters out control methods such as shutting down your node, +- authentication, +- load balances the traffic to multiple Oasis nodes. + +This chapter will show you how to set up a **public** gRPC endpoint using Envoy +so that it exposes only a **safe subset of the [Oasis RPC services]**. The +final section presents an alternative approach to communicate with your node by +**securely tunnelling the Unix socket over the network**, so it can safely be +used by the client, but **does not filter out any services**. + +:::danger Never expose the UNIX socket directly! + +The `oasis-node` deliberately exposes the RPC interface only via an AF_LOCAL +socket called `internal.sock` located in the node's data directory. +This socket should **never be directly exposed over the network** as it has no +authentication and allows full control—including shutting down your node. + +::: + +[gRPC protocol]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/oasis-node/rpc.md +[Web3 gateway]: web3.mdx +[Oasis RPC services]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/oasis-node/rpc.md#services + +## gRPC Proxy with Envoy {#envoy} + +Let's set up a typical public Oasis endpoint using the [Envoy HTTP proxy] with +the following behavior: + +- whitelisted methods for checking the network status, performing queries and + submitting transactions, +- no control methods allowed and no queries that are CPU or I/O intensive, +- lives on `grpc.my-oasis-node.com` with TLS-enabled connection and certificates + that you already have from Let's Encrypt, +- `internal.sock` of the Oasis node is accessible at `/node/data/internal.sock`. + +Envoy already has built-in support for gRPC so after installing Envoy, simply +put the configuration below inside your `envoy.yaml` and then execute the proxy +with `envoy -c envoy.yaml`. + +```yaml title="envoy.yaml" +# Envoy gRPC-web proxy configuration +--- +admin: + address: + socket_address: + address: "127.0.0.1" + port_value: 10000 +static_resources: + listeners: + - name: listener_0 + address: + socket_address: + address: "0.0.0.0" + port_value: 443 + filter_chains: + - filters: + - name: envoy.filters.network.http_connection_manager + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager + codec_type: AUTO + stat_prefix: ingress_http + access_log: + - name: envoy.file_access_log + typed_config: + "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog + path: /dev/stdout + route_config: + virtual_hosts: + - name: vh_0 + domains: + - "*" + routes: + - match: + safe_regex: + regex: "\ +/oasis-core\\.(\ + Beacon/(\ + ConsensusParameters|\ + GetBaseEpoch|\ + GetBeacon|\ + GetEpoch|\ + GetEpochBlock|\ + GetFutureEpoch)|\ + Consensus/(\ + EstimateGas|\ + GetBlock|\ + GetChainContext|\ + GetGenesisDocument|\ + GetNextBlockState|\ + GetSignerNonce|\ + GetStatus|\ + GetTransactions|\ + GetTransactionsWithResults|\ + GetUnconfirmedTransactions|\ + SubmitTx)|\ + Governance/(\ + ActiveProposals|\ + ConsensusParameters|\ + GetEvents|\ + PendingUpgrades|\ + Proposal|\ + Proposals|\ + Votes)|\ + NodeController/(\ + GetStatus)|\ + Registry/(\ + ConsensusParameters|\ + GetEntity|\ + GetEvents|\ + GetNode|\ + GetNodeByConsensusAddress|\ + GetNodeStatus|\ + GetRuntime|\ + GetRuntimes)|\ + RootHash/(\ + ConsensusParameters|\ + GetEvents|\ + GetGenesisBlock|\ + GetLastRoundResults|\ + GetLatestBlock|\ + GetRuntimeState)|\ + RuntimeClient/(\ + CheckTx|\ + GetBlock|\ + GetEvents|\ + GetGenesisBlock|\ + GetLastRetainedBlock|\ + GetTransactions|\ + GetTransactionsWithResults|\ + Query|\ + SubmitTx|\ + SubmitTxMeta|\ + SubmitTxNoWait|\ + WatchBlocks)|\ + Scheduler/(\ + ConsensusParameters|\ + GetCommittees|\ + GetValidators)|\ + Staking/(\ + Account|\ + Allowance|\ + CommonPool|\ + ConsensusParameters|\ + DebondingDelegationInfosFor|\ + DebondingDelegationsFor|\ + DebondingDelegationsTo|\ + DelegationInfosFor|\ + DelegationsFor|\ + DelegationsTo|\ + GetEvents|\ + GovernanceDeposits|\ + LastBlockFees|\ + Threshold|\ + TokenSymbol|\ + TokenValueExponent|\ + TotalSupply))\ +" + route: + cluster: oasis_node_grpc + timeout: "0s" + max_stream_duration: + grpc_timeout_header_max: "0s" + - match: + prefix: /oasis-core + direct_response: + status: 404 + body: + inline_string: Only some methods are allowed on this proxy. + typed_per_filter_config: + envoy.filters.http.cors: + "@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.CorsPolicy + expose_headers: grpc-status,grpc-message,grpc-status-details-bin + allow_origin_string_match: + - exact: '*' + allow_headers: content-type,x-grpc-web,x-user-agent + max_age: '1728000' + http_filters: + - name: envoy.health_check + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.health_check.v3.HealthCheck + pass_through_mode: false + headers: + - name: :path + string_match: + exact: /health + - name: envoy.filters.http.grpc_web + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb + - name: envoy.filters.http.cors + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.Cors + - name: envoy.filters.http.router + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router + transport_socket: + name: envoy.transport_sockets.tls + typed_config: + "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext + common_tls_context: + alpn_protocols: + - h2,http/1.1 + tls_certificates: + - certificate_chain: + filename: /etc/letsencrypt/live/grpc.my-oasis-node.com/fullchain.pem + private_key: + filename: /etc/letsencrypt/live/grpc.my-oasis-node.com/privkey.pem + clusters: + - name: oasis_node_grpc + connect_timeout: 0.25s + load_assignment: + cluster_name: cluster_0 + endpoints: + - lb_endpoints: + - endpoint: + address: + pipe: + path: /node/data/internal.sock + typed_extension_protocol_options: + envoy.extensions.upstreams.http.v3.HttpProtocolOptions: + "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions + explicit_http_config: + http2_protocol_options: {} +layered_runtime: + layers: + - name: static + static_layer: + re2: + max_program_size: + error_level: 1000000 +``` + +[Envoy HTTP proxy]: https://www.envoyproxy.io/ + +## Tunnel Unix socket via SSH + +SSH supports forwarding a Unix socket over a secure layer. The command below +will establish a secure shell to the `my-oasis-node.com` server and then tunnel +the `internal.sock` file inside the data directory to a Unix socket inside your +home folder: + +```shell +ssh oasis@my-oasis-node.com -L /home/user/oasis-node-internal.sock:/node/data/internal.sock +``` + +The `/home/user/oasis-node-internal.sock` can now be used to safely connect to +the Oasis node **as if it was running locally without filtering any services**. +For example, using the [Oasis CLI]: + +```shell +oasis network add-local my-oasis-node unix:/home/user/oasis-node-internal.sock +``` + +```shell +oasis network status --network my-oasis-node +``` + +:::tip Permanent SSH channel + +To make a tunneled Unix socket over SSH permanent, consider using [autossh]. + +::: + +[Oasis CLI]: https://github.com/oasisprotocol/cli/blob/master/docs/network.md#add-local +[autossh]: https://www.harding.motd.ca/autossh/ + +## See also + + diff --git a/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md b/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md index eafbacaff1..66dd4fedf6 100644 --- a/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md +++ b/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md @@ -17,7 +17,7 @@ the [State Sync](sync-node-using-state-sync.md). To bootstrap a new Oasis node by copying state from a synced Oasis node, first set up your new Oasis node as a [Validator Node](../validator-node.mdx), a -[Non-validator Node](../non-validator-node.md) or a +[Non-validator Node](../non-validator-node.mdx) or a [ParaTime Node](../paratime-node.mdx). :::caution diff --git a/docs/node/run-your-node/advanced/sync-node-using-state-sync.md b/docs/node/run-your-node/advanced/sync-node-using-state-sync.md index f5487cbb2d..6b81b92c45 100644 --- a/docs/node/run-your-node/advanced/sync-node-using-state-sync.md +++ b/docs/node/run-your-node/advanced/sync-node-using-state-sync.md @@ -2,7 +2,7 @@ The State Sync is a way to **quickly bootstrap** a **full Oasis node** (either a [validator node](../validator-node.mdx) or a -[non-validator node](../non-validator-node.md)) by using the +[non-validator node](../non-validator-node.mdx)) by using the [Tendermint's Light Client protocol]. It allows one to initialize a node from a trusted height, its corresponding block's header and a trusted validator set (given in the [genesis document](../../genesis-doc.md)). It does so by securely diff --git a/docs/node/run-your-node/archive-node.md b/docs/node/run-your-node/archive-node.md index 42d3e3132f..22b0d30f57 100644 --- a/docs/node/run-your-node/archive-node.md +++ b/docs/node/run-your-node/archive-node.md @@ -72,4 +72,4 @@ Output should report `archive` consensus mode status: ## See also -[Archive Web3 Gateway](../web3.md#archive-web3-gateway) +[Archive Web3 Gateway](../web3.mdx#archive-web3-gateway) diff --git a/docs/node/run-your-node/ias-proxy.md b/docs/node/run-your-node/ias-proxy.md index ddbc90ea1f..9f69c42b92 100644 --- a/docs/node/run-your-node/ias-proxy.md +++ b/docs/node/run-your-node/ias-proxy.md @@ -10,7 +10,7 @@ Before following this guide, make sure you've followed the [Prerequisites](prerequisites) section and have the Oasis Node binary installed on your system. The IAS Proxy connects to an Oasis Node, so make sure you have a running node first. For more details, see the instructions on how to -[Run a Non-validator Node](non-validator-node.md#configuration). +[Run a Non-validator Node](non-validator-node.mdx#configuration). ### Obtaining IAS Service Provider ID (SPID) and API Key diff --git a/docs/node/run-your-node/keymanager-node/README.md b/docs/node/run-your-node/keymanager-node/README.md index e13abbae92..5e84787304 100644 --- a/docs/node/run-your-node/keymanager-node/README.md +++ b/docs/node/run-your-node/keymanager-node/README.md @@ -16,7 +16,7 @@ This guide will cover setting up your key manager node for the Oasis Network. Th ## Prerequisites -Before following this guide, make sure you've followed the [Prerequisites](../prerequisites) and [Run a Non-validator Node](../non-validator-node.md) sections and have: +Before following this guide, make sure you've followed the [Prerequisites](../prerequisites) and [Run a Non-validator Node](../non-validator-node.mdx) sections and have: * Oasis Node binary installed on your system and a dedicated non-root user that will run your Oasis Node. * The chosen top-level `/node/` working directory prepared (feel free to name it as you wish, e.g. `/srv/oasis/`) with: diff --git a/docs/node/run-your-node/non-validator-node.md b/docs/node/run-your-node/non-validator-node.mdx similarity index 94% rename from docs/node/run-your-node/non-validator-node.md rename to docs/node/run-your-node/non-validator-node.mdx index f3f5a3ff7a..487a9cc03d 100644 --- a/docs/node/run-your-node/non-validator-node.md +++ b/docs/node/run-your-node/non-validator-node.mdx @@ -1,3 +1,6 @@ +import DocCard from '@theme/DocCard'; +import {findSidebarItem} from '@site/src/sidebarUtils'; + # Non-validator Node :::info @@ -86,3 +89,6 @@ To ensure that your node is properly connected with the network, you can run the oasis-node control status -a unix:/node/data/internal.sock ``` +## See also + + diff --git a/docs/node/run-your-node/paratime-client-node.mdx b/docs/node/run-your-node/paratime-client-node.mdx index 876572d3c1..0fa69b8421 100644 --- a/docs/node/run-your-node/paratime-client-node.mdx +++ b/docs/node/run-your-node/paratime-client-node.mdx @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; :::info -These instructions are for setting up a _ParaTime client_ node which only observes ParaTime activity and can submit transactions. If you want to run a _ParaTime_ node instead, see the [instructions for running a ParaTime node](paratime-node.mdx). Similarly, if you want to run a _validator_ or a _non-validator_ node instead, see the [instructions for running a validator node](validator-node.mdx) or [instructions for running a non-validator node](non-validator-node.md). +These instructions are for setting up a _ParaTime client_ node which only observes ParaTime activity and can submit transactions. If you want to run a _ParaTime_ node instead, see the [instructions for running a ParaTime node](paratime-node.mdx). Similarly, if you want to run a _validator_ or a _non-validator_ node instead, see the [instructions for running a validator node](validator-node.mdx) or [instructions for running a non-validator node](non-validator-node.mdx). ::: @@ -27,7 +27,7 @@ This guide will cover setting up your ParaTime client node for the Oasis Network ## Prerequisites -Before following this guide, make sure you've followed the [Prerequisites](prerequisites) and [Run a Non-validator Node](non-validator-node.md) sections and have: +Before following this guide, make sure you've followed the [Prerequisites](prerequisites) and [Run a Non-validator Node](non-validator-node.mdx) sections and have: * Oasis Node binary installed and configured on your system. * The chosen top-level `/node/` working directory prepared. In addition to `etc` and `data` directories, also prepare the following directories: diff --git a/docs/node/run-your-node/paratime-node.mdx b/docs/node/run-your-node/paratime-node.mdx index 85984cb533..ceceecbb7f 100644 --- a/docs/node/run-your-node/paratime-node.mdx +++ b/docs/node/run-your-node/paratime-node.mdx @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; :::info -These instructions are for setting up a _ParaTime_ node which participates in one or more ParaTime compute committees. If you want to run a _ParaTime client_ node instead, see the [instructions for running a ParaTime client node](paratime-client-node.mdx). If you want to run a _validator_ node instead, see the [instructions for running a validator node](validator-node.mdx). Similarly, if you want to run a non-validator node instead, see the [instructions for running a non-validator node](non-validator-node.md). +These instructions are for setting up a _ParaTime_ node which participates in one or more ParaTime compute committees. If you want to run a _ParaTime client_ node instead, see the [instructions for running a ParaTime client node](paratime-client-node.mdx). If you want to run a _validator_ node instead, see the [instructions for running a validator node](validator-node.mdx). Similarly, if you want to run a non-validator node instead, see the [instructions for running a non-validator node](non-validator-node.mdx). ::: @@ -35,7 +35,7 @@ This guide will cover setting up your ParaTime compute node for the Oasis Networ ## Prerequisites -Before following this guide, make sure you've followed the [Prerequisites](prerequisites) and [Run a Non-validator Node](non-validator-node.md) sections and have: +Before following this guide, make sure you've followed the [Prerequisites](prerequisites) and [Run a Non-validator Node](non-validator-node.mdx) sections and have: * Oasis Node binary installed and configured on your system. * The chosen top-level `/node/` working directory prepared. In addition to `etc` and `data` directories, also prepare the following directories: diff --git a/docs/node/run-your-node/prerequisites/hardware-recommendations.md b/docs/node/run-your-node/prerequisites/hardware-recommendations.md index 1421940e2a..c4f40a0559 100644 --- a/docs/node/run-your-node/prerequisites/hardware-recommendations.md +++ b/docs/node/run-your-node/prerequisites/hardware-recommendations.md @@ -11,7 +11,7 @@ as: :::info Hardware requirements for running the Oasis Web3 gateway can be found -[here](../../web3.md#hardware). +[here](../../web3.mdx#hardware). ::: diff --git a/docs/node/run-your-node/validator-node.mdx b/docs/node/run-your-node/validator-node.mdx index da62563cac..63711571e5 100644 --- a/docs/node/run-your-node/validator-node.mdx +++ b/docs/node/run-your-node/validator-node.mdx @@ -1,4 +1,4 @@ -import DocCard from '@theme/DocCard'; +import DocCardList from '@theme/DocCardList'; import {findSidebarItem} from '@site/src/sidebarUtils'; # Validator Node @@ -181,7 +181,7 @@ common: data_dir: /node/data # Logging. # - # Per-module log levels are defined below. If you prefer just one unified + # Per-module log levels are defined below. If you prefer just one unified # log level, you can use: # # log: @@ -190,11 +190,11 @@ common: level: cometbft: warn cometbft/context: error - # Per-module log levels. Longest prefix match will be taken. + # Per-module log levels. Longest prefix match will be taken. # Fallback to "default", if no match. default: debug format: JSON - # By default logs are output to stdout. If you would like to output + # By default logs are output to stdout. If you would like to output # logs to a file, you can use: # # file: /var/log/oasis-node.log @@ -451,5 +451,8 @@ the node operator's name and the avatar. # See also - - + diff --git a/docs/node/web3.md b/docs/node/web3.mdx similarity index 97% rename from docs/node/web3.md rename to docs/node/web3.mdx index 6869755c36..e3b7e2da49 100644 --- a/docs/node/web3.md +++ b/docs/node/web3.mdx @@ -2,6 +2,9 @@ description: Web3 gateway for Emerald and Sapphire ParaTimes --- +import DocCardList from '@theme/DocCardList'; +import {findSidebarItem} from '@site/src/sidebarUtils'; + # Oasis Web3 Gateway for your EVM ParaTime This guide will walk you through the steps needed to set up the Oasis Web3 @@ -272,3 +275,10 @@ extended downtime while the Web3 Gateway is reindexing the blocks. [Testnet]: testnet/README.md [testnet-emerald]: testnet/README.md#emerald [testnet-sapphire]: testnet/README.md#sapphire + +## See also + + diff --git a/sidebarNode.ts b/sidebarNode.ts index 84945bf7cc..fbd36ee52a 100644 --- a/sidebarNode.ts +++ b/sidebarNode.ts @@ -131,5 +131,10 @@ export const sidebarNode: SidebarsConfig = { label: 'Web3 Gateway', id: 'node/web3', }, + { + type: 'doc', + label: 'gRPC Proxy', + id: 'node/grpc', + }, ], };