III.a Creating .LINKS --------------------- The ability to make links to other hosts is how gopher distributes itself among multiple hosts. There are two different ways to make a link. The first and simplest is to create a link file that contains the data needed by the server. By default all files in the gopher data directory starting with a period (".", or perhaps in your configuration you've overriden this) are taken to be link files. A link file can contain multiple link tupless. A define a link tuple you need to put five lines in a link file that define the characteristics for the document. Here is an example of a link tuple: Name=Cheese Ball Recipes Type=1 Port=150 Path=1/Moo/Cheesy Host=zippy.micro.umn.edu The Path= line contains the selector string that the client will use to retrieve the actual document. The Port= and Host= lines tell the client where the server is which will respond to that selector string with the correct file or menu. The Name= and Type= specifications are used for display, by the client, of the link. Normally the client doesn't tell its user the values of the Path=, Port= and Host= lines. An easy way to retrieve this information is to use telnet to get the information. For instance let's say you want to link the University of Minnesota's Gopher Server to your gopher server. Just telnet to the port (like in the example above) and retrieve the information. The server returns a list in the following format: You need to keep the Object Type, Path, Host, and Port the same in the link tuple. You can change the name of the document if you want. The OpenVMS Gopher Server's .LINKS file is a two-part file. The first part is optional while the second is required (if the 2nd part is missing, the Gopher Server will effectively ignore the file). Comments in the form of null lines or lines beginning with "#" are permitted throughout and are ignored by the server. The syntax of a link file is as follows: := CR-LF := | := | "#" [] := "=" Note that no space is permitted between the keyword and "=". Continuation of extra long texts is permissable by having a '-' (hyphen) as the very last character in a long line, and a ' ' (blank) as the very first character of the next line. In this situation, the '-' will be discarded, and the next line will be appended to the long line in place of the '-'. This may continue through the maximum length of a link file line, 1024 bytes. It is probably only useful for Path= specifications which can get excessively long on occasion. Name= specifications may be continued, but it's wise to keep them shorter than 70 characters so clients are able to display them without truncation. The first part consists of one or more local Ignore and/or Access speci- fications and optionally a DName, SortDir and/or IgnoreAll specification. Access= Specifies sites which are to be denied access or explicitly granted access to *this directory*. Multiple Access specifications may be made. No defaults are defined. The for the Access specification is formatted as follows: [["!"]][,["!"]]... is the domain name or IP number of a site whose clients are to be granted or denied access. "default" may be specified to define a default set of access permissions. Specifying a site with a prefixing "." (e.g., Access=.psu.edu) specifies that any host with a name ending in ".psu.edu" should match the specification. Similarly, specifying a site in dotted decimal form with a suffixing "." (e.g., Access=128.118.) specifies that any host with an IP address starting with "128.118." should match the specification. specifies "b" for browse, "r" for read and "s" for search permissions. "!" prefixing a permission denies the access, while omitting the "!" grants the access. Note that because of this syntax, inline commentary ("!" prefixing any other text), allowed with all other configuration lines, is not allowed with an Access specification. Also note that multiple permissions can be associated with a site on a single line, if they are separated by commas or spaces, e.g. Access:.unc.edu b,r,!s. At present, only "b" is relevant, since browse access is required to secure a listing of a directory. Ignore= Specifies default *exclusion* of files by extension within this directory. Semantically, this is the same intent as the Ignore: specifications in the configuration file. This allows files not globally ignored to be ignored when building menus for the directory where this .LINKS file resides. More than one Ignore= specification may be specified; all to be specified in a given .LINKS file *must* appear before any non-comment, non Ignore= specifications, however. IgnoreAll=TRUE Specifies default *exclusion* of *all* non-.LINKS files within this directory. After processing .LINKS files (i.e., files with "." as the first character in their filename, other files in the directory are ignored. Alternatively, IgnoreAll=FALSE can be used to impose the default behavior within the directory. DName= Specifies a default Name= equivalence for documents within this directory without a lookaside file Name= specification. This offers a way to achieve the behavior of a Unix server with the "date+size" patch, by specifying DName=%fn [%ts, %sz] Note this overrides a DName: specification in the configuration file for the directory only. Only the last DName= specification encountered within one or more .LINKS files will be used. The DName= specification is ignored for documents for which the "date+size" patch is inappropriate (directories, indexes, etc.); in this case, the document name only is presented. SortDir= Specifies whether the directory should be sorted (TRUE) or not sorted (FALSE), overriding the configuration file default for SortDir: for this directory. The second part consists of one or more link tuples. A link tuple is a set of specifications describing the link. Minimum specifications are a Name=, Type=, Port=, Path=, and Host= specification; once a tuple is started, omitting any of these required specifications causes the entire tuple to be ignored. Note that the Host=, Port= and Path= specifications uniquely identify any document or resource world-wide, while the Name= and Type= specifications describe them. Order of optional versus Required link tuple entries is very important: All Optional link tuple entries must be sandwiched between the first and last Required entries or they will be ignored. A good rule of thumb is to always have Name= first and Host= last, with all other link tuple entries between them, Required or Optional. Required Link Tuple specifications: Name= Specifies the title which the client is to present for this menu item. Some clients are restricted on how much they can display, so this should be limited to about 70 characters. You may include specifications in this field to have the server include details about the file in the name as presented to clients. These specifications are of the following format: %fn - server substitutes the filename from the Path= for "%fn" (device:[directory], if any, is omitted). %pt - server substitutes the port number associated with the current link tuple. %ho - server substitutes the host name associated with the current link tuple. %ts - server substitutes the last modification time/date for "%ts". If the current year, DD-MMM HH:MM:SS is the format; if not, DD-MM-YYYY is the format. %ti - server substitutes the last modification time in HH:MM:SS format for "%ti". %dt - server substitutes the last modification date in DD-MM-YYYY format for "%dt". %sz - server substitutes the file size in bytes for "%sz". If the file size exceeds 999 bytes, it is rounded up to the nearest K (1024 bytes) and suffixed by "KB"; if 999 bytes or less, it is displayed with the text " bytes". Type= Specifies the Gopher document type, or capability. These may be any type valid at the host specified in the Host= specifica- tion. This is one-character, a letter or number. 0 means a file, 1 a directory, 7 a searchable index, 8 a Telnet session, 2 a CSO phonebook server, i for an information line and so on. Host= The Internet host where the Name= specified document or resource resides, specified as a domain name or IP number. Specifying "+" directs the server to supply its own HostAlias from the configuration file. Port= The port on the specified Host= where the document or resource is available. This is a numeric TCP/IP port number. For other hosts's Gopher servers, this is normally 70. For a Telnet session (Type=8), it is normally 23. Specifying "+" directs the server to supply its own port number (from the configuration file or, lacking that, the compiled CONF.H value of GOPHER_PORT) as the port. "+" should probably not be used when the value of Host= doesn't match the HostAlias specification in the configuration file. Path= Specifies, again, the Type= code, immediately followed by the specification string expected by the Gopher Server on the Port= and Host= specifications, to which that server will respond with the document or menu described by the Name= specification. Often this is an appropriate file specification on the Host's OS, like 1/pub/gopherdata/ for a directory on a Unix platform, or 0GOPHER_ROOT:[_data] for a directory on an OpenVMS platform. The path, if specified for a Telnet session (Type=8), generally names the presumed login to the session. The path one specifies for an index search operation (Type=7) will vary depending upon the kind of index search to be supported; see "Setting Up Searches" below. The specification of paths can get long; continuation is appropriate for them, as in: Path=1gopher_root_this_is_a_long_one:[dir1.dir2.dir3.- dir4.dir5.dir6] (note the '-' at the end of the 1st line, and the ' ' at the start of the 2nd line). Optional Link Tuple specifications: Access= Specifies sites which are to be denied access or explicitly granted access to this *item*. Multiple Access specifications may be made. No defaults are defined. The for the Access specification is formatted as follows: [["!"]][,["!"]]... is the domain name or IP number of a site whose clients are to be granted or denied access. "default" may be specified to define a default set of access permissions. Specifying a site with a prefixing "." (Access=.psu.edu) specifies that any host with a name ending in ".psu.edu" should match the specification. Similarly, specifying a site in dotted decimal form with a suffixing "." (e.g., Access=128.118.) specifies that any host with an IP address starting with "128.118." should match the specification. specifies "b" for browse, "r" for read and "s" for search permissions. "!" prefixing a permission denies the access, while omitting the "!" grants the access. Note that because of this syntax, inline commentary ("!" prefixing any other text), allowed with all other configuration lines, is not allowed with an Access specification. Denial of "b" (browse) access will suppress the item in the menu listing for the denied clients; Denial of "r" prohibits access for reading purposes (applicable only in lookaside files); Denial of "s" prohibits access for search purposes; at present no testing of suppressed search access at the link tuple level has been tested. Note that multiple permissions can be associated with a site on a single line, if they are separated by commas or spaces, e.g. Access:.unc.edu b,r,!s. Numb= Specifies the ordinal position in the menu to be offered. Items with Numb= specified are sorted into numeric order by the Numb= value an placed at the start of the menu. Items without any Numb= specification are sorted in lexical order and appear after all the items with Numb= specified. Hidden Specifies the item is not to appear in the menu under any circumstances. Since directory-wide Access specifications in the 1st part of a .LINKS file are syntactically the same as those in any document-specific link tuple specification in the 2nd part, it is a wise practice to always start each link tuple in the 2nd part with one of the *required* specifications (required entries are Name=, Type=, Port=, Path= and Host=; optional entries are Access=, Numb= and Hidden). Access= specifications that are to apply specifically to a link tuple *should* not be the first specification in a link tuple, since either the initial construction of the .LINKS file, or subsequent editing of that file, might make that link tuple the 1st one in the 2nd part, and the server will interpret the Access= specifications as members of the 1st part, thus global to the directory, not specific to the tuple as was intended. .