Bucktooth: Serving files and directories, the gophermap file and gophertags --------------------------------------------------------------------------- The gophermap file is responsible for the look of a gopher menu. Unlike the UMN gopherd-style map files, which are somewhat cumbersome and can get rather large, Bucktooth encourages a slimline approach, or you can have none at all. This is not too secure since it will happily serve any and every file in its mountpoint to a greedy user, but if that's really what you want, congratulations. You can stop reading this now, since that's exactly what it will do when you install it with no gophermap files. Only gophermap, ., and .. are not served to the user. If you are using Bucktooth 0.2 and you turn on sorting, then the directory listing is alpha-sorted for you too. What if you want to give your files some sort of proper description instead of just their name? If you have Bucktooth 0.2 on and you enable smart linking, then you can make a symlink to the file with a nice long proper name, and both that and the original file will both point to the same place (the original file). Thus, you can make a proper menu out of any filesystem: any symbolic links in that directory will be automatically dereferenced for you into a consistent relative selector -- meaning that the name of the symlink will be used as the display string, but the selector will be what it *points to*, relative to the server's mountpoint. This lets you give your files some sort sort of meaningful descriptive text both in the filesystem and in gopherspace and yet still have the relationships between symlinks and their target files explicitly maintained. Smart linking is automatic and other than turning it on, you don't need to do anything else. This might be all some sites need for menus. --- DIVERSION, SKIP IF YOU DON'T CARE --- (Why have a feature like this? Smart linking allows you to have lots of symbolic links to directories in your mountpoint, but have the actual selectors remain consistent so that bots and smart clients traversing your content will Do The Right Thing(tm) and treat the symlinks as one resource instead of handling the symlinks as individual unique selectors unnecessarily, repetitively and separately. However, this feature is also smart enough to know that links outside of Bucktooth's mountpoint should be left alone or else the client won't be able to get to it. Because it doesn't restrict symlinks pointing outside of the server's mountpoint, you should not assume that smart linking is the equivalent of chroot()ing Bucktooth; running Bucktooth inside of a chroot()ed environment is considered beyond the scope of this manual. Smart linking doesn't mean "genius linking" either: if your file really points to a symlink of a symlink, or a symlink's symlink's symlink, etc., or resides in a directory tree that may be made up of symlinks to other directories, these kinds of indirect linkages are not resolved to cut down on execution time and complexity. This should be considered a feature; if explicitly stating this is important, forge an entry in the gophermap. Smart linking, however, is so socially advantageous in general for intelligent clients and users that it is the default.) --- END DIVERSION --- However, even smart linking isn't enough for many sites and it doesn't handle external links. This is where Bucktooth's gophermap files come in. Create or edit the gophermap file (one per directory) with any text editor and follow a few simple rules to gopher goodness. (A sample file is in stuff/ for your enjoyment.) Bucktooth sends any RFC-1436 compliant line to the client. In other words, 1gopher.floodgap.com homegopher.floodgap.com70 where , is of course, the tab (CTRL-I, 0x09) character, generates a link to "null" selector on gopher.floodgap.com 70 with an itemtype of 1 and a display string of "gopher.floodgap.com home". You don't even have to enter valid selectors, although this will not endear you much to your users. (Null selector is the same as the root of the mountpoint, by the way.) If you are not well-versed in RFC-1436, it breaks down to the first character being the itemtype (0 = text, 1 = gopher menu, 5 = zip file, 9 = generic binary, 7 = search server, I = generic image, g = gif image, h = HTML; others are also supported by some clients), then the string shown by the client up to the first tab ("display string"); then the full path to the resource ("selector"); the hostname of the server; and the port. Since it would be a major drag to always have to type things out in full, Bucktooth allows the following shortcuts: * If you don't specify a port, Bucktooth provides the one your server is using (almost always 70). * If you don't specify a host, Bucktooth provides your server's hostname. * If you only specify a relative selector and not an absolute path, Bucktooth sticks on the path they're browsing. So, if your server is gopher.somenetwork.com and your server's port is 7070, and this gophermap is inside of /lotsa, then 1Lots of stuffstuff is expanded out to 1Lots of stuff/lotsa/stuffgopher.somenetwork.com7070 If you don't specify a selector, two things can happen. Putting a at the end, like 1src explicitly tells Bucktooth you aren't specifying a selector, so Bucktooth uses your display string as the selector, adds on the host and port, and gives the client that. (If you have Bucktooth 0.2 or higher and you enable gopher globbing, then this **specific** type of gophermap entry is subject to wildcard expansion, which is highly useful. See the separate section on that.) If you enable gopher tagging, supported in Bucktooth 0.2.8 and higher, and the resource is a directory with a "gophertag" file, then the contents of that file are used as the display string instead, and the "display string" becomes the selector. This is useful for centralized resource naming. Otherwise, any lines without any characters in them are interpreted as free text descriptions and Bucktooth will give them an i itemtype to instruct the client to display them as non-interactive text. This allows you to add text descriptions to your menus (look at gopher.floodgap.com for an example). However, don't use the character anywhere in your text description or Bucktooth will try to interpret it as an RFC-1436 resource, which will yield possibly hilarious and definitely erroneous results. If you are running Bucktooth 0.2 or higher, and you make your gophermap file executable by the uid running Bucktooth, it will be treated as if it were a mole. This allows completely dynamic behaviour. See the section on moles for how executables are handled in Bucktooth. One last warning: keep display strings at 67 characters or less -- some clients may abnormally wrap them or display them in a way you didn't intend. .