Difference between revisions of "LOCKSS Technical Manual"

From Plnwiki

Line 47: Line 47:
 
* Prerequisite: CentOS 6.4 basic server install with the following open TCP ports:  8080 (proxy), 8081 (webadmin), 9729 (V3 poll)  and 22 (ssh)
 
* Prerequisite: CentOS 6.4 basic server install with the following open TCP ports:  8080 (proxy), 8081 (webadmin), 9729 (V3 poll)  and 22 (ssh)
 
# Log in as root
 
# Log in as root
> ssh root@[you_lockss_box_ip_address]
+
#: > ssh root@[you_lockss_box_ip_address]
 
# Get lockss-daemon rpm from sourceforge
 
# Get lockss-daemon rpm from sourceforge
> cd ~
+
#: > cd ~
> wget http://downloads.sourceforge.net/project/lockss/Daemon/1.60.3/lockss-daemon-1.60.3-1.noarch.rpm
+
#: <nowiki>> wget http://downloads.sourceforge.net/project/lockss/Daemon/1.60.3/lockss-daemon-1.60.3-1.noarch.rpm </nowiki>
 
+
 
# Install rpm
 
# Install rpm
>  rpm -i lockss-daemon-1.60.3-1.noarch.rpm
+
#: >  rpm -i lockss-daemon-1.60.3-1.noarch.rpm
 
+
 
# Create local caches folders
 
# Create local caches folders
> mkdir /caches
+
#: > mkdir /caches
> mkdir /caches/cache0
+
#: > mkdir /caches/cache0
> mkdir /caches/cache1
+
#: > mkdir /caches/cache1
 
+
 
+
 
# Run the LOCKSS daemon configuration script
 
# Run the LOCKSS daemon configuration script
> /etc/lockss/hostconfig  
+
#: > /etc/lockss/hostconfig  
 
+
 
# Answer local configuration questions as follows
 
# Answer local configuration questions as follows
Fully qualified hostname (FQDN) of this machine: [lockssbox1.ulb.ac.be]  
+
#:Fully qualified hostname (FQDN) of this machine: [lockssbox1.ulb.ac.be]  
IP address of this machine: [164.15.4.112]  
+
#:IP address of this machine: [164.15.4.112]  
Is this machine behind NAT?: [N]  
+
#:Is this machine behind NAT?: [N]  
Initial subnet for admin UI access: [164.15.4.0/24]  
+
#:Initial subnet for admin UI access: [164.15.4.0/24]  
LCAP V3 protocol port: [9729]  
+
#:LCAP V3 protocol port: [9729]  
PROXY port: [8080]  
+
#:PROXY port: [8080]  
Admin UI port: [8081]  
+
#:Admin UI port: [8081]  
Mail relay for this machine: [localhost] smtp.ulb.ac.be
+
#:Mail relay for this machine: [localhost] smtp.ulb.ac.be
Does mail relay smtp.ulb.ac.be need user & password: [N] y
+
#:Does mail relay smtp.ulb.ac.be need user & password: [N] y
User for smtp_server: [] lockssadmin@ulb.ac.be
+
#:User for smtp_server: [] lockssadmin@ulb.ac.be
Password for locksadmin@ulb.ac.be @ smtp.ulb.ac.be: []  
+
#:Password for locksadmin@ulb.ac.be @ smtp.ulb.ac.be: []  
Again: []  
+
#:Again: []  
E-mail address for administrator: [] lockssadmin@ulb.ac.be
+
#:E-mail address for administrator: [] lockssadmin@ulb.ac.be
Path to java: [/usr/bin/java]  
+
#:Path to java: [/usr/bin/java]  
Java switches: []  
+
#:Java switches: []  
Configuration URL: [http://props.lockss.org:8001/daemon/lockss.xml] http://164.15.1.1/lockss.xml
+
#:Configuration URL: [http://props.lockss.org:8001/daemon/lockss.xml] http://164.15.1.1/lockss.xml
Configuration proxy (host:port): [NONE]  
+
#:Configuration proxy (host:port): [NONE]  
Preservation group(s): [prod] testpln
+
#:Preservation group(s): [prod] testpln
Content storage directories: [] /caches/cache0; /caches/cache1
+
#:Content storage directories: [] /caches/cache0; /caches/cache1
Temporary storage directory: [/caches/cache0/tmp]  
+
#:Temporary storage directory: [/caches/cache0/tmp]  
User name for web UI administration: [] lockss
+
#:User name for web UI administration: [] lockss
Password for web UI administration user lockss: []  
+
#:Password for web UI administration user lockss: []  
Password for web UI administration (again): []  
+
#:Password for web UI administration (again): []  
OK to store this configuration: [Y] y
+
#:OK to store this configuration: [Y] y
 +
# Start the daemon
 +
#: >  /etc/init.d/lockss start
 +
# Connect to the web interface
 +
#: with your favorite browser, go to:
 +
#: http://your_ip_address:8081
 +
#: user/pwd: previously defined credentials
 +
#:  no need to chkconfig on, done automatically
 +
#: if any error appears, check /var/log/lockss/stdout for info
 +
# Ask PLN admin to update
 +
* the lockss.xml file with the new cache IP address
 +
*  nagios monitoring server configuration
  
 
== How to create a title database? ==
 
== How to create a title database? ==
Line 100: Line 106:
 
* [[Plugins/Plugin XML Format|Plugin XML Format]]
 
* [[Plugins/Plugin XML Format|Plugin XML Format]]
  
* Plug-in tool
+
* [[Using the Plug-in tool]]
  
 
== How to ingest content with the UI? ==
 
== How to ingest content with the UI? ==

Revision as of 20:58, 27 October 2013

Anthony's list will go here

LOCKSS applications

LOCKSS is a versatile technology which can be used for many applications

Type of usage

  • preserving access to content (e.g. the LOCKSSdm “proxy”)
  • backing-up content (simple storage, no curation, every modification goes in)
  • preserving content on the long-term (which implies curation)

Type of content

  • rather static content (journals,...)
  • dynamic content (institutional repositories, websites)

Type of access

  • public (e.g. GLN)
  • private (SSL, over VPN)

The difference between these applications mainly resides in the lockss.xml configuration (767 parameters lacking documentation, many of which are not used).

Basic Private LOCKSS Network infrastructure

Basic PLN infrastructure
  • (first draft... will be improved later)

A PLN is a generic framework. For the sake of illustration, the figure represents one specific implementation of a PLN composed of:

  • LOCKSS caches: The LOCKSS caches are the nodes in the network in which digital objects will be preserved and monitored as archival units. One archival unit is typically a one-year collection (size: 1GB to 20GB). The daemon is a java application which basically fetches and monitors data inside the cache. The LOCKSS cache local configuration can be set through a web-based user interface. The size of an AU results of a trade-off between the processing overhead required by large AUs and the guarantee that all AUs integrity can be regularly checked in the case of a miltitude of small AUs.
  • The adminsitrative server: The Admin server mainly contains the global configuration of the PLN nodes (lockss.xml, . Local node configuration can however needs to be accessible to all PLN nodes. Its purpose is to maintain the whole PLN.
  • Conspectus database (specific MetaArchive config): contains functional metadata to maintain LOCKSS title database and non-functional metadata required for the maintainers of the preservation network: collection title, description, coverage, format, language, ownership, related collections, base URL, HARVESTING info (plugin identifier, plugin parameters, manifest page, OAI provider). This conspectus database generates and updates the title databases
  • Title database: xml which describes the content of the archival units: where to find the corresponding plug-in, the archival unit base url, the IP adress of all the cache in the network
  • Plug-ins repository: Versionning server that stores the plug-ins. A plug-in instructs the LOCKSS box of how to crawl (filtering rules) and audit the content - where to find the manifest page - only signed plugins are accepted (keystore) - reread plugin registries every 6 hours
  • Manifest page: provides permission for LOCKSS to crawl and harvest an Archival unit from the webserver


How to set up a PLN admin server properly (what are the important parameters?)

A complete list of parameters (and their description) is available but it would be interesting to have a list of the most important parameters (~100 parameters according to Tom) and a more detailed description for those parameters (typical values, range of acceptable values).

How to install and configure a locks daemon on a PLN node?

  • Prerequisite: CentOS 6.4 basic server install with the following open TCP ports: 8080 (proxy), 8081 (webadmin), 9729 (V3 poll) and 22 (ssh)
  1. Log in as root
    > ssh root@[you_lockss_box_ip_address]
  2. Get lockss-daemon rpm from sourceforge
    > cd ~
    > wget http://downloads.sourceforge.net/project/lockss/Daemon/1.60.3/lockss-daemon-1.60.3-1.noarch.rpm
  3. Install rpm
    > rpm -i lockss-daemon-1.60.3-1.noarch.rpm
  4. Create local caches folders
    > mkdir /caches
    > mkdir /caches/cache0
    > mkdir /caches/cache1
  5. Run the LOCKSS daemon configuration script
    > /etc/lockss/hostconfig
  6. Answer local configuration questions as follows
    Fully qualified hostname (FQDN) of this machine: [lockssbox1.ulb.ac.be]
    IP address of this machine: [164.15.4.112]
    Is this machine behind NAT?: [N]
    Initial subnet for admin UI access: [164.15.4.0/24]
    LCAP V3 protocol port: [9729]
    PROXY port: [8080]
    Admin UI port: [8081]
    Mail relay for this machine: [localhost] smtp.ulb.ac.be
    Does mail relay smtp.ulb.ac.be need user & password: [N] y
    User for smtp_server: [] lockssadmin@ulb.ac.be
    Password for locksadmin@ulb.ac.be @ smtp.ulb.ac.be: []
    Again: []
    E-mail address for administrator: [] lockssadmin@ulb.ac.be
    Path to java: [/usr/bin/java]
    Java switches: []
    Configuration URL: [1] http://164.15.1.1/lockss.xml
    Configuration proxy (host:port): [NONE]
    Preservation group(s): [prod] testpln
    Content storage directories: [] /caches/cache0; /caches/cache1
    Temporary storage directory: [/caches/cache0/tmp]
    User name for web UI administration: [] lockss
    Password for web UI administration user lockss: []
    Password for web UI administration (again): []
    OK to store this configuration: [Y] y
  7. Start the daemon
    > /etc/init.d/lockss start
  8. Connect to the web interface
    with your favorite browser, go to:
    http://your_ip_address:8081
    user/pwd: previously defined credentials
    no need to chkconfig on, done automatically
    if any error appears, check /var/log/lockss/stdout for info
  9. Ask PLN admin to update
  • the lockss.xml file with the new cache IP address
  • nagios monitoring server configuration

How to create a title database?

  • Placeholder for MetaArchive title db configuration (forthcoming)

How to expose your content to LOCKSS?

How to create, sign and publish a plug-in?

How to ingest content with the UI?

How to monitor your AUs status?

How to replace, upgrade or insert a new node in a PLN already in production?

When a new cache is inserted in the PLN (due to a new institution contributing to the PLN, a cache repair or a regular 3-year cache disk replacement) and if this new cache shows a valid security certificate, it should directly collect AUs not from the original source (the AU publisher) but from another cache in the PLN configured as a proxy. The idea is that the PLN should survive the institutions, implying that the safe source of information is supposed to be the PLN itself and not the original source which is supposed to be more prone to attacks and less safe than our PLN. This is actually another point of view than "LOCKSS cache can be used as a proxy for the original server at anytime" which assumes that the original source is always the reference and which, in my understanding, should be only used for the GLN and not for PLNs. If I understand well, this behavior should be easy to configure by setting the AU parameter org.lockss.crawler.fetch_from_other_caches_only to true, forcing the cache to collect the AU from other caches.

Advanced configuration, fine-tuning and more

Securing your PLN

For the web interfaces, IP filtering is turned on be default, and can be configured through the UI (Admin Access Control, Content Access Control). Stronger security is available (SSL, form authentication with inactivity timeouts, password rotation and strength requirements, etc.) for all but the proxy. The easiest way to enable this is to choose one of the pre-defined policies by setting org.lockss.accounts.policy to one of {BASIC, FORM, SSL, LC}. BASIC just enables the user accounting subsystem and allows you to create additional user accounts; FORM replaces the basic auth method (browser popup) with an HTML form, SSL replaces HTTP with HTTPS, and LC enables the strict Library of Congress security policies (strong passwords, password rotation, session timeouts, auditing of user-initiated events, etc.) When you enable SSL you can either give it a server certificate or let it generate one itself (in which case browsers will produce a scary warning about a self-signed certificate, which users will have to accept. I recommend you use the defaults at first and turn on additional security once you have things working.

LCAP communication is unencrypted by default. If you put the appropriate keystores in /etc/lockss/keys, the startup scripts will automatically enable v3overSSL and sslClientAuth, which will cause all communication to be encrypted and all connections to be verified as coming from a node with a valid key. It's best to leave this until all or most of the nodes are up and running as generating and distributing the key files adds a nuisance factor.

In-depth Guide to LOCKSS

Tobin Cataldo at ADPN has created an in-depth guide to the LOCKSS software.

Software that works with LOCKSS

There's a list.

Basic documentation describing how to set-up a simple testPLN environment

Media:PLN_kick_off_meeting_290413.pdf