English French
Unit files for traditional services have a naming scheme of `+foobar.service+`. When considering what basename to use, keep in mind that we'd like to use the same service names for software across distributions. We'd also like to ship the `+.service+` files in the upstream packages. These desires create a few guides for naming a unit file:
Follow upstream if they're already distributing a `+.service+` file and it's not likely to conflict with other packages.
Look at packages in other distros or talk with the maintainers of those packages and upstream to try to come up with a common name.
Unit files should be named after the software implementation that they support as opposed to the generic type of software. So, a good name would be `+apache-httpd.service+` and bad names would be `+httpd.service+` or `+apache.service+` as there are multiple httpd implementations and multiple projects produced by the apache foundation.
For backwards compatibility you may also want to create a symlink from an older, name to the new name. In the above example, for instance, Fedora has always used `+httpd+` for the service. When creating the new `+apache-httpd.service+` file, also create a symlink named `+httpd.service+` that points at `+apache-httpd.service+`. Then end users that are used to using `+service httpd+` will have it continue to work.
Basic format
Every `+.service+` file must begin with a `+[Unit]+` section:
Description=A brief human readable string describing the service (not the .service file!)
Documentation=man:foo.service(8) man:foo.conf(5) https://www.foo.org/docs/
The `+Description=+` line must not exceed 80 characters, and must describe the service, and not the `+.service+` file. For example, "Apache Web Server" is a good description, but "Starts and Stops the Apache Web Server" is a bad one.
Documentation field
Systemd has support for defining documentation in unit files via the `Documentation=` field. System administrators will be looking at the contents of the `+Documentation=+` field to determine what the service is, how to configure it, and where to locate additional documentation relating to the service. Accordingly, packagers are strongly encouraged to include any available sources in the `Documentation=` field which provide this information. If a man page or info page is present in the package, refer to it using `man:manpage` or `info:infofile` respectively. If the documentation is in plaintext, use `\file://path/to/file`. Lastly, if no local documentation exists in the package, but it exists at a URL, use the URL (with `https://`) in this field. Multiple URIs can be added to the `Documentation=` field, as a space separated list. For details on URI definitions and formatting, please refer to the `uri(7)` manpage (`man uri`).
Next, the `+.service+` file must have a `+[Service]+` section:
The `+Type=+` setting is very important. For D-Bus services this should be `+dbus+`, for traditional services `+forking+` is usually a good idea, for services not offering any interfaces to other services `+simple+` is best. For "one-shot" scripts `+oneshot+` is ideal, often combined with `+RemainAfterExit=+`. See https://www.freedesktop.org/software/systemd/man/systemd.service.html[systemd.service(5)] for further discussion on the topic. Since `+simple+` is the default type, `+.service+` files which would normally set `+Type=simple+` may simply omit the `+Type+` line altogether.
`+BusName=+` should be set for all services connecting to D-Bus. (i.e. it is a must for those where `+Type=dbus+`, but might make sense otherwise, too) Omit this option if your service does not take a name on the bus.
`+ExecStart=+` is necessary for all services. This line defines the string that you would run to start the daemon, along with any necessary options.
`+ExecReload=+` should be specified for all services supporting reload. It is highly recommended to add code here that synchronously reloads the configuration file here (i.e. `+/bin/kill -HUP $MAINPID+` is usually a poor choice, due to its asynchronous nature). Omit this option if your service does not support reloading.