(Redirected from Installation instructions)
Jump to: navigation, search

LOCKSS CD Release 280 (2010/03/12)

Please read this page carefully before bringing your LOCKSS box online.

Contents

[edit] Background

In order to improve security, the LOCKSS software runs from a CD rather than from the hard disk. Only the content that is being preserved is permanently written on the disks; all the software is reloaded from CD each time the machine boots. Configuration information is kept on a floppy disk, or a USB flash disk, which is written during the first boot of the system and is then write-locked. Alternatively, the first boot can create the image of a configured CD, which can be burnt and then used to boot and run the system.

The LOCKSS software distribution includes everything you need, including a specially configured OpenBSD operating system and the LOCKSS daemon. LOCKSS is not normally run alongside other applications in an operating system used for other purposes. If LOCKSS is installed on a machine that already has an operating system installed, that operating system and all existing data will be erased.

LOCKSS can also be run in "demo mode", if the system's hard disk is not an OpenBSD disk, typically if LOCKSS has never run on it, and if it has at least 768MB of memory. In demo mode it will leave any existing operating system and data unchanged (it will not write to the disk at all). A configuration floppy created in "demo mode" can be used later if the system is actually installed.

These instructions explain how to download an image of the CD, burn it on a blank CD-R, use it to write a configuration, and use the CD and the configuration to boot and run your LOCKSS box. You may use any machine to burn the CD.

[edit] Release Notes

The release notes for CD280 can be found in the Platform Release Notes section of our site.

You can upgrade to CD280 if you are currently running any of the two previously supported releases, CD267 or CD273. If you are currently running an earlier release, you need to upgrade in multiple steps of no more than two releases at a time.

Please upgrade to CD280 as soon as possible. With this release we are ending support for releases before CD273. LOCKSS boxes running CDs before CD273 will continue to function but will not receive any further daemon upgrades. For more details please see the Platform Release Notes.

[edit] Before Starting to Install or Upgrade

[edit] Minimum Requirements

Verify that your machine meets our minimum requirements:

  • CPU: At least 1GHz.
  • Memory: At least 1GB of RAM. If you have 750GB or 1TB drives, you will need at least 1.5GB of RAM.
  • Storage: 1 or more IDE drives totaling at least 250GB. To preserve all the content that has been released to Alliance members to date you will need at least 1TB. SATA disks are recommended. (Older BIOS versions may need to be configured to put SATA drives in "native" or "enhanced" mode.) Parallel ATA drives should also work. Most SCSI drives and controllers, and external USB disk drives will work, but are not officially supported. Performance may suffer with external USB drives, which can be several times slower than internal drives.
  • CD: A bootable IDE CD drive. (i.e., the machine must be able to boot from a CD.)
  • Ethernet interface: The full list of Ethernet adapters that we believe will work can be found under the heading "Ethernet Adapters" at http://www.openbsd.org/i386.html. Integrated adapters (on the motherboard) generally work, but the latest motherboards may have an adapter that is too new for the OpenBSD drivers. If you experience installation trouble that seems to be caused by the ethernet card, particularly if you have a recent 3COM ethernet card, please see the Ethernet Interface FAQ.
  • Network connectivity: The LOCKSS daemon uses the internet to collect content from publishers and to communicate with other LOCKSS boxes to audit and repair content. If you are installing a LOCKSS box behind a firewall please contact us for a list of ports that need to be open.
  • One of the following:
    • Floppy disk drive: Only old-style floppy disk drives will work; USB floppy drives will not work.
    • USB flash disk: sometimes called a thumb drive. The LOCKSS CD requires (and will check) that the USB flash disk has a working hardware write-protect switch. Combining USB flash disk configuration storage and SCSI or USB data storage does not work.
    • Nothing: If neither a floppy drive nor a write-protectable USB flash disk is available, configuration information can be stored on the CD itself. This is usually the most trouble-free option, but requires burning a second CD after configuration is completed.

[edit] Information You Need to Know

You will need to know the following information:

  • Keyboard type: The two-letter country code (e.g. us or uk) for your keyboard layout.
  • IP address: The IP address assigned to the machine. This must be a statically-assigned, globally-routable IP address. If this is a new install, or a current site changing its IP address, please send us e-mail (at Image:EmailLockssSupportBoldRed.gif) with the IP address of the machine so we can add it to the access control table. Current sites using the same IP address need not e-mail us.
  • Subnet Mask: The netmask for the local subnet that the LOCKSS machine is on.
  • Gateway IP address: The IP address of the default gateway or router.
  • Name server (DNS) IP address: The IP address of the DNS server the LOCKSS machine should use.
  • Host Name and Domain Name: The DNS name of the LOCKSS machine. The fully qualified name (FQDN) is a string of the form ahost.auniversity.edu. The host name is the part before the first dot (eg, ahost); the domain name is the part after the first dot (eg, auniversity.edu).
    • Please note: You must have a registered DNS name to install LOCKSS. The install process will verify that the name you enter resolves to the IP address you enter, so it is wise to test beforehand that it does. On a Unix system the command to do this is host ahost.auniversity.edu 192.168.1.1 where the name is the name of the LOCKSS box and the IP address is that of the DNS server. Make sure that the command succeeds and returns the correct IP address for the LOCKSS box.
  • Mail relay (SMTP server, mail hub): The name of a local mail (SMTP) relay for outgoing mail from the LOCKSS machine. The correct choice of mail relay will almost always be the SMTP server your network asks internal users to set in their mail client configuration. It should be able to relay mail to both internal addresses at your institution, and external addresses (e.g., @lockss.org).
    • Please note: For security reasons LOCKSS machines do not receive mail. The mail relay will be asked to relay mail to either the admin e-mail address (below) or the Stanford LOCKSS team. In both cases the mail will have as its From: address the admin e-mail address. The mail sent to Stanford contains configuration information and the machine's public keys.
  • Administrative e-mail address: The e-mail address which should receive alert messages generated when the operating system detects potential problems. This may be a mailing list.
  • E-mail sender: The e-mail address from which the alert messages should appear to come. This should not be a mailing list; any main sent to the administrative e-mail address that cannot be delivered will bounce to this address.
  • Administrative access subnet: Administrative access (to both to web UI and ssh) is restricted to certain IP addresses. ssh logins are allowed only from the specified subnet; access to the administrative UI is initially limited to the same subnet, but can be changed by accessing the UI from any machine already in the access list. The admin subnet may be specified either as a class A, B or C subnet (eg, 10.*.*.* , 192.168.47.*), or using CIDR notation (eg, 192.168.47.0/24). The default is the class C subnet that the LOCKSS machine itself is in.
  • Administrative UI password: Access to the administrative user interface is protected by a password. You will be asked to chose and enter a password.
  • Network Time Protocol (NTP) server: Your LOCKSS box will preferably synchronize itself with the global NTP network via pool.ntp.org. If your local firewall rules prevent this, you can specify a local NTP server, or decide not to use NTP at all.

Note: If you are upgrading an existing LOCKSS system, most of this information will not have to be reentered.

[edit] Other Things You Will Need

  1. A computer (not the LOCKSS machine) that is connected to the Internet and has a CD burner. It does not matter what OS this computer is running, as long as it can write an ISO image to a CD. See the CD burning instructions.
  2. A blank CD-R disk.
  3. A blank, DOS-formatted floppy disk, or a blank, DOS-formatted USB flash disk, or nothing if your configuration will be written to CD.
  4. If your machine has more than one Ethernet interface, you will need to know which one is connected.

[edit] Creating the Boot CD

This step is performed on an Internet-connected workstation with a CD burner, not the LOCKSS machine.

  1. Download the CD image (about 175MB) and either its MD5 or its SHA1 from one of the following locations. The MD5 for CD280 is b56b706de520b0154d3e514a93ec3647 and the SHA1 is 39a26f2904cda1f9b4fac89dae1b430845a51875.
  2. Verify that the download is correct. On most Unix systems, the command to do this is:
    md5sum -c lockssCD280.iso.md5
    or:
    sha1sum -c lockssCD280.iso.sha1
    Windows users can try the software at http://www.md5summer.org/.
  3. Burn the .iso file to a CD. Note: the file must be burned as an ISO image, not as a regular file. Please see the CD burning instructions.

[edit] Upgrading your LOCKSS Box

When a new platform CD is released, we recommend you upgrade your LOCKSS machine to the new version. OpenBSD, the operating system on which the LOCKSS platform is based, has a well-developed release process that produces a release every 6 months. The LOCKSS team aim to release a new platform CD about six weeks after each new OpenBSD release, meaning that the upgrade process should be regular, but infrequent.

The upgrade procedure is straightforward: you are required to burn a new CD with the newest ISO image, then reboot your machine with the new CD and blank write-protectable media (e.g. a blank floppy or blank USB drive). The machine will have access to previously entered configuration values and will use these as default values during the configuration process. In most cases, this means you can simply hit enter at each to confirm they are still correct.

A platform release may contain changes to the configuration script stored on the write protected media. If an older configuration script is used with a new platform release, system conflicts may result. In order to prevent such problems during upgrade please be aware you are required to recreate the configuration script on blank write protectable media.

[edit] Preparing the Configuration Medium

  • If your configuration medium is floppy disk or USB flash disk, you will be asked twice during the process to insert or write enable the medium, and twice to write protect it. See the Platform FAQ for why you have to do this twice.
  • If your configuration medium is floppy disk or USB flash disk, make sure it is blank and DOS-formatted.
  • If your configuration medium is USB flash disk, when you are asked to write-enable or write-protect the device, please disconnect the medium, flip the write-protect switch, and then reconnect it. Only some drives can change their write-protect status successfully without disconnection, but it is always safe to disconnect before changing it. Please wait after connecting the USB flash disk for a blue message indicating that sd0 has been recognized before pressing ENTER.
  • If your configuration medium is CD you will not encounter these instructions. Instead, at the end of the process the system will create a configured .iso image in /cache/CD280.iso.

If you encounter problems in this process, please consult the Troubleshooting Installation page. It may help you, or at least help you collect the information the LOCKSS team will need to diagnose the problem.

[edit] Ensuring the BIOS Settings Are Correct

The remaining steps are performed on the LOCKSS machine.

Ensure that the LOCKSS machine's BIOS settings are correct:

  1. The BIOS must be set to boot first from the CD-ROM drive. Somewhere in the BIOS setup program there will be a "boot" screen, which lists the order in which boot devices are tried. The CD drive must be first in this list. It does not matter what else is in the list; LOCKSS boots only from the CD.
  2. The "After power failure" setting (or something similar; look in the "power" or "boot" screen) should be set to "last state" or "previous state" (or "on" if "previous state" is not available). This will cause the computer to start running again after a power failure, if it had been running before the power failure. Most new machines are configured by default to remain off after a power failure; this is not appropriate for a LOCKSS box

[edit] Booting the Machine

  1. Insert the CD you burned into the CD-ROM drive and power off the machine. Do not simply reboot the machine; please turn its power off.
  2. Ensure that there is no floppy in the floppy drive or USB disk attached.
  3. WITHOUT any floppy in the drive, power up the machine. As the system boots it may run a filesystem check, which may take several minutes. Messages about fd0 errors are possible at this point and should be ignored.
  4. If this machine has never run LOCKSS before or this is a new hard disk you should see:
    New disk wd0 - Demo [D], Install [I] or quit [Q]?
    If you answer D the LOCKSS system will attempt to run without using the hard disk at all, simply using RAM. If your system has enough RAM, about 750MB, the process should continue as described below starting with the "No current configuration available" question.
  5. If you answer I, you should see:
    Install – Y will erase entire disk.
    Are you sure – Y or N?
  6. If you answer Y, you will be presented with a summary of the hard disk geometry and the following message:
    wd0: New Disk– ALL DATA ON IT WILL BE OVERWRITTEN IF YOU ANSWER yes
    If you are installing on a new machine or a new hard drive and you do not see this message, something is wrong. Please contact us.
  7. If you answer yes, LOCKSS will overwrite all data, and then partition the disk. This process may take some time (possibly an hour or more on very large disks); please be patient.

[edit] Configuring the Machine

[edit] Configuration Medium

  • To the question:
    No current configuration available: create floppy (F) or USB (U) or CD (C)[Funcs]?
    answer with the letter for the device on which you wish to store configuration data (F for floppy or U for USB), or C to include the configuration data directly into a CD image (which you will then burn to a new CD).

[edit] Network Interface

  • If the machine has a single network interface controller (NIC), its name will be displayed, for instance:
    NIC is fxp0
  • If the machine has multiple network interfaces, you should see a list of NIC names. Type the one you want to use.
  • If you see the message Ethernet interface: [unknown], please refer to the Ethernet Interface FAQ.

[edit] Network Configuration

  • You will be prompted to enter the following information:
    • keyboard type
    • IP address
    • netmask
    • gateway
    • name server (DNS server)
    • host name
    • domain
    • mail hub (SMTP server)
    • administrator e-mail address
  • If you are upgrading an existing LOCKSS box, most of these will default to their previous value. Please verify them, correcting any that need to be changed. If this is a new install you will have to enter each value.

[edit] Daily Mail

  • You will be asked:
    Should this e-mail get daily system mail?
    Answer N to this. If you answer Y the system will generate two e-mails a day, reporting on its health and its security. If you answer N, the system will generate only the security e-mail, and only when it notices potential security problems. Depending on the initial state of the machine, an initial security e-mail may be generated with a long listing of device files. You may safely ignore this initial email.

[edit] Web User Interface

  • You will be presented with the list of subnets from which administrators will access the web user interface (UI):
    Web admin UI access subnet(s) "XXX.YY.ZZZ.*"
    (where XXX.YY.ZZZ.* represents a subnet or a list of subnets), followed by a yes/no prompt to accept the list or revise it. (The subnet(s) are also used to establish packet filters that restrict access via SSH. See the explanation of the administrative access subnet.)
    • If you will be using a machine on the same class C subnet as the LOCKSS machine, accept the default answer by answering Y.
    • If you answer N, you will be asked:
      Please enter a new subnet:
      and:
      Would you like to enter another subnet?
      Enter one subnet at a time, answering Y if you wish to enter an additional subnet or N when you are done.
  • Next you will be prompted to enter (twice) a:
    Password for web UI administration user lockss
    This password will be needed to connect to the UI from a web browser.
    • If the two entries do not match, you will be again prompted to enter the password twice.
    • Currently the password can be changed only by repeating this configuration procedure.
    • The system enforces the requirement that the password be different from its predecessor.

[edit] SSH

During initial production testing, the Stanford LOCKSS team occasionally needs to diagnose and fix problems on individual LOCKSS boxes. We do this by using SSH to log in to the lcap account that runs the daemon, using individual SSH keys. However, some institutions' rules forbid this type of access, so it can be disabled. In many cases, fixing problems requires root access, so we also request that you allow us to use the sudo program.

  • To the question:
    Should the LOCKSS team be able to log in via SSH?
    please answer yes unless your institution forbids it.
  • If you answer yes to the previous question, you will then be asked:
    Should the LOCKSS team have root access via sudo?
    Again, please answer yes unless your institution forbids it.


[edit] Additional Configuration

A major change to the configuration dialog as of CD253 is the introduction of the "Additional configuration" section. There were an increasing number of questions that were not relevant to most libraries' configurations. We have moved these to a separate section. You will be asked them only if you answer Y to the Additional configuration question. You need do so only if one or more of the following applies to you:

  • You want to use ICP (Internet Cache Protocol)
  • You want to use a local NTP (Network Time Protocol) server to synchronize the LOCKSS box's clock instead of the default pool.ntp.org servers.
  • Your LOCKSS box is behind a NAT (Network Address Translator).
  • You are part of a Private LOCKSS Network.
  • Your SMTP mail server requires a user name and password and/or TLS encrypted connections.
  • Your network requires the use of an HTTP proxy to access external web sites.

If you answer Y you will be asked the following questions. Otherwise skip to Network Testing below.

[edit] ICP

The Internet Cache Protocol (ICP) is an inter-cache communication protocol that allows the LOCKSS box to integrate with proxy caches.

  • To the question:
    Configure ICP inter-cache protocol (ICP)?
    answer Y if you want this LOCKSS box to respond to ICP requests from other proxies.
  • If you answer Y to the previous question, you will be further prompted for the UDP port on which the ICP service should listen (normally port 3130, but depends on local proxy configuration) and the subnet(s) from which ICP requests should be accepted.
    • The list of ICP subnets is presented the same way as the list of administrative subnets (see above). You may either accept the list or revise it one subnet at a time.
    • The list of ICP subnets is used to establish packet filters to restrict access to the ICP service.

[edit] V3 Protocol

Some private LOCKSS networks use a different port for the V3 mutual audit protocol. Even if your LOCKSS box is part of the public LOCKSS network there may be specific reasons at your site to use a different port.

  • Next you will be asked whether to configure the V3 protocol, and on what TCP port:
    Configure V3 protocol port (0 to disable)?
    Please accept the default answer unless you have made special arrangements with us. This will add a packet filter rule to allow V3 polling protocol messages to be received.

[edit] NTP

  • You will be asked to configure the Network Time Protocol (NTP).
    NTP server (none to disable)?
    Unless your local firewall rules prevent this, accept the default pool.ntp.org. Enter none to disable NTP.

[edit] Web Proxy

If your network requires use of a Web proxy to access external Web sites, you can configure the LOCKSS box to use it during daemon startup as the properties that configure the daemon are fetched from the props server. Answer with the DNS name or IP address of your proxy followed by a colon followed by the port number.

  • Props proxy (none to disable)?

[edit] NAT

If your machine is behind network address translation (NAT) you will need to follow the instructions on the NAT page and provide the external IP address in response to the External IP address for NAT? question.

[edit] PLN

If your LOCKSS box is part of a Private LOCKSS Network you will need to provide answers to:

  • Name of PLNs, ENTER for done
  • URL for props server:

These answers will be provided by your PLN administration.

[edit] SMTP

The SMTP server you configured in the earlier part of the configuration dialog may need a user and password. In most cases if it does, it will also require TLS (SSL) connections. You can configure them by answering Y to the first question. You will then be asked the following questions:

  • Mail hub smtp.example.com needs user/password?
    • User for smtp.example.com:
    • Password for joe.user@smtp.example.com:
    • smtp.example.com needs SSL?

Note that the password will be stored in the clear on the configuration medium.

[edit] Network Testing

  • The machine will then display all the information it has gathered and ask:
    OK to test this network configuration?
    Verify that the info is correct and answer Y, or N to correct any of the entries.
  • After you answer Y, a short test will be run to verify that the network is reachable, the DNS server can resolve the box's name, etc. If the test fails you will be given a chance to correct the info.

[edit] Root Password

  • Follow the instructions:
    Insert a blank, write-enabled floppy in the drive, press ENTER
    The machine will check to make sure that the floppy is write enabled. If it is not you will be prompted again. The configuration will be written to the floppy (or to the USB disk, or saved for future use in creating a configured CD).
  • Follow the instructions:
    Please write-lock the floppy, replace in the drive, then press ENTER
    The machine will check that the floppy (or the USB disk) is actually write-protected and repeat this prompt if it isn't. Messages about fd0 errors (or sd0 for USB) are possible at this point and should be ignored.
  • The system will refresh the public signing keys (this may take a while), verify the signatures on a long list of packages, then prompt:
    Please write-enable the floppy, replace in the drive, then press ENTER
    Please do so.
    • See the Platform FAQ for why you have to do this twice.
    • Messages about fd0 errors (or sd0 for USB) are possible at this point and should be ignored.
  • You will be prompted:
    Please choose a new root password
    You will have to enter it twice. PLEASE choose a good password (containing letters, numbers, and punctuation, and not easily guessable) and remember it, or write it down and keep it in a safe place. This password can be used to login to your machine as a Unix user, either on the console or via SSH (from any machine in the admin access subnet). This is not the same as the password for the web-based administrative user interface, set earlier. Logging in with this password is not needed for normal operation of LOCKSS, but may be required in special circumstances, such as replacing disk drives or installing security updates, and if something goes wrong with the machine we may ask you to login to help us diagnose and correct problems.
  • After a short while, you will be prompted to:
    Please write-lock the floppy, replace in drive, press ENTER
    Please do so.
    • Messages about fd0 errors (or sd0 for USB) are possible at this point and should be ignored.

[edit] Congratulations

  • The machine will finish booting and start various daemons.
    • If you chose the configuration on CD option, you will see a string of messages as the image of the configured CD is created. You will need to burn this image to a new CD; see below.
  • Eventually you will see:
    • The URL and username for the administrative user interface. Remember these, you will need them and the administrative user interface password you chose in order to access the UI.
    • A login: prompt.
  • If you chose the configuration on CD option, you should now transfer the configured CD image to a machine with a CD burner. The easiest way to do this is to use a web browser to connect to the admin UI at http://hostname:8081/, click on ISOs, then click on CD280.iso to download it. (Alternatively, you may log in to the LOCKSS box as root and use scp to copy the configured image from /cache/CD280.iso to another machine.) You should then burn this image to a CD, replace the unconfigured CD that you originally downloaded with this new, configured CD, login to the LOCKSS box as root, and type reboot to restart it.

Congratulations! You have successfully installed the LOCKSS software.

Note: Shortly after installing or upgrading to a new CD, probably the next day, you will receive a "daily insecurity" email from the LOCKSS box listing several thousand lines of changes to system files. This is normal. If you receive one of these insecurity emails when you have *not* made any changes, and we haven't announced any new releases, please contact us.

Note: When a LOCKSS box comes online properly, the LOCKSS team is sent an email describing your machine's configuration. This helps us diagnose problems that may arise. If you do not receive confirmation that we received a configuration email from your LOCKSS box within 48 hours of bringing the machine online, PLEASE CONTACT US.

Because we release new versions of the LOCKSS daemon more frequently than CD images, it is likely that the daemon on the CD is out-of-date. The daemons on the CDs are always named version 0.0.0. The system will attempt to download and install a new version as soon as it comes up, but it is a good idea an hour or two after the first boot to check the daemon version at the bottom of the administrative UI page. If it is 0.0.0, login as root and type ./immediate_system_upgrade to force the upgrade to happen. When it finishes, type exit to logout.

If anything goes wrong -- please send e-mail to Image:EmailLockssSupportBoldRed.gif

Retrieved from "http://www.lockss.org/lockss/Installation_Instructions"