NAME
nnadmin - nn database administration
SYNOPSIS
nnadmin [ commands ]
DESCRIPTION
nnadmin is a control program for the nnmaster(1M) daemon
which is responsible for building and maintaining the data-
base used by the nn(1) news reader.
nnadmin 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 nnmaster to
expire one or more groups, alter the options of the running
nnmaster, and much more.
nnadmin runs in two modes: interactive and non-interactive.
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).
In non-interactive mode, the 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 nnmaster, the following invokation
of nnadmin can be used:
nnadmin MK
which will select the (M)aster submenu from the main menu,
and then the (K)ill entry from the submenu.
In non-interactive mode, the menus are not displayed and the
commands are not echoed! nnadmin will exit when there are
no more key-strokes to be read from the commands argument.
It is not possible to specify a group name in the commands
argument, so the functionalities of nnadmin that relates to
specific groups are only available in interactive mode.
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 [Y] following
the command name.
You can also invoke an interactive nnadmin using the :admin
command in nn.
SHELL ESCAPES
At all prompts you can hit `!' to spawn a subshell.
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.
MAIN MENU
From the main menu (identified by the ADMIN prompt) you can
select the following operations:
C)onf
Show current configuration parameters such as direc-
tories, files, programs, network usage, etc.
E)xpire [Y]
Send a request to the nnmaster daemon to schedule (and
run) expire for all groups in the database.
G)roups
Enter the GROUP submenu.
I)nit [Y]
Send a request to the nnmaster daemon to recollect all
groups in the database.
L)og
Enter the LOG submenu.
M)aster
Enter the MASTER submenu.
Q)uit
Quit nnadmin.
S)tat
Print general statistics about the database. See the
section on Database Statistics below.
U)pdate
Update the incore copy of the database master index.
V)alidate
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 nnmaster daemon
to recollect the group (in non-interactive mode,
requests will be sent automatically for all corrupted
groups).
W)akeup
Send a wakeup signal to the nnmaster daemon to have it
receive messages sent to it, perform the required
actions, and then collect articles as necessary.
Z (silent validation)
This operation is identical to the Validate operation,
expect that no output is produced during the con-
sistency check; this operation is used by the nnmaster
to execute the -C option.
THE MASTER MENU
The master menu (identified by the MASTER prompt) provides
access to overall database information, and to send control
messages to the nnmaster daemon.
C)heck
In interactive mode and in verbose batch mode (nnadmin
MC), print a message telling whether nnmaster is run-
ning or not. In silent batch mode (nnadmin =MC) exit
with a status code of 0 if nnmaster is running and 1
otherwise; this may be useful is administrative
scripts.
D)ump
Enter the DUMP submenu.
F)iles
Print a listing (using ls(1)) of all the data and index
files in the database.
G)roup
Print the master index entry for a single group identi-
fied by its internal group number.
K)ill
Stop the nnmaster when it has finished its current
task.
O)ptions
Change the runtime options of the running nnmaster dae-
mon. Currently, only the value of the -r and -e
options can be modified.
S)tat
Print general statistics about the database. See the
section on Database Statistics below.
T)race
Turn the trace option -t on or off in the running
nnmaster.
THE DUMP MENU
The dump menu (identified by the DUMP prompt) allows you to
print the master index entry for various selections of
groups in the database.
A)ll
Print all groups in the database.
E)mpty
Print the empty groups in the database.
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).
I)gnored
Print groups which are ignored, either in the GROUPS
file or because of some other condition (mainly no
spool directory).
N)on-empty
Print the non-empty groups in the database.
V)alid
Print the groups which are present in the active file.
in(W)alid
Print the groups in the database which are not present
in the active file.
THE LOG MENU
The log menu (identified by the LOG prompt) enables you the
extract specific entries from the log file, and to truncate
the log file.
The entries in the log file share the following format:
<class>: <date> <time> (<user>): <message>
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 nnmaster),
and the <message> is the text of the entry.
To extract the log file entries of a specific class, simply
enter the letter identifying the class:
A - admin to master communication
This class of messages are related to the sending of
messages from an nnadmin program to the nnmaster dae-
mon.
B - bad articles
Reports about bad articles which have been ignored or
removed (controlled by the -b and -B options to nnmas-
ter).
C - collection statistics
Statistics about collection of new articles. The mes-
sage has the format:
Collect: nnn art, ppp gr, ttt s
meaning that nnn articles in ppp groups were collected
in ttt seconds (real time).
E - fatal errors
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).
M - nnmaster messages.
Master start/stop messages.
N - NNTP related messages
Various messages related to the NNTP part of the nnmas-
ter, 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.
O - old articles
Reports related to ignoring (and removing) old articles
when building the database (controlled by the -O and -B
options to nnmaster).
R - reports
Non-fatal error which enables the nnmaster to continue
operation, but may prevent a user to run nn (file
access problems). Reported problems should be checked.
The most common report message will probably be
some.group: no directory
which indicates that the spool directory for that group
has disappeared (most likely because it has been
rmgroup'ed).
T - trace output
Messages produced as a result of using the -t option on
the nnmaster. This is primarily for debugging pur-
poses.
U - usage statistics
If nn 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:
USAGE hours.minutes
Since it is possible to suspend nn, or leave the termi-
nal while nn is active, nn tries to be intelligent when
it calculates the usage time so it will reflect the
actual time spent on news reading. The usage statis-
tics can be summarized using the nnusage(1M) program.
V - validation errors
When inconsistencies are detected in the database dur-
ing validation, an entry for each corrupted group will
be entered in the log file.
X - expire statistics
Messages similar to the Collect statistics reporting
the result of running expire on the database. Reports
related to ignoring, removing, renumbering, and reac-
tivation of groups are also given class X.
To extract a specific entry class, grep(1) is used, so it
may take a while on a large log file.
There are also a few special operations on the log file:
G)roup
Extract the entries which refers to a specified group.
(1-9) tail
Invoke tail(1) to extract the last 10-90 entries in the
log file.
space
Equivalent to 1 (list last 10 lines of log).
(.) all
Display the complete log file.
(@) clean [Y]
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.)
THE GROUP MENU
When you enter the group menu (identified by the GROUP
prompt), nnadmin will prompt you for the name of a news
group, which you can enter with the usual completion feature
described in the nn(1) manual. You can then perform the
following operations on the specified group:
C)lear_flag
Clear a group specific flag. See the section on group
flags below.
D)ata
Dump the contents of the data file containing the
extracted article headers for the group.
E)xpire
Request the nnmaster to run expire on the group.
F)iles
List the files (using ls(1)) containing the index and
data for the group.
G)roup
Switch to another group.
H)eader
Dump the master index entry for the group.
R)ecollect
Request the nnmaster to recollect all articles in the
group.
S)et_flag
Set a group specific flag. See the section on group
flags below.
V)alidate
Perform validation on the group's database information.
Z)ap [Y]
Remove group from news system - this will be done by
running the rmgroup program which must reside in the
NEWS_LIB directory. Of course, this should be done
with great caution.
INDIVIDUAL GROUP FLAGS
You can set and clear the following flags for individual
groups to control the future behaviour of nnmaster on that
group.
Notice that these flags will be reset to their default value
if you reinitialize the database using nnmaster -I. To
change these flags permanently, they should be set or
cleared in the GROUPS file.
A)lways_digest
Normally, nnmaster will only attempt to split digests
into individual articles if it can easily recognize an
article as a digest. This requires that the word "dig-
est" 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 fre-
quently receives digests which break one or both of
these requirements. To have nnmaster split these dig-
ests into individual articles anyway, you can turn on
the "always digest" flag on these news groups. This
will instruct nnmaster to treat all articles in the
group as digests (naturally, articles which are then
found not to contain other articles are still treated
as normal articles.)
C)ontrol
This is a special flag for the control group. It indi-
cates that the "Newsgroups:" field in the article
header cannot be trusted (it does not specify the
groups to which the article has been posted.)
D)irectory missing
This flag indicates that the spool directory for the
news group cannot be found (the group has probably been
removed with rmgroup(1M)). It is set automatically be
the nnmaster if it cannot access the directory. When
the flag is set, nnmaster 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 nnmaster recognize the group again.
M)oderated
Indicates that the group is moderated. This flag is
normally initialized automatically from the active
file, and it should not be changed lightly.
N)ever_digest
This is the opposite of the "always digest" flag; when
set, the nnmaster will never attempt to split any arti-
cles in that group into subarticles.
DATABASE STATISTICS DISPLAY
When you select the (S)tat operation in the main or master
menus, you will get some general statistics about the data-
base:
initialized
The time when the database was last rebuild using
nnmaster -I.
last_scan, last_size
The time stamp on the active file and its size the last
time the nnmaster read it.
no of groups
The total number of groups in the database.
Articles
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).
Disk usage
The total number of (1 kbyte) disk blocks occupied by
the database.
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:
group_name group_number
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.
first/last art
This is the numbers of the first and last article that
are currently stored in the database.
active info
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 nnmaster is working on the group (or
it has not yet collected all the articles in the
group).
Offsets: index->..., data->...
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.
Flags:
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 nnmaster while it is updating the database
files for that group to prevent nn clients to access
that group.
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.
When nn 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.
The article header information is presented in a very terse
form; each of the output lines are described below for
reference purposes:
offset = xxxx , article # = nnnnn (type)
This shows the offset into the data file and the arti-
cle number. The offset is stored in the index file for
quick access. If no type is printed it is a normal
article. Other types are: "digest header" and "digest
sub-article".
xpost(count): nnn, nnn, nnn, ...
Cross-postings to other groups are encoded as a list of
internal group numbers.
ts=nn hp=nn fp=nn lp=nn ref=nn[+Re] lines=nn
These values are used by nn to sort, present, and
access an article:
ts is the time stamp on the article; it is a simple
encoding of the posting date and time found in the
Date: field.
hp, fp, and lp are offsets into the file containing the
article text: the header position, first text position,
and last text position. The first will be zero for
normal articles, but not for articles in a split dig-
est. The last will be equal to the length of the file
for normal articles, but not inside digests.
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.
Sender(length): name
The name of the sender in "ready to print" format, i.e.
reduced to 16 characters as explained in the nn manual.
Subj(length): subject
This is the full subject line from the article header
(except for Re: prefixes in various formats).
FILES
The $db, $lib, and $news used below are synonyms for the
DB_DIRECTORY, LIB_DIRECTORY, and the news system's lib
directories respectively.
$db/MASTER Database master index
$db/GROUPS News group names in MASTER file order
$db/DATA/nnn.x Index file for group number nnn
$db/DATA/nnn.d Data file for group number nnn
$master/GATE Message channel from nnadmin to nnmaster
$master/MPID The process id of the nnmaster daemon.
$Log The log file (truncate it regularly!)
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.
The GATE file will be created by nnadmin when needed, and
removed by nnmaster when it has read it. Therefore, to send
a message to the nnmaster requires that you are allowed to
write in the $master directory.
SEE ALSO
nn(1), nncheck(1), nngrep(1), nntidy(1)
nnquery(1M), nnusage(1M), nnmaster(8)
WARNINGS
The GATE file is created with the owner and modes of the
user that runs nnadmin which may cause problems if the owner
of the nnmaster 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 direc-
tory where the GATE file resides, only the owner of the
directory (normally "news") and "root" can use nnadmin to
send messages to the nnmaster. However, to send a wakeup
signal to the master, anybody can run
nnmaster -w
BUGS
The user interface is completely out of line with the rest
of the nn family, and the way to run nnadmin 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!
AUTHOR
Kim F. Storm, Texas Instruments A/S, Denmark
E-mail: storm@texas.dk