systemd.service — Service unit configuration
service.service
A unit configuration file whose name ends in
                .service encodes information
                about a process controlled and supervised by
                systemd.
This man page lists the configuration options
                specific to this unit type. See
                systemd.unit(5)
                for the common options of all unit configuration
                files. The common configuration items are configured
                in the generic [Unit] and
                [Install] sections. The service
                specific configuration options are configured in the
                [Service] section.
Additional options are listed in systemd.exec(5), which define the execution environment the commands are executed in, and in systemd.kill(5) which define the way the processes of the service are terminated.
Unless DefaultDependencies=
                is set to false, service units will
                implicitly have dependencies of type
                Requires= and
                After= on
                basic.target as well as
                dependencies of type Conflicts= and
                Before= on
                shutdown.target. These ensure
                that normal service units pull in basic system
                initialization, and are terminated cleanly prior to
                system shutdown. Only services involved with early
                boot or late system shutdown should disable this
                option.
If a service is requested under a certain name
                but no unit configuration file is found, systemd looks
                for a SysV init script by the same name (with the
                .service suffix removed) and
                dynamically creates a service unit from that
                script. This is useful for compatibility with
                SysV. Note that this compatibility is quite
                comprehensive but not 100%. For details about the
                incompatibilities see the Incompatibilities
                with SysV document.
                
Service files must include a
                [Service] section, which carries
                information about the service and the process it
                supervises. A number of options that may be used in
                this section are shared with other unit types. These
                options are documented in
                systemd.exec(5)
                and
                systemd.kill(5). The
                options specific to the [Service]
                section of service units are the following:
Type=¶Configures the process
                                start-up type for this service
                                unit. One of simple,
                                forking,
                                oneshot,
                                dbus,
                                notify or
                                idle.
If set to
                                simple (the default
                                value if BusName=
                                is not specified) it is expected that
                                the process configured with
                                ExecStart= is the
                                main process of the service. In this
                                mode, if the process offers
                                functionality to other processes on
                                the system its communication channels
                                should be installed before the daemon
                                is started up (e.g. sockets set up by
                                systemd, via socket activation), as
                                systemd will immediately proceed
                                starting follow-up units.
If set to
                                forking it is
                                expected that the process configured
                                with ExecStart=
                                will call fork()
                                as part of its start-up. The parent process is
                                expected to exit when start-up is
                                complete and all communication
                                channels set up. The child continues
                                to run as the main daemon
                                process. This is the behavior of
                                traditional UNIX daemons. If this
                                setting is used, it is recommended to
                                also use the
                                PIDFile= option, so
                                that systemd can identify the main
                                process of the daemon. systemd will
                                proceed starting follow-up units as
                                soon as the parent process
                                exits.
Behavior of
                                oneshot is similar
                                to simple, however
                                it is expected that the process has to
                                exit before systemd starts follow-up
                                units. RemainAfterExit=
                                is particularly useful for this type
                                of service.
Behavior of
                                dbus is similar to
                                simple, however it is
                                expected that the daemon acquires a
                                name on the D-Bus bus, as configured
                                by
                                BusName=. systemd
                                will proceed starting follow-up units
                                after the D-Bus bus name has been
                                acquired. Service units with this
                                option configured implicitly gain
                                dependencies on the
                                dbus.socket
                                unit. This type is the default if
                                BusName= is
                                specified.
Behavior of
                                notify is similar to
                                simple, however it is
                                expected that the daemon sends a
                                notification message via
                                sd_notify(3)
                                or an equivalent call when it finished
                                starting up. systemd will proceed
                                starting follow-up units after this
                                notification message has been sent. If
                                this option is used
                                NotifyAccess= (see
                                below) should be set to open access to
                                the notification socket provided by
                                systemd. If
                                NotifyAccess= is
                                not set, it will be implicitly set to
                                main.
Behavior of
                                idle is very similar
                                to simple, however
                                actual execution of the service
                                binary is delayed until all jobs are
                                dispatched. This may be used to avoid
                                interleaving of output of shell
                                services with the status output on the
                                console.
RemainAfterExit=¶Takes a boolean value
                                that specifies whether the service
                                shall be considered active even when
                                all its processes exited. Defaults to
                                no.
GuessMainPID=¶Takes a boolean value
                                that specifies whether systemd should
                                try to guess the main PID of a service
                                if it cannot be determined
                                reliably. This option is ignored
                                unless Type=forking
                                is set and PIDFile=
                                is unset because for the other types
                                or with an explicitly configured PID
                                file the main PID is always known. The
                                guessing algorithm might come to
                                incorrect conclusions if a daemon
                                consists of more than one process. If
                                the main PID cannot be determined
                                failure detection and automatic
                                restarting of a service will not work
                                reliably. Defaults to
                                yes.
PIDFile=¶Takes an absolute file
                                name pointing to the PID file of this
                                daemon. Use of this option is
                                recommended for services where
                                Type= is set to
                                forking. systemd will
                                read the PID of the main process of
                                the daemon after start-up of the
                                service. systemd will not write to the
                                file configured here.
BusName=¶Takes a D-Bus bus
                                name, that this service is reachable
                                as. This option is mandatory for
                                services where
                                Type= is set to
                                dbus, but its use
                                is otherwise recommended as well if
                                the process takes a name on the D-Bus
                                bus.
ExecStart=¶Commands with their arguments that are executed when this service is started. The first argument must be an absolute path name.
When Type is
                                not oneshot, only one
                                command may be given. When
                                Type=oneshot is
                                used, more than one command may be
                                specified. Multiple command lines may
                                be concatenated in a single directive,
                                by separating them with semicolons
                                (these semicolons must be passed as
                                separate words). Alternatively, this
                                directive may be specified more than
                                once with the same effect. However,
                                the latter syntax is not recommended
                                for compatibility with parsers
                                suitable for XDG
                                .desktop files.
                                Lone semicolons may be escaped as
                                '\;'. If the empty
                                string is assigned to this option the
                                list of commands to start is reset,
                                prior assignments of this option will
                                have no effect.
If more than one command is
                                specified, the commands are invoked
                                one by one sequentially in the order
                                they appear in the unit file. If one
                                of the commands fails (and is not
                                prefixed with '-'),
                                other lines are not executed and the
                                unit is considered failed.
Unless
                                Type=forking is
                                set, the process started via this
                                command line will be considered the
                                main process of the daemon.
The command line accepts
                                '%' specifiers as
                                described in
                                systemd.unit(5). Note
                                that the first argument of the command
                                line (i.e. the program to execute) may
                                not include specifiers.
Basic environment variable
                                substitution is supported. Use
                                ${FOO} as part of a
                                word, or as a word of its own on the
                                command line, in which case it will be
                                replaced by the value of the
                                environment variable including all
                                whitespace it contains, resulting in a
                                single argument.  Use
                                $FOO as a separate
                                word on the command line, in which
                                case it will be replaced by the value
                                of the environment variable split up
                                at whitespace, resulting in zero or
                                more arguments. Note that the first
                                argument (i.e. the program to execute)
                                may not be a variable, since it must
                                be a literal and absolute path
                                name.
Optionally, if the absolute file
                                name is prefixed with
                                '@', the second token
                                will be passed as
                                argv[0] to the
                                executed process, followed by the
                                further arguments specified. If the
                                absolute file name is prefixed with
                                '-' an exit code of
                                the command normally considered a
                                failure (i.e. non-zero exit status or
                                abnormal exit due to signal) is ignored
                                and considered success. If both
                                '-' and
                                '@' are used they
                                can appear in either order.
Note that this setting does not directly support shell command lines. If shell command lines are to be used they need to be passed explicitly to a shell implementation of some kind. Example:
ExecStart=/bin/sh -c 'dmesg | tac'
                                For services run by a user
                                instance of systemd the special
                                environment variable
                                $MANAGERPID is set
                                to the PID of the systemd
                                instance.
ExecStartPre=, ExecStartPost=¶Additional commands
                                that are executed before or after
                                the command in
                                ExecStart=, respectively.
                                Syntax is the same as for
                                ExecStart=, except
                                that multiple command lines are allowed
                                and the commands are executed one
                                after the other, serially.
If any of those commands (not
                                prefixed with '-')
                                fail, the rest are not executed and
                                the unit is considered failed.
ExecReload=¶Commands to execute to
                                trigger a configuration reload in the
                                service. This argument takes multiple
                                command lines, following the same
                                scheme as described for
                                ExecStart=
                                above. Use of this setting is
                                optional. Specifier and environment
                                variable substitution is supported
                                here following the same scheme as for
                                ExecStart=.
One additional special
                                environment variables is set: if known
                                $MAINPID is set to
                                the main process of the daemon, and
                                may be used for command lines like the
                                following:
/bin/kill -HUP $MAINPID
ExecStop=¶Commands to execute to
                                stop the service started via
                                ExecStart=. This
                                argument takes multiple command lines,
                                following the same scheme as described
                                for ExecStart=
                                above. Use of this setting is
                                optional. All processes remaining for
                                a service after the commands
                                configured in this option are run are
                                terminated according to the
                                KillMode= setting
                                (see
                                systemd.kill(5)). If
                                this option is not specified the
                                process is terminated right-away when
                                service stop is requested. Specifier
                                and environment variable substitution
                                is supported (including
                                $MAINPID, see
                                above).
ExecStopPost=¶Additional commands
                                that are executed after the service
                                was stopped. This includes cases where
                                the commands configured in
                                ExecStop= were used,
                                where the service doesn't have any
                                ExecStop= defined, or
                                where the service exited unexpectedly. This
                                argument takes multiple command lines,
                                following the same scheme as described
                                for ExecStart. Use
                                of these settings is
                                optional. Specifier and environment
                                variable substitution is
                                supported.
RestartSec=¶Configures the time to
                                sleep before restarting a service (as
                                configured with
                                Restart=). Takes a
                                unit-less value in seconds, or a time
                                span value such as "5min
                                20s". Defaults to
                                100ms.
TimeoutStartSec=¶Configures the time to
                                wait for start-up. If a
                                daemon service does not signal
                                start-up completion within the
                                configured time, the service will be
                                considered failed and be shut down
                                again.
                                Takes a unit-less value in seconds, or a
                                time span value such as "5min
                                20s". Pass 0 to disable the timeout
                                logic. Defaults to 90s, except when
                                Type=oneshot is
                                used in which case the timeout
                                is disabled by default.
                                
TimeoutStopSec=¶Configures the time to
                                wait for stop. If a service is asked
                                to stop but does not terminate in the
                                specified time, it will be terminated
                                forcibly via SIGTERM, and after
                                another delay of this time with
                                SIGKILL (See
                                KillMode=
                                in systemd.kill(5)).
                                Takes a unit-less value in seconds, or a
                                time span value such as "5min
                                20s". Pass 0 to disable the timeout
                                logic. Defaults to 90s.
                                
TimeoutSec=¶A shorthand for configuring
                                both TimeoutStartSec=
                                and TimeoutStopSec=
                                to the specified value.
                                
WatchdogSec=¶Configures the
                                watchdog timeout for a service. The
                                watchdog is activated when the start-up is
                                completed. The service must call
                                sd_notify(3)
                                regularly with "WATCHDOG=1" (i.e. the
                                "keep-alive ping"). If the time
                                between two such calls is larger than
                                the configured time then the service
                                is placed in a failure state. By
                                setting Restart= to
                                on-failure or
                                always the service
                                will be automatically restarted. The
                                time configured here will be passed to
                                the executed service process in the
                                WATCHDOG_USEC=
                                environment variable. This allows
                                daemons to automatically enable the
                                keep-alive pinging logic if watchdog
                                support is enabled for the service. If
                                this option is used
                                NotifyAccess= (see
                                below) should be set to open access to
                                the notification socket provided by
                                systemd. If
                                NotifyAccess= is
                                not set, it will be implicitly set to
                                main. Defaults to 0,
                                which disables this
                                feature.
Restart=¶Configures whether the
                                service shall be restarted when the
                                service process exits, is killed,
                                or a timeout is reached. The service
                                process may be the main service
                                process, but also one of the processes
                                specified with
                                ExecStartPre=,
                                ExecStartPost=,
                                ExecStopPre=,
                                ExecStopPost=, or
                                ExecReload=.
                                When the death of the process is a
                                result of systemd operation (e.g. service
                                stop or restart), the service will not be
                                restarted. Timeouts include missing
                                the watchdog "keep-alive ping"
                                deadline and a service start, reload,
                                and stop operation timeouts.
Takes one of
                                no,
                                on-success,
                                on-failure,
                                on-abort, or
                                always. If set to
                                no (the default) the
                                service will not be restarted. If set to
                                on-success it will be
                                restarted only when the service process
                                exits cleanly.
                                In this context, a clean exit means
                                an exit code of 0, or one of the signals
                                SIGHUP, SIGINT, SIGTERM, or SIGPIPE, and
                                additionally, exit statuses and signals
                                specified in SuccessExitStatus=.
                                If set to on-failure
                                the service will be restarted when the
                                process exits with an nonzero exit code,
                                is terminated by a signal (including on
                                core dump), when an operation (such as
                                service reload) times out, and when the
                                configured watchdog timeout is triggered.
                                If set to
                                on-abort the service
                                will be restarted only if the service
                                process exits due to an uncaught
                                signal not specified as a clean exit
                                status.
                                If set to
                                always the service
                                will be restarted regardless whether
                                it exited cleanly or not, got
                                terminated abnormally by a signal or
                                hit a timeout.
In addition to the above settings,
                                the service will not be restarted if the
                                exit code or signal is specified in
                                RestartPreventExitStatus=
                                (see below).
SuccessExitStatus=¶Takes a list of exit
                                status definitions that when returned
                                by the main service process will be
                                considered successful termination, in
                                addition to the normal successful exit
                                code 0 and the signals SIGHUP, SIGINT,
                                SIGTERM and SIGPIPE. Exit status
                                definitions can either be numeric exit
                                codes or termination signal names,
                                separated by spaces. Example:
                                "SuccessExitStatus=1 2 8
                                SIGKILL", ensures that exit
                                codes 1, 2, 8 and the termination
                                signal SIGKILL are considered clean
                                service terminations. This option may
                                appear more than once in which case
                                the list of successful exit statuses
                                is merged. If the empty string is
                                assigned to this option the list is
                                reset, all prior assignments of this
                                option will have no
                                effect.
RestartPreventExitStatus=¶Takes a list of exit
                                status definitions that when returned
                                by the main service process will
                                prevent automatic service restarts
                                regardless of the restart setting
                                configured with
                                Restart=. Exit
                                status definitions can either be
                                numeric exit codes or termination
                                signal names, and are separated by
                                spaces. Defaults to the empty list, so
                                that by default no exit status is
                                excluded from the configured restart
                                logic. Example:
                                "RestartPreventExitStatus=1 6
                                SIGABRT", ensures that exit
                                codes 1 and 6 and the termination
                                signal SIGABRT will not result in
                                automatic service restarting. This
                                option may appear more than once in
                                which case the list of restart preventing
                                statuses is merged. If the empty
                                string is assigned to this option the
                                list is reset, all prior assignments
                                of this option will have no
                                effect.
PermissionsStartOnly=¶Takes a boolean
                                argument. If true, the permission
                                related execution options as
                                configured with
                                User= and similar
                                options (see
                                systemd.exec(5)
                                for more information) are only applied
                                to the process started with
                                ExecStart=, and not
                                to the various other
                                ExecStartPre=,
                                ExecStartPost=,
                                ExecReload=,
                                ExecStop=,
                                ExecStopPost=
                                commands. If false, the setting is
                                applied to all configured commands the
                                same way. Defaults to
                                false.
RootDirectoryStartOnly=¶Takes a boolean
                                argument. If true, the root directory
                                as configured with the
                                RootDirectory=
                                option (see
                                systemd.exec(5)
                                for more information) is only applied
                                to the process started with
                                ExecStart=, and not
                                to the various other
                                ExecStartPre=,
                                ExecStartPost=,
                                ExecReload=,
                                ExecStop=,
                                ExecStopPost=
                                commands. If false, the setting is
                                applied to all configured commands the
                                same way. Defaults to
                                false.
NonBlocking=¶Set O_NONBLOCK flag for all file descriptors passed via socket-based activation. If true, all file descriptors >= 3 (i.e. all except STDIN/STDOUT/STDERR) will have the O_NONBLOCK flag set and hence are in non-blocking mode. This option is only useful in conjunction with a socket unit, as described in systemd.socket(5). Defaults to false.
NotifyAccess=¶Controls access to the
                                service status notification socket, as
                                accessible via the
                                sd_notify(3)
                                call. Takes one of
                                none (the default),
                                main or
                                all. If
                                none no daemon status
                                updates are accepted from the service
                                processes, all status update messages
                                are ignored. If main
                                only service updates sent from the
                                main process of the service are
                                accepted. If all all
                                services updates from all members of
                                the service's control group are
                                accepted. This option should be set to
                                open access to the notification socket
                                when using
                                Type=notify or
                                WatchdogSec= (see
                                above). If those options are used but
                                NotifyAccess= not
                                configured it will be implicitly set
                                to
                                main.
Sockets=¶Specifies the name of the socket units this service shall inherit the sockets from when the service is started. Normally it should not be necessary to use this setting as all sockets whose unit shares the same name as the service (ignoring the different suffix of course) are passed to the spawned process.
Note that the same socket may be
                                passed to multiple processes at the
                                same time. Also note that a different
                                service may be activated on incoming
                                traffic than inherits the sockets. Or
                                in other words: the
                                Service= setting of
                                .socket units
                                doesn't have to match the inverse of
                                the Sockets=
                                setting of the
                                .service it
                                refers to.
This option may appear more than once, in which case the list of socket units is merged. If the empty string is assigned to this option the list of sockets is reset, all prior uses of this setting will have no effect.
StartLimitInterval=, StartLimitBurst=¶Configure service
                                start rate limiting. By default
                                services which are started more often
                                than 5 times within 10s are not
                                permitted to start any more times
                                until the 10s interval ends. With
                                these two options this rate limiting
                                may be modified. Use
                                StartLimitInterval=
                                to configure the checking interval
                                (defaults to 10s, set to 0 to disable
                                any kind of rate limiting). Use
                                StartLimitBurst= to
                                configure how many starts per interval
                                are allowed (defaults to 5). These
                                configuration options are particularly
                                useful in conjunction with
                                Restart=, however
                                apply to all kinds of starts
                                (including manual), not just those
                                triggered by the
                                Restart= logic.
                                Note that units which are configured
                                for Restart= and
                                which reach the start limit are not
                                attempted to be restarted anymore,
                                however they may still be restarted
                                manually at a later point from which
                                point on the restart logic is again
                                activated. Note that
                                systemctl
                                reset-failed will cause the
                                restart rate counter for a service to
                                be flushed, which is useful if the
                                administrator wants to manually start
                                a service and the start limit
                                interferes with
                                that.
StartLimitAction=¶Configure the action
                                to take if the rate limit configured
                                with
                                StartLimitInterval=
                                and
                                StartLimitBurst= is
                                hit. Takes one of
                                none,
                                reboot,
                                reboot-force or
                                reboot-immediate. If
                                none is set,
                                hitting the rate limit will trigger no
                                action besides that the start will not
                                be
                                permitted. reboot
                                causes a reboot following the normal
                                shutdown procedure (i.e. equivalent to
                                systemctl reboot),
                                reboot-force causes
                                an forced reboot which will terminate
                                all processes forcibly but should
                                cause no dirty file systems on reboot
                                (i.e. equivalent to systemctl
                                reboot -f) and
                                reboot-immediate
                                causes immediate execution of the
                                reboot(2)
                                system call, which might result in
                                data loss.  Defaults to
                                none.
Check systemd.exec(5) and systemd.kill(5) for more settings.
The following options are also available in the
                [Service] section, but exist purely
                for compatibility reasons and should not be used in
                newly written service files.
SysVStartPriority=¶Set the SysV start
                                priority to use to order this service
                                in relation to SysV services lacking
                                LSB headers. This option is only
                                necessary to fix ordering in relation
                                to legacy SysV services, that have no
                                ordering information encoded in the
                                script headers. As such it should only
                                be used as temporary compatibility
                                option, and not be used in new unit
                                files. Almost always it is a better
                                choice to add explicit ordering
                                directives via
                                After= or
                                Before=,
                                instead. For more details see
                                systemd.unit(5). If
                                used, pass an integer value in the
                                range 0-99.
FsckPassNo=¶Set the fsck passno
                                priority to use to order this service
                                in relation to other file system
                                checking services. This option is only
                                necessary to fix ordering in relation
                                to fsck jobs automatically created for
                                all /etc/fstab
                                entries with a value in the fs_passno
                                column > 0. As such it should only be
                                used as option for fsck
                                services. Almost always it is a better
                                choice to add explicit ordering
                                directives via
                                After= or
                                Before=,
                                instead. For more details see
                                systemd.unit(5). If
                                used, pass an integer value in the
                                same range as
                                /etc/fstab's
                                fs_passno column. See
                                fstab(5)
                                for details.