From 319458ca90e795fd8770c6da13375a7b84fc6c2d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ji=C5=99=C3=AD=20Filipovi=C4=8D?= Date: Wed, 14 Nov 2007 17:06:12 +0000 Subject: [PATCH] Added man pages. --- org.glite.lb.client/Makefile | 15 +- org.glite.lb.client/doc/glite-lb-dump.8 | 62 ++++++ org.glite.lb.client/doc/glite-lb-load.8 | 50 +++++ org.glite.lb.client/doc/glite-lb-logevent.1 | 28 +-- org.glite.lb.client/doc/glite-lb-purge.8 | 91 ++++++++ org.glite.lb.logger/Makefile | 17 +- org.glite.lb.logger/doc/glite-lb-interlogd.8 | 175 ++++++++++++++++ org.glite.lb.logger/doc/glite-lb-logd.8 | 162 +++++++++++++++ org.glite.lb.server/Makefile | 20 +- org.glite.lb.server/doc/glite-lb-bkindex.8 | 171 +++++++++++++++ org.glite.lb.server/doc/glite-lb-bkserverd.8 | 300 +++++++++++++++++++++++++++ 11 files changed, 1065 insertions(+), 26 deletions(-) create mode 100644 org.glite.lb.client/doc/glite-lb-dump.8 create mode 100644 org.glite.lb.client/doc/glite-lb-load.8 create mode 100644 org.glite.lb.client/doc/glite-lb-purge.8 create mode 100644 org.glite.lb.logger/doc/glite-lb-interlogd.8 create mode 100644 org.glite.lb.logger/doc/glite-lb-logd.8 create mode 100644 org.glite.lb.server/doc/glite-lb-bkindex.8 create mode 100644 org.glite.lb.server/doc/glite-lb-bkserverd.8 diff --git a/org.glite.lb.client/Makefile b/org.glite.lb.client/Makefile index ecf2649..d7729c0 100644 --- a/org.glite.lb.client/Makefile +++ b/org.glite.lb.client/Makefile @@ -150,7 +150,9 @@ EXAMPLES_PLUS= job_status_plus MAN_GZ:=glite-lb-logevent.1.gz +MAN8_GZ:=glite-lb-dump.8.gz glite-lb-load.8.gz glite-lb-purge.8.gz MAN = $(MAN_GZ:.gz=) +MAN8 = $(MAN8_GZ:.gz=) PLUS_EXTRA_LIB:=-lglite_wmsutils_jobid -lglite_wmsutils_exception @@ -238,6 +240,9 @@ ${MAN_GZ}: ${MAN} cp $? . gzip $(notdir $?) +${MAN8_GZ}: ${MAN8} + cp $? . + gzip $(notdir $?) perftest_logjobs.o: perftest_logjobs.c ${CC} ${CFLAGS} -DLB_PERF_DROP ${GLOBUSINC} -c $< @@ -268,9 +273,9 @@ default: all ifdef LB_STANDALONE -compile all: ${LIB} ${THRLIB} ${TOOLS} logevent examples ${MAN_GZ} +compile all: ${LIB} ${THRLIB} ${TOOLS} logevent examples ${MAN_GZ} ${MAN8_GZ} else -compile all: check_version ${LIB} ${THRLIB} ${TOOLS} logevent ${PLUSLIB} ${THRPLUSLIB} examples ${MAN_GZ} +compile all: check_version ${LIB} ${THRLIB} ${TOOLS} logevent ${PLUSLIB} ${THRPLUSLIB} examples ${MAN_GZ} ${MAN8_GZ} endif examples: ${EXAMPLES} ${EXAMPLES_CL} ${EXAMPLES_CL_THR} ${sh_PROGS} @@ -289,7 +294,7 @@ producer_test: producer_test.o prod_proto_test.o producer_test.o: %.o: %.cpp ${CXX} -c ${CXXFLAGS} ${TEST_INC} ${GLOBUSINC} $< -man: ${MAN_GZ} +man: ${MAN_GZ} ${MAN8_GZ} stage: compile ${FAKELIB} ${FAKETHRLIB} $(MAKE) install PREFIX=${stagedir} @@ -314,6 +319,7 @@ install: mkdir -p ${PREFIX}/lib mkdir -p ${PREFIX}/share/doc/${package}-${version} mkdir -p ${PREFIX}/share/man/man1 + mkdir -p ${PREFIX}/share/man/man8 ifdef LB_STANDALONE ${INSTALL} -m 644 ${LIB} ${THRLIB} ${PREFIX}/lib else @@ -333,10 +339,11 @@ endif done ${INSTALL} -m 755 ${top_srcdir}/src/export.sh "${PREFIX}/sbin/glite-lb-export.sh" ${INSTALL} -m 644 ${MAN_GZ} ${PREFIX}/share/man/man1 + ${INSTALL} -m 644 ${MAN8_GZ} ${PREFIX}/share/man/man8 clean: rm -rf *.o *.lo .libs lib* *.c *.cpp producer_test - rm -rf ${LIB} ${THRLIB} ${TOOLS} logevent ${PLUSLIB} ${THRPLUSLIB} ${MAN_GZ} + rm -rf ${LIB} ${THRLIB} ${TOOLS} logevent ${PLUSLIB} ${THRPLUSLIB} ${MAN_GZ} ${MAN8_GZ} rm -rf ${EXAMPLES} ${EXAMPLES_CL} ${EXAMPLES_CL_THR} ${sh_PROGS} diff --git a/org.glite.lb.client/doc/glite-lb-dump.8 b/org.glite.lb.client/doc/glite-lb-dump.8 new file mode 100644 index 0000000..a963698 --- /dev/null +++ b/org.glite.lb.client/doc/glite-lb-dump.8 @@ -0,0 +1,62 @@ +.TH EDG-WL-BKDUMP 8 "May 2003" "DataGrid Project" "Logging&Bookkeeping" + +.SH NAME +glite-lb-dump - utility for dumping job events from L&B database + +.SH SYNOPSIS +.B glite-lb-dump +.RI [ options ] +.br + +.SH DESCRIPTION +.B glite-lb-dump +is utility for dumping job events from L&B database. It is primarilly used for statistical purposes. By default, it dumps events from the time when the last dum ended upto now. + +.B glite-lb-dump +may be run periodically, however the periodic dumps are done by server itself, so check the configuration of the server first. + +.SH OPTIONS +.TP +.BI \-m \fR,\fP --server mkserver +L&B server machine name. If not specified, the environment variable EDG_WL_QUERY_SERVER is beeing checked. + +.TP +.BI \-f \fR,\fP --from YYYYMMDDHHmmss +Beginning of the time interval for events to be dumped. + +.TP +.BI \-t \fR,\fP --to YYYYMMDDHHmmss +End of the time interval for events to be dumped. + +.TP +.BI \-h \fR,\fP --help +Display help. + +.TP +.BI \-v \fR,\fP --version +Display version. + +.TP +.B "-d\fR,\fP --debug" +Print diagnostics on the +.I stderr\fR.\fP + +.\".SH USAGE +.\" Add any additional description here + +.PP + +.SH FILES +No configuration files needed. + +.SH ENVIRONMENT +No environment variables needed. + +.SH REPORTING BUGS +Please, report all bugs to DataGrid Bug Tracking System located at http://marianne.in2p3.fr/datagrid/bugzilla + +.SH SEE ALSO +.B glite-lb-bkindex\fR(8),\fP glite-lb-bkserverd\fR(8),\fP glite-lb-interlogd\fR(8),\fP glite-lb-logd\fR(8),\fP glite-lb-logevent\fR(1),\fP + +.SH AUTHOR +DataGrid Work Package 1, CESNET group. diff --git a/org.glite.lb.client/doc/glite-lb-load.8 b/org.glite.lb.client/doc/glite-lb-load.8 new file mode 100644 index 0000000..7b7bd62 --- /dev/null +++ b/org.glite.lb.client/doc/glite-lb-load.8 @@ -0,0 +1,50 @@ +.TH EDG-WL-BKLOAD 8 "May 2003" "DataGrid Project" "Logging&Bookkeeping" + +.SH NAME +glite-lb-load - utility for loading job events into the L&B database + +.SH SYNOPSIS +.B glite-lb-load +.RI [ options ] +.br + +.SH DESCRIPTION +.B glite-lb-load +is utility for loading job events into the L&B database. It is primarilly used for recovery purposes. By default, it loads events from the last dump. + +.SH OPTIONS +.IP "\-m, --server \fIbkserver\fR" +L&B server machine name. If not specified, the environment variable EDG_WL_QUERY_SERVER is beeing checked. + +.IP "\-f, --file \fIfilename\fR" +File with dumped data to be loaded. + +.IP "\-h, --help" +Display help. + +.IP "\-v, --version" +Display version. + +.IP "\-d, --debug" +Print diagnostics on the +.I stderr\fR.\fP + +.\".SH USAGE +.\" Add any additional description here + +.PP + +.SH FILES +No configuration files needed. + +.SH ENVIRONMENT +No environment variables needed. + +.SH REPORTING BUGS +Please, report all bugs to DataGrid Bug Tracking System located at http://marianne.in2p3.fr/datagrid/bugzilla + +.SH SEE ALSO +.B glite-lb-bkindex\fR(8),\fP glite-lb-bkserverd\fR(8),\fP glite-lb-dump\fR(8),\fP glite-lb-purge\fR(8),\fP + +.SH AUTHOR +DataGrid Work Package 1, CESNET group. diff --git a/org.glite.lb.client/doc/glite-lb-logevent.1 b/org.glite.lb.client/doc/glite-lb-logevent.1 index 4a79400..43394d0 100644 --- a/org.glite.lb.client/doc/glite-lb-logevent.1 +++ b/org.glite.lb.client/doc/glite-lb-logevent.1 @@ -1,10 +1,10 @@ -.TH GLITE-LB-LOGEV 1 "May 2003" "EU EGEE Project" "Logging&Bookkeeping" +.TH EDG-WL-LOGEV 1 "May 2003" "EU DataGrid Project" "Logging&Bookkeeping" .SH NAME -glite-lb-logev - program for logging events to L&B subsystem +glite-lb-logevent - program for logging events to L&B subsystem .SH SYNOPSIS -.B glite-lb-logev +.B glite-lb-logevent .B -s Application -e UserTag .B -j .I JOBID @@ -17,10 +17,10 @@ glite-lb-logev - program for logging events to L&B subsystem .br .SH DESCRIPTION -.B glite-lb-logev +.B glite-lb-logevent is a low-level program for logging events to the L&B service. -It is used internally by WMS components. -At the user level it is supposed to be used only for logging user tag events and changing job ACL's in L&B enventually. +It is used internally by WMS components and has many more options, that are not recomend to be used at the user level. +At the user level it is supposed to be used only for logging user tag events. .SH USAGE Besides @@ -37,18 +37,18 @@ The user application is always executed from within a .I JobWrapper script. The wrapper sets the appropriate JobId in the environment variable EDG_WL_JOBID. The user should pass this value to the -j option of -.B edg-wl-logev. +.B glite-lb-logevent. Similarly, the wrapper sets an initial value of the event sequence code in the environment variable EDG_WL_SEQUENCE_CODE. If the user application calls -.B edg-wl-logev +.B glite-lb-logevent just once, it is sufficient to pass this value to the -c option. However, if there are more subsequent calls, the user is responsible for capturing an updated sequence code from the .B stdout of -.B edg-wl-logev +.B glite-lb-logevent and using it in subsequent calls. The L&B design requires the sequence codes in order to be able to sort events correctly while not relying on strictly synchronized clocks. @@ -67,7 +67,7 @@ as a part of the job status returned by L&B. for p in `seq 1 100`; do # log the UserTag event - EDG_WL_SEQUENCE_CODE=`edg-wl-logev -s Application + EDG_WL_SEQUENCE_CODE=`glite-lb-logevent -s Application -e UserTag -j $EDG_WL_JOBID -c $EDG_WL_SEQUENCE_CODE --name=phase --value=$p` @@ -80,8 +80,8 @@ done .SH OTHER OPTIONS -See command line help (edg-wl-logev -h) for extensive help on all options. -However, GLITE users should follow the usage shown in SYNOPSIS strictly. +See command line help (glite-lb-logevent -h) for extensive help on all options. +However, EDG users should should follow the usage shown in SYNOPSIS strictly. Logging other events may confuse the L&B service and cause wrong job status information to be reported. @@ -89,10 +89,10 @@ information to be reported. No configuration files needed. .SH REPORTING BUGS -Please, report all bugs to EU EGEE Bug Tracking System located at https://savannah.cern.ch/bugs/?func=additem&group=jra1mdw +Please, report all bugs to EU DataGrid Bug Tracking System located at http://marianne.in2p3.fr/datagrid/bugzilla .SH SEE ALSO -.B edg-wl-bkserver\fR(8),\fP edg-wl-interlogd\fR(8),\fP edg-wl-logd\fR(8) +.B glite-lb-bkserverd\fR(8),\fP glite-lb-interlogd\fR(8),\fP glite-lb-logd\fR(8) L&B API Reference, DataGrid-01-TED-0139 diff --git a/org.glite.lb.client/doc/glite-lb-purge.8 b/org.glite.lb.client/doc/glite-lb-purge.8 new file mode 100644 index 0000000..7069af4 --- /dev/null +++ b/org.glite.lb.client/doc/glite-lb-purge.8 @@ -0,0 +1,91 @@ +.TH EDG-WL-BKPURGE 8 "May 2003" "DataGrid Project" "Logging&Bookkeeping" + + +.SH NAME +edg-wl-bkpurge - utility for removing inactive jobs from the L&B database + + +.SH SYNOPSIS +.B glite-lb-purge +.RI [ options ] +.br + + +.SH DESCRIPTION +.B glite-lb-purge +is utility for removing inactive jobs from the L&B database. By default, it removes jobs that reached CLEARED, ABORTED and CANCELLED state and also OTHER jobs that are in another state and are inactive for specific (rather long) time. It is a command line frontend to server internal purge. It is used by administrators of bkserver and it is not supposed to be used at the user level. + +.B glite-lb-purge +may be run periodically in order to avoid database overflow, however the periodic purges are done by server itself, so check the configuration of the server first. + + +.SH OPTIONS +.IP "-m, --server \fIbkserver\fR" +L&B server machine name. If not specified, the environment variable EDG_WL_QUERY_SERVER is beeing checked. + +.IP "-a, --aborted \fiNNN[smhd]\fR" +Purge ABORTED jobs older than NNN seconds/minutes/hours/days (only one number and one letter allowed). If the time is not specified, the default timeout is determined by the server. + +.IP "-c, --cleared \fiNNN[smhd]\fR" +Purge CLEARED jobs older than given time. + +.IP "-n, --cancelled \fiNNN[smhd]\fR" +Purge CANCELLED jobs older than given time. + +.IP "-o, --other \fiNNN[smhd]\fR" +Purge OTHER (i.e. job in other state than ABORTED, CLEARED or CANCELLED) jobs older than given time. + +.IP "-r, --dry-run" +Do not really purge. + +.IP "-j, --jobs \fIfilename\fR" +Input file with jobIds of jobs to purge. + +.IP "-l, --return-list" +Return list of jobid matching the purge/dump criteria. + +.IP "-s, --server-dump" +Dump jobs at the server into a file (see bkserverd). + +.IP "-i, --client-dump" +Receive stream of dumped jobs (NOT implemented yet!). + +.IP "-f, --dump-full" +Dump full database records of purged jobs. + +.IP "-h, --help" +Display help. + +.IP "-v, --version" +Display version. + +.IP "-d, --debug" +Print diagnostics on the \fIstderr\fR. + + +.\".SH EXAMPLES +.\"To appear :o( + + +.SH FILES +No configuration files needed. + + +.SH ENVIRONMENT +.TP +.B EDG_WL_QUERY_SERVER +If +.RB $ EDG_WL_QUERY_SERVER +is set, its value is used as the bkserver address. + + +.SH REPORTING BUGS +Please, report all bugs to DataGrid Bug Tracking System located at http://marianne.in2p3.fr/datagrid/bugzilla + + +.SH SEE ALSO +\fBedg-wl-bkindex\fP(8), \fBedg-wl-bkserver\fP(8), \fBedg-wl-interlogd\fP(8), \fBedg-wl-logd\fP(8), \fBedg-wl-logev\fP(1), \fBedg-wl-bkdump\fP(8), \fBedg-wl-bkload\fP(8) + + +.SH AUTHOR +DataGrid Work Package 1, CESNET group. diff --git a/org.glite.lb.logger/Makefile b/org.glite.lb.logger/Makefile index d94ccb1..efe5a05 100644 --- a/org.glite.lb.logger/Makefile +++ b/org.glite.lb.logger/Makefile @@ -20,7 +20,7 @@ version=${module.version} CC=gcc -VPATH:=${top_srcdir}/src:${top_srcdir}/test +VPATH:=${top_srcdir}/src:${top_srcdir}/test:${top_srcdir}/doc VERSION=-DVERSION=\"GLite-${version}\" @@ -113,9 +113,12 @@ INTERLOG_TEST_OBJS:= \ IlTestBase.o \ il_test.o +MAN_GZ:=glite-lb-interlogd.8.gz glite-lb-logd.8.gz +MAN = $(MAN_GZ:.gz=) + default: all -all compile: $(LOGD) $(INTERLOGD) $(NOTIF_INTERLOGD) +all compile: $(LOGD) $(INTERLOGD) $(NOTIF_INTERLOGD) ${MAN_GZ} glite-lb-logd: ${LOGD_OBJS} ${LINK} -o $@ ${LOGD_OBJS} ${COMMON_LIB}_${nothrflavour} @@ -145,6 +148,12 @@ glite-lb-interlogd-perf-empty: ${INTERLOG_EMPTY_OBJS} # ${LINK} -o $@ ${INTERLOG_INLINE_EMPTY_OBJS} \ # ${COMMON_LIB}_${thrflavour} +${MAN_GZ}: ${MAN} + cp $? . + gzip $(notdir $?) + +man: ${MAN_GZ} + stage: compile $(MAKE) install PREFIX=${stagedir} DOSTAGE=yes @@ -179,6 +188,7 @@ install: -mkdir -p ${PREFIX}/bin -mkdir -p ${PREFIX}/etc/init.d -mkdir -p ${PREFIX}/share/doc/${package}-${version} + -mkdir -p ${PREFIX}/share/man/man8 ${INSTALL} -m 755 ${LOGD} ${PREFIX}/bin ${INSTALL} -m 755 ${INTERLOGD} ${PREFIX}/bin if [ x${DOSTAGE} = xyes ]; then \ @@ -190,6 +200,7 @@ ifdef LB_PERF endif ${INSTALL} -m 755 ${top_srcdir}/config/startup ${PREFIX}/etc/init.d/glite-lb-locallogger ${INSTALL} -m 644 ${top_srcdir}/LICENSE ${PREFIX}/share/doc/${package}-${version} + ${INSTALL} -m 644 ${MAN_GZ} ${PREFIX}/share/man/man8 ${INTERLOG_NOBJS}: %.no: %.c ${CC} ${CFLAGS} ${GLOBUSTHRINC} -DIL_NOTIFICATIONS -c $< -o $@ @@ -222,4 +233,4 @@ il_test.o IlTestBase.o server_msgTest.o event_queueTest.o input_queue_socketTest ${CXX} ${CFLAGS} ${GLOBUSTHRINC} ${TEST_INC} -c $< -o $@ clean: - rm -rf .libs/ *.o *.no ${LOGD} ${INTERLOGD} ${NOTIF_INTERLOGD} + rm -rf .libs/ *.o *.no ${LOGD} ${INTERLOGD} ${NOTIF_INTERLOGD} {MAN_GZ} diff --git a/org.glite.lb.logger/doc/glite-lb-interlogd.8 b/org.glite.lb.logger/doc/glite-lb-interlogd.8 new file mode 100644 index 0000000..20732a0 --- /dev/null +++ b/org.glite.lb.logger/doc/glite-lb-interlogd.8 @@ -0,0 +1,175 @@ +.TH EDG-WL-INTERLOGD 8 "May 2003" "EU DataGrid Project" "Logging&Bookkeeping" + +.SH NAME +glite-lb-interlogd - interlogger daemon + +.SH SYNOPSIS +.B glite-lb-interlogd +.RI [ options ] +.br + +.SH DESCRIPTION +.B glite-lb-interlogd +takes over L&B events from glite-lb-logd and +it is responsible for reliable transfer to their target storage - +bookkeeping and logging servers. +Interlogger maintains message queues for each target server +and implements reliable handling in environment with possible communication +failures. + +On startup (and then periodically during operation) interlogger checks the +event files (created by glite-lb-logd, see also the -f option), +spawns a thread for each target server, and populates the queues +with events read from the files. +Then it starts listening for further incoming events on the UNIX socket +(see the -s option). + +The queue threads periodically attempt to contact the destination servers +and to deliver the pending events. + +Eventually, when all events from a file are delivered the file is removed +after a certain timeout by a clean-up thread. +Possible race conditions wrt. glite-lb-logd are prevented by +locking the files appropriately. + +.SH OPTIONS +.TP +.B "-b\fR,\fP --book +Send events only to bookkeeping server. This option has effect only if +the logging server address is specified through the -l option. There is no +implementation of logging server currently. + +.TP +.BI \-c " FILE" "\fR,\fP --cert " FILE +Get certificate from +.I FILE\fR.\fP +This option overrides the +.B \fR$\fPX509_USER_CERT +environment variable. + +.TP +.BI \-k " FILE" "\fR,\fP --key " FILE +Get server private key from +.I FILE\fR.\fP +This option overrides the +.B \fR$\fPX509_USER_KEY +environment variable. + +.TP +.BI \-C " DIR" "\fR,\fP --CAdir " DIR +Look for trusted CA's certificates in +.I DIR\fR.\fP +This option overrides the +.B \fR$\fPX509_CERT_DIR +environment variable. + +.TP +.B "-d\fR,\fP --debug" +Don't run as daemon (do not fork and put itself into background). + +.TP +.BI \-f " PREFIX" "\fR,\fP --file-prefix " PREFIX +.I PREFIX +is path prefix of the event files. + +For each job (jobid) a specific file is created that stores all events +associated with this job. +The job filename is constructed by stripping the +protocol+server prefix from the jobid and appending the rest to this +.I PREFIX. + +.I PREFIX +defaults to /tmp/dglogd.log. + +On startup, interlogger checks all files matching the pattern +.I PREFIX*. + +The value has to be same as used in the cooperating glite-lb-logd. + +.TP +.BI \-k " FILE" "\fR,\fP --key " FILE +Get private key from +.I FILE\fR.\fP +This option overrides the +.B \fR$\fPX509_USER_KEY +environment variable. + +.TP +.BI -l " HOST" "\fR,\fP --log-server " HOST +Use +.I HOST +as address of logging server. +As the logging is not implemented yet this option should not be used. + +.TP +.BI -s " PATH" "\fR,\fP --socket " PATH +Listen for events sent by glite-lb-logd at the UNIX socket +.I PATH. + +.TP +.B "-v\fR,\fP --verbose" +Print extensive debug output. + +.TP +.B "-V\fR,\fP --version" +Print version and exit. + +.TP +.BI -L " TIMEOUT" "\fR,\fP --lazy " TIMEOUT +Be lazy when closing connections to servers (default, +.I TIMEOUT\fR +==0 means turn lazy off). + +.\".SH USAGE +.\" Add any additional description here + +.PP + +.SH FILES +.TP +.I /tmp/interlogger.sock +Default name of local socket. +.TP +.I /tmp/dglogd.log* +Default location of event files. + +.I /tmp/dglogd.log*.ctl +Interlogger's control files keeping the information on status of +the corresponding event file wrt. delivery to the target server. + +.TP +No configuration files needed. + +.SH ENVIRONMENT +.TP +.B X509_USER_KEY +If +.B \fR$\fPX509_USER_KEY +is set, it is used to locate private key file. + +.TP +.B X509_USER_CERT +If +.B \fR$\fPX509_USER_CERT +is set, it is used to locate certificate file. + +.TP +.B X509_CERT_DIR +If +.B \fR$\fPX509_CERT_DIR +is set, it is used to locate the trusted CA's certificates and ca-signing-policy files. + +.TP +.B X509_USER_PROXY +If +.B \fR$\fPX509USER_PROXY +is set, it is used to locate proxy certificate file. + +.SH REPORTING BUGS +Please, report all bugs to EU DataGrid Bug Tracking System located at http://marianne.in2p3.fr/datagrid/bugzilla + +.SH SEE ALSO +.B te-lb-bkserverd\fR(8),\fP glite-lb-logd\fR(8),\fP glite-lb-logevent\fR(1),\fP + +.SH AUTHOR +EU DataGrid Work Package 1, CESNET group. diff --git a/org.glite.lb.logger/doc/glite-lb-logd.8 b/org.glite.lb.logger/doc/glite-lb-logd.8 new file mode 100644 index 0000000..c9bf108 --- /dev/null +++ b/org.glite.lb.logger/doc/glite-lb-logd.8 @@ -0,0 +1,162 @@ +.TH EDG-WL-LOGD 8 "May 2003" "EU DataGrid Project" "Logging&Bookkeeping" + +.SH NAME +glite-lb-logd - local logger daemon + +.SH SYNOPSIS +.B glite-lb-logd +.RI [ options ] +.br + +.SH DESCRIPTION +.B glite-lb-logd +accepts the L&B events from their sources (via the producer L&B API). +It is responsible for fast acceptance of the events and their reliable storage +in local files. + +Under normal conditions, the events are forwared to the +.B glite-lb-interlogd +immediately. +The file storage allows the interlogger crash recovery. + +.SH OPTIONS +.TP +.BI \-c " FILE" "\fR,\fP --cert " FILE +Get certificate from +.I FILE\fR.\fP +This option overrides the +.B \fR$\fPX509_USER_CERT +environment variable. + +.TP +.BI \-C " DIR" "\fR,\fP --CAdir " DIR +Look for trusted CA's certificates in +.I DIR\fR.\fP +This option overrides the +.B \fR$\fPX509_CERT_DIR +environment variable. + +.TP +.B "-d\fR,\fP --debug" +Don't run as daemon, print additional diagnostics. + +.TP +.B "-v\fR,\fP --verbose" +Print extensive debug output. + +.TP +.BI \-p " NUM" "\fR,\fP --port " NUM +Listen on the port +.I NUM\fR.\fP + +.TP +.BI \-f " PREFIX" "\fR,\fP --file-prefix " PREFIX +.I PREFIX +is a path prefix of the event files. + +For each job (jobid) a specific file is created that stores all events +associated with this job. +The job filename is constructed by stripping the +protocol+server prefix from the jobid and appending the rest to this +.I PREFIX. + +.I PREFIX +defaults to /tmp/dglogd.log. + +The value has to be same as used in the cooperating glite-lb-logd. + +.TP +.BI \-k " FILE" "\fR,\fP --key " FILE +Get private key from +.I FILE\fR.\fP +This option overrides the +.B \fR$\fPX509_USER_KEY +environment variable. + + +.TP +.BI -s " PATH" "\fR,\fP --socket " PATH +Send the messages to interlogger through the UNIX socket +.I PATH\fR.\fP + +The value has to be same as used in the cooperating glite-lb-interlogd. + +.TP +.B "-V\fR,\fP --version" +Print version and exit. + +.TP +.B --noAuth +Don't require valid X509 credentials to run the daemon. +Used for debugging only. + +.TP +.B --noIPC +Don't send messages to interlogger. + +.TP +.B --noParse +Don't parse messages for correctness. +Dangerous, for debugging only! Don't use at all. + + +.\".SH USAGE +.\" Add any additional description here + +.PP + +.SH FILES +.TP +.I /tmp/interlogger.sock +Default name of local socket. + +.TP +.I /tmp/dglogd.log* +Default location of the event storage files. +.TP +No configuration files needed. + +.SH ENVIRONMENT +.TP +.B X509_USER_KEY +If +.B \fR$\fPX509_USER_KEY +is set, it is used to locate private key file. + +.TP +.B X509_USER_CERT +If +.B \fR$\fPX509_USER_CERT +is set, it is used to locate certificate file. + +.TP +.B X509_CERT_DIR +If +.B \fR$\fPX509_CERT_DIR +is set, it is used to locate the trusted CA's certificates and ca-signing-policy files. + +.TP +.B X509_USER_PROXY +If +.B \fR$\fPX509USER_PROXY +is set, it is used to locate proxy certificate file. + + +.SH SIGNALS +.TP +.B USR1 +Increase verbosity of the program. + +.TP +.B USR2 +Decrease verbosity of the program. + + +.SH REPORTING BUGS +Please, report all bugs to DataGrid Bug Tracking System located at http://marianne.in2p3.fr/datagrid/bugzilla + +.SH SEE ALSO +.B glite-lb-bkserverd\fR(8),\fP glite-lb-interlogd\fR(8),\fP glite-lb-logevent\fR(1),\fP + +.SH AUTHOR +EU DataGrid Work Package 1, CESNET group. diff --git a/org.glite.lb.server/Makefile b/org.glite.lb.server/Makefile index 4b468dc..ee716a6 100644 --- a/org.glite.lb.server/Makefile +++ b/org.glite.lb.server/Makefile @@ -62,9 +62,9 @@ YACC=bison -y CC=gcc ifeq ($(gsoap_version),2.7.0) - VPATH=${top_srcdir}/interface:${top_srcdir}/src:${top_srcdir}/test:${top_srcdir}/examples:${top_srcdir}/project:${gsoap_prefix} + VPATH=${top_srcdir}/interface:${top_srcdir}/src:${top_srcdir}/test:${top_srcdir}/examples:${top_srcdir}/project:${top_srcdir}/doc:${gsoap_prefix} else - VPATH=${top_srcdir}/interface:${top_srcdir}/src:${top_srcdir}/test:${top_srcdir}/examples:${top_srcdir}/project + VPATH=${top_srcdir}/interface:${top_srcdir}/src:${top_srcdir}/test:${top_srcdir}/examples:${top_srcdir}/project:${top_srcdir}/doc endif AT3=perl -I${top_srcdir}/project ${top_srcdir}/project/at3 @@ -240,6 +240,9 @@ LIB_OBJS_BK:= \ stored_master.o srv_purge.o server_state.o dump.o lb_authz.o load.o \ notification.o il_notification.o notif_match.o stats.o +MAN_GZ:= glite-lb-bkindex.8.gz glite-lb-bkserverd.8.gz +MAN = $(MAN_GZ:.gz=) + glite-lb-bkserverd: ${NSMAP} ${BKSERVER_OBJS} ${LINKXX} -o $@ ${BKSERVER_OBJS} ${BKSERVER_LIBS} @@ -261,7 +264,11 @@ else endif endif -compile: glite-lb-bkserverd glite-lb-bkindex ${STATIC_LIB_BK} ${PLUGIN_LIB} store.c index.c jp_job_attrs.h +${MAN_GZ}: ${MAN} + cp $? . + gzip $(notdir $?) + +compile: glite-lb-bkserverd glite-lb-bkindex ${STATIC_LIB_BK} ${PLUGIN_LIB} store.c index.c jp_job_attrs.h ${MAN_GZ} check: compile test.xml test.query @@ -344,6 +351,8 @@ jp_job_attrs.h: job-attrs.xsd jp_job_attrs.xsl doc: +man: ${MAN_GZ} + stage: compile $(MAKE) install PREFIX=${stagedir} DOSTAGE=yes @@ -365,6 +374,7 @@ install: -mkdir -p ${PREFIX}/share/doc/${package}-${version} -mkdir -p ${PREFIX}/lib -mkdir -p ${PREFIX}/include/${globalprefix}/${lbprefix} + mkdir -p ${PREFIX}/share/man/man8 ${INSTALL} -m 644 ${top_srcdir}/LICENSE ${PREFIX}/share/doc/${package}-${version} for p in bkserverd bkindex; do \ ${INSTALL} -m 755 "glite-lb-$$p" "${PREFIX}/bin/glite-lb-$$p"; \ @@ -386,9 +396,9 @@ install: ${INSTALL} -m 644 jp_job_attrs.h ${PREFIX}/include/${globalprefix}/${lbprefix} ; \ fi ${INSTALL} -m 644 ${top_srcdir}/interface/srv_perf.h ${PREFIX}/include/${globalprefix}/${lbprefix} - + ${INSTALL} -m 644 ${MAN_GZ} ${PREFIX}/share/man/man8 clean: - rm -rf *.c *.h *.ch *.xh *.xml *.nsmap *.o *.lo .libs glite-lb-* ${STATIC_LIB_BK} test* + rm -rf *.c *.h *.ch *.xh *.xml *.nsmap *.o *.lo .libs glite-lb-* ${STATIC_LIB_BK} test* ${MAN_GZ} %.c: %.c.T rm -f $@ diff --git a/org.glite.lb.server/doc/glite-lb-bkindex.8 b/org.glite.lb.server/doc/glite-lb-bkindex.8 new file mode 100644 index 0000000..d95a568 --- /dev/null +++ b/org.glite.lb.server/doc/glite-lb-bkindex.8 @@ -0,0 +1,171 @@ +.TH EDG-WL-BKINDEX 8 "May 2003" "EU DataGrid Project" "Logging&Bookkeeping" + +.SH NAME +glite-lb-bkindex - dump or rebuild bookkeeping server indices + +.SH SYNOPSIS +.B glite-lb-bkindex +.RB [\| -mrv\| ] +.RI [ FILE ] +.br +.B glite-lb-bkindex +.RB [\| -dmv\| ] + + +.SH DESCRIPTION +The bookkeeping server +.B glite-lb-bkserverd +uses database indices to support various types of user queries efficiently. +.B glite-lb-bkindex +is a tool for dumping and manipulating the indices. +Both single- and multiple-column indices are supported. + +Due to performance reasons (reindexing may take rather long time) +the default invocation performs only "dry run" - the input is checked and intended actions +reported but not really performed. +The option -r has to be specified to do the real work. + +.B glite-lb-bkindex +should not be run while there is a running +.B glite-lb-bkserverd +on top of the same database. + +.PP +By default the L&B server indexes data according to JobId only. Because +the querying capabilities of L&B release 2 were considerably extended, +the server refuses to process a query which would not utilize any index. +This prevent overloading the underlying database engine. Consequently, even a trivial query 'give me all my jobs' results in an error in the default setup because under certain conditions processing such query may require handling gigabytes of data. + +.PP +The server administrator can create and modify the set of indices and control the set of supported queries. The description of columns to be indexed is given to +.B glite-lb-bkindex +utility via +.I FILE +that follows this syntax (subset of ClassAd syntax): + +.PP +.IP +.I FILE +::= +.BI [\ JobIndices\ =\ {\ index-description\ \fR[\fP ,\ index-description\fR]*\fP +.B } ] +.br +.I index-description +::= +.I column-description \fR|\fP list-of-columns +.br +.I list-of-columns +::= +.BI {\ column-description\ \fR+\fP\ } +.br +.I column-description +::= +.BI [\ column-type ;\ column-name ;\ prefix-len\ \fR?\fP\ ] +.br +.I column-type +::= +.B type = """user""" \fR|\fP type = """system""" \fR|\fP type = """time""" +.br +.I column-name +::= +.B name = """\fIactual_column_name\fP""" +.br +.I prefix-len +::= +.BI prefixlen\ =\ integer + +.PP +The only top-level attribute +.B JobIndices +is a list (possibly empty) of index descriptions. Each index description is either a single column or a list of columns (where the order is important). The column is described by mandatory attributes +.B type +and +.B name\fR,\fP +and an optional attribute +.B prefixlen\fR.\fP +Possible values of type are +.B """system""" +(L&B internal attributes) +.B """time""" +("state entered" timestamps), and +.B """user""" +(user tags). +Currently supported system column names are +.I owner\fR,\fP destination \fRand\fP location\fR.\fP +and valid timestamps are the job states, i.e. +.I submitted, waiting, ready, scheduled, running, done, cleared, cancelled, aborted\fR. +Names of user tags are arbitrary as long as their length is less than 60 characters and they contain only ASCII printable characters excluding backtick (`). +The +.B prefixlen +value may be used to restrict indexing of columns, which may grow rather long, to a fixed size. This becomes necessary with compound indices as MySQL limits the total size of index to 250 bytes only. + +.PP +In the following example the index file contains two indices, the first +one on a single system attribute -- , the second one composed +from system attribute (job) and user tag called : + +.IP +[ +.br +\ \ JobIndices = { +.br +\ \ \ \ [ type = "system"; name = "owner" ], +.br +\ \ \ \ { +.br +\ \ \ \ \ \ [ type = "system"; name = "destination"; +.br +\ \ \ \ \ \ \ \ prefixlen = 100 ], +.br +\ \ \ \ \ \ [ type = "user"; name = "experiment number"; +.br +\ \ \ \ \ \ \ \ prefixlen = 100 ] +.br +\ \ \ \ } +.br +\ \ } +.br +] + +.SH OPTIONS +.TP +.B "-d\fR,\fP --dump" +Print current setup on +.I stdout\fR.\fP + +.TP +.BI \-m " STRING" "\fR,\fP --mysql " STRING +.I STRING +is the database connect string in the form + +USER_NAME/PASSWORD@DB_HOSTNAME:DB_NAME + +It defaults to lbserver/@localhost:lbserver20 (common with +.B glite-lb-bkserverd\fR). + +.TP +.B "-r, --really" +Really perform reindexing. + +.TP +.B "-R, --remove" +Remove all indexes from server. + +.TP +.B "-v, --verbose" +Increase verbosity. + + +.\".SH USAGE +.\" Add any additional description here + +.PP + +.SH REPORTING BUGS +Please, report all bugs to EU DataGrid Bug Tracking System located at http://marianne.in2p3.fr/datagrid/bugzilla + +.SH SEE ALSO +.B glite-lb-purge\fR(8),\fP glite-lb-bkserverd\fR(8) + +.SH AUTHOR +EU DataGrid Work Package 1, CESNET group. diff --git a/org.glite.lb.server/doc/glite-lb-bkserverd.8 b/org.glite.lb.server/doc/glite-lb-bkserverd.8 new file mode 100644 index 0000000..d326ac3 --- /dev/null +++ b/org.glite.lb.server/doc/glite-lb-bkserverd.8 @@ -0,0 +1,300 @@ +.TH EDG-WL-BKSERVERD 8 "May 2003" "EU DataGrid Project" "Logging&Bookkeeping" + +.SH NAME +glite-lb-bkserverd - bookkeeping server daemon + +.SH SYNOPSIS +.B glite-lb-bkserverd +.RI [ options ] +.br + +.SH DESCRIPTION +.B glite-lb-bkserverd +accepts L&B events from interlogger, manages the data storage, +and serves user queries (L&B consumer clients). + +Currently, the data are stored in MySQL database. + +.PP +The main process spawns several +.I slave +processes. Then it listens on +.I port +(default value is 9000) for consumer queries and +.I port+1 +for interlogger daemon requests to store events to database. +Requests are redirected to the slaves +(and picked up by the first free slave process). +All the connection handling and data processing (including SSL handshake) +is performed by the slaves. + +The slaves voluntarily die and are resurrected periodically to workaround +potential resource leakage. + + +.SH OPTIONS +.TP +.BI \-a " HOST:PORT" "\fR,\fP --address " HOST:PORT +Make the server pretend (wrt. data handling) it listens on +.I HOST:PORT +instead of the real listening address. +This is used for debugging and various administrative purposes +(e.g. computing usage statistics on data dumped from another server). + +.TP +.BI \-c " FILE" "\fR,\fP --cert " FILE +Get certificate from +.I FILE\fR.\fP +This option overrides the +.B \fR$\fPX509_USER_CERT +environment variable. + +.TP +.BI \-b " SWITCH" "\fR,\fP --transactions " SWITCH +Set transaction on/off. +.I SWITCH +is true where its value is not 0. + +.TP +.BI \-C " DIR" "\fR,\fP --CAdir " DIR +Trusted CA's certificates directory. +.I DIR\fR.\fP +This option overrides the +.B \fR$\fPX509_CERT_DIR +environment variable. + +.TP +.BI \-V " DIR" "\fR,\fP --VOMSdir " DIR +Trusted VOMS server's certificates directory. +.I DIR\fR.\fP +This option overrides the +.B \fR$\fPX509_VOMS_DIR +environment variable. + +.TP +.B "-d\fR,\fP --debug" +Don't run as daemon, print additional diagnostics. + +.TP +.B "-r\fR,\fP --rgmaexport" +Write state info to RGMA interface. + +.TP +.BI \-i " FILE" "\fR,\fP --pidfile " FILE +Store master pid into +.I FILE +instead of the default pidfile location. +Unless unavoidable it is not recommended to change the pidfile location +as it is also used for locking to prevent starting up multiple server instances +and to generate the semaphore set unique key (see option -l). + + +.TP +.BI \-k " FILE" "\fR,\fP --key " FILE +Get private key from +.I FILE\fR.\fP +This option overrides the +.B \fR$\fPX509_USER_KEY +environment variable. + +.TP +.BI -l " NUM" "\fR,\fP --semaphores " NUM +Use +.I NUM +semaphores (job locks). + +To prevent race conditions on simultaneous event storage and job-state updates +.B glite-lb-bkserverd +uses a set of semaphores to lock jobs. +Jobids are hashed to the semaphores and only one of the set of jobs that map +to a particular semaphore may be updated at any given time. +Therefore +.I NUM +is a limit on potential processing parallelism. + +.I NUM +defaults to the number of slaves (see -s). + + +.TP +.BI -L " NUM:NUM:NUM" "\fR,\fP --limits " NUM:NUM:NUM +Limit the maximum number of returned jobs/events that match user query to +.I NUM:NUM:NUM\fP in format events_limit:jobs_limit:size_limit.\ + +.TP +.BI -N " NUM" "\fR,\fP --notif-dur " NUM +Maximal duration of notification registrations in hours +.I NUM\fR.\fP + +.TP +.BI -S " PREFIX" "\fR,\fP --purge-prefix " PREFIX +Purge files full-path prefix +.I PREFIX\fR.\fP + +.TP +.BI -D " PREFIX" "\fR,\fP --dump-prefix " PREFIX +Dump files full-path prefix +.I PREFIX\fR.\fP + +.TP +.BI -J " DIR" "\fR,\fP --jpreg-dir " DIR +JP registration temporary files prefix (implies '-j'). +.I DIR\fR.\fP + +.TP +.BI "-j \fR,\fP --enable-jpreg-export" +Enable JP registration export (disabled by default). + +.TP +.BI \-m " STRING" "\fR,\fP --mysql " STRING +.I STRING +is a database connect string in the form + +USER_NAME/PASSWORD@DB_HOSTNAME:DB_NAME + +It defaults to lbserver/@localhost:lbserver20. + +.TP +.B "-n, --noauth" +Turn off any authorization. + +.TP +.BI \-p " NUM" "\fR,\fP --port " NUM +Listen on the port +.I NUM\fR.\fP + +.TP +.BI \-w " NUM" "\fR,\fP --wsport " NUM +Set port to serve the web services requests to +.I NUM\fR. + +.TP +.B "-r\fR,\fP --rgmaexport" +Write state info into the RGMA interface. Experimental. + +.TP +.BI -s " NUM" "\fR,\fP --slaves " NUM +Fork +.I NUM +slaves. + +.TP +.BI --super-user " USER" "\fR,\fP --super-user-file " FILE +Bypass query authorization (i.e. return results anyway) when +USER (or users listed in FILE) connect. + +.TP +.BI --no-index " NUM" +Disable checking the indices for superusers (NUM=1) or entirely (NUM=2). + +.TP +.BI --strict-locking +.I (not recommended). +Use a more strict locking strategy -- lock jobs sooner, when events +are stored, not just for status update. +This prevents a non-probable but still possible race +condition with parallel purge but may slow down processing on +heavy loaded servers. Anyway, the only consequence of the race condition +is a little garbage left in the database which is cleaned +form time to time anyway. + +.TP +.BI --notif-il-sock " SOCK +Socket +.I SOCK +to send notifications. + +.TP +.BI --notif-il-sock " PREFIX +File +.I PREFIX +for notifications. + +.TP +.BI --count-statistics " NUM +Count certain statistics on jobs for superusers (NUM=1) or for all (NUM=2). + +.TP +.BI -t " NUM" "\fR,\fP --request-timeout " NUM +Request timeout +.I NUM +for one client. + +.TP +.BI --silent +Do not print diagnostic, even if -d is on. + +.TP +.BI -g \fP --greyjobs +Allow delayed registration (grey jobs), implies --strict-locking. + + + +.\".SH USAGE +.\" Add any additional description here + +.PP + +.SH FILES +.TP +.I /var/run/edg-bkserverd.pid +if running as root (not recommended). + +.TP +.I $HOME/edg-bkserverd.pid +otherwise. + +.TP +File to store pid and to generate semaphores key. + +.TP +No configuration files needed. + +.SH ENVIRONMENT +.TP +.B X509_USER_KEY +If +.B \fR$\fPX509_USER_KEY +is set, it is used to locate private key file. + +.TP +.B X509_USER_CERT +If +.B \fR$\fPX509_USER_CERT +is set, it is used to locate certificate file. + +.TP +.B X509_CERT_DIR +If +.B \fR$\fPX509_CERT_DIR +is set, it is used to locate the trusted CA's certificates and ca-signing-policy files. + +.TP +.B X509_USER_PROXY +If +.B \fR$\fPX509USER_PROXY +is set, it is used to locate proxy certificate file. + +.TP +.B EDG_WL_RGMA_FILE +If +.B \fR$\fPEDG_WL_RGMA_FILE +is set, it is used as name of file for sharing data with RGMA services. + +.TP +.B EDG_WL_RGMA_SOCK +If +.B \fR$\fPEDG_WL_RGMA_SOCK +is set, it is used as name of socket for communication with RGMA. + +.SH BUGS +In a case of a sudden crash, alive slave processes may survive or some resources (IPC locks, open ports) may stay allocated. Please, deal with such problems via standard commands +.B kill\fR and\fP ipcrm\fR.\fP + +Please, report all bugs to EU DataGrid Bug Tracking System located at http://marianne.in2p3.fr/datagrid/bugzilla + +.SH SEE ALSO +.B glite-lb-bkindex\fR(8),\fP glite-lb-purge\fR(8),\fP glite-lb-interlogd\fR(8),\fP glite-lb-logd\fR(8),\fP glite-lb-logevent\fR(1),\fP + +.SH AUTHOR +EU DataGrid Work Package 1, CESNET group. -- 1.8.2.3