Setting up a Modern Unix Development Environment on z/OS (USS)

by

Your first steps towards feeling at home on the mainframe.

When you’re coming from Linux or any Unix-like system, the first encounter with z/OS can feel… different. Yes, it’s powerful, rock-solid, and built to run some of the world’s most important workloads. But when you SSH into UNIX System Services (USS) for the first time, the environment can feel pretty bare.

The good news: you can turn USS into a comfortable, modern Unix development environment. One that feels familiar, comes with most of the tools you expect, and lets you work productively.

This post walks you through exactly that setup. And because this will be the foundation for all upcoming articles in this series, we’ll do it clean and step by step.

Who is this for?

This guide is aimed at two groups:

  • Developers who moved into the z/OS world and want a familiar, Unix-like workspace.
  • People with a z/OS background who always used TSO/ISPF but now want to get more productive inside USS.

If you want bash, vim, git, make, curl & friends on z/OS, you’re in the right place.

Prerequisites

To keep this post focused on the actual setup, we assume the following is already in place:

  • You can SSH into USS.
  • Your RACF user has a valid OMVS segment (UID, home directory, shell).
  • USS is mounted and operational.
  • You have access to a sufficiently large zFS file system for installing the tools (Z Open Community Tools can easily consume several GB, depending on what you install).

That’s pretty much all we need.

About the tools we’ll install

There are two main ways to get modern open-source tools on z/OS.

The enterprise way (recommended)

Ask your system programmer to install one or both of these globally:

  • IBM Open Enterprise Foundation for z/OS (OEF) → an officially supported IBM offering
  • Z Open Tools (ZOPEN) → the full, community-driven toolchain

This is the cleanest and most maintainable option.
If your organization allows it, go for this.

The “I’m just a developer and want my tools now” way

A local, per-user installation of Z Open Tools.

This guide focuses on this user-level installation because:

  • It requires zero sysprog authority,
  • It works anywhere,
  • And it’s perfect for personal dev environments.

What we’ll set up

By the end of this guide, your environment will have:

  • bash as your default shell
  • vim as your editor
  • GNU make
  • git
  • curl
  • jq
  • A clean ~/.bashrc
  • A usable PATH and environment

In short: a comfortable, modern base Unix workspace on z/OS.

Installing Z Open Tools (user-level)

The Z Open Tools project provides precompiled open-source packages specifically for z/OS.
Since we don’t yet have curl or anything fancy in USS, we’ll install them the manual way — which is exactly what the project recommends for fresh systems.

Step 1: Downloading the installer on your workstation

Go to the Z Open releases page:

https://github.com/ZOSOpenTools/meta/releases

Download the file named meta-<version>.pax.Z

Save it somewhere local.

Step 2: Uploading the installer to z/OS

Use SFTP to place the installer in your USS home directory.

Example:
(Hint: You will be prompted to enter your z/OS password if you haven’t set up public key authentication for SSH.)
(Hint4Hint: Might be an extra “mini” post.)

sftp youruserid@yourhost
put meta-<version>.pax.Z
quit

Step 3: Extracting the installer

SSH into your system:
(Hint: You will be prompted to enter your z/OS password if you haven’t set up public key authentication for SSH.)

ssh youruserid@yourhost
cd $HOME
pax -rf meta-<version>.pax.Z

Step 4: Run the installer

Changing into the newly created directory, prepare the environment, and run the installer:

cd meta-<version>
. ./.env
zopen init

The installer will ask where to place the toolchain.
A good choice is the given default value:

$HOME/zopen

Step 5: Sourcing the environment and installing wanted tools

Now the zopen command should be available:

. $HOME/zopen/etc/zopen-config

zopen install bash git vim make less -y

This will take a while, depending on your system.
Grab a coffee. Maybe two.

Step 6: Cleaning up

cd $HOME
rm -f meta-<version>.pax.Z
rm -rf meta-<version>

Setting up the base environment

Most tools from the Z Open Tools need a enhanced ASCII environment. Following environment variables should be set by your system programmer in /etc/profile.
But we can handle this per user, too.

Add following variables to $HOME/.profile:

# enable enhanced ASCII support
export _BPXK_AUTOCVT="ON"
export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG)"
export _TAG_REDIR_ERR=txt
export _TAG_REDIR_IN=txt
export _TAG_REDIR_OUT=txt

# source Z Open Tools environment
ZOPEN_QUICK_LOAD=1 . $HOME/zopen/etc/zopen-config --quiet

Now we can reload / source the updated .profile file to enable our changes:

. $HOME/.profile

From now on, we should be able to use our newly installed tools. Verify the installation:

bash --version
vim --version
git --version
gmake --version
curl --version

You should start the bash, now:

bash

Setting up bash

To configure the bash shell, we have to create and fill some new configuration files. Please have in mind, these bash configuration files should be tagged as ISO8895-1.

cd $HOME
touch .bashrc .bash_profile
chtag -tc ISO8859-1 .bashrc .bash_profile
echo "if [ -f ~/.bashrc ]; then . ~/.bashrc; fi" >> .bash_profile

vim .bashrc
# add following lines

export TERM=xterm
export TERMINFO=/usr/share/lib/terminfo/
export ASCII_TERMINFO=$HOME/zopen/usr/local/share/terminfo/
export VIMRUNTIME=$HOME/zopen/usr/local/share/vim/vim91/
export LESS='-iR'
export PAGER=less
export GIT_PAGER=less
export EDITOR=vim
export VISUAL=vim
export HISTSIZE=10000
export TMPDIR=/tmp
export LANG=C


# seeting up a nice prompt
parse_git_branch() {
     git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
export PS1="\[\e[36m\]\u\[\e[m\]@\[\e[32m\]\h:\[\e[33;1m\]\w\[\e[m\]\[\033[33m\]\$(parse_git_branch)\[\033[00m\]\$ "

Reload / source the newly created config file:

. .bashrc

You should have a working bash environment, now.

Extra: a starting configuration for vim

Create a $HOME/.vimrc file and tag it as ISO8859-1

cd $HOME
touch .vimrc
chtag -tc ISO8859-1 .vimrc
vim .vimrc

# add folowing lines
set t_Co=256
syntax on
set number
set tabstop=4
set shiftwidth=4
set expandtab
set autoindent
set smartindent
set background=dark
colorscheme blue

Making bash your default shell

You have to options to make the bash your login / default shell. If you have permission, you could update your OMVS segment:

tsocmd "ALTUSER {youruserid} OMVS(Program(/u/{youruserid}/zopen/usr/local/bin/bash))"

If you do not have the permission, ask your system programmer to do this for you.

Another option is to let the current default shell let start the bash, automatically. Add the following line to the end of your $HOME/.profile file:

[ -x "$HOME/zopen/usr/local/bin/bash" ] && exec "$ZOPEN_ROOT/bin/bash"

(This keeps things simple and sysprog-free.)

What’s next?

Now that your USS environment is comfortable, future posts in this series will dive into:

But for now?
You’ve just taken the biggest step: making USS feel like home.

Welcome to the mainframe.

7 thoughts on “Setting up a Modern Unix Development Environment on z/OS (USS)”

  2. Excellent blog – a few comments

    1. for Step 2 and 3 mention that the user will be prompted to enter their z/OS password
    2. (1) can be avoided later by creating their $HOME/.ssh/authorized_keys file
    – use copy/paste for their workstations public key since sftp does *not* support text file transfer
    3. Ask/beg your sysprog to get the Co:Z Toolkit for an improved ssh/sftp experience
    – it’s free for most and not that expensive for the rest (and worth the cost for supporting a great product
    – see https://coztoolkit.com/downloads/coz/index.html
    – among the benefits are text sftp, sftp access to z/OS datasets, and much much more
    4. For a future blog discuss DSFS for easy access to z/OS datasets for *any* USS tool (e.g. grep, vim, …)

    Reply

    • Hello Lionel,

      Thank you very much for your comments.
      I will incorporate the notes regarding password entry.
      I will make a separate post on Co:Z, just as I will for DSDF.

      Best,
      Mike

      Reply
  3. Pingback: Building a Modern VIM Configuration from Scratch – Part 1: Solid Foundations – Neunetz IT Blog
  4. Pingback: Building a Modern VIM Configuration from Scratch – Part 2: Essential Plugins – Neunetz IT Blog
  5. Pingback: Building a Modern VIM Configuration from Scratch – Part 3: IDE Intelligence with LSP – Neunetz IT Blog

Leave a Comment