• Features
• Commands
  • newfs
  • info
  • makefs
  • tunefs
  • growfs
  • fsck_ufs
  • ls
  • extract
  • replace
  • add
  • delete
  • rename
  • chmod
  • stat
  • find
  • du
  • mount_udf
  • umount_udf
  • devinfo
• Examples
• PS5 Quick Start
• GUI Application
• Building
• Testing
• Implementation Details
• Platform-Specific Guides
• Notes
• License

• Create UFS1 and UFS2 filesystems on image files or raw Windows devices
• Full newfs(8) compatibility — supports all standard FreeBSD newfs flags (except -T, -k, -r)
• Populate from directory — create images from directory contents with auto-sizing (-D)
• makefs command — FreeBSD makefs(8) compatible interface for creating filesystem images from directory trees
• growfs command — FreeBSD growfs(8) compatible interface for expanding existing filesystem images
• fsck_ufs command — FreeBSD fsck_ffs(8)/fsck_ufs(8) compatible filesystem consistency checker
• Extract files from existing UFS1/UFS2 filesystem images
• Replace files in existing UFS1/UFS2 filesystem images (single file or directory tree)
• Add files to existing UFS1/UFS2 filesystem images (single file or directory tree, recursive)
• Delete files from existing UFS1/UFS2 filesystem images (single file or directory tree, recursive)
• Rename files or directories inside UFS1/UFS2 filesystem images
• Search for files by name pattern with glob wildcards (*, ?) and type filtering
• Disk usage analysis similar to FreeBSD du(1) with human-readable sizes, depth limiting, and summary mode
• Mount UFS images as Windows drives with read-write support via Dokan
• Read and inspect existing UFS1/UFS2 filesystem images
• List directory contents from UFS1/UFS2 images
• Device I/O — direct writing to physical drives and volumes on Windows

ufs2tool newfs [-EJNUjlnt] [-D input-directory] [-L volname] [-O format] [-S sector-size]
               [-a maxcontig] [-b block-size] [-c blocks-per-cg]
               [-d max-extent-size] [-e maxbpg] [-f frag-size]
               [-g avgfilesize] [-h avgfpdir] [-i bytes-per-inode]
               [-m free-space%] [-o optimization] [-p partition]
               [-s size] <target> [size-MB] [volume-name]

ufs2tool info <image-path>

FreeBSD makefs(8) compatible — creates a filesystem image from a directory tree without requiring special devices or privileges.

ufs2tool makefs [-DxZ] [-B endian] [-b free-blocks] [-f free-files]
                [-M minimum-size] [-m maximum-size] [-o fs-options]
                [-S sector-size] [-s image-size] [-T timestamp]
                [-t fs-type] image-file directory

Size suffixes: b (×512), k (×1024), m (×1M), g (×1G), t (×1T), w (×4). Products with x: e.g., 512x1024 = 524288.

ufs2tool tunefs [-Ap] [-a enable|disable] [-e maxbpg] [-f avgfilesize]
               [-J enable|disable] [-j enable|disable] [-k metaspace]
               [-L volname] [-l enable|disable] [-m minfree]
               [-N enable|disable] [-n enable|disable] [-o space|time]
               [-s avgfpdir] [-t enable|disable] <image-path>

Modify layout parameters on an existing UFS1/UFS2 filesystem image. Equivalent to FreeBSD's tunefs(8).

# Print current tuneable values
ufs2tool tunefs -p myimage.img

# Enable soft updates journaling
ufs2tool tunefs -j enable myimage.img

# Set volume label and minfree
ufs2tool tunefs -L MYVOLUME -m 5 myimage.img

# Write updated superblock to all backup locations
ufs2tool tunefs -A -n enable myimage.img

ufs2tool growfs [-Ny] [-s size] <image-path>

Expand an existing UFS1/UFS2 filesystem image. Equivalent to FreeBSD's growfs(8).

Examples:

# Grow filesystem to fill expanded image
truncate -s 512M myimage.img
ufs2tool growfs -y myimage.img

# Grow to specific size
ufs2tool growfs -y -s 256m myimage.img

# Dry-run: see what would happen
ufs2tool growfs -N -s 1g myimage.img

ufs2tool fsck_ufs [-dfnpy] [-b block] <filesystem>

File system consistency check and interactive repair. Equivalent to FreeBSD's fsck_ffs(8)/fsck_ufs(8). Also available as fsck_ffs.

Performs a five-phase check:

1. Phase 1 — Check Blocks and Sizes (validate block pointers, detect duplicates, verify sizes)
2. Phase 2 — Check Pathnames (walk directory tree, validate entries)
3. Phase 3 — Check Connectivity (find orphaned inodes)
4. Phase 4 — Check Reference Counts (verify link counts)
5. Phase 5 — Check Cylinder Groups (verify CG summaries, free counts)

# Check a filesystem image
ufs2tool fsck_ufs myimage.img

# Force check a clean filesystem
ufs2tool fsck_ufs -f myimage.img

# Preen mode (auto-fix safe issues)
ufs2tool fsck_ufs -p myimage.img

# Check with debug output
ufs2tool fsck_ufs -df myimage.img

# Read-only check (same as -n)
ufs2tool fsck_ufs -n myimage.img

ufs2tool ls <image-path> [path]

ufs2tool extract <image-path> <output-directory> [fs-path]

Extract files from a UFS1/UFS2 filesystem image. If fs-path is omitted, extracts the entire filesystem. If it points to a directory, extracts recursively. If it points to a file, extracts that single file.

ufs2tool replace <image-path> <fs-path> <source-path>

Replace a file or directory in a UFS1/UFS2 filesystem image. If fs-path points to a file, its content is replaced with source-path. If it points to a directory, matching files from source-path are replaced recursively.

# Replace a single file
ufs2tool replace myimage.img /path/to/file.txt ./local/file.txt

# Replace matching files in a directory
ufs2tool replace myimage.img /path/to/dir ./local/dir

ufs2tool add <image-path> <fs-path> <source-path>

Add a file or directory to a UFS1/UFS2 filesystem image. If source-path is a file, it is added at fs-path. If source-path is a directory, it is created at fs-path and its contents are added recursively.

# Add a single file
ufs2tool add myimage.img /newfile.txt ./local/file.txt

# Add a file into a subdirectory
ufs2tool add myimage.img /subdir/newfile.txt ./local/file.txt

# Add a directory recursively
ufs2tool add myimage.img /newdir ./local/dir

ufs2tool delete <image-path> <fs-path>

Delete a file or directory from a UFS1/UFS2 filesystem image. If fs-path points to a directory, all contents are deleted recursively.

# Delete a single file
ufs2tool delete myimage.img /path/to/file.txt

# Delete a directory recursively
ufs2tool delete myimage.img /path/to/dir

ufs2tool rename <image-path> <fs-path> <new-name>

Rename a file or directory inside a UFS1/UFS2 filesystem image. The entry stays in the same parent directory; only its name is changed.

# Rename a file
ufs2tool rename myimage.img /path/to/old.txt newname.txt

# Rename a directory
ufs2tool rename myimage.img /path/to/olddir newdir

ufs2tool chmod [-R] <image-path> <mode> [fs-path | dir-mode]

Change the permission mode of a file or directory inside a UFS1/UFS2 filesystem image, or apply permissions to the entire image recursively.

# Change permissions on a single file
ufs2tool chmod myimage.img 644 /path/to/file.txt

# Change permissions on a directory
ufs2tool chmod myimage.img 755 /path/to/dir

# Recursively set file permissions for the entire image
ufs2tool chmod -R myimage.img 644

# Recursively set file and directory permissions separately
ufs2tool chmod -R myimage.img 644 755

ufs2tool stat <image-path> <fs-path>

Displays detailed inode information for a file, directory, or symbolic link inside a UFS1/UFS2 filesystem image. Output includes file type, inode number, permissions (octal and symbolic), link count, owner UID/GID, size, block count, timestamps (access, modify, change, birth), and block pointer usage.

Examples:

# Show info for root directory
ufs2tool stat myimage.img /

# Show info for a specific file
ufs2tool stat myimage.img /path/to/file.txt

# Show info for a subdirectory
ufs2tool stat myimage.img /path/to/dir

ufs2tool find <image-path> <name-pattern> [-type f|d|l] [-path start-path]

Recursively search for files and directories matching a name pattern within a UFS1/UFS2 filesystem image. Supports glob-style wildcards (* and ?) and optional type filtering.

# Find all .txt files
ufs2tool find myimage.img "*.txt"

# Find files matching a prefix
ufs2tool find myimage.img "game*" -type f

# Find all directories
ufs2tool find myimage.img "*" -type d

# Find files in a specific subdirectory
ufs2tool find myimage.img "*.cfg" -path /etc

ufs2tool du [-h] [-s] [-d depth] <image-path> [fs-path]

Display disk usage for files and directories in a UFS1/UFS2 filesystem image, similar to FreeBSD's du(1).

# Show disk usage for the entire filesystem
ufs2tool du myimage.img

# Show disk usage with human-readable sizes
ufs2tool du -h myimage.img

# Show summary only
ufs2tool du -s myimage.img

# Show disk usage for a specific directory
ufs2tool du myimage.img /subdir

# Limit depth
ufs2tool du -d 1 myimage.img

ufs2tool mount_udf [-o options] [-v] <image-path> <drive-letter>

Mount a UFS1/UFS2 filesystem image as a Windows drive letter using the Dokan driver. Supports read-only (default) and read-write modes.

# Mount read-only
ufs2tool mount_udf myimage.img X:

# Mount read-write
ufs2tool mount_udf -o rw myimage.img X:

# Unmount
ufs2tool umount_udf X:

Requires the Dokan driver to be installed.

ufs2tool umount_udf <drive-letter>

Unmount a previously mounted UFS filesystem drive. Alternatively, pressing Ctrl+C in the mount_udf terminal also cleanly unmounts.

ufs2tool devinfo <device-path>

# Create a 256 MB UFS2 image with default settings
ufs2tool newfs myimage.img 256

# Create a UFS1 image with custom block/fragment sizes
ufs2tool newfs -O 1 -b 16384 -f 2048 myimage.img 128

# Create with soft updates, journaling, and TRIM enabled
ufs2tool newfs -Ujt -L MYVOLUME myimage.img 512

# Auto-sized image from directory contents
ufs2tool newfs -D /path/to/my/files output.img

# With explicit options and directory population
ufs2tool newfs -O 1 -D /path/to/my/files output.img MyVolume

# Dry run — show what would be created without writing
ufs2tool newfs -N myimage.img 256

# Create distribution image (soft updates disabled by default)
ufs2tool makefs output.img /path/to/my/files

# Create UFS2 image with makefs (FreeBSD-compatible syntax)
ufs2tool makefs -t ffs -o version=2 output.img /path/to/my/files

# makefs with label and custom block size
ufs2tool makefs -o version=2,bsize=32768,label=MYVOLUME output.img /path/to/my/files

# makefs with size constraints
ufs2tool makefs -s 256m output.img /path/to/my/files
ufs2tool makefs -b 10% -f 10% output.img /path/to/my/files

# makefs with soft updates explicitly enabled
ufs2tool makefs -o softupdates=1,version=2 output.img /path/to/my/files

# Add a single file to the filesystem
ufs2tool add myimage.img /newfile.txt ./local/file.txt

# Add a directory recursively
ufs2tool add myimage.img /newdir ./local/dir

# Delete a single file
ufs2tool delete myimage.img /path/to/file.txt

# Delete a directory recursively
ufs2tool delete myimage.img /path/to/dir

# Create on a Windows device (requires Administrator)
ufs2tool newfs \\.\PhysicalDrive2
ufs2tool newfs -O 1 -b 16384 -f 2048 \\.\E:

# Inspect a filesystem image
ufs2tool info myimage.img
ufs2tool ls myimage.img

Use this command to quickly create a UFS2 image compatible to be mounted on the PS5 with ShadowMount:

UFS2Tool.exe newfs -D <folder> <PPSAxxxx.ffpkg>

Alternatively, you can use this command to quickly create a UFS2 image with FreeBSD-compatible FFS options that can be mounted on the PS5 with ShadowMount:

UFS2Tool.exe makefs -S 4096 -t ffs -o version=2,minfree=0,softupdates=0,optimization=space <PPSAxxxx.ffpkg> <folder>

The GUI's PS5 tab also supports batch processing — add multiple input folders and generate all .ffpkg images in one operation. Output filenames are automatically derived from folder names, with collision detection to prevent overwrites when multiple folders share the same name.

The project includes a modern cross-platform GUI built with Avalonia UI in the UFS2Tool.GUI directory. The GUI provides a graphical interface for all major UFS2Tool operations:

• Create Filesystem — Create UFS1/UFS2 images with configurable parameters
• Filesystem Operations — List, extract, add, delete, replace files, and change permissions
• Content Browser — Browse filesystem contents visually with tree navigation
• Maintenance — TuneFS, GrowFS, and FsckUFS operations
• Write Filesystem — Write UFS images to USB drives and physical devices with progress tracking and optional post-write verification (Windows, Linux, macOS)
• Device Mount — Mount/unmount UFS images as Windows drives (Windows only, requires Dokan)
• PS5 Quick Create — Preset templates for PS5-compatible filesystem creation with single-folder and batch processing modes
• Settings — Language selection with automatic detection from OS locale (supports 26 languages)

Building the GUI:

dotnet build UFS2Tool.GUI/UFS2Tool.GUI.csproj

Running the GUI:

dotnet run --project UFS2Tool.GUI/UFS2Tool.GUI.csproj

Note: The GUI runs on Windows, Linux, and macOS. See the Platform-Specific Guides section for setup instructions on each platform.

Requires .NET 8.0 SDK or later.

Using the solution file (builds CLI, GUI, and tests):

dotnet build UFS2-Tool.sln

Using the project file directly (CLI only):

dotnet build UFS2Tool.csproj
dotnet run -- newfs myimage.img 256

GUI only:

dotnet build UFS2Tool.GUI/UFS2Tool.GUI.csproj

The project includes a comprehensive xUnit test suite in the UFS2Tool.Tests directory:

dotnet test

For a detailed breakdown of the core library components, filesystem structures, and all implemented features, see IMPLEMENTATIONS.md.

• Linux Guide — Required packages and step-by-step instructions for running UFS2Tool and the GUI on Linux
• macOS Guide — Required packages and step-by-step instructions for running UFS2Tool and the GUI on macOS

• Device operations (newfs on physical drives, devinfo, mount_udf) require Administrator privileges on Windows.
• The tool targets net8.0 and uses conditional Windows-specific features for device I/O and Dokan mounting.
• Image file operations (create, inspect, extract, add, delete, replace, chmod, growfs, tunefs, fsck) work on any platform supported by .NET 8.0.
• Filesystem images created by this tool are compatible with FreeBSD's mount and fsck_ffs.
• When creating images with makefs, soft updates are disabled by default (softupdates=0), matching FreeBSD makefs(8) behavior. Use -o softupdates=1 to enable them explicitly.

This project is licensed under the BSD 2-Clause License. See the LICENSE file for details.