LionShare Peer Server Installation Instructions
support@lionshare.its.psu.edu

Introduction:
Thank you for you intrest in the LionShare project.  This document describes the installation of a LionShare Peer Server.  This Server will provide users the ability to persistently share files on the P2P network when local client Peers have been disconnected from the network.  These instructions will describe in detail what is needed to have a successful LionShare Peer Server installation.

Pre-Requisites:
1    Download and Install the Java J2SE 5.0 Runtime Environment from
http://java.sun.com
1    Request a Long Term Certificate from your SASL-CA administrator. See Appendix A for instructions.
2    Install and Configure a PostgresSQL or MySQL database installation.

Quick Install:
1    Download the LionShare Peerserver from http://lionshare.its.psu.edu/downloads/releases/lionshare-peerserver/
2    Unpackage the peerserver with you favorite zip utility.
3    Run the peerserver
On Linux:
cd lionshare-peerserver/bin
./startup.sh

On Windows:
cd lionshare-peerserver\bin
startup.bat

Custom Installation: Follow steps 1 & 2 of the Quick Install and then proceed with the following instructions.
Database Configuration:
By default LionShare comes with an open source embedded Java database from the Apache Derby project.  Although this database is adequate for testing the LionShare Peer Server we strongly discourage its use in production deployments.  Switching to another open source database such as PostgreSQL or MySQL should be relatively simple.
#For PostgreSQL:
cd lionshare-peerserver/config
cp server-postgres.xml server.xml
edit server.xml

#Search for the following section in server.xml and make sure that you have the appropriate username/password configured for you database user and that the database URL is correct.

         <Resource name="jdbc/peerserver"
                   auth="Container"
                   type="javax.sql.DataSource"
                   driverClassName="org.postgresql.Driver"
                   url="jdbc:postgresql://127.0.0.1:5432/peerserver"
                   username="tomcat"
                   password="XXXXX"
                   maxActive="100"
                   maxIdle="25"
                   maxWait="10000" />

cd lionshare-peerserver/webapps/lionshare-peerserver/WEB-INF/classes
edit hibernate.properties
#Comment out the derby dialect and uncomment the Postgres as follows
#hibernate.dialect=org.hibernate.dialect.DerbyDialect
#hibernate.dialect=org.hibernate.dialect.MySQLDialect
hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

#Note the same procedures should be applied for configuring MySQL with the exception of replacing references to postgres with mysql.

Tomcat Configuration:

1    Configure Tomcat server.xml
In your lionshare-peerserver/config directory you will find a file named server.xml. Certain changes need to be made to this file for the lionshare-peerserver.

There are three server socket connectors created for the LionShare Peer Server, and those connectors can be configured from the server.xml file.  Of most notable importance is the path to the keystore and trustore located in the connector descriptor listed below.  The keystoreFile path should point to the location of the keystore containing the PeerServer's certificate.   
    <Connector port="8443"
               maxThreads="150" minSpareThreads="25"
    maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="true" sslProtocol="TLS"
               redirectPort="8444" maxKeepAliveRequests="-1"
               maxSavePostSize="-1" maxPostSize="-1"
               maxHttpHeaderSize="16384"
               keystoreFile="../.keystore"
               truststoreFile="../.truststore"
               truststorePass="foobar"/>
asdfa
It is important to note the following attributes and verify their correctness as well.
Attribute Name    Description
port    The port to run the secure socket on (default = 8443 )
clientAuth    Verify the identity of the client certificate, this must be set to true in order to ensure only valid users can use your peerserver (default = true )
maxKeepAliveRequests    The number of request per connections, this value needs to be set high to ensure large files can be uploaded without the connection being closed (default = -1 ) disabled
maxSavePostSize    The size of post request (default = -1 )
maxPostSize    The size of a post request (default = -1) disable.  This value needs to be large to ensure that a POST request for a protected file, which contains signed attributes from the client is not limited by Install and Configure a PostgresSQL or MySQL database installation.

Quick Install:
1    Download the LionShare Peerserver from http://lionshare.its.psu.edu/downloads/releases/lionshare-peerserver/
2    Unpackage the peerserver with you favorite zip utility.
3    Run the peerserver
On Linux:
cd lionshare-peerserver/bin
./startup.sh

On Windows:
cd lionshare-peerserver\bin
startup.bat

Custom Installation: Follow steps 1 & 2 of the Quick Install and then proceed with the following instructions.
Database Configuration:
By default LionShare comes with an open source embedded Java database from the Apache Derby project.  Although this database is adequate for testing the LionShare Peer Server we strongly discourage its use in production deployments.  Switching to another open source database such as PostgreSQL or MySQL should be relatively simple.
#For PostgreSQL:
cd lionshare-peerserver/config
cp server-postgres.xml server.xml
edit server.xml

#Search for the following section in server.xml and make sure that you have the appropriate username/password configured for you database user and that the database URL is correct.

         <Resource name="jdbc/peerserver"
                   auth="Container"
                   type="javax.sql.DataSource"
                   driverClassName="org.postgresql.Driver"
                   url="jdbc:postgresql://127.0.0.1:5432/peerserver"
                   username="tomcat"
                   password="XXXXX"
                   maxActive="100"
                   maxIdle="25"
                   maxWait="10000" />

cd lionshare-peerserver/webapps/lionshare-peerserver/WEB-INF/classes
edit hibernate.properties
#Comment out the derby dialect and uncomment the Postgres as follows
#hibernate.dialect=org.hibernate.dialect.DerbyDialect
#hibernate.dialect=org.hibernate.dialect.MySQLDialect
hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

#Note the same procedures should be applied for configuring MySQL with the exception of replacing references to postgres with mysql.

Tomcat Configuration:

1    Configure Tomcat server.xml
In your lionshare-peerserver/config directory you will find a file named server.xml. Certain changes need to be made to this file for the lionshare-peerserver.

There are three server socket connectors created for the LionShare Peer Server, and those connectors can be configured from the server.xml file.  Of most notable importance is the path to the keystore and trustore located in the connector descriptor listed below.  The keystoreFile path should point to the location of the keystore containing the PeerServer's certificate.   
    <Connector port="8443"
               maxThreads="150" minSpareThreads="25"
    maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="true" sslProtocol="TLS"
               redirectPort="8444" maxKeepAliveRequests="-1"
               maxSavePostSize="-1" maxPostSize="-1"
               maxHttpHeaderSize="16384"
               keystoreFile="../.keystore"
               truststoreFile="../.truststore"
               truststorePass="foobar"/>
asdfa
It is important to note the following attributes and verify their correctness as well.
Attribute Name    Description
port    The port to run the secure socket on (default = 8443 )
clientAuth    Verify the identity of the client certificate, this must be set to true in order to ensure only valid users can use your peerserver (default = true )
maxKeepAliveRequests    The number of request per connections, this value needs to be set high to ensure large files can be uploaded without the connection being closed (default = -1 ) disabled
maxSavePostSize    The size of post request (default = -1 )
maxPostSize    The size of a post request (default = -1) disable.  This value needs to be large to ensure that a POST request for a protected file, which contains signed attributes from the client is not limited by size.
maxHttpHeaderSize    The maximum size of the HTTP head (default = 16384) this value ensure that HTTP request can contain large headers with client signed attributes for secure requests.
keystoreFile    The path to the keystore with the PeerServer's certificate.
truststoreFile    The trust file that contains the trusted root certificates for all clients that attempt to connect to the peerserver.  We highly recommend you use the one found in  lionshare-peerserver-xxx/.truststore
truststorePass    The password that protects the truststore file (default = foobar ) for the trustore file found in lionshare-peerserver-xxx/.truststore


LionShare Peer Server Configuration:   
1    Configure PeerserverProperties.properties
The peerserver contains one main configuration file called 
PeerserverProperties.properties, a default version of this file can be found in
lionshare-peerserver/webapps/lionshare-peerserver/WEB-INF/classes, this file should be customized to your installation needs.
#Peerserver Properties
#Wed Feb 16 14:36:11 EST 2005
kerbkdc=sherlock.aset.psu.edu
jaasconfig=../../config/jaas.conf
kerbrealm=dce.psu.edu
quota=1000
peerserver_description=The default peerserver Install and Configure a PostgresSQL or MySQL database installation.

Quick Install:
1    Download the LionShare Peerserver from http://lionshare.its.psu.edu/downloads/releases/lionshare-peerserver/
2    Unpackage the peerserver with you favorite zip utility.
3    Run the peerserver
On Linux:
cd lionshare-peerserver/bin
./startup.sh

On Windows:
cd lionshare-peerserver\bin
startup.bat

Custom Installation: Follow steps 1 & 2 of the Quick Install and then proceed with the following instructions.
Database Configuration:
By default LionShare comes with an open source embedded Java database from the Apache Derby project.  Although this database is adequate for testing the LionShare Peer Server we strongly discourage its use in production deployments.  Switching to another open source database such as PostgreSQL or MySQL should be relatively simple.
#For PostgreSQL:
cd lionshare-peerserver/config
cp server-postgres.xml server.xml
edit server.xml

#Search for the following section in server.xml and make sure that you have the appropriate username/password configured for you database user and that the database URL is correct.

         <Resource name="jdbc/peerserver"
                   auth="Container"
                   type="javax.sql.DataSource"
                   driverClassName="org.postgresql.Driver"
                   url="jdbc:postgresql://127.0.0.1:5432/peerserver"
                   username="tomcat"
                   password="XXXXX"
                   maxActive="100"
                   maxIdle="25"
                   maxWait="10000" />

cd lionshare-peerserver/webapps/lionshare-peerserver/WEB-INF/classes
edit hibernate.properties
#Comment out the derby dialect and uncomment the Postgres as follows
#hibernate.dialect=org.hibernate.dialect.DerbyDialect
#hibernate.dialect=org.hibernate.dialect.MySQLDialect
hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

#Note the same procedures should be applied for configuring MySQL with the exception of replacing references to postgres with mysql.

Tomcat Configuration:

1    Configure Tomcat server.xml
In your lionshare-peerserver/config directory you will find a file named server.xml. Certain changes need to be made to this file for the lionshare-peerserver.

There are three server socket connectors created for the LionShare Peer Server, and those connectors can be configured from the server.xml file.  Of most notable importance is the path to the keystore and trustore located in the connector descriptor listed below.  The keystoreFile path should point to the location of the keystore containing the PeerServer's certificate.   
    <Connector port="8443"
               maxThreads="150" minSpareThreads="25"
    maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="true" sslProtocol="TLS"
               redirectPort="8444" maxKeepAliveRequests="-1"
               maxSavePostSize="-1" maxPostSize="-1"
               maxHttpHeaderSize="16384"
               keystoreFile="../.keystore"
               truststoreFile="../.truststore"
               truststorePass="foobar"/>
asdfa
It is important to note the following attributes and verify their correctness as well.
Attribute Name    Description
port    The port to run the secure socket on (default = 8443 )
clientAuth    Verify the identity of the client certificate, this must be set to true in order to ensure only valid users can use your peerserver (default = true )
maxKeepAliveRequests    The number of request per connections, this value needs to be set high to ensure large files can be uploaded without the connection being closed (default = -1 ) disabled
maxSavePostSize    The size of post request (default = -1 )
maxPostSize    The size of a post request (default = -1) disable.  This value needs to be large to ensure that a POST request for a protected file, which contains signed attributes from the client is not limited by size.
maxHttpHeaderSize    The maximum size of the HTTP head (default = 16384) this value ensure that HTTP request can contain large headers with client signed attributes for secure requests.
keystoreFile    The path to the keystore with the PeerServer's certificate.
truststoreFile    The trust file that contains the trusted root certificates for all clients that attempt to connect to the peerserver.  We highly recommend you use the one found in  lionshare-peerserver-xxx/.truststore
truststorePass    The password that protects the truststore file (default = foobar ) for the trustore file found in lionshare-peerserver-xxx/.truststore


LionShare Peer Server Configuration:   
1    Configure PeerserverProperties.properties
The peerserver contains one main configuration file called 
PeerserverProperties.properties, a default version of this file can be found in
lionshare-peerserver/webapps/lionshare-peerserver/WEB-INF/classes, this file should be customized to your installation needs.
#Peerserver Properties
#Wed Feb 16 14:36:11 EST 2005
kerbkdc=sherlock.aset.psu.edu
jaasconfig=../../config/jaas.conf
kerbrealm=dce.psu.edu
quota=1000
peerserver_description=The default peerserver size.
maxHttpHeaderSize    The maximum size of the HTTP head (default = 16384) this value ensure that HTTP request can contain large headers with client signed attributes for secure requests.
keystoreFile    The path to the keystore with the PeerServer's certificate.
truststoreFile    The trust file that contains the trusted root certificates for all clients that attempt to connect to the peerserver.  We highly recommend you use the one found in  lionshare-peerserver-xxx/.truststore
truststorePass    The password that protects the truststore file (default = foobar ) for the trustore file found in lionshare-peerserver-xxx/.truststore


LionShare Peer Server Configuration:   
1    Configure PeerserverProperties.properties
The peerserver contains one main configuration file called 
PeerserverProperties.properties, a default version of this file can be found in
lionshare-peerserver/webapps/lionshare-peerserver/WEB-INF/classes, this file should be customized to your installation needs.
#Peerserver Properties
#Wed Feb 16 14:36:11 EST 2005
kerbkdc=sherlock.aset.psu.edu
jaasconfig=../../config/jaas.conf
kerbrealm=dce.psu.edu
quota=1000
peerserver_description=The default peerserver description
gnu_port=6346
peerserver_host_address=localhost
peerserver_name=localhost
non_secure_port=8080
secure_port=8443
max_virtual_directories_per_user=10
file_storage_dir=UserFiles

    The table below gives a description of each property PeerserverProperties.properties.
Attribute    Description
kerbkdc    This attribute is required to allow kerberos authentication of the peerserver adminstrators, example kerbkdc=fido.aset.psu.edu
kerbrealm    This attribute is required to allow kerberos authentication of the peerserver administrators, example
kerbrealm=dce.psu.edu
quota    This quota limits the amount of data that a user may upload to a peerserver, the amount is in MB,  example quota=1000, means users have 1 Gig of available space on a peerserver.
jaasconfig    This attribute is required to allow kerberos authentication of the peerserver administrators, example
jaasconfig=jaas.conf.  The jaas.conf file must be within the peerservers classpath.
gnu_port    This is the port number that the gnutella query messages will be sent and received on,  example gnu_port=7791
peerserver_host_address    This is the IP or Host address that will be sent in query replies to allow users to download the files from, examples
peerserver_host_address=harpua.tlt.psu.edu
peerserver_host_address=128.118.102.222
non_secure_port    The port number in which insecure files will be uploaded from.  This value needs to align with the insecure connector configured in tomcat,  example  non_secure_port=8080
secure_port    The port number in which secure/protected files will be uploaded. This value needs to align with the secure connector configured in the tomcat server.xml file,example
secure_port=8443
max_virtual_directories_per_user    This is the maximum number of virtual directories that a user may create on this peersever, example
max_virtual_directories_per_user=10
file_storage_dir    This is the location where the files uploaded by users will be stored. 
peerserver_name    The name of the peerserver that will be displayed in the uddi registry listing
peerserver_description    A description of the peerserver that will be displayed in the uddi registry listing
uddi_registery_url    The host/ip of the uddi registery that this peerserver should automatically annouce itself too.
uddi_registery_port    The port number that the uddi_registery is listeninig on that this peerserver will annouce itself too.
2    Peer Server Admin users:
To allow a user to become an administrator of the peerserver, the user needs to be specified in the lionshare-peerserver/webapps/lionshare-peerserver/WEB-INF/web.xml configuration file.  Example users already exist asv108@dce.psu.edu, lmm270@dce.psu.edu.   These should be removed and switch to the principal names of your peerserver adminstrator as listed in your instution's Kerberos Realm.  Example username@kerberos.realm


Testing:  You should now be ready to start and test the LionShare peerserver.

cd lionshare-peerserver/bin
./run  or   run.bat

After starting the peerserver you should view  lionshare-peerserver/logs to verify that no problems have occurred on startup.

Once started you may proceed to http://peerserver.address:8444/Admin where you should be prompted to login.  Once you provide you username and password for the user configured in the web.xml above you should see the following screen.
 

If the above screen does not appear, then there is a problem with your installation.   Please consult the Troubleshooting section that doesn't yet exists! or contact me via email at lmetzger@psu.edu

Now from the LionShare client you should be able to add your newly created peerserver to Library interface, under the peerservers node.

Thanks again for interest in LionShare, please feel free to contact the lionshare team with any questions or comments at  support@lionshare.its.psu.edu.


 
Appendix A: Obtaining a PeerServer Certificate

The PeerServer needs a certificate to establish SSL sessions with remote users. For convenience's sake, this certificate is usually issued by your institution's SASL-CA.

1    You must first generate a keypair. Issue the following commands:

    cd lionshare-peer/config

    keytool     -genkey -keyalg RSA -keysize 1024 \
        -alias peerserver -keystore .keystore

You will be prompted for a password for the keystore. The password should be "changeit" (without the quotes). You will then be prompted for your first and last name. In this field, type the fully qualified hostname of the Peer Server (such as peerserver.yourinstitution.edu).

You will then be prompted for your Organizational Unit, Organization, City, State and Country. You can leave these fields blank or fill them in if you like. Finally, you will be prompted for a keypassword. Leave this blank (just press RETURN).
       
1    Using the keystore from step 1, you will generate a Certificate Signing Request (CSR).  Use the following command:

    keytool     -certreq -keystore .keystore \
        -alias peerserver -file peerserver.csr

This command will generate a file, peerserver.csr, which you will need to email to your SASL-CA admininistrator. During the LionShare pilot phase at Penn State, you should email Derek Morr (derekmorr@psu.edu) to request a certificate.

1    Your SASL-CA administrator will email you two certificates: the SASL-CA's root certificate and a certificate for your PeerServer. You must import both of these certificates into the keystore you made in step 1.

First, import the SASL-CA's root certificate:

    keytool -import -file root.certificate -keystore .keystore

You will be asked if you want to trust this certificate. Enter yes.

Next, import the PeerServer's certificate:

    keytool -import -file peerserver.certificate -keystore .keystore