=head1 NAME

inndstart - Start innd

=head1 SYNOPSIS

B<inndstart> [B<-P> I<port>] [B<-I> I<address>] [I<innd-options>]

=head1 DESCRIPTION

The purpose of B<inndstart> is to raise system file descriptor limits,
open the privileged news transfer port, and then start innd(8), passing it
the open file descriptor for the news port.  B<inndstart> is used since
only privileged programs can perform those two operations and since
B<innd> should not run privileged.  It is installed setuid root and drops
privileges to the news user (set at configure time) before running
B<innd>.

Normally there is no need to run B<inndstart> directly.  Instead, run
rc.news(8) as the news user, and it will handle running B<inndstart>
appropriately for you.

Since B<inndstart> is setuid root, it is extremely restrictive about who
can run it and what it is willing to do.  See L<"SECURITY"> for the full
details.

B<inndstart> 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 B<--with-innd-port> 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.

Before running B<innd>, B<inndstart> cleans out the environment and sets
only those environment variables listed in L<"ENVIRONMENT">.

=head1 OPTIONS

=over 4

=item B<-P> I<port>

Bind to I<port> instead of whatever is specified by I<port> in
inn.conf(5).  Note that this is subject to the constraints mentioned
above.

=item B<-I> I<address>

Bind as I<address> instead of whatever is specified by I<bindaddress> in
inn.conf(5).  The default behavior is to bind to INADDR_ANY, and that's
what's desired almost all the time.  This option, and the inn.conf(5)
parameter, may be useful if the machine has multiple interface cards and
B<innd> should only be listening on a particular one.

=back

All other options given on the command line are passed verbatim to
B<innd>.  In addition, B<inndstart> will give the B<-p> option to B<innd>,
specifying the file descriptor of the open network socket.

=head1 SECURITY

B<inndstart> is setuid root, and therefore an expected point of attack.
It has therefore been carefully written with security in mind.  In a
normal INN installation, it is installed setuid root and executable only
by users in the news group.

Ideally, everything about B<inndstart>'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 INN's operation as possible should be
configurable at run-time using inn.conf(5), and the news system should be
able to an alternate inn.conf by setting INNCONF to the path to that file
before starting any programs.  The configuration data therefore can't be
trusted.

The security model used is:

=over 2

=item *

B<inndstart> can only be executed by the news user and news group, as
determined at configure time and compiled into B<inndstart> as constants.
Similarly, B<inndstart> will always setuid() and setgid() to those users
before running B<innd>.  This is to prevent a user other than news but in
the news group from using B<inndstart> to leverage that access into access
to the news account.

=item *

As mentioned above, B<inndstart> will only bind to a very limited set of
ports below 1024.  There are various attacks that can be performed using
random low-numbered ports, including exploits of the rsh family of
commands on some systems.

=item *

B<inndstart> does as little as possible as root, dropping privileges
before performing any operations that do not require elevated privileges.

=back

This program therefore gives the news user the ability to revoke system
file descriptor limits and bind to the news port, and nothing else.

=head1 DIAGNOSTICS

B<inndstart> may log the following messages to syslog (like the rest of
INN, syslog is the best place to find detailed debugging information):

=over 4

=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
netstat(8) and make sure that inetd(8) doesn't think it's running a
service on the same port you're trying to run B<innd> on.

=item can't exec %s: %s

(Fatal) B<inndstart> was unable to execute B<innd>.  Make sure that
I<pathbin> is set correctly in inn.conf and that B<innd> is located in
that directory and is executable by the news user.

=item can't getrlimit(NOFILE)

(Warning) Unable to obtain the current system resource limit on file
descriptors.  Chances are something is wrong with the *rlimit()
functions.  The file descriptor limit was left unchanged from the system
default.

=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.

=item can't setgid(%d): %s

(Fatal) Dropping privileges to the news group failed for some reason.

=item can't setgroups: %s

(Warning) Dropping all supplemental groups except the news group failed
for some reason, and the process group membership was left unchanged.
This message may indicate a minor security hole if the news user is in
extra groups.

=item can't setrlimit(NOFILE, %d)

(Warning) Unable to set the system file descriptor limit to the specified
value.  Either that value is too high for your system or something else
went wrong.  The file descriptor limit was left unchanged.  Try changing
I<rlimitnofile> in inn.conf to a smaller value.

=item can't setsockopt: %s

(Warning) B<inndstart> attempts to set SO_REUSEADDR so that if B<innd>
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.

=item can't setuid(%d): %s

(Fatal) Dropping privileges to the news user failed for some reason.

=item can't stat pathrun (%s): %s

(Fatal) I<pathrun> as specified in inn.conf doesn't exist.

=item getgrnam(%s) failed

(Fatal) Unable to determine the GID for the compiled-in news group.  Is
the news group listed in /etc/group?

=item getpwnam(%s) failed

(Fatal) Unable to determine the UID for the compiled-in news user.  Is the
news user listed in /etc/passwd?

=item invalid address %s

(Fatal) B<-I> was specified on the command line, but the argument wasn't a
valid address.  Addresses must be given as numeric IP addresses.

=item invalid bindaddress in inn.conf (%s)

(Fatal) The I<bindaddress> specified in inn.conf could not be converted to
an IP address.  See inn.conf(5) for more information about valid values.

=item invalid port %s

(Fatal) B<-P> was specified on the command line, but the argument wasn't a
valid port.  Ports must be port numbers; service names are not allowed.

=item missing address after -I

(Fatal) B<-I> was given on the command line, but no address was given
after the option.

=item missing port after -P

(Fatal) B<-P> was given on the command line, but no port was given after
the option.

=item pathrun (%s) not a directory

(Fatal) I<pathrun> as specified in inn.conf isn't a directory.  This is
where B<innd> will create its local control socket; it should always be a
directory.

=item pathrun (%s) owned by group %d, not %s (%d)

(Fatal) I<pathrun> specified in inn.conf must be owned by the news group.
This is checked for security reasons.

=item pathrun (%s) owned by user %d, not %s (%d)

(Fatal) I<pathrun> specified in inn.conf must be owned by the news user.
This is checked for security reasons.

=item ran by GID %d, who isn't %s (%d)

(Fatal) Someone not in the news group attempted to run B<inndstart>.  If
you were running B<inndstart> as the news user, make sure that the news
user's default group is the news group you picked at compile time (C<news>
by default).

=item ran by UID %d, who isn't %s (%d)

(Fatal) Someone other than the news user attempted to run B<inndstart>.
B<inndstart> may only be run by the news user for security reasons.

=item seteuid(%d) failed: %s

(Fatal) Unable to change the effective UID.  This usually means that
B<inndstart> was installed with the wrong permissions.  If it does have
the correct permissions (setuid root) and seteuid() to root (UID 0) is
failing, this may mean that your system has seteuid() but doesn't have
support for POSIX saved UIDs.  If this is the case, please report this to
the INN maintainers.

=item setreuid(%d, %d) failed: %s

(Fatal) Unable to change the real and effective UIDs.  This message
usually means that B<inndstart> was installed with the wrong permissions.

=item tried to bind to port %d

(Fatal) B<inndstart> 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.

=back

=head1 EXAMPLES

Normally, B<inndstart> is never run directly.  However, a simple way to
just restart B<innd> without running any other auxilliary programs or
performing any of the other checks done by rc.news(8) is to just run:

    inndstart

as the news user.

To start B<innd> on port 433, passing it the C<-c21> option, use:

    inndstart -P433 -c21

=head1 ENVIRONMENT

One environment variable affects the operation of B<inndstart> itself:

=over 8

=item INNCONF

The full path to the inn.conf(5) file to read, rather than the default.
This can be used to run multiple copies of INN on the same machine with
different settings.

=back

When executing B<innd>, B<inndstart> cleans out the entire environmnent
and sets only the following variables:

=over 8

=item BIND_INADDR

Passed verbatim from B<inndstart>'s environment.  This is apparently used
on Linux.

=item HOME

Set to I<pathnews> from inn.conf.

=item LOGNAME

Set to the news master, as determined at configure time.

=item PATH

Set to I<pathbin> from inn.conf, I<pathetc> from inn.conf, and then /bin,
/usr/bin, and /usr/ucb in that order.

=item SHELL

Set to the path to the system Bourne shell as determined by configure
(probably /bin/sh).

=item TMPDIR

Set to I<pathtmp> from inn.conf.

=item TZ

Passed verbatim from B<inndstart>'s environment.

=item USER

Set to the news master, as determined at configure time.

=back

=head1 FILES

=over 4

=item inn.conf

Read for I<pathnews>, I<pathbin>, I<pathrun>, I<pathtmp>, I<rlimitnofile>,
I<bindaddress>, and I<port>.

=item I<pathbin>/innd

The binary that is executed as B<innd> and passed the open network socket.

=item I<pathrun>

Checked for existence and the right ownership.

=back

=head1 HISTORY

Written by Russ Allbery E<lt>rra@stanford.eduE<gt> for InterNetNews.

$Id: inndstart.pod,v 1.2 1999/10/23 16:25:47 rra Exp $

=head1 SEE ALSO

inn.conf(5), innd(8)

=cut
