flom Code

115 lines (114 with data), 9.6 kB

.\" Manpage for flom.
.\" Contact tiian@users.sourceforge.net to correct errors or typos.
.TH man 1 "@_RELEASE_DATE@" "@PACKAGE_VERSION@" "flom man page"
.SH NAME
flom \- serialize command execution
.SH SYNOPSIS
.B "flom"
[\fIOPTION\fP] -- [\fICOMMAND\fP [\fIARG\fP]...]
.SH DESCRIPTION
Run COMMAND serializing it with other commands executed by flom.
.SH OPTIONS
.TP 4
.B "-h, --help"
show help options
.TP
.B -v, --version
print flom version and exit
.TP
.B -V, --verbose
verbose mode execution
.TP
.B -c, --config-file=\fIFILENAME
user configuration file name. Flom tries to read system default configuration file @sysconfdir@/@_SYSTEM_CONFIG_FILENAME@, user default configuration file ~/@_USER_CONFIG_FILENAME@ and finally this file if specified. Definitive configuration is obtained overloading hard wired build time defaults, system defaults, user defaults, user custom, command line options.
.TP
.B -r, --resource-name=\fIRESOURCE
name of the resource used for enqueing (locking). Resource name can be composed of "alpha" and "digit" characters, but the first character \fBmust be\fP of type "alpha" (example: "RA123" is \fBOK\fP, "123RA" is \fBnot\fP OK). Accepted resource names are described in function "global_res_name_preg_init": inspect source code for more details
.TP
.B -w, --resource-wait=\fIyes|no
\fBdefault\fP (\fIyes\fP): the command will enqueue if the resource is already locked by someone else, otherwise (\fIno\fP) it will return immediately
.TP
.B -o, --resource-timeout=\fImilliseconds
maximum enqueue time if the resource is already locked by someone else; if the resource doesn't become free before \fItimeout milliseconds\fP the command will return. Note: "\fI-o 0\fP" is equivalent to "\fI-w no\fP"
.TP
.B -l, --lock-mode=\fIMODE
lock mode as defined by VMS DLM (Distributed Lock Manager). \fIMODE\fP can be: "NullLock", "ConcurrentRead", "ConcurrentWrite", "ProtectedRead", "ProtectedWrite", "Exclusive" (equivalent short forms are: "NL", "CR", "CW", "PR", "PW", "EX"). More information are available here \fIhttp://en.wikipedia.org/wiki/Distributed_lock_manager#Lock_modes\fP
.TP
.B -s, --socket-name=\fIFILENAME
absolute \fIFILENAME\fP that must be used to create the UNIX socket used for local communication between \fBflom\fP command line and \fBflom daemon\fP; typical values are something like \fI/tmp/something\fP. This option is useful to share locks between different users (the default socket is per user and every user creates a different one)
.TP
.B -a, --unicast-address=\fIIPaddress
TCP/IP address that must be used to reach a running daemon; if the daemon must be started locally, \fIIPaddress\fP must be a valid IP address for this host
.TP
.B -p, --unicast-port=\fIIPport
TCP/IP port that must be used to reach a running daemon; if the daemon must be started locally, \fIIPport\fP must be a port not used by another process on this host. If \fIIPaddress\fP (see \fB-a\fP, \fB--unicast-address\fP) is specified and \fIIPport\fP is not specified, the default value is @_DEFAULT_DAEMON_PORT@
.TP
.B -A, --multicast-address=\fIIPaddress
UDP/IP multicast address that must be used to discover the location of a running daemon; if the daemon must be started locally, \fIIPaddress\fP must be a valid multicast IP address for this host. Multicast address ranges are: 224.0.0.1 - 224.0.0.255 (link-local), 239.255.0.0 - 239.255.255.255 (site-local), 239.192.0.0 - 239.195.255.255 (organization-local) and 224.0.1.0 - 238.255.255.255 (global); a typical choice is an address in \fIlink-local\fP or in \fIsite-local\fP range
.TP
.B -P, --multicast-port=\fIIPport
UDP/IP multicast port that must be used to discover the location of a running daemon; if the daemon must be started locally, \fIIPport\fP must be a port not used by another process on this host. If \fIIPaddress\fP (see \fB-A\fP, \fB--multicast-address\fP) is specified and \fIIPport\fP is not specified, the default value is @_DEFAULT_DAEMON_PORT@
.TP
.B -d, --daemon-lifespan=\fImilliseconds
lifespan of \fBflom\fP daemon if activated, expressed using milliseconds. The value of \fImilliseconds\fP can be and integer greater than 0, equal to 0 or less than 0: values greater than 0 are interpreted as minimum daemon lifetime (in milliseconds), the value 0 is interpreted as "don't start a daemon process" and values less than 0 are interpreted as "run forever" (or until a kill message is sent to \fBflom\fP daemon). If not specified, the default value is @_DEFAULT_DAEMON_LIFESPAN@ milliseconds
.TP
.B -D, --discovery-attempts=\fIattempts
number of attempts (UDP/IP multicast sent datagrams) performed to locate \fBflom\fP daemon; if the answer to UDP/IP multicast does not arrive, auto-discovery will fail. If not specified, the default value is @_DEFAULT_DISCOVERY_ATTEMPTS@
.TP
.B -I, --discovery-timeout=\fImilliseconds
timeout related to UDP/IP multicast auto-discovery feature: if the answer to UDP/IP multicast query does not arrive before this timeout, another datagram is sent (until \fIattempts\fP limit is reached). If not specified, the default value is @_DEFAULT_DISCOVERY_TIMEOUT@ milliseconds
.TP
.B --discovery-ttl=\fITTL
IP hop limit for outgoing UDP/IP multicast datagrams (this option may be useful if your datagrams have to traverse some router). If not specified, the default value is @_DEFAULT_DISCOVERY_TTL@
.TP
.B --tcp-keepalive-time=\fIseconds
\fBflom\fP daemon sets SO_KEEPALIVE attribute to every TCP/IP socket connected with a \fBflom\fP command; this parameter allows you to change after how many connection inactivity \fIseconds\fP the kernel will start to probe the TCP/IP connection. A good explanation of \fBtcp_keepalive_time\fP kernel parameter can be found at this URL: \fIhttp://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO\fP. If not specified, the default value set by \fBflom\fP daemon is @_DEFAULT_TCP_KEEPALIVE_TIME@ seconds
.TP
.B --tcp-keepalive-intvl=\fIseconds
\fBflom\fP daemon sets SO_KEEPALIVE attribute to every TCP/IP socket connected with a \fBflom\fP command; this parameter allows you to change how many \fIseconds\fP the kernel will wait before a new probe of the TCP/IP connection (the \fIconnection inactivity condition\fP already triggered before successive probes are issued). A good explanation of \fBtcp_keepalive_intvl\fP kernel parameter can be found at this URL: \fIhttp://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO\fP. If not specified, the default value set by \fBflom\fP daemon is @_DEFAULT_TCP_KEEPALIVE_INTVL@ seconds
.TP
.B --tcp-keepalive-probes=\fIprobes
\fBflom\fP daemon sets SO_KEEPALIVE attribute to every TCP/IP socket connected with a \fBflom\fP command; this parameter allows you to change how many \fIprobes\fP for a suspicious connection will be tried by the kernel before the connection will be terminated. A good explanation of \fBtcp_keepalive_probes\fP kernel parameter can be found at this URL: \fIhttp://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO\fP. If not specified, the default value set by \fBflom\fP daemon is @_DEFAULT_TCP_KEEPALIVE_PROBES@ probes
.TP
.B -T, --command-trace-file=\fIFILENAME
file destination of the trace messages produced by the command (foreground) process; \fIFILENAME\fP must be an absolute path. \fBFLOM_TRACE_MASK\fP environment variable must be set with an active bit for every desired module
.TP
.B -t, --daemon-trace-file=\fIFILENAME
file destination of the trace messages produced by the daemon (background) process; \fIFILENAME\fP must be an absolute path. \fBFLOM_TRACE_MASK\fP environment variable must be set with an active bit for every desired module
.P
.SH EXIT STATUS
if anything runs as expected, \fBflom\fP exit status is the same of the controlled (serialized) command. Sometimes an error occurs and \fBflom\fP reports it using dedicated exit statuses you can check with \fI$?\fP environment variable:
.P
\fB@_ES_UNABLE_TO_EXECUTE_COMMAND@:\fP \fBflom\fP caught an error trying to exec (see \fIexecvp\fP man page) COMMAND
.P
\fB@_ES_RESOURCE_BUSY@:\fP the resource can \fBnot\fP be locked because it's already locked by someone else (have you used \fB--resource-wait=no\fP option?!)
.P
\fB@_ES_GENERIC_ERROR@:\fP \fBflom\fP caught some type of error and did not execute COMMAND
.P
.SH ENVIRONMENT
environment variable \fBFLOM_TRACE_MASK\fP can be used to activate internal detailed trace. The available flags are explained in file \fIflom_trace.h\fP; you can activate more than one module trace using OR operation between values
.P
.SH EXAMPLES
See web page \fIhttp://sourceforge.net/p/flom/wiki/FLOM%20by%20examples/\fP for a list of detailed use cases
.P
.SH CAVEATS
.B flom -- flom --
[COMMAND [ARG]...]
.P
hangs due to a deadlock: the inner flom instance waits the lock obtained by the first flom instance.
.SH AUTHOR
Christian Ferrari (tiian@users.sourceforge.net)
.SH REPORTING BUGS
Bugs should be reported using \fIhttp://sourceforge.net/p/flom/tickets/\fP. Suggestions, hints and helps should be asked using \fIhttp://sourceforge.net/p/flom/discussion/\fP
.SH COPYRIGHT
Copyright (C) 2013-2014, Christian Ferrari. License GPL version 2 \fIhttp://www.gnu.org/licenses/\fP. This is free software: you are free to change and redistribute it. There is 
.B NO WARRANTY
, to the extent permitted by law.
.SH SEE ALSO
More documentation available at project wiki page
.P
\fIhttp://sourceforge.net/p/flom/wiki/Home/\fP
.P
A sample configuration file (\fI@_SYSTEM_CONFIG_FILENAME@\fP) is installed in dir \fI@docdir@\fP: you may copy it and customize as explained inside the sample itself.
.P
Take a look to file \fIflom_trace.h\fP for \fBFLOM_TRACE_MASK\fP environment variable setting.