NNADMIN(1M)

📦
version 6.7.5 · 2 versions
, in ubuntu stonking

💖 NNADMIN — the manual bestie 💖

okay so this is nnadmin(1M), aka nn database administration. welcome to the control room 🎀

✨ NAME ✨

nnadmin — nn database administration, but make it y2k ✨

✨ SYNOPSIS ✨

nnadmin [ commands ]

✨ DESCRIPTION ✨

so nnadmin is literally the control program for the nnmaster(1M) daemon — and that daemon is the one responsible for building and maintaining the database that the nn(1) news reader uses. main character energy, honestly 👑

with nnadmin you can:

  • display extracts from the log file 📜
  • display the "raw" contents of the database 🫣
  • make consistency checks on the database 🔍
  • tell the running nnmaster to expire one or more groups ⏳
  • alter the options of the running nnmaster 🎛️
  • and much more. like, much more. iykyk 💅

nnadmin runs in two modes: interactive and non-interactive.

Interactive mode keeps it cute and simple: one-line menus show you the available operations, and you just type the letter associated with the command (normally the first letter in the command name). slay. easy.

Non-interactive mode is where the commands argument comes in — it gets used as a series of key-strokes interpreted exactly as if you'd typed them from the keyboard in interactive mode. for example, to stop the nnmaster, you can invoke nnadmin like this:

nnadmin MK

that selects the (M)aster submenu from the main menu, then the (K)ill entry from the submenu. chef's kiss.

⚠️ heads up bestie: in non-interactive mode the menus are not displayed and the commands are not echoed! nnadmin exits when there are no more key-strokes left to read from the commands argument. and no, you cannot specify a group name in the commands argument, so all the nnadmin functionalities that relate to specific groups are only available in interactive mode. 🙈

some "dangerous" commands require you to confirm them by following them with "Y" on the command line. the most notable are IY (initialize database) and EY (expire all groups). these commands get marked with a [Y] right after the command name. respect the [Y], fr fr 💀

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. iconic.

where that subshell wakes up depends on where you summoned it from:

  • from the MASTER or DUMP menus → the working directory gets changed to the database directory
  • from the GROUP menu → it gets changed to the group's spool directory (if it exists)

from the main menu (you'll know it by the ADMIN prompt) you can pick from these operations:

  • C)onf — show current configuration parameters such as directories, files, programs, network usage, etc. the receipts, basically 💅
  • 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. bye bestie 🦋
  • 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'll be asked whether a request should be sent to the nnmaster daemon to recollect that group. (and in non-interactive mode, requests get sent automatically for all corrupted groups — no asking, it just does it.)
  • W)akeup — send a wakeup signal to the nnmaster daemon so it receives messages sent to it, performs the required actions, and then collects articles as necessary. wake up babe 🌸
  • Z (silent validation) — identical to the Validate operation, except no output is produced during the consistency check. this is the one the nnmaster uses to execute the -C option. the quiet, mysterious one 🤫

✨ THE MASTER MENU ✨

the master menu (you'll spot it by the MASTER prompt) gives you access to overall database info and lets you send control messages to the nnmaster daemon.

  • C)heck — in interactive mode and in verbose batch mode (nnadmin MC), print a message telling you whether nnmaster is running or not. in silent batch mode (nnadmin =MC), it exits with a status code of 0 if nnmaster is running and 1 otherwise — which may be useful in administrative scripts. yes bestie, that's a 0/1 exit status, write it down 📝
  • 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, identified by its internal group number.
  • K)ill — stop the nnmaster once it has finished its current task. not a jump scare, it waits its turn 🫶
  • O)ptions — change the runtime options of the running nnmaster daemon. 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 (the DUMP prompt bestie) lets you print the master index entry for various selections of groups in the database. pick your filter, get your data 🔥

  • 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's 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 (LOG prompt, obviously 💅) lets you extract specific entries from the log file, and truncate the log file.

every entry in the log file shares this format:

<class>: <date> <time> (<user>): <message>

where:

  • <class> identifies the message class
  • <date> and <time> say when the entry was made
  • <user> says who created the entry (the letter "M" denotes the nnmaster)
  • <message> is the text of the entry

to extract the log file entries of a specific class, just type the letter identifying the class:

  • A — admin to master communication 🎀 this class of messages is related to the sending of messages from an nnadmin program to the nnmaster daemon.
  • B — bad articles reports about bad articles which have been ignored or removed (controlled by the -b and -B options to nnmaster).
  • C — collection statistics statistics about collection of new articles. the message 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 things that "cannot happen" happen anyway — and that 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 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. rip 🪦
  • 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 errors which let the nnmaster continue operation, but may prevent a user from running 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 purposes.
  • 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's possible to suspend nn, or leave the terminal while nn is active, nn tries to be intelligent when it calculates the usage time so it reflects the actual time spent on news reading. the usage statistics can be summarized using the nnusage(1M) program.

  • V — validation errors when inconsistencies are detected in the database during 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 reactivation 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. be patient bestie ⏳

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 the last 10 lines of the 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 ✨

Okay so when you slide into the group menu (you'll know it by the GROUP prompt, it's giving ✨labeled✨), nnadmin asks you for the name of a news group, and you can type it in with the usual completion feature, which is fully described in the nn(1) manual. Then you get to do these things to that group:

  • C)lear_flag — clears a group-specific flag. Flags are explained in the section right below, keep scrolling bestie 💅
  • D)ata — dumps the contents of the data file that holds the extracted article headers for the group.
  • E)xpire — asks the nnmaster to run expire on the group.
  • F)iles — lists the files containing the index and data for the group (it uses ls(1) to do it).
  • G)roup — switches to a different group.
  • H)eader — dumps the master index entry for the group.
  • R)ecollect — asks the nnmaster to recollect all the articles in the group.
  • S)et_flag — sets a group-specific flag. Again, see below 💖
  • V)alidate — performs validation on the group's database information.
  • Z)ap [Y] — removes the group from the news system, and this happens by running the rmgroup program, which must live in the NEWS_LIB directory. And like. obviously this should be done with great caution. no cap. 🙈

🌸 INDIVIDUAL GROUP FLAGS 🌸

You can set and clear these flags per individual group to control how nnmaster will behave on that group going forward.

Heads up bestie: these flags get reset to their default value if you reinitialize the database with nnmaster -I. So if you want a flag change to be permanent, set or clear it in the GROUPS file instead. Periodt.
  • A)lways_digest — Normally nnmaster will only attempt to split digests into individual articles if it can easily recognize an article as a digest. And "easily" means: the word "digest" appears somewhere in the subject line, and one of the first few lines in the body of the article loosely matches the subject. But some news groups frequently receive digests that break one or both of these requirements 😭. So to have nnmaster split those digests into individual articles anyway, you can turn on the "always digest" flag on those news groups. This tells nnmaster to treat all articles in the group as digests. (Naturally, articles that turn out not to contain other articles are still treated as normal articles — it's not chaotic, it's just thorough.)
  • C)ontrol — this is a special flag for the control group. It indicates that the "Newsgroups:" field in the article header cannot be trusted — i.e. it does not specify the groups to which the article has been posted. 💀
  • D)irectory missing — this flag says the spool directory for the news group can't be found (the group has probably been removed with rmgroup(1M)). It gets set automatically by the nnmaster if it can't access the directory. While the flag is set, nnmaster completely ignores the group, so you can use it to disable news collection in specific groups. And if you recreate the group or the directory by hand, you must also clear this flag to make 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. fr fr, leave it alone.
  • N)ever_digest — the exact opposite of the "always digest" flag; when it's set, the nnmaster will never attempt to split any articles in that group into subarticles. 🚫

📊 DATABASE STATISTICS DISPLAY 📊

When you pick the (S)tat operation in the main or master menus, you get some general stats about the database:

  • initialized — the time when the database was last rebuilt 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. Note: this is not an exact number, because it counts split digests as a single article (which makes the number too small), and it may count some articles that have already been expired (which makes the number too large). So it's giving approximate, not giving precise. 😌
  • Disk usage — the total number of (1 kbyte) disk blocks occupied by the database.

🔍 MASTER INDEX ENTRIES 🔍

The master index entries you see when you select the (H)eader operation in the master and group menus contain this info:

  • group_name group_number — the first line of the display shows the name of the group and the internal group number, which is what identifies the group in the database.
  • first/last art — the numbers of the first and last article currently stored in the database.
  • active info — the numbers of the first and last article in the news system, as read from the active file. These normally match the numbers above, but they can differ while the nnmaster is working on the group (or if it hasn't yet collected all the articles in the group). it's giving "in progress" vibes.
  • Offsets: index->..., data->... — these values show the starting position for the next write operation on the index and data files. They're mainly used for consistency checking and for recovery after a system crash. But heads up: after an "expire by rewrite" operation (that's 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: — shows the current flags set for this group. If no flags are set, the field is simply omitted from the display. And there's one extra flag that wasn't explained above: the BLOCKED flag. It's a temporary locking flag that the nnmaster sets on a group while it's updating the database files for that group, so that nn clients can't access that group. it's literally holding the door, bestie 🚪

🧚 RAW DATABASE DISPLAY 🧚

When you select the (D)ata operation in the group menu, you 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. That value is an offset into the data file, pointing to the header for the corresponding article.

When nn wants to access the articles from number N to the last article, it looks up the offset for article number N in the index file, and uses that as the starting point for reading article header information in the data file. Then it just reads to the end of the data file, where the article headers for articles number N+1, N+2, and so on follow immediately after the header for article number N. slay, sequential. 💅

The article header information shows up in a very terse form; each of the output lines is described below, for reference purposes:

  • offset = xxxx , article # = nnnnn (type) — 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 type is printed, it's a normal article. The 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's 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 digest. 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 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. And that sequence also defines the group numbers used to identify the files in the database and in a few other places. ✨

The GATE file gets created by nnadmin when needed, and removed by nnmaster once it has read it. So to send a message to the nnmaster, you have to be allowed to write in the $master directory. that's the vibe check right there.

👀 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.). So 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 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. And this is not likely to change, because I believe there are more important things to do! it's giving "I know, I know, leave me alone" energy 🙈

💜 AUTHOR 💜

Kim F. Storm, Texas Instruments A/S, Denmark E-mail: storm@texas.dk

and that's the whole page bestie, we did it 🫶 this one came from the 4th Berkeley Distribution, Release 6.7.5, and it's literally titled NNADMIN(1M). iconic. go forth and manage some news, mwah 💅✨🎀🦋

📦 where this page comes from