Gopher Protocol Reference
Gopher is the internet's menu system: a 1991 protocol from the University of Minnesota that predates the web's rise and still has hundreds of servers run by hobbyists. This page explains how it works on the wire and exactly how the gateway's browser speaks it.
Where the web is pages with links inside the text, Gopher is menus. Every screen is a list of items, and each item is one thing: another menu, a text file, a search, a file to download, or a telnet session. There is no layout, no styling, no scripts and no images on the page. That makes it one of the few corners of the internet that a 40-column Commodore 64 or an 80-column terminal can use completely.
The protocol is deliberately tiny. The client opens a TCP connection (port 70 by default), sends one line naming what it wants, and reads until the server closes. There are no headers, no cookies and no state between requests. Gopher+ (1993) adds, in an upward-compatible way, information about each item, alternate formats, and simple forms.
T item as a tn3270
session and says only to connect to its host and port and log in as the
selector. The gateway does that over plain telnet, without 3270
emulation, and warns on the screen first; many 3270 hosts will not work
this way. The compliance table lists each
requirement and where it stands.
Gopher lives in the gateway's text web browser; the keys are the browser's.
| Do this | Keys |
|---|---|
| Open the browser | B on the main menu |
| Go to a gopher server | G, then an address such as gopher://gopher.floodgap.com |
| Follow an item | L and its number |
| Go back | B |
| Gopher+ information on an item | I and its number; I then Enter for the whole menu |
| Fill in a Gopher+ form | opens by itself; F to return to it |
| Bookmark the page | K |
gopher://gopher.floodgap.com.
Its menu includes a search of all of Gopher, and it links to most of the
other servers still running.
Every request is a new connection, one line out, one reply back.
C: connects to host, port 70
C: selector CR LF
S: the menu, text file or binary file
S: closes the connection
The selector is an opaque string the server handed out
in an earlier menu; the empty selector asks for the server's top menu.
The client never interprets a selector: it sends back exactly what it was
given. A menu or text file ends with a line holding a single
. (the Lastline), and a binary file ends when the
server closes.
RFC 1436 says either side may close once the reply is complete. The
gateway reads until the server closes, but when a text file or menu has
ended with its . line (a dot, then CR LF, as the RFC
writes it) it waits only two more seconds, so a
server that keeps the connection open costs a moment rather than a
timeout.
Every type RFC 1436 defines, the Gopher+ additions, and the common extensions — and what the gateway does with each.
| Type | Defined by | Is | Shown as | Following it |
|---|---|---|---|---|
0 | RFC 1436 | Text file | name | Shows it; see dots. |
1 | RFC 1436 | Menu | name/ | Opens it. |
2 | RFC 1436 | CSO phone book | [CSO] | Asks a name, queries, shows each entry. |
3 | RFC 1436 | Error | ERR: text | Not followable. |
4 | RFC 1436 | BinHex (Macintosh) file | [HQX] | Shown as the text it is. |
5 | RFC 1436 | DOS binary | [BIN] | Saved to the transfer folder. |
6 | RFC 1436 | uuencoded file | [UUE] | Shown as the text it is. |
7 | RFC 1436 | Search | name? | Asks for words, shows the results menu. |
8 | RFC 1436 | Telnet session | [TEL] | Asks, then connects you; see telnet items. |
9 | RFC 1436 | Binary file | [BIN] | Saved to the transfer folder. |
+ | RFC 1436 | Redundant server | [ALT] | The item above it, on another server; see redundant servers. |
T | RFC 1436 | tn3270 session | [3270] | See telnet items. |
g | RFC 1436 | GIF image | [IMG] | Saved to the transfer folder. |
I | RFC 1436 | Other image | [IMG] | Saved to the transfer folder. |
: ; < | Gopher+ | Bitmap, movie, sound | [IMG] [MOV] [SND] | Saved to the transfer folder. |
i | extension | Information line | plain text | Not followable. |
h | extension | HTML document, or a web link (URL: selector) | name | Drawn as a web page, or the web link opened. |
s d p P | extension | Sound, document, PNG, PDF | [SND] [DOC] [IMG] [DOC] | Saved to the transfer folder. |
| anything else | — | Unknown | [???] | Shown, not followed (RFC 1436 allows ignoring or showing it). |
A saved file asks first, takes the selector's last name made safe, and is numbered rather than overwriting a file already there. It is at most 8 MB, what XMODEM, ZMODEM and Kermit can send on.
Why a server doubles some dots, and why a line can come out one dot short.
Gopher never says how long a text file is. The server ends it with a
line holding a single ., the way mail servers end a message
they pass on. That would cut the file short wherever a line of the file
itself starts with a dot, so RFC 1436 has the server add an extra
dot to every such line, and the client take it off again:
The file: On the wire: Shown:
Hello Hello Hello
.hidden ..hidden .hidden
... .... ...
. (end)
The gateway does the client's part for text files and the two text
encodings of a file (types 0, 4 and
6): it hides the closing line and takes one dot off any line
that starts with two.
Text that is not valid UTF-8 is read as ISO Latin-1, the character set
both specifications name, one line at a time; a Latin-1
é is drawn as itself. On a C64 or a 7-bit terminal
it is folded the way all internet text is.
Two item types ask the user something first.
C: selector<TAB>words CR LF
S: a menu of what matched
The browser asks Search:, sends the words after a TAB, and draws
the reply as a menu. Spaces mean and; some engines also take
and, or and not. The words stay in
the page's URL, so Back, Reload and bookmarks repeat the search.
C: query name CR LF
C: quit CR LF
S: -200:1:name: Ricky Bryce
S: -200:1:email: ...
S: 200:Ok.
A CSO item is not Gopher at all: RFC 1436 says the client must “resort to a pure CSO nameserver protocol”. The browser asks Look up:, connects to the item's host (port 105 if the menu gives none), and shows each matching entry's fields. Codes of 500 and up are errors. Lookups only: logging in and changing entries are left out.
A + item is the item above it, held on another server.
1Documents<TAB>/docs<TAB>main.example<TAB>70
+Documents<TAB>/docs<TAB>mirror.example<TAB>70
The item a + stands in for is the last one above it that
is not a +, and it is fetched as that item's type. Both are
listed, the copy marked [ALT], so either can be picked.
RFC 1436 §3.5 describes smart clients that choose at random
between cloned servers to spread the load, and move to the other when one
“seems to be down”. The gateway does the second half for
+ copies: following
any of them, it tries the others in menu order, at most three, when the server cannot be
reached — its name does not resolve, or nothing answers. A server
that answers, even with an error or a missing item, is up, and its answer
stands. This covers menus, text, searches (the copy is asked the same
words), phone books, downloads and telnet items. No more than three copies are tried,
because each one that is down can take 15 seconds to give up on.
Types 8 and T are sessions, not documents.
RFC 1436: “Connect to given host at given port. The name to login as at this host is in the selector string.” The browser shows the host and the name to log in as, asks, and hands you to the gateway's own Telnet Gateway. Pressing ESC twice leaves and returns to the menu. Port 23 is used when the menu gives none.
Every address the host name resolves to is checked against the same rule as any other fetch (see safety), and the address checked is the one dialled — the name is not looked up a second time.
T item is a session with an IBM
mainframe, which expects a 3270 block-mode terminal. It is connected over
plain telnet, and the screen says so before connecting; many 3270 hosts
do not work that way.
RFC 4266 is how a gopher item is written as an address.
gopher://host[:port]/Tselector[%09search[%09gopher+ string]]
| Part | Rule |
|---|---|
| Port | 70 when omitted. |
T | The item type. With no path at all, 1 (a menu) and the empty selector. |
| Selector | Percent-encoded. gopher://host/0/my%20file asks for my file. |
%09 search | A search's words, after an encoded TAB. |
%09 Gopher+ string | After a second TAB (the search may be empty): +, !, $, a view or ?. |
A selector is bytes, not text. RFC 4266 allows any
byte but TAB, CR and LF in one (RFC 1436 and Gopher+ also exclude
NUL; RFC 1436 says ASCII, Gopher+ any octet). The gateway keeps a selector as the exact bytes the
menu gave: a Latin-1 é is written %E9 in
the URL and sent as that one byte, so a server whose selectors are not
UTF-8 is asked for what it listed. A gopher address typed at
G, and the words typed at a search prompt, go the same way:
as the bytes the terminal sent. Bookmarks, Back and Reload keep the
whole URL, search and Gopher+ string included.
Upward-compatible extensions: item information, alternate formats and forms.
A Gopher+ server marks its items with the menu's fifth field, and a
Gopher+ request adds a TAB and a command after the selector. The gateway
sends Gopher+ requests only for items marked
+ or ?, because servers that do not speak it
vary: Floodgap and SDF ignore the extra field and send the plain reply,
and the gateway takes a reply with no Gopher+ header as the plain reply
it is.
| Request | Asks for |
|---|---|
selector<TAB>+ | The item, in its default view. |
selector<TAB>+text/plain En_US | One of its views (formats), by MIME type and language. |
selector<TAB>! | The item's attributes. |
selector<TAB>$ | The attributes of every item in a menu. |
selector<TAB>words<TAB>+ | A Gopher+ search. |
| First line | Means |
|---|---|
+5340 | Exactly 5340 bytes follow. |
+-1 | Data ends with a . line. |
+-2 | Data ends when the server closes. |
--1 … | An error. Its first token is a code: 1 not available, 2 try again later, 3 moved — followed by the menu line of where it went, which the gateway shows as a link. |
A counted reply ends the read as soon as its bytes are in, without waiting for the server to close. A download that arrives short of what its header promised is refused rather than saved as if whole.
| Block | Holds | Shown as |
|---|---|---|
+INFO | The item's menu line (always present). | The item, as a link. |
+ADMIN | Admin: who keeps it, Mod-Date: when it changed, and optional lines. | Each line; the date as YYYY-MM-DD hh:mm:ss. |
+VIEWS | The other formats it can be fetched in, with language and size. | Each a link that fetches that view; a file view is saved. |
+ABSTRACT | A short description, or a reference to one. | The text, and a link to the full one. |
+ASK | A form. | “Has a form”; see below. |
| others | Anything a server adds. | As sent. |
An item marked ? asks questions before it is fetched.
Following one fetches its attributes (!), and the form
screen opens on the questions in its +ASK block, in order.
S sends the answers.
| Line | Asks | On the form screen |
|---|---|---|
Ask: | One line of text, with an optional default after a TAB. | A text field. |
AskP: | A password. | Shown as stars. |
AskL: | Several lines. | Typed line by line, a blank line ending it (up to 50). |
AskF: | A file name to save the reply under. | A text field; the reply is saved in the transfer folder. |
Select: | A yes/no option (label:1 starts ticked). | A checkbox. |
Choose: | One of several choices, TAB-separated. | A pick list. |
ChooseF: | A local file to send. | A pick list of the transfer folder's files, nothing chosen at first. |
Note: | Nothing: text for the user. | Shown above the form. |
C: selector<TAB>+<TAB>1 CR LF
C: +N CR LF N = bytes that follow
C: one answer per line, in order
C: (an AskL: its line count, then its lines)
C: (a ChooseF: the file's bytes, last)
S: the reply, drawn as a page
Neither specification says what character set the answers are in; only
the display string is named, as ISO Latin-1. The gateway answers in the
form's own: Latin-1 when its questions came in Latin-1, UTF-8
otherwise. A letter Latin-1 lacks is sent as ?.
+ASK block, on a gopher page,
and is sent to a gopher item — so no web page can make the browser
send a file from the transfer folder. The Gopher+ spec suggests limiting
ChooseF to one directory; the gateway offers only the
transfer folder's own files.
A menu can point anywhere, so what it points at is checked.
| Rule | Why |
|---|---|
Hosts on this machine or the local network are refused, unless disable_ip_safety is on. | A menu on the internet must not be able to reach your LAN through the gateway. Every address a name resolves to is checked, and the checked address is the one connected to. |
| Control characters are stripped from everything shown, the C1 range included. | A hostile server could otherwise move the cursor or rewrite the screen. |
Pages: 512 KB, 15 seconds for the whole exchange with each server. At most three + copies are tried after a server that is down. | A server trickling bytes, or a menu listing many dead copies, cannot hold the session. |
| Files: 8 MB, 180 seconds. | What the transfer protocols can send on; time for a slow server. |
After a . line: 2 seconds more at most. | Either side may close then. |
What each specification asks of a client, and where the gateway stands.
Every client obligation in RFC 1436, RFC 4266 and the Gopher+ specification, read end to end, with the behaviours each describes as optional (marked so). All are met; the one met in part is tn3270, whose 3270 terminal is not emulated. What a server does is the server's own compliance (none of the servers measured doubles a text line's leading dot, for one).
| Spec | Requirement | Section | Status |
|---|---|---|---|
| RFC 1436 | Connect to the host and port the item names; port 70 when none is given | §2; App. (Port); RFC 4266 §2.1 | Yes |
| RFC 1436 | Send the selector, then CR LF; never modify the selector | §2 | Yes, byte for byte |
| RFC 1436 | Read a menu line: type, display string, selector, host, port; ignore further fields | §2; App. (DirEntity) | Yes; the fifth is read for Gopher+ |
| RFC 1436 | A menu ends at the . line | App. (Menu) | Yes |
| RFC 1436 | Show the user what kind of item each is | §2 | Yes: [CSO], [TEL], [IMG] and the like |
| RFC 1436 | An unknown type may be ignored or shown as unknown | §3.5 (may) | Shown as [???] |
| RFC 1436 | Stack visited locations so the user can back out | §3.5 (may) | Yes, Back |
| RFC 1436 | Choose between cloned servers, and move to one when the other seems down | §3.5 (optional) | Failover yes, in menu order, for menus, text, searches, phone books, downloads and telnet items; at most three copies; no random load balancing |
| RFC 1436 | A phone-book (2) item: speak the CSO protocol | §3.4, §3.7; App. (type 2) | Yes, lookups |
| RFC 1436 | A search: the selector, a TAB, the words; with an empty selector, the words alone | §3.7; App. (type 7) | Yes |
| RFC 1436 | Types 5 and 9: read until the server closes; the client decides what to do with the file | §3.8; App. | Yes: saved to the transfer folder |
| RFC 1436 | Type 3: an error | §3.8; App. | Shown as an ERR: line |
| RFC 1436 | Types g and I: the client decides how to display | §3.8; App. | Saved to the transfer folder |
| RFC 1436 | Display strings: a client may truncate them | §3.9 (may) | Wrapped to the screen instead |
| RFC 1436 | Do something reasonable with odd characters in text | §4(c) | Yes: control characters filtered, text folded for 7-bit and C64 screens |
| RFC 1436 | Strip the extra dot from a text line | App. (TextFile) | Yes, type 0 (and 4 and 6, also text) |
| RFC 1436 | Be prepared for no . line (the server just closes) | App. (TextFile) | Yes |
| RFC 1436 | Either side may close after the reply | App. (transactions) | Yes, 2 s after a . line |
| RFC 1436 | Telnet (8): connect to the host and port; the login is the selector | App. (type 8) | Yes |
| RFC 1436 | tn3270 (T): connect to the host and port; the login is the selector | §3.8; App. (type T) | In part: connected and logged in as the RFC says, over plain telnet with a warning; a tn3270 session's 3270 terminal is not emulated |
| RFC 1436 | A + item: a duplicate of the last non-+ item, fetched with its transaction | App. (type +) | Yes |
| RFC 1436 | 8-bit display strings are ISO Latin-1 | App. (Notes) | Read as Latin-1, and UTF-8 too |
| RFC 1436 | A selector holds no TAB, CR, LF or NUL | App. (Selector) | Yes; nothing else is changed |
| RFC 4266 | gopher://host:port/, port 70 by default; an empty path is the root menu (type 1) | §2.1 | Yes |
| RFC 4266 | A selector is octets: any but TAB, CR and LF; no character in the path is reserved | §2.1 | Yes: %XX to the byte, nothing in the path is a mark |
| RFC 4266 | A search: %09 and the words; sent as the selector, a TAB and the words | §2.2 | Yes (with an empty selector, the words alone, as RFC 1436 §3.7 says) |
| RFC 4266 | Gopher+: a second %09 and the Gopher+ string, the search possibly empty | §2.3 | Yes |
| RFC 4266 | + is the default view; ? an item with a form, its +ASK fetched and filled in | §2.4, §2.5 | Yes |
| RFC 4266 | ! an item's attributes, $ a directory's | §2.6 | Yes |
| RFC 4266 | Named attributes: !+ABSTRACT, several separated by coded spaces | §2.7 | Yes |
| RFC 4266 | A view: +view%20language | §2.8 | Yes |
| RFC 4266 | A filled-in form: the coded request, answers and all | §2.9 | Yes: the selector, TAB, +, TAB, 1, then the answers as coded |
| Gopher+ | Ignore fields beyond those expected | §2.1 | Yes |
| Gopher+ | A + (or ?) after the port marks a Gopher+ item; an old-style request still works | §2.2 | Yes: Gopher+ requests go only to marked items |
| Gopher+ | Replies: +N bytes, +-1 to a . line, +-2 to the close | §2.3 | Yes |
| Gopher+ | Errors: -, a code (1 not available, 2 try later, 3 moved, with where to), the administrator, the message | §2.3 | Yes; moved is a link |
| Gopher+ | A request: selector, TAB, +, representation, TAB, data flag, then the data block | §2.4; App. II | Yes |
| Gopher+ | A search item's Gopher+ string follows the words | §2.4 | Yes |
| Gopher+ | !: attribute blocks, + in column 1, lines starting with a space, +INFO first | §2.5; App. I | Yes |
| Gopher+ | An attribute given both by reference and explicitly: the explicit value is preferred | §2.5 | Yes: shown, the reference offered as a link |
| Gopher+ | Attribute names are case sensitive | §2.5 | Yes |
| Gopher+ | +VIEWS: the views, the server's preferred first, each with its size; the user picks one | §2.5, §2.6; App. I | Yes |
| Gopher+ | $: every item's attributes at once, named blocks optional; the client inspects what comes back | §2.7 | Yes |
| Gopher+ | +ASK: every line in order; Ask, AskP, AskL, AskF, Select, Choose, ChooseF; answers as the first lines, an AskL with its line count, one file last | §2.8 | Yes |
| Gopher+ | ChooseF: restrict the files offered | §2.8 (suggestion) | Yes: the transfer folder only |
| Gopher+ | Pictures, movies and sounds (: ; <): no default format, it comes from +VIEWS | §2.9 | Yes: fetched in the first view listed, saved with its type's extension |
| Gopher+ | A search item's attributes: selector, TAB, TAB, ! | App. II | Yes |
| Gopher+ | A selector can be longer than 255 characters | App. II (Notes) | Yes, sent whole |
| Gopher+ | A Gopher+ menu: a data head, then the items | App. II (Menu) | Yes |
As they appear on the wire (C: = the gateway, S: = the gopher server).
C: CR LF the empty selector: the top menu
S: iWelcome to the example server<TAB><TAB>error.host<TAB>1
S: 1Software<TAB>/software<TAB>example.org<TAB>70
S: 0About this server<TAB>/about.txt<TAB>example.org<TAB>70
S: 7Search the archive<TAB>/search<TAB>example.org<TAB>70
S: .
-> Welcome to the example server
Software/ [1]
About this server [2]
Search the archive? [3]
C: /search<TAB>commodore 64 CR LF
S: 0C64 memory map<TAB>/docs/c64map.txt<TAB>example.org<TAB>70
S: .
C: /about.txt<TAB>! CR LF
S: +-1
S: +INFO: 0About this server<TAB>/about.txt<TAB>example.org<TAB>70<TAB>+
S: +ADMIN:
S: Admin: Example Admin <admin@example.org>
S: Mod-Date: Mon Aug 30 17:02:01 1993 <19930830170201>
S: +VIEWS:
S: Text/plain: <2k>
S: .
C: /feedback<TAB>! CR LF
S: +-1
S: +INFO: 0Send feedback<TAB>/feedback<TAB>example.org<TAB>70<TAB>?
S: +ASK:
S: Ask: Your name?
S: Choose: Rating<TAB>Good<TAB>Bad
S: .
...the user answers "Ricky" and picks Good...
C: /feedback<TAB>+<TAB>1 CR LF
C: +13 CR LF
C: Ricky CR LF
C: Good CR LF
S: +-2
S: Thank you!
menu: 1Documents ... main.example 70
+Documents ... mirror.example 70
C: connect main.example:70 refused
C: connect mirror.example:70 answers
C: /docs CR LF
| Term | Meaning |
|---|---|
| Selector | The string a client sends to fetch an item. Opaque to the client; any bytes but TAB, CR and LF. |
| Display string | The text a menu shows for an item. |
| Item type | The one character at the start of a menu line saying what the item is. |
| Lastline | The line holding only . that ends a menu or text file. |
| Dot doubling | The server adding a . to a text line that starts with one, so it cannot be mistaken for the Lastline. |
| Gopherspace | All the gopher servers, linked by their menus. |
| Gopher+ | The 1993 upward-compatible extension: attributes, views and forms. |
| View | One of the formats a Gopher+ item can be fetched in, named by MIME type and language. |
| CSO | The Computing Services Office “ph” phone-book protocol from the University of Illinois. |
| Veronica | The classic search engine of all gopherspace; Veronica-2 runs on Floodgap. |
Deep-dive reference pages for every protocol and interface, plus the character-set tables and ANSI escape-sequence reference.
UART profiles, EGT8080, HBIOS calls, BDOS/BIOS coverage.
128-byte blocks; CRC-16 / checksum negotiation.
Block-0 metadata, batch, exact size truncation.
Streaming; ZDLE, CRC-32, autostart, resume.
Send-Init negotiation; F / A / D / Z / B transfer.
C1 dual checksum, two-phase, GOO/BAD/ACK.
Hayes command set, S-registers, +++ escape.
IAC negotiation, every option, the NVT data phase.
Server, gateway, host keys, TOFU, auth modes.
Menus, every item type, Gopher+ attributes and forms.
Hex tables for every encoding: ASCII, ANSI, PETSCII, ATASCII, Baudot/ITA2, ZX Spectrum, TRS-80.
Cursor, colour/SGR, erase, and screen-mode escape codes, with the raw hex bytes.