1initctl(8) System Manager's Manual initctl(8)
2
6 initctl - init daemon control tool
7
9 initctl [OPTION]... COMMAND [OPTION]... ARG...
10
12 initctl allows a system administrator to communicate and interact with
13 the Upstart init(8) daemon.
14 When run as initctl, the first non-option argument is the COMMAND.
16 Global options may be specified before or after the command.
17 You may also create symbolic or hard links to initctl named after com‐
19 mands. When invoked through these links the tool will behave only as
20 that command, with global and command-specific options intermixed. The
21 default installation supplies such links for the start, stop, restart,
22 reload and status commands.
23
25 --system
26 Communication with the init(8) daemon is normally performed over
27 a private socket connection. This has the advantage of speed
28 and robustness, when issuing commands to start or stop services
29 or even reboot the system you do not want to be affected by
30 changes to the D-Bus system bus daemon.
31 The disadvantage to using the private socket however is secu‐
33 rity, init(8) only permits the root user to communicate over
34 this socket which means that read-only commands such as status
35 and list cannot be made by other users.
36 The --system option instructs initctl to communicate via the D-
38 Bus system bus rather than over the private socket.
39 This is only possible if the system bus daemon is running and if
41 init(8) is connected to it. The advantage is that the default
42 security configuration allows non-root users to use read-only
43 commands.
44 --dest Specifies the well-known name of the init(8) daemon when using
46 --system.
47 There is normally no need to use this option since the init(8)
49 daemon uses the default com.ubuntu.Upstart name. However it may
50 be useful for debugging.
51 --no-wait
53 Applies to the start, stop, restart and emit commands.
54 Normally initctl will wait for the command to finish before
56 returning.
57 For the start, stop and restart commands, finishing means that
59 the named job is running (or has finished for tasks) or has been
60 fully stopped.
61 For the emit command, finishing means that all of the jobs
63 affected by the event are running (or have finished for tasks)
64 or have been fully stopped.
65 This option instead causes these commands to only wait for the
67 goal change or event to be queued.
68 --quiet
70 Reduces output of all commands to errors only.
71
73 start JOB [KEY=VALUE]...
74 Requests that a new instance of the named JOB be started, out‐
76 putting the status of the job to standard output when the com‐
77 mand completes.
78 See status for a description of the output format.
80 The optional KEY=VALUE arguments specify environment variables
82 to be passed to the starting job, and placed in its environment.
83 They also serve to specify which instance of multi-instance jobs
84 should be started.
85 Most jobs only permit a single instance; those that use the
87 instance stanza in their configuration define a string expanded
88 from environment variables to name the instance. As many unique
89 instances may be started as unique names may be generated by the
90 stanza. Thus the environment variables also serve to select
91 which instance of JOB is to be acted upon.
92 If the job is already running, start will return an error.
94 stop JOB [KEY=VALUE]...
96 Requests that an instance of the named JOB be stopped, out‐
98 putting the status of the job to standard output when the com‐
99 mand completes.
100 See status for a description of the output format and start for
102 a discussion on instances.
103 restart
105 JOB [KEY=VALUE]...
106 Requests that an instance of the named JOB be restarted, out‐
108 putting the status of the job to standard output when the com‐
109 mand completes.
110 See status for a description of the output format and start for
112 a discussion on instances.
113 Note that this command can only be used when there is an
115 instance of JOB, if there is none then it returns an error
116 instead of starting a new one.
117 reload JOB [KEY=VALUE]...
119 Sends the SIGHUP signal to running process of the named JOB
121 instance.
122 See start for a discussion on instances.
124 status JOB [KEY=VALUE]...
126 Requests the status an instance of the named JOB, outputting to
128 standard output.
129 See start for a discusson on instances.
131 For a single-instance job a line like the following is output:
133 job start/running, process 1234
135 The job name is given first followed by the current goal and
137 state of the selected instance. The goal is either start or
138 stop, the status may be one of waiting, starting, pre-start,
139 spawned, post-start, running, pre-stop, stopping, killed or
140 post-stop.
141 If the job has an active process, the process id will follow on
143 the same line. If the state is pre-start or post-stop this will
144 be the process id of the equivalent process, otherwise it will
145 be the process id of the main process.
146 job start/pre-start, process 902
148 The post-start and pre-stop states may have multiple processes
150 attached, the extra processes will follow on consecutive lines
151 indented by a tab:
152 job start/post-start, process 1234
154 post-start process 1357
155 If there is no main process, they may follow on the same line
157 but will be prefixed to indicate that it is not the main process
158 id being given:
159 job start/post-start, (post-start) process 1357
161 Jobs that permit multiple instances have names for each
163 instance, the output is otherwise identical to the above except
164 that the instance name follows the job name in parentheses:
165 job (tty1) start/post-start, process 1234
167 post-start process 1357
168 list
170 Requests a list of the known jobs and instances, outputs the
172 status of each to standard output.
173 See status for a description of the output format and start for
175 a discussion on instances.
176 No particular order is used for the output, and there is no dif‐
178 ference in the output (other than the instance name appearing in
179 parentheses) between single-instance and multiple-instance jobs.
180 emit EVENT [KEY=VALUE]...
182 Requests that the named EVENT be emitted, potentially causing
184 jobs to be started and stopped depending on their use of the
185 start on and stop on stanzas in their configuration.
186 The optional KEY=VALUE arguments specify environment variables
188 to be included with the event and thus exported into the envi‐
189 ronment of any jobs started and stopped by the event.
190 The environment may also serve to specify which instance of
192 multi-instance jobs should be started or stopped. See start for
193 a discussion on instances.
194 There is no limitation on the event names that may be emitted
196 with this command, you are free to invent new events and use
197 them in your job configurations.
198 The most well known event used by the default Upstart configura‐
200 tion is the runlevel(7) event. This is normally emitted by the
201 telinit(8) and shutdown(8) tools.
202 reload-configuration
204 Requests that the init(8) daemon reloads its configuration.
206 This command is generally not necessary since init(8) watches
208 its configuration directories with inotify(7) and automatically
209 reloads in cases of changes.
210 No jobs will be started by this command.
212 version
215 Requests and outputs the version of the running init daemon.
217 log-priority
219 [PRIORITY]
220 When called with a PRIORITY argument, it requests that the
222 init(8) daemon log all messages with that priority or greater.
223 This may be used to both increase and decrease the volume of
224 logged messages.
225 PRIORITY may be one of debug, info, message, warn, error or
227 fatal.
228 When called without argument, it requests the current minimum
230 message priority that the init(8) daemon will log and ouputs to
231 standard output.
232
236Show usage information an instance of the named JOB defined with usage stanza.
238For job with usage stanza a line like the following is output, see init(5) :
240 Usage: tty DEV=ttyX - where X is console id
242
244 Written by Scott James Remnant <scott@netsplit.com>
245
247 Report bugs at <https://launchpad.net/upstart/+bugs>
248
250 Copyright © 2010 Canonical Ltd.
251 This is free software; see the source for copying conditions. There is
252 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
253 PURPOSE.
254
256 init(8) telinit(8) shutdown(8)
257Upstart 2010-02-04 initctl(8)