doc/pod/inndstart.pod

   1 =head1 NAME
   2
   3 inndstart - Start innd
   4
   5 =head1 SYNOPSIS
   6
   7 B<inndstart> [B<-P> I<port>] [B<-I> I<address>] [I<innd-options>]
   8
   9 =head1 DESCRIPTION
  10
  11 The purpose of B<inndstart> is to raise system file descriptor limits,
  12 open the privileged news transfer port, and then start innd(8), passing it
  13 the open file descriptor for the news port.  B<inndstart> is used since
  14 only privileged programs can perform those two operations and since
  15 B<innd> should not run with elevated privileges.  It is installed setuid
  16 root and drops privileges to the news user (as set at configure time)
  17 before running B<innd>.
  18
  19 Normally there is no need to run B<inndstart> directly.  Instead, run
  20 rc.news(8) as the news user, and it will handle running B<inndstart>
  21 appropriately for you.
  22
  23 Since B<inndstart> is setuid root, it is extremely restrictive about who
  24 can run it and what it is willing to do.  See L<"SECURITY"> for the full
  25 details.
  26
  27 B<inndstart> can only be run by the news user; if run by any other user,
  28 it will abort.  It will also only bind to ports 119, 433, or a port number
  29 given at configure time with B<--with-innd-port> among those ports below
  30 1024, although it can bind to any port above 1024.  This is to prevent
  31 various security exploits possible by binding to arbitrary privileged
  32 ports.
  33
  34 Before running B<innd>, B<inndstart> cleans out the environment and sets
  35 only those environment variables listed in L<"ENVIRONMENT">.
  36
  37 =head1 OPTIONS
  38
  39 =over 4
  40
  41 =item B<-P> I<port>
  42
  43 Bind to I<port> instead of whatever is specified by I<port> in
  44 F<inn.conf>.  Note that this is subject to the constraints mentioned
  45 above.
  46
  47 =item B<-I> I<address>
  48
  49 Bind as I<address> instead of whatever is specified by I<bindaddress> in
  50 F<inn.conf>.  The default behavior is to bind to INADDR_ANY, and that's
  51 what's desired almost all the time.  This option, and the F<inn.conf>
  52 parameter, may be useful if the machine has multiple interface cards and
  53 B<innd> should only be listening on a particular one.
  54
  55 =back
  56
  57 All other options given on the command line are passed verbatim to
  58 B<innd>.  In addition, B<inndstart> will give the B<-p> option to B<innd>,
  59 specifying the file descriptor of the open network socket.
  60
  61 =head1 SECURITY
  62
  63 B<inndstart> is setuid root, and therefore an expected point of attack.
  64 It has therefore been carefully written with security in mind.  In a
  65 normal INN installation, it is installed setuid root and executable only
  66 by users in the news group.
  67
  68 Ideally, everything about B<inndstart>'s operations would be hard-coded so
  69 that it could not be modified.  Fighting against this desire, however, is
  70 the ideal that as much of INN's operation as possible should be
  71 configurable at run-time using F<inn.conf>, and the news system should be
  72 able to an alternate inn.conf by setting INNCONF to the path to that file
  73 before starting any programs.  The configuration data therefore can't be
  74 trusted.
  75
  76 The security model used is:
  77
  78 =over 2
  79
  80 =item *
  81
  82 B<inndstart> can only be executed by the news user and news group, as
  83 determined at configure time and compiled into B<inndstart> as constants.
  84 Similarly, B<inndstart> will always setuid() and setgid() to those users
  85 before running B<innd>.  This is to prevent a user other than news but in
  86 the news group from using B<inndstart> to leverage that access into access
  87 to the news account.
  88
  89 =item *
  90
  91 As mentioned above, B<inndstart> will only bind to a very limited subset
  92 of ports below 1024.  There are various attacks that can be performed
  93 using random low-numbered ports, including exploits of the rsh(1) family
  94 of commands on some systems.
  95
  96 =item *
  97
  98 B<inndstart> does as little as possible as root, dropping privileges
  99 before performing any operations that do not require elevated privileges.
 100
 101 =back
 102
 103 This program therefore gives the news user the ability to revoke system
 104 file descriptor limits and bind to the news port, and nothing else.
 105
 106 =head1 DIAGNOSTICS
 107
 108 B<inndstart> may log the following messages to syslog and print them to
 109 stderr.
 110
 111 =over 4
 112
 113 =item can't bind: %s
 114
 115 (Fatal) Unable to bind to the designated port.  This usually means that
 116 something else is already running on the news port.  Check with
 117 netstat(8) and make sure that inetd(8) doesn't think it's running a
 118 service on the same port you're trying to run B<innd> on.
 119
 120 =item can't bind to restricted port %d
 121
 122 (Fatal) B<inndstart> was told to bind to a low numbered port (under 1024)
 123 other than 119, 433, or a port number given at configure time.  This is
 124 not allowed for security reasons.  If you're running B<innd> on a port
 125 other than 119 or 433, you need to give the --with-innd-port flag to
 126 C<configure> when you compile INN.
 127
 128 =item can't exec %s: %s
 129
 130 (Fatal) B<inndstart> was unable to execute B<innd>.  Make sure that
 131 I<pathbin> is set correctly in inn.conf and that B<innd> is located in
 132 that directory and is executable by the news user.
 133
 134 =item can't getgrnam(%s)
 135
 136 (Fatal) Unable to determine the GID for the compiled-in news group.
 137 Perhaps the news group is not listed in F</etc/group>.
 138
 139 =item can't getpwnam(%s)
 140
 141 (Fatal) Unable to determine the UID for the compiled-in news user.
 142 Perhaps the news user is not listed in F</etc/passwd>.
 143
 144 =item can't open socket: %s
 145
 146 (Fatal) Something went wrong in creating the network socket.  Chances are
 147 your system is out of resources of some kind.
 148
 149 =item can't set file descriptor limit to %d: %s
 150
 151 (Warning) Unable to set the system file descriptor limit to the specified
 152 value; the limit was left unchanged.  Perhaps that value is too high for
 153 your system.  Try changing I<rlimitnofile> in F<inn.conf> to a smaller
 154 value.
 155
 156 =item can't set SO_REUSEADDR: %s
 157
 158 (Warning) B<inndstart> attempts to set SO_REUSEADDR using setsockopt(2) so
 159 that if B<innd> exits, it can be restarted again immediately without
 160 waiting for the port to time out.  For some reason, this failed, and that
 161 option was not set on the port.
 162
 163 =item can't seteuid to %d: %s
 164
 165 (Fatal) Unable to change the effective UID.  If B<inndstart> has the
 166 correct permissions (setuid root) and seteuid to root (UID 0) is failing,
 167 this may mean that your system has seteuid(2) but doesn't have support for
 168 POSIX saved UIDs.  If this is the case, please report this to the INN
 169 maintainers.
 170
 171 =item can't setgid to %d: %s
 172
 173 (Fatal) Dropping privileges to the news group failed for some reason.
 174
 175 =item can't setgroups (is inndstart setuid root?): %s
 176
 177 (Warning) Dropping all supplemental groups except the news group failed
 178 for some reason, and the process group membership was left unchanged.
 179 This almost always indicates that B<inndstart> isn't setuid root as it has
 180 to be to do what it does.  Make sure that B<inndstart> is setuid root,
 181 owned by group news, and mode 4710.
 182
 183 =item can't setuid to %d: %s
 184
 185 (Fatal) Dropping privileges to the news user failed for some reason.
 186
 187 =item invalid address %s
 188
 189 (Fatal) B<-I> was specified on the command line, but the argument wasn't a
 190 valid address.  Addresses must be given as numeric IP addresses.
 191
 192 =item invalid bindaddress in inn.conf (%s)
 193
 194 (Fatal) The I<bindaddress> specified in F<inn.conf> could not be converted
 195 to an IP address.  See inn.conf(5) for more information about valid
 196 values.
 197
 198 =item invalid port %s (must be a number)
 199
 200 (Fatal) B<-P> was specified on the command line, but the argument wasn't a
 201 valid port.  Ports must be port numbers; service names are not allowed.
 202
 203 =item missing address after -I
 204
 205 (Fatal) B<-I> was given on the command line, but no address was given
 206 after the option.
 207
 208 =item missing port after -P
 209
 210 (Fatal) B<-P> was given on the command line, but no port was given after
 211 the option.
 212
 213 =item must be run by user %s (%d), not %d
 214
 215 (Fatal) Someone other than the news user attempted to run B<inndstart>.
 216 B<inndstart> may only be run by the news user for security reasons.
 217
 218 =back
 219
 220 =head1 EXAMPLES
 221
 222 Normally, B<inndstart> is never run directly.  However, a simple way to
 223 just restart B<innd> (if it is not running) without running any other
 224 auxilliary programs or performing any of the other checks done by
 225 rc.news(8) is to just run:
 226
 227     inndstart
 228
 229 as the news user.
 230
 231 To start B<innd> on port 433, passing it the C<-c21> option, use:
 232
 233     inndstart -P433 -c21
 234
 235 =head1 ENVIRONMENT
 236
 237 One environment variable affects the operation of B<inndstart> itself:
 238
 239 =over 8
 240
 241 =item INNCONF
 242
 243 The full path to the inn.conf(5) file to read, rather than the default.
 244 This can be used to run multiple copies of INN on the same machine with
 245 different settings.
 246
 247 =back
 248
 249 When executing B<innd>, B<inndstart> cleans out the entire environmnent
 250 and sets only the following variables:
 251
 252 =over 8
 253
 254 =item BIND_INADDR
 255
 256 Passed verbatim from B<inndstart>'s environment.  This is used by various
 257 programs to override the I<bindaddress> parameter in F<inn.conf> and
 258 therefore must be in B<innd>'s environment for programs like innfeed(8).
 259
 260 =item HOME
 261
 262 Set to I<pathnews> from F<inn.conf>.
 263
 264 =item LOGNAME
 265
 266 Set to the news master, as determined at configure time.
 267
 268 =item PATH
 269
 270 Set to I<pathbin> from F<inn.conf>, I<pathetc> from F<inn.conf>, and then
 271 F</bin>, F</usr/bin>, and F</usr/ucb> in that order.
 272
 273 =item SHELL
 274
 275 Set to the path to the system Bourne shell as determined by configure
 276 (probably F</bin/sh>).
 277
 278 =item TMPDIR
 279
 280 Set to I<pathtmp> from inn.conf.
 281
 282 =item TZ
 283
 284 Passed verbatim from B<inndstart>'s environment.
 285
 286 =item USER
 287
 288 Set to the news master, as determined at configure time.
 289
 290 =back
 291
 292 =head1 FILES
 293
 294 =over 4
 295
 296 =item inn.conf
 297
 298 Read for I<pathnews>, I<pathbin>, I<pathtmp>, I<rlimitnofile>,
 299 I<bindaddress>, and I<port>.
 300
 301 =item I<pathbin>/innd
 302
 303 The binary that is executed as B<innd> and passed the open network socket.
 304
 305 =back
 306
 307 =head1 HISTORY
 308
 309 Written by Russ Allbery E<lt>rra@stanford.eduE<gt> for InterNetNews.
 310
 311 $Id: inndstart.pod 5909 2002-12-03 05:17:18Z vinocur $
 312
 313 =head1 SEE ALSO
 314
 315 inn.conf(5), innd(8)
 316
 317 =cut