Linux stop command
On Unix-like operating systems, the stop command calls the init daemon to stop a job that is running on the system. It is equivalent to the command initctl stop.
Description
initctl allows a system administrator to communicate and interact with the init daemon.
When run as initctl, the first non-option argument is the COMMAND. Global options may be specified before or after the command.
You may also create symbolic or hard links to initctl named after commands. When invoked through these links the tool will behave only as that command, with global and command-specific options intermixed. The default installation supplies such links for the start, stop, restart, reload and status commands.
Syntax
Options
| —user | User mode. In this mode, initctl will talk to the init daemon using the D-Bus private socket defined in the UPSTART_SESSION environment variable. |
| —session | Connect to init daemon using the D-Bus session bus (for testing purposes only). |
| —system | Communication with the init daemon is normally performed over a private socket connection. This communication has the advantage of speed and robustness, when issuing commands to start or stop services or even reboot the system you do not want to be affected by changes to the D-Bus system bus daemon. |
The disadvantage to using the private socket, however, is security; init only permits the root user to communicate over this socket which means that read-only commands such as status and list cannot be made by other users.
The —system option instructs initctl to communicate via the D-Bus system bus rather than over the private socket.
This option is only possible if the system bus daemon is running and if init is connected to it. The advantage is that the default security configuration allows non-root users to use read-only commands.
There is normally no need to use this option since the init daemon uses the default Upstart name. However, it may be useful for debugging.
Normally initctl will wait for the command to finish before returning.
For the start, stop and restart commands, finishing indicates the named job is running (or has finished for tasks) or was fully stopped.
For the emit command, finishing means that all of the jobs affected by the event are running (or have finished for tasks) or was stopped.
This option instead causes these commands to only wait for the goal change or event to be queued.
Commands
| start JOB [KEY=VALUE]. | Requests that a new instance of the named JOB be started, outputting the status of the job to standard output when the command completes. |
See status for a description of the output format.
The optional KEY=VALUE arguments specify environment variables to be passed to the starting job, and placed in its environment. They also serve to specify which instance of multi-instance jobs should be started.
Most jobs only permit a single instance; those that use the instance stanza in their configuration define a string expanded from environment variables to name the instance. As many unique instances may be started as unique names may be generated by the stanza. Thus the environment variables also serve to select which instance of JOB is to be acted upon.
If the job is already running, start returns an error.
When called from the pre-stop stanza of a job configuration, start may be called without argument to cancel the stop.
See status for a description of the output format, and start for a discussion on instances.
When called from the pre-start stanza of a job configuration, stop may be called without an argument to cancel the start.
The job instance being restarted will retain its original configuration. To have the new instance run with the latest job configuration, stop the job and then start it again instead.
See status for a description of the output format and start for a discussion on instances.
Note that this command can only be used when there is an instance of JOB; if there is none then it returns an error instead of starting a new one.
See start for a discussion on instances.
For a single-instance job, a line like the following is output:
The job name is given first followed by the current goal and state of the selected instance. The goal is either start or stop, the status may be one of waiting, starting, pre-start, spawned, post-start, running, pre-stop, stopping, killed or post-stop.
If the job has an active process, the process id will follow on the same line. If the state is pre-start or post-stop this will be the process id of the equivalent process, otherwise it will be the process id of the main process:
The post-start and pre-stop states may have multiple processes attached, the extra processes will follow on consecutive lines indented by a tab:
If there is no main process, they may follow on the same line but will be prefixed to indicate that it is not the main process id being given:
Jobs that permit multiple instances have names for each instance, the output is otherwise identical to the above except that the instance name follows the job name in parentheses:
Note that this command includes in the enumeration as-yet-to-run jobs (in other words, configuration files for which no job instances have yet been created) in the output with status «stop/waiting». In effect such entries denote configuration files which represent potential future jobs.
See status for a description of the output format, and start for a discussion on instances.
No particular order is used for the output, and there is no difference in the output (other than the instance name appearing in parentheses) between single-instance and multiple-instance jobs.
The optional KEY=VALUE arguments specify environment variables to be included with the event and thus exported into the environment of any jobs started and stopped by the event.
The environment may also serve to specify which instance of multi-instance jobs should be started or stopped. See start for a discussion on instances.
There is no limitation on the event names emitted with this command, you are free to invent new events and use them in your job configurations.
The most «well-known» event used by the default Upstart configuration is the runlevel event. This option is normally emitted by the telinit and shutdown tools.
This command is generally not necessary since init watches its configuration directories with inotify and automatically reloads in changes.
No jobs will be started by this command.
PRIORITY may be one of debug, info, message, warn, error or fatal.
When called without argument, it requests the current minimum message priority that the init daemon will log and outputs to standard output.
Note that a job configuration is the name of a job configuration file, without the extension. Note too that this information is static: it does not refer to any running job.
For each event emitted, a separate line is displayed beginning with two space characters followed by, «emits event» where «event» denotes a single emitted event.
The start on and stop on conditions are listed on separate lines beginning with two space characters and followed by «start on» and «stop on» respectively and ending with the appropriate condition.
If a job configuration has no emits, start on, or stop on conditions, the name of the job configuration will be displayed with no further details.
Note that the start on and stop on conditions will be fully bracketed, regardless of whether they appear like this in the job configuration file, which is useful to see how the init daemon perceives the condition.
OPTION may be the following:
| -e, —enumerate | If specified, rather than listing the precise start on and stop on conditions, outputs the emits lines along with one line for each event or job the CONF in question may be started or stopped by if it were to become a job. If the start on condition specifies a non-job event, this will be listed verbatim, whereas for a job event, the name of the job as opposed to the event the job emits will be listed. The type of entity, its triggering event (if appropriate) and its full environment is displayed in brackets following its name for clarity. This option is useful for tools which generate graphs of relationships between jobs and events. It is also instructive since it shows how the init daemon has parsed the job configuration file. Example output (an analog of the default output format above): |
This option is useful for determining the impact of adding or removing job configuration files.
Note that to use this command, it is necessary to ensure that all job configuration files advertise the events they emit correctly.
If errors are identified, the name of the job configuration will be displayed. Subsequent lines will show the failed conditions for the job configuration, one per line. Condition lines begin with two spaces and are followed with either «start on: » or «stop on: «, the word «unknown», the type of entity that is not known and finally its name.
Note that only job configurations that are logically in error (those with unsatisfiable conditions) will be displayed. Note too that job configurations that are syntactically invalid may trigger an error if they would cause a condition to be in error.
Assuming job configuration file /etc/init/foo.conf contains the following:
The check-config command might display:
If any errors are detected, the exit code will be 1 (one). If all checks pass, the exit code will be 0 (zero).
Note that for complex start on and stop on conditions, this command may give what appears to be misleading output when an error condition is found since all expressions in the failing condition that are in error will generate error output. For example, if job configuration /etc/init/bar.conf contains the following:
And only event A can be satisfied, the output will be:
OPTION may be the following:
| -i [EVENTS], —ignore-events [EVENTS] | If specified, the argument should be a list of comma-separated events to ignore when checking the job configuration files. This option may be useful to ignore errors if a particular job configuration file does not advertise it emits an event. Note that internal events (such as startup and starting) are automatically ignored. |
| -w, —warn | If specified, treat any unknown jobs and events as errors. |
When run from within a job, this command will automatically query the job-specific environment table; otherwise the global environment table that is applied to all jobs when they first start is queried.
Note that the global job environment table comprises those variables already set in the init daemons environment at startup, the minimal set of standard system variables added by the init daemon, and any variables set using set-env. See init for further details.
OPTION may be the following:
| -g, —global | Operate on the global job environment table. This option is implied when not run from within a job. |
When run from within a job, this command will automatically query the job-specific environment table; otherwise the global environment table that is applied to all jobs when they first start is queried.
OPTION may be the following:
| -g, —global | Operate on the global job environment table. This option is implied when not run from within a job. |
This command is only permitted When running in User Session Mode. See init for further details.
OPTIONS may be the following:
| -r, —retain | If the specified variable is already set, do not modify it. |
| -g, —global | Operate on the global job environment table and all existing running job environment tables. This option is implied when not run from within a job. This option is an advanced option whose use is discouraged since it can change the job environment as it moves between different process stages (for example, between pre-start and the main process). See init for further details. |
OPTIONS may be the following:
| -r, —retain | If the specified variable is already set, do not modify it. |
| -g, —global | Operate on the global job environment table and all existing running job environment tables. This option is implied when not run from within a job. This option is an advanced option whose use is discouraged since it can change the job environment as it moves between different process stages (for example, between pre-start and the main process). See init for further details. |
This command is only permitted when running in User Session Mode. See init for further details.
Note that the effect of the Session Init process that manages the User Session Mode restarting is equivalent to this command having been called.
OPTIONS may be the following:
| -r, —retain | If the specified variable is already set, do not modify it. |
| -g, —global | Operate on the global job environment table. This option is implied when not run from within a job. Note that unlike set-env and unset-env, this option does not modify running job environment tables. |
Example output for a job that specifies the usage stanza is shown below:
Examples
Stop the job with process ID 1234.
Related commands
init — The parent of all processes on the system.
kill — Send a signal to a process, affecting its behavior or killing it.
ps — Report the status of a process or processes.
shutdown — Schedule a time for the system to be powered down.
top — Display a sortable, continually-updated list of processes.
Источник
