Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PERL-NOCEM(8)		  InterNetNews Documentation		 PERL-NOCEM(8)

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.8.0			  2024-09-30			 PERL-NOCEM(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=perl-nocem&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>

home | help