diff --git a/.gitmodules b/.gitmodules index eebeeb7859..b1c953dd35 100644 --- a/.gitmodules +++ b/.gitmodules @@ -5,9 +5,6 @@ [submodule "external/oasis-sdk"] path = external/oasis-sdk url = https://github.com/oasisprotocol/oasis-sdk -[submodule "external/oasis-core-ledger"] - path = external/oasis-core-ledger - url = https://github.com/oasisprotocol/oasis-core-ledger [submodule "external/adrs"] path = external/adrs url = https://github.com/oasisprotocol/adrs diff --git a/docs/general/manage-tokens/faq.md b/docs/general/manage-tokens/faq.md index 932aa92405..709734b750 100644 --- a/docs/general/manage-tokens/faq.md +++ b/docs/general/manage-tokens/faq.md @@ -110,15 +110,26 @@ and [import it to the Oasis wallet][oasis-wallet-import-private-key]. ### Chromium under Ubuntu does not recognize my Ledger device. What is the problem? -First check that you added the Ledger udev device descriptors as mentioned in the [Linux installation guide](https://support.ledger.com/hc/en-us/articles/4404389606417-Download-and-install-Ledger-Live). Next, check that your Ledger wallet is recognized by the [Oasis Core Ledger tool](../../oasis-core-ledger/usage/address.md). You should see something like this: - -```bash -$ oasis-core-ledger show_address -oasis1qp8d9kuduq0zutuatjsgltpugxvl38cuaq3gzkmn -Ensure account address shown on device's screen matches the outputted address. -``` - -If all of the above works, then the issue is most likely that Chromium does not have the permission to access your Ledger device. Starting with Ubuntu 20.04 the Chromium browser is installed via snap package by default. Snap is more convenient for upstream developers to deploy their software and it also adds additional layer of security by using apparmor. In our case however, it prevents Chromium to access arbitrary USB devices with WebUSB API including your Ledger device. A workaround for this issue is to install Chromium natively using the official [Chormium beta PPA](https://launchpad.net/\~saiarcot895/+archive/ubuntu/chromium-beta) or the official [Google Chrome .deb package](https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb). +First check that you added the Ledger udev device descriptors as mentioned in +the [Linux installation guide]. Next, check that your Ledger wallet is +recognized by the [Oasis CLI]. You should be able to add your Ledger account to +the Oasis CLI wallet by running: + +![code shell](../../../external/cli/examples/wallet/create.in.static) + +If all of the above works, then the issue is most likely that Chromium does not +have the permission to access your Ledger device. Starting with Ubuntu 20.04 the +Chromium browser is installed via snap package by default. Snap is more +convenient for upstream developers to deploy their software and it also adds +additional layer of security by using apparmor. In our case however, it prevents +Chromium to access arbitrary USB devices with WebUSB API including your Ledger +device. A workaround for this issue is to install Chromium natively using the +official [Chormium beta PPA] or the official [Google Chrome .deb package]. + +[Linux installation guide]: https://support.ledger.com/hc/en-us/articles/4404389606417-Download-and-install-Ledger-Live +[Oasis CLI]: cli/README.md +[Chormium beta PPA]: https://launchpad.net/\~saiarcot895/+archive/ubuntu/chromium-beta +[Google Chrome .deb package]: https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb ### Are Ethereum and Oasis wallets that different? I can use the same mnemonics with both, right? diff --git a/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md b/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md index 8c9895fe8f..313c49c339 100644 --- a/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md +++ b/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md @@ -142,8 +142,10 @@ tasks (sending, staking, ParaTime deposits and withdrawals), but also generating and/or signing raw transactions, multi-signatures, network governance operations etc. -Ledger is supported by the Oasis CLI. Follow the instructions in the -[Oasis CLI Tools] page to learn more. +Ledger is supported by the [Oasis CLI]. You can add a new Ledger account to the +Oasis CLI by invoking the [`oasis wallet create`] command. For example: + +![code shell](../../../../external/cli/examples/wallet/create-ledger.in.static) [Ledger]: https://www.ledger.com [Oasis app]: https://github.com/Zondax/ledger-oasis @@ -157,4 +159,5 @@ Ledger is supported by the Oasis CLI. Follow the instructions in the [Nano S Plus]: https://support.ledger.com/hc/en-us/articles/4445777839901-Update-Ledger-Nano-S-Plus-firmware [BIP 39]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki [Oasis Wallets]: ../oasis-wallets/README.mdx -[Oasis CLI Tools]: ../cli/README.md +[Oasis CLI]: ../cli/README.md +[`oasis wallet create`]: ../cli/wallet.md#create diff --git a/docs/node/mainnet/upgrade-log.md b/docs/node/mainnet/upgrade-log.md index 0676671eb4..e4876c7eda 100644 --- a/docs/node/mainnet/upgrade-log.md +++ b/docs/node/mainnet/upgrade-log.md @@ -366,8 +366,7 @@ oasis-node consensus submit_tx \ [upgrade governance proposal]: ../../core/consensus/services/governance.md#submit-proposal [your entity's nonce]: ../../general/manage-tokens/cli/account.md#show [Oasis CLI Tools Setup]: ../../core/oasis-node/cli.md#storing-base-and-signer-flags-in-an-environment-variable -[Installing Oasis App on Your Ledger Wallet]: - ../../oasis-core-ledger/usage/setup#installing-oasis-app-on-your-ledger-wallet +[Installing Oasis App on Your Ledger Wallet]: ../../general/manage-tokens/holding-rose-tokens/ledger-wallet.md ### Instructions - Before upgrade diff --git a/docs/node/run-your-node/advanced/install-oasis-remote-signer-binary.md b/docs/node/run-your-node/advanced/install-oasis-remote-signer-binary.md deleted file mode 100644 index 372ab3e490..0000000000 --- a/docs/node/run-your-node/advanced/install-oasis-remote-signer-binary.md +++ /dev/null @@ -1,55 +0,0 @@ -# Install Oasis Remote Signer Binary - -:::info - -You only need to install the Oasis Remote Signer binary if you intend to configure your Oasis node with a remote signer setup. - -An example of such a setup is described in [Using Ledger-backed Consensus Key with a Remote Signer](using-ledger-backed-consensus-key-with-a-remote-signer.md). - -::: - -The Oasis Remote Signer is a binary that is created from the [Oasis Core](https://github.com/oasisprotocol/oasis-core) repository's [`go/oasis-remote-signer` path](https://github.com/oasisprotocol/oasis-core/tree/master/go/oasis-remote-signer). - -It contains the logic for implementing various Oasis Core signers (i.e. Ledger-based signer, file-based signer or a combination of both via composite signer) and a gRPC service through which an Oasis node can connect to it and request signatures from it. - -:::caution - -The Oasis Remote Signer is currently only supported on x86_64 Linux systems. - -::: - -## Downloading a Binary Release - -:::tip - -We suggest that you build Oasis Remote Signer from source yourself for a production deployment of an Oasis node with a remote signer setup. - -::: - -For convenience, we provide binaries that have been built by the Oasis Protocol Foundation. Links to the binaries are provided in the Network Parameters page ([Mainnet], [Testnet]). - -[Mainnet]: ../../mainnet/README.md -[Testnet]: ../../testnet/README.md - -## Building From Source - -Although highly suggested, building from source is currently beyond the scope of this documentation. - -See [Oasis Core's Build Environment Setup and Building](../../../core/development-setup/build-environment-setup-and-building) documentation for more details. - -:::danger - -The code in the [`master` branch](https://github.com/oasisprotocol/oasis-core/tree/master/) might be incompatible with the code used by other nodes in the Mainnet. - -Make sure to use the version specified in the Network Parameters page ([Mainnet], [Testnet]). - -::: - -## Adding `oasis-remote-signer` Binary to `PATH` - -To install the `oasis-node` binary next to your Oasis node data directory, copy/symlink it to e.g. `/node/bin`. - -To install the `oasis-remote-signer` binary for the current user, copy/symlink it to `~/.local/bin`. - -To install the `oasis-remote-signer` binary for all users of the system, copy it to `/usr/local/bin`. - diff --git a/docs/node/run-your-node/advanced/remote-signer.mdx b/docs/node/run-your-node/advanced/remote-signer.mdx new file mode 100644 index 0000000000..62a651b4ff --- /dev/null +++ b/docs/node/run-your-node/advanced/remote-signer.mdx @@ -0,0 +1,207 @@ +import DocCard from '@theme/DocCard'; +import {findSidebarItem} from '@site/src/sidebarUtils'; + +# Remote Signer for Oasis Node Keys + +The [Oasis remote signer][oasis-core-remote-signer] is an application that +contains logic for various Oasis Core signers. Currently, only the file-based +signer is implemented, but support for hardware signers is in the works. Access +to the remote signer is provided via a gRPC service through which the Oasis node +can connect to it and request signatures. + +This chapter will describe how to install the Oasis remote signer and then +configure your Oasis node to use it. We will use two separate physical machines +for deployment: + +- a `server` which will function as a system running the Oasis node, +- a `signer-server` which will run the Oasis remote signer and store the node + keys. + +**These are advanced instructions intended for node operators that want to +increase the security of their validator nodes.** + +:::tip + +This chapter describes a tool to remotely access the [node keys] (i.e. +`beacon.pem`, `consensus.pem`, `identity.pem`, `p2p.pem`...). There is another +[`oasis wallet remote-signer`] Oasis CLI command which enables remote access to +your [entity key] and should not be confused with. + +::: + +[oasis-core-remote-signer]: https://github.com/oasisprotocol/oasis-core/tree/master/go/oasis-remote-signer +[node keys]: ../validator-node.mdx#node-keys +[entity key]: ../validator-node.mdx#initialize-entity +[validator-node]: ../validator-node.mdx +[discord]: ../../../get-involved/README.md +[`oasis wallet remote-signer`]: ../../../general/manage-tokens/cli/wallet.md#remote-signer + +## Prerequisites + +Before we continue, make sure you've followed the [Install Oasis Node Binary] +chapter and have the Oasis node binary installed on your system. + +[Install Oasis Node Binary]: ../prerequisites/oasis-node.md + +## Install Oasis Remote Signer Binary + +The Oasis remote signer is part of the [Oasis Core][oasis-core-remote-signer]. +You can either download the binary or compile it from source and then copy it +over to your `signer-server` system. + +:::info + +The Oasis remote signer is currently only supported on x86_64 Linux systems. + +::: + +### Downloading a Binary Release + +The Oasis remote signer binary is part of the **Oasis Core release bundle**. +Links to the latest releases are on the Network Parameters page ([Mainnet], +[Testnet]). The Oasis remote signer binary inside the release bundle is called +`oasis-remote-signer`. You should always use the version of the remote signer +matching the version of your Oasis node. + +[Mainnet]: ../../mainnet/README.md +[Testnet]: ../../testnet/README.md + +### Building From Source + +Follow the [Oasis Core's Build Environment Setup and Building][oasis-core-build] +chapter. After the Oasis Core is compiled, the `oasis-remote-signer` binary +should be located in the `go/oasis-remote-signer` subdirectory. + +:::caution + +The code in the current [`master`] branch may be incompatible with the code used +by other nodes on the network. Make sure to use the version specified on the +Network Parameters page ([Mainnet], [Testnet]). + +::: + +[oasis-core-build]: ../../../core/development-setup/build-environment-setup-and-building +[`master`]: https://github.com/oasisprotocol/oasis-core/tree/master/ + +### Adding `oasis-remote-signer` Binary to `PATH` + +To install the `oasis-remote-signer` binary for the current user, copy/symlink +it to `~/.local/bin`. + +To install the `oasis-remote-signer` binary for all users of the system, copy +it to `/usr/local/bin`. + +## Set Up Remote Signer System + +### Initialize Remote Signer + +On `signer-server`, create a directory for the remote signer, e.g. +`remote-signer`, by running: + +``` +mkdir --mode=700 remote-signer +``` + +Then, generate the [node keys] and the server certificate by running: + +``` +oasis-remote-signer init --datadir remote-signer/ +``` + +Also, generate the remote signer's client certificate which will be used by +the Oasis node to connect to the remote signer: + +``` +oasis-remote-signer init_client --datadir remote-signer/ +``` + +### Run Remote Signer + +Choose the gRPC port on which the remote signer will listen for client requests +and run: + +``` +oasis-remote-signer \ +--datadir remote-signer \ +--client.certificate remote-signer/remote_signer_client_cert.pem \ +--grpc.port \ +--log.level DEBUG +``` + +:::tip + +The Oasis Remote Signer is configured to run in the foreground by default. + +We recommend you configure and use it with a process manager like [systemd] or +[Supervisor]. Check out the [System Configuration] page for examples. + +::: + +[systemd]: https://github.com/systemd/systemd +[Supervisor]: http://supervisord.org +[System Configuration]: ../prerequisites/system-configuration.mdx#change-to-non-root + +### Copy Remote Signer Certificate, Client Key and Certificate + +In order for the Oasis node to securely connect to the Oasis remote signer and +be able to demonstrate its authenticity, you need to copy the following files +from `signer-server` to `server` inside the `/node/data/remote-signer` +directory: + +* `remote-signer/remote_signer_server_cert.pem`: The remote signer's + certificate. This certificate ensures the Oasis node system is connecting to + the trusted remote signer system. +* `remote-signer/remote_signer_client_key.pem`: The remote signer's client key. + This key enables the Oasis node system to demonstrate its authenticity when it + is requesting signatures from the remote signer system. +* `remote-signer/remote_signer_client_cert.pem`: The remote signer's client + certificate. This certificate is the counterpart of the remote signer's client + key. + +## Configuration + +When [configuring your Oasis Node](../validator-node.mdx#configuration) +on `server`, you need to add the appropriate `signer` section to configure the +**composite** and **remote** signers. For example: + +```yaml +# Signer. +signer: + backend: composite + # Use file-based signer for entity, node and P2P keys and remote signer for the + # consensus key. + composite: + backends: entity:file,node:file,p2p:file,consensus:remote + # Configure how to connect to the Oasis Remote Signer. + remote: + address: : + server: + certificate: /node/data/remote-signer/remote_signer_server_cert.pem + client: + key: /node/data/remote-signer/remote_signer_client_key.pem + certificate: /node/data/remote-signer/remote_signer_client_cert.pem +``` + +This assumes you've copied the remote signer's certificate and remote signer's +client key and certificate to the `/node/data/remote-signer/` directory. + +## Starting the Oasis node + +[Start the Oasis node] using the modified config above. To ensure that your +Oasis node will be able to sign consensus transactions, check that the Oasis +remote signer is running and accepting remote client connections via the +designated port. + +:::info + +The `/node/data` directory on `server` will only have `consensus_pub.pem` and no +`consensus.pem` since the consensus key is backed by the Oasis remote signer. + +::: + +[Start the Oasis node]: ../validator-node.mdx#starting-the-oasis-node + +# See also + + + diff --git a/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md b/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md deleted file mode 100644 index b1a9adeab7..0000000000 --- a/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md +++ /dev/null @@ -1,177 +0,0 @@ -# Using Ledger-backed Consensus Key with a Remote Signer - -This guide will describe how you can set up your [_validator_ node](../validator-node.mdx) with a detached consensus key stored on a [Ledger](https://www.ledger.com) wallet connected via [Oasis Core's Remote Signer](https://github.com/oasisprotocol/oasis-core/tree/master/go/oasis-remote-signer). - -:::caution - -These instructions are still a work-in-progress draft. - -Your feedback is welcome. Please, reach out via the [**#node-operators** channel at the Oasis Network Community server on Discord](../../../get-involved/README.md) with your questions, comments, and feedback. - -::: - -:::danger - -These are advanced instructions intended for node operators that want to increase their validator node security by having the consensus key be detached and stored on a Ledger wallet and connected via Oasis Core's remote signer instead of having consensus key simply be a file on the file system. - -::: - -## Prerequisites - -Before following this guide, make sure you've followed the [Prerequisites](../prerequisites) section and have the Oasis Node binary installed on your Oasis node system. - -Also make sure you've followed the [Install Oasis Remote Signer Binary](install-oasis-remote-signer-binary.md) section and have the Oasis Remote Signer binary installed on your remote signer system where your Ledger wallet will be connected. - -Finally, you need to do steps described in the [Setup](../../../oasis-core-ledger/usage/setup.md) section of our [Oasis Core Ledger docs](../../../oasis-core-ledger). Make sure you also install the _**OasisVal**_** app** on your Ledger wallet. - -## Set Up Remote Signer System - -### Initialize Remote Signer - -On your remote signer system, create a directory for the remote signer, e.g. `remote-signer`, by running: - -``` -mkdir --mode=700 remote-signer -``` - -Then initialize remote signer's keys (consensus, entity, identity, ...) and server certificate by running: - -``` -oasis-remote-signer init --datadir remote-signer/ -``` - -Also initialize remote signer's client certificate which will be used by the Oasis node system to connect to the remote signer system: - -``` -oasis-remote-signer init_client --datadir remote-signer/ -``` - -### Run Remote Signer - -:::info - -Before following the instructions below, make sure your Ledger wallet is connected to your remote signer system, unlocked and the OasisVal App is open. - -::: - -:::caution - -While the OasisVal App is available in _Developer mode_, opening the App brings up the "Pending Ledger review" screen. You need to press both buttons at once to close that screen and transition to the _ordinary_ "Oasis Ready" screen where the OasisVal App is ready to be used. - -::: - -Choose the gRPC port on which the remote signer will listen for client requests and set the path to the `ledger-signer` plugin in the appropriate environment variables and run: - -``` -GRPC_PORT= -LEDGER_SIGNER_PATH= -oasis-remote-signer \ ---datadir remote-signer \ ---signer.backend composite \ ---signer.composite.backends entity:file,node:file,p2p:file,consensus:plugin \ ---signer.plugin.name ledger \ ---signer.plugin.path $LEDGER_SIGNER_PATH \ ---client.certificate remote-signer/remote_signer_client_cert.pem \ ---grpc.port $GRPC_PORT \ ---log.level DEBUG -``` - -:::info - -If necessary, you can configure the Ledger-based signer by setting the `--signer.plugin.config` flag appropriately, e.g.: - -``` ---signer.plugin.config "wallet_id:1fc3be,index:5" -``` - -to configure the wallet with a specific ID and to use a non-zero account index. - -::: - -:::tip - -The Oasis Remote Signer is configured to run in the foreground by default. - -We recommend you configure and use it with a process manager like [systemd](https://github.com/systemd/systemd) or [Supervisor](http://supervisord.org). - -::: - -### Copy Remote Signer Certificate and Client Key and Certificate - -For the Oasis node system to be able to connect to the Oasis Remote Signer on the remote signer system and to be able to demonstrate its authenticity to it, you need to copy the following files from your remote signer system to your Oasis node system: - -* `remote-signer/remote_signer_server_cert.pem`: The remote signer's certificate. This certificate ensures the Oasis node system is connecting to the trusted remote signer system. -* `remote-signer/remote_signer_client_key.pem`: The remote signer's client key. This key enables the Oasis node system to demonstrate its authenticity when it is requesting signatures from the remote signer system. -* `remote-signer/remote_signer_client_cert.pem`: The remote signer's client certificate. This certificate is the counterpart of the remote signer's client key. - -## Set Up Oasis Node System - -For setting up your Oasis Node system, follow the [Run a Validator Node](../validator-node.mdx) docs. - -:::info - -Make sure you've copied the remote signer's certificate and remote signer's client key and certificate to your Oasis Node system as described in [Copy Remote Signer Certificate and Client Key and Certificate](using-ledger-backed-consensus-key-with-a-remote-signer.md#copy-remote-signer-certificate-and-client-key-and-certificate) section. - -::: - -### Initialize Oasis Node - -When [initializing your Oasis node](../validator-node.mdx#initializing-a-node), you need to pass appropriate `--signer.*` flags to configure the composite and remote signers. For example: - -``` -ENTITY_DIR= -STATIC_IP= -REMOTE_SIGNER_IP= -REMOTE_SIGNER_PORT= -oasis-node registry node init \ ---signer.backend composite \ ---signer.composite.backends 1:file,2:file,3:file,4:remote \ ---signer.dir $ENTITY_DIR \ ---node.consensus_address $STATIC_IP:26656 \ ---node.role validator \ ---signer.remote.address $REMOTE_SIGNER_IP:$REMOTE_SIGNER_PORT \ ---signer.remote.client.certificate remote-signer/remote_signer_client_cert.pem \ ---signer.remote.client.key remote-signer/remote_signer_client_key.pem \ ---signer.remote.server.certificate remote-signer/remote_signer_server_cert.pem \ ---datadir node/ -``` - -This assumes you've copied the remote signer's certificate and remote signer's client key and certificate to the `remote-signer/` directory. - -:::tip - -The resulting directory only has `consensus_pub.pem` and no `consensus.pem` since the consensus key is Ledger-backed. - -::: - -### Configure Oasis Node - -When [configuring your Oasis Node](../validator-node.mdx#configuring-the-oasis-node), you need to add the appropriate `signer` section to configure the composite and remote signers. For example: - -```yaml -# Signer. -signer: - backend: composite - # Use file-based signer for entity, node and P2P keys and remote signer for the - # consensus key. - composite: - backends: entity:file,node:file,p2p:file,consensus:remote - # Configure how to connect to the Oasis Remote Signer. - remote: - address: : - server: - certificate: /srv/oasis/remote-signer/remote_signer_server_cert.pem - client: - key: /srv/oasis/remote-signer/remote_signer_client_key.pem - certificate: /srv/oasis/remote-signer/remote_signer_client_cert.pem -``` - -This assumes you've copied the remote signer's certificate and remote signer's client key and certificate to the `/srv/oasis/remote-signer/` directory. - -:::info - -To ensure your Oasis Node will be able to sign consensus transactions, make sure your Ledger wallet is connected to your remote signer system, unlocked and the OasisVal App is open. - -Also make sure the Oasis Remote Signer is running on your remote signer system and accepting remote client connections via the designated port. - -::: diff --git a/docs/node/run-your-node/prerequisites/oasis-node.md b/docs/node/run-your-node/prerequisites/oasis-node.md index eec7a067fd..61885b1a4f 100644 --- a/docs/node/run-your-node/prerequisites/oasis-node.md +++ b/docs/node/run-your-node/prerequisites/oasis-node.md @@ -1,8 +1,8 @@ -# Install Oasis Node Binary +# Install the Oasis Node -The Oasis Node is a binary that is created from the [Oasis Core](https://github.com/oasisprotocol/oasis-core) repository's `go/` path. - -It contains both the logic for running an Oasis node and also provides a CLI for handling registry, staking and other operations. +The Oasis node is a binary that is created from the [Oasis Core] repository's +[`go/`] directory. It is a single executable that contains the logic for running +your node in various [roles]. :::caution @@ -10,56 +10,105 @@ The Oasis Node is currently only supported on x86_64 Linux systems. ::: -## Downloading a Binary Release +[Oasis Core]: https://github.com/oasisprotocol/oasis-core +[`go/`]: https://github.com/oasisprotocol/oasis-core/tree/master/go +[roles]: ../../README.mdx#node-roles + +## Set up the Oasis Node's Working Directory -:::tip +Before we install the Oasis node we need to ensure that we have a place to +store necessary files. -We suggest that you build Oasis Node from source yourself for a production deployment of an Oasis node. +:::info + +We will reference the working directory on the server as `/node` +throughout the documentation. ::: -For convenience, we provide binaries that have been built by the Oasis Protocol Foundation. Links to the binaries are provided in the Network Parameters page ([Mainnet], [Testnet]). +### Setting Up the `/node` Directory + +In the `/node` directory, create the following subdirectories: + +* `etc/`: this is to store the configuration and `entity.json` +* `data/`: this is to store the node's data +* `bin/`: this is to store the `oasis-node` binary +* `runtimes/`: this is to store the ParaTime `.orc` bundles + +You can make this directory structure with the **corresponding permissions** by +executing the following command: + +```shell +mkdir -m700 -p /node/{etc,bin,runtimes,data} +``` + +### Copying the Genesis File to the server + +The latest Genesis file can be found in the Network Parameters page ([Mainnet], +[Testnet]). You should download the latest `genesis.json` file and +copy it to `/node/etc/genesis.json` on the `server`. [Mainnet]: ../../mainnet/README.md [Testnet]: ../../testnet/README.md -## Building From Source +## Obtain the `oasis-node` Binary + +### Downloading a Binary Release + +For convenience, we provide binaries that have been built by the Oasis Protocol +Foundation. Links to the binaries are provided in the Network Parameters page +([Mainnet], [Testnet]). + +[Mainnet]: ../../mainnet/README.md +[Testnet]: ../../testnet/README.md -Although highly suggested, building from source is currently beyond the scope of this documentation. +### Building From Source -See [Oasis Core's Build Environment Setup and Building](../../../core/development-setup/build-environment-setup-and-building) documentation for more details. +Although highly suggested, building from source is currently beyond the scope of +this documentation. -:::danger +See [Oasis Core's Build Environment Setup and Building][oasis-core-build] +documentation for more details. -The code in the [`master` branch](https://github.com/oasisprotocol/oasis-core/tree/master/) might be incompatible with the code used by other nodes in the Mainnet. +:::caution -Make sure to use the version specified in the Network Parameters page ([Mainnet], [Testnet]). +The code in the current [`master`] branch may be incompatible with the code used +by other nodes on the network. Make sure to use the version specified on the +Network Parameters page ([Mainnet], [Testnet]). ::: -## Adding `oasis-node` Binary to `PATH` +[oasis-core-build]: ../../../core/development-setup/build-environment-setup-and-building +[`master`]: https://github.com/oasisprotocol/oasis-core/tree/master/ + +### Adding `oasis-node` Binary to `PATH` -To install the `oasis-node` binary next to your Oasis node data directory, copy/symlink it to e.g. `/node/bin`. +To install the `oasis-node` binary next to your Oasis node data directory, +copy/symlink it to e.g. `/node/bin`. -To install the `oasis-node` binary for the current user, copy/symlink it to `~/.local/bin`. +To install the `oasis-node` binary for the current user, copy/symlink it to +`~/.local/bin`. -To install the `oasis-node` binary for all users of the system, copy it to `/usr/local/bin`. +To install the `oasis-node` binary for all users of the system, copy it to +`/usr/local/bin`. ## Running ParaTimes -If you intend to [run a ParaTime node](../paratime-node.mdx) you will need to additionally install the following software packages: +If you intend to [run a ParaTime node](../paratime-node.mdx) you will need to +additionally install the following software packages: -* [Bubblewrap](https://github.com/projectatomic/bubblewrap) 0.4.1+, needed for creating process sandboxes. +* [Bubblewrap](https://github.com/projectatomic/bubblewrap) 0.4.1+, needed for + creating process sandboxes. On Ubuntu 20.04+, you can install it with: - ```text + ```shell sudo apt install bubblewrap ``` On Fedora, you can install it with: - ```text + ```shell sudo dnf install bubblewrap ``` diff --git a/docs/node/run-your-node/validator-node.mdx b/docs/node/run-your-node/validator-node.mdx index a79658adb3..b086f8e003 100644 --- a/docs/node/run-your-node/validator-node.mdx +++ b/docs/node/run-your-node/validator-node.mdx @@ -29,10 +29,6 @@ use a [hardware wallet] as a secure storage, such as [Ledger]. [Start the Oasis Node](#starting-the-oasis-node). The server needs to meet the hardware requirements and have access to the internet. -[create your entity]: #creating-your-entity -[set up the server in order to start the Oasis node]: - #running-an-oasis-node-on-the-server - 3. Finally, we will [stake assets to your entity, register it on the network, and attach the unique ID](#staking-and-registering) of the Oasis Node instance running on your server. @@ -146,53 +142,12 @@ Now, we can move on to configuring our Oasis node with the freshly generated [`oasis wallet import-file`]: ../../general/manage-tokens/cli/wallet.md#import-file [`oasis account entity init`]: ../../general/manage-tokens/cli/account.md#entity-init -## Starting the Oasis Node - -### Setting up the Oasis Node's Working Directory - -Before we run the node on the `server` we need to ensure that we have a place to -store necessary files for the node. - -:::info - -We will reference the working directory on the `server` as `/node` -throughout the documentation. - -::: - -#### Setting Up the the `/node` Directory - -We will reference the working directory on the `server` as `/node` (with -subdirectories `/node/{etc,bin,runtimes,data}`) throughout the documentation. -In the `/node` directory, create the following subdirectories: - -* `etc/`: this is to store the configuration and `entity.json` -* `data/`: this is to store the node's data -* `bin/`: this is to store the `oasis-node` binary -* `runtimes/`: this is to store the ParaTime `.orc` bundles - -You can make this directory structure by executing the following command: - -```shell -mkdir -m700 -p /node/{etc,bin,runtimes,data} -``` +### Copy the Public Entity File Descriptor to `server` -#### Copying the Public Entity Artifacts from `/localhostdir` +The Oasis node needs access to the public key of your entity. Copy your +`entity.json` to `/node/etc/entity.json` on the `server`. -We will also need to have the public entity artifacts from the `/localhostdir` -present on the `server`. Copy the `/localhostdir/entity/entity.json` file on -`localhost` to `/node/etc/entity.json` on the `server`. - -#### Copying the Genesis File to the server - -The latest Genesis file can be found in the Network Parameters page ([Mainnet], -[Testnet]). You should download the latest `genesis.json` file and -copy it to `/node/etc/genesis.json` on the `server`. - -[Mainnet]: ../mainnet/README.md -[Testnet]: ../testnet/README.md - -#### Configuring the Oasis Node +## Configuration There are a variety of options available when running an Oasis node. The following YAML file is a basic configuration for a validator node on the @@ -294,16 +249,31 @@ consensus: - "{{ seed_node_address }}" ``` -#### Starting Oasis Node for the First Time +## Starting the Oasis Node -Execute the Oasis node and pass the config file above by invoking: +You can start the node by simply running the command: ```shell oasis-node --config /node/etc/config.yml ``` -After the node starts, it will automatically register itself to the peer-to-peer -network. The following files will be generated in your `/node/data` folder: +:::tip + +The Oasis node is configured to run in the foreground by default. + +We recommend that you configure and use it with a process manager like +[systemd](https://github.com/systemd/systemd) or +[Supervisor](http://supervisord.org). Check out the [System Configuration] +page for examples. + +::: + +### Node Keys + +The Oasis node requires **node keys** in order to register itself and to +securely communicate with other nodes in the peer-to-peer network. The following +keys will automatically be generated and stored in your `/node/data` folder +as `.pem` files: * `consensus.pem`: The node's consensus private key. **DO NOT SHARE** * `consensus_pub.pem`: The node's consensus public key. @@ -316,59 +286,51 @@ network. The following files will be generated in your `/node/data` folder: * `sentry_client_tls_identity_cert.pem`: The node's TLS certificate for communicating with sentry nodes. -#### Ensuring Proper Permissions - -Only the owner of the process that runs the Oasis node should have access to the -files in the `/node/data` directory. The `oasis-node` binary ensures that -the files used by the node are as least privileged as possible so that you don't -accidentally shoot yourself in the foot while operating a node. - -To ensure proper permissions are set, we suggest running the following to remove -all non-owner read/write/execute permissions: - -```shell -chmod -R go-r,go-w,go-x /node -``` - :::info -Just so it's clear, the following permissions are expected by the `oasis-node` -binary: - -* `700` for the `/node/data` directory -* `700` for the `/node/etc` directory -* `600` for all `/node/data/*.pem` files +If the node keys do not exist, they will be automatically generated when you +launch the Oasis node. Otherwise, the existing ones will be used. ::: :::caution -You may have noticed that some of these files were listed as **DO NOT SHARE** in -the [Initializing a Node](#initializing-a-node) section. +You may have noticed that some files above are listed as **DO NOT SHARE**. -In the future, these keys should be generated and referenced from an HSM. -However, until HSM support is implemented, these keys should be kept as secure -as possible on the `server`. +Ideally, the node keys should be stored on a separate device such as a +[hardware wallet] or a [remote signer]. However, until the support is +fully implemented, keep the keys on the `server` as secure as possible. ::: -### Starting the Oasis Node +[System Configuration]: prerequisites/system-configuration.mdx#change-to-non-root -You can start the node by running the following command: +### Ensuring Proper Permissions -```shell -oasis-node --config /node/etc/config.yml -``` +Only the owner of the process that runs the Oasis node should have access to the +files in the `/node/data` directory. The `oasis-node` binary ensures that +the files used by the node are as least privileged as possible so that you don't +accidentally shoot yourself in the foot while operating a node. -:::tip +If you followed the steps described in the +[Install the Oasis Node][Oasis node binary] chapter, then the proper permissions +are already set: -The Oasis node is configured to run in the foreground by default. +* `700` for the `/node/data` directory +* `700` for the `/node/etc` directory +* `700` for the `/node/runtimes` directory +* `600` for all `/node/data/*.pem` files -We recommend you configure and use it with a process manager like [systemd](https://github.com/systemd/systemd) or [Supervisor](http://supervisord.org). +Otherwise, run the following to remove all non-owner read/write/execute +permissions: -::: +```shell +chmod -R go-r,go-w,go-x /node +``` + +[remote signer]: advanced/remote-signer.mdx -### Obtaining the node ID +### Obtain the Node ID Now that the Oasis node is running, you can obtain your unique node ID which is needed in order to associate your node with your entity in the network registry. @@ -381,7 +343,7 @@ oasis-node control status -a unix:/node/data/internal.sock | jq .identity.node "5MsgQwijUlpH9+0Hbyors5jwmx7tTmKMA4c9leV3prI=" ``` -### Check that your node is synced +### Check that your Node is Synced Before you can become a validator, you will have to make sure that your node is synced. To do so call this command on the server: @@ -433,10 +395,10 @@ oasis account delegate 200 my_entity --no-paratime --account my_funding_account [`oasis account delegate`]: ../../general/manage-tokens/cli/account.md#delegate -### Adding your Node ID to the Entity Descriptor +### Add your Node ID to the Entity Descriptor Now we can register our entity on the network and associate it with the node ID -obtained in the [section above](#obtaining-the-node-id). Open the `entity.json` +obtained in the [section above](#obtain-the-node-id). Open the `entity.json` file we initially generated and add the ID inside the `nodes` block. Your entity descriptor file should now look like this: @@ -461,7 +423,7 @@ oasis account entity register entity.json --account my_entity [`oasis account entity register`]: ../../general/manage-tokens/cli/account.md#entity-register -### Checking that Your Node is Properly Registered +### Check that Your Node is Properly Registered To ensure that your node is properly connected as a validator on the network, invoke the following command on your `server`: diff --git a/docs/oasis-core-ledger b/docs/oasis-core-ledger deleted file mode 120000 index da39005393..0000000000 --- a/docs/oasis-core-ledger +++ /dev/null @@ -1 +0,0 @@ -../external/oasis-core-ledger/docs \ No newline at end of file diff --git a/external/cli b/external/cli index 6b400a2e6f..92744e34ca 160000 --- a/external/cli +++ b/external/cli @@ -1 +1 @@ -Subproject commit 6b400a2e6ffab8b9e26989610e0f86421c3cbea1 +Subproject commit 92744e34cafbc62f9ffaacb27ea260b965570589 diff --git a/external/oasis-core-ledger b/external/oasis-core-ledger deleted file mode 160000 index 67060bdf75..0000000000 --- a/external/oasis-core-ledger +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 67060bdf75b28b1fc5f868ca62f03687e4153fcb diff --git a/redirects.js b/redirects.js index 0450333cdf..9607f5f8a4 100644 --- a/redirects.js +++ b/redirects.js @@ -129,6 +129,19 @@ const redirectsOptions = { to: '/general/manage-tokens/', from: '/general/manage-tokens/overview', // #200 Restructure docs }, + { + to: '/general/manage-tokens/holding-rose-tokens/ledger-wallet/', + from: [ + '/oasis-core-ledger', // #626 Deprecate oasis-core-ledger + '/oasis-core-ledger/usage/setup', // #626 Deprecate oasis-core-ledger + '/oasis-core-ledger/usage/address', // #626 Deprecate oasis-core-ledger + '/oasis-core-ledger/usage/entity', // #626 Deprecate oasis-core-ledger + '/oasis-core-ledger/usage/transactions', // #626 Deprecate oasis-core-ledger + '/oasis-core-ledger/usage/wallets', // #626 Deprecate oasis-core-ledger + '/oasis-core-ledger/versioning', // #626 Deprecate oasis-core-ledger + '/oasis-core-ledger/release-process', // #626 Deprecate oasis-core-ledger + ] + }, { to: '/general/oasis-network/', from: '/general/oasis-network/overview', // #200 Restructure docs @@ -161,6 +174,13 @@ const redirectsOptions = { to: '/node/genesis-doc', from: '/general/oasis-network/genesis-doc', // #200 Restructure docs }, + { + to: '/node/run-your-node/advanced/remote-signer', + from: [ + '/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer', // #626 Deprecate oasis-core-ledger + '/node/run-your-node/advanced/install-oasis-remote-signer-binary', // #626 Deprecate oasis-core-ledger + ], + }, { to: '/node/run-your-node/ias-proxy', from: '/general/run-a-node/set-up-your-node/run-an-ias-proxy', // #200 Restructure docs diff --git a/sidebarCore.js b/sidebarCore.js index f095d231ef..9a29c804da 100644 --- a/sidebarCore.js +++ b/sidebarCore.js @@ -157,11 +157,6 @@ const sidebars = { }, ], }, - { - type: 'link', - label: 'Oasis Core Ledger', - href: '/oasis-core-ledger' - }, { type: 'link', label: 'ADRs', diff --git a/sidebarNode.js b/sidebarNode.js index bae7db0d6d..05a3961f31 100644 --- a/sidebarNode.js +++ b/sidebarNode.js @@ -121,8 +121,7 @@ const sidebars = { items: [ 'node/run-your-node/advanced/sync-node-using-state-sync', 'node/run-your-node/advanced/copy-state-from-one-node-to-the-other', - 'node/run-your-node/advanced/install-oasis-remote-signer-binary', - 'node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer', + 'node/run-your-node/advanced/remote-signer', ] }, 'node/run-your-node/troubleshooting', diff --git a/sidebarOasisCoreLedger.js b/sidebarOasisCoreLedger.js deleted file mode 100644 index f01970fe04..0000000000 --- a/sidebarOasisCoreLedger.js +++ /dev/null @@ -1,35 +0,0 @@ -// @ts-check - -/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ -const sidebars = { - oasisSdk: [ - { - type: 'doc', - label: 'Introduction to Oasis Core Ledger', - id: 'oasis-core-ledger/README', - }, - { - type: 'category', - label: 'Usage', - collapsible: false, - items: [ - 'oasis-core-ledger/usage/setup', - 'oasis-core-ledger/usage/address', - 'oasis-core-ledger/usage/entity', - 'oasis-core-ledger/usage/transactions', - 'oasis-core-ledger/usage/wallets', - ], - }, - { - type: 'category', - label: 'Processes', - collapsible: false, - items: [ - 'oasis-core-ledger/versioning', - 'oasis-core-ledger/release-process', - ], - }, - ], -}; - -module.exports = sidebars; diff --git a/sidebars.js b/sidebars.js index b06ca87f11..6735f3eee1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -7,7 +7,6 @@ const sidebars = { ...require('./sidebarDapp.js'), ...require('./sidebarParatime.js'), ...require('./sidebarCore.js'), - ...require('./sidebarOasisCoreLedger.js'), ...require('./sidebarAdrs.js'), ...require('./sidebarGetInvolved.js'), }; diff --git a/src/editUrl.js b/src/editUrl.js index 6e74ffeb8f..1b15c6c689 100644 --- a/src/editUrl.js +++ b/src/editUrl.js @@ -6,7 +6,6 @@ const gitModules = { 'external/adrs/': 'https://github.com/oasisprotocol/adrs/{mode}/main/', 'external/cli/': 'https://github.com/oasisprotocol/cli/{mode}/master/', 'external/oasis-core/': 'https://github.com/oasisprotocol/oasis-core/{mode}/stable/22.2.x/', - 'external/oasis-core-ledger/': 'https://github.com/oasisprotocol/oasis-core-ledger/{mode}/master/', 'external/oasis-sdk/': 'https://github.com/oasisprotocol/oasis-sdk/{mode}/main/', }; diff --git a/src/remark/cross-repo-links.js b/src/remark/cross-repo-links.js index 172bf78208..83a0bd3501 100644 --- a/src/remark/cross-repo-links.js +++ b/src/remark/cross-repo-links.js @@ -4,7 +4,6 @@ const cliRegex = /https:\/\/github\.com\/oasisprotocol\/cli\/blob\/master\/docs\ const oasisSdkContractRegex = /https:\/\/github\.com\/oasisprotocol\/oasis-sdk\/blob\/main\/docs\/contract\/(.*)\.mdx?(#.*)?/; const oasisSdkRuntimeRegex = /https:\/\/github\.com\/oasisprotocol\/oasis-sdk\/blob\/main\/docs\/runtime\/(.*)\.mdx?(#.*)?/; const oasisCoreRegex = /https:\/\/github\.com\/oasisprotocol\/oasis-core\/blob\/master\/docs\/(.*)\.mdx?(#.*)?/; -const oasisCoreLedgerRegex = /https:\/\/github\.com\/oasisprotocol\/oasis-core-ledger\/blob\/master\/docs\/(.*)\.mdx?(#.*)?/; const adrsRegex = /https:\/\/github\.com\/oasisprotocol\/adrs\/blob\/main\/(.*)\.mdx?(#.*)?/; const docsRegex = /https:\/\/github\.com\/oasisprotocol\/docs\/blob\/main\/docs\/(.*)\.mdx?(#.*)?/; @@ -32,8 +31,6 @@ module.exports = function (options) { node.url = node.url.replace(cliRegex, '/general/manage-tokens/cli/$1$2'); } else if (oasisCoreRegex.test(node.url)) { node.url = node.url.replace(oasisCoreRegex, '/core/$1$2'); - } else if (oasisCoreLedgerRegex.test(node.url)) { - node.url = node.url.replace(adrsRegex, '/oasis-core-ledger/$1$2'); } else if (adrsRegex.test(node.url)) { node.url = node.url.replace(adrsRegex, '/adrs/$1$2'); } else if (docsRegex.test(node.url)) {