[systemd-devel] [PATCH v2 2/2] systemd.service(5): add some simple examples

[Lennart Poettering]

On Tue, 27.01.15 17:45, Christian Seiler (christian at iwakd.de) wrote:

> +                <title>Examples</title>
> +
> +                <example>
> +                        <title>Simple service</title>
> +
> +                        <para>The following unit file creates a service
> +                        that will execute
> +                        <filename>/usr/sbin/foo-daemon</filename>.
> +                        Since no <varname>Type=</varname> is specified,
> +                        the default
> +                        <varname>Type=</varname><option>simple</option>
> +                        will be assumed. systemd will assume the unit
> +                        to be started immediately after the program has
> +                        begun executing.</para>
> +
> +                        <programlisting>[Unit]
> +Description=Foo
> +
> +[Service]
> +ExecStart=/usr/sbin/foo-daemon
> +
> +[Install]
> +WantedBy=multi-user.target</programlisting>
> +
> +                        <para>Note that systemd assumes here that the
> +                        program will continue running in the foreground
> +                        as long as it's active. If the program

I think "foreground" vs. "background" here is probably something to
avoid. These are services after all, and hence kinda "background" in
all cases. I am not sure how to explain this better though... Maybe
clarify that the program does not fork on its own, and that the
process systemd starts stays running until the very end of the
daemon, or so.

> +                        <para>Note that systemd will consider the unit
> +                        to be in the state 'starting' until the program
> +                        has terminated, so ordered dependencies will
> +                        wait for the program to finish before starting
> +                        themselves. The unit will revert to the
> +                        'inactive' state after the execution is
> +                        done. That means another request to start the
> +                        unit will perform the action again.</para>

It might be worth also mentioning here that the the unit this way will
never actually be "active". It will go directly from "activating" to
"inactive", which might be surprising!

> +                </example>
> +
> +                <example>
> +                        <title>Stoppable oneshot service</title>
> +
> +                        <para>Similarly to the oneshot services, there
> +                        are sometimes units that need to execute a
> +                        program to set up something and then execute
> +                        another to shut it down, but no process remains
> +                        active while they are considered
> +                        'started'. Network configuration can sometimes
> +                        fall into this category.</para>

Another reason to use RemainAfterExit= are services that shall not
execute again and again when they are pulled in, but only the first
time...

> +                <example>
> +                        <title>DBus services</title>
> +
> +                        <para>For services that acquire name on the
> +                        DBus system bus, use
> +
> <varname>RemainAfterExit=</varname><option>dbus</option>

Typo. Should be Type=, not RemainAfterExit=

> +                <example>
> +                        <title>Deferred (idle) services</title>

Hmm, I wonder if we maybe should remove this part. Idle services are
kinda exotic, and I figure people might be tempted to misuse them. I
think this might be something to document at the description of Type=,
but not push people towards using this beyond that.

Looks great otherwise! Thanks a ton for putting this together, much appreciated!

Lennart

-- 
Lennart Poettering, Red Hat