.TH NNADMIN 1m "Release 6.6"
.\" (c) Copyright 1988, 1990, Kim F. Storm.  All rights reserved.
.UC 4
.SH NAME
nnadmin \- nn database administration
.SH SYNOPSIS
.B nnadmin
[
.I commands
]
.SH DESCRIPTION
.I nnadmin
is a control program for the \fInnmaster\fP(1M) daemon which is
responsible for building and maintaining the database used by the
\fInn\fP(1) news reader.
.LP
\fInnadmin\fP allows you to display extracts from the log file,
display the "raw" contents of the database, make consistency checks on
the database, instruct the running \fInnmaster\fP to expire one or
more groups, alter the options of the running \fInnmaster\fP, and much
more.
.LP
\fInnadmin\fP runs in two modes: interactive and non-interactive.
.LP
In interactive mode, simple one line menus are used to show the
available operations which are then selected by typing the letter
associated with the command (normally the first letter in the command
name).
.LP
In non-interactive mode, the
.I commands
argument will be used as a series of key-strokes which are interpreted
exactly as if they were typed in from the keyboard in interactive
mode.  For example, to stop the \fInnmaster\fP, the following
invocation of nnadmin can be used:
.br
	\fInnadmin\fP MK
.br
which will select the (M)aster submenu from the main menu, and then
the (K)ill entry from the submenu.
.LP
In non-interactive mode, the menus are not displayed and the commands
are not echoed!  \fInnadmin\fP will exit when there are no more
key-strokes to be read from the
.I commands
argument.  It is not possible to specify a group name in the
.I commands
argument, so the functionalities of \fInnadmin\fP that relates to
specific groups are only available in interactive mode.
.LP
Some "dangerous" commands will require that you confirm them by
following them by "Y" on the command line.  The most noteable are
IY (initialize database) and EY (expire all groups).  These commands
will be marked with a \fB[Y]\fP following the command name.
.LP
You can also invoke an interactive \fInnadmin\fP using the
.B :admin
command in \fInn\fP.
.SH SHELL ESCAPES
At all prompts you can hit `!' to spawn a subshell.
.LP
The working
directory of the subshell will be changed to the database directory
when invoked from the MASTER or DUMP menus, and it will changed to the
group's spool directory (if it exists) when invoked from the GROUP
menu.
.SH MAIN MENU
From the main menu (identified by the
.B ADMIN
prompt) you can select the following operations:
.TP
.B C)onf
.br
Show current configuration parameters such as directories, files,
programs, network usage, etc.
.TP
\fBE)xpire [Y]\fP
.br
Send a request to the \fInnmaster\fP daemon to schedule (and run)
expire for all groups in the database.
.TP
.B G)roups
.br
Enter the GROUP submenu.
.TP
\fBI)nit [Y]\fP
.br
Send a request to the \fInnmaster\fP daemon to recollect all
groups in the database.
.TP
.B L)og
.br
Enter the LOG submenu.
.TP
.B M)aster
.br
Enter the MASTER submenu.
.TP
.B Q)uit
.br
Quit \fInnadmin\fP.
.TP
.B S)tat
.br
Print general statistics about the database.  See the section on
Database Statistics below.
.TP
.B U)pdate
.br
Update the incore copy of the database master index.
.TP
.B V)alidate
.br
Make a thorough consistency check on the database.  If inconsistencies
are found in a group, you will be asked whether a request should be
sent to the \fInnmaster\fP daemon to recollect the group (in
non-interactive mode, requests will be sent automatically for all
corrupted groups).
.TP
.B W)akeup
.br
Send a wakeup signal to the \fInnmaster\fP daemon to have it receive
messages sent to it, perform the required actions, and then collect
articles as necessary.
.TP
\fBZ\fP (silent validation)
.br
This operation is identical to the Validate operation, expect that no
output is produced during the consistency check; this operation is
used by the \fInnmaster\fP to execute the \-\fBC\fP option.
.SH THE MASTER MENU
The master menu (identified by the
.B MASTER
prompt) provides access to overall database information, and to send
control messages to the \fInnmaster\fP daemon.
.TP
.B C)heck
In interactive mode and in verbose batch mode (\fInnadmin\fP MC),
print a message telling whether \fInnmaster\fP is running or not.
In silent batch mode (\fInnadmin\fP =MC) exit with a status code of 0
if \fInnmaster\fP is running and 1 otherwise; this may be useful is
administrative scripts.
.TP
.B D)ump
Enter the DUMP submenu.
.TP
.B F)iles
.br
Print a listing (using
.IR ls (1))
of all the data and index files in the database.
.TP
.B G)roup
.br
Print the master index entry for a single group identified by its
internal group number.
.TP
.B K)ill
.br
Stop the \fInnmaster\fP when it has finished its current task.
.TP
.B O)ptions
.br
Change the runtime options of the running \fInnmaster\fP daemon.
Currently, only the value of the \-r and \-e options can be modified.
.TP
.B S)tat
.br
Print general statistics about the database.  See the section on
Database Statistics below.
.TP
.B T)race
.br
Turn the trace option \-t on or off in the running \fInnmaster\fP.
.SH THE DUMP MENU
The dump menu (identified by the
.B DUMP
prompt) allows you to print the master index entry for various
selections of groups in the database.
.TP
.B A)ll
.br
Print all groups in the database.
.TP
.B E)mpty
.br
Print the empty groups in the database.
.TP
.B H)oles
Print the groups where the `min' field in the active file is not the
first article saved in the database (because it doesn't exist or
because it is ignored for some other reason, e.g. bad or old).
.TP
.B I)gnored
Print groups which are ignored, either in the GROUPS file or because
of some other condition (mainly no spool directory).
.TP
.B N)on-empty
.br
Print the non-empty groups in the database.
.TP
.B V)alid
Print the groups which are present in the active file.
.TP
.B in(W)alid
Print the groups in the database which are not present in the active
file.
.SH THE LOG MENU
The log menu (identified by the
.B LOG
prompt) enables you the extract specific entries from the log file,
and to truncate the log file.
.LP
The entries in the log file share the following format:
.sp 0.5v
	<class>: <date> <time> (<user>): <message>
.sp 0.5v
where <class> identifies the message class, the <date> and <time>
specify when the entry was made, the <user> specifies who created the
entry (the letter "M" denote the \fInnmaster\fP), and the <message> is
the text of the entry.
.LP
To extract the log file entries of a specific class, simply enter the
letter identifying the class:
.TP
.B A - admin to master communication
.br
This class of messages are related to the sending of messages from an
\fInnadmin\fP program to the \fInnmaster\fP daemon.
.TP
.B B - bad articles
Reports about bad articles which have been ignored or removed
(controlled by the \-\fBb\fP and \-\fBB\fP options to \fInnmaster\fP).
.TP
.B C - collection statistics
.br
Statistics about collection of new articles.  The message has the format:
.br
	Collect: \fInnn\fP art, \fIppp\fP gr, \fIttt\fP s
.br
meaning that
.I nnn
articles in
.I ppp
groups were collected in
.I ttt
seconds (real time).
.TP
.B E - fatal errors
.br
Fatal errors encountered during operation.  These errors require
manual intervention to be fixed (some of the fatal errors occur if
thing that "cannot happen" happens anyway, and may indicate a bug
in the software).
.TP
.B M - nnmaster messages.
.br
Master start/stop messages.
.TP
.B N - NNTP related messages
.br
Various messages related to the NNTP part of the nnmaster, mostly
about lost connections and failed attempts to connect to the NNTP
server.  These messages should only appear if you use NNTP, and your
NNTP server is down for some reason.
.TP
.B O - old articles
Reports related to ignoring (and removing) old articles when building
the database (controlled by the \-\fBO\fP and \-\fBB\fP options to
\fInnmaster\fP).
.TP
.B R - reports
.br
Non-fatal error which enables the \fInnmaster\fP to continue
operation, but may prevent a user to run \fInn\fP (file access
problems).  Reported problems should be checked.  The most common
report message will probably be
.br
	some.group: no directory
.br
which indicates that the spool directory for that group has
disappeared (most likely because it has been rmgroup'ed).
.TP
.B T - trace output
.br
Messages produced as a result of using the \-t option on the
\fInnmaster\fP.  This is primarily for debugging purposes.
.TP
.B U - usage statistics
.br
If \fInn\fP is compiled with the STATISTICS option enabled, an entry
will be made in the log file every time a user has spent more than
five minutes on news reading.  The message will have the following format:
.br
	USAGE \fIhours.minutes\fP
.br
Since it is possible to
suspend
\fInn\fP, or leave the terminal while \fInn\fP is active, \fInn\fP
tries to be intelligent when it calculates the usage time so it will
reflect the actual time spent on news reading.  The usage statistics
can be summarized using the \fInnusage\fP(1M) program.
.TP
.B V - validation errors
.br
When inconsistencies are detected in the database during validation,
an entry for each corrupted group will be entered in the log file.
.TP
.B X - expire statistics
.br
Messages similar to the Collect statistics reporting the result of
running expire on the database.  Reports related to ignoring, removing,
renumbering, and reactivation of groups are also given class X.
.LP
To extract a specific entry class,
.IR grep (1)
is used, so it may take a while on a large log file.
.LP
There are also a few special operations on the log file:
.TP
.B G)roup
.br
Extract the entries which refers to a specified group.
.TP
.B (1-9) tail
.br
Invoke
.IR tail (1)
to extract the last 10-90 entries in the log file.
.TP
\fBspace\fP
.br
Equivalent to \fB1\fP (list last 10 lines of log).
.TP
.B (.) all
.br
Display the complete log file.
.TP
.B (@) clean [Y]
.br
Move the Log file to Log.old, and create a new empty Log file.  If you
want to clean out the old log file as well, simply repeat the clean
operation (this will result in an empty Log.old file.)
.SH THE GROUP MENU
When you enter the group menu (identified by the
.B GROUP
prompt), \fInnadmin\fP will prompt you for the name of a news group,
which you can enter with the usual completion feature described in the
\fInn\fP(1) manual.  You can then perform the following operations on
the specified group:
.TP
.B C)lear_flag
.br
Clear a group specific flag.  See the section on group flags below.
.TP
.B D)ata
.br
Dump the contents of the data file containing the extracted article
headers for the group.
.TP
.B E)xpire
.br
Request the \fInnmaster\fP to run expire on the group.
.TP
.B F)iles
.br
List the files (using
.IR ls (1))
containing the index and data for the group.
.TP
.B G)roup
.br
Switch to another group.
.TP
.B H)eader
.br
Dump the master index entry for the group.
.TP
.B R)ecollect
.br
Request the \fInnmaster\fP to recollect all articles in the group.
.TP
.B S)et_flag
.br
Set a group specific flag.  See the section on group flags below.
.TP
.B V)alidate
.br
Perform validation on the group's database information.
.TP
.B Z)ap [Y]
.br
Remove group from news system - this will be done by running the
\fIrmgroup\fP program which must reside in the NEWS_LIB directory.
Of course, this should be done with great caution.
.SH INDIVIDUAL GROUP FLAGS
You can set and clear the following flags for individual groups to
control the future behaviour of \fInnmaster\fP on that group.
.LP
Notice that these flags will be reset to their default value if you
reinitialize the database using \fInnmaster\fP \-I.  To change these
flags permanently, they should be set or cleared in the GROUPS file.
.TP
.B A)lways_digest
.br
Normally, \fInnmaster\fP will only attempt to split digests into
individual articles if it can easily recognize an article as a digest.
This requires that the word "digest" appears somewhere in the subject
line, and that one of the first few lines in the body of the article
loosely matches the subject.  A few news groups frequently receives
digests which break one or both of these requirements.  To have
\fInnmaster\fP split these digests into individual articles anyway,
you can turn on the "always digest" flag on these news groups.
This will instruct \fInnmaster\fP to treat
.I all
articles in the group as digests (naturally, articles which are then
found not to contain other articles are still treated as normal articles.)
.TP
.B C)ontrol
.br
This is a special flag for the control group.  It indicates that the
"Newsgroups:" field in the article header cannot be trusted (it does
not specify the groups to which the article has been posted.)
.TP
.B D)irectory missing
.br
This flag indicates that the spool directory for the news group cannot
be found (the group has probably been removed with
.IR rmgroup (1M)).
It is set automatically be the \fInnmaster\fP if it cannot
access the directory.  When the flag is set, \fInnmaster\fP completely
ignores the group, so it can be used to disable news collection in
specific groups.  If you recreate the group or the directory
manually, you must also clear this flag to have the \fInnmaster\fP
recognize the group again.
.TP
.B M)oderated
.br
Indicates that the group is moderated.  This flag is normally
initialized automatically from the active file, and it should not be
changed lightly.
.TP
.B N)ever_digest
.br
This is the opposite of the "always digest" flag; when set, the
\fInnmaster\fP will never attempt to split any articles in that group
into subarticles.
.SH DATABASE STATISTICS DISPLAY
When you select the (S)tat operation in the main or master menus, you
will get some general statistics about the database:
.TP
initialized
.br
The time when the database was last rebuild using \fInnmaster\fP \-I.
.TP
last_scan, last_size
.br
The time stamp on the active file and its size the last time the
\fInnmaster\fP read it.
.TP
no of groups
.br
The total number of groups in the database.
.TP
Articles
.br
The total number of articles in all groups.  This is not an
exact number, because it will count split digests as a single article
(making the number too small), and it may count some articles that
have been expired (making the number too large).
.TP
Disk usage
.br
The total number of (1 kbyte) disk blocks occupied by the database.
.SH MASTER INDEX ENTRIES
The master index entries displayed when you select the (H)eader
operation in the master and group menus contain the following information:
.TP
\fIgroup_name  group_number\fP
.br
The first line of the display will show the name of the group and the
internal group number which is used to identify the group in the database.
.TP
first/last art
.br
This is the numbers of the first and last article that are currently
stored in the database.
.TP
active info
.br
This is the numbers of the first and last article in the news system
as read from the active file.  They will normally match the numbers
above, but they may differ while the \fInnmaster\fP is working on the
group (or it has not yet collected all the articles in the group).
.TP
Offsets: index->..., data->...
.br
These values show the starting position for the next write operation
on the index and data files.  They are primarily used for consistency
checking and recovery after a system crash, but after an "expire by
rewrite" operation (expire method 2) which is performed "in-situ", the
data and index files may physically be longer than the actual data
stored in them.
.TP
Flags:
.br
This shows the current flags set for this group.  If no flags are set,
the field is omitted from the display.  One extra flag which was not
explained above is the BLOCKED flag; it is a temporary locking flag
set on a group by the \fInnmaster\fP while it is updating the database
files for that group to prevent \fInn\fP clients to access that group.
.SH RAW DATABASE DISPLAY
When you select the (D)ata operation on the group menu, you will get a
combined display of the raw data and index files for that group.  The
index file contains a single 32 bit value for each existing article
number.  This value is an offset into the data file pointing to the
header for the corresponding article.
.LP
When \fInn\fP want to access the article from number N to the last
article, it looks up the offset for article number N in the index
file, and uses this as the starting point for reading article header
information in the data file.  It then simply reads to the end of the
data file in which the article headers for articles number N+1, N+2,
and so on follows immediately after the header for article number N.
.LP
The article header information is presented in a very terse form; each
of the output lines are described below for reference purposes:
.TP
offset = \fIxxxx\fP    , article # = \fInnnnn\fP   (type)
.br
This shows the offset into the data file and the article number.  The
offset is stored in the index file for quick access.  If no \fItype\fP
is printed it is a normal article.  Other types are: "digest header"
and "digest sub-article".
.TP
xpost(\fIcount\fP):  \fInnn\fP, \fInnn\fP, \fInnn\fP, ...
.br
Cross-postings to other groups are encoded as a list of internal group
numbers.
.TP
ts=\fInn\fP hp=\fInn\fP fp=\fInn\fP lp=\fInn\fP ref=\fInn\fP[+Re] lines=\fInn\fP
.br
These values are used by \fInn\fP to sort, present, and access an
article:
.br
.B ts
is the
.I time stamp
on the article; it is a simple encoding of the posting date and time
found in the Date: field.
.br
.BR hp ,
.BR fp ,
and
.B lp
are offsets into the file containing the article text: the \fIheader
position\fP, \fIfirst text position\fP, and \fIlast text position\fP.
The first will be zero for normal articles, but not for articles in a
split digest.  The last will be equal to the length of the file for
normal articles, but not inside digests.
.br
.B ref
is the number of references on the Reference: line.  If "+Re" follows
the number, the subject line contained a "Re:" prefix which has been
removed.
.TP
Sender(\fIlength\fP): \fIname\fP
.br
The name of the sender in "ready to print" format, i.e. reduced to 16
characters as explained in the \fInn\fP manual.
.TP
Subj(\fIlength\fP): \fIsubject\fP
.br
This is the full subject line from the article header (except for Re:
prefixes in various formats).
.fi
.SH FILES
The $db, $lib, and $news used below are synonyms for the DB_DIRECTORY,
LIB_DIRECTORY, and the news system's lib directories respectively.
.br
.DT
.ta \w'$db/DATA/\fInnn\fP.dx'u+3m
.\"ta 0 16
$db/MASTER	Database master index
.br
$db/GROUPS	News group names in MASTER file order
.br
$db/DATA/\fInnn\fP.x	Index file for group number \fInnn\fP
.br
$db/DATA/\fInnn\fP.d	Data file for group number \fInnn\fP
.br
$master/GATE	Message channel from \fInnadmin\fP to \fInnmaster\fP
.br
$master/MPID	The process id of the \fInnmaster\fP daemon.
.br
$Log	The log file (truncate it regularly!)
.DT
.LP
The MASTER file contains a record for each news group, occurring in
the same sequence as the group names in the GROUPS file.  The sequence
also defines the group numbers used to identify the files in the
database and in a few other places.
.LP
The GATE file will be created by \fInnadmin\fP when needed, and
removed by \fInnmaster\fP when it has read it.  Therefore, to send a
message to the \fInnmaster\fP requires that you are allowed to write
in the $master directory.
.SH SEE ALSO
nn(1), nncheck(1), nngrep(1), nntidy(1)
.br
nnquery(1M), nnusage(1M), nnmaster(8)
.SH WARNINGS
The GATE file is created with the owner and modes of the user that
runs \fInnadmin\fP which may cause problems if the owner of the
\fInnmaster\fP process (normally "news") is not allowed to read the
created GATE file (a "umask" of 022 is ok.)  Unless you allow ordinary
users to create files in the LIB directory where the GATE file
resides, only the owner of the directory (normally "news") and "root"
can use \fInnadmin\fP to send messages to the \fInnmaster\fP.
However, to send a wakeup signal to the master, anybody can run
.br
	\fInnmaster\fP \-w
.SH BUGS
The user interface is completely out of line with the rest of the
\fInn\fP family, and the way to run \fInnadmin\fP in the
non-interactive mode is a bit bizarre.  This is not likely to change,
because I believe there are more important things to do!
.SH AUTHOR
Kim F. Storm, Texas Instruments A/S, Denmark
.br
E-mail: storm@texas.dk