''' Hey EMACS, I'm an -*-Nroff-*- file.
.bp
.NH 1
Trouble-shooting Notes
.XS
\*(SN Trouble-shooting Notes
.XE
.PP
Sometimes, Notes does not work.  Here are some hints for diagnosing
problems and recovering from them.
.NH 2
Permissions
.XS
\*(SN Permissions
.XE
.PP
The most common cause of mysterious behavior from a program in the
notesfile system is incorrect permissions.  When notes is acting up,
it is always worth the effort to carefully check all the programs,
files, and directories.  There are many ways to wreck the permissions,
but creating a file as root or moving files to a new directory are
fairly common methods.
.PP
Since notes runs setgid, the files and directories need to have the
group permissions open.  User programs should be setgid only, and
utility programs need to be setgid.  The utility programs are usually
installed both setuid and setgid, but it really doesn't matter, since
most of them refuse to proceed if they are not run by the notesfile
owner.  The network reception programs (nfrcv and newsinput) are
generally setuid and setgid.  None of the scripts need to be setgid
or setuid.
.PP
All directories in the spool area and archive area must be 0770, and
all files there must be 0660.  You could set permissions to 0775 and
0664, but there is little useful that a user can do with a raw
notesfile (besides running "du").  All files and directories should be
owned by the notesfile owner and must be owned by the notesfile group.
If in doubt, write a find to guarantee the correct permissions.
.PP
The home directory for the notesfile owner should be 0775.  The
subdirectories should be 0775 and all non-executable files should be
0660 or 0664.  Setting the files to 0664 is very handy (especially for
net.log), since it allows an administrator to inspect the notesfile
system without becoming "root" or "notes".
.PP
The binaries in LIBDIR should be 0754, with the exception of nfrcv
and newsinput which must be 0755.
.NH 2
The nfmaint Notesfile
.XS
\*(SN The nfmaint Notesfile
.XE
.PP
Problems and events in the notesfile system are logged to the
notesfile "nfmaint".  Most of the messages really are self-explanatory,
but a couple require special attention here.
.PP
The marvelous message "Failure: net.jokes" means that either newsinput
or nfrcv was unable to open the net.jokes notesfile.  This is usually
a permission problem, though it can be the result of a damaged
notesfile.  To get this message, an open has to fail on one of the
files that make up the notesfiles (ACCESS.LIST, NOTE.INDEX,
RESP.INDEX, and BODY.TEXT).  If any of the files are inaccessible or
missing, the open will fail.  The files are always opened for
read/write.
.PP
If the message claims that the errno is "Not a Teletype", then that
information is probably not relevant.  Errno is set to ENOTTY
elsewhere in the program.  Look for another cause.
.PP
Any message complaining about getnrec, putnrec, getrrec, or putrrec
probably indicates a corrupted notesfile.  These are usually an error
in an lseek() or a read().
.NH 2
Examining Headers
.XS
\*(SN Examining Headers
.XE
.PP
When you are looking at note or response in notes, the 'H' command
will show you all the headers.  The "Path:" header line will tell you
where that particular note came from.  All the headers are explained
in RFC-850, "Standard for USENET Text Messages", which is included
with the Notes documentation.
'''.NH 2
'''Verbose Messages
'''.XS
'''\*(SN Verbose Messages
'''.XE
.NH 2
Duplicates
.XS
\*(SN Duplicates
.XE
.PP
When News articles are translated to old notes format and back, it is
possible for the articles returning from oldnotes to not match the
original.  Notes 2.7 avoids this problem by not using oldnotes format
at all.  It can however exchange articles in oldnotes format with
older Notes implementations.  This will almost a always cause
duplicates.
.PP
Each article has a unique identifier.  In the B News format, this is
called the Message-ID, and looks like this: <1234.abdc@newsvax.UUCP>.
It may be an arbitrary string, but really should have the form:
.DS
\fB<\fIUnique-string\fB@\fIsystem-name\fB>\fR
.DE
In the oldnotes format, the unique identifier looks like this:
.DS
\fIsystem-name\fB:\fIlong-integer\fR
.DE
The system name must be less than 32 characters (less than 10
characters in Notes 1.3), and never has a domain.  Notes 2.7 will
truncate system names to 31 characters when sending in oldnotes
format.
.PP
If the unique-string part of the message-ID cannot be converted to an
integer, a -1 will be put into the integer and the entire message-ID
will be stored in the system-name part.  All message-ID's generated by
News 2.10.3 are of this type.
.NH 3
Domain Duplicates
.XS
\*(SN Domain Duplicates
.XE
.PP
When the domain is stripped from the system-name part to transform it
into an oldnotes system-name, information is lost.  A Message-ID made
from the notes unique ID will not match the original.  Notes 2.7
attempts to handle this.  When it check for a match between two
Message-ID's, one with a domain, and one without, it ignores the
domain in the match.
.NH 3
Truncation Duplicates
.XS
\*(SN Truncation Duplicates
.XE
.PP
If the system name is longer than 31 characters, it will be truncated.
This is more likely if the entire message-ID has to be stored in the
system-name part.  Notes 2.7 does not eliminate truncation duplicates.
.PP
If the note passes through a Notes 1.3 system, it is likely to have
garbage tacked on after the tenth character (if the system-name was 10
chars or longer).
.NH 3
-100 Duplicates
.XS
\*(SN -100 Duplicates
.XE
.PP
Previous News/Notes gateways multiplied the integer part of the
message-ID by -100 when going from News to Notes, an undid it coming
back.  Notes 2.7 never multiplies by -100, though it will undo that
multiplication.  This can cause duplicates on the oldnotes side of
things, if there are two gateways (an old and a new) talking to the
same set of notes sites.
.PP
It is possible to get an "arithmetic truncation" duplicate if the
multiplication by -100 overflowed the 32-bit signed integer.
.NH 2
Corrupted Notesfiles
.XS
\*(SN Corrupted Notesfiles
.XE
.PP
There is little that can be done about a corrupted notesfile unless
you are a real notes guru.  Generally, you should restore it from a
backup and ask a site that sends you articles to reset your sequencer
to the backup time.  It might be easier to simply get a tape of the
notesfiles from the other site rather than get them off of your own
backups.  This will work fine if you are running compatible versions
of Notes (one way to find out ...).
.PP
To tell if a notesfile is corrupted, dump it with nfdump.  If the dump
succeeds, then the notesfile is probably OK.  If it fails, you may be
able to tell where the problem is by looking at the dump.  If only one
note is bad, then a director or the notes owner can zap the offending
notesstring ('z' command on the director page).
.PP
One type of notesfile damage is very easy to fix.  If the file
ACCESS.LIST is missing or corrupt, just copy a good one from another
notesfile, and then change it to the correct permissions.
.PP
Obviously, a corrupt notesfile is a serious bug.  Please try to track
down the problem if it happens to you.
.NH 2
Problems Transferring Notes
.XS
\*(SN Problems Transferring Notes
.XE
.PP
Rnews and nfrcv can exit with one of four exit values.  A value of 0
(zero) means success, of course.  A 1 (one) means that some fatal error
occurred.  A 2 (two) means that there was no notesfile by that name,
and that none could be created.  A 3 (three) means that the incoming
news batch was in the wrong format or garbled.
.PP
An exit value larger than 128 means that a signal terminated the
program and that a core file was left.  Subtract 128 from the returned
value to find the number of the signal.  Signal numbers are documented
in signal(2).  The signal+128 encoding is the return from a wait(2)
system call.  When looking up the signal number, use the documentation
from the remote system (where the error occurred).  Signal numbers are
not the same on all Unix systems.
.PP
A message like "rnews (DENIED)" means that uuxqt is not allowed to execute
rnews.  Add it to "/usr/lib/uucp/L.cmds".
.PP
When you do run into problems receiving batches, it is very helpful to
capture batches for a while.  Later, those can be fed into rnews, perhaps
even using a debugger.  Substitute one of these scripts for /bin/rnews:
.DS
cat > /usr/spool/rnews/batch$$
tee /usr/spool/rnews/batch$$ | /usr/lib/notes/newsinput
.DE
Remember to change this back when you are done.  This can eat a lot of
disk space.
