Describes the process of installing pillars.

Installation Guide for a ChecksumPillar

This is a installation guide for version 1.6 of the ReferenceChecksumPillar using a PostgreSQL database and certificates. Installation being performed on Linux.

Dependencies:

For the ChecksumPillar to be able to run, the following is required on the machine, before installation:

Requires Java v. 8 (can be either Oracle or OpenJDK)
Requires installation of PostgreSQL.
Requires open firewall to the ActiveMQ of the setup.

For configuring the ChecksumPillar to be able to participate in a repository-setup, the following is required:

A certificate in pem
- Can either be created locally (see Create self signed certificate) or delivered from those who administers the central Repository.
- This certificate must be registered at the ActiveMQ, so the pillar can use it for communication.
The pillar ID for the ChecksumPillar
ReferenceSettings.xml
- Can be downloaded at https://github.com/bitrepository/reference/raw/bitrepository-parent-1.6/bitrepository-integration/src/main/resources/quickstart/conf/checksumpillar/ReferenceSettings.xml.
- See configuration.
RepositorySettings.xml
- Must contain a Permission section with the certificate, and at least one Collection containing the PillarID.
- This file must also be distributed to all other component (services, client and other pillars) in its newest form.

Installation of the ChecksumPillar

Download the software for the ChecksumPillar:
> wget http://sbforge.org/nexus/content/repositories/releases/org/bitrepository/reference/bitrepository-reference-pillar/1.6/bitrepository-reference-pillar-1.6-distribution.tar.gz

Unpack the package:
> tar xvf bitrepository-reference-pillar-1.6-distribution.tar.gz

Install the database

Start in the root of the installation directory, and run the following through a terminal:

> createuser -P -s -e bitmag
(write 'bitmag' for both username and password)
> createdb checksumdb
> createdb auditdb
> psql -d checksumdb -f sql/postgres/checksumDBCreation.sql
> psql -d auditdb -f sql/postgres/auditContributorDBCreation.sql

Configuration

Place the RepositorySettings.xml, the ReferenceSettings.xml and the certificate in the 'conf' directory.

ReferenceSettings

Change the following in the ReferenceSettings (The dots means parts of the ReferenceSettings, which you can ignore):

<ReferenceSettings xmlns="http://bitrepository.org/settings/ReferenceSettings.xsd">
...
<PillarSettings>
    <PillarID>YOUR_PILLAR_ID</PillarID>
    <PillarType>CHECKSUM</PillarType>
...
    <AuditTrailContributerDatabase>
      <DriverClass>org.postgresql.Driver</DriverClass>
      <DatabaseURL>jdbc:postgresql:auditdb</DatabaseURL>
      <Username>bitmag</Username>
      <Password>bitmag</Password>
    </AuditTrailContributerDatabase
    <ChecksumDatabase>
      <DriverClass>org.postgresql.Driver</DriverClass>
      <DatabaseURL>jdbc:postgresql:checksumdb</DatabaseURL>
      <Username>bitmag</Username>
      <Password>bitmag</Password>
    </ChecksumDatabase>
...
</PillarSettings>
</ReferenceSettings>

Bitmag.sh

Change the path to the certificate in the bitmag.sh file in the 'bin' folder.

Setup as a Service

Turn the pillar into a Linux service. Place the following script in '/etc/init.d/' (remember to replace the path):

#!/bin/sh
#-----------------------------------------------------------------------
#
# chkconfig: 345 84 14
#
# description: Service script (start, stop status) for BitMag pillar service.
#
#-----------------------------------------------------------------------

USER_ACCT="modisk01"

case "$1" in
'start')
        su - $USER_ACCT -c "/path/to/pillar/bin/pillar.sh start"
        ;;

'stop')
        su - $USER_ACCT -c "/path/to/pillar/bin/pillar.sh stop"
        ;;

'status')
        su - $USER_ACCT -c "/path/to/pillar/bin/pillar.sh status"Installation Guide for ChecksumPillar         ;;
*)
        echo "Usage: $0 { start | stop | status }"
        exit 1
        ;;
esac
exit $?

Validate

Start the service and look in the log (under log folder). It should have the following lines (dots for ignore the begining and/or the end the line):

... Initializing ActiveMQMessageBus...
... Settings component filter to: <PILLARID>
... Creating the connection to the database 'DatabaseSpecifics [driverClass=org.postgresql.Driver, ...
... Starting the ReferencePillar of type 'CHECKSUM'

Ensure that the pillar did not erroneous automatically create a Derby database, by validating the no 'checksumDB' or 'auditDB' folders is located either the installation directory or a conf/checksum folder.

ChecksumPillar functionality

To instantiate the ChecksumPillar, run the 'checksum-pillar.sh' script from the 'bin' folder.

The following are legal ChecksumPillar commands

checksum-pillar.sh start
checksum-pillar.sh stop
checksum-pillar.sh restart
checksum-pillar.sh status

Installation Guide for the ReferencePillar

The ReferencePillar currently comes in two different formats, the FullReferencePillar and the ChecksumReferencePillar (also know as the ChecksumPillar), and currently they both requires commandline installation and instantiation.

This is the guide for installing ReferencePillars of version 0.19 or more.

The installation of the ReferencePillar is done in the following way:

Download the ReferencePillar zip file. (https://sbforge.org/nexus/content/repositories/releases/org/bitrepository/reference/bitrepository-reference-pillar/)
Unzip the zip-file.
Go to the directory root directory, where the zip-file has been unzipped (named 'bitrepository-reference-pillar-VERSION').
Copy your settings files into the 'conf' subfolder, e.g. the CollectionSettings.xml and the ReferenceSettings.xml. (There is already placed examples of these settings in the 'conf' directory)
Copy you certificate file (e.g. 'pillar-XX.pem') in the 'conf' subfolder.
Run the bin/create_databases.sh script. This will create the checksum and auditContributor databases according to the settings in the ReferenceSettings.xml.

FullReferencePillar Functionality

To instantiate the FullReferencePillar run the 'reference-pillar.sh' script from the 'bin' folder.

The following are legal FullReferencePillar commands

reference-pillar.sh start
reference-pillar.sh stop
reference-pillar.sh restart
reference-pillar.sh status

Upgrading the ReferencePillar

Before you upgrade the ReferencePillar (either the FullReferencePillar or the ChecksumPillar) make sure, that you have the following (e.g. place a copy outside the current installation prior to upgrading):

The zip-file with the new version of the ReferencePillar.
The CollectionSettings, ReferenceSettings and certificate for the new installation of the ReferencePillar (they might be same as for the version you are about to upgrade)

Refer to the release-notes for the version you are about to upgrade to. Follow the version specific upgrade guides, if any.

To upgrade an existing ReferencePillar while preserving the databases and files do the following:

Shutdown the current instance of the pillar (e.g. run 'reference-pillar.sh stop' or 'checksum-pillar.sh stop' in the 'bin' folder).
Delete the 'bin', 'lib' and 'conf' folders in the installation directory of the pillar.
Unzip the file into the current installation directory (or unzip it elsewhere and move the folders 'bin', 'conf' and 'lib' into the installation directory of the pillar).
Copy the CollectionSettings, the ReferenceSettings and the certificate files for the ReferencePillar into the 'conf' directory.
Start the pillar (e.g. run 'reference-pillar.sh start' or 'checksum-pillar.sh start').

Installation Guide for Non-Reference Pillar

Descripes how to setup other pillars than the reference pillars in a collection.

Pillars other than the reference pillars must be setup according to the specific pillar instructions.The Non-reference pillars will typically be organization specific, and it is the role of that organization to create a installation guide for its specific pillar.

The pillar installation will require the RepositorySettings to be available, as they define the infrastructure the pillar should be connected to.

Bitrepository

Pillar setup