NeurologWikiSite

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== NeuroLOG middleware prototype ======

This page describes the current status of the NeuroLOG middleware prototype. It gives installation and configuration instructions.




===== Distribution and execution =====

The software is distributed in the following archive:
  * [[http://egee1.unice.fr/NeuroLOG_Middleware-0.1.1.tgz|NeuroLOG middleware v0.1.1 archive]]
This version was tested under linux only.


The archive unpacks in two sub directories:
  * ''bin'' contains services startup scripts
  * ''dist'' contains the program jar archive and its dependencies 


The archive is meant to be unpacked in the HOME directory of a regular user under whom ID the NeuroLOG services will execute. It is recommended, although not mandatory, to create a specific user account. On installation the software will create extra directories, in particular ''~/.neurolog'' for writing configuration files and ''~/log'' for writing services logs.


The software is currently composed of 3 main services:
  * The **NeuroLOG Registry service** is meant to be deployed on a single site (root site). It ensures coordination between participating sites.
  * The **NeuroLOG Site Server** is meant to be deployed on each participating site.
  * The **NeuroLOG Client** is meant to be deployed on each user client machine. 
The ''bin'' directory contains 3 facility scripts to start each of these services:
  * ''bin/nlog_registry'' for the NeuroLOG Registry service;
  * ''bin/nlog_server'' for the NeuroLOG Site Server; and
  * ''bin/nlog_client'' for the NeuroLOG client.
Note that if the ''dist'' directory is not deployed in the HOME directory of the user, the ''nlog_*'' scripts need to be edited to change the second line (JAR variable containing the path to the main NeuroLOG jar file inside the dist directory). The first line (Java VM location may also need to be updated depending on your installation.




===== Installation =====

You need to install 1, 2 or the 3 components depending on who you are. The components self-configure on the first execution.

=== Prerequisites ===

The software requires:
  * The [[http://java.sun.com/javase/downloads|Java Runtime Environment version 1.6]]
The NeuroLOG Registry and Site Server also depend on:
  * [[http://dev.mysql.com/downloads/mysql/5.0.html#downloads|MySQL version 5.0]]
  * [[http://www.openssl.org/source|openssl]]
  * java keytool (this should be part of the JRE)

Check that your MySQL server is started before installing the Registry or a Site Server.

=== If you are installing a complete platform ===

You first need to deploy a single **NeuroLOG Registry** service. Run the ''bin/nlog_registry'' script and follow the instructions. The software will create the registry configuration files and a root Certification Authority for the platform. A Registry server certificate will also be created. You will be asked to sign the server certificate using a given openssl command to be executed in a shell.

The registry exposes 3 ports to which the other services will connect. The port numbers are configurable during the installation. Your firewall need to authorize incoming connections to these ports to ensure proper functioning of the platform. The default ports configuration is:
  - port **63876**: Java RMI registry service
  - port **63877**: Registry secured interface, used for all communication but initialization
  - port **63878**: Registry unsecured interfaced, only used for new site requests initialization

The NeuroLOG registry includes two separate programs: a daemon server and a graphical interface for the administrator. Upon successful installation, both programs are started. The interface can be shut down through the ''Administration -> Exit'' menu while the daemon keeps running.


=== If you are a system administrator ===

You need to deploy a single **NeuroLOG Site Server** per participating site. Run the ''bin/nlog_server'' script and follow the installation instructions. The software will first create the server configuration files and a site Certification Authority that depends on the Registry root CA. During the configuration phase, you need to provide a site name (typically the participating organization name). You also need to specify the NeuroLOG Registry service to connect to. If you are connecting to a self-installed registry service, set up your parameters accordingly. If you are deploying a NeuroLOG project site, you should connect to the official registry service:
  * host fully qualified name: ''proton.polytech.unice.fr''
  * RMI port: 63876
  * Secured interface port: 63877
  * Unsecured interface port: 63878

The installation procedure is a two steps process. On the first run, a CA certificate request is generated and sent to the Registry CA administrator. The process then normally exits, waiting for the Registry CA administrator to sign the request. You will be notified by phone or email when your request is ready to be retrieved. You can then restart the program to proceed with the second step. During the second step, the signed CA certificate is retrieved. The root CA certificate is then imported. The site administrator is requested to validate the root CA certificate fingerprint as follows:

{{public_namespace:registry-fingerprint.png}}

**Carefully check the fingerprint value of the certificate you are importing as the complete trust chain depends on it**. If you are connecting to the official NeuroLOG project Registry service, the finger print should exactly match:

  6B:27:87:FE:13:3B:C2:66:A5:E7:17:07:68:AD:2C:A2:B9:42:8E:71

If you are connecting to a different service, the fingerprint will be different. Check its value with your Registry administrator.

Once done, a Registry server certificate will be created. You will be asked to sign the server certificate using a given openssl command to be executed in a shell.

The server exposes 3 ports to which the Registry and clients will connect. The port numbers are configurable during the installation. Your firewall need to authorize incoming connections to these ports to ensure proper functioning of the platform. The default ports configuration is:
  - port **63876**: Java RMI registry service
  - port **63878**: Server secured interface, used for all communication but clients initialization
  - port **63880**: Server unsecured interfaced, only used for new client requests initialization

The NeuroLOG Site Server includes two separate programs: a daemon server and a graphical interface for the administrator. Upon successful installation, both programs are started. The interface can be shut down through the ''Administration -> Exit'' menu while the daemon keeps running.

=== If you are a user ===

The **NeuroLOG Client** can be installed on personal user machines. Run the ''bin/nlog_client'' script and follow the installation instructions. The software will first create the client configuration files. During the configuration phase, you need to provide the information on the site server to connect to. Check with your site administrator for the site name and the connectivity information of your site. The default parameters are:
  * RMI port: 63876
  * Secured interface port: 63879
  * Unsecured interface port: 63880

The installation procedure is a two steps process. On the first run, a user certificate request is generated and sent to the site CA administrator. The process then normally exits, waiting for the site administrator to sign the request. You will be notified by phone or email when your request is ready to be retrieved. You can then restart the program to proceed with the second step. During the second step, the signed user certificate is retrieved. The site CA certificate is then imported. You are requested to validate the site CA certificate fingerprint. **Carefully check the fingerprint value of the certificate you are importing as the complete trust chain depends on it**. Contact your site administrator to verify its value.

On completion, the client graphical interface will start.




===== Normal runs =====

On the first run, the NeuroLOG Registry service and the NeuroLOG Site Server will fork a daemon process executing in background even if the administator interface is terminated. On subsequent runs, the program auto-detects if a daemon is running. If a daemon is found, only the administrator interface is started and it is reconnected to the daemon. If no daemon can be found, a new daemon is forked. The administrator interface can be used to terminate a running daemon through the ''Administration -> Kill daemon'' menu.

===== Configuration =====

The services are normally self-configured during the installation process. If you need to change some configuration parameters later, the text configuration files can be edited. Configuration changes require an application restart to be taken into account.

The default configuration files are located in ''~/.neurolog''. The default files are:
  - ''registry.config'' for the NeuroLOG Registry service
  - ''server.config'' for the NeuroLOG Site Server
  - ''client.config'' for the NeuroLOG client

Note that the default configuration file location can be overriden by the ''-c'' option.

===== Sources ======

The source files are available through the [[http://nyx.unice.fr/svn/neurolog|NeuroLOG SVN repository]]. A [[http://nyx.unice.fr/projects/neurolog|TRAC server]] is also available for following the developments.



===== Troubleshooting =====

The services logs are written to a file. The exact file name is configured during the services installation phase. By default it is located in the ''~/log'' repository. If it was configured differently, the log file location can be found from the service configuration file. Also note that the ''-l'' command line option may be used to override the log file location.



===== TODO =====

The prototype only provides basic distribution facilities and data importation capability currently. Most components still need to be integrated. The data importation prototype available is not secured in the sense that images are not anonymized and files are not encrypted.