README
¶
TN3270Proxy
A TN3270 gateway: presents itself as a TN3270 server, authenticates users (passwords + optional TOTP MFA), shows a group-filtered menu of internal TN3270 services, and bridges the user to the selected service. Administration happens on the 3270 screen itself, through a built-in ISPF-style admin UI.
This project was created solely to satisfy a personal need. It is released as open source in the hope that others may find it useful.
Quick start
The fastest path is the Docker quick start — one docker compose up provisions
a demo gateway (admin account, sample users, a DEMO backend, TLS, MFA key) you
can connect to with any 3270 emulator:
c3270 127.0.0.1:2323
See the Quick Start guide. Prefer a plain binary? Grab a prebuilt release or build from source, then follow First run and Running the gateway.
Features
See the FEATURES document for a list of features.
Documentation
| Manual | Audience |
|---|---|
| Setup / Installation | Standing up a gateway: Docker quick start, building, TLS, hardening |
| Administration | Day-to-day operation: users/groups/services, MFA, audit, logging, backups |
| End-user | Connecting with a 3270 emulator: login, MFA, the menu, PF3/PA3 navigation |
Contributor-facing reference lives in docs/dev/.
Releases
Tagged releases (vX.Y.Z) publish cross-platform binaries to the GitHub
Releases page and multi-arch Docker images to ghcr.io/coffeemuse/tn3270proxy.
See Installing from a binary release.
AI Use Disclosure
This project was developed with substantial AI assistance (Anthropic's Claude Code) under a spec-driven workflow. All architecture, design decisions, and feature direction were human-conceived and human-directed; AI-generated code was reviewed, tested, and frequently revised before merging. The full development history — specifications, issues, pull requests, and commits — documents that process and is preserved in this repository. The design decisions in this project are the maintainer's own, and questions about how any part of the system works are welcome. As with all software provided under the GPLv3, this project comes with no warranty; see the LICENSE file for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
dummy3270
command
Command dummy3270 is a tiny standalone TN3270 server used as a demo and test bridge target for the gateway (point a service's host:port at its -listen address).
|
Command dummy3270 is a tiny standalone TN3270 server used as a demo and test bridge target for the gateway (point a service's host:port at its -listen address). |
|
tn3270proxy
command
Command tn3270proxy is the TN3270 gateway: it presents a TN3270 server to clients, authenticates users against a local SQLite database, shows a group-filtered menu of backend services, and bridges the chosen session.
|
Command tn3270proxy is the TN3270 gateway: it presents a TN3270 server to clients, authenticates users against a local SQLite database, shows a group-filtered menu of backend services, and bridges the chosen session. |
|
internal
|
|
|
auth
Package auth verifies credentials against the user store.
|
Package auth verifies credentials against the user store. |
|
bridge
Package bridge relays a live 3270 session between the end user's connection and a backend TN3270 host, watching for the escape AID (PA3) that returns the user to the gateway menu.
|
Package bridge relays a live 3270 session between the end user's connection and a backend TN3270 host, watching for the escape AID (PA3) that returns the user to the gateway menu. |
|
config
Package config loads the gateway's deployment configuration: which listeners to open, connection limits, logging, the database path, and the MFA master key.
|
Package config loads the gateway's deployment configuration: which listeners to open, connection limits, logging, the database path, and the MFA master key. |
|
dummy
Package dummy is a throwaway TN3270 server used as a bridge target for demos and tests.
|
Package dummy is a throwaway TN3270 server used as a bridge target for demos and tests. |
|
listen
Package listen builds the proxy's network listeners (plaintext and TLS) from configuration.
|
Package listen builds the proxy's network listeners (plaintext and TLS) from configuration. |
|
logging
Package logging provides a configurable slog-based logger for the proxy.
|
Package logging provides a configurable slog-based logger for the proxy. |
|
mfa
Package mfa provides TOTP (RFC 6238) generation/validation and AES-256-GCM encryption of TOTP secrets at rest.
|
Package mfa provides TOTP (RFC 6238) generation/validation and AES-256-GCM encryption of TOTP secrets at rest. |
|
quickstart
Package quickstart provisions a fresh data directory for the opinionated Docker quick-start: a generated admin, sample users, a demo service, an MFA key, a self-signed cert, a MOTD, and a human-readable credentials file.
|
Package quickstart provisions a fresh data directory for the opinionated Docker quick-start: a generated admin, sample users, a demo service, an MFA key, a self-signed cert, a MOTD, and a human-readable credentials file. |
|
screens
Package screens builds the go3270 screens the gateway renders to clients.
|
Package screens builds the go3270 screens the gateway renders to clients. |
|
seed
Package seed populates the store with users, groups, and services from a declarative description (used by the `seed` subcommand and tests).
|
Package seed populates the store with users, groups, and services from a declarative description (used by the `seed` subcommand and tests). |
|
server
Package server accepts TCP connections and drives each one through the gateway's session state machine: telnet/terminal negotiation, login, an optional MFA gate, the MOTD/NEWS screen, the group-filtered service menu, and finally a bridged session to a backend (internal/bridge).
|
Package server accepts TCP connections and drives each one through the gateway's session state machine: telnet/terminal negotiation, login, an optional MFA gate, the MOTD/NEWS screen, the group-filtered service menu, and finally a bridged session to a backend (internal/bridge). |
|
store
Package store owns ALL SQL in the gateway: users, groups, services, trusted networks, runtime system parameters, MFA state, and the audit trail, in one SQLite database (modernc.org/sqlite — pure Go, no cgo).
|
Package store owns ALL SQL in the gateway: users, groups, services, trusted networks, runtime system parameters, MFA state, and the audit trail, in one SQLite database (modernc.org/sqlite — pure Go, no cgo). |
|
sysconfig
Package sysconfig defines the catalog of runtime system parameters that operators can edit via the admin UI.
|
Package sysconfig defines the catalog of runtime system parameters that operators can edit via the admin UI. |
|
ui3270
Package ui3270 is the generic 3270 screen-widget engine: paginated line-command lists (RunList), labeled-input forms (RunForm), read-only snapshot lists (RunSnapshotList), and detail records (RunDetail).
|
Package ui3270 is the generic 3270 screen-widget engine: paginated line-command lists (RunList), labeled-input forms (RunForm), read-only snapshot lists (RunSnapshotList), and detail records (RunDetail). |
|
version
Package version resolves the effective version string for the binary.
|
Package version resolves the effective version string for the binary. |