[[PageOutline]] 

= QCG-Notification Installation =

QCG-Notification requires the [[http://apps.man.poznan.pl/trac/qcg-core/wiki/WikiStart|QCG-Core]] library to be installed (generally it is enough to use the QCG-Core library compilled and installed in a default fashion, but in specific scenarios, additional parameters to the QCG-Core's `./configure` script may be needed). If this prerequisite is fulfilled the QCG-Notification may be installed from [http://grass1.man.poznan.pl/qcg-sources/qcg-ntf sources] in a few simple steps:
{{{
#!div style="font-size: 90%"
{{{#!sh
tar xf qcg-ntf-*.*.*.tar
cd qcg-ntf-*.*.*
./configure --prefix=/opt/qcg --with-qcg-core=/opt/qcg
make
sudo make install
}}}
}}}

In order to verify later the installation, it is recommended to provide an additional option to `./configure`: `--with-consumer`
= Configuration =
Before you start you need to create a new system user (e.g. `qcg-ntf`) that will be used to start the service:
{{{
#!div style="font-size: 90%"
{{{#!sh
useradd -d  /opt/qcg/var/log/qcg-ntf/ -M  qcg-ntf
}}}
}}}
Give the `qcg-ntf` user ownership of the log directory:
{{{
#!div style="font-size: 90%"
{{{#!sh
chown qcg-ntf /opt/qcg/var/log/qcg-ntf/
}}}
}}}

== Service configuration ==
Minimal configuration requires only disabling the database and setting apropriately the host and port parameters in the main service configuration file: `PREFIX/etc/qcg-ntfd.xml`. 

Although it is optional, the database may be configured to realize more advanced notification scenarios as well as support recovery of the notification objects (such as subscriptions) after the service restart.
=== Database configuration ===
The easiest way to setup QCG-Notification database is use of provided script located in `PREFIX/share/qcg-ntf/tools/` direcotory:
{{{
#!div style="font-size: 90%"
{{{#!sh
/opt/qcg/share/qcg-ntf/tools/qcg-ntf-install.sh
Welcome to qcg-ntf installation script!

This script will guide you through process of configuring proper environment
for running the QCG-Notification service. You have to answer few questions regarding
parameters of your database. If you are not sure just press Enter and use the
default values.
  
Use local PostgreSQL server? (y/n) [y]: y
Database [qcg-ntf]: 
User [qcg-ntf]: 
Password [qcg-ntf]: MojeTajneHaslo
Create database? (y/n) [y]: y
Create user? (y/n) [y]: y
  
Checking for system user qcg-ntf...OK
Checking whether PostgreSQL server is installed...OK
Checking whether PostgreSQL server is running...OK
  
Performing installation
* Creating user qcg-ntf...OK
* Creating database qcg-ntf...OK
* Creating database schema...OK
* Checking for ODBC data source qcg-ntf...
* Installing ODBC data source...OK
    
Remember to add appropriate entry to /var/lib/pgsql/data/pg_hba.conf (as the first rule!) to allow user qcg-ntf to
access database qcg-ntf. For instance:
  
host    qcg-ntf       qcg-ntf       127.0.0.1/32    md5
  
and reload Postgres server.
}}}
}}}

== Further reading ==
For more information about configuration of the service please take a look at the [[/wiki/technicalGuideAndManual#configuration|QCG-Notification technical guide and manual]]. 

= Starting the service =
As the `qcg-ntf` user  type:
{{{
#!div style="font-size: 90%"
{{{#!sh
/opt/qcg/sbin/qcg-ntfd
}}}
}}}
or if you want the service not to daemonize and print all logs to console type:
{{{
#!div style="font-size: 90%"
{{{#!sh
/opt/qcg/sbin/qcg-ntfd -d
}}}
}}}
otherwise the logs can be found in `/opt/qcg/var/log/qcg-ntf/qcg-ntfd.log`.

= Stopping the service =
The service is stopped by sending `SIGTERM` signal, e.g.:
{{{
#!div style="font-size: 90%"
{{{#!sh
pkill qcg-ntfd
}}}
}}}

= Verifying the installation =
If the service was configured with the option `--with-consumer` attached to `./configure`, the basic verification scenario may be proceeded in a following way:

1. Set the `Host` and `Port` parameters in the configuration files of the QCG-Notification service and sample consumer, respectivetly in `/opt/qcg/etc/qcg-ntfd.xml` and `/opt/qcg/etc/qcg-ntf-consumer.xml`. For example, the key part of the `qcg-ntfd.xml` file may looks as foolows:
{{{
#!div style="font-size: 90%"
{{{#!xml
<sm:Module xsi:type="sm:ecm_gsoap.service">
    <sm:Host>127.0.0.1</sm:Host>
    <sm:Port>2211</sm:Port>
    ...
</sm:Module>
}}}
}}}
 Similarly, the part of `qcg-ntf-consumer.xml` may have a following form:
{{{
#!div style="font-size: 90%"
{{{#!xml
<sm:Module xsi:type="sm:ecm_gsoap.service">
    <sm:Host>127.0.0.1</sm:Host>
    <sm:Port>2212</sm:Port>
    ...
</sm:Module>
}}}
}}}

2. Start the `qcg-ntfd` in a debug mode:
{{{
#!div style="font-size: 90%"
{{{#!sh
/opt/qcg/sbin/qcg-ntfd -d
}}}
}}}

3. Start the `qcg-ntf-consumer` in a debug mode:  
{{{
#!div style="font-size: 90%"
{{{#!sh
/opt/qcg/sbin/qcg-ntf-consumer -d
}}}
}}}

4. Using the sample client program create a subscription in the QCG-Notification service:
{{{
#!div style="font-size: 90%"
{{{#!sh
./qcg-ntf-client -d -u http://127.0.0.1:2211 -S "cons=http://127.0.0.1:2212 top=http://schemas.qoscosgrid.org/comp/2011/04/notification/topic;//*;Full"
...
INF May 17 14:15:51 1128       0xa0262720 [qcg-client-gsoa] Subscribed, subRef: '810917963'
...
}}}
}}}
 '''Note:''' The created subscription assigns a service running on `http://127.0.0.1:2212` to be a consumer of notifications sent on topics from a namespace `http://schemas.qoscosgrid.org/comp/2011/04/notification/topic`. The subscription id is `810917963` 

5. Send a sample notification on a some topic from the namespace `http://schemas.qoscosgrid.org/comp/2011/04/notification/topic` to the QCG-Notification service:
{{{
#!div style="font-size: 90%"
{{{#!sh
./qcg-ntf-client -d -u http://127.0.0.1:2211 -N "top=http://schemas.qoscosgrid.org/comp/2011/04/notification/topic;ActivityState/Queued;Full msg=<SampleNotification/>"
...
INF May 17 14:19:32 1134       0xa0262720 [qcg-client-gsoa] Notification sent successfully
...
}}}
}}}

6. Check the output of `qcg-ntfd` and output of `qcg-ntf-consumer`. The outputs' scripts, in order, should be simillar to the following ones:
{{{
#!div style="font-size: 90%"
{{{#!default
...
INF May 17 14:19:32 1113       0xb0185000 [......ecm_gsoap] Serving Notify routine
INF May 17 14:19:32 1113       0xb0185000 [...............] Sending message to: 'http://localhost:2212'
INF May 17 14:19:32 1113       0xb0185000 [...............] Notification forwarded to '1' consumers
INF May 17 14:19:32 1113       0xb0185000 [...............] Forwarded Notification on topic: 'http://schemas.qoscosgrid.org/comp/2011/04/notification/topic/ActivityState/Queued'
...
}}}
 
{{{#!default
...
INF May 17 14:19:32 1120       0xb0491000 [qcg-consumer-gs] Receive notify message:
INF May 17 14:19:32 1120       0xb0491000 [qcg-consumer-gs] From:  127.0.0.1
INF May 17 14:19:32 1120       0xb0491000 [qcg-consumer-gs] Topic: <wsnt:Topic xmlns:tns="http://schemas.qoscosgrid.org/comp/2011/04/notification/topic" xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Full">tns:ActivityState/Queued</wsnt:Topic>
...
}}}
}}}

7. Finally remove the created subscription:
{{{
#!div style="font-size: 90%"
{{{#!default
./qcg-ntf-client -d -u http://localhost:2211 -U "id=810917963"
...
INF May 17 14:41:48 3318       0xa0262720 [qcg-client-gsoa] Unsubscribed: '810917963'
...
}}}
}}}

= Integration with QCG services and other interested parties =

QCG-Notification simplifyies cooperation of the two key !QosCosGrid services, i.e. QCG-Broker and QCG-Computing, as well as it offers notification capabilities to the external components. The integration of QCG-Notification with these entities is not problematic, however it meet some restrictions:
* QCG-Notification has to be able to initiate connections with QCG-Broker.
* QCG-Computing has to be able to initiate connections with QCG-Notification.
* QCG-Broker has to be able to initiate connections with QCG-Notification.
* If XMPP plugin is used, QCG-Notification should be able to connect to the XMPP server.
* If SMTP plugin is used, QCG-Notification should be able to connect to the SMTP server.
== QCG-Computing integration ==
After finishing the QCG-Notification configuration and having QCG-Computing service installed, you must edit the QCG-Computing service configuration file and update the content of the `<ServiceURL>` elements (in `<Module xsi:type="smc:notification_wsa">` section). For e.g. if in the  `PREFIX/etc/qcg-ntfd.xml` one can find  `<Host>example.com<Host>` and `<Port>19005<Port>` the `<ServiceURL>` in `PREFIX/etc/qcg-compd.xml` must be set to `http://example.com:19005/`. 

'''Note:''' You must restart the QCG-Computing service after updating the `qcg-compd.xml` configuration file.

When you start the QCG-Notification service and update the QCG-Computing configuration try to submit a simple job and check the QCG-Computing log file to see if there are now any error messages on sending notifications, e.g.:
{{{
#!div style="font-size: 90%"
{{{#!sh
tail -f /opt/qcg/var/log/qcg-comp/qcg-compd.log
INF Sep 17 16:15:01 24201 0x44b22940 [notification_ws] Sending notify message (topic = ActivityState/TerminalState/Finished, activity_id = 0544b24a-e960-400e-4910-f1a893632610, status = Finished)
}}}
}}}

== Configuring firewall ==
QCG-Notification requires only one TCP port to be open for incoming connections. By default it should be port 19001.
Note that the QCG-Notification service may publish notifications using various protocols and connect to many notification consumer services deployed on different machines and listening on different ports. Within the PL-Grid, the QCG-Notification sends notifications via HTTP/HTTPS to the QCG-Broker service listening on a predefined port as well as it may use XMPP and SMTP protocols to distribute XMPP and e-mail messages. These all remarks should be reflected in the firewall configuration.

== QCG-Notification installation using RPMS (in PL-Grid) ==
There are available RPM packages for installation QCG-Notification in PL-Grid. For detailed instructions follow this [[InstallingUsingRPMS|link]].