1initctl(8)                  System Manager's Manual                 initctl(8)
2
3
4

NAME

6       initctl - init daemon control tool
7

SYNOPSIS

9       initctl [OPTION]...  COMMAND [OPTION]...  ARG...
10

DESCRIPTION

12       initctl  allows a system administrator to communicate and interact with
13       the Upstart init(8) daemon.
14
15       When run as initctl, the first  non-option  argument  is  the  COMMAND.
16       Global options may be specified before or after the command.
17
18       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

OPTIONS

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
32              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
37              The --system option instructs initctl to communicate via the  D-
38              Bus system bus rather than over the private socket.
39
40              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
45       --dest Specifies the well-known name of the init(8) daemon  when  using
46              --system.
47
48              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
52       --no-wait
53              Applies to the start, stop, restart and emit commands.
54
55              Normally  initctl  will  wait  for  the command to finish before
56              returning.
57
58              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
62              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
66              This option instead causes these commands to only wait  for  the
67              goal change or event to be queued.
68
69       --quiet
70              Reduces output of all commands to errors only.
71

COMMANDS

73       start  JOB [KEY=VALUE]...
74
75              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
79              See status for a description of the output format.
80
81              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
86              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
93              If the job is already running, start will return an error.
94
95       stop   JOB [KEY=VALUE]...
96
97              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
101              See  status for a description of the output format and start for
102              a discussion on instances.
103
104       restart
105              JOB [KEY=VALUE]...
106
107              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
111              See status for a description of the output format and start  for
112              a discussion on instances.
113
114              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
118       reload JOB [KEY=VALUE]...
119
120              Sends  the  SIGHUP  signal  to  running process of the named JOB
121              instance.
122
123              See start for a discussion on instances.
124
125       status JOB [KEY=VALUE]...
126
127              Requests the status an instance of the named JOB, outputting  to
128              standard output.
129
130              See start for a discusson on instances.
131
132              For a single-instance job a line like the following is output:
133
134                job start/running, process 1234
135
136              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
142              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
147                job start/pre-start, process 902
148
149              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
153                job start/post-start, process 1234
154                        post-start process 1357
155
156              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
160                job start/post-start, (post-start) process 1357
161
162              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
166                job (tty1) start/post-start, process 1234
167                        post-start process 1357
168
169       list
170
171              Requests a list of the known jobs  and  instances,  outputs  the
172              status of each to standard output.
173
174              See  status for a description of the output format and start for
175              a discussion on instances.
176
177              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
181       emit   EVENT [KEY=VALUE]...
182
183              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
187              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
191              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
195              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
199              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
203       reload-configuration
204
205              Requests that the init(8) daemon reloads its configuration.
206
207              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
211              No jobs will be started by this command.
212
213
214       version
215
216              Requests and outputs the version of the running init daemon.
217
218       log-priority
219              [PRIORITY]
220
221              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
226              PRIORITY  may  be  one  of  debug, info, message, warn, error or
227              fatal.
228
229              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

AUTHOR

234       Written by Scott James Remnant <scott@netsplit.com>
235

REPORTING BUGS

237       Report bugs at <https://launchpad.net/upstart/+bugs>
238
240       Copyright © 2010 Canonical Ltd.
241       This is free software; see the source for copying conditions.  There is
242       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
243       PURPOSE.
244

SEE ALSO

246       init(8) telinit(8) shutdown(8)
247
248
249
250Upstart                           2010-02-04                        initctl(8)
Impressum