[[PageOutline]] 

= QCG-Notification installation using RPMS =
This document describes basic procedures needed to install QCG-Notification from RPM packages and concentrates on a deployment of the service as a part of the !QosCosGrid middleware installed on the PL-Grid resources. Within !QosCosGrid the QCG-Notification service is used for brokering notification messages about the job state changes. All instances of the QCG-Computing services acts as the information ''Producers'' while the QCG-Broker as the ''Consumer''. In most cases it is enough that only one instance of the QCG-Notification is deployed per Administrative Domain (i.e.: not necessary one per Cluster). You can install the QCG-Notification service on the same machine where the [[http://www.qoscosgrid.org/trac/qcg-computing|QCG-Computing service]] is installed. 

= Installation =
Similarly to the [[http://www.qoscosgrid.org/trac/qcg-computing/wiki/InstallingUsingRPMS|QCG-Computing service]] service, QCG-Notification may be installed using the Yum Package Manager from RPMs. Assuming that the QCG-Computing service has been installed and initially configured (thus the basic dependencies are satisfied), the procedure is as follows:

* ensure that the qcg-ntf user is present in a system, otherwise create it:
{{{
#!div style="font-size: 90%"
{{{#!sh
useradd -r -d /opt/plgrid/var/log/qcg-ntf/ qcg-ntf
}}}
}}}

* ensure that the qcg-dev group is present in a system, otherwise create it:
{{{
#!div style="font-size: 90%"
{{{#!sh
groupadd -r qcg-dev
}}}
}}}

* install PL-Grid (official) and QCG (testing) repositories, if you have not done this yet.:
{{{
#!div style="font-size: 90%"
{{{#!sh
#QosCosGrid testing repository
cat > /etc/yum.repos.d/qcg.repo << EOF
[qcg]
name=QosCosGrid YUM repository
baseurl=http://fury.man.poznan.pl/qcg-packages/sl/x86_64/
enabled=1
gpgcheck=0
EOF
  
#Official PL-Grid repository
rpm -Uvh http://software.plgrid.pl/packages/repos/plgrid-repos-2010-2.noarch.rpm
}}}
}}}

* install QCG-Notification using YUM Package Manager:
{{{
#!div style="font-size: 90%"
{{{#!sh
yum install qcg-ntf
}}}
}}}

* setup QCG-Notification database using provided script:
{{{
#!div style="font-size: 90%"
{{{#!sh
/opt/plgrid/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.
}}}
}}}
 

* Add a new rule to the pg_hba.conf as requested:
{{{
#!div style="font-size: 90%"
{{{#!sh
vim /var/lib/pgsql/data/pg_hba.conf 
/etc/init.d/postgresql reload
}}}
}}}

= Configuration =

== Basic configuration ==
The service should be ready to use "out-of-the-box", however basic configuration may be needed to setup ''Host'' and ''Port'' on which QCG-Notification should listen as well as parameters of database connection: ''DSN'', ''User'' and ''Password''. It can be done by editing the main QCG-Notification configuration file located in: `/opt/plgrid/qcg/etc/qcg-ntf/qcg-ntfd.xml`. A part of the configuration file with marked key parameters is presented below:
{{{
#!div style="font-size: 90%"
{{{#!xml
<sm:QCGCore 
   <Configuration>
   ....
              <sm:Module xsi:type="sm:ecm_gsoap.service">
                  <sm:Host>127.0.0.1</sm:Host>
                  <sm:Port>19001</sm:Port>
                  <sm:UseWsa>true</sm:UseWsa>
              </sm:Module>
   ....
              <smn:Database>
                  <smn:DatabaseEnabled>true</smn:DatabaseEnabled>
                  <smn:DSN>qcg-ntf</smn:DSN>
                  <smn:User>qcg-ntf</smn:User>
                  <smn:Password>qcg-ntf</smn:Password>
                  <smn:CleanAtStart>false</smn:CleanAtStart>
              </smn:Database>
   ....
   </Configuration>
</sm:QCGCore>
}}}
}}}

== Optional Configuration ==

=== XMPP Publisher module configuration ===
If needed, the module for publishing notifications via XMPP protocol may be enabled in the service. The relevant part of QCG-Notification configuration file must be uncommented and adjusted to the real situation. For instance, the integration with the PL-Grid XMPP server, assuming that the XMPP account equals 'someaccount' and password is 'somepass', requires the following settings:

{{{
#!div style="font-size: 90%"
{{{#!xml
<sm:Module xsi:type="smn:ntf-publisher-xmpp">
   <smn:JID>someaccount@plgrid.pl/qcg-ntf</smn:JID>
   <smn:Password>somepass</smn:Password>  
   <smn:Encryption>TLS</smn:Encryption>                   
   <smn:CertFingerprint>7B55E421B023D4358BD9CE29F091D91C</smn:CertFingerprint>   
</sm:Module>
}}}
}}}


=== SMTP Publisher module configuration ===
Sending notifications through e-mails may be enabled by configuring the SMTP publisher module. The XML fragment presented below is sufficient to distribute e-mails via the locally running SMTP server, eg. Postfix.
{{{
#!div style="font-size: 90%"
{{{#!xml
<sm:Module xsi:type="smn:ntf-publisher-smtp">
   <smn:ServerURL>smtp://localhost:25</smn:ServerURL>
</sm:Module>
}}}
}}}

== 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]]. 

= Running the service =
The QCG-Notification initialization script is automatically added to `init.d` directory and may be run as a standard system service:
{{{
#!div style="font-size: 90%"
{{{#!sh 
/etc/init.d/qcg-ntfd start
}}}
}}}

The service logs can be found in:
{{{
#!div style="font-size: 90%"
{{{#!sh
/opt/plgrid/var/log/qcg-ntf/qcg-ntfd.log
}}}
}}}

It could be then stopped with the following command:
{{{
#!div style="font-size: 90%"
{{{#!sh
/etc/init.d/qcg-ntfd stop
}}}
}}}
'''Note:''' `qcg-ntfd` will be started with the `qcg_ntf` user permissions.

= Integration with QCG services =

== QCG-Computing ==

After finishing the QCG-Notification configuration 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  `/opt/plgrid/qcg/etc/qcg-ntfd.xml` one can find  `<Host>example.com<Host>` and `<Port>19001<Port>` the `<ServiceURL>` must be set to `http://example.com:19001/`. 

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

== Configuring firewall ==
QCG-Notification requires only one TCP port to be open for incoming connections. By default it should be port 19001.
Note if the service will use XMPP or SMTP transport, it may be required to open firewall to connect to external servers: XMPP (default port is 5222) or SMTP (default port is 25 or 587).

Please have a look also at [[https://apps.man.poznan.pl/trac/qcg-computing/wiki/InstallingUsingRPMS#Firewallconfiguration|this section]].

== Verifying ==

After starting the QCG-Notification service and updating 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 /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)
}}}
}}}

= Maintenance =

== Log management ==
You may also wish to install logrotate configuration for QCG-Notification:
{{{
#!div style="font-size: 90%"
{{{#!sh
yum install qcg-ntf-logrotate
}}}
}}}

== Data analysys and management ==
The administrators may need to view or manage data used by QCG-Notification (e.g. verify subscriptions, remove old pullpoints). The easiest way to view the data is to connect to the QCG-Notification database and select values from the particullar relations. This operation is read-only so it may be proceeded also when the QCG-Notification service is running. The more difficult thing is to modify the content of the stored data. When the service is running the operations of this type should be invoked using the provided QCG-Notification client applications. When the service is switched off the persistent data stored by QCG-Notification still can be accessed (if needed also cleaned) using the direct connection to the database. 

{{{
#!div style="font-size: 90%"
{{{#!sh
psql -h localhost qcg-ntf qcg-ntf 
Password for user qcg-ntf: 
Welcome to psql 8.1.23, the PostgreSQL interactive terminal.
  
Type:  \copyright for distribution terms
     \h for help with SQL commands
     \? for help with psql commands
     \g or terminate with semicolon to execute query
     \q to quit

qcg-ntf=>
}}}
}}}