sbin/init/init.8

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Donn Seeley at Berkeley Software Design, Inc.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)init.8      8.3 (Berkeley) 4/18/94
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd August 6, 2019
  35 .Dt INIT 8
  36 .Os
  37 .Sh NAME
  38 .Nm init
  39 .Nd process control initialization
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Nm
  43 .Oo
  44 .Cm 0 | 1 | 6 |
  45 .Cm c | q
  46 .Oc
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility
  51 is the last stage of the boot process.
  52 It normally runs the automatic reboot sequence as described in
  53 .Xr rc 8 ,
  54 and if this succeeds, begins multi-user operation.
  55 If the reboot scripts fail,
  56 .Nm
  57 commences single-user operation by giving
  58 the super-user a shell on the console.
  59 The
  60 .Nm
  61 utility may be passed parameters
  62 from the boot program to
  63 prevent the system from going multi-user and to instead execute
  64 a single-user shell without starting the normal daemons.
  65 The system is then quiescent for maintenance work and may
  66 later be made to go to multi-user by exiting the
  67 single-user shell (with ^D).
  68 This
  69 causes
  70 .Nm
  71 to run the
  72 .Pa /etc/rc
  73 start up command file in fastboot mode (skipping disk checks).
  74 .Pp
  75 If the
  76 .Em console
  77 entry in the
  78 .Xr ttys 5
  79 file is marked
  80 .Dq insecure ,
  81 then
  82 .Nm
  83 will require that the super-user password be
  84 entered before the system will start a single-user shell.
  85 The password check is skipped if the
  86 .Em console
  87 is marked as
  88 .Dq secure .
  89 Note that the password check does not protect from variables
  90 such as
  91 .Va init_script
  92 being set from the
  93 .Xr loader 8
  94 command line; see the
  95 .Sx SECURITY
  96 section of
  97 .Xr loader 8 .
  98 .Pp
  99 If the system security level (see
 100 .Xr security 7 )
 101 is initially nonzero, then
 102 .Nm
 103 leaves it unchanged.
 104 Otherwise,
 105 .Nm
 106 raises the level to 1 before going multi-user for the first time.
 107 Since the level cannot be reduced, it will be at least 1 for
 108 subsequent operation, even on return to single-user.
 109 If a level higher than 1 is desired while running multi-user,
 110 it can be set before going multi-user, e.g., by the startup script
 111 .Xr rc 8 ,
 112 using
 113 .Xr sysctl 8
 114 to set the
 115 .Va kern.securelevel
 116 variable to the required security level.
 117 .Pp
 118 If
 119 .Nm
 120 is run in a jail, the security level of the
 121 .Dq host system
 122 will not be affected.
 123 Part of the information set up in the kernel to support a jail
 124 is a per-jail security level.
 125 This allows running a higher security level inside of a jail
 126 than that of the host system.
 127 See
 128 .Xr jail 8
 129 for more information about jails.
 130 .Pp
 131 In multi-user operation,
 132 .Nm
 133 maintains
 134 processes for the terminal ports found in the file
 135 .Xr ttys 5 .
 136 The
 137 .Nm
 138 utility reads this file and executes the command found in the second field,
 139 unless the first field refers to a device in
 140 .Pa /dev
 141 which is not configured.
 142 The first field is supplied as the final argument to the command.
 143 This command is usually
 144 .Xr getty 8 ;
 145 .Nm getty
 146 opens and initializes the tty line
 147 and
 148 executes the
 149 .Xr login 1
 150 program.
 151 The
 152 .Nm login
 153 program, when a valid user logs in,
 154 executes a shell for that user.
 155 When this shell
 156 dies, either because the user logged out
 157 or an abnormal termination occurred (a signal),
 158 the cycle is restarted by
 159 executing a new
 160 .Nm getty
 161 for the line.
 162 .Pp
 163 The
 164 .Nm
 165 utility can also be used to keep arbitrary daemons running,
 166 automatically restarting them if they die.
 167 In this case, the first field in the
 168 .Xr ttys 5
 169 file must not reference the path to a configured device node
 170 and will be passed to the daemon
 171 as the final argument on its command line.
 172 This is similar to the facility offered in the
 173 .At V
 174 .Pa /etc/inittab .
 175 .Pp
 176 Line status (on, off, secure, getty, or window information)
 177 may be changed in the
 178 .Xr ttys 5
 179 file without a reboot by sending the signal
 180 .Dv SIGHUP
 181 to
 182 .Nm
 183 with the command
 184 .Dq Li "kill -HUP 1" .
 185 On receipt of this signal,
 186 .Nm
 187 re-reads the
 188 .Xr ttys 5
 189 file.
 190 When a line is turned off in
 191 .Xr ttys 5 ,
 192 .Nm
 193 will send a SIGHUP signal to the controlling process
 194 for the session associated with the line.
 195 For any lines that were previously turned off in the
 196 .Xr ttys 5
 197 file and are now on,
 198 .Nm
 199 executes the command specified in the second field.
 200 If the command or window field for a line is changed,
 201 the change takes effect at the end of the current
 202 login session (e.g., the next time
 203 .Nm
 204 starts a process on the line).
 205 If a line is commented out or deleted from
 206 .Xr ttys 5 ,
 207 .Nm
 208 will not do anything at all to that line.
 209 .Pp
 210 The
 211 .Nm
 212 utility will terminate multi-user operations and resume single-user mode
 213 if sent a terminate
 214 .Pq Dv TERM
 215 signal, for example,
 216 .Dq Li "kill \-TERM 1" .
 217 If there are processes outstanding that are deadlocked (because of
 218 hardware or software failure),
 219 .Nm
 220 will not wait for them all to die (which might take forever), but
 221 will time out after 30 seconds and print a warning message.
 222 .Pp
 223 The
 224 .Nm
 225 utility will cease creating new processes
 226 and allow the system to slowly die away, if it is sent a terminal stop
 227 .Pq Dv TSTP
 228 signal, i.e.\&
 229 .Dq Li "kill \-TSTP 1" .
 230 A later hangup will resume full
 231 multi-user operations, or a terminate will start a single-user shell.
 232 This hook is used by
 233 .Xr reboot 8
 234 and
 235 .Xr halt 8 .
 236 .Pp
 237 The
 238 .Nm
 239 utility will terminate all possible processes (again, it will not wait
 240 for deadlocked processes) and reboot the machine if sent the interrupt
 241 .Pq Dv INT
 242 signal, i.e.\&
 243 .Dq Li "kill \-INT 1".
 244 This is useful for shutting the machine down cleanly from inside the kernel
 245 or from X when the machine appears to be hung.
 246 .Pp
 247 The
 248 .Nm
 249 utility will do the same, except it will halt the machine if sent
 250 the user defined signal 1
 251 .Pq Dv USR1 ,
 252 or will halt and turn the power off (if hardware permits) if sent
 253 the user defined signal 2
 254 .Pq Dv USR2 .
 255 .Pp
 256 When shutting down the machine,
 257 .Nm
 258 will try to run the
 259 .Pa /etc/rc.shutdown
 260 script.
 261 This script can be used to cleanly terminate specific programs such
 262 as
 263 .Nm innd
 264 (the InterNetNews server).
 265 If this script does not terminate within 120 seconds,
 266 .Nm
 267 will terminate it.
 268 The timeout can be configured via the
 269 .Xr sysctl 8
 270 variable
 271 .Va kern.init_shutdown_timeout .
 272 .Pp
 273 .Nm init
 274 passes
 275 .Dq Li single
 276 as the argument to the shutdown script if return to single-user mode
 277 is requested.
 278 Otherwise,
 279 .Dq Li reboot
 280 argument is used.
 281 .Pp
 282 The role of
 283 .Nm
 284 is so critical that if it dies, the system will reboot itself
 285 automatically.
 286 If, at bootstrap time, the
 287 .Nm
 288 process cannot be located, the system will panic with the message
 289 .Dq "panic: init died (signal %d, exit %d)" .
 290 .Pp
 291 If run as a user process as shown in the second synopsis line,
 292 .Nm
 293 will emulate
 294 .At V
 295 behavior, i.e., super-user can specify the desired
 296 .Em run-level
 297 on a command line, and
 298 .Nm
 299 will signal the original
 300 (PID 1)
 301 .Nm
 302 as follows:
 303 .Bl -column Run-level SIGTERM
 304 .It Sy "Run-level       Signal  Action"
 305 .It Cm 0 Ta Dv SIGUSR1 Ta "Halt"
 306 .It Cm 0 Ta Dv SIGUSR2 Ta "Halt and turn the power off"
 307 .It Cm 0 Ta Dv SIGWINCH Ta "Halt and turn the power off and then back on"
 308 .It Cm 1 Ta Dv SIGTERM Ta "Go to single-user mode"
 309 .It Cm 6 Ta Dv SIGINT Ta "Reboot the machine"
 310 .It Cm c Ta Dv SIGTSTP Ta "Block further logins"
 311 .It Cm q Ta Dv SIGHUP Ta Rescan the
 312 .Xr ttys 5
 313 file
 314 .El
 315 .Sh KERNEL ENVIRONMENT VARIABLES
 316 The following
 317 .Xr kenv 2
 318 variables are available as
 319 .Xr loader 8
 320 tunables:
 321 .Bl -tag -width indent
 322 .It Va init_chroot
 323 If set to a valid directory in the root file system, it causes
 324 .Nm
 325 to perform a
 326 .Xr chroot 2
 327 operation on that directory, making it the new root directory.
 328 That happens before entering single-user mode or multi-user
 329 mode (but after executing the
 330 .Va init_script
 331 if enabled).
 332 This functionality has generally been eclipsed by rerooting.
 333 See
 334 .Xr reboot 8
 335 .Fl r
 336 for details.
 337 .It Va init_exec
 338 If set to a valid file name in the root file system,
 339 instructs
 340 .Nm
 341 to directly execute that file as the very first action,
 342 replacing
 343 .Nm
 344 as PID 1.
 345 .It Va init_script
 346 If set to a valid file name in the root file system,
 347 instructs
 348 .Nm
 349 to run that script as the very first action,
 350 before doing anything else.
 351 Signal handling and exit code interpretation is similar to
 352 running the
 353 .Pa /etc/rc
 354 script.
 355 In particular, single-user operation is enforced
 356 if the script terminates with a non-zero exit code,
 357 or if a SIGTERM is delivered to the
 358 .Nm
 359 process (PID 1).
 360 This functionality has generally been eclipsed by rerooting.
 361 See
 362 .Xr reboot 8
 363 .Fl r
 364 for details.
 365 .It Va init_shell
 366 Defines the shell binary to be used for executing the various shell scripts.
 367 The default is
 368 .Dq Li /bin/sh .
 369 It is used for running the
 370 .Va init_exec
 371 or
 372 .Va init_script
 373 if set, as well as for the
 374 .Pa /etc/rc
 375 and
 376 .Pa /etc/rc.shutdown
 377 scripts.
 378 The value of the corresponding
 379 .Xr kenv 2
 380 variable is evaluated every time
 381 .Nm
 382 calls a shell script, so it can be changed later on using the
 383 .Xr kenv 1
 384 utility.
 385 In particular, if a non-default shell is used for running an
 386 .Va init_script ,
 387 it might be desirable to have that script reset the value of
 388 .Va init_shell
 389 back to the default, so that the
 390 .Pa /etc/rc
 391 script is executed with the standard shell
 392 .Pa /bin/sh .
 393 .Sh FILES
 394 .Bl -tag -width /var/log/init.log -compact
 395 .It Pa /dev/console
 396 system console device
 397 .It Pa /dev/tty*
 398 terminal ports found in
 399 .Xr ttys 5
 400 .It Pa /etc/ttys
 401 the terminal initialization information file
 402 .It Pa /etc/rc
 403 system startup commands
 404 .It Pa /etc/rc.shutdown
 405 system shutdown commands
 406 .It Pa /var/log/init.log
 407 log of
 408 .Xr rc 8
 409 output if the system console device is not available
 410 .El
 411 .Sh DIAGNOSTICS
 412 .Bl -diag
 413 .It "getty repeating too quickly on port %s, sleeping."
 414 A process being started to service a line is exiting quickly
 415 each time it is started.
 416 This is often caused by a ringing or noisy terminal line.
 417 .Bf -emphasis
 418 Init will sleep for 30 seconds,
 419 then continue trying to start the process.
 420 .Ef
 421 .It "some processes would not die; ps axl advised."
 422 A process
 423 is hung and could not be killed when the system was shutting down.
 424 This condition is usually caused by a process
 425 that is stuck in a device driver because of
 426 a persistent device error condition.
 427 .El
 428 .Sh SEE ALSO
 429 .Xr kill 1 ,
 430 .Xr login 1 ,
 431 .Xr sh 1 ,
 432 .Xr ttys 5 ,
 433 .Xr security 7 ,
 434 .Xr getty 8 ,
 435 .Xr halt 8 ,
 436 .Xr jail 8 ,
 437 .Xr rc 8 ,
 438 .Xr reboot 8 ,
 439 .Xr shutdown 8 ,
 440 .Xr sysctl 8
 441 .Sh HISTORY
 442 An
 443 .Nm
 444 utility appeared in
 445 .At v1 .
 446 .Sh CAVEATS
 447 Systems without
 448 .Xr sysctl 8
 449 behave as though they have security level \-1.
 450 .Pp
 451 Setting the security level above 1 too early in the boot sequence can
 452 prevent
 453 .Xr fsck 8
 454 from repairing inconsistent file systems.
 455 The
 456 preferred location to set the security level is at the end of
 457 .Pa /etc/rc
 458 after all multi-user startup actions are complete.