From PlcWiki

PLC Service is a unified way of running tasks in the background.

Any script or program can be run as a system service.

Contents 1 Service installation 2 Service uninstallation 3 Service list 4 Service configuration 5 Commented configuration file example 6 Tips

Service installation

/usr/local/plc/bin/plc_service_install [-s|--start] <service name>

This command will install (and with -s option even start) a new system service. If the program has the same name as the service, is in /usr/local/plc/bin/ directory and doesn't take any command line options, no other configuration is needed.

Also if a file with name /usr/local/plc/etc/<service name>_<WPID>.cfg or /usr/local/plc/etc/<service name>.cfg exists, it is passed as a parameter to the program by default and no configuration is needed, supposed this is the only option that the program needs.

If the service name is plc, it will install a superservice that will reparent all current PLC services. Such services are launched on boot as plc subservices and are started when the plc superservice is started (and stopped when the plc superservice is stopped) unless it has NOAUTOSTART=yes in its configuration.

All subservices are required to have appropriate configuration file in /usr/local/plc/etc/service/. This configuration file can be empty if the default behaviour is sufficient. For old-style PLC services, an empty configuration file is created upon first start of plc superservice as a part of migration process.

I order to start/stop/query PLC service, use standard SysV commands:

service plc_example start
service plc_example stop
service plc_example restart
service plc_example condrestart
service plc_example status
service plc_example reload       # only if RELOADCOMMAND is defined

Additional specific commands:

service plc_example condstart    # Be silent if the service is already running
service plc_example startalone   # Start without starting possible required services
service plc_example forcestart   # Start even if the program is missing. If KEEPRUNNIG is set,
                                 # the service will recover after the program becomes available

Service uninstallation

/usr/local/plc/bin/plc_service_uninstall [-n|--nostop] [-d|--dead] [<service name>]

This command stops (unless -n option is given) and uninstalls given PLC service.

Uninstalling the plc superservice will cancel starting of all PLC services on boot.

Uninstalling a service when the plc superservice is active will either delete its configuration file in /usr/local/plc/etc/service/ directory (if its empty) or rename it by appending an extension .uninstalled to avoid auto-installing upon next start of the plc superservice.

You can uninstall all services not referenced in /usr/local/plc/etc/service/ directory (i.e. dead services) by this command:

/usr/local/plc/bin/plc_service_uninstall --dead

Service list

/usr/local/plc/bin/plc_service_list [-s] [-c]

List all installed PLC services. -s option also shows their status, -c option also shows the complete command

Status colors have their meaning:

• red: The service is stopped and scheduled to start on boot
• green: The service is running and scheduled to start on boot
• blue: The service is stopped and not scheduled to start on boot
• yellow: The service is running and not scheduled to start on boot

Service configuration

Service configuration file has to be named like this (sorted in the order of precedence):

/usr/local/plc/etc/service/<name>	(also the only mandatory location if the plc superservice is used)
/usr/local/plc/etc/<name>.service.cfg	(deprecated)
/usr/local/plc/etc/<name>	(deprecated)

Contents of multiple configuration files are merged together, however it is recommended to use only one file (preferably /usr/local/plc/etc/service/<name>)

Commented configuration file example

# Not necessary if the program name is the same as the service name
PROGRAM="/usr/local/plc/bin/blah"

# Custom stop command
# STOPCOMMAND="poweroff"

# Custom reload command
# RELOADCOMMAND="dbus-send --system --dest=cz.clever.pmc.blah cz.clever.pmc.Reload"

# Start again if the process gets killed by accident or crashes.
# Set to "yes" by default.
KEEPRUNNING=yes

# Command line arguments
OPTIONS="-v"

# Default stdout log file is named /usr/local/plc/log/<name>.service.log"
#LOG=/tmp/logfile.log

# Default error log file is named /usr/local/plc/log/<name>.service.err.log"
#ERRORLOG=/tmp/errlogfile.log

# If set, standard output and standard error output are redirected to the same file ( $LOG ).
# Set to "yes" by default.
#COMMONLOG=no

# If set, the plc superservice won't start this service when started (however it will stop it when stopped)
# Set to "no" by default.
#NOAUTOSTART=yes

# List of services that have to be started _before_ this one
# Use 'service <name> startalone' to ignore requires
REQUIRES:
      another_service_1
      another_service_2
      another_service_3

# Any other variables set here will be accessible from the program

RUNFASTER=yes
DONTCRASH=yes

Tips

Replacing qdbus calls with dbus-send in PMC services configuration files:

find /usr/local/plc/etc/service -name '*.pmc' -exec sed -i 's|qdbus\s*--system\s*|dbus-send --system --dest=|g' {} \;