2.9BSD/usr/contrib/notes/doc/3

.ch "Managing Notesfiles"

	The notesfile system is installed by a user who is known as the
"owner" of the notesfiles (UIUCDCS uses user "notes").
This user can create, delete, rename, and initiate networking of notesfiles.
Each notesfile is assigned a set of "directors" (who may or may not be
associated with owner of notesfiles).  The directors have special privileges
for managing the notesfile (see below).
The "owner" rarely manages the day to day aspects of a notesfile,
although he has director, read, write and response privileges to
all notesfiles for
handling emergencies and failures.

.se "Director Options"

	The director can:

.bx
.ix
Change the access permissions.
.ix
Write the policy note.
.ix
Change the notesfile title and director message.
.ix
Open or close the notesfile.
.ix
Allow the notesfile to be networked.
.ix
Permit or restrict anonymous notes.
.ix
Compress the notesfile.
.ix
Delete notes and responses.
.ix
Toggle director message on any note or response.
.ex

	The director can delete notes or toggle the director message
above them while reading the notes.
Access other options
by typing "d" on the index page.  A display like this results:
.KS
.nf

		      Workstation Discussion
		*** Your Director Message Here ***
Anonymous: ON            Notefile: OPEN                 Networked: YES






                            Option:

		= = = = = = = = = = = = = = = = = =
.fi
.KE

	Options available on this page include:  access lists, policy
note writing, title and director messages, open/close notesfile,
network enabling, anonymous notes, notesfile compress, and delete
a list of notes.

.ss "Access Lists"

	The notesfile system allows directors to allow or restrict access
to each notesfile.
The access list can allow or deny read, write, respond, and director
options to any user, group, or system.
Type "p" ("permissions") on the director options page to enter the access list editor.
The system prompts for an option:  "m" to modify an extant entry, "d" to delete
an entry, "i" to insert a new entry, "r" to replot the list,
"q" to quit editing the access list, and capital "Q" to quit editing the
access list and IGNORE ANY CHANGES MADE.
Delete or modify entries by entry number.  Scroll the entries using "+" and
"-".
[As distributed, the list is configured for a single page of entries]
After typing "i" to insert a new entry, the system prompts for a user type
("u" for user, "g" for group, "s" for system).
The system then prompts for the name of the user, group, or system.
(Users and groups must be valid names)
The default access options
are then displayed: read, write, answer (for responses).  Use the keys
"r", "w", "a", and "d" to toggle the read, write, answer, and director
privileges respectively.  Some options automatically
enable others (e.g., "w" for writing automatically enables "a" for answering).
It is not possible to remove answer access while write access is enabled.
The "n" key will remove all privileges ("no access").
Type return (or "q") when the correct options have been entered.
The system prompts for another user.  Press return at the prompt to exercise
other access list options.

	The access machinery checks user names before checking
group names.  If user "john" explicitly has no
access but his group does, he will nevertheless be denied access to the file.
The current implementation of system access enforcement is naive.
The network software will send to a system only if it has read permission.
Reception allows intermediaries
to pass on notes even if they are not allowed write access to the notesfile;
the access permission is determined from the originating system of each note
or response.
The name "Other" (capital "O") matches any name in the class not
mentioned explicitly
(n.b.:  if you include a user named "Other", that user's access will override
all group access checks since it is checked first).

	Many notesfiles allow several users and groups to have
read/write access,
a single user to have director access, and all other users no access.

.ss "Policy Note"

	Type "w" ("write policy") on the director option page to write a policy
note (just like writing any other note though limited to a single
page).

.ss "Title and Director Messages"

	Change the notesfile title with "t", the director message with "m".
The
system prompts for a new message.
Typing only a carriage return will not change the old message.

.ss "Open/Close"

	Type "o" ("open") to toggle the availability of the notesfile (subject to
the access list).
Closed notesfiles are unavailable to non-directors.

.ss "Network Options"

	Type "n" ("network") to toggle the availability of the notesfile
for networking.
Arrangements must be made with the notesfile system "owner" to do the network
transfers.

.ss "Anonymous Notes"

	Type "a" ("anonymous") to toggle the availability of
anonymous notes in the notesfile.
The availability of the anonymous option may provoke slanderous
attacks from users
(whose anonymity is completely protected).

.ss "Compression"

	Type "c" ("compress") to compress the notesfile.  As notes
are deleted, their text and index space is not reclaimed.  This command
reclaims the space.  The notesfile must be closed.  On a VAX 11/780,
20 seconds of real time (on a slightly loaded system) is required to
reclaim the space of a notesfile with 50 remaining notes
(compression time is dependent on remaining notes).
Notesfiles should be compressed whenever many of their notes have been
deleted.
The notesfile archiver and cron(8) can be used to automate this
process.

.ss "Massive Deletions"

	Type "z" ("zap") to delete many notes (and their
responses) quickly.
Enter a list of note numbers or note ranges (aa-bb) separated by spaces.
Confirm with "y".  It is economical and prudent to compress the notesfile
shortly thereafter.
Note that deleting notes in a networked notesfile makes those notes
unavailable to those who poll your system for new notes and responses.

.ss "Director Options for Notes"

	Directors may put a "director message" above any note they write.
There is one single line director message for each notesfile.  Typical
director messages are: "New Policy", "*** This problem fixed or ignored ***",
or "-- Eat Flaming Death Fascist Pigs --".
Directors can also toggle the director message on a note being read ("d" for
"director message").  A director can delete a note (and all its
responses) or any response while reading the text of the note or response
by typing "Z" ("zap this one") and confirming with "y".

.se "Creation and Deletion of Notesfiles"

	Only the "owner" of the notesfile system can create notesfiles.
Create notesfiles with the mknf command:

	mknf [ -aon ] topic1 [ ... ]

	The created notesfiles have default status of
closed, non-networked, and
no anonymous notes permitted.
Specify -a to permit anonymous notes in the new notesfiles.
Use -o to have the notesfiles marked open for general use and
the -n option to enable the notesfiles' network availability.
These status flags can all be modified from the directors page at later
times.

	Delete notesfiles with rmnf:

	rmnf [-f] topic1 [ ... ]

Each notesfile to be removed must be verified with "y" after a
prompt -- anything else will leave that notesfile intact.
The -f option forces the removal, similar to 'rm -f'.

	The file /usr/spool/notes/.utilities/avail.notes contains
a list of the public notesfiles.
The notesfile owner should update this file when he creates
new notesfiles.
The contents of the file are up to the discretion of the
notesfile system owner.

.se "Intersystem Notesfiles"

	The notesfile system provides for intersystem notesfiles
in an arbitrary connected network.
Copies of a shared notesfile must exist on each
of the systems wishing to read notes for that notesfile.
The contents are kept in synchrony through occasional exchanges
over a network (UIUCDCS uses uucp).
Notesfiles to be shared must have their "network status" enabled (see
director options).


	Duplication of notes and responses is prevented by the use of
unique identifiers.
Each note and response in a notesfile is assigned a unique number.
The networking software checks each note as it arrives to
see if a copy already exists.
In the event of duplication, the extra copy is discarded and
the fact is logged in the statistics and the network log.

	In the (hopefully) rare event that a response arrives at a 
system before the base note does, the network reception program will
generate a "foster parent" for the orphaned response.
When the true parent arrives,
the foster parent will be overwritten.
A count of orphaned responses received is kept and available 
through use of the nfstats program (see section 4.4).

.ss "Transmitting Notesfile Updates"

	The nfxmit program gathers the new notes and responses in specified
notesfiles and sends them to a specified site.
The notesfile "owner" must occasionally enter the following command (or
have it entered for him by cron)
to update remote notesfiles with new notes and receive new remote
notes:

	nfxmit -dsitename [-tmmddyy] [-r] [-a] [-f file] topic1 [...]

The "sitename" is the name of the remote site
to receive the new notes.
The remote site should have notesfiles matching those specified
by the topic1 parameter.
For remote notesfiles with different names, see the section below on
Name Mapping.

	The optional -t specifies that all notes and responses
since that date should be sent (normally -t is omitted and the notesfile
system sends only new notes and responses).

	The -r option specifies that the remote notes system
should not only receive the current changes but also reply in kind.
This is useful if the remote system does not automatically run the
nfxmit program.

	The -a option specifies that articles inserted from the news(I) system
are to be sent also. Normally these articles are not sent because the 
receiver probably has them; the primary use of this switch is for sites
that do not run news(I).

	Using the -f switch tells nfxmit to read the file specified for a list
of notesfiles to transmit;
multiple -f parameters are permitted and can be freely intermixed
with `topic' parameters.
Notesfile name pattern matching is performed on both `topic' parameters and
the entries in a file specified by the -f option.

.ss "Network Transaction Log"

	The network software maintains a log of all transactions,
including time, date, number of notes and responses transferred, direction
of transfer,
and number of notes replicated by transfer.
This log is placed in a file called `net.log' and resides in the
notesfile utility directory (by default: /usr/spool/notes/.utilities).

.ss "Non-Standard Links"

	Some systems will be unable to keep the notesfile network
software in a public directory (such as /usr/bin).
Other sites will have non-uucp links.
The `net.how' file is for these cases.  `Net.how' is
kept in the notesfile utility
directory (/usr/spool/notes/.utilities)
and 
contains information on linking to remote systems.
Entries in the file are made for systems with non-standard links
and 
have the following format:

	system:direction:::command string

	The system field is self explanatory.
The direction field
contains either an `x' or `r' (no quotes) and specifies the direction
that the line is for. 
An `x' specifies that the command string is for sending notes to the
remote site; an `r' specifies that the command string is used in
coercing the remote system to send its new notes and responses back.

	The command string is a printf control string (without quotes)
with two `%s'
entries.
The first is for filling in the name of the notesfile, the second is
for the local system name.
Many entries in the `net.how' file will be to place
different paths on the `nfrcv' and `nfxmit' commands.
The default command line is:

	uux -z - system\\!nfrcv %s %s

for the `x' entry and for the `r' entry:

	uux system\\!nfxmit %s -d%s

A sample from the uiucdcs net.how file:

.nf
	uicsovax:x:::uux - uicsovax!/mnt/dcs/essick/.commands/nfrcv %s %s
	uicsovax:r:::uux uicsovax!/mnt/dcs/essick/.commands/nfxmit %s -d%s
.fi

A sample from the ucbcad net.how file (4.1c BSD, ethernet transmission):

.nf
ucbmonet:x:::rsh ucbmonet -l ricks /usr/local/lib/notes/nfrcv %s %s
ucbmonet:r:::rsh ucbmonet -l ricks /usr/local/lib/notes/nfxmit %s -d%s
.fi

.ss "Notesfile Name Mapping"

	To provide flexibility in the naming of notesfile across systems,
the network software looks in the
directory /usr/spool/notes/.utilities/net.aliases
for mappings of local notesfile names to remote notesfile names.
Each file in the directory is named after a system (e.g., pur-ee or uicsovax).
Each of these files contains lines which specify the mapping of local
notesfiles to the particular systems notesfiles.
Lines in the files look like:

	local_nf:remote_nf

	If there is no entry for a particular notesfile or
the file for that system is missing, the local name is used.

.se "Initial Installation and Parameters"

	Installation of the notesfile system requires
the following:

.bx
.ix
A working familiarity with version 7 UNIX
(and UUCP for intersystem transfers).
.ix
The notesfile distribution tape.
.ix
A signon for the notesfile owner.
This should be a member of the same group as the uucp signons.
.ix
The ability to write into the directories where the notesfile
binaries and data base are to live.
.ex

	Appendix A ("Notesfile Installation Checklist") is a helpful
guide for installing the notesfile system.

	First: read in the
distribution tape.
The tape is a TAR format tape. 
This will read in several directories worth of data. 
The src directory contains all source code for the notesfile
system and the internal help files.
The doc directory contains the nroff sources for the user manual and
the macros that were used to generate it, along with the man pages.
The Sample directory is a collection of various system files from our
machine;
they are included to provide examples in setting the matching files on
your system.

	After the tape has been read in, select the appropriate parameters.

.ss "Selecting Appropriate Constants"

	Go to the src directory and edit the file `parms.h'.
The parameters should be modified as follows:

.bx
.ix
"Sysname" should be the local system name. For compatibility with the
rest of the world, this should be 9 or fewer characters. (e.g., uiucdcs)
.ix
"MSTDIR" should be the directory where the notesfiles will be kept.
We use /usr/spool/notes.
.ix
"ARCHDIR" is where the archived notes are sent.
Placing ARCHDIR and MSTDIR on the same file system is not recommended
unless you have lots of disk space.
.ix
"NOTESRC" is the default ".notesrc" file name.
.ix
"ARCHTIME" is the default number of days that a note
is allowed to go unmodified
before it is eligible for archival.
Nfarchive allows this to be overridden on its command line.
.ix
"NOTESUID" is the uid of the notesfile "owner". On our system we have a 
user "notes" which owns the notesfiles.
.ix
"ANONUID" is the uid used for anonymous notes. This uid is not allowed
to run notesfiles.
We made a dummy user in our password file whose uid we set this constant
equal to. 
If you are on a PDP-11 and have no free uid slots, pick your worst enemy.
.ix
"DFLTSH" is the default shell for forking. /bin/sh will usually suffice.
The environment variable SHELL will override this for any user.
.ix
"DFLTED" is the editor that notesfiles uses for writing notes. Each user
can specify his preference by the NFED or EDITOR environment variables.
.ix
"AUTOSEQ" is the pseudonym (a la the Unix program `ln')
of the notes program
used for
automatic sequencing.
We use "autoseq".
.ix
"MAILER" defines the mail program used by notesfiles.
Because the notesfile system does not maintain the full pathname to 
remote authors, it is recommended that the 'uumail' program which
is included in the distribution be used.
.ix
"OLDGROUP" is the number of days to wait before expiring a group.
.ix
"AUTOCREATE" should be defined if you wish notes groups to be created
automatically by newsinput.
.ix
"NEWS" should be defined if your machine runs news.
.ix
"DEMANDNEWS" should be defined if you wish "newsoutput" to be forked
immediately on a submission.
.ex

	If you are running on a PDP-11 or other machine with 8 bit user
ids,
then the following line should
be added to the `parms.h' file:

.nf
#define	PDP11	1				/* running on PDP-11 */
.fi

	If you wish the notesfile system to use a prompt, you should
define the string PROMPT as follows (use any string you prefer):

.nf
#define	PROMPT	"? "				/* command prompt */
.fi

	There are several other definitions that might need to be changed.
See appendix A ("Notesfile Installation Checklist") for a list of these.

	Once these changes have been made, the next step is to update the
Makefile. The values which should be checked are:

.bx
.ix
"DESTDIR" is where the  programs 
notes, nfprint, nfstats,
and
nfpipe
are installed. We use /usr/local.
.ix 
"MSTDIR" must match the value given in `parms.h'.
.ix
"ARCHDIR" must also match the value given in `parms.h'.
.ix
"NET" is the extant directory where the notesfile networking software is kept.
This must be somewhere along the default search rule for uucp.
We use /usr/local/lib/notes.
.ix
"AUTOSEQ" is the name of the link to the notes program used for automatic
sequencing.
This must match the value given in `parms.h'.
.ix
"NOTES" is the user name of the notesfile system "owner". This should match
the NOTESUID in `parms.h'.  (e.g., NOTESUID=144, NOTES=notes)
.ix
"NOTESGRP" is the group of the notesfile "owner".
This should be the same group
as the uucp signon.
.ex

.ss "Compiling the Notesfile System"

	After all the appropriate parameters are set up, the next step is
to generate the notesfile system. First, the requisite directories and files
in /usr/local (or wherever) should be manufactured.
This procedure should be run exactly once and will probably have to be run
by the superuser.
To make these files type:

.nf
	make base
.fi

	The next phase should be run while signed in as the notesfile "owner".
Type:

.nf
	make boot
.fi

	If all goes well, this should end with a message to the effect
that the notesfile system has been installed
(Less than 10 minutes on a VAX-11/780, less than 50 minutes on an 11/60).
If anything goes wrong, perusal of the terminal dialogue should
point out the offending steps.
The most likely cause of errors will be a missing directory.

	To replace the notesfile software
any time after these two steps have been run, type:

.nf
	make install
.fi

	If at some time you are must change some of the internal constants
of the notesfile package (such as string lengths and blocking factors),
all the existing notesfiles on your system will be incompatible with the
new instantiation of the program.  

.ss "User Subroutines"

	The user subroutine "nfcomment" (which is described later) is
found in the file src/nfcomment.c.
For users to take advantage of this routine, it should be compiled 
and placed in /usr/lib (or the appropriate place on your system).

	To generate the user subroutine, type:

	make subs

	The resulting file (libnfcom.a) should then be moved to the appropriate
library (usually /usr/lib).
Users can then load this routine by specifying `-lnfcom' on 
the `cc' or `ld' command lines.

.se "Installing the man(1) Documentation"

	Install the man(1) pages for the notesfile with the following
commands. They are best done as su.

.nf
.ne 2
	cd Page
	make install
.fi

The nroff sources for the documentation will be installed in the
directory /usr/man in subdirectories man1, man3, and man8.

.se "Interfacing to News(I)"

	The notesfile system interfaces to the news(I)
program. 
The newsinput program parses the A news protocol
and inserts articles in the appropriate notesfiles.
The bnewsinput program parses the B news protocol.
The newsoutput program moves notes from the notesfile system
to the news system.
Neither program will move text between the two systems if the notesfile
is not enabled for networking (see section 3.1.5).
Newsoutput will not retransmit articles inserted by newsinput.
Sites sharing notesfiles can all run newsinput; only one of the sites
should run newsoutput for any given notesfile. 

	Before interfacing to news,
check the file `newsgate.h' to guarantee that the correct calling
sequence to insert news articles is used.

.ss "Copying News to Notesfiles"

	To have news automatically forward the articles it receives to 
the newsinput program, an entry similar to this should be made to
the /usr/spool/news/.sys file:

	nf_system:newsgroup_list::/usr/spool/notes/.utilities/newsinput

	Where "newsgroup_list" is a news(I) subscription list of the
newsgroups which have parallel notesfiles.
The above entry assumes
that you are running A news;
B news users should run bnewsinput.

.ss "Copying Notesfiles to News"

	The newsoutput program accepts a list of notesfiles as
parameters and scans them looking for new notes/responses to place into
the news(I) system. 
Newsoutput accepts two optional parameters in addition to the
list of notesfiles to send to news.

	newsoutput [ -a ] [ -f file ] topic [ ... ]

	The -a parameter specifies that notes and responses
from any system
are to be sent to news. The default is for local text only.

	The -f parameter specifies a file containing a list of 
notesfiles to send to the news system.
The preferred method of running newsoutput is with cron.
Only the "notesfile owner" is permitted to run newsoutput, so the
cron entry should have an su to the correct uid.

	Since most notesfile users will form small subnets of the larger
news network, some care must be taken as to
who uses the -a option of newsoutput.
One solution is to have a single site running news and then sharing notesfiles
with the other sites.
If more than one site runs news, things are trickier.
If all the sites run news, then they can each run both newsinput and
newsoutput without the -a option. 

	In any case, if a notesfile generated article finds its way to news 
through two different sites, a duplication in the news system
will occur which will not
cancel itself when the two meet on the same system.
Newer versions of news (release 2.7 and later)
should be flexible enough to eliminate this problem
once the news/notes gateways are modified accordingly.

.ss "Naming Notesfiles and Newsgroups"

	Newsgroup names may be longer than the fourteen characters
allowed for file names by UNIX,
although the first fourteen characters must be unique.
Notesfile names are limited to fourteen characters.
An aliasing facility is included to
convert between notesfiles and newsgroups.
The file
`/usr/spool/notes/.utilities/newsgroups'
contains the relationships of notesfiles and newsgroups. 
If the file does not exist
or 
there is no entry for the desired notesfile/newsgroup
the routine which scans that file returns the
original argument as if it had matched itself.
A typical line in the file looks like:

	notesfile_name:newsgroup

	Entries in this file need be made for only a few reasons:
(1) The newsgroup which matches the notesfile is longer than fourteen
characters,
(2) the notesfile and the newsgroup are different names
(e.g. the notesfile `Bnews' can be linked to the newsgroup `net.news.b'
with an entry of `Bnews:net.news.b'),
and
(3) you want several newsgroups linked to a single notesfile.
You can not link a single newsgroup to several notesfiles.
The file is scanned from the start until EOF or a match is found.
Several newsgroups can spool into the same
notesfile:

	somenotesfile:newsgroup1
.br
	somenotesfile:newsgroup2

	If you want newsoutput to send the notesfile-generated notes in
`somenotesfile' to both `newsgroup1' and `newsgroup2',
add the following entry BEFORE the above two entries:

	somenotesfile:newsgroup1,newsgroup2


.ss "Space Utilization"

	Since the notes system stores the entire text of a single notesfile
in a single file, a notesfile system uses less space than the
same scale news system.
The notesfile system is generally more space efficient
than B news.

.se "Housekeeping"

	When a note or response is deleted, a hole is left in
that notesfile.  This makes for quick deletion but tends to leave
disk space wasted.  The compress option on the director page is
on way that this space is reclaimed.
The nfarchive program (see section 3.6.2) also returns unused space.
Have cron run the nfarchive program weekly to automate
space reclamation.

.ss "Automatic Removal of Notes"

	The nfarchive program archives notes and groups untouched for more than
a specified number of days.
The notes and their responses are archived in `generic' notesfile
format in the archive directory specified in `parms.h'.
Each notesfile has a subdirectory in the archive directory and each time
nfarchive is run it generates a unique file
for each notesfile archived.
The notes are deleted after they have been archived. 
After the archival, a compression of the notesfile is performed to
recover the space formerly occupied by the archived notes.
Nfarchive assumes that all months have 30 days and all years have 12 months.
The format of the nfarchive command line is:

	nfarchive [-d] [-m+ or -m-] [-n] [-f file] topic

	The -d option specifies that no archiving is to take place;
the notes eligible are to be deleted.

	The -m option specifies whether to check the director message
status before archiving notes.
Use "-m+" to archive notes which meet the age requirement and have
the director message on.
The "-m-" option archives notes of sufficient age with the director
message turned off.
If this option is omitted, notes are archived on the basis of age only.

	The -n option specifies the age of eligible notes. The
increment is days.
The default is determined by the value of ARCHTIME in `parms.h' and 
is distributed as fourteen days.
The value of OLDGROUP specifies the group expiration time.

	The -f option specifies a file containing a list of notesfiles
to be archived.
Multiple -f parameters are permitted and can be intermixed with
`topic' parameters.
Notesfile name pattern matching is performed on both `topic' parameters
and the entries in a file specified by the -f option.

.ss "Additions to System Boot"

	Since the notesfile system maintains several lock files to 
ensure mutual exclusion of each notesfile, a line similar to the following
should be added to the /etc/rc file.

	rm -f /usr/spool/notes/.locks/*

	Make sure `/usr/spool/notes' matches the MSTDIR parameter in the
Makefile and the `parms.h' file. 
This line will remove any dangling locks left if the system has
crashed.