Provided by: inn2_2.7.3~20241006-1build1_amd64 
NAME
perl-nocem - A NoCeM-on-spool implementation for INN 2.x
SYNOPSIS
perl-nocem [-hlu] [-b directory] [-c filename] [-g command] [-G command] [-i filename] [-k
keyring] [-v level]
DESCRIPTION
NoCeM, which is pronounced No See 'Em, is a protocol enabling authenticated third-parties
to issue notices which can be used to cancel unwanted articles (like spam and articles in
moderated newsgroups which were not approved by their moderators). It can also be used by
readers as a third-party killfile. It is intended to eventually replace the protocol for
third-party cancel messages which can too easily be forged as cancel messages are not
authenticated, contrary to NoCeM notices.
perl-nocem processes third-party, PGP-signed article cancellation notices. It is possible
to honour a selective set of NoCeM notices, and not all of them. You can configure in
nocem.ctl in pathetc the list of NoCeM issuers you trust and add the corresponding public
PGP keys to your NoCeM keyring (by default, no PGP keys are installed, so nobody is
trusted). It is up to you to decide whether you wish to honour their notices, depending
on the criteria they use. You are encouraged to regularly have a look at the official
NoCeM Registry <https://rosalind.home.xs4all.nl/nocemreg/nocemreg.html> to check for
possible new NoCeM issuers to add and see an overview of their policy. The daily summary
of NoCeM messages sent <https://www.novabbs.com/SEARCH/search_nocem.php?stats=daily> may
also be useful.
perl-nocem expects either storage tokens or file names on its standard input. It will
then read and process the corresponding article. It appends all status messages to
perl-nocem.log in pathlog if the syslog facility is not available or the -l flag is
explicitly used; otherwise, the syslog facility is used in which case status messages are
appended to a file usually named news.notice in pathlog. (Some logs will be written only
if debug level is set up to be logged via syslog.)
CONFIGURATION
Processing NoCeM notices is easy to set up:
1. If not already done, install GnuPG, or an equivalent implementation of the OpenPGP
standard, to be able to verify the signature of NoCeM messages. It will provide the
gpg and gpgv programs. If GnuPG was already installed when INN was configured, then
the paths to these programs were taken into account. Otherwise, you can use the -g
and -G flags to set (or even override) the commands perl-nocem will use to run these
programs.
All still active NoCeM issuers use rather modern PGP keys accepted by both GnuPG 1.x
and 2.x versions. It is no longer needed to explicitly use gpg1 to process NoCeM
notices.
2. Import the public keys of the NoCeM issuers you trust in order to check the
authenticity of their notices. You can run the following command:
gpg --no-default-keyring --allow-non-selfsigned-uid \
--primary-keyring <pathetc>/pgp/ncmring.gpg --no-options \
--no-permission-warning --batch --import <key-file>
chmod 644 <pathetc>/pgp/ncmring.gpg
where <pathetc> is the value of the pathetc parameter set in inn.conf and <key-file>
the file containing the public key(s) to import. The keyring is located in
<pathetc>/pgp/ncmring.gpg by default; you only have to create the directory
<pathetc>/pgp before using gpg (it will automatically generate the ncmring.gpg file)
and make sure the news user can read this file, once generated. You can use another
location and file name for the keyring, and then run perl-nocem with the -k flag.
The public keys of NoCeM issuers can be found in the web site of The NoCeM Registry
<https://rosalind.home.xs4all.nl/nocemreg/nocemreg.html> where you can even download a
unique file which contains all the public keys.
3. Create or update the nocem.ctl configuration file in pathetc to indicate the NoCeM
issuers and the types of notices you want to follow. This permission file contains
lines like:
bleachbot@httrack.com:spam,site
pgpmoose@killfile.org:pgpmoose-forged-moderation
This will remove all articles for which the issuer (first part of the line, before the
colon ":") has issued NoCeM notices of a type present in the comma-separated list of
types specified after the colon (using "*" is possible, and means that all types are
accepted).
Blank lines and lines beginning with a hash sign ("#") are ignored. Case is
insensitive. Any entry with no corresponding public PGP key in the keyring will be
skipped.
You will also find information about the issuers on the web site of The NoCeM
Registry. Note that INN is shipped with an up-to-date nocem.ctl file already
configured with the current NoCeM issuers. (Only the public PGP keys installed at the
previous step are not included, so as to leave you the choice of whom to trust, and
download the most recent ones, in case they have changed.)
4. Add to the newsfeeds file in pathetc an entry like this one in order to feed perl-
nocem with the NoCeM messages (cross)posted to news.lists.filters, the global
newsgroup where notices should be sent:
nocem!\
:!*,news.lists.filters\
:Tc,Wf,Ap:<pathbin>/perl-nocem
with the correct path to perl-nocem, located in <pathbin>, and any optional flag you
want to use. Then, run "inncheck" to ensure the syntax of the modified newsfeeds file
is correct, and reload it (via "ctlinnd reload newsfeeds 'NoCeM channel feed'").
Note that you should at least carry news.lists.filters on your news server (or other
newsgroups where NoCeM notices are sent) if you wish to process them.
5. Everything should now work. However, do not hesitate to manually test perl-nocem with
a NoCeM message, using either:
grephistory '<Message-ID>' | perl-nocem -l -v 2
echo '/path/to/a/nocem/message' | perl-nocem -l -v 2
perl-nocem expects either storage tokens or file names on its standard input
(grephistory returns the storage token of an article identified by its Message-ID).
Check the logs of that test in perl-nocem.log in pathlog.
You can also check the list of installed PGP public keys with the following command,
adapted to the location of the NoCeM keyring:
gpg --no-default-keyring --list-keys \
--primary-keyring <pathetc>/pgp/ncmring.gpg
OPTIONS
-b directory
Back up cancelled articles into files in directory. The directory should exist and be
writable by the news user. Files are named issuer%type, and contain the articles
actually removed from your news spool by the given NoCeM issuer for the given type of
NoCeM notices. Cancelled articles which are not stored in your news spool when the
notice is processed cannot be backed up.
This flag is primarily meant for auditing possible false positives. As the backups
are not automatically purged, you should prune them from time to time after having
inspected their contents.
-c filename
By default, perl-nocem reads a configuration file named nocem.ctl in pathetc. This
flag permits reading another configuration file, specified with an absolute path.
-g command
By default, perl-nocem runs the gpg(1) binary whose path was determined when INN was
configured. If GnuPG wasn't installed at that time, or if you want to use another
program, this flag will be helpful. Please ensure that at least an equivalent of the
default options given to gpg is present in command; otherwise, perl-nocem may
malfunction.
Assuming "/bin/gpg" corresponds to the gpg binary, the default is:
-g "/bin/gpg --status-fd=1 --verify --allow-weak-digest-algos"
-G command
By default, perl-nocem runs the gpgv(1) binary whose path was determined when INN was
configured. If GnuPG wasn't installed at that time, or if you want to use another
program, this flag will be helpful. Please ensure that at least an equivalent of the
default option given to gpgv is present in command; otherwise, perl-nocem may
malfunction.
Assuming "/bin/gpgv" corresponds to the gpgv binary, the default is:
-G "/bin/gpgv --status-fd=1"
Note that gpg will be preferentially used over gpgv when both are available, unless -g
is given an empty string.
-h Print to standard output a usage message and exit.
-i filename
When this flag is used, perl-nocem includes an external Perl script named filename,
specified with an absolute path. It permits loading a "local_want_cancel_id" function
with local rules to fine-tune within a NoCeM notice which articles get cancelled. All
the articles present in a NoCeM notice are otherwise cancelled by default.
This function is called for every article in the notice and has access to several
variables: the Message-ID "$msgid" of the NoCeM message, the Message-ID "$artid" of
the article to cancel, the comma-separated list of newsgroups "$groups" to which the
article to cancel was posted, the hash reference "$hdrs" to the pseudo header fields
of the NoCeM notice, in lowercase value. The article is kept if the function returns
"0", and cancelled otherwise.
Here is an illustration of what this function can do, when defined in filename and the
-i flag is used:
sub local_want_cancel_id {
my ($msgid, $artid, $groups, $hdrs) = @_;
my $carried = 0;
# Walk through the newsgroups the article was posted to.
foreach my $group (split(/,/, $groups)) {
# Keep it if posted to news.software.nntp.
return 0 if $group eq "news.software.nntp";
# Keep it if posted to fr.* and the issuer is "john".
return 0
if $group =~ /^fr\./ and $hdrs->{issuer} eq "john";
# The article has been posted to at least a newsgroup
# in the fr.* or news.* hierarchy. You may use here
# a regular expression corresponding to the newsgroups
# pattern you ask your feeds to send you.
$carried = 1 if $group =~ /^(fr|news)\./;
}
# In case the server only carries fr.* and news.*, this
# rule permits discarding NoCeM notices related to
# newsgroups not carried by the server, and therefore
# neither treating nor remembering in the history file
# Message-IDs of articles which won't reach the server.
return 0 if not $carried;
# Keep it if only posted to news.admin.net-abuse.usenet
# and the type of the notice is "spam".
return 0
if $groups eq "news.admin.net-abuse.usenet"
and $hdrs->{type} eq "spam";
# Cancel it!
return 1;
}
If any syntax problem occurs when Perl loads the function, perl-nocem will die and
report the reason in the logs. You'll then have to fix the function.
-k keyring
By default, perl-nocem verifies the signatures of NoCeM messages with the PGP public
keys present in a keyring named ncmring.gpg in the pathetc/pgp directory. This flag
permits using another keyring, specified with an absolute path.
A --keyring= flag with the keyring value is then passed to the gpg(1) and gpgv(1)
commands unless keyring is an empty string.
-l By default, perl-nocem send logs to syslog(3). In case the syslog facility is not
available or this flag is used, logs are sent to perl-nocem.log in pathlog. Error log
level will still additionally be sent to syslog if available.
-u By default, innreport will show unprocessed NoCeM notices in daily reports it
generates. When this flag is used, issuers or types of notices not configured in
nocem.ctl will still be mentioned in the logs but the corresponding log lines will not
be parsed by innreport.
-v level
Increase log verbosity to that level, from 1 to 3. Default is "1".
FILES
pathbin/perl-nocem
The Perl script itself used to process NoCeM messages.
pathetc/nocem.ctl
The configuration file which specifies the NoCeM notices to be processed. Another
file can be specified with the -c flag.
pathetc/pgp/ncmring.gpg
The keyring which contains the public keys of trusted NoCeM issuers. Another file can
be specified with the -k flag.
pathlog/perl-nocem.log
The log file used when the syslog facility is not available or the -l flag is used.
NOTES
The accuracy of the newsgroups following the Message-IDs to cancel in the NoCeM body is
not checked, nor is the Newsgroups pseudo header field if present. Well, as we already
trust the issuer of the notice about the Message-IDs he marks as spam, let's also be
confident about the listed newsgroups.
HISTORY
Copyright 2000 by Miquel van Smoorenburg <miquels@cistron.nl>.
Copyright 2001 by Marco d'Itri <md@linux.it>.
SEE ALSO
gpg(1), gpgv(1), grephistory(1), inn.conf(5), innreport(8), newsfeeds(5), pgp(1).