Difference between revisions of "Daemons and Services"

From Free Pascal wiki
Jump to navigationJump to search
(26 intermediate revisions by 13 users not shown)
Line 1: Line 1:
 
{{Daemons and Services}}
 
{{Daemons and Services}}
=What are daemons and services?=
 
  
Unix ''daemons'', Windows ''services'' and Mac OS X ''agents'' are programs running without user interaction. 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.
+
== What are daemons, services and agents? ==
  
With Free Pascal, Lazarus it is possible to write these daemons/services platform-independent via the Lazarus lazdaemon package. To avoid name conlicts with the Delphi components these classes are called 'daemons'.
+
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.
  
=Install LazDaemon=
+
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 LazDaemon ==
  
 
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.
 
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.
+
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":'''
  
=Classes=
+
== Classes ==
  
==TCustomDaemon==
+
=== TCustomDaemon ===
  
 
This is a TDataModule descendant that does all the work. There can be several TCustomDaemons classes and/or instances running at the same time and in the same process (multi threaded).
 
This is a TDataModule descendant that does all the work. There can be several TCustomDaemons classes and/or instances running at the same time and in the same process (multi threaded).
  
==TCustomDaemonApplication==
+
=== TCustomDaemonApplication ===
  
This is a TCustomApplication descendant which creates the TCustomDaemons. This does not need any change. It runs under windows until it receives the Stop call or under linux until the TERM signal.
+
This is a TCustomApplication descendant which creates the TCustomDaemons. This does not need any change. It runs under Windows until it receives the Stop call or under Linux until the TERM signal.
  
==TDaemonMapper==
+
=== TDaemonMapper ===
  
 
This component handles the service registration. Each instance needs one entry in the property '''DaemonDefs'''.
 
This component handles the service registration. Each instance needs one entry in the property '''DaemonDefs'''.
  
=Daemon - Step by Step=
+
== Daemon - Step by Step ==
  
 
*When the daemon is started the command line parameters are parsed. The following are predefined:
 
*When the daemon is started the command line parameters are parsed. The following are predefined:
Line 34: Line 38:
  
 
*Create the TDaemonMapper
 
*Create the TDaemonMapper
 
 
*Create one TCustomDaemon for each entry of ''DaemonDefs''.
 
*Create one TCustomDaemon for each entry of ''DaemonDefs''.
 
 
*install, uninstall or run every instance.
 
*install, uninstall or run every instance.
 
 
*if run: start every instance in its own thread and then wait for Stop/TERM signal.
 
*if run: start every instance in its own thread and then wait for Stop/TERM signal.
  
=Daemon Methods=
+
== Daemon Methods ==
  
==Start==
+
;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.
  
Called when daemon should start. This method must return immediately with ''True''.
+
=== Getting Started ===
  
==Stop==
+
Before you are able to create a Service or Daemon application you must first ensure that the Lazarus Daemon package "lazdaemon" is installed.
  
Called when daemon should stop. This method must return immediately with ''True''.
+
== Example ==
 
 
==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 windows service. This method should return ''True'' on success.
 
 
 
==Uninstall==
 
 
 
Called when daemon is unregistered as windows service. This method should return ''True'' on success.
 
 
 
==AfterUnInstall==
 
 
 
Called after daemon was unregistered as 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.
 
 
 
==Getting Started==
 
Before you are able to create a Service or Daemon application you must first ensure that the Lazarus Daemon package "lazdaemon" is installed.
 
 
 
=Example=
 
  
 
There is a simple example in examples/cleandir/. Read the README.txt.
 
There is a simple example in examples/cleandir/. Read the README.txt.
  
=Service Installation=
+
== Service Installation ==
  
==Windows==
+
=== Windows ===
  
 
You can install the service by executing the process with the Install parameter.
 
You can install the service by executing the process with the Install parameter.
Line 99: Line 72:
 
See also: [[ServiceManager]]
 
See also: [[ServiceManager]]
  
==Linux (Debian)==
+
==== 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 [http://aurawin.com/lazarus/debian-service.sh Service Script].
+
Download, configure, and "Save As" - the sample script located at Web Archive: [https://web.archive.org/web/20130209102726/http://aurawin.com/lazarus/debian-service.sh] (The original link is dead for a long time).
  
 
*SVC_ALIAS is the long description of your application
 
*SVC_ALIAS is the long description of your application
Line 112: Line 88:
 
start the service by running "sudo service Name_Of_Your_Script start"
 
start the service by running "sudo service Name_Of_Your_Script start"
  
 +
{{Note|sudo has some variations, e.g.:
 +
<br/>sudo -s #
 +
<br/>sudo -H #
 +
<br/>sudo -i  #
 +
<br/>sudo su  #
 +
<br/>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.
 
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<syntaxhighlight>
+
Option 1
 +
<syntaxhighlight lang="bash">
 
sudo update-rc.d Name_Of_Your_Script defaults
 
sudo update-rc.d Name_Of_Your_Script defaults
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Option 2<syntaxhighlight>
+
Option 2
 +
<syntaxhighlight lang="bash">
 
sudo apt-get install chkconfig
 
sudo apt-get install chkconfig
 
sudo chkconfig --add Name_Of_Your_Script
 
sudo chkconfig --add Name_Of_Your_Script
Line 125: Line 109:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==Linux (Fedora)==
+
=== systemd (Fedora, Debian, SLES12) ===
 +
 
 
Presently, linux flavors are trending away from differing daemon launching and into a unified service model.  
 
Presently, linux flavors are trending away from differing daemon launching and into a unified service model.  
  
Fedora uses systemd and with that commands to start/stop services are the same as on debian.
+
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
 
* From the command prompt sudo gedit
 
* Copy and Paste
 
* Copy and Paste
<syntaxhighlight>
+
 
 +
<syntaxhighlight lang="ini">
 
[Unit]
 
[Unit]
 
Description=Long description of your application
 
Description=Long description of your application
Line 155: Line 141:
 
** Name the file the name_of_your_service.service
 
** Name the file the name_of_your_service.service
  
 +
== See also ==
  
A sample systemd config file can be found [http://aurawin.com/lazarus/fedora.service Service]
 
  
=See also=
+
* [[ServiceManager]] Example for the Free Pascal unit for managing Windows services
* [[ServiceManager]] Example for the FreePascal unit for managing Windows services
+
* [[macOS daemons and agents]] - macOS native using launchd
 
* [[Office Automation]]
 
* [[Office Automation]]
 
+
* [https://www.freepascal.org/~michael/articles/daemons/daemons.pdf Taming the daemon: PDF by Michaël Van Canneyt]
[[Category:Tutorials]]
+
* [http://forum.lazarus.freepascal.org/index.php/topic,22983.msg152303.html#msg152303 Useful discussion with small working daemon application]
[[Category:Lazarus]]
+
* [[Docker Containerization]] - Containerization as a means to create daemons / services easily

Revision as of 11:45, 8 July 2021

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 LazDaemon

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":

Classes

TCustomDaemon

This is a TDataModule descendant that does all the work. There can be several TCustomDaemons classes and/or instances running at the same time and in the same process (multi threaded).

TCustomDaemonApplication

This is a TCustomApplication descendant which creates the TCustomDaemons. This does not need any change. It runs under Windows until it receives the Stop call or under Linux until the TERM signal.

TDaemonMapper

This component handles the service registration. Each instance needs one entry in the property DaemonDefs.

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.

Getting Started

Before you are able to create a Service or Daemon application you must first ensure that the Lazarus Daemon package "lazdaemon" is installed.

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"

Light bulb  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