[systemd-devel] Documentation error for systemctl kill?

[Lennart Poettering]

On Thu, 13.03.14 14:54, Alan Stern (stern at rowland.harvard.edu) wrote:

> In systemd 208 (the version currently distributed in Fedora 20), the 
> man page for the systemctl(1) kill command says:
> 
> 	Send a signal to one or more processes of the unit. Use --kill-who=
> 	to select which process to kill. Use --kill-mode= to select the
> 	kill mode and --signal= to select the signal to send.
> 
> This seems peculiar, because the man page does not mention a
> --kill-mode= option anywhere else.  It does mention --kill-who=,
> saying:

Ah, yeah, I removed --kill-mode= a long long time ago from systemctl since it
was confusing and redundant, and I forgot to update the man page
accordinly. I corrected that now. Thanks for the pointer.

> 	When used with kill, choose which processes to kill. Must be one of
> 	main, control or all to select whether to kill only the main
> 	process of the unit, the control process or all processes of the
> 	unit. If omitted, defaults to all.
> 
> This sounds an awful lot like the description of the KillMode= option 
> documented under systemd.kill(5):
> 
> 	Specifies how processes of this service shall be killed. One of
> 	control-group, process, none....
> 
> As far as I can tell, "main" for --kill-who= means much the same thing
> as "process" for KillMode=, and "all" for --kill-who= means much the
> same as "control-group" for KillMode=.

Yeah, --kill-mode= used to be a command line argument for specifiying
what is configured for units with KillMode=. But it's really redundant,
as this can actually be derived from --kill-who= implicitly...

> So what does "control" mean for --kill-who=?  That is, what is the
> control process (as opposed to the main process) of the unit?

Basically, each service consists of 0 or 1 main process + of 0 or 1
control process + any number of additional processes. The main process
is, well, the main process of a service, which is by which we track the
lifetime of the service. The control processes are all other processes
system starts and tracks, in order to induce state changes. Basically,
all processes started by ExecStartPre, ExecStartPost, ExecStop,
ExecReload, ExecStopPost are control processes, and if Type=forking is
used even the one configured in ExecStart=, since in that case the main
process of the service will not be the one PID 1 starts, but one that is
eventually forked off.

I have now changed the systemctl man page to explain this in quite some
detail.
        
> And what about the --kill-mode= option?  According to the output from
> "systemctl --help", it doesn't exist.  Is it a relic from an earlier 
> version of systemctl?

Yes it is. But no longer!

Thanks for reporting this! Much appreciated!

Lennart

-- 
Lennart Poettering, Red Hat