5. Configuring LOCKSS 2.x for Migration

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

5.1. Importing Configuration From LOCKSS 1.x

First, you will need to make your LOCKSS 1.x configuration file, and if applicable the LCAP SSL keystores of your LOCKSS 1.x instance, available to LOCKSS 2.x. This depends on your Migration Scenario:

New-Host Migration

If you are doing a new-host migration, follow these steps:

Copy the LOCKSS 1.x configuration file from /etc/lockss/config.dat on your LOCKSS 1.x host to /tmp/v1config.dat on your LOCKSS 2.x host. For example you might use scp on your LOCKSS 1.x host:
```
scp /etc/lockss/config.dat <username>@lockss2.myuniversity.edu:/tmp/v1config.dat
```
Tip

Custom file path on the LOCKSS 2.x host

The destination file name on your LOCKSS 2.x host can be something other than /tmp/v1config.dat. The LOCKSS 2.x configuration script will later prompt you for the path of this file on the LOCKSS 2.x host, so you can enter your custom file path then.

Unable to copy the LOCKSS 1.x configuration file to the LOCKSS 2.x host

If you are unable to copy the LOCKSS 1.x configuration file to the LOCKSS 2.x host, 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.
Ensure that on the LOCKSS 2.x host, the LOCKSS 1.x configuration file is readable by all. You can do this as root with (for instance):
```
chmod +r /tmp/v1config.dat
```
If your LOCKSS network uses LCAP SSL keystores for encrypted communication between nodes, see the Appendix: LCAP Over SSL Migration appendix for additional instructions in this spot.

Same-Host Migration

If you are doing a same-host migration, follow these steps:

The LOCKSS 2.x configuration script will find the LOCKSS 1.x configuration file /etc/lockss/config.dat directly, so you do not need to do anything in this step.
If your LOCKSS network uses LCAP SSL keystores for encrypted communication between nodes, see the Appendix: LCAP Over SSL Migration appendix for additional instructions in this spot.

5.2. Running configure-lockss --migrate

The second part of this phase is to run the configure-lockss tool with the special --migrate option on your LOCKSS 2.x host [1]. With some notable exceptions described below, this will proceed largely as described in chapter 4 (Configuring the LOCKSS System) of the LOCKSS System Manual:

Per section 4.1 (Configuration Prerequisites) of the LOCKSS System Manual, gather information about your LOCKSS 2.x host [1].
Run the following command as the lockss user in the LOCKSS Installer Directory:
```
scripts/configure-lockss -m
```
which is short for:
```
scripts/configure-lockss --migrate
```
This is almost the same as section 4.2 (Invoking configure-lockss) of the LOCKSS System Manual, but with the additional --migrate option.
The first prompt, Command to use to execute kubectl commands, is the same as that from section 4.3 (Kubernetes Settings) of the LOCKSS System Manual. If you are using the K3s Kubernetes environment that ships with LOCKSS 2.x, the proposed value is already correct; hit Enter to accept it. Otherwise, enter the command needed to invoke kubectl in your environment.
This step depends on your Migration Scenario:
New-Host Migration
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?
  - 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, or hit Enter to accept the default in square brackets (/tmp/v1config.dat) if it matches the path you used.
  - If you enter N for "no", you will have to manually and accurately enter a number of values reflecting your LOCKSS 1.x configuration in the next step (instead of the values being imported directly from your copied LOCKSS 1.x configuration file).
2. You will be asked to confirm each configuration value. You can do so by simply hitting Enter for each, to accept the imported value in square brackets. (If you answered N in the previous step because you could not copy your LOCKSS 1.x configuration file to the LOCKSS 2.x host, there will be no imported values offered as defaults and you will have to manually enter the values reflecting your LOCKSS 1.x configuration.)
  
  These confirmation prompts are as follows:
  - Fully qualified hostname (FQDN) of this machine
  - IP address of this machine
  - Initial subnet(s) for admin UI access
  - LCAP protocol port
  - Is this machine behind NAT?
  - Mail relay for this machine
  - Does the mail relay <mailhost> need a username and password?
  - E-mail address for administrator
  - Configuration URL
  - Configuration proxy (host:port)
  - Preservation group(s)
  corresponding to these sections of the LOCKSS System Manual:
  - Section 4.4 (Network Settings)
  - Section 4.5 (Mail Settings)
  - Section 4.6 (Preservation Network Settings)
Same-Host Migration
If you are doing a same-host migration, follow these steps:
1. Data will be imported from the LOCKSS 1.x configuration file /etc/lockss/config.dat directly, and you will be asked to confirm each configuration value. You can do so by simply hitting Enter for each, to accept the imported value in square brackets. These confirmation prompts are as follows:
  - Fully qualified hostname (FQDN) of this machine
  - IP address of this machine
  - Initial subnet(s) for admin UI access
  - LCAP protocol port
  corresponding to section 4.4 (Network Settings) of the LOCKSS System Manual.
2. 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.
3. You will be asked to confirm more configuration values. You can do so by simply hitting Enter for each, to accept the imported value in square brackets. These confirmation prompts are as follows:
  - Is this machine behind NAT?
  - Mail relay for this machine
  - Does the mail relay <mailhost> need a username and password?
  - E-mail address for administrator
  - Configuration URL
  - Configuration proxy (host:port)
  - Preservation group(s)
  corresponding to these sections from the LOCKSS System Manual:
  - Section 4.5 (Mail Settings)
  - Section 4.6 (Preservation Network Settings)
Follow the instructions from the following sections of the LOCKSS System Manual:
- Section 4.7 (Web User Interface Settings)
- Section 4.8 (Storage Areas)
- Section 4.9 (Database Settings)
- Section 4.10 (LOCKSS Services)
- Section 4.11 (Web Replay Settings)
- Section 4.12 (Final Steps)

5.3. Running LOCKSS 2.x

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

Run the following command as lockss in the LOCKSS Installer Directory:
```
scripts/start-lockss -w
```
which is short for:
```
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.
This step depends on your Migration Scenario:
New-Host Migration
If you are doing a new-host migration, follow these steps:
1. In a browser, go to the URL http://<lockss2.myuniversity.edu>:24621/DaemonStatus, where <lockss2.myuniversity.edu> represents the host name of your LOCKSS 2.x host. Log in using the Web user interface username and password you specified during the configuration process. If the red warning "This LOCKSS box is still starting" is shown, wait a moment and hit refresh until it is gone and you can log in.
2. Click on Admin Access Control in the top-right menu.
3. If needed, allow the IP address of your existing LOCKSS 1.x host by entering it or its subnet in Allow Access, then click the Update button.
4. If your LOCKSS network uses LCAP SSL keystores for encrypted communication between nodes, see the Appendix: LCAP Over SSL Migration chapter.
Same-Host Migration

If you are doing a same-host migration, go to the URL http://<lockss.myuniversity.edu>:24621/DaemonStatus in a browser, where <lockss.myuniversity.edu> represents the host name of your LOCKSS host [1]. Log in using the Web user interface username and password you specified during the configuration process. If the red warning "This LOCKSS box is still starting" is shown, wait a moment and hit refresh until it is gone and you can log in. Your LOCKSS 2.x system is now ready for the next phase.

Footnotes