.CACHE(5)

📦 version 1.2, in nixos 26.05, nixpkgs unstable

💅 .CACHE(5) — the GoFish .cache files, explained by your fav unix bestie

okay so real talk — this is the manual page for .cache, the description files that make the GoFish gopher server work. yes, GoFish, the gopher server. gopher is vintage but it's serving and we respect it 🫶

✨ NAME ✨

.cache — description files for the GoFish gopher server, no cap.

🌸 DESCRIPTION 🌸

The GoFish gopher server uses .cache files for directory listings. A .cache file can serve as a directory page. GoFish will serve any page that resides inside the chroot jail and has read permissions for the gopher uid/gid. literally any page, it's very generous 💖

However — and this is the important part, bestie — unless the caller has prior knowledge of a file, only files specified in the .cache file will be displayed.

And here's the slay detail: the .cache file does not need to contain only the files in the current directory. Any file in gopherspace — and yes, that means external as well as internal files — can be put in the .cache. it's giving "no boundaries" energy 🔥

🦋 FILE FORMAT 🦋

The .cache file is an ascii text file. It is sent to the client as the directory listing. This means the .cache file must match the gopher spec. Here is my take on a BNF for GoFish:

<type><desc>tab[019]<path>tab<server>tab<port>

and here's the field-by-field breakdown, because you deserve to know 👑

  • tab — is the ASCII tab character as per the gopher spec
  • <type> — can be any gopher type but should match the filetype in some way
  • <desc> — is a description of the file. This field can contain any ascii text except tab
  • [019] — GoFish allowed file types. See below.
  • <pathname> — is the path for the file, rooted at the chroot jail home
  • <server> — is the server name. This does not have to be local.
  • <port> — is the port number. Usually 70.

🎀 EXAMPLE 🎀

ngl this is the part where it all clicks. look at these icons:

0Text File     0/text.txt     domain.com     70
hHTML File     0/text.html    domain.com     70
9Binary File   9/binary.tgz   domain.com     70
Iimage.gif     9/image.gif    domain.com     70
1Directory     1/asubdir/     domain.com     70

⭐ FILE TYPES ⭐

At a basic level GoFish only understands two types of file: text (0) and binary (9). Directory specifications (1) are special in the GoFish knows to concat the .cache to the end of the specification. But it is then treated as a text file.

There is a distinction between text and binary files because the gopher spec says that text files end with a period (.) on a line by itself. Binary files are sent raw. Most modern clients have no problem with sending a text file marked binary. In fact, both Netscape and IE will display the final . from a text file. However, for old clients, you should specify the text files as such.

The gopher type at the start of a line can be more expressive. This tells the client what type of file it is. For example, an html file will be processed by Netscape/IE as an html file. A binary file will popup a dialog box asking if you want to save the file. An image will be displayed if possible. ✨ main character type field, honestly ✨

🔒 FILE PERMISSIONS 🔒

okay so permissions time, pay attention 🙈

GoFish must run as root to be able to accept connections on the privileged port 70. However, it does not need to be root to serve the files. GoFish drops to a non-privileged user while opening the file. This means you can protect special files if you want. GoFish has no checking, it will serve any file that the user knows the name of.

⚠️ heads up: no checking means no checking. if a user knows the name of a file, it's getting served. protect your special files yourself, bestie 💀

💜 SEE ALSO 💜

👑 AUTHOR 👑

Written by Sean MacLennan

🐛 REPORTING BUGS 🐛

Report bugs to <headgopher@seanm.ca>.

Copyright © 2002 Sean MacLennan

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

okay that's the whole page, you ate that 🍓 this was the .cache(5) page from the GoFish manual, dated August 2002 — go forth and populate your chroot jail, periodt 💅

📦 where this page comes from