There are three file server systems currently in use by various versions of LISTSERV:
•
The VM (mainframe) version of LISTSERV continues to support the "traditional" file server system. While it is very powerful, this file server system dates back to 1986 and suffers from a few annoying limitations. In addition, it is written in a non portable language. This will be replaced eventually with the "new" file server system, currently under development.
•
The non-VM versions of LISTSERV 1.8d enhanced further the new file server system introduced in non-VM 1.8c, which included most of the functionality of the "traditional" file system. Notably, GIVE and file "packages" became available. Most end user commands continue to work as before. However, there is no guarantee that the internal data files manipulated by the file server functions will remain as before. Note that SITE.CATALOG files from versions 1.8a through 1.8c are still supported and will not need to be changed in order to work with 1.8d and later.
•
The non-VM versions of LISTSERV 1.8a and 1.8b supported a "temporary" file server system, to provide an interim solution while the new system was being developed. This temporary system supports only a subset of the functions of the traditional system. This system is no longer supported by L-Soft as it has been superseded by the new non-VM file server referenced above.
In general, the three systems are compatible, with the understanding that the temporary system does not include all the possible options. However, the mechanism for registering files (defining them to the file server system) is different.
Since the first and third systems will eventually be replaced by the second system, rather than providing an exhaustive section detailing all filelist aspects from the management side, we have provided only a basic overview of the two systems currently in the field with 15.5, with pointers to where further information may be obtained.
With the traditional system (running on the VM servers), the LISTSERV maintainer creates files called "xxxx FILELIST", which contain definitions for all the files belonging to a particular archive.
The LISTSERV maintainer stores "root-level" file definitions in a file called SITE.CATALOG, which should be placed in the same directory with the SYSTEM.CATALOG file.
2 The LISTSERV maintainer can also define "sub-catalogs" which in turn can define further files. You should be aware of the differences between VM and workstation file server functions as many people are using and will continue to use the VM file server with different conventions, and may give you incorrect advice. Non-VM sites should skip section 8.3, and use the information below in section 8.4 to maintain their file archives.
Maintaining the filelist for your archive is not difficult. It requires only that you have a working knowledge of VM XEDIT (or your local system's editor) and understand how to send files via e-mail.
to the LISTSERV host where the filelist is stored. The (CTL switch causes LISTSERV to lock the filelist until you store it again or explicitly unlock it with an
UNLOCK listname FILELIST command. (If you don't want to lock the filelist, use
(CTL NOLOCK instead.) If your mail account is not located on the same host as LISTSERV, you will need to provide your personal password (same as your password for getting and putting your lists).
A filelist retrieved with the (CTL option does not look like the filelist you get with an
INDEX command. A sample
(CTL option filelist appears below.
Notes: The filelist does not include the comment lines you would normally see at the top of an INDEX filelist; nor does it include any notebook archives. LISTSERV creates these lines dynamically at the time the INDEX command is received from a user. If the filelist you have retrieved has any of this kind of material in it, either a) you have not retrieved the filelist correctly, or b) you or someone else has stored the filelist previously with this material included. If you did a GET with (CTL, you should be able to remove these extraneous lines by simply deleting them.
If you do an INDEX of your archive and it has (for instance) two sets of comment lines or duplicate notebook archive listings, then you should GET the filelist with (CTL and edit out the offending lines. While the extra lines will not affect the operation of the file server, they are a source of potential confusion for your users.
Adding a file to a filelist is not exactly accurate terminology, although it is a widely-used phrase. Adding files to file archives is a two-step process: First, add a file descriptor to the appropriate filelist and store the filelist on the server. Second, store the file itself on the server.
To add a file descriptor, start a line with a space and then type in your file's name, access codes, five dots (periods), and then a short description, each separated by a space. For example:
Note: The line must begin with a space. Also, you must place five dots separated by spaces between the PUT file access code (here it is OWN) and the short description. These dots are place holders for the record format (recfm), logical record length (lrecl), number of records (nrecs), and the date and time of the last update. If these dots are not present, LISTSERV will return an error message when you try to store the filelist.
The line you have just added does not look like the other lines in the filelist. Ignore the "pretty" formatting. LISTSERV will reformat the information for you. After adding the line, your filelist should look like this:
You can add comment lines to the filelist by placing an asterisk in the left-most column instead of a space. Comment lines can act as indexes, descriptions, or pointers to other resources.
FACs define which users have access to files in the file archive. The FAC for GET indicates who may retrieve the files, and the FAC for
PUT indicates who may store the files on the server. (Note that some special FACs exist for "superusers" such as the LISTSERV maintainer(s) and the LISTSERV Master Coordinator, who may
GET and
PUT any file regardless of its
GET/PUT permissions.)
•
ALL – Universal access.
•
PRV – Only members of the associated mailing list have access.
•
OWN – Only the owners of the associated mailing list have access.
Note: This assumes the name of the filelist is identical to the name of the associated mailing list – for instance, MYLIST@FOO.BAR.EDU would have a
MYLIST LIST file and a
MYLIST FILELIST file. Ask your LISTSERV maintainer for assistance if this is not the case or if you need special FACs added for special user access to files.)
Warning: Before you delete file descriptors from the filelist, you should delete the files themselves from LISTSERV's archive disk. See Section 8.6
Deleting Files from the Host Machine for instructions. If this step is not followed, LISTSERV may not be able to find the file you want to delete after you edit the filelist and store it.
where XXXXXXXX is your personal password for LISTSERV on that host. Note that this is similar to the PUT command used when storing the list file.
Documented Restriction: The hierarchical listname.catalog system documented below is not available under LISTSERV Lite. You may store files on a Lite server for people to retrieve, but the files must be registered in the site.catalog file and must reside in the same directory with the *.list files so that LISTSERV can find them.
LISTSERV version 1.8c and later uses a file archive registration system similar to (but differing in important respects from) the old VM FILELIST system. This system is available on the VMS, unix, and Windows ports only. VM sites will continue to use the old FILELIST system indefinitely as it still offers more functionality than the new system.
In 1.8c a new "native" format for these entries was introduced, and the new format is used in all of the examples below. The old format remains supported for compatibility. However, note that you MUST use the old format if any of the directories in the path contains a period.
Documented Restriction: All files manipulated by LISTSERV must be accessible through LISTSERV's OS-independent file access methods. This means that files whose name contains spaces or control characters (or, under unix, upper case characters) cannot be accessed. Similarly, files whose name does not contain a period cannot be manipulated by LISTSERV. There is no limit on the length of the file name, only on its contents. Note that these "system filenames" are not visible to the end users, who refer to the files by the names assigned in the catalog.
To register a new file to the server on workstation systems, the LISTSERV maintainer adds a line to the SITE.CATALOG file. If SITE.CATALOG does not already exist (it is not shipped with the installation kits), simply open a new ASCII text file named
site.catalog in the same directory as
system.catalog and add entries to it as shown below. (Do not just add entries to
system.catalog as this file will always be overwritten during a software update.)
Note: Under Unix, LISTSERV does not observe case-sensitivity internally. Therefore you cannot define two different files with the same non-case-sensitive filename. In other words, LISTSERV will not differentiate between MY.FILE and my.file, or even My.File. But note carefully that the physical files you store must be named in lower-case; in other words, the output of an 'ls' command must show my.file, not MY.FILE or My.File. LISTSERV will handle this issue automatically when you PUT the files, but be forewarned if you store the files on the server via ftp or the Unix file system.)
The first item, MY.FILE, is the name by which the file is known to LISTSERV. That is, the users will use
GET MY.FILE to order a copy of that file. The name should contain only one period.
The second item, for instance C:\FILES\XYZ\MY.FILE, is the name LISTSERV will use for the actual disk file, in native OS format. Note that the directory must be created before you register the file. For security reasons, LISTSERV will not create the directory (or set the protections) for you. (LISTSERV will normally need full access to these files.)
•
ALL – Universal access.
•
CTL – Only the LISTSERV maintainers have access.
•
OWNER(xxx) – Only the owners of the xxx list have access.
•
SERVICE(xxx) – Only users in the service area of the xxx list have access.
•
user@host – The user in question is granted access.
Except for ALL, which must occur on its own, multiple file access code entries can be specified, separated by a comma with no intervening space. For instance:
Important: These "file access codes" apply to LISTSERV commands (GET, PUT, INDEX) only, and not to the workstation or PC's file security system. It is your responsibility to protect the actual disk file by setting the file protections for the directory in which they are created.
The sub-catalog enhancement allows the LISTSERV administrator to delegate file management authority in a controlled and secure manner. Multiple list owners can be given the authority to maintain their own sub-catalog in a predefined directory. With the LISTSERV-ISP add on (under development), a quota can be imposed on the directory in question.
If you are migrating from VM to one of the non-VM versions of LISTSERV, please note that it is not necessary to create a subcatalog file for WELCOME, FAREWELL and MAILTPL files. If a subcatalog for these files is not created, they do not appear in the output of an INDEX command. However, there are two ways to force them to appear:
To create a sub-catalog, the LISTSERV administrator edits the file called SITE.CATALOG (or site.catalog under unix) in LISTSERV's main directory (the directory where SYSTEM.CATALOG/system.catalog is located). A sub-catalog is defined as follows:
Notes: The name must end in '.CATALOG', but otherwise it can be anything. In particular, there does not need to be a list by that name.
The directory specification indicated for the catalog file (e.g., /home/lists/xyz) is where ALL the files defined in the sub-catalog will be stored. DO NOT USE LISTSERV'S MAIN (A) DIRECTORY FOR THIS PURPOSE! The catalog owner will be given FULL ACCESS to all the files in this directory, so make sure to create a new, empty directory. If the sub-catalog is being set up for a list owner, it may be a good idea to put the list archives and the sub-catalog in the same directory.
A file name must be provided for the sub-catalog file itself. This name, however, does not need to match.
This file access code controls the authority to INDEX the sub-catalog. This will also be the default GET access code for all the files registered in the sub-catalog.
This file access code defines the catalog owner(s) and default file owner(s) for all the files in the sub-catalog.
There is no need to reboot LISTSERV after updating the SITE.CATALOG file. Also, bear in mind that you are responsible for the OS-level security of the directory you create for the catalog. The file access codes in SITE.CATALOG only affect operations that go through LISTSERV; it is your responsibility to make sure that other users of the computer are given the appropriate access level to any directory you create for LISTSERV's purposes.
Once the sub-catalog is created, the catalog owner(s) can register new files using the following procedure (in this example, it will be assumed that the sub-catalog is called MY.CATALOG):
Alternatively, if the catalog owner has an account on the LISTSERV host system and write access to the directory associated with the sub-catalog, the file can be edited directly. Note however that, in that case, the LISTSERV-ISP quota system will be inoperative as it has no control over disk accesses which do not go through LISTSERV itself.
Notes: (1) This defines the name of the file as seen by LISTSERV users. That is, the command to retrieve the file will be GET MY.FILE.
(2) This defines the name of the actual disk file where the contents of MY.FILE will be stored. Normally, you should specify the same as (1), or just an equal sign (LISTSERV will then substitute the name you provided for (1)). However, in some cases you may want to make a particular file available under multiple names. This can be done by registering multiple files (ie multiple values for (1)), and using the same (2) value every time.
(3) This file access code determines who can order the file through a GET command. See Section 8.4.1
Adding Files to the SITE.CATALOG for more information on FAC codes.
(4) This file access code determines who can update the file with the PUT command. See section 8.4.1
Adding Files to the SITE.CATALOG for more information on FAC codes.
(2) defaults to the value of (1), and (3) and (4) default to the GET and PUT access codes of the sub-catalog itself, respectively. So, in most cases a sub-catalog entry will be as simple as:
MY.FILE
Additionally, comment lines (starting with an asterisk) or blank lines can be interspersed with file definitions. These comments will be echoed when the sub-catalog is indexed (see below), in sequence with the file definitions. For instance, your catalog could read:
*
* Files for the XYZ sub-project
*
XYZ.AGENDA
XYZ.BUDGET
XYZ.PROPOSAL-1
XYZ.PROPOSAL-2
then any user who matches the 'xxx' file access code is authorized to issue an INDEX MY command to get a formatted version of the catalog. For compatibility with older versions of LISTSERV, GET MY.FILELIST will produce the same results. If there is a mailing list called MY, a list of the archive files will be appended automatically.
Note: LISTSERV does not currently recognize "attachments" created by many popular mail clients as files to be stored with the
PUT command. Such files must be part of the body of the message that contains the
PUT command. This means that binary files must be stored either in 7-bit format (uuencoded, etc.) or ftp’d to the server and placed in the appropriate directory by the LISTSERV maintainer or other privileged user.
If you store binary-format files on the server, you should be careful to note in the file catalog or filelist that users who want to
GET the files will need to use an
F= modifier (e.g.,
GET BINARY.FILE F=MIME/APPL) when ordering them by email.
To store a file on any LISTSERV host, first ensure that it has been registered with an entry in a filelist or the site catalog. Then mail the file to LISTSERV with a single line at the top of the document. Follow the directions below:
(This line will not appear to people who GET the file from LISTSERV.) Replace
XXXXXXXX with your personal password. If you specify the filelist or catalog name, do not put the square brackets around the name.
•
If the file you are going to store is registered in a sub-catalog or filelist other than the sitewide one, you may have to specify the name of the sub-catalog or filelist in order to be able to store the file. This is because it is entirely possible that two lower-level filelists or catalogs may have files registered with the same name (for instance, README TXT). If LISTSERV has two sub-catalogs registered (for instance, MYLIST CATALOG and HISLIST CATALOG) that both have a file called README TXT registered, then a PUT README TXT command will tell LISTSERV to try and store the file in the first catalog it comes to in the hierarchy. If MYLIST CATALOG is registered before HISLIST CATALOG in SITE CATALOG, LISTSERV will try to store the file as if it belonged to MYLIST (which we assume is what you want). However, if HISLIST CATALOG is registered before MYLIST CATALOG (and many sites like to keep things in alphabetical order, so this is a most likely scenario), LISTSERV will try to store the file as if it belonged to HISLIST, and you will get an error stating that you aren't allowed to store the file.
5.
For VM Systems ONLY: GET the
listname FILELIST for your list and delete the line for the file you’ve just deleted.
PUT the
listname FILELIST back on the server.
6.
For Workstation and PC Systems ONLY: GET the
listname.CATALOG for your list and delete the line for the file you've just deleted.
PUT the
listname.CATALOG back on the server. Note that this is not necessarily required since under non-VM, if the physical file does not exist, LISTSERV will not include it in the output of an INDEX command. This is primarily a housekeeping measure.
AFD and FUI have not yet been ported to the workstation and PC environments. However, this feature is supported on VM and will be supported in the near future on the other platforms.
Note: If you are running LISTSERV under unix, Windows, or VMS, please skip the rest of this section as it does not pertain in any way to your implementation of LISTSERV.
These two features are similar in their command syntax, but do different things. AFD provides a method whereby users may subscribe to specific files, which will be sent to them any time the files are updated. For instance, if you have a FAQ file that is updated monthly, a user could send an AFD subscription to that FAQ file and LISTSERV would send it to the user every time you updated and stored the FAQ.
FUI, on the other hand, is a method whereby a user subscribes to a file but receives only a notification that the file has been updated. The user can then GET the file when applicable.
AFD and FUI can be password-protected to protect users from network hackers who might forge mail from the user subscribing to large or frequently-updated files. If a password is not provided in an AFD ADD or FUI ADD command, LISTSERV warns the user that it would be a good idea to password protect the subscription.
You can define a group of files as a "package" that can be retrieved by users with a single GET command. First, ensure that all the files in the package are defined in the appropriate filelist and stored on the server as detailed above.
Next, create a file descriptor in the appropriate filelist or catalog for a file called filename $PACKAGE (or
filename.$PACKAGE for non-VM), where
filename is the name you have chosen for the group of files. Be sure that the filetype or extension is
$PACKAGE, with a leading $ sign, and store your filelist.
Now create the actual filename $PACKAGE file. At the top of the file you can insert comment lines beginning with asterisks, for example:
* MYLIST $PACKAGE* Packing list for MYLIST PACKAGE
*
* You can make other comments here, such as
* the contact email address.
*
* filename filetype filelist
*==========================
•
A "compatibility" mode that works on all platforms, and which is identical to the original method used on VM (and which VM servers still must use). In the compatibility mode the basic format for the entries is
filename filetype filelist <optional_comments>
for example,
MYLIST $PACKAGE MYLIST The packing list
INTEREST FILE MYLIST Interest groups
NETIQUET FILE MYLIST How to behave
ANOTHER FILE MYLIST No commentNote: Anything that is not the name of a file in the package must be commented out with an asterisk in the left-most column of the line. It is possible to create a package file without any comment lines at all, but this is not preferable in practice. Often users will get the package file itself just to see what is in it. You should include a reference to the package file itself so that the user will get a copy of the "packing list" to check against the files he receives from LISTSERV.
Notebook archives are files in which postings to the list are stored (assuming that notebooks are enabled for the particular list). In general, they are managed automatically by LISTSERV, with certain functions left to the list owner(s). For instance, there is no need to register notebook archives in the
listname.FILELIST or
listname.CATALOG; this is taken care of automatically.
For instance, let's assume you have a list called MYLIST running on a unix server and you wish to store its archives in a directory called
/usr/listserv/home/mylist-archive. Notebooks are to be kept on a monthly basis and are to be available to anyone. Your Notebook= keyword would look like this:
Note: Only the LISTSERV maintainer may change the location of Notebook archives (or change Notebook= No to Notebook= Yes). Anyone else attempting to PUT the list header after changing these values will result in the following message being sent in response:
* Notebook= ...Error: The first two parameters of the "Notebook=" keyword may only be updated by the LISTSERV administrator.
Note: This output will appear either if an attempt is made to change "Notebook= No" to "Notebook= Yes", or if an attempt is made to change the location where notebook archives are stored on the server, by anyone who is not a LISTSERV maintainer.
If migrating old notebook archives from one LISTSERV site to another, you can simply ftp (in TEXT mode) the notebooks from the old host to the new host, put them in the directory reference in the Notebook= keyword settings, and LISTSERV will immediately recognize their presence. You can also migrate the notebooks with
GET and
PUT.
Date: Thu, 12 Mar 1998 13:24:58 -0500Sender: Test list <TEST@XXXXXX.NET>
From: Nathan Brindle <nathan@XXXXXX.NET>
Subject: Test 3
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
The last message in the archive is not followed by a separator line (in other words, the separator line is found at the beginning of each message, not at the end of each message).
(where yy = 2 digit year,
mm = 2 digit month,
w = letter A-F denoting the week of the month), place them in the directory pointed to by the Notebook= keyword for the list, and LISTSERV will index them and make them available via the web archive interface and so on.
4 In order for the web archive interface to notice new notebook files you must either
GET and
PUT the list header or restart LISTSERV.
If a list owner is planning to store archive files via the PUT method, the LISTSERV maintainer must first make dummy files with the same filenames in the list's notebook directory so that LISTSERV will not say that the file does not exist and reject the
PUT operation. However please note that you should not make entries for the notebooks in
listname.catalog (if one exists). LISTSERV makes its list of notebooks "on the fly" every time an
INDEX command is issued for the list.
•
Send a PUT command by itself (in essence, you are storing a zero-length file) via mail to LISTSERV. For instance:
LISTSERV creates the notebook archive index "on the fly" as required. If there is an existing
listname.FILELIST or
listname.CATALOG, it appends the index of notebook archives to the end of the index of other files. Otherwise, the index of notebooks is generated and sent by itself. The user simply issues the command
INDEX listname to receive the index of available files and notebooks.
