mkfs.ocfs2(8)

📦
version 1.8.9 · 3 versions
, in fedora 44, ubuntu resolute, ubuntu stonking

💖 mkfs.ocfs2 — OCFS2 Manual Pages 💖

okay bestie, buckle up, because we're about to talk about the OCFS2 manual page mkfs.ocfs2(8) and honestly? it's a lot, but we're gonna get through it together 🫶

✨ NAME ✨

mkfs.ocfs2 — creates an OCFS2 file system. that's it, that's the whole vibe. it makes filesystems. iconic behavior honestly 💅

🌸 SYNOPSIS 🌸

mkfs.ocfs2 [-b block-size] [-C cluster-size] [-L volume-label] [-M
mount-type] [-N number-of-nodes] [-J journal-options]
[--fs-features=[no]sparse...] [--fs-feature-level=feature-level] [-T
filesystem-type] [--cluster-stack=stackname]
[--cluster-name=clustername] [--global-heartbeat] [--discard |
--nodiscard] [-FqvV] device [blocks-count]

like, look at all those little flags. they're all important, we're gonna go through every single one, no skipping, no cap 🔥

🦋 DESCRIPTION 🦋

so mkfs.ocfs2 is the girl whose whole job is creating an OCFS2 file system on a device, which is usually a partition on a shared disk. she's the moment. she's the blueprint. ✨

and listen, she's also careful — because we do not do data loss in this house. so if mkfs.ocfs2 peeks at an existing OCFS2 volume and notices it's mounted on another node in the cluster, she will simply not format it. protective queen behavior fr fr 🛡️

also important: this tool needs the cluster service to be online. like, it's not optional, it's the whole mood. if the cluster service is not up, this is not happening.

💅 OPTIONS 💅

here comes the part where I tell you about every flag, because every flag matters, and I refuse to gatekeep.

  • -b, --block-size block-size — sets the block size. the valid values are 512, 1K, 2K and 4K bytes per block. if you don't say anything, a value gets heuristically determined based on what the file system is expected to be used for (peep the -T option, she knows things). and bestie, a block size of 512 bytes is never recommended — like, ever. choose 1K, 2K or 4K. that's the move. 🎀
  • -C, --cluster-size cluster-size — sets the cluster size. valid values are 4K, 8K, 16K, 32K, 64K, 128K, 256K, 512K and 1M. if omitted, a value gets heuristically determined based on the expected usage of the file system (again, that's the -T option doing her thing). for volumes expected to store large files — think database files — a cluster size of 128K or more is the recommendation, but you can opt for a smaller size as long as that value is not smaller than the database block size. for everything else, use 4K. simple as. 💖
  • -F, --force — so for existing OCFS2 volumes, mkfs.ocfs2 makes sure the volume isn't mounted on any node in the cluster before formatting. for that check to work, she expects the cluster service to be online. specify this option to disable that check. yes, that means skipping the safety net. do with that information what you will. 😭
  • -J, --journal-options options — creates the journal using options specified on the command-line. journal options are comma separated, and may take an argument using the equals (=) sign. the following options are supported:
    • size=journal-size — creates a journal of size journal-size. minimum size is 4M. if omitted, a value is heuristically determined based upon the file system size. ✨
    • block32 — uses a standard 32bit journal. the journal will be able to access up to 2^32-1 blocks. this is the default. it has been the journal format for OCFS2 volumes since the beginning (elder emoji, respect her 👑). the journal is compatible with all versions of OCFS2. prepending no is equivalent to the block64 journal option.
    • block64 — uses a 64bit journal. the journal will be able to access up to 2^64-1 blocks. this allows large filesystems that can extend to the theoretical limits of OCFS2. it requires a new-enough filesystem driver that uses the new journalled block device, JBD2. prepending no is equivalent to the block32 journal option.
  • -L, --label volume-label — sets the volume label for the file system. this is super useful for mounting-by-label (iykyk). keep the label under 64 bytes, bestie, that's the limit. 🏷️
  • -M, --mount mount-type — valid types are local and cluster. local mount lets users mount the volume without the cluster overhead, and it works only with OCFS2 bundled with Linux kernels 2.6.20 or later. defaults to cluster. 💫
  • -N, --node-slots number-of-node-slots — valid number ranges from 1 to 255. this number specifies the maximum number of nodes that can concurrently mount the partition. if omitted, the number depends on volume size: for volume size < 2G, it's 2; for 2G <= size < 10G, it's 4; for 10G <= size < 1T, it's 8; for other size, it's 16. and guess what — the number of slots can be later tuned up or down using tunefs.ocfs2. so you're not locked in forever, periodt. 🔢
  • -T filesystem-type — specifies how the filesystem is going to be used, so that mkfs.ocfs2 can choose optimal filesystem parameters for that use. the supported filesystem types are:
    • mail — appropriate for file systems that will host lots of small files. 📧
    • datafiles — appropriate for file systems that will host a relatively small number of very large files. 🗂️
    • vmstore — appropriate for file systems that will host Virtual machine images. 🖥️
  • --fs-features=[no]sparse... — turns specific file system features on or off. a comma separated list of feature flags can be provided, and mkfs.ocfs2 will try to create the file system with those features set according to the list. to turn a feature on, include it in the list. to turn a feature off, prepend no to the name. choices here will override individual features set via the --fs-feature-level option. and bestie, please refer to the section titled feature compatibility before selecting specific features — that's not a suggestion, that's a heads up. 🚨 the following flags are supported:
    • backup-super — mkfs.ocfs2, by default, makes up to 6 backup copies of the super block at offsets 1G, 4G, 16G, 64G, 256G and 1T depending on the size of the volume. this can be useful in disaster recovery. this feature is fully compatible with all versions of the file system and generally should not be disabled. like, she's your safety net, leave her alone. 🛟
    • local — creates the file system as a local mount, so that it can be mounted without a cluster stack.
    • sparse — enables support for sparse files. with this, OCFS2 can avoid allocating (and zeroing) data to fill holes. turn this feature on if you can, otherwise extends and some writes might be less performant. so like, on = good vibes. ✨
    • unwritten — enables unwritten extents support. with this turned on, an application can request that a range of clusters be pre-allocated within a file. OCFS2 will mark those extents with a special flag so that expensive data zeroing doesn't have to be performed. reads and writes to a pre-allocated region act as reads and writes to a hole, except a write will not fail due to lack of data allocation. this feature requires sparse file support to be turned on. no sparse, no unwritten, that's the rule. 🔗
    • inline-data — enables inline-data support. if this feature is turned on, OCFS2 will store small files and directories inside the inode block. data is transparently moved out to an extent when it no longer fits inside the inode block. in some cases, this can also make a positive impact on cold-cache directory and file operations. cute and efficient, we love her. 🎀
    • extended-slotmap — the slot-map is a hidden file on an OCFS2 fs which is used to map mounted nodes to system file resources. the extended slot map allows a larger range of possible node numbers, which is useful for userspace cluster stacks. if required, this feature is automatically turned on by mkfs.ocfs2. she handles it herself, don't stress. 💅
    • metaecc — enables metadata checksums. with this enabled, the file system computes and stores the checksums in all metadata blocks. it also computes and stores an error correction code capable of fixing single bit errors. math girlboss energy, honestly. 🧮
    • refcount — enables creation of reference counted trees. with this enabled, the file system allows users to create inode-based snapshots and clones known as reflinks. snapshots?? clones?? yes bestie, that's the vibe. 📸
    • xattr — enables extended attributes support. with this enabled, users can attach name:value pairs to objects within the file system. in OCFS2, the names can be up to 255 bytes in length, terminated by the first NUL byte. while it is not required, printable names (ASCII) are recommended. the values can be up to 64KB of arbitrary binary data. attributes can be attached to all types of inodes: regular files, directories, symbolic links, device nodes, etc. this feature is required for users wanting to use extended security facilities like POSIX ACLs or SELinux. 🏷️
    • usrquota — enables user quota support. with this feature enabled, the filesystem will track amount of space and number of inodes (files, directories, symbolic links) each user owns. it is then possible to limit the maximum amount of space or inodes a user can have. see a documentation of quota-tools package for more details. 👤
    • grpquota — enables group quota support. with this feature enabled, the filesystem will track amount of space and number of inodes (files, directories, symbolic links) each group owns. it is then possible to limit the maximum amount of space or inodes a user can have. see a documentation of quota-tools package for more details. 👥
    • indexed-dirs — enables directory indexing support. with this feature enabled, the file system creates indexed tree for non-inline directory entries. for large scale directories, directory entry lookup performance from the indexed tree is faster then from the legacy directory blocks. (yes, "then" — I'm keeping it exactly as she wrote it, no cap 🫶)
    • discontig-bg — enables discontiguous block groups. with this feature enabled, the file system is able to grow the inode and the extent allocators even when there is no contiguous free chunk available. it allows the file system to grow the allocators in smaller (discontiguous) chunks. ✨
    • clusterinfo — enables storing the cluster stack information in the superblock. this feature is needed to support userspace cluster stacks and the global heartbeat mode in the o2cb cluster stack. if needed, this feature is automatically turned on by mkfs.ocfs2. 💫

okay that's part one bestie, and we are not done — more of this manual page is coming, so don't go anywhere 🌈

  • --fs-feature-level=feature-level — bestie, this one lets you pick a pre-determined set of filesystem features. It's literally designed so users can conveniently choose a set of filesystem features that fits their needs. And no cap: there is no downside to trying a set of features which your module might not support — if it won't mount the new filesystem, simply reformat at a lower level. Feature levels can be fine-tuned via the --fs-features option. Currently, there are 3 types of feature levels:
    • max-compat — chooses fewer features but ensures that the filesystem can be mounted from older versions of the OCFS2 module. safe and cozy 🫶
    • default — the default feature set tries to strike a balance between providing new features and maintaining compatibility with relatively recent versions of OCFS2. It currently enables sparse, unwritten, inline-data, xattr, indexed-dirs, discontig-bg, refcount, extended-slotmap and clusterinfo.
    • max-features — choose the maximum amount of features available. This will typically provide the best performance from OCFS2 at the expense of creating a filesystem that is only compatible with very recent versions of the OCFS2 kernel module. high risk, high reward energy ✨
  • --cluster-stack — specify the cluster stack. This option is normally not required as mkfs.ocfs2 chooses the currently active cluster stack. It is required only if the cluster stack is not online and the user wishes to use a stack other than the default, o2cb. Other supported cluster stacks are pcmk (Pacemaker) and cman (rgmanager). Once set, OCFS2 will only allow mounting the volume if the active cluster stack and cluster name matches the one specified on-disk. iykyk 🦋
  • --cluster-name — specify the name of the cluster. This option is mandatory if the user has specified a cluster-stack. This name is restricted to a max of 16 characters. Additionally, the o2cb cluster stack allows only alpha-numeric characters. keep it short, keep it cute 💅
  • --global-heartbeat — enable the global heartbeat mode of the o2cb cluster stack. This option is not required if the o2cb cluster stack with global heartbeat is online as mkfs.ocfs2 will detect the active stack. However, if the cluster stack is not up, then this option is required alongwith cluster-stack and cluster-name. For more, refer to o2cb(7). 💓
  • --discard — attempt to discard blocks at mkfs time (discarding blocks initially is useful on solid state devices and sparse / thin-provisioned storage). When the device advertises that discard also zeroes data (any subsequent read after the discard and before write returns zero), then mark all not-yet-zeroed blocks as zeroed. This significantly speeds up filesystem initialization. This is set as default. speedy queen 🌸
  • --nodiscard — do not attempt to discard blocks at mkfs time. the opposite vibe 🙈
  • --no-backup-super — this option is deprecated, please use --fs-features=nobackup-super instead. > deprecated alert! don't use this one, use the other one bestie 😭
  • -n, --dry-run — display the heuristically determined values without overwriting the existing filesystem. preview mode, no take-backs 👑
  • -q, --quiet — quiet mode. 🤫
  • -U uuid — specify a custom UUID in the plain (2A4D1C581FAA42A1A41D26EFC90C1315) or traditional (2a4d1c58-1faa-42a1-a41d-26efc90c1315) format. This option is not recommended because the filesystem uses the UUID to uniquely identify a filesystem. If more than one filesystem were to have the same UUID, one is very likely to encounter erratic behavior, if not, outright filesystem corruption. > ⚠️ seriously, don't unless you know exactly what you're doing 💀
  • -v, --verbose — verbose mode. 🗣️
  • -V, --version — print version and exit. ⭐
  • blocks-count — usually mkfs.ocfs2 automatically determines the size of the given device and creates a filesystem that uses all of the available space on the device. This optional argument specifies that the filesystem should only consume the given number of filesystem blocks (see -b) on the device. tiny filesystem moment 🎀

✨ FEATURE COMPATIBILITY ✨

This section lists the filesystem features that have been added to the OCFS2 filesystem and the version that it first appeared in. The table below lists the versions of the mainline Linux kernel and ocfs2-tools. Users should use this information to enable only those features that are available in the filesystem that they are using. Before enabling new features, users are advised to review the section titled feature values. do your homework bestie 📚

Here's the compatibility timeline, but make it a list because tables are not the vibe:

  • local — Kernel Version: Linux 2.6.20; Tools Version: ocfs2-tools 1.2
  • sparse — Kernel Version: Linux 2.6.22; Tools Version: ocfs2-tools 1.4
  • unwritten — Kernel Version: Linux 2.6.23; Tools Version: ocfs2-tools 1.4
  • inline-data — Kernel Version: Linux 2.6.24; Tools Version: ocfs2-tools 1.4
  • extended-slotmap — Kernel Version: Linux 2.6.27; Tools Version: ocfs2-tools 1.6
  • metaecc — Kernel Version: Linux 2.6.29; Tools Version: ocfs2-tools 1.6
  • grpquota — Kernel Version: Linux 2.6.29; Tools Version: ocfs2-tools 1.6
  • usrquota — Kernel Version: Linux 2.6.29; Tools Version: ocfs2-tools 1.6
  • xattr — Kernel Version: Linux 2.6.29; Tools Version: ocfs2-tools 1.6
  • indexed-dirs — Kernel Version: Linux 2.6.30; Tools Version: ocfs2-tools 1.6
  • refcount — Kernel Version: Linux 2.6.32; Tools Version: ocfs2-tools 1.6
  • discontig-bg — Kernel Version: Linux 2.6.35; Tools Version: ocfs2-tools 1.6
  • clusterinfo — Kernel Version: Linux 2.6.37; Tools Version: ocfs2-tools 1.8

Users can query the features enabled in the filesystem as follows:

# tunefs.ocfs2 -Q "Label: %V\nFeatures: %H %O\n" /dev/sdg1
Label: apache_files_10
Features: sparse inline-data unwritten

✨ FEATURE VALUES ✨

okay bestie this part is literally the cheat sheet 💅 this is where we spill the hex values that go with each file system feature. super useful when you're debugging mount failures that happen because of feature incompatibility, iykyk.

so picture this: someone tries to mount an OCFS2 volume that has features enabled which the running file system software does not support. it's gonna fail, and it's gonna fail with an error like:

ERROR: couldn't mount because of unsupported optional features (200).

and now you're like ??? 🙈 but wait — peek at the list below and it becomes so obvious: they tried to mount a volume with the xattr (extended attributes) feature turned on, using a version of the file system software that didn't support it. classic. at this point the user has two options, and only two:

  • upgrade the file system software, or
  • disable that on-disk feature using tunefs.ocfs2.

some features are lowkey chill and will let the file system mount with an older version of the software — but only if the mount is read-only. if someone tries to mount a volume like that in read-write mode, it fails with an error like:

ERROR: couldn't mount RDWR because of unsupported optional features (1).

this one means the volume had the unwritten RO Compat feature enabled, and a volume like that can only be mounted by older file system software in read-only mode. so again, two options bestie:

  • mount the volume with the ro mount option, or
  • disable that on-disk feature using tunefs.ocfs2.

🌈 The Feature Table (as a list bc we're cozy like that) 🌈

Incompat 🚫

  • local — hex value 8
  • sparse — hex value 10
  • inline-data — hex value 40
  • extended-slotmap — hex value 100
  • xattr — hex value 200
  • indexed-dirs — hex value 400
  • metaecc — hex value 800
  • refcount — hex value 1000
  • discontig-bg — hex value 2000
  • clusterinfo — hex value 4000

RO Compat 🌸

  • unwritten — hex value 1
  • usrquota — hex value 2
  • grpquota — hex value 4

👀 SEE ALSO 👀

debugfs.ocfs2(8) fsck.ocfs2(8) mount.ocfs2(8) mounted.ocfs2(8) o2cb(7) o2cluster(8) o2image(8) o2info(1) tunefs.ocfs2(8)

like, go read those too, they're the rest of the squad 🫶

💖 AUTHORS 💖

Oracle Corporation

Copyright © 2004, 2012 Oracle. All rights reserved.

and that's the whole page bestie, we ate and left no crumbs 🎀 this was Version 1.8.9, dated January 2012, and it's the mkfs.ocfs2(8) manual page — iconic behavior honestly 👑 now go format something pretty ✨🦋💜

📦 where this page comes from