We’ve walked into more than a few shops where the z/OS Unix System Services (USS) file system grew organically over a decade or two — home-grown directories bolted onto root, application teams inventing their own conventions, and nobody quite sure which mount points are safe to touch during maintenance. None of this is unique to the mainframe; it’s the same drift you’d see on any Unix system left unsupervised. But on z/OS, the consequences are a little sharper, since USS shares the box with your batch, CICS, and DB2 workloads, and a filesystem that fills up or gets mounted wrong can take down more than just a shell session.

Here’s a rundown of the standard top-level directories under root, what each one is for, and where we typically see things go sideways.

/bin

Executables and shell utilities — the Unix equivalent of your system libraries. This is IBM-supplied and shouldn’t be touched. If you’ve installed Rocket, Python, or other USS-based tooling, that belongs in /usr/lpp or a similar product-specific mount, not crammed into /bin.

/etc

Configuration files for USS itself and any Unix-based subsystems — things like inetd.conf, profile, and resolv.conf. This directory tends to accumulate cruft over the years as products install their own config snippets. Keep a change log of anything you hand-edit here; it’s one of the few directories where a typo can quietly break TCP/IP services or telnet/ssh access for the whole LPAR.

/dev

Device files — pseudo-terminals, /dev/null, /dev/random, and so on. You’ll rarely need to touch this directly, but it’s worth knowing it’s there when you’re troubleshooting odd terminal behavior in OMVS or SSH sessions.

/tmp

Temporary storage, typically backed by a separate zFS or HFS mounted specifically for this purpose. This is the one we see cause outages most often. Application teams and ISV products love to dump scratch files here, and if /tmp is sharing space with anything else — or worse, is part of the root filesystem — a runaway job can fill it and start affecting unrelated work. Give /tmp its own zFS, size it generously, and consider an automated cleanup job (find files older than X days, or use the system’s tmpwatch-equivalent housekeeping) to keep it from becoming a junk drawer.

/var

Variable data — logs, spool files, lock files, and other things that change frequently during normal operation. Like /tmp, this is a good candidate for its own mount point so a noisy logging subsystem doesn’t compete with your application directories for space.

/usr

Where most installed software lives, including /usr/lpp (IBM and ISV product installs) and often /usr/local for site-specific tools. If you’re running things like Git, Python, Java, or open source tooling under USS, this is generally where it gets staged. Treat /usr/lpp as read-mostly outside of maintenance windows — it’s shared infrastructure, and developers poking around in here looking for a quick fix is a bad habit to let take root.

/opt

Less universally used on z/OS than on distributed Unix, but you’ll see some vendors install here instead of under /usr/lpp. Worth knowing about so you’re not surprised when a product’s installer asks for it.

/SYSTEM (z/OS-specific)

Mount points for system-related filesystems tied to a specific sysplex or LPAR — kernel-related data, sysplex root structures, and similar. This one’s specific to z/OS’s shared/sysplex root model and won’t show up on a distributed Unix box. Generally hands-off unless you’re a systems programmer working sysplex root maintenance.

/SCOPE (z/OS-specific)

Similarly tied to the shared file system model — holds release-specific or system-specific data depending on how your shared root is configured. Again, this is systems programming territory, not application territory.

/u — the one that actually needs your attention

The /u directory is where user home directories live — one subdirectory per TSO/USS user ID, typically /u/userid. This is by far the directory most likely to bite you operationally, because unlike /bin or /usr, it’s not static. It grows continuously and unpredictably as every developer, batch ID, and started task with a home directory writes config files, log output, downloaded source, and the occasional forgotten core dump into their own corner of it.

A few things we consistently recommend:

Give /u its own zFS, separate from root. This is non-negotiable in any shop running more than a handful of users. If /uis part of the root filesystem and a single user’s runaway process fills their home directory, you risk taking down USS services for everyone. A dedicated zFS for /u contains the blast radius to that one mount.

Consider per-user or grouped zFS data sets rather than one giant /u filesystem. Many shops mount a single large zFS at /u and let every user share it. That works fine until someone’s .profile script goes into a loop writing log files, fills the filesystem, and now nobody can log in — including the systems programmer who needs to fix it. Splitting heavy users (developers actively compiling, testing, and debugging) into their own zFS data sets, automounted on demand, isolates that risk per-user instead of shop-wide.

Use automount where you can. z/OS’s automount facility (via /etc/auto.master and friends) will mount a user’s home directory zFS on first access and unmount it after a period of inactivity. This avoids having hundreds of permanently mounted filesystems consuming storage and address space resources for users who haven’t logged on in months.

Watch your quotas. Whether you’re using zFS quotas or just relying on dataset space allocation, set a sane ceiling per user. Developers doing active DBB/Git work in their home directory — cloning repos, running builds, generating listings — can burn through space far faster than a typical TSO user. Size accordingly, and don’t be afraid to give your DevOps-heavy users a larger allocation than everyone else; that’s a more sustainable fix than firefighting “filesystem full” pages at 2 AM.

Be deliberate about what belongs in /u versus a shared application directory. We’ve seen teams accidentally treat a developer’s home directory as a shared workspace — checking build scripts or shared configuration into someone’s personal /u/userid because it was convenient at the time. When that person leaves or their ID gets revoked, the shop loses access to files everyone depended on. Anything that needs to outlive an individual’s account — shared scripts, team configuration, pipeline artifacts — belongs in /var, /usr/local, or an application-owned mount, not buried in a personal home directory.

Clean up stale home directories. When a user ID is revoked or deleted, the home directory under /u often gets left behind. Over the years this adds up to a meaningful amount of orphaned storage and, more importantly, files that don’t belong to anyone — which is its own audit and security headache. Tie home directory cleanup into your user offboarding process rather than treating it as a separate housekeeping task that never quite gets prioritized.

Steer clear of the # character in user IDs and file names. This one catches shops off guard because TSO/RACF happily allows # (along with @ and $) in a user ID, and it’s a long-standing mainframe convention going back to the days when those were the only “special” characters available. The problem is that # is a comment character in the shell, a history-expansion trigger in some shells, and gets mangled by various scripting and parsing tools that assume a more traditional Unix-safe character set. A home directory like /u/#smith or a file inside it can cause a script to silently truncate a command, misinterpret an argument, or skip processing entirely — and it’s a miserable thing to troubleshoot because the directory looks fine sitting in a listing. If your shop’s user ID convention includes #, @, or $, it’s worth flagging that as a known land mine for anyone writing shell scripts, automount maps, or build tooling against /u, and avoiding those characters in any new file or directory names you create by hand.

Getting the USS directory structure right isn’t glamorous work, but it’s the kind of thing that pays for itself the first time you avoid a filesystem-full outage at the worst possible moment. If you’re planning a USS storage review — or migrating a pile of ad hoc home directories into something more disciplined — happy to talk through it.