FreeBSD newfs: Provision UFS Filesystems Deliberately

The FreeBSD newfs utility constructs a new UFS1 or UFS2 filesystem on a provider. It initializes filesystem structures and clears previous filesystem metadata; it is not a nondestructive repair command. A wrong device argument can destroy the wrong dataset or filesystem even when the operator only intended to prepare a new disk. The safest workflow starts by tracing the intended disk through its partition table and GEOM providers, rehearsing the layout with the no-write mode, and requiring a second identity check before creation.

This guide covers UFS provisioning, not ZFS pool creation or UFS recovery. It explains which creation-time choices are difficult to change later, which settings can be reviewed with tunefs(8), and how to verify the completed filesystem before adding it to boot-time mounts. Defaults are often sensible, but “default” does not mean the target device or workload was correctly identified.

Establish the target from the outside inward

Begin with a storage inventory. Match the disk by serial, model, capacity, transport, and expected attachment path. Then inspect its partition table and GEOM providers. The short name da0 can change when device discovery order changes; a stable label or documented hardware identity is better evidence than an old command transcript.

geom disk list
gpart show -lp
gpart list
geom part list

If the disk already contains data, stop. Do not run newfs, gpart create, or a format test to investigate it. Confirm the application owner, backup status, current mounts, and the approved change plan. Check whether GEOM mirroring, multipath, encryption, or a virtual machine exposes a different layer than the physical disk.

Determine which layer will receive the filesystem. A GPT partition such as /dev/gpt/ufs_appdata is a provider distinct from the whole disk /dev/da0. Formatting the whole disk can overwrite the partition table and every partition. Formatting a partition can overwrite its existing filesystem while preserving the outer GPT. The exact target must match the design.

For a new disk, create the partition layout using an approved GPT plan and a stable label, then inspect it again. This article deliberately does not supply a generic partition-creation command because sector alignment, EFI requirements, boot layout, encryption, mirror topology, and capacity reservations are installation-specific. After partitioning, verify the label resolves to the intended provider:

glabel status
gpart show -lp
diskinfo -v /dev/gpt/ufs_appdata
mount -p

Do not continue if the label is missing, capacity differs from the change plan, or the provider is already mounted. mount -p is a useful inventory but does not reveal every possible open consumer. On a production system, check the application and storage stack before making a destructive change.

Choose format parameters from workload evidence

newfs builds a UFS1 or UFS2 filesystem; consult the target release manual and ffs(4) for the actual options. UFS block and fragment sizes, cylinders-per-group, average file size and density, reserved space, and optimization mode affect layout. Arbitrarily copying flags from an old host can bake assumptions about disk geometry and file mix into a new filesystem.

For most workloads, keep the release documented defaults unless measurements or a specific constraint justify a change. The -i bytes-per-inode setting influences inode density. A workload with very many tiny files can exhaust inodes even when blocks remain; an unnecessarily dense inode layout consumes space that could otherwise hold data. Estimate both file count and average file size from representative directories, and keep capacity for growth and metadata.

The free-space reserve is an operational buffer, not extra capacity. Running a filesystem close to full can degrade allocation behavior and leave too little room for logs, temporary files, or recovery. Choose any nondefault reserve intentionally, state who can consume it, and alert well before the filesystem reaches it. Do not reduce the reserve to “recover” space on an already-full production filesystem without evaluating the impact.

Soft Updates and journaling are separate choices. The -U option enables Soft Updates during creation; the UFS manual describes dependency tracking and the related Soft Updates journaling option. GEOM journaling through -J is a different mechanism, and the newfs manual documents incompatibilities with some combinations. Select only a mode supported by the target release and storage design. Do not assume that a journal turns an ordinary workload into a database-grade durability guarantee.

Before any write, use -N to print planned parameters without creating a filesystem:

newfs -N -U /dev/gpt/ufs_appdata

The output is a planning aid, not a device-identity check. Compare it with the approved size and parameters. The no-write option cannot tell whether the path points to the intended tenant data or whether an automation layer substituted the wrong provider.

Create only after an independent identity check

Once the change plan, backup, provider, and options are reviewed, format the confirmed target. This example is destructive and is not for copy-and-paste without replacing the label with an independently verified provider:

newfs -U -L appdata /dev/gpt/ufs_appdata

Do not include an explicit block size, inode density, optimization, or sector size unless the storage engineer has chosen it. The label helps identify the filesystem later, but it is not a substitute for confirming the provider. Stop immediately if the command reports an unexpected size, an I/O error, a busy provider, or a different format than the change plan.

After creation, inspect the filesystem metadata before mounting:

fstyp /dev/gpt/ufs_appdata
dumpfs -s /dev/gpt/ufs_appdata
fsck_ffs -n /dev/gpt/ufs_appdata

fsck_ffs -n requests a read-only check. A clean check immediately after formatting is a useful consistency signal, not a substitute for an application test or a hardware health check. Do not run a modifying filesystem check on a mounted writable filesystem. If metadata inspection fails, preserve the exact output and investigate the provider before proceeding.

Mount to a dedicated empty directory and verify both the mount source and resulting capacity:

mkdir -p /srv/appdata
mount -t ufs /dev/gpt/ufs_appdata /srv/appdata
mount -p | grep -F /srv/appdata
df -hT /srv/appdata

Check the output rather than assuming the command mounted the intended device. Test expected ownership, permissions, and application write behavior using a harmless test object. Avoid writing a full workload before confirming that the filesystem, mount flags, and service account match the change.

Separate creation-time decisions from tunable state

Some UFS parameters can be inspected or modified later using tunefs(8), but many operations have mount-state requirements and some choices are not freely changeable. Use dumpfs -m to print a newfs-style reconstruction of relevant filesystem parameters:

dumpfs -m /dev/gpt/ufs_appdata

Treat the output as evidence for an approved maintenance plan, not a ready-made command to run. It may contain flags that were appropriate when the filesystem was created but should not be blindly replayed against another provider. Keep the output with the change record so future operators can distinguish configured behavior from assumptions.

The label, filesystem type, size, and geometry should be settled at creation. Mount policy belongs in /etc/fstab after a successful test. Use a stable label or provider path as the source; verify it resolves to the right filesystem before relying on automatic mount at boot. Choose the filesystem-check pass fields based on the filesystem role and local policy, and test the entry with the documented mount -a workflow during a maintenance window.

Do not make a filesystem read-only or enable unusual mount behavior as a generic safety fix. Mount flags and mountpoint ownership affect the workload contract. Apply the narrowest required policy and confirm the actual mount options after reboot.

Failure cases and rollback boundaries

If newfs reports a provider is busy, identify the consumer. Do not force-detach a GEOM provider or use a force option merely to proceed; another filesystem, swap device, mirror, or virtualized layer may be active. If capacity is smaller than expected, stop before formatting and return to the partition/provider boundary. A filesystem cannot safely be sized using sectors the provider does not expose.

If the newly created filesystem fails to mount, preserve its metadata and logs. Confirm the filesystem type, provider, GEOM stack, and kernel messages. Do not repeatedly run newfs as a troubleshooting step; each attempt can overwrite recoverable metadata. If the wrong device was formatted, stop writes immediately, preserve the device, and use a data-recovery procedure. A backup restore is generally safer than speculative repairs to a newly overwritten filesystem.

An accepted provisioning record should include hardware identity, GEOM topology, partition map, provider path, newfs command, full command output, filesystem type and label, mount options, verification results, owner, and backup reference. Record any nondefault parameter with its reason and the person or design document that approved it.

Acceptance criteria

The filesystem is ready only when the operator has verified the target provider independently, inspected the planned format, confirmed the created filesystem type and label, mounted the intended source, tested ownership and a harmless read/write path, and validated the persistent mount configuration. Confirm the service observes the same path and capacity after a controlled restart or reboot.

Keep the separation clear: partitioning defines the provider, newfs initializes UFS, mount configuration exposes it, and the application validates its own data path. Success at one layer does not prove the others. This layered record makes destructive storage work reviewable and recoverable.

Related:

Sources: