control.ctl man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

CONTROL.CTL(5)		  InterNetNews Documentation		CONTROL.CTL(5)

NAME
       control.ctl - Specify handling of Usenet control messages

DESCRIPTION
       The file pathetc/control.ctl is used to determine what action is taken
       when a control message is received.  It is read by controlchan, which
       is normally invoked as a channel program by innd.  When control.ctl is
       modified, controlchan notices this automatically and reloads it.

       If a control.ctl.local file exists in pathetc, it is read by
       controlchan after control.ctl (the resulting behaviour is as though the
       contents of control.ctl.local were at the end of control.ctl).  This
       local file is formatted like control.ctl and is intended to contain
       local customization.  It is also automatically reloaded when modified.

       Blank lines and lines beginning with a number sign ("#") are ignored.
       All other lines should consist of four fields separated by colons:

	   <type>:<from>:<newsgroups>:<action>

       Lines are matched in order and the last matching line in the file will
       be used, except for checkgroups messages which are handled differently
       (every matching line is used).

       The first field, <type>, is the type of control message for which this
       line is valid.  It should either be the name of a control message or
       the word "all" to indicate that it applies to all control messages.
       Besides, the following special types are understood:

       /encoding/
	   This type specifies the encoding of newgroup and checkgroups
	   control messages so that new descriptions could be decoded the
	   right way.

	       /encoding/:*:cn.*:gb18030

	   means that a description for a newsgroup in the Chinese cn.*
	   hierarchy will be decoded as though it were encoded in GB18030,
	   unless a charset is specified in the control message (in such a
	   case, the charset mentioned in the message is used).	 However, it
	   is possible to override the mentioned charset if "=force" is
	   appended after the encoding.	 For instance,

	       /encoding/:*:scout.forum.chinese:big5=force

	   means that the description for scout.forum.chinese will always be
	   decoded as though it were encoded in Big5, no matter the charset of
	   the corresponding control message.

	   The default value when no encoding is mentioned (or when the
	   specified encoding is unknown) is "CP1252".

	   The last matching line for a given newsgroup name in control.ctl
	   will be used.

       /localencoding/
	   When this type is used, the line consist of only two fields.	 The
	   default value when this type does not appear in control.ctl (or
	   when the specified charset is unknown) is equivalent to:

	       /localencoding/:utf-8

	   It means that new descriptions in the newsgroups file will be
	   written using UTF-8.	 And controlchan will try to read existing
	   descriptions, so as to see whether they should be updated, as
	   though they were encoded in UTF-8.

	   The last matching line in control.ctl will be used.

       /maxdocheckgroups/
	   This type specifies the maximum number of changes that could be
	   made at one time by a checkgroups before bailing and mailing the
	   changes to the admin if no log file was specified.  The default
	   value is 10.

	       /maxdocheckgroups/:*:*:10
	       /maxdocheckgroups/:*:fr.*:20

	   Such a configuration means that a checkgroups containing 15 changes
	   for the French fr.* hierarchy (newgroups to add, remove or change
	   the status) will be automatically honoured whereas a checkgroups
	   containing 15 changes for france.* will only have the required
	   changes mailed or logged.

	   The last matching line for a given newsgroup name in control.ctl
	   will be used.

       The second field, <from>, is a shell-style pattern that matches the
       e-mail address of the person posting the message (with the address
       first converted to lowercase).  The matching is done with rules
       equivalent to those of the shell's case statement; see sh(1) for more
       details.

       If the control message is a newgroup or rmgroup, the third field,
       <newsgroups>, is a shell-style pattern matching the newsgroup affected
       by the control message (especially "?" matches exactly one character,
       "*" matches zero or more characters and "|" permits to match several
       patterns on the same line -- for instance "comp.*|humanities.*"
       matches every newsgroup whose name begins with "comp." or
       "humanities.").	If the control message is a checkgroups, the third
       field is a shell-style pattern matching the newsgroups that should be
       processed for checking.	If the control message is of any other type,
       the third field is ignored.

       The fourth field, <action>, specifies what action to take with control
       messages that match this line.  The following actions are understood:

       doit
	   The action requested by the control message should be performed.
	   It means that the change will be silently performed.	 For
	   checkgroups messages, depending on the value of /maxdocheckgroups/,
	   the shell commands that should be run may be mailed to the news
	   administrator (the argument to --with-news-master given at
	   configure time, "usenet" by default) instead of being performed.

	   If you always want notification of actions taken, use "doit=mail"
	   instead (see below).

       doifarg
	   If the control message has an argument, this is equivalent to doit.
	   If it does not have an argument, this is equivalent to mail.	 This
	   is only useful for entries for sendsys control messages, allowing a
	   site to request its own newsfeeds entry by posting a "sendsys
	   mysite" control message, but not allowing the entire newsfeeds file
	   to be sent.	This was intended to partially counter so-called
	   "sendsys bombs", where forged sendsys control messages were used to
	   mailbomb people.

	   Processing sendsys control messages is not recommended even with
	   this work-around unless they are authenticated in some fashion.
	   The risk of having news servers turned into anonymous mail bombing
	   services is too high.

       doit=file
	   The action is performed as in doit, and additionally a log entry is
	   written to the specified log file file.  If file is the word
	   "mail", the log entry is mailed to the news administrator instead.
	   An empty string is equivalent to /dev/null and says to log nothing.

	   If file starts with a slash, it is taken as the absolute filename
	   to use for the log file.  Otherwise, the filename is formed by
	   prepending pathlog and a slash, and appending ".log".  In other
	   words, an action of "doit=newgroup" will log to
	   pathlog/newgroup.log.

       drop
	   No action is taken and the message is ignored.  For checkgroups
	   messages, it means that the newsgroups mentioned will be considered
	   as not existent in the checkgroups for its subsequent process.

	       checkgroups:*:comp.*:doit
	       checkgroups:*:*binaries*:drop

	   will for instance remove every newsgroup whose name contains
	   "binaries" in the comp.* hierarchy, even though such groups are
	   mentioned in the checkgroups.  (In that example, the removal is
	   performed by the doit action because drop does nothing by itself.)

       verify-*
	   If the action starts with the string "verify-", as in:

	       verify-news.announce.newgroups

	   then PGP verification of the control message will be done and the
	   user ID of the key of the authenticated signer will be checked
	   against the expected identity defined by the rest of the string
	   ("news.announce.newgroups" in the above example).  This
	   verification is done via pgpverify; see pgpverify(8) for more
	   details.

	   If no logging is specified (with =file as mentioned below), logging
	   will be done the same as with doit as described above.

       verify-*=mail
	   PGP verification is done as for the verify-* action described
	   above, and notification of successful newgroup and rmgroup control
	   messages and the output of checkgroups messages will be mailed to
	   the news administrator.  (In the case of checkgroups messages, this
	   means that the shell script that should be run will be mailed to
	   the administrator.  The subject of the mail will contain
	   information on whether the script has already been run, depending
	   on the value of /maxdocheckgroups/.)

       verify-*=file
	   PGP verification is done as for the verify-* action described
	   above, and a log entry is written to the specified file as
	   described in doit=file above.  (In the case of checkgroups
	   messages, this means that the shell script output of the
	   checkgroups message will be written to that file.  The initial line
	   of the log will contain information on whether the script has
	   already been run, depending on the value of /maxdocheckgroups/.)

       log A one-line log message is sent to standard error.  innd normally
	   directs this to pathlog/errlog.

       log=file
	   A log entry is written to the specified log file, which is
	   interpreted as in doit=file described above.

       mail
	   A mail message is sent to the news administrator without taking any
	   other action.

       One of the difference between a doit or verify action and a mail action
       for a checkgroups control message lies in what e-mail is sent; doit or
       verify will mail the news administrator a shell script (which may have
       already been run) to create, delete, or modify newsgroups to match the
       checkgroups message, whereas mail will just mail relevant lines of the
       checkgroups for manual processing by the news administrator.

       Use of the verify action for processing newgroup, rmgroup and
       checkgroups messages is STRONGLY recommended.  Abuse of control
       messages is rampant, and authentication via PGP signature is currently
       the only reliable way to be sure that a control message comes from who
       it claims to be from.  Most major hierarchies are now issuing PGP-
       authenticated control messages.

       In order to use verify actions, the PGP key ring of the news user must
       be populated with the PGP keys of the hierarchy maintainers whose
       control messages you want to honour.  For more details on PGP-
       authenticated control messages and the URL for downloading the PGP keys
       of major hierarchies, see pgpverify(8).

       Control messages of type cancel are handled internally by innd and
       cannot be affected by any of the mechanisms described here.

EXAMPLES
       With the following three lines in control.ctl:

	   newgroup:*:*:drop
	   newgroup:group-admin@isc.org:comp.*:verify-news.announce.newgroups
	   newgroup:kre@munnari.oz.au:aus.*:mail

       a newgroup coming from "group-admin@isc.org" will be honoured if it is
       for a newsgroup in the comp.* hierarchy and if it has a valid signature
       corresponding to the PGP key with a user ID of
       "news.announce.newgroups".  If any newgroup claiming to be from
       "kre@munnari.oz.au" for a newsgroup in the aus.* hierarchy is received,
       it too will be honoured.	 All other newgroup messages will be ignored.

       Besides, if a control.ctl.local file exists and contains:

	   newgroup:*:comp.lang.*:drop

       then a newgroup control article for comp.lang.awk will not be honoured
       even though it comes from "group-admin@isc.org" with a valid signature.

       As for checkgroups, suppose your news server contains these groups for
       foo.*, all of them being unmoderated ("y" status in the active file):

	   foo.bar1
	   foo.bar2.first
	   foo.bar2.second
	   foo.bar2.third
	   foo.bar3
	   foo.bar3.first
	   foo.bar3.second
	   foo.bar5

       and you receive the following checkgroups by <foo@bar.com> for foo.*:

	   foo.bar1	     A valid newsgroup.
	   foo.bar3.first    Only one newsgroup in foo.bar3.*.
	   foo.bar4	     A newsgroup you want.
	   foo.bar5	     A newsgroup you do not want.
	   foo.bar5.first    Another newsgroup you do not want.

       with the following control.ctl entries:

	   /maxdocheckgroups/:*:foo.*:2

	   checkgroups:foo@bar.com:foo.*:verify-key-foo
	   checkgroups:foo@bar.com:foo.bar2.*:doit
	   checkgroups:foo@bar.com:foo.bar3.*:mail
	   checkgroups:foo@bar.com:foo.bar4|foo.bar4.*:doit
	   checkgroups:foo@bar.com:foo.bar5|foo.bar5.*:drop

       Then, as control.ctl is processed from bottom, here is what happens:

       1.  The newsgroups foo.bar5 and foo.bar5.first are marked as unwanted.
	   But nothing is done yet:  other control.ctl entries have to be
	   processed with a real action and a set of newsgroups containing
	   foo.bar5 and foo.bar5.first.

       2.  The newsgroup foo.bar4 is silently created on the news server, with
	   the description "A newsgroup you want." added to the newsgroups
	   file.  In the absence of encoding values (either in the checkgroups
	   message or in /encoding/ and /localencoding), the default is to
	   decode the sentence as CP1242 and reencode it as UTF-8.

	   If "doit=mail" was used, a mail would be sent to the news
	   administrator to inform him that foo.bar4 was successfully created.

       3.  The newsgroup foo.bar3.second is no longer present.	A mail is sent
	   to the news administrator with a shell script to execute.  When it
	   is manually executed, foo.bar3.second will be removed.

	   Note that the descriptions are handled differently and have already
	   been updated without any manual intervention (foo.bar3.first now
	   has the description "Only one newsgroup in foo.bar3.*." and
	   foo.bar3.second no longer has a description).

       4.  The newsgroups foo.bar2.first, foo.bar2.second and foo.bar2.third
	   are no longer present.  However, as the maximum number of changes
	   that could be made at one time by a checkgroups before bailing and
	   mailing the changes to the news administrator is 2, these
	   newsgroups are not removed.	A mail is sent with a shell script to
	   manually execute in order to remove these groups from the news
	   server.

	   Note that their descriptions are removed from the newsgroups file,
	   as well as any other possible descriptions for obsolete newsgroups
	   in foo.bar2.*.

       5.  The remaining entry is executed if the PGP verification of the
	   checkgroups message is successful.  Otherwise, nothing is done
	   (especially, foo.bar5 remains on the news server).

	   In case the PGP signature is verified, foo.bar3 and foo.bar5 are
	   removed from the news server.  This entry acts upon newsgroups
	   marked as dropped in its scope and newsgroups not already dealt
	   with by previous control.ctl entries (like foo.bar3 because only
	   foo.bar3.* was previously checked).

	   Note that if you had wanted to keep foo.bar3 or foo.bar5, you could
	   have added them to the localgroups file in pathetc.

HISTORY
       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Rewritten
       in POD by Russ Allbery <eagle@eyrie.org>.

       $Id: control.ctl.pod 9767 2014-12-07 21:13:43Z iulius $

SEE ALSO
       controlchan(8), inn.conf(5), innd(8), newsfeeds(5), newsgroups(5),
       pgpverify(8), sh(1).

INN 2.6.0			  2015-09-12			CONTROL.CTL(5)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net