Restrict downgrade

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 23.10.4
 
 ### Breaking Changes
+- Protection against accidental downgrade of Besu version to avoid possible data corruption problems. Starting an older version of Besu with a given data directory is now only possible with the `--allow-downgrade` configuration option [6307](https://github.com/hyperledger/besu/pull/6307)
 
 ### Deprecations
 - Forest pruning (`pruning-enabled` options) is deprecated and will be removed soon. To save disk space consider switching to Bonsai data storage format [#6230](https://github.com/hyperledger/besu/pull/6230)

besu/build.gradle

@@ -62,6 +62,7 @@ dependencies {
   implementation 'com.fasterxml.jackson.core:jackson-databind'
   implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8'
   implementation 'com.github.oshi:oshi-core'
+  implementation 'org.apache.maven:maven-artifact'
   implementation 'com.google.guava:guava'
   implementation 'com.google.dagger:dagger'
   implementation 'com.graphql-java:graphql-java'

besu/src/main/java/org/hyperledger/besu/cli/BesuCommand.java

@@ -126,6 +126,7 @@
 import org.hyperledger.besu.ethereum.core.ImmutableMiningParameters;
 import org.hyperledger.besu.ethereum.core.MiningParameters;
 import org.hyperledger.besu.ethereum.core.PrivacyParameters;
+import org.hyperledger.besu.ethereum.core.VersionMetadata;
 import org.hyperledger.besu.ethereum.eth.sync.SyncMode;
 import org.hyperledger.besu.ethereum.eth.sync.SynchronizerConfiguration;
 import org.hyperledger.besu.ethereum.eth.transactions.ImmutableTransactionPoolConfiguration;
@@ -241,6 +242,7 @@
 import io.vertx.core.VertxOptions;
 import io.vertx.core.json.DecodeException;
 import io.vertx.core.metrics.MetricsOptions;
+import org.apache.maven.artifact.versioning.ComparableVersion;
 import org.apache.tuweni.bytes.Bytes;
 import org.apache.tuweni.units.bigints.UInt256;
 import org.jetbrains.annotations.NotNull;
@@ -559,6 +561,12 @@
       arity = "1")
   private final Path kzgTrustedSetupFile = null;
 
+  @Option(
+      names = {"--allow-downgrade"},
+      description =
+          "Allow an older version of Besu to start if it detects that a more recent version has started with this data directory. Warning - this could result in unrecoverable changes to the database so should only be used if a backup of the data has been taken before the downgrade. (default: ${DEFAULT-VALUE})")
+  private Boolean allowDowngrade = false;
+
   @CommandLine.ArgGroup(validate = false, heading = "@|bold GraphQL Options|@%n")
   GraphQlOptionGroup graphQlOptionGroup = new GraphQlOptionGroup();
 
@@ -1458,6 +1466,9 @@
       vertx = createVertx(createVertxOptions(metricsSystem.get()));
 
       validateOptions();
+
+      performDowngradeCheck();
+
       configure();
       configureNativeLibs();
       besuController = initController();
@@ -1481,6 +1492,65 @@
     }
   }
 
+  /**
+   * This function is designed to protect a Besu instance from being unintentionally started at a
+   * lower version than the previous instance. Doing so could cause unexpected data corruption
+   * (depending on the storage provider that is in use), so this check prompts the user if a
+   * downgrade is detected and requires them to opt-in by setting --allow-downgrade. The
+   * --allow-downgrade flag only needs to be passed in once, and then the version information is
+   * updated to the lower version number, meaning future restarts will pass the check.
+   */
+  private void performDowngradeCheck() throws IOException {
+    final VersionMetadata versionMetaData = VersionMetadata.lookUpFrom(dataDir());
+    if (versionMetaData.getBesuVersion().equals(VersionMetadata.BESU_VERSION_UNKNOWN)) {
+      // The version isn't known, potentially because the file doesn't exist. Write the latest
+      // version to the metadata file.
+      logger.info(
+          "No version data detected. Writing Besu version {} to metadata file",
+          VersionMetadata.getRuntimeVersion());
+      new VersionMetadata(VersionMetadata.getRuntimeVersion()).writeToDirectory(dataDir());
+    } else {
+      // Check the runtime version against the most recent version as recorded in the version
+      // metadata file
+      final String installedVersion = VersionMetadata.getRuntimeVersion().split("-", 2)[0];
+      final String metadataVersion = versionMetaData.getBesuVersion().split("-", 2)[0];
+      final int versionComparison =
+          new ComparableVersion(installedVersion).compareTo(new ComparableVersion(metadataVersion));
+      if (versionComparison == 0) {
+        // Versions match - no-op
+      } else if (versionComparison < 0) {
+        if (allowDowngrade) {
+          logger.warn(
+              "Besu version {} is lower than version {} that last started. Allowing startup because --allow-downgrade has been enabled.",
+              installedVersion,
+              metadataVersion);
+          // We've allowed startup at an older version of Besu. Since the version in the metadata
+          // file records the latest version of
+          // Besu to write to the database we'll update the metadata version to this
+          // downgraded-version. This avoids the need after a successful
+          // downgrade to keep specifying --allow-downgrade on every startup.
+          new VersionMetadata(VersionMetadata.getRuntimeVersion()).writeToDirectory(dataDir());
+        } else {
+          final String message =
+              "Besu version "
+                  + installedVersion
+                  + " is lower than version "
+                  + metadataVersion
+                  + " that last started."
+                  + "Specify --allow-downgrade to allow Besu to start at the lower version (warning - this may have unrecoverable effects on the database).";
+          logger.error(message);
+          throw new StorageException(message);
+        }
+      } else {
+        logger.info(
+            "Besu version {} is higher than version {} that last started. Updating version metadata.",
+            installedVersion,
+            metadataVersion);
+        new VersionMetadata(VersionMetadata.getRuntimeVersion()).writeToDirectory(dataDir());
+      }
+    }
+  }
+
   @VisibleForTesting
   void setBesuConfiguration(final BesuConfiguration pluginCommonConfiguration) {
     this.pluginCommonConfiguration = pluginCommonConfiguration;
@@ -3371,6 +3441,16 @@
     return loggingLevelOption.getLogLevel();
   }
 
+  /**
+   * Returns the flag indicating that downgrades are allowed.
+   *
+   * @return true if downgrades are allowed, otherwise false
+   */
+  @VisibleForTesting
+  public Boolean getAllowDowngrade() {
+    return allowDowngrade;
+  }
+
   private class BesuCommandConfigurationService implements BesuConfiguration {
 
     @Override

besu/src/test/java/org/hyperledger/besu/cli/BesuCommandTest.java

@@ -1997,6 +1997,13 @@ public void dnsEnabledOptionIsParsedCorrectly() {
     assertThat(besuCommand.getEnodeDnsConfiguration().updateEnabled()).isFalse();
   }
 
+  @Test
+  public void allowDowngradeTrueOptionIsParsedCorrectly() {
+    final TestBesuCommand besuCommand = parseCommand("--allow-downgrade", "true");
+
+    assertThat(besuCommand.getAllowDowngrade()).isTrue();
+  }
+
   @Test
   public void dnsUpdateEnabledOptionIsParsedCorrectly() {
     final TestBesuCommand besuCommand =

besu/src/test/resources/everything_config.toml

@@ -16,6 +16,7 @@ node-private-key-file="./path/to/privateKey"
 pid-path="~/.pid"
 reorg-logging-threshold=0
 static-nodes-file="~/besudata/static-nodes.json"
+allow-downgrade=true
 
 # Security Module plugin to use
 security-module="localfile"

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/core/VersionMetadata.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright Hyperledger Besu contributors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.ethereum.core;
+
+import java.io.File;
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.nio.file.Path;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class VersionMetadata {
+  private static final Logger LOG = LoggerFactory.getLogger(VersionMetadata.class);
+
+  /** Represents an unknown Besu version in the version metadata file */
+  public static final String BESU_VERSION_UNKNOWN = "UNKNOWN";
+
+  private static final String METADATA_FILENAME = "VERSION_METADATA.json";
+  private static final ObjectMapper MAPPER = new ObjectMapper();
+  private final String besuVersion;
+
+  /**
+   * Get the version of Besu that is running.
+   *
+   * @return the version of Besu
+   */
+  public static String getRuntimeVersion() {
+    return VersionMetadata.class.getPackage().getImplementationVersion();
+  }
+
+  @JsonCreator
+  public VersionMetadata(@JsonProperty("besuVersion") final String besuVersion) {
+    this.besuVersion = besuVersion;
+  }
+
+  public String getBesuVersion() {
+    return besuVersion;
+  }
+
+  public static VersionMetadata lookUpFrom(final Path dataDir) throws IOException {
+    LOG.info("Lookup version metadata file in data directory: {}", dataDir.toString());
+    return resolveVersionMetadata(getDefaultMetadataFile(dataDir));
+  }
+
+  public void writeToDirectory(final Path dataDir) throws IOException {
+    MAPPER.writeValue(getDefaultMetadataFile(dataDir), this);
+  }
+
+  private static File getDefaultMetadataFile(final Path dataDir) {
+    return dataDir.resolve(METADATA_FILENAME).toFile();
+  }
+
+  private static VersionMetadata resolveVersionMetadata(final File metadataFile)
+      throws IOException {
+    VersionMetadata versionMetadata;
+    try {
+      versionMetadata = MAPPER.readValue(metadataFile, VersionMetadata.class);
+      LOG.info("Existing version data detected. Besu version {}", versionMetadata.besuVersion);
+    } catch (FileNotFoundException fnfe) {
+      versionMetadata = new VersionMetadata(BESU_VERSION_UNKNOWN);
+    } catch (JsonProcessingException jpe) {
+      throw new IllegalStateException(
+          java.lang.String.format("Invalid metadata file %s", metadataFile.getAbsolutePath()), jpe);
+    }
+    return versionMetadata;
+  }
+}

ethereum/core/src/test/java/org/hyperledger/besu/ethereum/core/VersionMetadataTest.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright Hyperledger Besu contributors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.hyperledger.besu.ethereum.core;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+class VersionMetadataTest {
+  @TempDir public Path temporaryFolder;
+
+  @Test
+  void getVersion() {
+    final VersionMetadata versionMetadata = new VersionMetadata("23.10.2");
+    assertThat(versionMetadata).isNotNull();
+    assertThat(versionMetadata.getBesuVersion()).isEqualTo("23.10.2");
+  }
+
+  @Test
+  void metaFileShouldContain() throws Exception {
+    final Path tempDataDir =
+        createAndWrite("data", "VERSION_METADATA.json", "{\"besuVersion\":\"23.10.3\"}");
+
+    final VersionMetadata versionMetadata = VersionMetadata.lookUpFrom(tempDataDir);
+    assertThat(versionMetadata).isNotNull();
+    assertThat(versionMetadata.getBesuVersion()).isEqualTo("23.10.3");
+  }
+
+  private Path createAndWrite(final String dir, final String file, final String content)
+      throws IOException {
+    return createAndWrite(temporaryFolder, dir, file, content);
+  }
+
+  private Path createAndWrite(
+      final Path temporaryFolder, final String dir, final String file, final String content)
+      throws IOException {
+    final Path tmpDir = temporaryFolder.resolve(dir);
+    Files.createDirectories(tmpDir);
+    createAndWrite(tmpDir.resolve(file), content);
+    return tmpDir;
+  }
+
+  private void createAndWrite(final Path path, final String content) throws IOException {
+    path.toFile().createNewFile();
+    Files.writeString(path, content);
+  }
+}

gradle/verification-metadata.xml

@@ -3880,11 +3880,29 @@
             <sha256 value="4d223e01a6569d6655c1f4fce84969d45142cdbabdb118ea08c5c8c33ec632f6" origin="Generated by Gradle"/>
          </artifact>
       </component>
+      <component group="org.apache.maven" name="maven" version="3.9.6">
+         <artifact name="maven-3.9.6.pom">
+            <sha256 value="ba0bf325c52954058e9a7029e40273a1fe06be4a50530f6a4eba46c558a1e4ac" origin="Generated by Gradle"/>
+         </artifact>
+      </component>
+      <component group="org.apache.maven" name="maven-artifact" version="3.9.6">
+         <artifact name="maven-artifact-3.9.6.jar">
+            <sha256 value="ad7a0fb408f8e47585ccc0d0011e0b501d93bfc9888d369bbd4a043d19475073" origin="Generated by Gradle"/>
+         </artifact>
+         <artifact name="maven-artifact-3.9.6.pom">
+            <sha256 value="b610a3b025982b98576d7664900ace31362f005827051f3698e649d289f3ffb5" origin="Generated by Gradle"/>
+         </artifact>
+      </component>
       <component group="org.apache.maven" name="maven-parent" version="21">
          <artifact name="maven-parent-21.pom">
             <sha256 value="fc45af8911ea307d1b57564eef1f78b69801e9c11a5619e7eb58d5d00ae9db8e" origin="Generated by Gradle"/>
          </artifact>
       </component>
+      <component group="org.apache.maven" name="maven-parent" version="41">
+         <artifact name="maven-parent-41.pom">
+            <sha256 value="762fcdd4ce8621c5fa0a2cf6495ad26972a8093eb432aa3e402bc2d4e2500c53" origin="Generated by Gradle"/>
+         </artifact>
+      </component>
       <component group="org.apache.maven" name="maven-settings" version="3.0.4">
          <artifact name="maven-settings-3.0.4.jar">
             <sha256 value="3e3df17f5df5e4ce1e7b7f2011c57d61d328e65678542ade2048f0d0fa295f09" origin="Generated by Gradle"/>
@@ -4120,6 +4138,11 @@
             <sha256 value="1472325a16f0b1bdabed21fa4839372964944610294ce2681b2059edc654f2b3" origin="Generated by Gradle"/>
          </artifact>
       </component>
+      <component group="org.codehaus.plexus" name="plexus" version="10">
+         <artifact name="plexus-10.pom">
+            <sha256 value="bba9c521064b9ca132ce97cc1cc7eb4afc2dbe32bc88cb872c88e99f6162301f" origin="Generated by Gradle"/>
+         </artifact>
+      </component>
       <component group="org.codehaus.plexus" name="plexus" version="2.0.6">
          <artifact name="plexus-2.0.6.pom">
             <sha256 value="bea12e747708d25e73410ca1c731ebdfa102e8bdb6ec7d81bd4522583b234bcc" origin="Generated by Gradle"/>
@@ -4169,6 +4192,14 @@
             <sha256 value="fddad4fa62c82310aec43525e519cd59f27d04c7569fe21b1b03ca210887810c" origin="Generated by Gradle"/>
          </artifact>
       </component>
+      <component group="org.codehaus.plexus" name="plexus-utils" version="3.5.1">
+         <artifact name="plexus-utils-3.5.1.jar">
+            <sha256 value="86e0255d4c879c61b4833ed7f13124e8bb679df47debb127326e7db7dd49a07b" origin="Generated by Gradle"/>
+         </artifact>
+         <artifact name="plexus-utils-3.5.1.pom">
+            <sha256 value="94ff68edeb48204d12c99189c767164d3a9f778a1372d1dce11a41462e6236f2" origin="Generated by Gradle"/>
+         </artifact>
+      </component>
       <component group="org.connid" name="connid" version="1.3.2">
          <artifact name="connid-1.3.2.pom">
             <sha256 value="a9d00ba9710f73ca156f8897f27607e639f34f2bb7f7a220068667e20f502bc5" origin="Generated by Gradle"/>

gradle/versions.gradle

@@ -233,5 +233,7 @@ dependencyManagement {
     dependency 'tech.pegasys.discovery:discovery:22.2.0'
 
     dependency 'com.github.oshi:oshi-core:6.4.1'
+
+    dependency 'org.apache.maven:maven-artifact:3.9.6'
   }
 }