1. Manuals
  2. Tumbleweed
  3. flom
  4. flom.man(1)

Scroll to navigation

man(1) flom man page man(1)

NAME

flom - serialize command execution

SYNOPSIS

flom [OPTION] [-- [COMMAND [ARG]...]]

DESCRIPTION

Run COMMAND serializing it with other commands executed under the supervision of flom or explicitly synchronizing using FLoM API (libflom).

OPTIONS

Show help options
Print flom version and exit
Stop the running daemon after current activity completion
Stop the running daemon immediately without any quiesce time
Verbose mode execution
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
Name of the resource used for enqueing (locking)

Simple resource names can be composed of "alpha" and "digit" characters, but the first character must be of type "alpha" (example: "RA123" is OK, "123RA" is not OK). Accepted resource names are described in function "global_res_name_preg_init": inspect source code for more details

Numeric resource names are composed by simple resource names followed by an integer value enclosed in square brackets ("[ ]"); examples: "foo[12]", "bar[3]", "RA123[23]". Numbers must be expressed using decimal base)

Resource set names are obtained concatenating simple resource names with character '@_RESOURCE_SET_SEPARATOR@' (example: "RED@_RESOURCE_SET_SEPARATOR@BLUE@_RESOURCE_SET_SEPARATOR@GREEN")

Hierarchical resource names are like absolute path filenames using "@_DIR_FILE_SEPARATOR@" as the level delimiter (but a trailing delimiter is not allowed); examples: "@_DIR_FILE_SEPARATOR@apple", "@_DIR_FILE_SEPARATOR@apple@_DIR_FILE_SEPARATOR@pear" are valid names while "@_DIR_FILE_SEPARATOR@apple@_DIR_FILE_SEPARATOR@" and "@_DIR_FILE_SEPARATOR@apple@_DIR_FILE_SEPARATOR@pear@_DIR_FILE_SEPARATOR@" are not valid names

Sequence resource names are composed by _s_ (non transactional) or _S_ (transactional) prefix and a simple resource name followed by an integer value enclosed in square brackets ("[ ]"); examples: "_s_foo[12]", "_S_bar[3]", "_s_RA123[23]". Numbers must be expressed using decimal base)

Timestamp resource names are composed by the _t_ prefix followed by a timestamp format and by an integer value enclosed in square brackets ("[ ]"); examples: "_t_foo.%D.%T[4]", "_t_bar:%S#fff[1]". Numbers must be expressed using decimal base)

Additional information can be retrieved from official wiki documentation: http://sourceforge.net/p/flom/wiki/Home/

Default (-1): maximum enqueue time if the resource is already locked by someone else; if the resource doesn't become free before timeout milliseconds the command will return. A negative value means "infinite timeout" and the command will wait until the resource will become free. If the value equals zero, in case of locked resource, the command will not wait
Number of numeric resources to lock; it's meaningless if the locked resource is not of type "numeric". number must be an integer positive number. Note: only positive values are accepted
Default (yes): the command will create the resource if it was not already created by another command, otherwise (no) it will wait for resource creation or will end immediately (see -o, --resource-timeout option). Note: if used with a hierarchical resource, the behavior applies to the root level of the resource, not to the single leaf
How long a resource will be kept after last usage, default value is 0 milliseconds; this option can be used to avoid a following job that specifies -e n, --resource-create=no will wait undefinitely just because the previous task terminated too early. Warning: too many long lasting resources can waste memory and threads inside flom daemon. Note: if used with a hierarchical resource, the behavior applies to the root level of the resource, not to the single leaf
Lock mode as defined by VMS DLM (Distributed Lock Manager). MODE can be: "NullLock", "ConcurrentRead", "ConcurrentWrite", "ProtectedRead", "ProtectedWrite", "Exclusive" (equivalent short forms are: "NL", "CR", "CW", "PR", "PW", "EX"). More information are available here http://en.wikipedia.org/wiki/Distributed_lock_manager#Lock_modes
Absolute FILENAME that must be used to create the UNIX socket used for local communication between flom command line and flom daemon; typical values are something like /tmp/something. This option is useful to share locks between different users (the default socket is per user and every user creates a different one)
TCP/IP address that must be used to reach a running daemon; if the daemon must be started locally, IPaddress must be a valid IP address for this host. Both IPv4 and IPv6 addresses can be used
TCP/IP port that must be used to reach a running daemon; if the daemon must be started locally, IPport must be a port not used by another process on this host. If IPaddress (see -a, --unicast-address) is specified and IPport is not specified, the default value is @_DEFAULT_DAEMON_PORT@
UDP/IP multicast address that must be used to discover the location of a running daemon; if the daemon must be started locally, IPaddress must be a valid multicast IP address for this host. Multicast IPv4 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). Multicast IPv6 addresses are documented at this URL: http://www.iana.org/assignments/ipv6-multicast-addresses/. A typical choice is an address in link-local or in site-local range
UDP/IP multicast port that must be used to discover the location of a running daemon; if the daemon must be started locally, IPport must be a port not used by another process on this host. If IPaddress (see -A, --multicast-address) is specified and IPport is not specified, the default value is @_DEFAULT_DAEMON_PORT@
Ignore SIGNAL while waiting for the termination of the monitored program. SIGNAL can be a string like for example "SIGTERM" or "SIGQUIT" or a number like for example "15" or "3". The option can be specified more than once to ignore two or more signals. Some signals can not be ignored: as explained in SIGNAL(7) man page, the signals SIGKILL and SIGSTOP cannot be caught, blocked, or ignored
Print the list of signals that can be used with --ignore-signal and exit
Network interface that must be used to reach IPv6 link-local addresses. It's the equivalent of the % notation that can be used for network addresses but can not be used for network aliases. Typical values are eth0, eth1 and so on. If this option is specified, only IPv6 network adresses will be used
Lifespan of flom daemon if activated, expressed using milliseconds. The value of milliseconds 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 flom daemon). If not specified, the default value is @_DEFAULT_DAEMON_LIFESPAN@ milliseconds
Number of attempts (UDP/IP multicast sent datagrams) performed to locate flom 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@
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 attempts limit is reached). If not specified, the default value is @_DEFAULT_DISCOVERY_TIMEOUT@ milliseconds
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@
FLoM daemon sets SO_KEEPALIVE attribute to every TCP/IP socket connected with a flom command; this parameter allows you to change after how many connection inactivity seconds the kernel will start to probe the TCP/IP connection. A good explanation of tcp_keepalive_time kernel parameter can be found at this URL: http://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO. If not specified, the default value set by flom daemon is @_DEFAULT_TCP_KEEPALIVE_TIME@ seconds
FLoM daemon sets SO_KEEPALIVE attribute to every TCP/IP socket connected with a flom command; this parameter allows you to change how many seconds the kernel will wait before a new probe of the TCP/IP connection (the connection inactivity condition already triggered before successive probes are issued). A good explanation of tcp_keepalive_intvl kernel parameter can be found at this URL: http://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO. If not specified, the default value set by flom daemon is @_DEFAULT_TCP_KEEPALIVE_INTVL@ seconds
FLoM daemon sets SO_KEEPALIVE attribute to every TCP/IP socket connected with a flom command; this parameter allows you to change how many probes for a suspicious connection will be tried by the kernel before the connection will be terminated. A good explanation of tcp_keepalive_probes kernel parameter can be found at this URL: http://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO. If not specified, the default value set by flom daemon is @_DEFAULT_TCP_KEEPALIVE_PROBES@ probes
PEM file containing the X.509 certificate of the peer
PEM file containing the private key of the peer
PEM file containing the X.509 certificate of the certification authority used to sign the peers' certificates
Perform peer authentication comparing the unique ID sent by the peer (see --unique-id option) with the content of the CN field inside the certificate presented by the peer
File destination of the trace messages produced by the command (foreground) process; FILENAME must be an absolute path. FLOM_TRACE_MASK environment variable must be set with an active bit for every desired module
File destination of the trace messages produced by the daemon (background) process; FILENAME must be an absolute path. FLOM_TRACE_MASK environment variable must be set with an active bit for every desired module
Default (no): the command will truncate the trace file(s), otherwise (yes) it will append the trace file(s). The number and the name of the trace files depends on -T, --command-trace-file and -t, --daemon-trace-file options
Print flom unique ID and exit
Activate an IPv6 multicast server (requester) for debugging purposes
Activate an IPv6 multicast client (replier) for debugging purposes
Activate a TLS server for debugging purposes
Activate a TLS client for debugging purposes

EXIT STATUS

If anything runs as expected, flom exit status is the same of the controlled (serialized) command. Sometimes an error occurs and flom reports it using dedicated exit statuses you can check with $? environment variable:

@_ES_UNABLE_TO_EXECUTE_COMMAND@: flom caught an error trying to exec (see execvp man page) COMMAND

@_ES_RESOURCE_BUSY@: the resource can not be locked because it's already locked by someone else (have you used --resource-timeout=0 option?!)

@_ES_GENERIC_ERROR@: flom caught some type of error and did not execute COMMAND

ENVIRONMENT

Environment variable FLOM_TRACE_MASK can be used to activate internal detailed trace. The available flags are explained in file flom_trace.h; you can activate more than one module trace using OR operation between values

EXAMPLES

A list of example use cases is avalaible at this web page http://www.tiian.org/flom/FLoM_by_examples/FLoM_by_examples.html

CAVEATS

flom -- flom -- [COMMAND [ARG]...]

Hangs due to a deadlock: the inner flom instance waits the lock obtained by the first flom instance.

AUTHOR

Christian Ferrari (tiian@users.sourceforge.net)

REPORTING BUGS

Bugs should be reported using https://github.com/tiian/flom/issues. Suggestions, hints and helps should be asked using http://sourceforge.net/p/flom/discussion/

COPYRIGHT

Copyright (C) 2013-2023, Christian Ferrari. License GPL version 2 http://www.gnu.org/licenses/. This is free software: you are free to change and redistribute it. There is NO WARRANTY , to the extent permitted by law.

SEE ALSO

Official documentation is available at

http://www.tiian.org/flom/

A sample configuration file (@_SYSTEM_CONFIG_FILENAME@) is installed in dir @docdir@: you may copy it and customize as explained inside the sample itself.

Take a look to file flom_trace.h for FLOM_TRACE_MASK environment variable setting.

@_RELEASE_DATE@ @PACKAGE_VERSION@