Install x3270 on AlmaLinux, RHEL, Rocky Linux, Oracle Linux and CentOS

Mainframe Series, part 1. This part installs a 3270 terminal emulator on Linux so you can open a session to z/OS, z/VM, VSE, or a local Hercules lab. Later parts cover the other integration points (FTP and the JES interface, Connect:Direct, MQ, DB2, z/OSMF and Zowe), the common 3270 and 5250 clients, dataset FTP, the differences between 3270, 5250 and VT/ANSI emulation, and the hardware and software philosophy that still shapes mainframe operations. After that, a full Linux on IBM Z (s390x) series covers everything that is different about running Linux on IBM Z compared with an x86 computer.

A Linux administrator who has to talk to a mainframe almost always starts with a 3270 session. TSO, ISPF, CICS, the z/VM logo screen and most traditional operators’ tools are still block-mode 3270 applications. They do not behave like SSH or a VT terminal, and a regular telnet or SSH client is the wrong tool. The standard open source client on Linux is the x3270 family: an X11 emulator (x3270), a curses emulator you can use over SSH (c3270), a scriptable headless client (s3270) and a 3287 printer emulator (pr3287).

This post shows how to install x3270 on AlmaLinux, Red Hat Enterprise Linux, Rocky Linux, Oracle Linux and CentOS (and, briefly, on Debian and Ubuntu), how the packages are actually split, how to connect to a host, how 3270 keymaps and fonts work, and how a 3270 session itself behaves. Package names and file lists were checked against the official AlmaLinux 10, Rocky Linux 8/9/10 and Oracle Linux 10 repositories, and the clients were installed and exercised on Debian 13. Where something was not tested, that is called out.

Applies to: AlmaLinux 10, Red Hat Enterprise Linux 10, Rocky Linux 10, Oracle Linux 10 and CentOS Stream 10, with notes for the 8 and 9 generations of the same family. The same commands apply on the corresponding older releases with the versions listed below. Debian 13 (trixie) and current Ubuntu are covered as a second packaging style. The x3270 documentation referenced here is the project’s wiki, which is also what the distribution man pages point at.

The x3270 family

Upstream ships several programs from one source tree (suite3270). Distributions split them into packages, but the binaries have the same names everywhere:

ProgramInterfaceTypical use
x3270X11A window that looks like a 3278/3279, with its own 3270 bitmap fonts and a menu bar.
c3270curses / terminalThe client you run in an SSH session or on a text console when you have no X display.
s3270script / stdinAutomation: drive a 3270 session from a script or from x3270if.
pr3287printer (3287)Attach a printer LU and send host print jobs to lpr or a file.
x3270if / playbackhelperTalk to a script port, and replay a saved 3270 trace.

On Windows the same project provides wc3270 and the newer wx3270 GUI. Those are useful to know about when you are comparing clients; they are not what you install on Linux. There is also b3270 (a UI-independent backend) and tcl3270, which Debian packages separately.

Install x3270 on AlmaLinux, RHEL, Rocky Linux, Oracle Linux and CentOS

On the current Red Hat family, x3270 is not an EPEL package. It ships in the distribution’s own repositories: the common tools are in BaseOS, and the X11 frontend is in AppStream. There is no package named c3270 on these distributions; c3270 is the binary inside x3270-text.

That matters because older notes and some generic install guides still say “enable EPEL and install c3270.” I checked EPEL 9 and EPEL 10 (https://dl.fedoraproject.org/pub/epel/, Everything/x86_64/Packages/x/) and there is no x3270 package there. You do not need EPEL for this.

Package names and what they contain

PackageRepository (EL 8/9/10)What you get
x3270BaseOSs3270, pr3287, x3270if, playback, prtodir, and /etc/ibm_hosts. The X11 and curses frontends are separate.
x3270-textBaseOS/usr/bin/c3270 and its man page. Requires the x3270 package.
x3270-x11AppStream/usr/bin/x3270, a desktop file, and the 3270 PCF fonts under /usr/share/fonts/x3270/. Requires the x3270 package.

Versions I confirmed from official repository listings (and, for AlmaLinux 10, by downloading the RPMs and listing their files):

DistributionVersion in the official repos
AlmaLinux 10, Rocky Linux 10, Oracle Linux 10 (and the matching RHEL 10 / CentOS Stream 10 set)4.3ga8-8.el10
Rocky Linux 9 (EL 9 family)4.0ga14-2.el9
Rocky Linux 8 (EL 8 family)3.6ga5-1.el8

AlmaLinux 10 packages were taken from https://repo.almalinux.org/almalinux/10/ (BaseOS x3270 and x3270-text, AppStream x3270-x11). Rocky Linux 8, 9 and 10 were listed from https://download.rockylinux.org/pub/rocky/. Oracle Linux 10 was listed from https://yum.oracle.com/repo/OracleLinux/OL10/ (BaseOS x3270 and x3270-text, AppStream x3270-x11). I did not query a Red Hat subscription repository directly; RHEL 10 and CentOS Stream 10 use the same package names and the same .el10 build.

Install with dnf

For a text-mode client you can use over SSH (the usual choice on a server):

sudo dnf install x3270-text
c3270 -v

dnf will also pull in the x3270 base package, which gives you s3270 and pr3287. To add the X11 emulator and the 3270 fonts on a workstation with AppStream enabled:

sudo dnf install x3270-x11
x3270 -v

Or install the whole set at once:

sudo dnf install x3270 x3270-text x3270-x11

These packages were not installed with dnf on a live AlmaLinux host for this article. The RPM file lists, requires, and the s3270 -v output from the official AlmaLinux 10 4.3ga8-8.el10 binary were checked instead. On that binary, s3270 -v reported “s3270 v4.3ga8” built with gcc 14.2.1.

Debian and Ubuntu

Debian and Ubuntu split the same suite by binary name, which is closer to how people talk about the tools. On Debian 13 (trixie) the packages come from the ibm-3270 source and are version 4.3ga10-5 — the same 4.3 series as AlmaLinux 10, one upstream “ga” release later.

sudo apt install c3270 s3270 pr3287
# optional: the X11 client and its bitmap fonts
sudo apt install x3270 xfonts-x3270-misc
c3270 -v

Related packages you may also see in apt search 3270: 3270-common (shared files, including x3270if and /etc/3270/ibm_hosts), b3270, tcl3270, and fonts-3270. That last one is a modern monospaced typeface inspired by the 3270 look; it is not the bitmap font set that x3270 itself uses. Ubuntu uses the same package names. I installed c3270, s3270, pr3287 and 3270-common 4.3ga10-5 on Debian 13 and ran them for the examples below.

One packaging difference to remember: the sample hosts file is /etc/ibm_hosts on AlmaLinux, RHEL, Rocky Linux, Oracle Linux and CentOS, and /etc/3270/ibm_hosts on Debian and Ubuntu.

Building from source

Use the distribution packages unless you need a newer release than your OS ships. As of 28 July 2026, the project’s current stable source is suite3270 4.5ga6; a 4.6 alpha exists, but the stable tarball is the one to build. The Downloads page on the x3270 wiki lists the tarball, mirrors (SourceForge and bgp.nu) and a SHA-256 for 4.5ga6 of 06faf5ce883852258cc6a2a4da9fe5ce023e97d01e50625ff36f4a01ea703468.

The official Build/Linux instructions are: install a C compiler and the development libraries, run ./configure, then make. Binaries land under obj/<host-triplet>/, for example obj/x86_64-pc-linux-gnu/c3270/.

On AlmaLinux, RHEL, Rocky Linux, Oracle Linux or CentOS Stream:

sudo dnf install gcc make m4 openssl-devel readline-devel \
    ncurses-devel libXaw-devel expat-devel tcl-devel
# download suite3270-4.5ga6-src.tgz from the wiki Downloads page, then:
tar xf suite3270-4.5ga6-src.tgz
cd suite3270-4.5ga6
./configure
make

On Debian or Ubuntu the corresponding development packages are:

sudo apt install gcc make m4 libssl-dev libreadline-dev \
    libncurses-dev libxaw7-dev libexpat-dev tcl-dev
./configure
make

libXaw is required only for x3270, ncurses for c3270, expat for b3270, and tcl for tcl3270. OpenSSL is used for TLS on all of the emulators. I followed the official wiki for these steps and did not run a source build on this box.

Connecting to a host

The host name syntax is the same for x3270, c3270 and s3270:

[prefix:...][LUname@]host[:port][=accept-name]

The default port is 23 (TELNET). Many TN3270 servers also listen on 992 (the TLS “telnets” port) or on 3270. Prefixes are single letters followed by a colon, and you can stack them. The ones you will actually use:

PrefixMeaning
L:Open a TLS tunnel immediately, before TELNET negotiation. This is the usual way to reach a host that expects a secure session on 992 (or on another TLS port).
Y:Do not verify the TLS certificate. Lab use only; it overrides the default of verifying the certificate.
N:Do not negotiate TN3270E; stay at TN3270 if the host asks for TN3270E.
S:Disable the 3270 Extended Data Stream. The terminal name will not get the -E suffix unless you override it.
C:Treat the host as a CICS-style system that does not format the screen immediately, so the keyboard is not left locked waiting for a first screen.

Examples:

# Clear-text TN3270 on port 3270 (common on Hercules labs)
c3270 mvs.example.com:3270

# TLS first, then TELNET, default verify the certificate
c3270 L:tn3270.example.com:992

# Request a specific LU name
c3270 TSO1234@tn3270.example.com:992

# TLS plus a name that must appear on the certificate
c3270 'L:10.10.10.8:992=tn3270.example.com'

# Same idea with a URI (x3270 4.4 and later; 4.3 on current EL/Debian may not have this)
c3270 'tn3270s://tn3270.example.com:992'

TLS is documented on the wiki page Transport Layer Security. Two ways exist: the L: tunnel (and, starting with 4.4, port 992 implied), or a clear TCP session on which the host later asks for TELNET STARTTLS. If you know the host wants TLS, L: is faster and avoids the host’s fallback timeout. Client certificates, a custom CA file and protocol bounds are available as -certfile, -cafile / -cadir, -tlsminprotocol and -tlsmaxprotocol. -noverifycert is the command-line form of the Y: prefix; leave verification on against real systems.

Models and terminal names

A 3270 is a model with a fixed screen size. You pick the model with -model. The emulator then reports a TELNET terminal type derived from that model; the model resource page describes the mapping.

ModelSizeTypical terminal type in TN3270E
224 × 80IBM-3278-2-E
332 × 80IBM-3278-3-E
443 × 80IBM-3278-4-E
527 × 132IBM-3278-5-E

The default model in current x3270 is a color 3279 model 4 (43 × 80, extended data stream). In TN3270E the emulator reports 3279 models as 3278, so a default session presents itself as something like IBM-3278-4-E. The -E suffix means Extended Data Stream (structured fields, Query, and oversize). On 4.3, which is what AlmaLinux 10 and Debian 13 ship, you still include -E in the model string when you want that; starting with 4.4 the -E is controlled separately and is ignored if you append it to the model name.

# 24x80, a conservative choice that almost every host accepts
c3270 -model 3278-2-E mvs.example.com:3270

# Force the TELNET terminal name explicitly
c3270 -model 2 -tn IBM-3278-2-E mvs.example.com:3270

# Larger than a standard model; the terminal type becomes IBM-DYNAMIC
c3270 -model 4 -oversize 132x43 mvs.example.com:3270

If a host rejects the session or paints a broken screen, drop back to -model 3278-2-E. Some older software also objects to color 3279 model 4/5 names; x3270 already rewrites those to 3278 in TN3270E, which is the usual fix.

Keymaps and fonts

c3270 keys

c3270 is what you will use from an SSH session, so its keymap is the one that matters first. I dumped the compiled-in base keymap from c3270 4.3ga10 on Debian 13 with Show(Keymap) over the script port, in a local session that was not in 3270 mode. The important bindings:

KeyAction
F1–F12PF1–PF12
Ctrl-A, then F1–F12PF13–PF24
Ctrl-A, then 1 / 2 / 3PA1 / PA2 / PA3
Ctrl-A, then cClear
Ctrl-A, then rReset
Ctrl-A, then kOn-screen 3270 keypad
Ctrl-A, then iInsert mode on
Ctrl-A, then lRedraw
Ctrl-A, then qQuit
Ctrl-]c3270 command prompt (Escape())
Arrows, Home, DeleteCursor movement and delete

The official wiki page for the c3270 keymap and the action pages document a 3270-mode overlay as well: in 3270 mode, Clear is Ctrl-C and Reset is Ctrl-R (on x3270 they are Alt-C and the Reset action). Because the dump above was taken without a TN3270 host, I did not observe that overlay live. If F-keys do nothing, your terminal is probably not sending curses F1 through F12 — press Ctrl-A then k and use the on-screen keypad, or start c3270 with -trace and read /tmp/x3trc.<pid> to see the key names, as the wiki describes.

Custom keymaps go in ~/.c3270pro, in a session file, or in a keymap file named with -keymap. c3270 cannot see modifier keys in isolation (it is a curses program talking to a terminal), so some mappings people want on a PC keyboard, such as Right-Ctrl for Enter or Shift-Tab for BackTab, are not always possible. x3270, because it is an X11 client, has a richer keymap.

x3270 fonts

The X11 client draws a 3270-accurate display with its own bitmap fonts, not with your desktop’s monospace font. On AlmaLinux, RHEL, Rocky Linux, Oracle Linux and CentOS those fonts are in the x3270-x11 package, installed under /usr/share/fonts/x3270/ and added to the X font path through /etc/X11/fontpath.d/x3270. The fonts.dir from the AlmaLinux 10 RPM lists names such as 3270, 3270-12, 3270-20, 3270bold, 3270gt16 and 3270gt24. Select one with -efont:

x3270 -efont 3270-20 -model 3279-4-E mvs.example.com:3270

On Debian and Ubuntu, install xfonts-x3270-misc for the same kind of fonts. I listed the font files from the official AlmaLinux 10 RPM and confirmed -efont on the x3270 --help text of that binary. I did not open an interactive X11 session against a host.

How a 3270 session actually works

This is the part that surprises people who only know SSH or telnet. A 3270 is not a character-at-a-time terminal. It is a block-mode, field-oriented device. The host paints a screen full of fields and then unlocks the keyboard. You move between fields, type, and only when you press an attention key is a message sent back to the host.

  • Fields. Each field has a start attribute: protected or unprotected, alphanumeric or numeric, visible or hidden (for passwords), intensified, and so on. Tab jumps to the next unprotected field. Typing into a protected field is ignored; the keyboard may lock until you press Reset.
  • Enter is not a newline. Enter is an AID (Attention Identifier). It sends the modified fields to the host and usually locks the keyboard until the host responds with a new screen. A newline inside a field is a different operation.
  • PF and PA keys. PF1–PF24 are program function keys. ISPF, for example, uses PF3 for Exit, PF1 for Help, PF7/PF8 to scroll. PA1–PA3 are program attention keys; PA1 is often the way out of a runaway program or back to a READY prompt in TSO. These keys send only the AID, not the field data, when used as a short read.
  • Clear. Clear sends the Clear AID and blanks the screen; the host is then expected to repaint. It is not the same as the Unix Ctrl-L redraw.
  • Reset. Reset unlocks a keyboard that the emulator has locked locally (wrong key in a field, input inhibited). It does not cancel a request the host is already processing. If the operator information area shows a host wait (SYSTEM or CLOCK), wait or use the host’s attention function rather than hammering Reset.
  • The operator information area (OIA). The status line at the bottom shows connection state, 3270 versus NVT mode, TLS, insert mode, and why the keyboard is locked. Read it before assuming the session is dead.

Until the host unlocks the keyboard, keystrokes either queue or beep. That is normal. It is also why a TN3270 connection that stays in NVT (line) mode feels “wrong”: you are not actually in 3270 mode yet, so none of the field and AID behaviour applies.

A first session

On a machine with c3270 installed:

c3270 -model 3278-2-E mvs.example.com:3270

If the connection is good, you should get a formatted logo or a LOGON screen, not a stream of telnet option garbage. Tab to the user field, type, tab to the password field, and press Enter. Use the PF keys as the application tells you (the legend is usually on the screen). To leave c3270, press Ctrl-] to get the c3270> prompt and type quit, or use Ctrl-A then q.

The same host from a script, using s3270 (this is the interface behind a lot of automated 3270 tooling):

s3270 -model 3278-2-E <<'EOF'
Connect(mvs.example.com:3270)
Wait(10, InputField)
Query(TerminalName)
PrintText
Disconnect
Quit
EOF

A successful script prints status lines and then ok for each command. PrintText dumps the screen in ASCII, which is enough to confirm you reached a logon panel. I ran this style of script locally against c3270/s3270 4.3; the Connect to a public host from this writing environment did not complete 3270 negotiation, as described next.

Named hosts can go in the ibm_hosts file so you can type a short name instead of a prefix string. The file format is documented in ibm_hosts(5) and in the comments of the sample file:

# /etc/ibm_hosts  (Debian/Ubuntu: /etc/3270/ibm_hosts)
mvs  primary  mvs.example.com:3270
tsos  primary  L:tn3270.example.com:992

Testing against Hercules, TK4- or a public host

The reliable way to practice is to run a local mainframe emulator. TK4- is a ready-to-run MVS 3.8j system for the Hercules System/370 emulator; TK5 and MVS/CE are more recent community systems in the same spirit. After IPL, Hercules typically exposes TN3270 on port 3270 on the machine that runs it:

c3270 -model 3278-2-E 127.0.0.1:3270

Public TN3270 systems exist from time to time (community TK5 hosts and similar), but their names and ports change, and they are someone else’s machine: read their rules and do not treat them as a load-test target. I attempted to reach documented public demo ports from the environment used to write this article, including mainframe.hercules-390.org:3270. DNS and TCP in that environment are intercepted (every name resolved to 198.18.0.1). s3270 reported a TCP connect and then sat in TELNET negotiation with no 3270 mode and no screen data. I did not get a logon screen, and I did not IPL a local Hercules or TK4- system for this post. If you can reach a lab, the s3270 script above is the right smoke test: Wait(InputField) should succeed and PrintText should show the logo.

Troubleshooting

SymptomWhat to check
Connection refused or a hang before any screenHost, port, and path. Confirm with nc -vz host port or openssl s_client if you expected TLS. A clear-text client against a TLS-only port will hang in TELNET negotiation.
Session stays in NVT / line modeThe thing on the other end is not a TN3270 server, or you used the N: prefix, or the port is ordinary telnet. Check the OIA. Try without extra prefixes, and try port 23 versus 3270 versus 992.
TLS certificate errorUse L: and a CA the client trusts (-cafile or the system store). The =accept-name suffix or -accepthostname is for when you connect by IP but the certificate has a DNS name. Do not leave Y: / -noverifycert on for production.
Host rejects the terminal type or paints a broken screenRetry with -model 3278-2-E and, if needed, -tn IBM-3278-2-E. Disable oversize. Some applications dislike model 5 (27 × 132) or a dynamic size.
Garbled characters, especially @, brackets or national charactersWrong host code page. Set -codepage cp037 (US), cp1047, or cp1140 (US with the euro). c3270 -v lists the built-in SBCS and DBCS pages.
Keyboard locked, status shows X or SYSTEMWait for the host if it is a host lock. Use Reset (Ctrl-R or Ctrl-A r) only for a local inhibit. PA1 or Attn is the usual way to interrupt TSO.
F-keys do nothing in c3270The terminal did not send curses F-key codes. Use Ctrl-A k, fix TERM/terminfo, or add a keymap entry from a -trace capture.
Works in c3270 but not in a scripts3270 needs Wait(InputField) or Wait(3270Mode) before you type. A Connect that returns ok is only a TCP/TELNET success; the screen may not be ready.

What was tested

  • Debian 13: installed c3270, s3270, pr3287 and 3270-common 4.3ga10-5 from the official Debian repository. Ran -v and --help on all three clients. Dumped the c3270 base keymap with Show(Keymap). Ran an s3270 script session far enough to prove the script protocol works.
  • AlmaLinux 10: downloaded x3270-4.3ga8-8.el10, x3270-text-4.3ga8-8.el10 and x3270-x11-4.3ga8-8.el10 from repo.almalinux.org, listed their files, and ran the packaged s3270 -v and x3270 --help binaries.
  • Rocky Linux 8/9/10 and Oracle Linux 10 package names and versions confirmed from their official repository indexes. EPEL 9 and EPEL 10 confirmed not to ship x3270. Fedora’s package set uses the same three names (x3270, x3270-text, x3270-x11).
  • Not tested: dnf install on a live RHEL-family host, an interactive X11 x3270 session, a source build, a TLS session against a real certificate, IND$FILE file transfer, pr3287 attached to a printer LU, and a completed TN3270 logon to Hercules, TK4- or any public demo host (outbound TN3270 was not usable from the writing environment).

What is next

The next posts in this series stay on the Linux side of a mainframe shop: the integration points you actually use besides a green screen (TN3270, FTP and the JES job interface, Connect:Direct, MQ, DB2 DRDA, z/OSMF REST, SSH into Unix System Services, and Zowe CLI), a comparison of 3270 and 5250 clients, FTP to and from z/OS datasets, the differences between 3270, 5250 and VT/ANSI emulation, and the hardware and software philosophy behind RAS, channels, LPARs, and batch/JCL. After that comes a Linux on IBM Z series: installing and operating AlmaLinux, RHEL, Rocky Linux and friends on s390x, where the machine, the IPL, the devices and the network really are different from x86. Both AlmaLinux 10 and Rocky Linux 10 publish s390x ISOs and s390x ISOs; that series will start from those images.

Leave a Reply

Your email address will not be published. Required fields are marked *