.\" -*- 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 "CONTROLCHAN 8"
.TH CONTROLCHAN 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
controlchan \- Channel\-fed control message handler
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBcontrolchan\fR [\fB\-ch\fR]
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBcontrolchan\fR removes the responsibility for handling control messages
(except cancels) from \fBinnd\fR and instead processes them from a channel
or file feed.
.PP
The two Perl modules \f(CW\*(C`Encode\*(C'\fR and \f(CW\*(C`MIME::Parser\*(C'\fR are required by
\&\fBcontrolchan\fR.
.PP
To reduce load, \fBcontrolchan\fR keeps a copy of \fIcontrol.ctl\fR and
\&\fIcontrol.ctl.local\fR in memory and checks permissions (including any required
PGP headers) before any scripts are called.  These two configuration
files are automatically reloaded when \fBcontrolchan\fR notices they have
been modified.  Also, the default case of an unrecognized control article
is handled internally.  The \f(CW\*(C`drop\*(C'\fR case is handled with far less fuss.
.PP
Normally, \fBcontrolchan\fR is invoked by \fBinnd\fR as configured in \fInewsfeeds\fR.
An example entry is below.  Make sure that the newsgroup \f(CW\*(C`control.cancel\*(C'\fR
exists so that \fBcontrolchan\fR does not have to scan through cancels,
which it will not be processing anyway.
.PP
.Vb 4
\&    controlchan!\e
\&        :!*,control,control.*,!control.cancel\e
\&        :AC,Tc,Wnsm\e
\&        :<pathbin in inn.conf>/controlchan
.Ve
.PP
\&\fBcontrolchan\fR can also be manually invoked with a mere path to a file
(containing a complete control article with its headers and its body)
or a token on its standard input:
.PP
.Vb 2
\&    echo \*(Aq/path/to/a/control/article\*(Aq | controlchan
\&    echo \*(Aq@0303465234000000000000235AE000000002@\*(Aq | controlchan
.Ve
.PP
Note that in the (very, very unlikely) event that you need to process
ihave/sendme control messages, be sure that \fIlogipaddr\fR is set to false
in \fIinn.conf\fR, because in this case \fBcontrolchan\fR needs a site name,
not an IP address.
.PP
\&\fBcontrolchan\fR tries to report all log messages through syslog(3), unless
connected to an interactive terminal.  To enable syslog(3)'ing for versions of
Perl prior to 5.6.0, you will need to have run \fBh2ph\fR on your system include
files at some point (this is required to make \f(CW\*(C`Sys::Syslog\*(C'\fR work).  If you
have not done so, do this:
.PP
.Vb 2
\&    cd /usr/include
\&    h2ph * sys/*
.Ve
.PP
If you run FreeBSD, you will need to run the following in addition:
.PP
.Vb 1
\&    h2ph machine/*
.Ve
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-c\fR 4
.IX Item "-c"
By default, \fBcontrolchan\fR does not process articles whose Date
or Injection-Date header fields are too far in the past (more than
\&\fIartcutoff\fR days, as set in \fIinn.conf\fR) or one day in the future.
It allows preventing a malicious replay of old control articles.
.Sp
Using the \fB\-c\fR flag disables this check on the cutoff date.
.IP \fB\-h\fR 4
.IX Item "-h"
Gives usage information.
.SH HISTORY
.IX Header "HISTORY"
Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.  Converted to
POD by Julien Elie.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
control.ctl(5), inn.conf(5).