OCF_HEARTBEAT_FILESY(7)

💅 ocf_heartbeat_Filesystem(7) — the Filesystem resource agent, explained

okay so bestie, this is ocf_heartbeat_Filesystem(7) from the OCF resource agents crew, and it's literally the page that tells you how to manage a filesystem mount on shared storage. sit down, grab a 🍓, we're doing this.

---

✨ NAME ✨

ocf_heartbeat_Filesystem — manages filesystem mounts. that's it, that's the vibe. it mounts them, it checks them, it stops them. a whole main character. 👑

---

🌸 SYNOPSIS 🌸

Filesystem [start | stop | monitor | meta-data | validate-all]

those are your actions, periodt. pick one.

---

🦋 DESCRIPTION 🦋

So it's a resource script for Filesystem — it manages a Filesystem on a shared storage medium. no cap.

And here's the tea on monitoring ☕: the standard monitor operation at depth 0 (also called the probe) just checks whether the filesystem is mounted. that's it. shallow, but honest.

If you want deeper tests (like, actually look at it, not just vibe check), set OCF_CHECK_LEVEL to one of these:

10: read the first 16 blocks of the device (raw read)

okay so real talk — this doesn't exercise the filesystem at all 💀, it only touches the device the filesystem lives on. and for non-block devices such as NFS, SMBFS, or bind mounts, this is a noop. literally nothing happens. 🙈

20: test if a status file can be written and read

writes a status file and reads it back, which means the status file must be writable by root. and ngl, that's not always the case with an NFS mount, because NFS exports usually have the root_squash option set. so in that kind of setup, you have exactly three options, bestie:

• use read-only monitoring (depth=10),
• export with no_root_squash on your NFS server,
• or grant world write permissions on the directory where the status file is going to be placed.

pick your fighter. 🥊

---

💖 SUPPORTED PARAMETERS 💖

• device — the name of the block device for the filesystem, or -U, -L options for mount, or an NFS mount specification.

NOTE: On Linux, /dev/disk/by-{uuid,label}/ are preferred to -U/-L. like, please use those, they're iconic. 💅

(required, string, no default)

• directory — the mount point for the filesystem. the place where it lives. 🏠

(required, string, no default)

• fstype — the type of filesystem to be mounted.

(required, string, no default)

• options — any extra options to be given as -o options to mount.

for bind mounts, add "bind" here and set fstype to "none". we will do the right thing for options such as "bind,ro". we gotchu. 🫶

(optional, string, no default)

• statusfile_prefix — the prefix to be used for a status file for resource monitoring with depth 20. if you don't specify this parameter, all status files will be created in a separate directory.

(optional, string, default ".Filesystem_status/")

• run_fsck — specify how to decide whether to run fsck or not.
  • "auto" : decide to run fsck depending on the fstype (default)
  • "force" : always run fsck regardless of the fstype
  • "no" : do not run fsck ever.

(optional, string, default "auto")

• fast_stop — normally, we expect no users of the filesystem and the stop operation to finish quickly. but if you cannot control the filesystem users easily and you want to prevent the stop action from failing, then set this parameter to "no" and add an appropriate timeout for the stop operation. 🔥

this defaults to "no" for GFS2 filesystems.

(optional, boolean, default no)

• force_clones — the use of a clone setup for local filesystems is forbidden by default. but for special setups like glusterfs, cloning a mount of a local device with a filesystem like ext4 or xfs independently on several nodes is a valid use case. 👀

Only set this to "true" if you know what you are doing! like actually. fr fr. 💀

(optional, boolean, default false)

• force_unmount — this option allows specifying how to handle processes that are currently accessing the mount directory. choose your energy:
  • "true" : kill processes accessing the mount point
  • "safe" : kill processes accessing the mount point using methods that avoid functions that could potentially block during process detection
  • "false" : do not kill any processes.

you may add one or more comma separated modifiers "[no]move", "[no]xargs", "[no]ps". for example:

• "true,xargs,nops" : find processes using system tools, then kill them "simultaneously" using xargs kill, do not bother to show process details.
• "safe,move,noxargs,ps" : move the mount first, then find processes by walking /proc/ "manually", then show process details and kill them individually in a loop.
• "safe,move,xargs,ps" : move the mount first, then find processes by walking /proc/ "manually", then use xargs ps to show process details before using xargs kill to get rid of them.

if you have modifiers that contradict each other, the last mentioned wins — "ps,nops" results in nops. last one standing, periodt. ✋

the 'safe' option uses shell logic to walk the /proc/<pid>/ directories for pids using the mount point, while the default option uses the fuser cli tool. and heads up: fuser is known to perform operations that can potentially block if unresponsive nfs mounts are in use on the system. 😭

also, if new users of the file system are being spawned continuously by unmanaged 3rd party apps, we likely never win the race and the file system will be kept busy. which may result in a timeout and stop failure, potentially escalating to hard-reset of this node via fencing. that's the bad ending, avoid it. 🚨

the 'move' option tries to mount --move the mount point somewhere those "rogue apps" do not expect it, then proceed to kill current users and attempt to umount. sneaky. iconic. 🧚

for 'move' to work, you will have to make sure the mount point does not reside under a shared mount, for example by mount -o bind,private /mount /mount before mounting /mount/point.

(optional, string, default "true")

• term_signals — signals (names or numbers, whitespace separated) to send processes during the graceful termination phase in the stop-action. polite but firm. 🎀

(optional, string, default "TERM")

• kill_signals — signals (names or numbers, whitespace separated) to send processes during the forceful killing phase in the stop-action. no more mr. nice girl. 💅

(optional, string, default "KILL")

• signal_delay — how many seconds to wait after sending term/kill signals to processes in the stop-action.

(optional, string, default "1")

---

⭐ SUPPORTED ACTIONS ⭐

this resource agent supports the following actions (operations). slay:

• start — starts the resource. suggested minimum timeout: 60s.
• stop — stops the resource. suggested minimum timeout: 60s.
• monitor — performs a detailed status check. suggested minimum timeout: 40s. suggested interval: 20s.
• validate-all — performs a validation of the resource configuration. suggested minimum timeout: 5s.
• meta-data — retrieves resource agent metadata (internal use only). suggested minimum timeout: 5s.

---

🌈 EXAMPLE CRM SHELL 🌈

here's an example config for a Filesystem resource using the crm(8) shell. copy-paste responsibly ✨:

primitive p_Filesystem ocf:heartbeat:Filesystem \
  params \
    device=string \
    directory=string \
    fstype=string \
  op monitor depth="0" timeout="40s" interval="20s"

---

🎀 EXAMPLE PCS 🎀

and here's the same energy for pcs(8):

pcs resource create p_Filesystem ocf:heartbeat:Filesystem \
  device=string \
  directory=string \
  fstype=string \
  op monitor OCF_CHECK_LEVEL="0" timeout="40s" interval="20s"

---

🔥 SEE ALSO 🔥

• http://clusterlabs.org/ — go say hi, iykyk 🦋

---

👑 AUTHOR 👑

ClusterLabs contributors (see the resource agent source for information about individual authors). legends, all of them. 🫶

---

and that's the whole page, bestie — no crumbs left. this gem is from the resource-agents package, version UNKNOWN, dated 10/01/2026, and it lives at OCF_HEARTBEAT_FILESY(7). go mount something responsibly 💖✨