doc/man/inndstart.8

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "INNDSTART 8"
 132 .TH INNDSTART 8 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
 133 .SH "NAME"
 134 inndstart \- Start innd
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBinndstart\fR [\fB\-P\fR \fIport\fR] [\fB\-I\fR \fIaddress\fR] [\fIinnd-options\fR]
 138 .SH "DESCRIPTION"
 139 .IX Header "DESCRIPTION"
 140 The purpose of \fBinndstart\fR is to raise system file descriptor limits,
 141 open the privileged news transfer port, and then start \fIinnd\fR\|(8), passing it
 142 the open file descriptor for the news port.  \fBinndstart\fR is used since
 143 only privileged programs can perform those two operations and since
 144 \&\fBinnd\fR should not run with elevated privileges.  It is installed setuid
 145 root and drops privileges to the news user (as set at configure time)
 146 before running \fBinnd\fR.
 147 .PP
 148 Normally there is no need to run \fBinndstart\fR directly.  Instead, run
 149 \&\fIrc.news\fR\|(8) as the news user, and it will handle running \fBinndstart\fR
 150 appropriately for you.
 151 .PP
 152 Since \fBinndstart\fR is setuid root, it is extremely restrictive about who
 153 can run it and what it is willing to do.  See \*(L"\s-1SECURITY\s0\*(R" for the full
 154 details.
 155 .PP
 156 \&\fBinndstart\fR can only be run by the news user; if run by any other user,
 157 it will abort.  It will also only bind to ports 119, 433, or a port number
 158 given at configure time with \fB\-\-with\-innd\-port\fR among those ports below
 159 1024, although it can bind to any port above 1024.  This is to prevent
 160 various security exploits possible by binding to arbitrary privileged
 161 ports.
 162 .PP
 163 Before running \fBinnd\fR, \fBinndstart\fR cleans out the environment and sets
 164 only those environment variables listed in \*(L"\s-1ENVIRONMENT\s0\*(R".
 165 .SH "OPTIONS"
 166 .IX Header "OPTIONS"
 167 .IP "\fB\-P\fR \fIport\fR" 4
 168 .IX Item "-P port"
 169 Bind to \fIport\fR instead of whatever is specified by \fIport\fR in
 170 \&\fIinn.conf\fR.  Note that this is subject to the constraints mentioned
 171 above.
 172 .IP "\fB\-I\fR \fIaddress\fR" 4
 173 .IX Item "-I address"
 174 Bind as \fIaddress\fR instead of whatever is specified by \fIbindaddress\fR in
 175 \&\fIinn.conf\fR.  The default behavior is to bind to \s-1INADDR_ANY\s0, and that's
 176 what's desired almost all the time.  This option, and the \fIinn.conf\fR
 177 parameter, may be useful if the machine has multiple interface cards and
 178 \&\fBinnd\fR should only be listening on a particular one.
 179 .PP
 180 All other options given on the command line are passed verbatim to
 181 \&\fBinnd\fR.  In addition, \fBinndstart\fR will give the \fB\-p\fR option to \fBinnd\fR,
 182 specifying the file descriptor of the open network socket.
 183 .SH "SECURITY"
 184 .IX Header "SECURITY"
 185 \&\fBinndstart\fR is setuid root, and therefore an expected point of attack.
 186 It has therefore been carefully written with security in mind.  In a
 187 normal \s-1INN\s0 installation, it is installed setuid root and executable only
 188 by users in the news group.
 189 .PP
 190 Ideally, everything about \fBinndstart\fR's operations would be hard-coded so
 191 that it could not be modified.  Fighting against this desire, however, is
 192 the ideal that as much of \s-1INN\s0's operation as possible should be
 193 configurable at run-time using \fIinn.conf\fR, and the news system should be
 194 able to an alternate inn.conf by setting \s-1INNCONF\s0 to the path to that file
 195 before starting any programs.  The configuration data therefore can't be
 196 trusted.
 197 .PP
 198 The security model used is:
 199 .IP "\(bu" 2
 200 \&\fBinndstart\fR can only be executed by the news user and news group, as
 201 determined at configure time and compiled into \fBinndstart\fR as constants.
 202 Similarly, \fBinndstart\fR will always \fIsetuid()\fR and \fIsetgid()\fR to those users
 203 before running \fBinnd\fR.  This is to prevent a user other than news but in
 204 the news group from using \fBinndstart\fR to leverage that access into access
 205 to the news account.
 206 .IP "\(bu" 2
 207 As mentioned above, \fBinndstart\fR will only bind to a very limited subset
 208 of ports below 1024.  There are various attacks that can be performed
 209 using random low-numbered ports, including exploits of the \fIrsh\fR\|(1) family
 210 of commands on some systems.
 211 .IP "\(bu" 2
 212 \&\fBinndstart\fR does as little as possible as root, dropping privileges
 213 before performing any operations that do not require elevated privileges.
 214 .PP
 215 This program therefore gives the news user the ability to revoke system
 216 file descriptor limits and bind to the news port, and nothing else.
 217 .SH "DIAGNOSTICS"
 218 .IX Header "DIAGNOSTICS"
 219 \&\fBinndstart\fR may log the following messages to syslog and print them to
 220 stderr.
 221 .ie n .IP "can't bind: %s" 4
 222 .el .IP "can't bind: \f(CW%s\fR" 4
 223 .IX Item "can't bind: %s"
 224 (Fatal) Unable to bind to the designated port.  This usually means that
 225 something else is already running on the news port.  Check with
 226 \&\fInetstat\fR\|(8) and make sure that \fIinetd\fR\|(8) doesn't think it's running a
 227 service on the same port you're trying to run \fBinnd\fR on.
 228 .ie n .IP "can't bind to restricted port %d" 4
 229 .el .IP "can't bind to restricted port \f(CW%d\fR" 4
 230 .IX Item "can't bind to restricted port %d"
 231 (Fatal) \fBinndstart\fR was told to bind to a low numbered port (under 1024)
 232 other than 119, 433, or a port number given at configure time.  This is
 233 not allowed for security reasons.  If you're running \fBinnd\fR on a port
 234 other than 119 or 433, you need to give the \-\-with\-innd\-port flag to
 235 \&\f(CW\*(C`configure\*(C'\fR when you compile \s-1INN\s0.
 236 .ie n .IP "can't exec %s:\fR \f(CW%s" 4
 237 .el .IP "can't exec \f(CW%s:\fR \f(CW%s\fR" 4
 238 .IX Item "can't exec %s: %s"
 239 (Fatal) \fBinndstart\fR was unable to execute \fBinnd\fR.  Make sure that
 240 \&\fIpathbin\fR is set correctly in inn.conf and that \fBinnd\fR is located in
 241 that directory and is executable by the news user.
 242 .IP "can't getgrnam(%s)" 4
 243 .IX Item "can't getgrnam(%s)"
 244 (Fatal) Unable to determine the \s-1GID\s0 for the compiled-in news group.
 245 Perhaps the news group is not listed in \fI/etc/group\fR.
 246 .IP "can't getpwnam(%s)" 4
 247 .IX Item "can't getpwnam(%s)"
 248 (Fatal) Unable to determine the \s-1UID\s0 for the compiled-in news user.
 249 Perhaps the news user is not listed in \fI/etc/passwd\fR.
 250 .ie n .IP "can't open socket: %s" 4
 251 .el .IP "can't open socket: \f(CW%s\fR" 4
 252 .IX Item "can't open socket: %s"
 253 (Fatal) Something went wrong in creating the network socket.  Chances are
 254 your system is out of resources of some kind.
 255 .ie n .IP "can't set file descriptor limit to %d:\fR \f(CW%s" 4
 256 .el .IP "can't set file descriptor limit to \f(CW%d:\fR \f(CW%s\fR" 4
 257 .IX Item "can't set file descriptor limit to %d: %s"
 258 (Warning) Unable to set the system file descriptor limit to the specified
 259 value; the limit was left unchanged.  Perhaps that value is too high for
 260 your system.  Try changing \fIrlimitnofile\fR in \fIinn.conf\fR to a smaller
 261 value.
 262 .ie n .IP "can't set \s-1SO_REUSEADDR:\s0 %s" 4
 263 .el .IP "can't set \s-1SO_REUSEADDR:\s0 \f(CW%s\fR" 4
 264 .IX Item "can't set SO_REUSEADDR: %s"
 265 (Warning) \fBinndstart\fR attempts to set \s-1SO_REUSEADDR\s0 using \fIsetsockopt\fR\|(2) so
 266 that if \fBinnd\fR exits, it can be restarted again immediately without
 267 waiting for the port to time out.  For some reason, this failed, and that
 268 option was not set on the port.
 269 .ie n .IP "can't seteuid to %d:\fR \f(CW%s" 4
 270 .el .IP "can't seteuid to \f(CW%d:\fR \f(CW%s\fR" 4
 271 .IX Item "can't seteuid to %d: %s"
 272 (Fatal) Unable to change the effective \s-1UID\s0.  If \fBinndstart\fR has the
 273 correct permissions (setuid root) and seteuid to root (\s-1UID\s0 0) is failing,
 274 this may mean that your system has \fIseteuid\fR\|(2) but doesn't have support for
 275 \&\s-1POSIX\s0 saved UIDs.  If this is the case, please report this to the \s-1INN\s0
 276 maintainers.
 277 .ie n .IP "can't setgid to %d:\fR \f(CW%s" 4
 278 .el .IP "can't setgid to \f(CW%d:\fR \f(CW%s\fR" 4
 279 .IX Item "can't setgid to %d: %s"
 280 (Fatal) Dropping privileges to the news group failed for some reason.
 281 .ie n .IP "can't setgroups (is inndstart setuid root?): %s" 4
 282 .el .IP "can't setgroups (is inndstart setuid root?): \f(CW%s\fR" 4
 283 .IX Item "can't setgroups (is inndstart setuid root?): %s"
 284 (Warning) Dropping all supplemental groups except the news group failed
 285 for some reason, and the process group membership was left unchanged.
 286 This almost always indicates that \fBinndstart\fR isn't setuid root as it has
 287 to be to do what it does.  Make sure that \fBinndstart\fR is setuid root,
 288 owned by group news, and mode 4710.
 289 .ie n .IP "can't setuid to %d:\fR \f(CW%s" 4
 290 .el .IP "can't setuid to \f(CW%d:\fR \f(CW%s\fR" 4
 291 .IX Item "can't setuid to %d: %s"
 292 (Fatal) Dropping privileges to the news user failed for some reason.
 293 .ie n .IP "invalid address %s" 4
 294 .el .IP "invalid address \f(CW%s\fR" 4
 295 .IX Item "invalid address %s"
 296 (Fatal) \fB\-I\fR was specified on the command line, but the argument wasn't a
 297 valid address.  Addresses must be given as numeric \s-1IP\s0 addresses.
 298 .IP "invalid bindaddress in inn.conf (%s)" 4
 299 .IX Item "invalid bindaddress in inn.conf (%s)"
 300 (Fatal) The \fIbindaddress\fR specified in \fIinn.conf\fR could not be converted
 301 to an \s-1IP\s0 address.  See \fIinn.conf\fR\|(5) for more information about valid
 302 values.
 303 .ie n .IP "invalid port %s (must be a number)" 4
 304 .el .IP "invalid port \f(CW%s\fR (must be a number)" 4
 305 .IX Item "invalid port %s (must be a number)"
 306 (Fatal) \fB\-P\fR was specified on the command line, but the argument wasn't a
 307 valid port.  Ports must be port numbers; service names are not allowed.
 308 .IP "missing address after \-I" 4
 309 .IX Item "missing address after -I"
 310 (Fatal) \fB\-I\fR was given on the command line, but no address was given
 311 after the option.
 312 .IP "missing port after \-P" 4
 313 .IX Item "missing port after -P"
 314 (Fatal) \fB\-P\fR was given on the command line, but no port was given after
 315 the option.
 316 .ie n .IP "must be run by user %s\fR (%d), not \f(CW%d" 4
 317 .el .IP "must be run by user \f(CW%s\fR (%d), not \f(CW%d\fR" 4
 318 .IX Item "must be run by user %s (%d), not %d"
 319 (Fatal) Someone other than the news user attempted to run \fBinndstart\fR.
 320 \&\fBinndstart\fR may only be run by the news user for security reasons.
 321 .SH "EXAMPLES"
 322 .IX Header "EXAMPLES"
 323 Normally, \fBinndstart\fR is never run directly.  However, a simple way to
 324 just restart \fBinnd\fR (if it is not running) without running any other
 325 auxilliary programs or performing any of the other checks done by
 326 \&\fIrc.news\fR\|(8) is to just run:
 327 .PP
 328 .Vb 1
 329 \&    inndstart
 330 .Ve
 331 .PP
 332 as the news user.
 333 .PP
 334 To start \fBinnd\fR on port 433, passing it the \f(CW\*(C`\-c21\*(C'\fR option, use:
 335 .PP
 336 .Vb 1
 337 \&    inndstart \-P433 \-c21
 338 .Ve
 339 .SH "ENVIRONMENT"
 340 .IX Header "ENVIRONMENT"
 341 One environment variable affects the operation of \fBinndstart\fR itself:
 342 .IP "\s-1INNCONF\s0" 8
 343 .IX Item "INNCONF"
 344 The full path to the \fIinn.conf\fR\|(5) file to read, rather than the default.
 345 This can be used to run multiple copies of \s-1INN\s0 on the same machine with
 346 different settings.
 347 .PP
 348 When executing \fBinnd\fR, \fBinndstart\fR cleans out the entire environmnent
 349 and sets only the following variables:
 350 .IP "\s-1BIND_INADDR\s0" 8
 351 .IX Item "BIND_INADDR"
 352 Passed verbatim from \fBinndstart\fR's environment.  This is used by various
 353 programs to override the \fIbindaddress\fR parameter in \fIinn.conf\fR and
 354 therefore must be in \fBinnd\fR's environment for programs like \fIinnfeed\fR\|(8).
 355 .IP "\s-1HOME\s0" 8
 356 .IX Item "HOME"
 357 Set to \fIpathnews\fR from \fIinn.conf\fR.
 358 .IP "\s-1LOGNAME\s0" 8
 359 .IX Item "LOGNAME"
 360 Set to the news master, as determined at configure time.
 361 .IP "\s-1PATH\s0" 8
 362 .IX Item "PATH"
 363 Set to \fIpathbin\fR from \fIinn.conf\fR, \fIpathetc\fR from \fIinn.conf\fR, and then
 364 \&\fI/bin\fR, \fI/usr/bin\fR, and \fI/usr/ucb\fR in that order.
 365 .IP "\s-1SHELL\s0" 8
 366 .IX Item "SHELL"
 367 Set to the path to the system Bourne shell as determined by configure
 368 (probably \fI/bin/sh\fR).
 369 .IP "\s-1TMPDIR\s0" 8
 370 .IX Item "TMPDIR"
 371 Set to \fIpathtmp\fR from inn.conf.
 372 .IP "\s-1TZ\s0" 8
 373 .IX Item "TZ"
 374 Passed verbatim from \fBinndstart\fR's environment.
 375 .IP "\s-1USER\s0" 8
 376 .IX Item "USER"
 377 Set to the news master, as determined at configure time.
 378 .SH "FILES"
 379 .IX Header "FILES"
 380 .IP "inn.conf" 4
 381 .IX Item "inn.conf"
 382 Read for \fIpathnews\fR, \fIpathbin\fR, \fIpathtmp\fR, \fIrlimitnofile\fR,
 383 \&\fIbindaddress\fR, and \fIport\fR.
 384 .IP "\fIpathbin\fR/innd" 4
 385 .IX Item "pathbin/innd"
 386 The binary that is executed as \fBinnd\fR and passed the open network socket.
 387 .SH "HISTORY"
 388 .IX Header "HISTORY"
 389 Written by Russ Allbery <rra@stanford.edu> for InterNetNews.
 390 .PP
 391 $Id: inndstart.8 7880 2008-06-16 20:37:13Z iulius $
 392 .SH "SEE ALSO"
 393 .IX Header "SEE ALSO"
 394 \&\fIinn.conf\fR\|(5), \fIinnd\fR\|(8)