5. Configuring LOCKSS 2.x for Migration

A diagram of eight consecutive arrow-shaped boxes, representing from left to right the steps of the migration workflow from LOCKSS 1.x to LOCKSS 2.x. The first three boxes, successively labeled "Upgrading LOCKSS 1.x", "Preparing the LOCKSS 2.x Host", and "Installing LOCKSS 2.x", are colored in light blue, indicating completed steps. The fourth box labeled "Configuring LOCKSS 2.x for Migration" is highlighted in yellow, indicating the step in progress. The last four boxes, successively labeled "Configuring LOCKSS 1.x for Migration", "Running the Migrator", "Reconfiguring LOCKSS 2.x for Normal Operation", and "Decommissioning LOCKSS 1.x", are not colored, indicating future steps.

The next task in the migration process is to configure LOCKSS 2.x for migration on your LOCKSS 2.x host.

5.1. Importing Configuration From LOCKSS 1.x

The first part of this task is to make your LOCKSS 1.x configuration file available to your LOCKSS 2.x instance.

This depends on your Migration Scenario:

If you are doing a New-Host Migration:

  1. Copy the LOCKSS 1.x configuration file from /etc/lockss/config.dat on your LOCKSS 1.x host to some file path on your LOCKSS 2.x host, symbolically represented here as /path/to/lockss1_config_file.dat. Although you can use any path on your LOCKSS 2.x host, we recommend /tmp/v1config.dat.

    For example, you might use scp on your LOCKSS 1.x host:

    scp /etc/lockss/config.dat <username>@<lockss2host>:/path/to/lockss1_config_file.dat

    or something similar.

    If you are unable to copy the LOCKSS 1.x configuration file to your LOCKSS 2.x, you can still configure LOCKSS 2.x for migration, but you will be prompted to supply more information, which you will have to enter accurately from the corresponding LOCKSS 1.x values.

  2. LOCKSS 2.x host as root Ensure that the LOCKSS 1.x configuration file /path/to/lockss1_config_file.dat is readable by all on the LOCKSS 2.x host. For example, you can do this as root on the LOCKSS 2.x host with:

    chmod +r /path/to/lockss1_config_file.dat

If you are doing a Same-Host Migration, the LOCKSS 2.x configuration script will find the LOCKSS 1.x configuration file directly at /etc/lockss/config.dat, so you do not need to do anything in this step.

5.2. Running configure-lockss --migrate

The second part of this task is to run the configure-lockss tool with the --migrate option on your LOCKSS 2.x host.

This will proceed largely as described in Chapter 4 (Configuring LOCKSS) of the LOCKSS 2.x System Manual, but with some notable exceptions described below:

  1. Follow the instructions in Section 4.1 (Gathering Configuration Information) of the LOCKSS 2.x System Manual.

  2. Follow these steps (modified from Section 4.2 of the LOCKSS 2.x System Manual):

    1. LOCKSS 2.x host as lockss Navigate to the LOCKSS Installer Directory, symbolically:

      cd <LOCKSS_INSTALLER_DIR>

    2. LOCKSS 2.x host as lockss Run this command:

  3. Follow the instructions in Section 4.3 (Kubernetes Settings) of the LOCKSS 2.x System Manual.

  4. This step depends on your Migration Scenario:

    If you are doing a New-Host Migration, follow these steps:

    1. You will receive the following prompt:

      Did you copy a LOCKSS 1.x config.dat file to this host?

      Enter Y for "yes" or N for "no", or hit Enter to accept the default in square brackets.

      • If you enter Y for "yes", you will then receive the following prompt:

        Location of copied LOCKSS 1.x config.dat file

        Enter the path of the copied LOCKSS 1.x configuration file, symbolically represented as /path/to/lockss1_config_file.dat above, or hit Enter to accept the default in square brackets (/tmp/v1config.dat).

      • If you enter N for "no", you will have to manually and accurately enter a number of values reflecting your LOCKSS 1.x configuration (instead of the values being imported directly from your copied LOCKSS 1.x configuration file).

    2. Follow all instructions in Section 4.4 (Network Settings) of the LOCKSS 2.x System Manual.

    If you are doing a Same-Host Migration, follow these steps:

    1. You will receive this message:

      Found /etc/lockss/config.dat

      confirming that the LOCKSS 1.x configuration file was detected.

    2. Follow the instructions in the following sections of the LOCKSS 2.x System Manual:

    3. After the LCAP port prompt, you will receive the following prompt:

      Temporary LOCKSS 2.x LCAP port

      Enter an LCAP port different from the one used by LOCKSS 1.x, for use during migration, or hit Enter to accept the suggested value in square brackets.

    4. Follow the instructions in Section 4.4.5 (Network Address Translation) of the LOCKSS 2.x System Manual.

  5. Follow all instructions in the remainder of Chapter 4 of the LOCKSS 2.x System Manual, namely Section 4.5 (Mail Settings) through Section 4.12 (Final Steps of configure-lockss).

5.3. Running LOCKSS 2.x

Now start the LOCKSS 2.x system. Follow these steps:

  1. LOCKSS 2.x host as lockss Run the following command on your LOCKSS 2.x host (still as the lockss user, still in the LOCKSS Installer Directory):

    scripts/start-lockss --wait

    If the startup process goes well, you will see:

    LOCKSS services are ready; AUs may still be loading.

    and control will be returned to the command line.

    Tip

    During this first startup, hundreds of megabytes of container images will be downloaded, which can take many minutes on a slow network.

  2. This step depends on your Migration Scenario:

    If you are doing a New-Host Migration, follow these steps:

    1. Log into the LOCKSS 2.x Configuration Service Web user interface as a way to verify that the LOCKSS 2.x stack has come up successfully. To do this, in a browser, go to the URL http://<lockss2host>:24602/DaemonStatus, where <lockss2host> represents the hostname of your LOCKSS 2.x host (for example lockss2.myuniversity.edu), and log in using the Web user interface username and password you specified during the LOCKSS 2.x configuration process.

      • If your browser is unable to connect, wait a moment and hit refresh until a Web user interface page is displayed.

      • If your login is successful but the red warning "This LOCKSS box is still starting" is shown, wait a moment and hit refresh until it is gone.

    2. Once successful, click on Admin Access Control in the top-right navigation menu.

    3. If it is not covered by the entries in the Allow Access section, add the IP address of your LOCKSS 1.x host (so it will be allowed to connect to the LOCKSS 2.x Web user interface), then click the Update button to save.

    If you are doing a Same-Host Migration, follow these steps:

    1. Log into the LOCKSS 2.x Configuration Service Web user interface as a way to verify that the LOCKSS 2.x stack has come up successfully. To do this, in a browser, go to the URL http://<locksshost>:24602/DaemonStatus, where <locksshost> represents the hostname of your LOCKSS host (for example lockss.myuniversity.edu), and log in using the Web user interface username and password you specified during the LOCKSS 2.x configuration process.

      • If your browser is unable to connect, wait a moment and hit refresh until a Web user interface page is displayed.

      • If your login is successful but the red warning "This LOCKSS box is still starting" is shown, wait a moment and hit refresh until it is gone.

    2. containerized LOCKSS 1.x In the unlikely event that your LOCKSS 1.x instance is a Docker container, you will have to perform an additional action:

      1. LOCKSS 1.x host as root On your LOCKSS 1.x host, run this command as root:

      docker exec lockss ip addr

      The output will look similar to this:

      1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host proto kernel_lo
       valid_lft forever preferred_lft forever
2: eth0@if731: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
    link/ether d6:18:ba:cf:05:26 brd ff:ff:ff:ff:ff:ff link-netnsid 0
    inet 172.18.0.3/16 brd 172.18.255.255 scope global eth0
       valid_lft forever preferred_lft forever

      Find the interface that is not a loopback (lo) interface, probably one with the prefix eth (eth0 in this example). You will want to make a note of the IP address (inet) of the LOCKSS 1.x container (172.18.0.3 in this example).

      1. In the Web user interface of the LOCKSS 2.x Configuration Service from the previous step, click on Admin Access Control in the top-right navigation menu.

      2. Add the IP address of your LOCKSS 1.x container to the Allow Access screen list so it will be allowed to connect to the LOCKSS 2.x Web user interface, then click the Update button to save.