lighthouse/book/src/advanced-datadir.md

Custom Data Directories

Users can override the default Lighthouse data directories (e.g., ~/.lighthouse/mainnet) using the --datadir flag. The custom data directory mirrors the structure of any network specific default directory (e.g. ~/.lighthouse/mainnet).

Note: Users should specify different custom directories for different networks.

Below is an example flow for importing validator keys, running a beacon node and validator client using a custom data directory /var/lib/my-custom-dir for the Mainnet network.

lighthouse --network mainnet --datadir /var/lib/my-custom-dir account validator import --directory <PATH-TO-LAUNCHPAD-KEYS-DIRECTORY>
lighthouse --network mainnet --datadir /var/lib/my-custom-dir bn --staking
lighthouse --network mainnet --datadir /var/lib/my-custom-dir vc

The first step creates a validators directory under /var/lib/my-custom-dir which contains the imported keys and validator_definitions.yml. After that, we simply run the beacon chain and validator client with the custom dir path.

Relative Paths

Prior to the introduction of #2682 and #2846 (releases v2.0.1 and earlier), Lighthouse would not correctly parse relative paths from the lighthouse bn --datadir flag.

If the user provided a relative path (e.g., --datadir here or --datadir ./here), the beacon directory would be split across two paths:

1. ~/here (in the home directory), containing:
   • chain_db
   • freezer_db
2. ./here (in the present working directory), containing:
   • logs
   • network

All versions released after the fix (#2846) will default to storing all files in the present working directory (i.e. ./here). New users need not be concerned with the old behaviour.

For existing users which already have a split data directory, a backwards compatibility feature will be applied. On start-up, if a split directory scenario is detected (i.e. ~/here exists), Lighthouse will continue to operate with split directories. In such a scenario, the following harmless log will show:

WARN Legacy datadir location    location: "/home/user/datadir/beacon", msg: this occurs when using relative paths for a datadir location

In this case, the user could solve this warn by following these steps:

1. Stopping the BN process
2. Consolidating the legacy directory with the new one:
   • mv /home/user/datadir/beacon/* $(pwd)/datadir/beacon
   • Where $(pwd) is the present working directory for the Lighthouse binary
3. Removing the legacy directory:
   • rm -r /home/user/datadir/beacon
4. Restarting the BN process

Although there are no known issues with using backwards compatibility functionality, having split directories is likely to cause confusion for users. Therefore, we recommend affected users migrate to a consolidated directory structure.