From e6d9858cb8f3c6763965c941d88692a622769663 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zden=C4=9Bk=20=C5=A0ustr?= <sustr4@cesnet.cz>
Date: Tue, 12 Apr 2011 13:20:54 +0000
Subject: [PATCH] - Basic documentation for notifications over messaging -
 Better reflect version differences - Update on changes in L&B 3.0

---
 org.glite.lb.doc/src/LBAG-Installation.tex | 43 +++++++++++++++++++++---------
 org.glite.lb.doc/src/LBUG-Introduction.tex | 35 ++++++++++++------------
 org.glite.lb.doc/src/components.tex        |  9 ++++---
 org.glite.lb.doc/src/notify.tex            | 16 ++++++++++-
 org.glite.lb.doc/src/versions.tex          |  2 +-
 5 files changed, 70 insertions(+), 35 deletions(-)

diff --git a/org.glite.lb.doc/src/LBAG-Installation.tex b/org.glite.lb.doc/src/LBAG-Installation.tex
index 6fd38ec..8cbdc14 100644
--- a/org.glite.lb.doc/src/LBAG-Installation.tex
+++ b/org.glite.lb.doc/src/LBAG-Installation.tex
@@ -29,7 +29,7 @@ In \LBver{1.x}, the list of all LB packages was the following:
 glite-lb-common & common files \\ 
 glite-lb-client & client library and CLI tools\\ 
 glite-lb-client-interface & client library interface (header files) \\ 
-%glite-lb-harvester & enhanced \LB notification client (since \LBver{1.10}) \\
+glite-lb-harvester & enhanced \LB notification client (since \LBver{1.10}) \\
 glite-lb-logger & local-logger and inter-logger \\ 
 glite-lb-proxy & proxy (restricted server used by WMS)\\ 
 glite-lb-server & server \\ 
@@ -49,6 +49,7 @@ glite-lb-client & client library and CLI tools\\
 glite-lb-client-java & Java implementation of the client (since \LBver{2.1})\\ 
 glite-lb-harvester & enhanced \LB notification client (since \LBver{2.1})\\
 glite-lb-logger & local-logger and inter-logger \\
+glite-lb-logger-msg & plugin for message delivery over ActiveMQ (since \LBver{3.0}) \\
 glite-lb-server & server, including merged proxy functionality \\
 glite-lb-state-machine & state machine and LB plugin for Job Provenance \\ 
 glite-lb-utils & auxiliary utilities \\
@@ -56,6 +57,7 @@ glite-lb-ws-interface & web service interface \\
 glite-lb-yaim & YAIM initialization scripts for \LB (since \LBver{2.1}) \\
 \end{tabularx}
 
+
 More detailed description together with the dependencies can be read directly from each package,
 for example by issuing the command 
 \begin{verbatim}
@@ -80,12 +82,13 @@ glite-jobid-api-c & gLite jobId C API library \\
 % pro beh LB neni triba
 % glite-jp-common & JP common files \\ 
 glite-lbjp-common-db & database access layer \\
+glite-lbjp-common-jp-interface & interface to the Job Provenance service\\
 glite-lbjp-common-log & glite common logging format implementation \\
 glite-lbjp-common-maildir & persistent request spool management \\
 glite-lbjp-common-server-bones & multi-process server building library \\
 glite-lbjp-common-trio & extended printf implementation \\
-glite-security-gss & GSS wrapper \\
-glite-security-gsoap-plugin & GSS plugin for gSoap \\
+glite-lbjp-common-gss & GSS wrapper (formerly \emph{glite-security-gss})\\
+glite-lbjp-common-gsoap-plugin & GSS plugin for gSoap (formerly \emph{glite-security-gsoap-plugin})\\
 \end{tabularx}
 
 where all \verb'glite-lbjp-common-*' packages are common both to \LB and 
@@ -101,7 +104,7 @@ The implementation is done in the \texttt{glite-lbjp-common-log} package and it
 uses \texttt{log4c} (\url{http://log4c.sourceforge.net})
 and its configuration file \texttt{log4crc}. 
 
-There is one configuration file \texttt{\$GLITE\_LOCATION/etc/glite-lb/log4crc}
+There is one configuration file \texttt{$[$/opt/glite$]$/etc/glite-lb/log4crc}
 that startup scripts use by setting the \texttt{LOG4C\_RCPATH} environment
 variable.
 
@@ -155,7 +158,7 @@ offered load.
 
 \subsubsection{Standard installation}
 
-Install and configure OS and basic services (certificates, CAs, time synchronization, software repositories) according to the \htmladdnormallink{https://twiki.cern.ch/twiki/bin/view/LCG/GenericInstallGuide320}{https://twiki.cern.ch/twiki/bin/view/LCG/GenericInstallGuide320}. Then glite-LB metapackage from appropriate gLite software repository should be installed.
+Install and configure OS and basic services (certificates, CAs, time synchronization, software repositories) according to the \htmladdnormallink{https://twiki.cern.ch/twiki/bin/view/LCG/GenericInstallGuide320}{https://twiki.cern.ch/twiki/bin/view/LCG/GenericInstallGuide320}. Then \texttt{glite-LB} metapackage from appropriate gLite software repository should be installed. When using the EMI or UMD repository, the correct metapackage to use is \texttt{emi-lb}.
 
 YAIM configuration for \emph{glite-LB} node type 
 (\texttt{/opt/glite/yaim/bin/yaim -c -s site-info.def -n glite-LB}) 
@@ -184,9 +187,9 @@ According to local retention policy you may want to use different purge timeouts
 
 Additional helper or legacy parameters for \LB:
 \begin{itemize}
-\item \texttt{GLITE\_LB\_LOCATION} -- \LB prefix (default: /opt/glite or /usr)
-\item \texttt{GLITE\_LB\_LOCATION\_ETC} -- system config directory (default: /opt/glite/etc or /etc)
-\item \texttt{GLITE\_LB\_LOCATION\_VAR} -- gLite local state directory (default: /opt/glite/var or /var/glite)
+\item \texttt{GLITE\_LB\_LOCATION} -- \LB prefix (default: \texttt{/opt/glite} or \texttt{/usr})
+\item \texttt{GLITE\_LB\_LOCATION\_ETC} -- system config directory (default: \texttt{/opt/glite/etc} or \texttt{/etc})
+\item \texttt{GLITE\_LB\_LOCATION\_VAR} -- gLite local state directory (default: \texttt{/opt/glite/var} or \texttt{/var/glite})
 \item \texttt{GLITE\_JP\_LOCATION} -- can be used when JP subsystem location differs from LB (default: empty)
 \item \texttt{GLITE\_LB\_HARVESTER\_ENABLED} -- set to \texttt{true} for sending notifications, used mainly for legacy export to MSG publish system (default: \texttt{false})
 \item \texttt{GLITE\_LB\_HARVESTER\_MSG\_OPTIONS} -- additional options for MSG publish (default: \texttt{--wlcg})
@@ -247,7 +250,7 @@ Steps:
   \begin{quote}
    \begin{verbatim}
 mysql -u lbserver lbserver20 \
-        </opt/glite/etc/glite-lb-dbsetup-migrate2transactions.sql
+        <[/opt/glite]/etc/glite-lb-dbsetup-migrate2transactions.sql
    \end{verbatim}
   \end{quote}
  \item \emph{Start the servers.} MySQL and \LB. Check logs.
@@ -282,7 +285,7 @@ Steps:
  \item \emph{Database conversion.} Use provided shell script (with the proper
   switch from previous step):
   \begin{quote}
-  \verb'/opt/glite/etc/glite-lb-migrate_db2version20 {-s|-p}'
+  \verb'[/opt/glite]/etc/glite-lb-migrate_db2version20 {-s|-p}'
   \end{quote}
  \item \emph{(Optional) Drop unnecesary index.} This operation is
   likely to take a lot of time when applied to large database.
@@ -306,6 +309,22 @@ There are no specific configuration changes required when migrating from \LBver{
 
 %\TODO{automated conversion through YAIM ?}
 
+\subsubsection{Connecting to the Messaging Infrastructure}
+\label{inst:messaging}
+
+As of \LBver{3.0}, the \LB server node becomes a producer of messages, which it delivers into the messaging infrastructure.
+
+Correct broker settings are infered from BDII by YAIM on configuration. By default, messaging-related settings are stored in file:
+
+  \begin{quote}
+	\begin{verbatim}
+[/opt/glite]/etc/glite-lb/msg.conf
+	\end{verbatim}
+  \end{quote}
+
+Alongside the broker address and port, \texttt{msg.conf} also specifies the messaging plugin to be used by the notification interlogger. Plugin settings should be correct \emph{ab initio} and do not require modification by administrators. Broker settings may require an adaptive change in case the currently configured broker disapears and automatic checks fail to switch the settings to another one on time.
+
+
 \subsubsection{Index configuration}
 
 Initial YAIM configuration creates \LB indexes typically,
@@ -342,7 +361,7 @@ rights that can be granted to the users:
 \item \verb'LOG_WMS_EVENTS'
 \item \verb'LOG_CE_EVENTS'
 \item \verb'LOG_GENERAL_EVENTS'
-\item \verb'GRANT_OWNERSHIP' (\LBver{3.0})
+\item \verb'GRANT_OWNERSHIP' (since \LBver{3.0})
 \end{itemize}
 
 The first action disables all authorization checks. The next four categories concern with acquring data from the \LB
@@ -560,7 +579,7 @@ the recommended workaround is to add the following variable setting
 
 \verb'GLITE_LB_SERVER_OTHER_OPTIONS="--mysql lbserver/@localhost:lbproxy"' 
 
-into the gLite startup environment (\verb'/opt/glite/etc/profile.d') instead.
+into the gLite startup environment (\verb'[/opt/glite]/etc/profile.d') instead.
 This setting makes \LB server use the \verb'lbproxy' database instead of the default.
 
 \subsection{\LB logger}
diff --git a/org.glite.lb.doc/src/LBUG-Introduction.tex b/org.glite.lb.doc/src/LBUG-Introduction.tex
index 36aa1f1..cd68a49 100644
--- a/org.glite.lb.doc/src/LBUG-Introduction.tex
+++ b/org.glite.lb.doc/src/LBUG-Introduction.tex
@@ -455,7 +455,8 @@ The user may even re-subscribe (providing the original handle) with different
 listener location (\eg moving from office to home), and \LB re-routes
 the notifications generated in the meantime to the new destination.
 The \LB event delivery infrastructure is reused for the notification
-transport.
+transport. Alongside it, there is a possibility to deliver notification
+messages thourgh the messaging infratstructure.
 
 \subsubsection{Local views}\label{local}
 % motivace proxy
@@ -699,30 +700,30 @@ Complete reference of the query language can be found in~\LB Developer's Guide
 \cite{lbdg}.
 
 \subsubsection{Notifications}
-The other mode of user interactions are the \LB notifications.
+\LB notifications are the other mode of user interaction.
 
-\LB infrastructure enables its users to be notified when something interesting happens on a \LB server
-(typically job status change). It enables the user not to poll \LB server periodically to find changed
-information, but confortably wait for server to inform the user.
+The \LB infrastructure can notify its users when something interesting happens on an \LB server
+(typically a job status change). This allows users to wait comfortably until they are informed by the server, rather than having to poll the \LB server periodically to detect changes.
 
-User registers for notifications via notification client \verb'glite-lb-notify', described in Section
+Users register for notifications via the notification client \verb'glite-lb-notify', described in Section
 \ref{s:lb-notify} 
-Conditions under which the notification is sent can be specified. For example - job XY reaches status
+Conditions under which the notifications are sent can be specified. For example -- job XY reaches status
 DONE. In \LBver{1.x}, one or more JOBID's are required in the condition and only a single occurence 
-of a specific attribute is allowed among ANDed conditions. In \LBver{2.x}, more complex conditions are allowed.
+of a specific attribute is allowed among ANDed conditions. More complex conditions are allowed since \LBver{2.0}
 
-The registration is then delivered to \LB server where it is stored.
-At the same time, server generates a unique notification ID for the registration and returns it to the
+The registration is then delivered to the \LB server where it is stored.
+At the same time, the server generates a unique notification ID for the registration and returns it to the
 user.
 
-The registration exists only for limited amount of time. The validity is returned by \LB server together with
-the notification ID when registering. During this period user can attach to server and receive notifications,
-change conditions which triger notification, prolong validity of the registration, or remove the registration
-from \LB server. 
+The registration exists only for a limited amount of time. Validity information is returned by \LB server together with
+the notification ID when registering. During this period the user can attach to the server and receive notification messages,
+change conditions which triger the notification, prolong validity of the registration, or remove the registration
+from the \LB server. 
+It is also possible to specify on registration that notification messages for a given registration are not supposed to be delivered through the notification client but through the messaging infrastructure instead. 
 
-While the registration is valid, user is able repeatably connect to \LB server from different places in the
-network and continue receiving notifications associated with given notification ID. Notifications generated
-during the time when user is connected are stored and waiting when user reconnects. 
+While the registration is valid, the user is able to repeatably connect to the \LB server from different places in the
+network and continue receiving notifications associated with the given notification ID. When relying on \LB's event delivery infrastructure to deliver messages, even notifications generated
+while the user was not connected are stored and waiting until the user reconnects. 
 
 \subsubsection{Caveats}
 \LB is designed to perform well in the unreliable distributed Grid
diff --git a/org.glite.lb.doc/src/components.tex b/org.glite.lb.doc/src/components.tex
index 620111f..94520bc 100644
--- a/org.glite.lb.doc/src/components.tex
+++ b/org.glite.lb.doc/src/components.tex
@@ -124,11 +124,12 @@ containing the job state data, notification handle,
 and the current user's listener location.
 The event is passed to the \emph{notification inter-logger} 
 via persistent disk file and directly (see Fig.~\ref{f:comp-query}).
-The daemon delivers events in the standard way, using the specified
-listener as destination.
-In addition, the server generates control messages when the user re-subscribes,
+The daemon delivers events either in a standard way, using the specified
+listener as destination, or forwards them to a messaging broker for delivery through the messaging infrastructure.
+When using the standard delivery mechanism,
+the server generates control messages when the user re-subscribes,
 changing the listener location.
-Inter-logger recognizes these messages, and changes its routing of all
+Inter-logger recognizes these messages, and changes the routing of all
 pending events belonging to this handle accordingly.
 
 
diff --git a/org.glite.lb.doc/src/notify.tex b/org.glite.lb.doc/src/notify.tex
index 1d6154f..ddd6d62 100644
--- a/org.glite.lb.doc/src/notify.tex
+++ b/org.glite.lb.doc/src/notify.tex
@@ -36,7 +36,7 @@ However, only a single active client for a notification is allowed.
 \LB server and port to contact must be specified with GLITE\_WMS\_NOTIF\_SERVER 
 environment variable.
 
-\verb'glite-lb-notify' is supported on in \LBver{2.x}. In \LBver{1.x}, \verb'glite-lb-notify' 
+\verb'glite-lb-notify' is supported by \LBver{2.x} and newer. In \LBver{1.x}, \verb'glite-lb-notify' 
 with very limited functionality can be found in \verb'examples' directory.
 
 \verb'glite-lb-notify' support these actions:
@@ -148,6 +148,7 @@ Destroy notification:
     https://skurut68-2.cesnet.cz:9100/NOTIF:tOsgB19Wz-M884anZufyUw
 \end{verbatim}
 
+
 \subsubsection{Example: Waiting for notifications on all user's jobs}
 
 Instead of waiting for one job, user may want to accept notification about 
@@ -207,6 +208,19 @@ returns:
 
 \end{verbatim}
 
+\subsubsection{Example: Registering for notifications to be delivered over ActiveMQ}
+\label{e:notifymsg}
+
+Delivering notification messages over the messaging infrastructure provided by ActiveMQ is a feature introduced in \LBver{3.0}. It uses the fake address capability (\texttt{-a} option) to specify messaging topic to use when generating messages.
+
+\begin{verbatim}
+  GLITE_WMS_NOTIF_SERVER=skurut68-2.cesnet.cz:9100 glite-lb-notify new \
+   -O -a x-msg://grid.emi.lbexample
+\end{verbatim}
+
+Rather than using the \LB notification API to receive messages, tap to the given messaging topic (\texttt{grid.emi.lbexample} in our case) in the messaging infrastructure.
+
+Note that production environments can impose restrictions on topic names. In the context of EGI, for instance, the ``\texttt{grid.emi.}'' prefix is mandatory.
 
 \subsubsection{Example: Waiting for more notifications on one socket}
 
diff --git a/org.glite.lb.doc/src/versions.tex b/org.glite.lb.doc/src/versions.tex
index 401930d..9cdbe84 100644
--- a/org.glite.lb.doc/src/versions.tex
+++ b/org.glite.lb.doc/src/versions.tex
@@ -58,7 +58,7 @@ The complete \LB Documentation consists of the following parts:
 
 \begin{itemize}
 \item \textbf{gLite releases}: gLite node-type repositories, offering a specific repository for each node type such as \emph{glite-LB}
-\item \textbf{emi releases}: EMI repository, offering all EMI middleware packages from a single repository and relying on the EPEL repository for dependencies
+\item \textbf{emi releases}: EMI repository or EGI's UMD repository, offering all EMI middleware packages from a single repository and relying on EPEL for dependencies
 \end{itemize}
 
 \emph{Note:} Despite offering the same functionality, binary packages obtained from different repositories differ and switching from one to the other for upgrades may not be altogether straightforward.
-- 
1.8.2.3