From 4d1a2fa96b3f1560255169465f63335c9063235d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Franti=C5=A1ek=20Dvo=C5=99=C3=A1k?= Date: Fri, 15 Jan 2010 00:34:37 +0000 Subject: [PATCH] Documentation for L&B harvester. --- org.glite.lb.harvester/Makefile | 18 +- org.glite.lb.harvester/doc/glite-lb-harvester.sgml | 466 +++++++++++++++++++++ org.glite.lb.harvester/src/harvester.c | 1 + 3 files changed, 479 insertions(+), 6 deletions(-) create mode 100644 org.glite.lb.harvester/doc/glite-lb-harvester.sgml diff --git a/org.glite.lb.harvester/Makefile b/org.glite.lb.harvester/Makefile index c41f15b..5fb9fa4 100644 --- a/org.glite.lb.harvester/Makefile +++ b/org.glite.lb.harvester/Makefile @@ -18,7 +18,7 @@ endif version:=${module.version} CC=gcc -VPATH=${top_srcdir}/src +VPATH=${top_srcdir}/src:${top_srcdir}/doc GLOBUS_CPPFLAGS:=-I${globus_prefix}/include/${thrflavour} CPPFLAGS:=-I${stagedir}/include -D_GNU_SOURCE -D_REENTRANT ${CPPFLAGS} @@ -46,24 +46,26 @@ INSTALL:=libtool --mode=install install default: all -compile all: harvester +compile all: harvester doc check: debug: harvester-dbg -doc: +doc: glite-lb-harvester.8 stage: compile $(MAKE) install PREFIX=${stagedir} install: compile - -mkdir -p ${PREFIX}/bin ${PREFIX}/share/doc/${package}-${version} + -mkdir -p ${PREFIX}/bin ${PREFIX}/share/doc/${package}-${version} ${PREFIX}/share/man/man8 ${INSTALL} -m 755 harvester ${PREFIX}/bin/glite-lb-harvester ${INSTALL} -m 444 ../doc/README ${PREFIX}/share/doc/${package}-${version} + ${INSTALL} -m 444 glite-lb-harvester.8 ${PREFIX}/share/man/man8 clean: - rm -rfv *.o *.lo .libs/ harvester harvester-dbg + rm -rfv *.o *.lo *.loT .libs/ manpage.links manpage.refs + rm -rvf harvester harvester-dbg glite-lb-harvester.* rm -rvf log.xml project/ rpmbuild/ RPMS/ tgz/ harvester: harvester.o @@ -78,4 +80,8 @@ harvester-dbg.o: harvester.c %.o: %.c ${COMPILE} -c $< -.PHONY: default all compike debug check doc stage install clean +%.8: %.sgml + docbook2man $< + mv $(@:.8=.1) $@ + +.PHONY: default all compile debug check doc stage install clean diff --git a/org.glite.lb.harvester/doc/glite-lb-harvester.sgml b/org.glite.lb.harvester/doc/glite-lb-harvester.sgml new file mode 100644 index 0000000..55f7330 --- /dev/null +++ b/org.glite.lb.harvester/doc/glite-lb-harvester.sgml @@ -0,0 +1,466 @@ + + + + + + glite-lb-harvester + 1 + EU EGEE Project + + + + glite-lb-harvester + daemon for processing L&B notifications + + + + + glite-lb-harvester + + + -h + --help + + + + -v + --version + + + + -d + --debug + LEVEL + + + -D + --daemon + + + + -i + --pidfile + PIDFILE + + + -s + --threads + N + + + -t + --ttl + TIME + + + -H + --history + TIME + + + -c + --config + + + + -m + --pg + USER/PWD@SERVER:DBNAME + + + -n + --notifs + FILE + + + -p + --port + PORT + + + -C + --cert + FILE + + + -K + --key + FILE + + + -o + --old + + + + -l + --cleanup + + + + -w + --wlcg + + + + --wlcg-binary + EXECUTABLE + + + --wlcg-topic + TOPIC + + + --wlcg-config + FILENAME + + + --wlcg-flush + + + + + + DESCRIPTION + +L&B Harvester gathers information about jobs from L&B servers using effective +L&B notification mechanism. It manages notifications and keeps them in +a persistent storage (file or database table) to reuse later on next launch. +It takes care about refreshing notifications and queries L&B servers back when +some notification on expires. + +The tool was initially written for Real Time Monitor (project at Imperial +College in London), later was extended with MSG publish messaging mechanism for WLCG. + + + + + Requirements + +It is required on L&B servers side: + + +lastUpdateTime index, see "Changing Index Configuration" section in L&B Admin Guide + + +L&B harvester identity (certification subject) in super users file + + + + + + + OPTIONS + + + + | + +Print short usage. + + + + + + + | + +Print harvester version identifier. + + + + + | + + Verbosity level: + + 0error only + 1warnings + 2info/progress + 3debug + 4insane + +8 (8,9,10,11,12)don't fork and no preventive restarts + + + + + + | + +Daemonize and detach from console. Error messages are directed to syslog. + + + + + | + +The file with process ID. Automatically removed on shutdown. + + + + + | + +Number of threads (slaves). Configured L&B servers are equally distributed between threads. + + + + + | + +Validity (time to live) of the notifications. Daemon regularly refreshes notification in advance as needed. + + + + + | + +Historic dive limit in seconds. <= means unlimited. + + When staring, the L&B harvester queries the L&B servers for existing jobs. It queries L&B server when notification expires too and can't be refreshed on time. This parameter is used for limit, how deep into history L&B harvester should go. + + Another usage of this parameter is for derivation of the maximal time of retries. When some L&B server is inaccessible or it is in error condition, harvester linearly increases retry time. The maximal retry time is half of this parameter. + + + + + | + + Config file name with list of L&B servers. When used together with database option (), this parameter has precedence before lb20 table. + + + + + | + +Database connection string in the USER/PWD@SERVER:DBNAME form. There are used following tables in database: + + + lb20 - the list of L&B servers is taken from this table. But when is specified option () too, the file has precedence before this table. + +There is kept a column monitored in too: if there is any inactive notification because of errors on given L&B server (one expired or it was unable to create a new one), the false value is set. After refreshing or creating the notification, the value is set back to true. + + + jobs - table for storing job states. Each record is updated for each incoming notification - when state of the job changes in L&B server. + + +Database schema can be found in source code of org.glite.lb.harvester: examples/test.sql + +Developer note: information about notifications are kept in a file. It is possible to compile a binary keeping states in the database. It is used in the test in examples source directory. + + + + + | + +File for internal usage in L&B harvester. There is kept persistent information about active notifications or errors on L&B servers. Default is /var/tmp/notifs.txt. + + + + + | + +Specifies the port for listening and requests L&B nodes to send notification messages only to this port. May be needed for networks behind NAT or behind firewalls. + + + + + | + +X509 certificate file. + + + + + | + +X509 key file. + + + + + | + +"silly" mode for L&B servers < 2.0. In this mode transfer of the notification is not optimized at all. On the other hand it will work with older L&B servers. + + + + + | + +Cleans up all active notifications and quits. + +Each notification automatically expires. But if you know, than notifications used in previous run of L&B harvester won;t be needed, it is recommended to clean up the notifications and spare the resources on L&B servers (queue with undelivered notification messages and matching rules). + + + + + | + +Enables delivery to MSG publish. Messages are sent by executing a binary with proper parameters. + + + + + + +Full path to msg-publish binary executable, which is called for sending messages. Default is /usr/bin/msg-publish. + + + + + + +Topic used in MSG publish messages. Default is org.wlcg.usage.jobStatus. + + + + + + +Config file used in MSG publish. Default is /etc/msg-publish/msg-publish.conf. + + + + + + +Messages are sent to MSG publish in batches by default. This option enforce sending the messages one by one on each notification from L&B server - for each job state change. + + + + + + + + ENVIRONMENT + + + + GLITE_LB_HARVESTER_NO_REMOVE + +0 or false instructs L&B harvester to not remove temporary files with sent messages for MSG publish. By default temporary files with successfully sent messages are removed. Files with failed messages are always preserved. + +Intended for debugging purposes. + + + + + + + EXAMPLES + + + MSG publish infrastructure + +Harvester will send notifications using msg-publish infrastructure. List of the L&B servers to harvest is specified in config file specified by option: + + + + glite-lb-harvester -c servers.txt -C certfile -K keyfile --wlcg + +With newer L&B servers >= 2.0. + + + + glite-lb-harvester -c servers.txt -C certfile -K keyfile --wlcg --old + +With older L&B servers < 2.0 (backward compatible but greedy notifications). + + + + + +Custom configuration examples for MSG publish: + + + $HOME/bin/msg-publish + + org.wlcg.usage.JobStatus2 + + $HOME/etc/msg-publish.conf.wlcg + + + + + + + Real Time Monitor + +Harvester will use postgres database. Table lb20 with L&B servers to harvest (read-only), table jobs for result job states (read/write): + + + + glite-lb-harvester -C certfile -K keyfile --pg rtm/@:rtm -p 9004 + +In this case the L&B harvester will connect to database rtm on localhost as user rtm. For incoming notification it will request and listen only on port 9004. + + + + + + + Other recommended options + +Use glite-lb-harvester --help for the whole summary. + +For example: + + + + +Daemonizing and using syslog. + + + + + + +Decreasing verbosity (2 for errors and warnings only). + + + + + + + + + EXIT + +In non-daemon mode CTRL-C can be used. + +Use the pidfile in daemon mode (pidfile will vanish after exit): + +kill `cat /var/run/glite-lb-harvester.pid` + +All notifications are preserved on LB servers, and will expire later. You can +purge them at once, if they won't be needed: + +glite-lb-harvester --cleanup + + + + + EXIT STATUS + + + 0 + Success. + + + 1 + Reloading, used only internally for preventive restarts. + + + 2 + Error occurred. Messages go on console (foreground run) or into syslog (daemon run), depending on verbosity. + + + + + + AUTHOR + gLite L&B product team, CESNET. + + + diff --git a/org.glite.lb.harvester/src/harvester.c b/org.glite.lb.harvester/src/harvester.c index c9267ab..171a247 100644 --- a/org.glite.lb.harvester/src/harvester.c +++ b/org.glite.lb.harvester/src/harvester.c @@ -2030,6 +2030,7 @@ void usage(const char *prog) { #endif " -n, --notifs file for persistent information about active\n" " notifications\n" + " -p, --port listen only on this port (default: use any)\n" " -C, --cert X509 certificate file\n" " -K, --key X509 key file\n" " -o, --old \"silly\" mode for old L&B 1.9 servers\n" -- 1.8.2.3