gaspersic/solana
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs cleanup (#16964)

Browse Source 
* Run lint:fix on docs

* Update dependencies

* Run prettier

* Run lint
This commit is contained in:
Justin Starry
2021-04-30 16:20:56 +08:00
committed by GitHub
parent 3d98321b38
commit 545e037e38
53 changed files with 23895 additions and 5418 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/src/running-validator/restart-cluster.md
View File

@@ -2,11 +2,10 @@
### Step 1. Identify the slot that the cluster will be restarted at
The highest optimistically confirmed slot is the best slot to start from, which
can be found by looking for
[this](https://github.com/solana-labs/solana/blob/0264147d42d506fb888f5c4c021a998e231a3e74/core/src/optimistic_confirmation_verifier.rs#L71)
metrics datapoint. Otherwise use the last root.
metrics datapoint. Otherwise use the last root.
Call this slot `SLOT_X`
@@ -22,7 +21,7 @@ $ solana-ledger-tool -l ledger create-snapshot SLOT_X ledger --hard-fork SLOT_X
The ledger directory should now contain the new snapshot.
`solana-ledger-tool create-snapshot` will also output the new shred version, and bank hash value,
call this NEW\_SHRED\_VERSION and NEW\_BANK\_HASH respectively.
call this NEW_SHRED_VERSION and NEW_BANK_HASH respectively.
Adjust your validator's arguments:
@@ -44,9 +43,9 @@ Post something like the following to #announcements (adjusting the text as appro
> We've released v1.1.12 and are ready to get testnet back up again.
>
> Steps:
>
> 1. Install the v1.1.12 release: https://github.com/solana-labs/solana/releases/tag/v1.1.12
> 2.
> a. Preferred method, start from your local ledger with:
> 2. a. Preferred method, start from your local ledger with:
>
> ```bash
> solana-validator
@@ -61,7 +60,9 @@ Post something like the following to #announcements (adjusting the text as appro
> --limit-ledger-size
> ... # <-- your other --identity/--vote-account/etc arguments
> ```
> b. If your validator doesn't have ledger up to slot SLOT_X or if you have deleted your ledger, have it instead download a snapshot with:
>
> b. If your validator doesn't have ledger up to slot SLOT_X or if you have deleted your ledger, have it instead download a snapshot with:
>
> ```bash
> solana-validator
> --wait-for-supermajority SLOT_X # <-- NEW! IMPORTANT! REMOVE AFTER THIS RESTART
@@ -80,7 +81,7 @@ Post something like the following to #announcements (adjusting the text as appro
>
> To confirm your restarted validator is correctly waiting for the 80%:
> a. Look for `N% of active stake visible in gossip` log messages
> b. Ask it over RPC what slot it's on: `solana --url http://127.0.0.1:8899 slot`. It should return `SLOT_X` until we get to 80% stake
> b. Ask it over RPC what slot it's on: `solana --url http://127.0.0.1:8899 slot`. It should return `SLOT_X` until we get to 80% stake
>
> Thanks!

8
docs/src/running-validator/validator-reqs.md
View File

@@ -17,7 +17,7 @@ transaction for each block the validator agrees with, which can cost up to
- 12 cores / 24 threads, or more
- 2.8GHz, or faster
- AVX2 instruction support (to use official release binaries, self-compile
otherwise)
otherwise)
- Support for AVX512f and/or SHA-NI instructions is helpful
- The AMD Threadripper Zen3 series is popular with the validator community
- RAM
@@ -29,14 +29,14 @@ otherwise)
- Ledger: 1TB or larger. High TBW suggested
- OS: (Optional) 500GB, or larger. SATA OK
- The OS may be installed on the ledger disk, though testing has shown better
performance with the ledger on its own disk
performance with the ledger on its own disk
- Accounts and ledger _can_ be stored on the same disk, however due to high
IOPS, this is not recommended
IOPS, this is not recommended
- The Samsung 970 and 980 Pro series SSDs are popular with the validator community
- GPUs
- Not strictly necessary at this time
- Motherboard and power supply speced to add one or more high-end GPUs in the
future suggested
future suggested
## Virtual machines on Cloud Platforms

54
docs/src/running-validator/validator-start.md
View File

@@ -47,12 +47,14 @@ that CUDA is enabled: `"[<timestamp> solana::validator] CUDA is enabled"`
## System Tuning
### Linux
#### Automatic
The solana repo includes a daemon to adjust system settings to optimize performance
(namely by increasing the OS UDP buffer and file mapping limits).
The daemon (`solana-sys-tuner`) is included in the solana binary release. Restart
it, *before* restarting your validator, after each software upgrade to ensure that
it, _before_ restarting your validator, after each software upgrade to ensure that
the latest recommended settings are applied.
To run it:
@@ -62,10 +64,12 @@ sudo solana-sys-tuner --user $(whoami) > sys-tuner.log 2>&1 &
```
#### Manual
If you would prefer to manage system settings on your own, you may do so with
the following commands.
##### **Increase UDP buffers**
```bash
sudo bash -c "cat >/etc/sysctl.d/20-solana-udp-buffers.conf <<EOF
# Increase UDP buffer size
@@ -75,39 +79,50 @@ net.core.wmem_default = 134217728
net.core.wmem_max = 134217728
EOF"
```
```bash
sudo sysctl -p /etc/sysctl.d/20-solana-udp-buffers.conf
```
##### **Increased memory mapped files limit**
```bash
sudo bash -c "cat >/etc/sysctl.d/20-solana-mmaps.conf <<EOF
# Increase memory mapped files limit
vm.max_map_count = 700000
EOF"
```
```bash
sudo sysctl -p /etc/sysctl.d/20-solana-mmaps.conf
```
Add
```
LimitNOFILE=700000
```
to the `[Service]` section of your systemd service file, if you use one,
otherwise add
```
DefaultLimitNOFILE=700000
```
to the `[Manager]` section of `/etc/systemd/system.conf`.
```bash
sudo systemctl daemon-reload
```
```bash
sudo bash -c "cat >/etc/security/limits.d/90-solana-nofiles.conf <<EOF
# Increase process file descriptor count limit
* - nofile 700000
EOF"
```
```bash
### Close all open sessions (log out then, in again) ###
```
@@ -299,24 +314,27 @@ example, `solana-validator --dynamic-port-range 11000-11010 ...` will restrict
the validator to ports 11000-11010.
### Limiting ledger size to conserve disk space
The `--limit-ledger-size` parameter allows you to specify how many ledger
[shreds](../terminology.md#shred) your node retains on disk. If you do not
include this parameter, the validator will keep the entire ledger until it runs
out of disk space.
The default value attempts to keep the ledger disk usage under 500GB. More or
The default value attempts to keep the ledger disk usage under 500GB. More or
less disk usage may be requested by adding an argument to `--limit-ledger-size`
if desired. Check `solana-validator --help` for the default limit value used by
`--limit-ledger-size`. More information about
`--limit-ledger-size`. More information about
selecting a custom limit value is [available
here](https://github.com/solana-labs/solana/blob/583cec922b6107e0f85c7e14cb5e642bc7dfb340/core/src/ledger_cleanup_service.rs#L15-L26).
### Systemd Unit
Running the validator as a systemd unit is one easy way to manage running in the
background.
Assuming you have a user called `sol` on your machine, create the file `/etc/systemd/system/sol.service` with
the following:
```
[Unit]
Description=Solana Validator
@@ -339,15 +357,17 @@ WantedBy=multi-user.target
```
Now create `/home/sol/bin/validator.sh` to include the desired `solana-validator`
command-line. Ensure that running `/home/sol/bin/validator.sh` manually starts
command-line. Ensure that running `/home/sol/bin/validator.sh` manually starts
the validator as expected. Don't forget to mark it executable with `chmod +x /home/sol/bin/validator.sh`
Start the service with:
```bash
$ sudo systemctl enable --now sol
```
### Logging
#### Log output tuning
The messages that a validator emits to the log can be controlled by the `RUST_LOG`
@@ -376,6 +396,7 @@ instead of the validator's, which will kill them both.
An example setup for the `logrotate`, which assumes that the validator is
running as a systemd service called `sol.service` and writes a log file at
/home/sol/solana-validator.log:
```bash
# Setup log rotation
@@ -394,11 +415,13 @@ systemctl restart logrotate.service
```
### Disable port checks to speed up restarts
Once your validator is operating normally, you can reduce the time it takes to
restart your validator by adding the `--no-port-check` flag to your
`solana-validator` command-line.
### Disable snapshot compression to reduce CPU usage
If you are not serving snapshots to other validators, snapshot compression can
be disabled to reduce CPU load at the expense of slightly more disk usage for
local snapshot storage.
@@ -407,6 +430,7 @@ Add the `--snapshot-compression none` argument to your `solana-validator`
command-line arguments and restart the validator.
### Using a ramdisk with spill-over into swap for the accounts database to reduce SSD wear
If your machine has plenty of RAM, a tmpfs ramdisk
([tmpfs](https://man7.org/linux/man-pages/man5/tmpfs.5.html)) may be used to hold
the accounts database
@@ -418,18 +442,20 @@ A 300GB tmpfs partition is recommended, with an accompanying 250GB swap
partition.
Example configuration:
1. `sudo mkdir /mnt/solana-accounts`
2. Add a 300GB tmpfs parition by adding a new line containing `tmpfs
/mnt/solana-accounts tmpfs rw,size=300G,user=sol 0 0` to `/etc/fstab`
(assuming your validator is running under the user "sol"). **CAREFUL: If you
2. Add a 300GB tmpfs parition by adding a new line containing `tmpfs /mnt/solana-accounts tmpfs rw,size=300G,user=sol 0 0` to `/etc/fstab`
(assuming your validator is running under the user "sol"). **CAREFUL: If you
incorrectly edit /etc/fstab your machine may no longer boot**
3. Create at least 250GB of swap space
- Choose a device to use in place of `SWAPDEV` for the remainder of these instructions.
Ideally select a free disk partition of 250GB or greater on a fast disk. If one is not
available, create a swap file with `sudo dd if=/dev/zero of=/swapfile bs=1MiB count=250KiB`,
set its permissions with `sudo chmod 0600 /swapfile` and use `/swapfile` as `SWAPDEV` for
the remainder of these instructions
- Format the device for usage as swap with `sudo mkswap SWAPDEV`
- Choose a device to use in place of `SWAPDEV` for the remainder of these instructions.
Ideally select a free disk partition of 250GB or greater on a fast disk. If one is not
available, create a swap file with `sudo dd if=/dev/zero of=/swapfile bs=1MiB count=250KiB`,
set its permissions with `sudo chmod 0600 /swapfile` and use `/swapfile` as `SWAPDEV` for
the remainder of these instructions
- Format the device for usage as swap with `sudo mkswap SWAPDEV`
4. Add the swap file to `/etc/fstab` with a new line containing `SWAPDEV swap swap defaults 0 0`
5. Enable swap with `sudo swapon -a` and mount the tmpfs with `sudo mount /mnt/solana-accounts/`
6. Confirm swap is active with `free -g` and the tmpfs is mounted with `mount`
@@ -440,7 +466,7 @@ command-line arguments and restart the validator.
### Account indexing
As the number of populated accounts on the cluster grows, account-data RPC
requests that scan the entire account set -- like
requests that scan the entire account set -- like
[`getProgramAccounts`](developing/clients/jsonrpc-api.md#getprogramaccounts) and
[SPL-token-specific requests](developing/clients/jsonrpc-api.md#gettokenaccountsbydelegate) --
may perform poorly. If your validator needs to support any of these requests,

67
docs/src/running-validator/vote-accounts.md
View File

@@ -2,30 +2,33 @@
title: Vote Account Management
---
This page describes how to set up an on-chain _vote account_. Creating a vote
This page describes how to set up an on-chain _vote account_. Creating a vote
account is needed if you plan to run a validator node on Solana.
## Create a Vote Account
A vote account can be created with the
[create-vote-account](../cli/usage.md#solana-create-vote-account) command.
The vote account can be configured when first created or after the validator is
running. All aspects of the vote account can be changed except for the
running. All aspects of the vote account can be changed except for the
[vote account address](#vote-account-address), which is fixed for the lifetime
of the account.
### Configure an Existing Vote Account
- To change the [validator identity](#validator-identity), use
[vote-update-validator](../cli/usage.md#solana-vote-update-validator).
- To change the [vote authority](#vote-authority), use
[vote-authorize-voter](../cli/usage.md#solana-vote-authorize-voter).
- To change the [withdraw authority](#withdraw-authority), use
[vote-authorize-withdrawer](../cli/usage.md#solana-vote-authorize-withdrawer).
- To change the [commission](#commission), use
[vote-update-commission](../cli/usage.md#solana-vote-update-commission).
- To change the [validator identity](#validator-identity), use
[vote-update-validator](../cli/usage.md#solana-vote-update-validator).
- To change the [vote authority](#vote-authority), use
[vote-authorize-voter](../cli/usage.md#solana-vote-authorize-voter).
- To change the [withdraw authority](#withdraw-authority), use
[vote-authorize-withdrawer](../cli/usage.md#solana-vote-authorize-withdrawer).
- To change the [commission](#commission), use
[vote-update-commission](../cli/usage.md#solana-vote-update-commission).
## Vote Account Structure
### Vote Account Address
A vote account is created at an address that is either the public key of a
keypair file, or at a derived address based on a keypair file's public key and
a seed string.
@@ -44,14 +47,14 @@ vote transaction fees submitted to the vote account.
Because the validator is expected to vote on most valid blocks it receives,
the validator identity account is frequently
(potentially multiple times per second) signing transactions and
paying fees. For this reason the validator identity keypair must be
paying fees. For this reason the validator identity keypair must be
stored as a "hot wallet" in a keypair file on the same system the validator
process is running.
Because a hot wallet is generally less secure than an offline or "cold" wallet,
the validator operator may choose to store only enough SOL on the identity
account to cover voting fees for a limited amount of time, such as a few weeks
or months. The validator identity account could be periodically topped off
or months. The validator identity account could be periodically topped off
from a more secure wallet.
This practice can reduce the risk of loss of funds if the validator node's
@@ -64,8 +67,8 @@ the [vote-update-validator](../cli/usage.md#solana-vote-update-validator) comman
### Vote Authority
The _vote authority_ keypair is used to sign each vote transaction the validator
node wants to submit to the cluster. This doesn't necessarily have to be unique
from the validator identity, as you will see later in this document. Because
node wants to submit to the cluster. This doesn't necessarily have to be unique
from the validator identity, as you will see later in this document. Because
the vote authority, like the validator identity, is signing transactions
frequently, this also must be a hot keypair on the same file system as the
validator process.
@@ -73,22 +76,22 @@ validator process.
The vote authority can be set to the same address as the validator identity.
If the validator identity is also the vote authority, only one
signature per vote transaction is needed in order to both sign the vote and pay
the transaction fee. Because transaction fees on Solana are assessed
the transaction fee. Because transaction fees on Solana are assessed
per-signature, having one signer instead of two will result in half the transaction
fee paid compared to setting the vote authority and validator identity to two
different accounts.
The vote authority can be set when the vote account is created. If it is not
The vote authority can be set when the vote account is created. If it is not
provided, the default behavior is to assign it the same as the validator identity.
The vote authority can be changed later with the
[vote-authorize-voter](../cli/usage.md#solana-vote-authorize-voter) command.
The vote authority can be changed at most once per epoch. If the authority is
The vote authority can be changed at most once per epoch. If the authority is
changed with [vote-authorize-voter](../cli/usage.md#solana-vote-authorize-voter),
this will not take effect until the beginning of the next epoch.
To support a smooth transition of the vote signing,
`solana-validator` allows the `--authorized-voter` argument to be specified
multiple times. This allows the validator process to keep voting successfully
multiple times. This allows the validator process to keep voting successfully
when the network reaches an epoch boundary at which the validator's vote
authority account changes.
@@ -96,7 +99,7 @@ authority account changes.
The _withdraw authority_ keypair is used to withdraw funds from a vote account
using the [withdraw-from-vote-account](../cli/usage.md#solana-withdraw-from-vote-account)
command. Any network rewards a validator earns are deposited into the vote
command. Any network rewards a validator earns are deposited into the vote
account and are only retrievable by signing with the withdraw authority keypair.
The withdraw authority is also required to sign any transaction to change
@@ -108,7 +111,7 @@ the withdraw authority keypair in an offline/cold wallet, as it is
not needed to sign frequent transactions.
The withdraw authority can be set at vote account creation with the
`--authorized-withdrawer` option. If this is not provided, the validator
`--authorized-withdrawer` option. If this is not provided, the validator
identity will be set as the withdraw authority by default.
The withdraw authority can be changed later with the
@@ -118,7 +121,7 @@ command.
### Commission
_Commission_ is the percent of network rewards earned by a validator that are
deposited into the validator's vote account. The remainder of the rewards
deposited into the validator's vote account. The remainder of the rewards
are distributed to all of the stake accounts delegated to that vote account,
proportional to the active stake weight of each stake account.
@@ -129,7 +132,7 @@ will be deposited into delegated stake accounts as immediately active stake.
A validator may choose to set a low commission to try to attract more stake
delegations as a lower commission results in a larger percentage of rewards
passed along to the delegator. As there are costs associated with setting up
passed along to the delegator. As there are costs associated with setting up
and operating a validator node, a validator would ideally set a high enough
commission to at least cover their expenses.
@@ -146,13 +149,14 @@ The integer represents the number of percentage points for the commission, so
creating an account with `--commission 10` will set a 10% commission.
## Key Rotation
Rotating the vote account authority keys require special handling when dealing
with a live validator.
### Vote Account Validator Identity
You will need access to the _withdraw authority_ keypair for the vote account to
change the validator identity. The follow steps assume that
change the validator identity. The follow steps assume that
`~/withdraw-authority.json` is that keypair.
1. Create the new validator identity keypair, `solana-keygen new -o ~/new-validator-keypair.json`.
@@ -162,28 +166,27 @@ change the validator identity. The follow steps assume that
4. Restart your validator with the new identity keypair for the `--identity` argument
### Vote Account Authorized Voter
The _vote authority_ keypair may only be changed at epoch boundaries and
requires some additional arguments to `solana-validator` for a seamless
migration.
1. Run `solana epoch-info`. If there is not much time remaining time in the
1. Run `solana epoch-info`. If there is not much time remaining time in the
current epoch, consider waiting for the next epoch to allow your validator
plenty of time to restart and catch up.
2. Create the new vote authority keypair, `solana-keygen new -o ~/new-vote-authority.json`.
3. Determine the current _vote authority_ keypair by running `solana
vote-account ~/vote-account-keypair.json`. It may be validator's
identity account (the default) or some other keypair. The following steps
assume that ` ~/validator-keypair.json` is that keypair.
3. Determine the current _vote authority_ keypair by running `solana vote-account ~/vote-account-keypair.json`. It may be validator's
identity account (the default) or some other keypair. The following steps
assume that `~/validator-keypair.json` is that keypair.
4. Run `solana vote-authorize-voter ~/vote-account-keypair.json ~/validator-keypair.json ~/new-vote-authority.json`.
The new vote authority is scheduled to become active starting at the next epoch.
5. `solana-validator` now needs to be restarted with the old and new vote
authority keypairs, so that it can smoothly transition at the next epoch. Add
the two arguments on restart: `--authorized-voter ~/validator-keypair.json
--authorized-voter ~/new-vote-authority.json`
the two arguments on restart: `--authorized-voter ~/validator-keypair.json --authorized-voter ~/new-vote-authority.json`
6. After the cluster reaches the next epoch, remove the
`--authorized-voter ~/validator-keypair.json` argument and restart
`solana-validator`, as the old vote authority keypair is no longer required.
### Vote Account Authorized Withdrawer
No special handling is required. Use the `solana vote-authorize-withdrawer` command as needed.
No special handling is required. Use the `solana vote-authorize-withdrawer` command as needed.