man(1)

📦 version 1.6.1, in opensuse-leap 16.0

💖 flom(1) — the manual page 💖

okay so bestie, welcome to flom(1), and honestly? this page is a whole journey. grab a snack. ✨

🦋 NAME 🦋

flom — it serializes command execution. that's it, that's the vibe. it makes sure your commands take turns instead of all shoving through the door at once. 💅

🌸 SYNOPSIS 🌸

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

✨ DESCRIPTION ✨

Run COMMAND, serializing it with other commands that are executed under the supervision of flom, or explicitly synchronizing using the FLoM API (libflom). like, either flom babysits everybody, or you do the coordinating yourself through the API. no cap. 🫶

💅 OPTIONS 💅

  • -h, --help — shows you the help options. the "what do i even do here" button.
  • -v, --version — prints the flom version and dips out. iconic exit behavior.
  • -x, --quiesce-exit — stops the running daemon after the current activity finishes. polite. lets it finish its little task first. 🎀
  • -X, --immediate-exit — stops the running daemon immediately, zero quiesce time, no waiting, no closure. main character energy fr.
  • -V, --verbose — verbose mode execution. it will yap. you will hear everything. 🗣️
  • -c, --config-file=FILENAME — user configuration file name. here's the order of operations, bestie, pay attention: flom tries to read the system default configuration file /etc/flom.conf, then the user default configuration file ~/.flom, and finally this file if you specified one. the definitive configuration is obtained by overloading, in order: hard wired build time defaults → system defaults → user defaults → user custom → command line options. so the command line always gets the last word. 👑
  • -r, --resource-name=RESOURCE — name of the resource used for enqueing (locking). and ohhhh the name grammar, it's giving whole little language so let's break it down:
    • 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. iykyk.
    • 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 . (example: "RED.BLUE.GREEN").
    • Hierarchical resource names are like absolute path filenames using / as the level delimiter (but a trailing delimiter is not allowed); examples: "/apple", "/apple/pear" are valid names while "/apple/" and "/apple/pear/" are not valid names. so watch that trailing slash, it's a trap 🙈
    • 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/ ⭐
  • -o, --resource-timeout=milliseconds — Default (-1): maximum enqueue time if the resource is already locked by someone else; if the resource doesn't become free before milliseconds, the command will return. A negative value means "infinite timeout" and the command will wait until the resource becomes free — it will simply stand there. forever. 💀 If the value equals zero, in case of a locked resource, the command will not wait at all. zero patience.
  • -q, --resource-quantity=number — 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. no negatives, no decimals, we don't do that here. 🍓
  • -e, --resource-create=yes|no — 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.
  • -i, --resource-idle-lifespan=milliseconds — 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 — so like, don't go feral with it 😭. Note: if used with a hierarchical resource, the behavior applies to the root level of the resource, not to the single leaf.
  • -l, --lock-mode=MODE — 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 🔥
  • -s, --socket-name=FILENAME — 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). so if you and your friends wanna share, this is your girl. 🫶
  • -a, --unicast-address=IPaddress — 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. versatile queen. 👑
  • -p, --unicast-port=IPport — 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 28015.
  • -A, --multicast-address=IPaddress — 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. 🌈
  • -P, --multicast-port=IPport — 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 28015. same number, different address family, slay.
  • --ignore-signal=SIGNAL — 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. so don't even try, they're built different 💀
  • --signal-list — print the list of signals that can be used with --ignore-signal and exit. a little menu, cute. 📋
  • -n, --network-interface=interface — 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. no take-backs. 🦋
  • -d, --daemon-lifespan=milliseconds — lifespan of flom daemon if activated, expressed using milliseconds. The value of milliseconds can be an 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 5000 milliseconds. so yes, negative means immortal, love that for it. ⭐
  • -D, --discovery-attempts=attempts — 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 2. two shots and then we're done here.
  • -I, --discovery-timeout=milliseconds — 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 500 milliseconds. ⏳
  • --discovery-ttl=TTL — 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 1. it does not travel far by default, bestie, it stays home. 🏠
  • --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 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 60 seconds.
  • --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 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 10 seconds.
  • --tcp-keepalive-probes=probes — 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 6 probes. six chances, then it's over. 🔥
  • --tls-certificate=FILENAME — PEM file containing the X.509 certificate of the peer. 🎀
  • --tls-private-key=FILENAME — PEM file containing the private key of the peer. keep this one secret, obviously. 🤫
  • --tls-ca-certificate=FILENAME — PEM file containing the X.509 certificate of the certification authority used to sign the peers' certificates. the whole chain of trust, we stan. 👑
  • --tls-check-peer-id=yes|no — peer auth time 🫶: it compares the unique ID the peer sends (that's the --unique-id thing) against the CN field inside the certificate the peer hands over.
  • -T, --command-trace-file=FILENAME — where the trace messages from the command (foreground) process go. FILENAME has to be an absolute path, no shortcuts bestie. And the FLOM_TRACE_MASK environment variable needs an active bit for every module you actually want traced.
  • -t, --daemon-trace-file=FILENAME — same vibe but for the daemon (background) process traces. Again FILENAME must be an absolute path, and again FLOM_TRACE_MASK needs an active bit for each desired module.
  • --append-trace-file=yes|no — default is (no), meaning the command truncates the trace file(s). Say yes and it appends instead. How many files and what they're called depends on -T, --command-trace-file and -t, --daemon-trace-file. iykyk 💅
  • --unique-id — prints the flom unique ID and dips out. that's it, that's the whole job ✨
  • --debug-feature=ipv6.multicast.server — spins up an IPv6 multicast server (requester) purely for debugging.
  • --debug-feature=ipv6.multicast.client — spins up an IPv6 multicast client (replier) purely for debugging.
  • --debug-feature=tls.server — activates a TLS server, debugging purposes only.
  • --debug-feature=tls.client — activates a TLS client, debugging purposes only.

💀 EXIT STATUS 💀

If everything goes how it's supposed to, flom's exit status is the exact same as the controlled (serialized) command's. Slay, inheritance. 🧬

But sometimes things go sideways and flom reports it with its own special exit statuses — peep them with the $? environment variable:

  1. 97: flom caught an error trying to exec (see the execvp man page) COMMAND.
  2. 98: the resource can not be locked because somebody else already locked it (…have you used --resource-timeout=0 option?! 👀).
  3. 99: flom caught some type of error and did not execute COMMAND.
lowkey the 98 is a whole mood — somebody else got there first, not your fault bestie 😭

🌸 ENVIRONMENT 🌸

The environment variable FLOM_TRACE_MASK activates the internal detailed trace. The available flags are explained in the file flom_trace.h — and yes you can activate more than one module's trace by OR-ing the values together. Stack 'em. 🫶

✨ EXAMPLES ✨

There's a whole list of example use cases waiting for you at this web page:

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

🚨 CAVEATS 🚨

ok so this one's important, no cap:

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

Hangs due to a deadlock: the inner flom instance is waiting on the lock that the first flom instance already holds. It's giving "waiting for your own reflection to move" 💀 don't do this.

👑 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/.

(so yes, there's a whole place for your "hey what if…" thoughts, they're welcome there 🫶)

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 (flom.conf) is installed in dir /usr/share/doc/packages/flom: you may copy it and customize as explained inside the sample itself. Copy-paste-and-tweak era 💅

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

okay that's the whole page bestie, go forth and serialize responsibly 🌈💖✨

this little icon of a page is version 1.6.1, dated 2023-05-20 — and it lives under man(1). periodt. 🎀

📦 where this page comes from