Provided by: inn2_2.7.2-1_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).
INN 2.7.2 2024-06-23 PERL-NOCEM(8)