.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PERL-NOCEM 8" .TH PERL-NOCEM 8 2024-04-01 "INN 2.7.2" "InterNetNews Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME perl\-nocem \- A NoCeM\-on\-spool implementation for INN 2.x .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fBperl-nocem\fR [\fB\-hl\fR] [\fB\-c\fR \fIfilename\fR] [\fB\-g\fR \fIcommand\fR] [\fB\-G\fR \&\fIcommand\fR] [\fB\-i\fR \fIfilename\fR] [\fB\-k\fR \fIkeyring\fR] [\fB\-v\fR \fIlevel\fR] .SH DESCRIPTION .IX Header "DESCRIPTION" NoCeM, which is pronounced \fINo See 'Em\fR, 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 \fIthird-party killfile\fR. 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. .PP \&\fBperl-nocem\fR 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 \fInocem.ctl\fR in \fIpathetc\fR 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 to check for possible new NoCeM issuers to add and see an overview of their policy. The daily summary of NoCeM messages sent may also be useful. .PP \&\fBperl-nocem\fR 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 \fIperl\-nocem.log\fR in \fIpathlog\fR if the syslog facility is not available or the \fB\-l\fR flag is explicitly used; otherwise, the syslog facility is used in which case status messages are appended to a file usually named \fInews.notice\fR in \fIpathlog\fR. (Some logs will be written only if debug level is set up to be logged via syslog.) .SH CONFIGURATION .IX Header "CONFIGURATION" Processing NoCeM notices is easy to set up: .IP 1. 4 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 \fBgpg\fR and \fBgpgv\fR 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 \fB\-g\fR and \fB\-G\fR flags to set (or even override) the commands \fBperl-nocem\fR will use to run these programs. .Sp 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 \fBgpg1\fR to process NoCeM notices. .IP 2. 4 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: .Sp .Vb 4 \& gpg \-\-no\-default\-keyring \-\-allow\-non\-selfsigned\-uid \e \& \-\-primary\-keyring /pgp/ncmring.gpg \-\-no\-options \e \& \-\-no\-permission\-warning \-\-batch \-\-import \& chmod 644 /pgp/ncmring.gpg .Ve .Sp where is the value of the \fIpathetc\fR parameter set in \fIinn.conf\fR and the file containing the public key(s) to import. The keyring is located in \fI/pgp/ncmring.gpg\fR by default; you only have to create the directory \fI/pgp\fR before using \fBgpg\fR (it will automatically generate the \fIncmring.gpg\fR 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 \fBperl-nocem\fR with the \fB\-k\fR flag. .Sp The public keys of NoCeM issuers can be found in the web site of The NoCeM Registry where you can even download a unique file which contains all the public keys. .IP 3. 4 Create or update the \fInocem.ctl\fR configuration file in \fIpathetc\fR to indicate the NoCeM issuers and the types of notices you want to follow. This permission file contains lines like: .Sp .Vb 2 \& bleachbot@httrack.com:spam,site \& pgpmoose@killfile.org:pgpmoose\-forged\-moderation .Ve .Sp This will remove all articles for which the issuer (first part of the line, before the colon \f(CW\*(C`:\*(C'\fR) has issued NoCeM notices of a type present in the comma-separated list of types specified after the colon (using \f(CW\*(C`*\*(C'\fR is possible, and means that all types are accepted). .Sp Blank lines and lines beginning with a hash sign (\f(CW\*(C`#\*(C'\fR) are ignored. Case is insensitive. Any entry with no corresponding public PGP key in the keyring will be skipped. .Sp You will also find information about the issuers on the web site of \fIThe NoCeM Registry\fR. Note that INN is shipped with an up-to-date \fInocem.ctl\fR 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.) .IP 4. 4 Add to the \fInewsfeeds\fR file in \fIpathetc\fR an entry like this one in order to feed \fBperl-nocem\fR with the NoCeM messages (cross)posted to news.lists.filters, the global newsgroup where notices should be sent: .Sp .Vb 3 \& nocem!\e \& :!*,news.lists.filters\e \& :Tc,Wf,Ap:/perl\-nocem .Ve .Sp with the correct path to \fBperl-nocem\fR, located in , and any optional flag you want to use. Then, run \f(CW\*(C`inncheck\*(C'\fR to ensure the syntax of the modified \fInewsfeeds\fR file is correct, and reload it (via \f(CW\*(C`ctlinnd reload newsfeeds \*(AqNoCeM channel feed\*(Aq\*(C'\fR). .Sp 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. .IP 5. 4 Everything should now work. However, do not hesitate to manually test \&\fBperl-nocem\fR with a NoCeM message, using either: .Sp .Vb 2 \& grephistory \*(Aq\*(Aq | perl\-nocem \-l \-v 2 \& echo \*(Aq/path/to/a/nocem/message\*(Aq | perl\-nocem \-l \-v 2 .Ve .Sp \&\fBperl-nocem\fR expects either storage tokens or file names on its standard input (\fBgrephistory\fR returns the storage token of an article identified by its Message-ID). .Sp Check the logs of that test in \fIperl\-nocem.log\fR in \fIpathlog\fR. .Sp You can also check the list of installed PGP public keys with the following command, adapted to the location of the NoCeM keyring: .Sp .Vb 2 \& gpg \-\-no\-default\-keyring \-\-list\-keys \e \& \-\-primary\-keyring /pgp/ncmring.gpg .Ve .SH OPTIONS .IX Header "OPTIONS" .IP "\fB\-c\fR \fIfilename\fR" 4 .IX Item "-c filename" By default, \fBperl-nocem\fR reads a configuration file named \fInocem.ctl\fR in \&\fIpathetc\fR. This flag permits reading another configuration file, specified with an absolute path. .IP "\fB\-g\fR \fIcommand\fR" 4 .IX Item "-g command" By default, \fBperl-nocem\fR 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 \fBgpg\fR is present in \&\fIcommand\fR; otherwise, \fBperl-nocem\fR may malfunction. .Sp Assuming \f(CW\*(C`/bin/gpg\*(C'\fR corresponds to the \fBgpg\fR binary, the default is: .Sp .Vb 1 \& \-g "/bin/gpg \-\-status\-fd=1 \-\-verify \-\-allow\-weak\-digest\-algos" .Ve .IP "\fB\-G\fR \fIcommand\fR" 4 .IX Item "-G command" By default, \fBperl-nocem\fR 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 \fBgpgv\fR is present in \&\fIcommand\fR; otherwise, \fBperl-nocem\fR may malfunction. .Sp Assuming \f(CW\*(C`/bin/gpgv\*(C'\fR corresponds to the \fBgpgv\fR binary, the default is: .Sp .Vb 1 \& \-G "/bin/gpgv \-\-status\-fd=1" .Ve .Sp Note that \fBgpg\fR will be preferentially used over \fBgpgv\fR when both are available, unless \fB\-g\fR is given an empty string. .IP \fB\-h\fR 4 .IX Item "-h" Print to standard output a usage message and exit. .IP "\fB\-i\fR \fIfilename\fR" 4 .IX Item "-i filename" When this flag is used, \fBperl-nocem\fR includes an external Perl script named \fIfilename\fR, specified with an absolute path. It permits loading a \&\f(CW\*(C`local_want_cancel_id\*(C'\fR 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. .Sp This function is called for every article in the notice and has access to several variables: the Message-ID \f(CW\*(C`$msgid\*(C'\fR of the NoCeM message, the Message-ID \f(CW\*(C`$artid\*(C'\fR of the article to cancel, the comma-separated list of newsgroups \f(CW\*(C`$groups\*(C'\fR to which the article to cancel was posted, the hash reference \f(CW\*(C`$hdrs\*(C'\fR to the pseudo header fields of the NoCeM notice, in lowercase value. The article is kept if the function returns \f(CW\*(C`0\*(C'\fR, and cancelled otherwise. .Sp Here is an illustration of what this function can do, when defined in \&\fIfilename\fR and the \fB\-i\fR flag is used: .Sp .Vb 2 \& 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\e./ and $hdrs\->{issuer} eq "john"; \& \& # The article has been posted to at least a newsgroup \& # in the fr.* or news.* hierarchy. \& $carried = 1 if $group =~ /^(fr|news)\e./; \& } \& \& # 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\*(Aqt 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; \& } .Ve .Sp If any syntax problem occurs when Perl loads the function, \fBperl-nocem\fR will die and report the reason in the logs. You'll then have to fix the function. .IP "\fB\-k\fR \fIkeyring\fR" 4 .IX Item "-k keyring" By default, \fBperl-nocem\fR verifies the signatures of NoCeM messages with the PGP public keys present in a keyring named \fIncmring.gpg\fR in the \&\fIpathetc\fR/pgp directory. This flag permits using another keyring, specified with an absolute path. .Sp A \fB\-\-keyring=\fR flag with the \fIkeyring\fR value is then passed to the gpg(1) and gpgv(1) commands unless \fIkeyring\fR is an empty string. .IP \fB\-l\fR 4 .IX Item "-l" By default, \fBperl-nocem\fR send logs to syslog(3). In case the syslog facility is not available or this flag is used, logs are sent to \fIperl\-nocem.log\fR in \fIpathlog\fR. .IP "\fB\-v\fR \fIlevel\fR" 4 .IX Item "-v level" Increase log verbosity to that \fIlevel\fR, from 1 to 3. Default is \f(CW\*(C`1\*(C'\fR. .SH FILES .IX Header "FILES" .IP \fIpathbin\fR/perl\-nocem 4 .IX Item "pathbin/perl-nocem" The Perl script itself used to process NoCeM messages. .IP \fIpathetc\fR/nocem.ctl 4 .IX Item "pathetc/nocem.ctl" The configuration file which specifies the NoCeM notices to be processed. Another file can be specified with the \fB\-c\fR flag. .IP \fIpathetc\fR/pgp/ncmring.gpg 4 .IX Item "pathetc/pgp/ncmring.gpg" The keyring which contains the public keys of trusted NoCeM issuers. Another file can be specified with the \fB\-k\fR flag. .IP \fIpathlog\fR/perl\-nocem.log 4 .IX Item "pathlog/perl-nocem.log" The log file used when the syslog facility is not available or the \fB\-l\fR flag is used. .SH NOTES .IX Header "NOTES" The Subject header field body is not checked for the \f(CW\*(C`@@NCM\*(C'\fR string and there is no check for the presence of the References header field. .PP 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. .SH HISTORY .IX Header "HISTORY" Copyright 2000 by Miquel van Smoorenburg . .PP Copyright 2001 by Marco d'Itri . .SH "SEE ALSO" .IX Header "SEE ALSO" gpg(1), gpgv(1), grephistory(1), inn.conf(5), newsfeeds(5), pgp(1).