.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "INNDSTART 8"
.TH INNDSTART 8 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
.SH "NAME"
inndstart \- Start innd
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBinndstart\fR [\fB\-P\fR \fIport\fR] [\fB\-I\fR \fIaddress\fR] [\fIinnd-options\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The purpose of \fBinndstart\fR is to raise system file descriptor limits,
open the privileged news transfer port, and then start \fIinnd\fR\|(8), passing it
the open file descriptor for the news port.  \fBinndstart\fR is used since
only privileged programs can perform those two operations and since
\&\fBinnd\fR should not run with elevated privileges.  It is installed setuid
root and drops privileges to the news user (as set at configure time)
before running \fBinnd\fR.
.PP
Normally there is no need to run \fBinndstart\fR directly.  Instead, run
\&\fIrc.news\fR\|(8) as the news user, and it will handle running \fBinndstart\fR
appropriately for you.
.PP
Since \fBinndstart\fR is setuid root, it is extremely restrictive about who
can run it and what it is willing to do.  See \*(L"\s-1SECURITY\s0\*(R" for the full
details.
.PP
\&\fBinndstart\fR can only be run by the news user; if run by any other user,
it will abort.  It will also only bind to ports 119, 433, or a port number
given at configure time with \fB\-\-with\-innd\-port\fR among those ports below
1024, although it can bind to any port above 1024.  This is to prevent
various security exploits possible by binding to arbitrary privileged
ports.
.PP
Before running \fBinnd\fR, \fBinndstart\fR cleans out the environment and sets
only those environment variables listed in \*(L"\s-1ENVIRONMENT\s0\*(R".
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-P\fR \fIport\fR" 4
.IX Item "-P port"
Bind to \fIport\fR instead of whatever is specified by \fIport\fR in
\&\fIinn.conf\fR.  Note that this is subject to the constraints mentioned
above.
.IP "\fB\-I\fR \fIaddress\fR" 4
.IX Item "-I address"
Bind as \fIaddress\fR instead of whatever is specified by \fIbindaddress\fR in
\&\fIinn.conf\fR.  The default behavior is to bind to \s-1INADDR_ANY\s0, and that's
what's desired almost all the time.  This option, and the \fIinn.conf\fR
parameter, may be useful if the machine has multiple interface cards and
\&\fBinnd\fR should only be listening on a particular one.
.PP
All other options given on the command line are passed verbatim to
\&\fBinnd\fR.  In addition, \fBinndstart\fR will give the \fB\-p\fR option to \fBinnd\fR,
specifying the file descriptor of the open network socket.
.SH "SECURITY"
.IX Header "SECURITY"
\&\fBinndstart\fR is setuid root, and therefore an expected point of attack.
It has therefore been carefully written with security in mind.  In a
normal \s-1INN\s0 installation, it is installed setuid root and executable only
by users in the news group.
.PP
Ideally, everything about \fBinndstart\fR's operations would be hard-coded so
that it could not be modified.  Fighting against this desire, however, is
the ideal that as much of \s-1INN\s0's operation as possible should be
configurable at run-time using \fIinn.conf\fR, and the news system should be
able to an alternate inn.conf by setting \s-1INNCONF\s0 to the path to that file
before starting any programs.  The configuration data therefore can't be
trusted.
.PP
The security model used is:
.IP "\(bu" 2
\&\fBinndstart\fR can only be executed by the news user and news group, as
determined at configure time and compiled into \fBinndstart\fR as constants.
Similarly, \fBinndstart\fR will always \fIsetuid()\fR and \fIsetgid()\fR to those users
before running \fBinnd\fR.  This is to prevent a user other than news but in
the news group from using \fBinndstart\fR to leverage that access into access
to the news account.
.IP "\(bu" 2
As mentioned above, \fBinndstart\fR will only bind to a very limited subset
of ports below 1024.  There are various attacks that can be performed
using random low-numbered ports, including exploits of the \fIrsh\fR\|(1) family
of commands on some systems.
.IP "\(bu" 2
\&\fBinndstart\fR does as little as possible as root, dropping privileges
before performing any operations that do not require elevated privileges.
.PP
This program therefore gives the news user the ability to revoke system
file descriptor limits and bind to the news port, and nothing else.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
\&\fBinndstart\fR may log the following messages to syslog and print them to
stderr.
.ie n .IP "can't bind: %s" 4
.el .IP "can't bind: \f(CW%s\fR" 4
.IX Item "can't bind: %s"
(Fatal) Unable to bind to the designated port.  This usually means that
something else is already running on the news port.  Check with
\&\fInetstat\fR\|(8) and make sure that \fIinetd\fR\|(8) doesn't think it's running a
service on the same port you're trying to run \fBinnd\fR on.
.ie n .IP "can't bind to restricted port %d" 4
.el .IP "can't bind to restricted port \f(CW%d\fR" 4
.IX Item "can't bind to restricted port %d"
(Fatal) \fBinndstart\fR was told to bind to a low numbered port (under 1024)
other than 119, 433, or a port number given at configure time.  This is
not allowed for security reasons.  If you're running \fBinnd\fR on a port
other than 119 or 433, you need to give the \-\-with\-innd\-port flag to
\&\f(CW\*(C`configure\*(C'\fR when you compile \s-1INN\s0.
.ie n .IP "can't exec %s:\fR \f(CW%s" 4
.el .IP "can't exec \f(CW%s:\fR \f(CW%s\fR" 4
.IX Item "can't exec %s: %s"
(Fatal) \fBinndstart\fR was unable to execute \fBinnd\fR.  Make sure that
\&\fIpathbin\fR is set correctly in inn.conf and that \fBinnd\fR is located in
that directory and is executable by the news user.
.IP "can't getgrnam(%s)" 4
.IX Item "can't getgrnam(%s)"
(Fatal) Unable to determine the \s-1GID\s0 for the compiled-in news group.
Perhaps the news group is not listed in \fI/etc/group\fR.
.IP "can't getpwnam(%s)" 4
.IX Item "can't getpwnam(%s)"
(Fatal) Unable to determine the \s-1UID\s0 for the compiled-in news user.
Perhaps the news user is not listed in \fI/etc/passwd\fR.
.ie n .IP "can't open socket: %s" 4
.el .IP "can't open socket: \f(CW%s\fR" 4
.IX Item "can't open socket: %s"
(Fatal) Something went wrong in creating the network socket.  Chances are
your system is out of resources of some kind.
.ie n .IP "can't set file descriptor limit to %d:\fR \f(CW%s" 4
.el .IP "can't set file descriptor limit to \f(CW%d:\fR \f(CW%s\fR" 4
.IX Item "can't set file descriptor limit to %d: %s"
(Warning) Unable to set the system file descriptor limit to the specified
value; the limit was left unchanged.  Perhaps that value is too high for
your system.  Try changing \fIrlimitnofile\fR in \fIinn.conf\fR to a smaller
value.
.ie n .IP "can't set \s-1SO_REUSEADDR:\s0 %s" 4
.el .IP "can't set \s-1SO_REUSEADDR:\s0 \f(CW%s\fR" 4
.IX Item "can't set SO_REUSEADDR: %s"
(Warning) \fBinndstart\fR attempts to set \s-1SO_REUSEADDR\s0 using \fIsetsockopt\fR\|(2) so
that if \fBinnd\fR exits, it can be restarted again immediately without
waiting for the port to time out.  For some reason, this failed, and that
option was not set on the port.
.ie n .IP "can't seteuid to %d:\fR \f(CW%s" 4
.el .IP "can't seteuid to \f(CW%d:\fR \f(CW%s\fR" 4
.IX Item "can't seteuid to %d: %s"
(Fatal) Unable to change the effective \s-1UID\s0.  If \fBinndstart\fR has the
correct permissions (setuid root) and seteuid to root (\s-1UID\s0 0) is failing,
this may mean that your system has \fIseteuid\fR\|(2) but doesn't have support for
\&\s-1POSIX\s0 saved UIDs.  If this is the case, please report this to the \s-1INN\s0
maintainers.
.ie n .IP "can't setgid to %d:\fR \f(CW%s" 4
.el .IP "can't setgid to \f(CW%d:\fR \f(CW%s\fR" 4
.IX Item "can't setgid to %d: %s"
(Fatal) Dropping privileges to the news group failed for some reason.
.ie n .IP "can't setgroups (is inndstart setuid root?): %s" 4
.el .IP "can't setgroups (is inndstart setuid root?): \f(CW%s\fR" 4
.IX Item "can't setgroups (is inndstart setuid root?): %s"
(Warning) Dropping all supplemental groups except the news group failed
for some reason, and the process group membership was left unchanged.
This almost always indicates that \fBinndstart\fR isn't setuid root as it has
to be to do what it does.  Make sure that \fBinndstart\fR is setuid root,
owned by group news, and mode 4710.
.ie n .IP "can't setuid to %d:\fR \f(CW%s" 4
.el .IP "can't setuid to \f(CW%d:\fR \f(CW%s\fR" 4
.IX Item "can't setuid to %d: %s"
(Fatal) Dropping privileges to the news user failed for some reason.
.ie n .IP "invalid address %s" 4
.el .IP "invalid address \f(CW%s\fR" 4
.IX Item "invalid address %s"
(Fatal) \fB\-I\fR was specified on the command line, but the argument wasn't a
valid address.  Addresses must be given as numeric \s-1IP\s0 addresses.
.IP "invalid bindaddress in inn.conf (%s)" 4
.IX Item "invalid bindaddress in inn.conf (%s)"
(Fatal) The \fIbindaddress\fR specified in \fIinn.conf\fR could not be converted
to an \s-1IP\s0 address.  See \fIinn.conf\fR\|(5) for more information about valid
values.
.ie n .IP "invalid port %s (must be a number)" 4
.el .IP "invalid port \f(CW%s\fR (must be a number)" 4
.IX Item "invalid port %s (must be a number)"
(Fatal) \fB\-P\fR was specified on the command line, but the argument wasn't a
valid port.  Ports must be port numbers; service names are not allowed.
.IP "missing address after \-I" 4
.IX Item "missing address after -I"
(Fatal) \fB\-I\fR was given on the command line, but no address was given
after the option.
.IP "missing port after \-P" 4
.IX Item "missing port after -P"
(Fatal) \fB\-P\fR was given on the command line, but no port was given after
the option.
.ie n .IP "must be run by user %s\fR (%d), not \f(CW%d" 4
.el .IP "must be run by user \f(CW%s\fR (%d), not \f(CW%d\fR" 4
.IX Item "must be run by user %s (%d), not %d"
(Fatal) Someone other than the news user attempted to run \fBinndstart\fR.
\&\fBinndstart\fR may only be run by the news user for security reasons.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Normally, \fBinndstart\fR is never run directly.  However, a simple way to
just restart \fBinnd\fR (if it is not running) without running any other
auxilliary programs or performing any of the other checks done by
\&\fIrc.news\fR\|(8) is to just run:
.PP
.Vb 1
\&    inndstart
.Ve
.PP
as the news user.
.PP
To start \fBinnd\fR on port 433, passing it the \f(CW\*(C`\-c21\*(C'\fR option, use:
.PP
.Vb 1
\&    inndstart \-P433 \-c21
.Ve
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
One environment variable affects the operation of \fBinndstart\fR itself:
.IP "\s-1INNCONF\s0" 8
.IX Item "INNCONF"
The full path to the \fIinn.conf\fR\|(5) file to read, rather than the default.
This can be used to run multiple copies of \s-1INN\s0 on the same machine with
different settings.
.PP
When executing \fBinnd\fR, \fBinndstart\fR cleans out the entire environmnent
and sets only the following variables:
.IP "\s-1BIND_INADDR\s0" 8
.IX Item "BIND_INADDR"
Passed verbatim from \fBinndstart\fR's environment.  This is used by various
programs to override the \fIbindaddress\fR parameter in \fIinn.conf\fR and
therefore must be in \fBinnd\fR's environment for programs like \fIinnfeed\fR\|(8).
.IP "\s-1HOME\s0" 8
.IX Item "HOME"
Set to \fIpathnews\fR from \fIinn.conf\fR.
.IP "\s-1LOGNAME\s0" 8
.IX Item "LOGNAME"
Set to the news master, as determined at configure time.
.IP "\s-1PATH\s0" 8
.IX Item "PATH"
Set to \fIpathbin\fR from \fIinn.conf\fR, \fIpathetc\fR from \fIinn.conf\fR, and then
\&\fI/bin\fR, \fI/usr/bin\fR, and \fI/usr/ucb\fR in that order.
.IP "\s-1SHELL\s0" 8
.IX Item "SHELL"
Set to the path to the system Bourne shell as determined by configure
(probably \fI/bin/sh\fR).
.IP "\s-1TMPDIR\s0" 8
.IX Item "TMPDIR"
Set to \fIpathtmp\fR from inn.conf.
.IP "\s-1TZ\s0" 8
.IX Item "TZ"
Passed verbatim from \fBinndstart\fR's environment.
.IP "\s-1USER\s0" 8
.IX Item "USER"
Set to the news master, as determined at configure time.
.SH "FILES"
.IX Header "FILES"
.IP "inn.conf" 4
.IX Item "inn.conf"
Read for \fIpathnews\fR, \fIpathbin\fR, \fIpathtmp\fR, \fIrlimitnofile\fR,
\&\fIbindaddress\fR, and \fIport\fR.
.IP "\fIpathbin\fR/innd" 4
.IX Item "pathbin/innd"
The binary that is executed as \fBinnd\fR and passed the open network socket.
.SH "HISTORY"
.IX Header "HISTORY"
Written by Russ Allbery <rra@stanford.edu> for InterNetNews.
.PP
$Id: inndstart.8 7880 2008-06-16 20:37:13Z iulius $
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIinn.conf\fR\|(5), \fIinnd\fR\|(8)