Skip to content

Connect and Use 3270Web

This page explains connection setup and the full Settings modal from a user perspective.

Connect to a Host

A first connection, end to end, in half a minute:

You can connect to:

  • hostname:port (example: mainframe.example.com:23)
  • IPv4:port (example: 10.0.0.5:23)
  • IPv6:port (example: [::1]:23)
  • sampleapp:<id> for bundled sample targets

While a connection is being made the Connect button reads Connecting… and is off, so a second click or Enter cannot start another one; the page says which address it is connecting to (screen readers announce it), and Cancel stops waiting. Cancel only ends the browser's wait. A host that was merely slow can still finish connecting in the background, and that unused session is closed once it has been idle long enough.

If autoconnect is enabled, 3270Web will connect automatically on startup.

Open Settings

  1. Open Settings from the account and settings menu at the right-hand end of the menu bar.
  2. Use tabs to switch sections.
  3. Edit values.
  4. Click Save settings.
  5. If a saved change needs a restart, 3270Web says so — see Restarting after a save.

You can also use:

  • Refresh to reload current values
  • Reset to defaults inside each settings section. It only changes the form: nothing is saved until you click Save settings, and the status line says so. A setting that is fixed outside the web interface is left as it is, and the status line names it.
  • Maximize for easier editing of long values

Closing Settings with Close, Esc or a click outside it, while the form holds edits you have not saved, asks Discard unsaved changes? Focus starts on Keep editing. Closing a form you have not changed, or one you have just saved, asks nothing.

Restarting after a save

Most settings apply as soon as they are saved (the App tab) or at the start of the next run (the Chaos Explorer tab). The terminal options on the Connectivity, TLS/Security and Emulation tabs are the exception: they are read once, when 3270Web starts, so a change to one needs a restart.

  • Saving without changing one of those options does not ask for a restart.
  • From the connect page, saving a change to one asks Restart 3270Web? The prompt names the settings and says that restarting ends every open terminal session, including other people's on a shared instance. Focus starts on Not now.
  • Restart now shows "Restarting 3270Web..." until the server answers again, then reloads the page.
  • From a terminal page the prompt is not offered, because restarting would end the session you are working in. The status line says the change takes effect after 3270Web next restarts.

Menu bar screenshot

  1. Session — open a connection, manage connections, connection details, reconnect, print, disconnect
  2. Terminal — find, copy, screen history, file transfer, keyboard mapping
  3. View — focus mode, hotspots, virtual keypad, theme
  4. Automation — recording, playback and exploration
  5. Tasks — run a guided business task
  6. AI chat — show or hide the AI side panel
  7. Command palette — search every action (Ctrl+K)
  8. Account and settings — settings, logs, Automation tools, about, sign out
  9. Collapse — fold the bar away for a distraction-free terminal

Automation tools are off by default

The screenshot above has Automation tools turned on, which is why callout 4 is visible. With it off — what you get on a fresh browser — the Automation menu is hidden and the bar carries only what an application user needs. Automation tools in menu 8 turns it on or off, and the choice persists per browser. See Keyboard and Controls for the full breakdown.

Settings Modal Callouts

Settings modal screenshot

  1. Refresh values
  2. Maximize/restore modal
  3. Close settings
  4. Section tabs
  5. Reset section to defaults
  6. Active section content
  7. Save settings

Settings Sections (Full)

The modal has six tabs: App, Chaos Explorer, Connectivity, TLS/Security, Emulation, and Theme.

Connectivity

Controls how 3270Web reaches the host.

Includes:

  • Port, connect timeout
  • IPv4/IPv6 preference
  • Proxy settings
  • callback/script port and socket options

Use this section when you need alternate network routing or script protocol listeners.

TLS/Security

Controls TLS certificate and protocol behavior.

Includes:

  • Certificate verification toggle
  • Min/max TLS protocol
  • Client certificate and key files
  • CA file/directory/chain
  • Accepted hostname and client certificate name

Use this when connecting to secured hosts with custom certificate requirements.

Emulation

Controls terminal identity and data representation.

Includes:

  • Terminal model (3278/3279 variants)
  • Host code page
  • Terminal/device/user identity options
  • NVT mode and oversize behavior

This section directly affects screen size, field positions, and recording reliability.

App

Controls application-level UI features.

Includes:

  • Allow log access
  • Use keypad (show virtual keypad by default, for people who have not chosen — see below)
  • Terminal Font dropdown — pick from the three bundled IBM 3270-style fonts (Regular, Semi-Condensed, Condensed). See Terminal Fonts for usage notes.

Use this section to control log visibility and default keyboard UI behavior.

Use keypad (APP_USE_KEYPAD in .env) is the instance default, and nothing more. Each person decides for their own browser with View → Virtual keypad; the browser remembers that choice and it wins over the default. The View toggle never writes to .env or to the server's environment, so one person turning the keypad on does not change what anyone else sees or what the next restart starts with. A browser that has never used the toggle, or that has cleared its site data, follows this setting. See Who decides whether the keypad is showing.

Theme

Controls the look of the terminal and surrounding UI.

Includes:

  • Theme — eleven built-in themes plus any custom themes you define: Yorkshire Mainframe Terminal (default), Authentic 3270, Amber Phosphor, Midnight Cyan, Paper Terminal, Neon Grid, and Ocean Ops, followed by the four palettes shared with the project site and the documentation sites — 3270.io Phosphor Green, 3270.io Amber CRT, 3270.io Ice and 3270.io Daylight. Picking one of those four gives the terminal the same colours as the GRN / AMB / ICE / DAY control on those sites.
  • Terminal Font — the three bundled IBM 3270-style fonts
  • A custom theme editor for authoring your own palette

Themes can also be switched straight from the command palette without opening Settings.

Chaos

Controls chaos exploration defaults.

Includes:

  • CHAOS_MAX_STEPS
  • CHAOS_TIME_BUDGET_SEC
  • CHAOS_STEP_DELAY_SEC
  • CHAOS_SEED
  • CHAOS_MAX_FIELD_LENGTH
  • CHAOS_FORCE_OVERRIDE_EXISTING_INPUTS — overwrite prefilled input fields more aggressively to maximise exploration.
  • CHAOS_SCREEN_DEDUP_SIMILARITY (default 0.95) — similarity threshold for merging near-duplicate screens in the discovery map. Higher is stricter.
  • CHAOS_LEARNED_INPUT_REUSE_BIAS (default 1.0) — weight applied to known-good input values when generating new field writes.
  • CHAOS_LEARNED_KEY_REUSE_BIAS (default 1.0) — how often the engine retries AID keys that have previously caused a transition versus exploring untried keys.
  • CHAOS_EXPORT_SUCCESS_BALANCE (default 1.0) — when exporting the chaos workflow JSON, balances steps drawn from successful transitions against exploratory steps.
  • CHAOS_OUTPUT_FILE — file name for the exported workflow JSON. Written into the chaos runs directory; any directory component is dropped. See the note in Chaos Mode.
  • CHAOS_TRANSITION_LOG_PATH — file name for a JSONL log with one line per attempt, written into the chaos runs directory. See Chaos Mode.
  • CHAOS_EXCLUDE_NO_PROGRESS_EVENTS

Use this section to tune how aggressively chaos mode explores screens and where optional output should be written. See Chaos Mode for a deeper walkthrough of the bias settings.

Settings Not Exposed in the Modal

A number of s3270 options are supported by the configuration file and environment variables but deliberately have no field in the Settings modal. Set them in webapp/WEB-INF/3270Web-config.xml or as environment variables before starting 3270Web:

Purpose Variables
Startup automation S3270_EXEC_COMMAND, S3270_LOGIN_MACRO, S3270_HTTPD, S3270_MIN_VERSION
Diagnostics/tracing S3270_TRACE, S3270_TRACE_FILE, S3270_TRACE_FILE_SIZE
Misc S3270_XRM, S3270_SET, S3270_CLEAR, S3270_UTF8, S3270_COOKIE_FILE

Use the tracing variables when troubleshooting host interaction issues, and the startup variables for scripted launch flows.

Opt-in capabilities

Four capabilities are off until an environment variable turns them on. Each one either opens a door to something outside this process or writes something that outlives the session, which is why none of them has a checkbox in the Settings modal — turning one on should be a deployment decision, made once, where the rest of the deployment is described.

Variable Default What it enables
API_TOKEN unset The whole of /api/v1. Unset, every route on it answers 503. One shared credential for one operator: with AUTH_MODE=local the instance refuses to start with it set, and clients use a token per account instead
ALLOW_SAMPLE_APPS off Letting the headless API start a bundled sample app. It is a listener this process opens on your behalf
ALLOW_SCREEN_TRACE off Screen tracing, which writes every screen the terminal draws to a file on the server — including whatever was typed into a field the host did not mark hidden
EMBED_ORIGINS unset Framing the terminal in a page on another origin, and calling the API from one. Names the exact origins; there is no wildcard. See Embedding 3270Web
DATA_DIR beside the program Where accounts, tokens, the audit trail and saved work are written. The Docker image sets /data; see Keeping the state
PR3287_PATH found on the path Where the pr3287 binary is, for printer sessions. Not a gate — the feature is available wherever the binary is, and reports that it is not where it is missing
ALLOWED_HOSTS unset Which mainframes this instance may connect to, as comma-separated globs, on every path. Unset means any host the usual validation allows — see Limiting what an instance can reach
RATE_LIMIT_CONNECT / _CHAOS / _TRANSFER / _AI / _AICONTROL 20 / 10 / 20 / 60 / 120 Requests a minute per account on the routes that cost the instance something. 0 turns one off
AUDIT_LOG_PATH audit.log beside the account store Where the audit trail is written. It is always on; this only moves it
TRUST_PROXY_HEADERS off Believing X-Forwarded-Proto, so cookies keep their Secure flag behind a proxy that terminated TLS. Only set it when a proxy really is in front of this server — the header is set by whoever sends the request
TLS_TERMINATED_UPSTREAM off Asserting that TLS is terminated in front of this server when the edge forwards no headers at all — a tunnel daemon, a sidecar. Applies to every request regardless of headers; see When the sign-in page still says the connection is not encrypted. Prefer TRUST_PROXY_HEADERS where X-Forwarded-Proto does arrive

ALLOW_LOG_ACCESS is the fifth, and it does have a Settings field — see Log Access below.

UI Conveniences

A few quality-of-life behaviours worth knowing about:

  • A collapsible menu bar — the chevron at the right-hand end folds the whole bar away and remembers the choice, so a session that needs the height can have it without leaving anything behind.
  • Required hostname input — the connect form marks the hostname field as required and announces missing-value errors to assistive tech, so it is harder to accidentally submit an empty form.
  • Saved host deletion confirmation — removing a saved host profile pops a confirmation modal; the destructive action cannot fire on a single mis-click.
  • Destructive disconnect styling — Disconnect is tagged as destructive in the Session menu so it never reads like the items above it.
  • Toast notifications — short-lived theme-aware toasts surface the result of background actions (save, export, error) without taking focus.
  • Command palette — Ctrl+K opens a searchable list of every menu and modal action, reaching controls without opening the menu they live in, plus one-key theme switching. See Command Palette.
  • Operator information area — the status bar under the terminal reports keyboard state, model, screen size and cursor position. The keyboard field is colour-coded: green when unlocked, amber when the host has locked input, red on an error condition.
  • Resizable AI chat panel — drag the panel's left edge (or focus it and use Left/Right) to change its width. The size is remembered between sessions.

Log Access

If log access is enabled in settings, you can open the Logs modal from the account and settings menu and:

  • Turn verbose logging on/off
  • Refresh logs
  • Copy/download logs
  • Clear logs

Running Behind a Reverse Proxy

When a reverse proxy terminates TLS, the hop from the proxy into 3270Web is plain HTTP. The app cannot see the browser's real scheme on its own, so session cookies would be issued without the Secure flag even though the user is browsing over HTTPS.

Set TRUST_PROXY_HEADERS=true so 3270Web reads X-Forwarded-Proto and marks its cookies Secure accordingly.

Only enable this behind a proxy you control

X-Forwarded-Proto is just a request header. If 3270Web is reachable directly, any client can set it and assert that its own plain-HTTP connection is secure. Leave this unset unless every route to the app passes through a proxy that overwrites the header.

Ensure the proxy sets the header on the way through, for example in nginx:

proxy_set_header X-Forwarded-Proto $scheme;

User Accounts

3270Web has no sign-in by default. Set AUTH_MODE=local to require one — see User Accounts and Sign-In for first-run setup, the account CLI and session lifetimes.

Secret Settings

Values 3270Web treats as secrets — currently S3270_KEY_PASSWORD and S3270_PROXY, which commonly carries credentials — are write-only. The Settings API reports whether each is set and shows ******** in place of the value; it never returns the value itself.

Saving the settings form with the mask still in the field leaves the stored secret untouched. To change one, type the new value; to remove one, clear the field.

Best Practices

  • Keep one known-good model/code page profile per host environment.
  • Apply TLS changes carefully and verify certificate paths.
  • Prefer debug playback for new recordings before running full play mode.

Connection choices

Connect opens an unsaved connection. Connection options enables TLS and per-connection LU, model and code page overrides. Save this connection opens the named personal connection editor (the Manage connections dialog) with the form already filled in. Open a connection… lists your saved connections, the bundled sample apps and a box for a typed host, and starts a session from whichever you pick. Manage connections distinguishes personal hosts from shared presets and can import and export connections. Importing old browser-saved hosts keeps the original list and does not publish hosts to other users.

If TargetHost.Value is configured, the raw address is read-only and identifies the enforced destination. Saved profile permissions continue to apply independently; arbitrary raw addresses and the quick sample are not offered in that form.