------------------------------------------------------------ revno: 1581 committer: James Hunt <[email protected]> branch nick: upstart timestamp: Fri 2013-12-20 15:13:45 +0000 message: * init/man/init.8: - Added Job States and Job Lifecycle sections (taken from Ubuntu+Debian specific upstart-events(7) since this information is distro-agnostic) (debian bug#732125). - Updated date+copyright. * util/man/initctl.8: - Added reference to Job States section in init(8). - Updated date+copyright. modified: ChangeLog init/man/init.8 util/man/initctl.8
-- lp:upstart https://code.launchpad.net/~upstart-devel/upstart/trunk Your team Upstart Reviewers is subscribed to branch lp:upstart. To unsubscribe from this branch go to https://code.launchpad.net/~upstart-devel/upstart/trunk/+edit-subscription
=== modified file 'ChangeLog' --- ChangeLog 2013-12-19 17:09:54 +0000 +++ ChangeLog 2013-12-20 15:13:45 +0000 @@ -1,3 +1,14 @@ +2013-12-20 James Hunt <[email protected]> + + * init/man/init.8: + - Added Job States and Job Lifecycle sections (taken from + Ubuntu+Debian specific upstart-events(7) since this information + is distro-agnostic) (debian bug#732125). + - Updated date+copyright. + * util/man/initctl.8: + - Added reference to Job States section in init(8). + - Updated date+copyright. + 2013-12-19 James Hunt <[email protected]> * init/man/init.5: Provide more detail on setuid and setgid stanzas === modified file 'init/man/init.8' --- init/man/init.8 2013-09-19 17:38:17 +0000 +++ init/man/init.8 2013-12-20 15:13:45 +0000 @@ -1,4 +1,4 @@ -.TH init 8 2012-12-18 "Upstart" +.TH init 8 2013-12-20 "Upstart" .\" .SH NAME init \- Upstart process management daemon @@ -49,6 +49,194 @@ .BR stopped (7) events emitted as jobs change state. .\" +.SS Job States +.P +\fBTable 1: Job Goals and State Transitions.\fP +.TS +box,tab(@); +c | c s +c | c s +c | c | c +c | l l. + @Goal + @_ +Current State @start @ stop += +waiting @ starting @ n/a +starting @ pre\-start @ stopping +pre\-start @ spawned @ stopping +spawned @ post\-start @ stopping +post\-start @ running @ stopping +running @ stopping @ pre\-stop / stopping (*) +pre\-stop @ running @ stopping +stopping @ killed @ killed +killed @ post\-stop @ post\-stop +post\-stop @ starting @ waiting +.TE +.po \n[old_po] +.in \n[old_in] +.P +Key: + (*) If there is a \fBscript\fP or \fBexec\fP section and this process is running, + state will be \(aqpre\-stop\(aq, else it will be \(aqstopping\(aq. + +.\" ------------------------------------------------------------ +.SS Job Lifecycle +.\" +.IP "Starting a Job" +.nr step 1 1 +.IP \n[step] 3 +Initially the job is "at rest" with a goal of \(aqstop\(aq +and a state of \(aqwaiting\(aq (shown as \(aqstop/waiting\(aq by the +.BR initctl (8) +.B list +and +.B status +commands). +.\" +.IP \n+[step] 3 +The goal is changed from \(aqstop\(aq to +\(aqstart\(aq indicating the job is attempting to start. +.\" +.IP \n+[step] 3 +The state is changed from \(aqwaiting\(aq to +\(aqstarting\(aq. +.\" +.IP \n+[step] 3 +The \fBstarting\fP(7) event is emitted denoting the job is +"about to start". +.\" +.IP \n+[step] 3 +Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied +by this job starting are started (or stopped respectively). +.\" +.IP \n+[step] 3 +The \fBstarting\fP(7) event completes. +.\" +.IP \n+[step] 3 +The state is changed from \(aqstarting\(aq to \(aqpre\-start\(aq. +.\" +.IP \n+[step] 3 +If the \fBpre\-start\fP stanza exists, the pre\-start process is +spawned. +.\" +.IP \n+[step] 3 +If the pre\-start process fails, the goal is changed from +\(aqstart\(aq to \(aqstop\(aq, and the +.BR stopping(7) +and +.BR stopped(7) +events are emitted with appropriate variables set denoting the error. +.\" +.IP \n+[step] 3 +Assuming the pre\-start did not fail or did not call "stop", the main +process is spawned. +.\" +.IP \n+[step] 3 +The state is changed from \(aqpre\-start\(aq to \(aqspawned\(aq. +.\" +.IP \n+[step] 3 +Upstart then ascertains the \fIfinal\fP PID for the job which may be a +descendent of the immediate child process if \fBexpect fork\fP or +\fBexpect daemon\fP has been specified. +.\" +.IP \n+[step] 3 +The state is changed from \(aqspawned\(aq to \(aqpost\-start\(aq. +.\" +.IP \n+[step] 3 +If the \fBpost\-start\fP stanza exists, the post\-start process is +spawned. +.\" +.IP \n+[step] 3 +The state is changed from \(aqpost\-start\(aq to \(aqrunning\(aq. +.\" +.IP \n+[step] 3 +The \fBstarted\fP(7) event is emitted. +.sp 1 +For services, when this event completes the main process will now be fully +running. If the job refers to a task, it will now have completed +(successfully or otherwise). +.\" +.IP \n+[step] 3 +Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied +by this job being started are started (or stopped respectively). +.\" +.IP "Stopping a Job" +.nr step 1 1 +.IP \n[step] 3 +Assuming the job is fully running, it will have a goal of \(aqstart\(aq +and a state of \(aqrunning\(aq (shown as \(aqstart/running\(aq by the +.BR initctl (8) +.B list +and +.B status +commands). +.\" +.IP \n+[step] 3 +The goal is changed from \(aqstart\(aq to \(aqstop\(aq indicating the +job is attempting to stop. +.\" +.IP \n+[step] 3 +The state is changed from \(aqrunning\(aq to +\(aqpre\-stop\(aq. +.\" +.IP \n+[step] 3 +If the \fBpre\-stop\fP stanza exists, the pre\-stop process is +spawned. +.\" +.IP \n+[step] 3 +The state is changed from \(aqpre\-stop\(aq to \(aqstopping\(aq. +.\" +.IP \n+[step] 3 +The \fBstopping\fP(7) event is emitted. +.\" +.IP \n+[step] 3 +Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied by this +job stopping are started (or stopped respectively). +.\" +.IP \n+[step] 3 +The main process is stopped: +.RS +.nr step2 1 1 +.af step2 i +.IP \n[step2] 3 +The signal specified by the +.B kill signal +stanza is sent to the process group of the main process +(such that all processes belonging to the jobs main process are killed). +By default this signal is +.BR SIGTERM "." +.sp 1 +See \fBsignal\fP(7) and \fBinit\fP(5). +.IP \n+[step2] 3 +Upstart waits for up to "kill timeout" seconds (default 5 seconds) for +the process to end. +.IP \n+[step2] 3 +If the process is still running after the timeout, a +.B SIGKILL +signal is sent to the process which cannot be ignored and will forcibly +stop the processes in the process group. +.RE +.\" +.IP \n+[step] 3 +The state is changed from \(aqkilled\(aq to \(aqpost\-stop\(aq. +.\" +.IP \n+[step] 3 +If the \fBpost\-stop\fP stanza exists, the post\-stop process is +spawned. +.\" +.IP \n+[step] 3 +The state is changed from \(aqpost\-stop\(aq to \(aqwaiting\(aq. +.\" +.IP \n+[step] 3 +The \fBstopped\fP(7) event is emitted. +.sp 1 +When this event completes, the job is fully stopped. +.\" +.IP \n+[step] 3 +Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied +by this job being stopped are started (or stopped respectively). +.\" .SS System V compatibility The Upstart .BR init (8) @@ -148,6 +336,194 @@ .B \-\-version Outputs version information and exits. .\" +.SH Job States +.P +\fBTable 1: Job Goals and State Transitions.\fP +.TS +box,tab(@); +c | c s +c | c s +c | c | c +c | l l. + @Goal + @_ +Current State @start @ stop += +waiting @ starting @ n/a +starting @ pre\-start @ stopping +pre\-start @ spawned @ stopping +spawned @ post\-start @ stopping +post\-start @ running @ stopping +running @ stopping @ pre\-stop / stopping (*) +pre\-stop @ running @ stopping +stopping @ killed @ killed +killed @ post\-stop @ post\-stop +post\-stop @ starting @ waiting +.TE +.po \n[old_po] +.in \n[old_in] +.P +Key: + (*) If there is a \fBscript\fP or \fBexec\fP section and this process is running, + state will be \(aqpre\-stop\(aq, else it will be \(aqstopping\(aq. + +.\" ------------------------------------------------------------ +.SH Job Lifecycle +.\" +.SS Starting a Job +.IP \n[step] 3 +Initially the job is "at rest" with a goal of \(aqstop\(aq +and a state of \(aqwaiting\(aq (shown as \(aqstop/waiting\(aq by the +.BR initctl (8) +.B list +and +.B status +commands). +.\" +.IP \n+[step] 3 +The goal is changed from \(aqstop\(aq to +\(aqstart\(aq indicating the job is attempting to start. +.\" +.IP \n+[step] 3 +The state is changed from \(aqwaiting\(aq to +\(aqstarting\(aq. +.\" +.IP \n+[step] 3 +The \fBstarting\fP(7) event is emitted denoting the job is +"about to start". +.\" +.IP \n+[step] 3 +Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied +by this job starting are started (or stopped respectively). +.\" +.IP \n+[step] 3 +The \fBstarting\fP(7) event completes. +.\" +.IP \n+[step] 3 +The state is changed from \(aqstarting\(aq to \(aqpre\-start\(aq. +.\" +.IP \n+[step] 3 +If the \fBpre\-start\fP stanza exists, the pre\-start process is +spawned. +.\" +.IP \n+[step] 3 +If the pre\-start process fails, the goal is changed from +\(aqstart\(aq to \(aqstop\(aq, and the +.BR stopping(7) +and +.BR stopped(7) +events are emitted with appropriate variables set denoting the error. +.\" +.IP \n+[step] 3 +Assuming the pre\-start did not fail or did not call "stop", the main +process is spawned. +.\" +.IP \n+[step] 3 +The state is changed from \(aqpre\-start\(aq to \(aqspawned\(aq. +.\" +.IP \n+[step] 3 +Upstart then ascertains the \fIfinal\fP PID for the job which may be a +descendent of the immediate child process if \fBexpect fork\fP or +\fBexpect daemon\fP has been specified. +.\" +.IP \n+[step] 3 +The state is changed from \(aqspawned\(aq to \(aqpost\-start\(aq. +.\" +.IP \n+[step] 3 +If the \fBpost\-start\fP stanza exists, the post\-start process is +spawned. +.\" +.IP \n+[step] 3 +The state is changed from \(aqpost\-start\(aq to \(aqrunning\(aq. +.\" +.IP \n+[step] 3 +The \fBstarted\fP(7) event is emitted. +.sp 1 +For services, when this event completes the main process will now be fully +running. If the job refers to a task, it will now have completed +(successfully or otherwise). +.\" +.IP \n+[step] 3 +Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied +by this job being started are started (or stopped respectively). + +.\" ------------------------------ +.SS Stopping a Job +.nr step 1 1 +.IP \n[step] 3 +Assuming the job is fully running, it will have a goal of \(aqstart\(aq +and a state of \(aqrunning\(aq (shown as \(aqstart/running\(aq by the +.BR initctl (8) +.B list +and +.B status +commands). +.\" +.IP \n+[step] 3 +The goal is changed from \(aqstart\(aq to \(aqstop\(aq indicating the +job is attempting to stop. +.\" +.IP \n+[step] 3 +The state is changed from \(aqrunning\(aq to +\(aqpre\-stop\(aq. +.\" +.IP \n+[step] 3 +If the \fBpre\-stop\fP stanza exists, the pre\-stop process is +spawned. +.\" +.IP \n+[step] 3 +The state is changed from \(aqpre\-stop\(aq to \(aqstopping\(aq. +.\" +.IP \n+[step] 3 +The \fBstopping\fP(7) event is emitted. +.\" +.IP \n+[step] 3 +Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied by this +job stopping are started (or stopped respectively). +.\" +.IP \n+[step] 3 +The main process is stopped: +.RS +.nr step2 1 1 +.af step2 i +.IP \n[step2] 3 +The signal specified by the +.B kill signal +stanza is sent to the process group of the main process +(such that all processes belonging to the jobs main process are killed). +By default this signal is +.BR SIGTERM "." +.sp 1 +See \fBsignal\fP(7) and \fBinit\fP(5). +.IP \n+[step2] 3 +Upstart waits for up to "kill timeout" seconds (default 5 seconds) for +the process to end. +.IP \n+[step2] 3 +If the process is still running after the timeout, a +.B SIGKILL +signal is sent to the process which cannot be ignored and will forcibly +stop the processes in the process group. +.RE +.\" +.IP \n+[step] 3 +The state is changed from \(aqkilled\(aq to \(aqpost\-stop\(aq. +.\" +.IP \n+[step] 3 +If the \fBpost\-stop\fP stanza exists, the post\-stop process is +spawned. +.\" +.IP \n+[step] 3 +The state is changed from \(aqpost\-stop\(aq to \(aqwaiting\(aq. +.\" +.IP \n+[step] 3 +The \fBstopped\fP(7) event is emitted. +.sp 1 +When this event completes, the job is fully stopped. +.\" +.IP \n+[step] 3 +Any jobs whose \(aqstart on\(aq (or \(aqstop on\(aq) condition would be satisfied +by this job being stopped are started (or stopped respectively). +.\" .SH NOTES .B init is not normally executed by a user process, and expects to have a process @@ -215,7 +591,7 @@ .RB < https://launchpad.net/upstart/+bugs > .\" .SH COPYRIGHT -Copyright \(co 2009\-2012 Canonical Ltd. +Copyright \(co 2009\-2013 Canonical Ltd. .br This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. === modified file 'util/man/initctl.8' --- util/man/initctl.8 2013-11-07 03:35:14 +0000 +++ util/man/initctl.8 2013-12-20 15:13:45 +0000 @@ -1,4 +1,4 @@ -.TH initctl 8 2011-06-02 "Upstart" +.TH initctl 8 2012-12-20 "Upstart" .\" .SH NAME initctl \- init daemon control tool @@ -256,6 +256,12 @@ .IR waiting ", " starting ", " pre\-start ", " spawned ", " post\-start ", " .IR running ", " pre\-stop ", " stopping ", " killed " or " post\-stop . +Table 1 in the +.B Job States +section of +.BR init (8) +summarises job goal and state transitions. + If the job has an active process, the process id will follow on the same line. If the state is .IR pre\-start " or " post\-stop @@ -759,7 +765,7 @@ .RB < https://launchpad.net/upstart/+bugs > .\" .SH COPYRIGHT -Copyright \(co 2009\-2011 Canonical Ltd. +Copyright \(co 2009\-2013 Canonical Ltd. .br This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-- upstart-devel mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/upstart-devel
