Infolog configuration and installation guide

Infolog is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Infolog is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Infolog. If not, see http://www.gnu.org/licenses.

Introduction

The Infolog desktop client is the desktop companion of Egroupware Infolog. It can be used in conjunction with an Egroupware installation or as a stand alone program. Infolog consists of a client and a server program. The client is capable of synchronizing with the server on a regular basis. This file provides information about the configuration of the client and the server program. Both the server and the client program are provided through the same archive.

1. Infolog Client

Installation

In order to run the client the provided archive should be extracted to a convenient directory on the client computer. After extraction, the following file structure should be in place:

/Infolog installation directory
 |
 |-infolog.properties
 |-log4j.xml
 |-Infolog.jar
 |-/icons
 |-/data

Configuration

infolog.properties

This file contains several configuration options for the program. Configuration of the connection to the server is done through the gui as explained later on. To use the program locally it is not necessary to configurate a username or password. Coloring, spacing, size of sticky notes and look and feel of the gui is configurable through this file. The file is heavily documented, therefore no further explanation will be given here.

log4j.xml

Logging is done through the log4j system. Normally logging is written to a file as configured by this xml file. By changing the "appender", logging can be written to the console as wel. The amount of logging is configured through the "threshold" property. Higher levels will generate fewer logging. Possible levels are: DEBUG, INFO, WARN, ERROR and FATAL. See http://logging.apache.org/log4j/1.2/ for further information.

icons

This directory contains the icons used by the program. The system tray icon can be configured in the properties file. As java on linux systems provides no decent transparency, you could create a "fake transparent" icon yourself by taking a picture and gluing this on a background with the same color as your taskbar. The screenshots prove that you can blend the icon with the background as if the icon is transparent. On windows systems this problem does not exist.

Run client program

The program is provided as an executable jar file (java archive) named Infolog.jar. The program can be started using the following command:

java -jar Infolog.jar client

This will run the client application. You can create sticky notes right away. If you want to make your sticky notes available through Egroupware you have to run the server program as well, which is explained in the next section. To configure the connection to this server click on 'Actions' -> 'Configure' to provide the username, password and the hostname or ip address the server program is running on. Now click on 'Test credentials' to login on the server. If the program is able to login it will notify you, otherwise an error message is shown. The program will synchronize with the server at startup, shutdown and at regular intervals configurable through the properties file.

2. Infolog Server

Installation

In order to run the server the provided archive should be extracted to a convenient directory on the server computer. After extraction, the following file structure should be in place:

/Infolog installation directory
 |
 |-infolog.properties
 |-hibernate.cfg.xml
 |-log4j.xml
 |-Infolog.jar

Configuration

infolog.properties

This file contains several configuration options for the program. The file is heavily documented so no further explanation will be given here. For the server part it is unlikely any option should be changed, but note that the server uses two ports to expose the sticky notes to the clients. When a firewall is in place, these two ports should be opened.

hibernate.cfg.xml

This file contains the configuration for the database connection in xml format. Several properties are of importance here:

hibernate.connection.url

This is the full url to the database:

jdbc:mysql://<SERVERNAME OR IP>:<PORT>/<DATABASE NAME>

e.g.

jdbc:mysql://localhost:3306/egroupware

```
hibernate.connection.username
```
The username of the database user with sufficient rights to alter entries in the database.
```
hibernate.connection.password
```
The password of the database user.

log4j.xml

Run server program

The program is provided as an executable jar file (java archive) named Infolog.jar. The program can be started using the following commands:

java -jar Infolog.jar server

Will run the server and start it right away.

java -jar Infolog.jar server gui

Will run the server and provide a rudimentary gui for starting and stopping the server.

The server program should be run in the background as a system service. Every operating system has its own way of handling services, therefore no generic description can be provided here. When using a Linux server you can use a script provided by Christian d'Heureuse on http://www.source-code.biz/snippets/java/7.htm

3. Infolog over SSH

When the program is used over a non-secure connection, communication between the clients and the server could be secured through SSH tunneling. Though the password is md5 hashed before send to the server, all communication between the client and the server is in plain text. Many people do not consider this a security thread because they exchange all sorts of private data through unsecured e-mail etc. If you however want to keep the information in your sticky notes absolutely secret you should consider the usage of a SSH tunnel. The program itself does not provide any further form of security enhancements and this is outside the scope of the project.

To communicate with the server the client uses a technique called java RMI. To use RMI over SSH please consult the very decent explanation of this topic given by Pankaj Kumar:
http://www.javaranch.com/journal/2003/10/rmi-ssh_p1.html
http://www.javaranch.com/journal/2003/11/rmi-ssh_p2.html

Here follows a brief instruction how to setup RMI over SSH:

SSH Deamon

On the same machine as the server program runs, start a SSH deamon. The user of the client program should be able to connect to this server through SSH, so a valid user account is needed. This can be the same user account for all clients with very limited access (i.e. only access to the Infolog server process).

Infolog Server

Start the server program with an extra commandline attribute to set the rmi hostname:

java -Djava.rmi.server.hostname=127.0.0.1 -jar Infolog.jar server

java -Djava.rmi.server.hostname=127.0.0.1 -jar Infolog.jar server gui

Infolog Client

A SSH tunnel should be set up on the client computer through a SSH client. On Linux this can be done by logging in on the server with the following command:

ssh -N -L1099:<SERVER HOSTNAME OR IP>:1099 -L1100:<SERVER HOSTNAME OR IP>:1100 -l <USERNAME> <SERVER HOSTNAME OR IP>

On windows systems, putty can be used to setup a SSH tunnel.

Start the client as described earlier, but with providing localhost or 127.0.0.1 as the Infolog server. This can be done in the infolog.properties file or through the client gui.

Key Exchange

The method described thusfar will require the user to login and establish a connection with forwarded ports every time the user wants to use the Infolog client. This is not convenient for a program that is supposed to run in the background and log in automatically. Therefore it is needed to exchange keys between the client and the server. The procedure for this is described hundreds of times on the internet, so plenty of tutorials are available. The procedure basically consists of the following steps:

Generate a key through ssh-keygen without a passphrase:
```
ssh-keygen -t rsa
```
(use defaults)

Copy your public key to the server:

ssh <SERVER HOSTNAME OR IP> "mkdir .ssh; chmod 0700 .ssh"

scp .ssh/id_rsa.pub <SERVER HOSTNAME OR IP>:.ssh/authorized_keys2

or append your public key to the file "authorized_keys2"

Add your identity to the identity agent:
```
ssh-add
```

You should now be able to login on the server through SSH and setup the port forwarding without providing a password. To run the program at startup I use two simple bash scripts:

infologTunnel.sh

#!/bin/bash
sudo -u <USER> ssh -N -L1099:<SERVER>:1099 -L1100:<SERVER>:1100 -l <USER> <SERVER> &

This script runs at startup (I put it in /etc/rc.local) to establish the SSH tunnel.

infolog.sh

#!/bin/bash
sleep 25
cd <Infolog installation dir>
java -jar Infolog.jar client

This script runs when I login on Gnome to start the Infolog Desktop Client (the sleep command is there to be sure Gnome has started the systemtray).

Infolog configuration and installation guide

Introduction

Contents:

infolog.properties

log4j.xml

icons

infolog.properties

hibernate.cfg.xml

log4j.xml

infologTunnel.sh

infolog.sh