UFSD

UFSD is a cross-address-space virtual filesystem daemon for IBM MVS 3.8j, running on Hercules-emulated mainframe systems.

It runs as a Started Task (STC) and gives client programs Unix-like filesystem access to BDAM datasets. Communication happens via IEFSSREQ (SVC 34); the libufs client library provides a clean C API and serves as a drop-in replacement for ufs370.

Client Address Space          UFSD STC Address Space
─────────────────────         ──────────────────────────────
  your program                  dispatch loop
    │                             ├─ session table (64 slots)
    ▼                             ├─ global file table (256)
  libufs                          ├─ inode / directory / block I/O
    │  IEFSSREQ (SVC 34)          └─ BDAM datasets
    ▼
  SSI router (UFSDSSIR)
    │  CS lock-free queue
    └──── CSA ────────────────▶ UFSD_ANCHOR (request + buffer pools)

Known Limitations

• No per-file permission system. Access control is mount-level only (RO/RW mode + OWNER restriction). There are no per-file or per-inode permission checks. Full RACF/RAKF integration is planned for a future release.
• After /C UFSD the ESTAE deliberately retains the SSI registration and CSA; the next /S UFSD reclaims them automatically (UFSDCLNP remains the standalone fallback)
• No symbolic links, hard links, or file locking
• Maximum file size: 4.06 MB (single indirect blocks)
• On-disk format is not finalized — images may not be portable across future versions

Installation

Download ufsd-<version>-dist.zip (or .tar.gz) from the latest release. It holds the load modules, the sample library, the two installation jobs and a step-by-step guide.

Installation runs through SMP 4, the SMP that ships with MVS 3.8j: upload two XMITs, submit an allocation job once, submit the install job. The system then records what is installed, and there is a defined way back out again.

The complete procedure — including which sample member to copy where, and the authorisation question — is docs/installation.md, which is also the README inside the archive.

Disk Setup

Each mounted filesystem lives in a BDAM dataset, and there are two ways to create one:

• On MVS, with the UFSFMT batch utility. No host toolchain, nothing to upload — allocate the dataset and format it in a single job (samplib/ufsfmt). This is the route for the root disk and for any empty filesystem.
• On a host, with ufsd-utils, when the disk should arrive with content already on it: create an image, fill it with cp -r, then upload.

Both produce the same on-disk layout. See docs/disk-setup.md for the complete workflow.

Starting and Stopping

/S UFSD                         Start with default config
/S UFSD,M=UFSDPRM1              Start with alternate config member
/F UFSD,STATS                   Show status and mount info
/F UFSD,SESSIONS                List active sessions
/F UFSD,HELP                    List available commands
/P UFSD                         Stop the server

For the complete parmlib reference and all operator commands, see docs/configuration.md.

Configuration

The server is configured through a Parmlib member referenced by the UFSDPRM DD card. Key statements:

Statement	Parameters	Description
ROOT	DSN [, BLKSIZE]	Root filesystem (always mounted at /, read-only for clients)
MOUNT	DSN, PATH, MODE, OWNER	Additional filesystem mount

Parameter	Values	Default	Description
DSN(name)	dataset name	—	BDAM dataset to mount
PATH(/path)	absolute path	—	Mount point
MODE(RO|RW)	RO or RW	RO	Read-only or read-write
OWNER(userid)	RACF userid	—	Restrict writes to this userid

For the complete reference, see docs/configuration.md.

Ecosystem

UFSD is part of the mvslovers open-source ecosystem for MVS 3.8j.

Project	Description
ufsd	Cross-address-space UFS filesystem daemon (this project)
ufsd-utils	Host-side CLI for creating and managing UFS disk images
httpd	Multi-threaded HTTP/1.1 server
mvsmf	z/OSMF-compatible REST API (server module for HTTPD)
ftpd	Standalone FTP daemon

For Developers

The libufs client library provides a POSIX-like C API for session management, file I/O, directory operations, and metadata queries. Programs that used ufs370 can switch to libufs with no source changes — the function signatures and asm aliases are identical.

Build instructions, architecture overview, the complete libufs API reference (including assembler calling conventions), and the wire protocol are documented in docs/development.md.

Credits

• Mike Großmann — author and maintainer of UFSD
• Michael Dean Rayborn — original designer of the in-address-space UFS370 filesystem that UFSD is based on

The on-disk format is derived from the Unix V7 filesystem, with code originally contributed to The NetBSD Foundation by UCHIYAMA Yasushi.

License

See LICENSE for details.