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.