Daemons and Services

│ English (en) │ español (es) │ français (fr) │ polski (pl) │ português (pt) │ русский (ru) │

What are daemons, services and agents?

Unix daemons and Windows services are system-wide programs running without user interaction; macOS agents are per user programs (cf system-wide daemons) that may or may not run without user interaction. Although the nomenclature differs, their function is similar: for example www or ftp servers are called daemons under Linux and services under Windows. Because they do not interact with the user directly, they close their stdin, stdout, stderr descriptors at start.

With Free Pascal, Lazarus it is possible to write these daemons/services platform-independent via the Lazarus lazdaemon package. To avoid name conflicts with the Delphi components these classes are called 'daemons'.

Install the LazDaemon package

Before you can start, install the LazDaemon package. Either via Components / Configure installed packages or by opening/installing the lpk file directly: lazarus/components/daemon/lazdaemon.lpk. This package installs some new components and menu items in the IDE:

Under File - New: 3 items appear in the dialog, under the heading: "Daemon (service) applications":

Creating your first Service Daemon

After having installed the LazDaemon package, from the File-New Menu, pick "Daemon (service) application)". This will automatically create two units: one for a TDaemon descendant, and one for a TDaemonMapper descendant. This is what the scaffolded units look like:

unit DaemonUnit1;

{$mode objfpc}{$H+}

interface

uses
  Classes, SysUtils, DaemonApp;
 
type
  TDaemon1 = class(TDaemon)
  private

  public

  end;

var
  Daemon1: TDaemon1;

implementation

procedure RegisterDaemon;
begin
  RegisterDaemonClass(TDaemon1)
end;

{$R *.lfm}

initialization
  RegisterDaemon;
end.

unit DaemonMapperUnit1;

{$mode objfpc}{$H+}

interface

uses
  Classes, SysUtils, DaemonApp;

type
  TDaemonMapper1 = class(TDaemonMapper)
  private

  public

  end;

var
  DaemonMapper1: TDaemonMapper1;

implementation

procedure RegisterMapper;
begin
  RegisterDaemonMapper(TDaemonMapper1)
end;

{$R *.lfm}

initialization
  RegisterMapper;
end.

The TDaemon class, which is a TDataModule descendant, does all the work of a specific daemon in its execute method. The TDaemonMapper handles the service registration and contains data structures describing the service. Both classes need to be registered, which, in this code sample, is done in the initialization section of each unit. Note that both units have a form resource file, which gives you convenient access to all the event handlers supported by both classes from within the Lazarus GUI. The main application component for a service-style application is introduced by putting a reference to DaemonApp into the uses secion of each unit.

Populating the DaemonMapper Class

For the moment let's just fill some basic properties to get things going.

For later use, note the WinBindings property, which lets you configure various service properties for use by the Windows Service Manager.

Now ... how about testing what we have achieved so far? Sure, our daemon doesn't have any execute routine so far, but didn't I promise that configuring the DaemonMapper would provide all required infos to the Windows Service Manager, and DaemonApp would handle the service install and uninstall? Well, we provided all information required, so install and uninstall should work. To test, compile your application, and open a command line windows with elevated privileges, normal users are by default not allowed to control Windows services. Navigate to the directory where you compiled your test application into, and try out the following commands (SC ist the built-in command line tool to control the Windows Services subsystem):

TestDaemon -install: install the daemon sc query TestDaemon: check the service status, of course, our service doesn't handle any events yet, so any attempt to start it it runs into an error, but note: the service got known to the Windows Services subsystem! TestDaemon -uninstall: remove the daemon, so we can enhance its code for the next try sc query TestDaemon: check whether the service was indeed uninstalled

2022-01-31_23_50_28-Lazarus_IDE_v2.2.0RC2_-_Daemon_application.png

Screenshots taken 2/2022 on a Windows 11 machine.

Daemon - Step by Step

• When the daemon is started the command line parameters are parsed. The following are predefined:
  • -i --install: register the daemon. This has no effect under unix.
  • -u --uninstall: unregister the daemon. This has no effect under unix.
  • -r --run: start the daemon. Windows does this normally itself.
• Create the TDaemonMapper
• Create one TCustomDaemon for each entry of DaemonDefs.
• install, uninstall or run every instance.
• if run: start every instance in its own thread and then wait for Stop/TERM signal.

Daemon Methods

Start

Called when daemon should start. This method must return immediately with True.

Stop

Called when daemon should stop. This method must return immediately with True.

Shutdown

Called when daemon should be killed. This method must stop the daemon immediately and return with True. This is not triggered under Linux. Linux simply kills the daemon.

Pause

Called when daemon should pause. This method must return immediately with True. Under Linux this is not triggered because the kernel stops the whole daemon on STOP and continues it on CONT.

Continue

Called when daemon should continue after a pause. This method must return immediately with True. Under Linux this is not triggered.

Install

Called when daemon is registered as a Windows service. This method should return True on success.

Uninstall

Called when daemon is unregistered as a Windows service. This method should return True on success.

AfterUnInstall

Called after daemon was unregistered as a Windows service. This method should return True on success.

HandleCustomCode

Called when a special signal was sent to the daemon. This method should return True on success.

Example

There is a simple example in examples/cleandir/. Read the README.txt.

Service Installation

Windows

You can install the service by executing the process with the Install parameter. Windows service manager will do the rest for you. You can configure the service and its options from the service manager.

See also: ServiceManager

System codepage / UTF-8

A LazDeamon project is working with default, not UTF-8, codepage. The -dDisableUTF8RTL mode has to be activated with Project Options ... -> Compiler Options -> Additions and Overrides -> Use system encoding.

Linux (only for older Debian)

Download, configure, and "Save As" - the sample script located at Web Archive: [1] (The original link is dead for a long time).

• SVC_ALIAS is the long description of your application
• SVC_FILENAME is the actual file name of your compiled service application
• SVC_DIR is the place your you copied the service application
• SVC_SERVICE_SCRIPT is the final name of the service.sh when you "Save As" the customized debian-service.sh script.

Place your script in the /etc/init.d/ folder

start the service by running "sudo service Name_Of_Your_Script start"

  Note: sudo has some variations, e.g.:

sudo -s #

sudo -H #

sudo -i  #

sudo su  #

sudo sh #

In order to auto-run the service at startup you can try update-rc.d or else will need a third party tool that will do this.

Option 1

sudo update-rc.d Name_Of_Your_Script defaults

Option 2

sudo apt-get install chkconfig
sudo chkconfig --add Name_Of_Your_Script
sudo chkconfig --level 2345 Name_Of_Your_Script on

systemd (Fedora, Debian, SLES12)

Presently, linux flavors are trending away from differing daemon launching and into a unified service model.

Fedora and SuSE Enterprise Linux Server 12 use systemd and with that commands to start/stop services are the same as on debian but there are differences on the configuration files.

• From the command prompt sudo gedit
• Copy and Paste

[Unit]
Description=Long description of your application
After=network.target

[Service]
Type=simple
ExecStart=complete_path_and_file_name -r
RemainAfterExit=yes
TimeoutSec=25

[Install]
WantedBy=multi-user.target

• Edit the following values
  • Description - Long Description of your service application
  • ExecStart - complete-path_and_file_name is the name of your compiled service application with its complete path

• Save As Dialog
  • Navigate to /lib/systemd/system/
  • Name the file the name_of_your_service.service

See also

• ServiceManager Example for the Free Pascal unit for managing Windows services
• macOS daemons and agents - macOS native using launchd
• Office Automation
• Taming the daemon: PDF by Michaël Van Canneyt
• Useful discussion with small working daemon application
• Docker Containerization - Containerization as a means to create daemons / services easily