Document --version-compatibility-protection (#1526)

hyperledger · Mar 6, 2024 · 499c416 · 499c416
1 parent 663d6c0
commit 499c416
Show file tree

Hide file tree

Showing 6 changed files with 61 additions and 14 deletions.
diff --git a/docs/private-networks/how-to/backup.md b/docs/private-networks/how-to/backup.md
@@ -8,7 +8,7 @@ tags:
 
 # Backup and restore Besu
 
-In a decentralized blockchain, data replicates between nodes so it's not lost. But backing up configuration and data ensures a smoother recovery from corrupted data or other failures.
+In a decentralized blockchain, data replicates between nodes so it is not lost. But backing up configuration and data ensures a smoother recovery from corrupted data or other failures.
 
 ## Genesis file
 
@@ -42,6 +42,13 @@ If log messages signify a corrupt database, the cleanest way to recover is:
 1. Restore the data from a [previous backup](#data-backups).
 1. Restart the node.
 
+## Prevent accidental downgrade
+
+When restarting Besu, accidentally using an earlier version of Besu might risk corrupting your database.
+To protect against incompatibility between versions, set the
+[`--version-compatibility-protection`](../../public-networks/reference/cli/options.md#version-compatibility-protection)
+option to `true`.
+
 ## Find peers after restarting
 
 The process for finding peers after restarting is the same as for [finding peers after upgrading and restarting].

diff --git a/docs/private-networks/reference/api/index.md b/docs/private-networks/reference/api/index.md
@@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem';
 
 # Private network API methods
 
-:::warning
+:::caution Important
 
 - This reference contains API methods that apply to only private networks. For API methods that apply to both private and public networks, see the [public network API reference](../../../public-networks/reference/api/index.md).
 - All JSON-RPC HTTP examples use the default host and port endpoint `http://127.0.0.1:8545`. If using the [--rpc-http-host](../../../public-networks/reference/cli/options.md#rpc-http-host) or [--rpc-http-port](../../../public-networks/reference/cli/options.md#rpc-http-port) options, update the endpoint.

diff --git a/docs/private-networks/reference/api/objects.md b/docs/private-networks/reference/api/objects.md
@@ -10,7 +10,7 @@ tags:
 
 The following objects are parameters for or returned by Besu private network API methods.
 
-:::warning
+:::caution Important
 
 This reference contains API objects that apply to only private networks. For API objects that apply to both private and public networks, see the [public network API objects reference](../../../public-networks/reference/api/objects.md).
 

diff --git a/docs/private-networks/reference/cli/options.md b/docs/private-networks/reference/cli/options.md
@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
 
 This reference describes the syntax of the Hyperledger Besu private network command line interface (CLI) options.
 
-:::danger
+:::caution Important
 
 This reference contains options that apply to only private networks. For options that apply to both private and public networks, see the [public network options reference](../../../public-networks/reference/cli/options.md).
 

diff --git a/docs/private-networks/reference/cli/subcommands.md b/docs/private-networks/reference/cli/subcommands.md
@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
 
 This reference describes the syntax of the Hyperledger Besu private network command line interface (CLI) subcommands.
 
-:::danger
+:::caution Important
 
 This reference contains subcommands that apply to only private networks. For subcommands that apply to both private and public networks, see the [public network subcommands reference](../../../public-networks/reference/cli/subcommands.md).
 

diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md
@@ -5426,43 +5426,83 @@ content if the save and restore functionality is enabled using
 The file is created on shutdown and reloaded during startup.
 The default file name is `txpool.dump` in the [data directory](#data-path).
 
-### `Xhelp`
+### `version`
 
 <Tabs>
 
 <TabItem value="Syntax" label="Syntax" default>
 
 ```bash
--X, --Xhelp
+-V, --version
 ```
 
 </TabItem>
 
 </Tabs>
 
-Displays the early access options and their descriptions, and exit.
+Prints version information and exits.
 
-:::caution
+### `version-compatibility-protection`
 
-The displayed options are unstable and may change between releases.
+<Tabs>
+<TabItem value="Syntax">
 
-:::
+```bash
+--version-compatibility-protection[=<true|false>]
+```
 
-### `version`
+</TabItem>
+<TabItem value="Example">
+
+```bash
+--version-compatibility-protection=true
+```
+
+</TabItem>
+<TabItem value="Environment variable">
+
+```bash
+BESU_VERSION_COMPATIBILITY_PROTECTION=true
+```
+
+</TabItem>
+<TabItem value="Configuration file">
+
+```bash
+version-compatibility-protection=true
+```
+
+</TabItem>
+</Tabs>
+
+Enables or disables performing version compatibility checks when starting Besu.
+If set to `true`, it checks that the version of Besu being started is the same
+or later than the version of Besu that previously started with the same data directory.
+
+The default is `false` for named networks, such as Mainnet or Goerli, and `true`
+for non-named networks.
+
+### `Xhelp`
 
 <Tabs>
 
 <TabItem value="Syntax" label="Syntax" default>
 
 ```bash
--V, --version
+-X, --Xhelp
 ```
 
 </TabItem>
 
 </Tabs>
 
-Prints version information and exit.
+Displays the early access options and their descriptions, and exits.
+
+:::caution
+
+The displayed options are unstable and may change between releases.
+
+:::
 
 <!-- Links -->