CDEmu Daemon
3.2.7
~~~~~


Table of Contents:
~~~~~~~~~~~~~~~~~~

1. Introduction
2. CDEmu suite overview
3. Requirements
4. Installation and set-up
5. Troubleshooting
6. CDEmu daemon D-BUS interface
7. Device options
8. Debugging
9. Hard-disk images
10. Encrypted images and password supplying
11. System bus vs. session bus
12. Deprecation of running on system bus
13. Configuration file
14. CDEmu as D-BUS on-demand service (the daemon autostart)
15. Contact information


1. Introduction
~~~~~~~~~~~~~~~

This is CDEmu daemon, the daemon part of the cdemu suite, a free,
GPL CD/DVD-ROM device emulator for linux.

This document describes both the cdemu suite in general, and the
specifics of CDEmu daemon, such as installation quirks, troubleshooting, and
daemon's D-BUS interface.


2. CDEmu suite overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The whole cdemu suite is intended as a rewrite of the cdemu kernel module
and userspace utility that was once written by Robert Penz. But instead of
providing only block device and linux uniform CD-ROM driver interface, CDEmu
daemon tries to implement packet command set as specified by MMC-3 and INF-8090,
thus fully emulating an optical storage device.

Main features:
 - full SCSI device emulation: CDEmu daemon attempts to implement MMC-3 packet
     command set, therefore allowing virtual devices to be used not only as
     block devices, but as full SCSI devices. Aside from mounting the device,
     you can use dd on it, use it with CD-player, or even copy the loaded image
     using one of linux's CD-ROM burning utilities. In addition, CDEmu devices
     can also be used with WINE.
 - multiple image format support: cdemu utilizes libMirage, an image
     access library, which attempts to provide unified access to various CD-ROM
     image formats (including B6T, CCD, CDI, CUE, ISO, MDS, NRG and TOC)
 - debugging: both CDEmu daemon and underlying libMirage library have debugging
     code that supports changing verbosity of debug messages while daemon is
     running, making it easier to discover and fix problems.

The whole cdemu suite consists of three major components:
 - kernel module
 - daemon
 - clients

2.1. Kernel module
~~~~~~~~~~~~~~~~~~

Kernel module, written by Chia-I Wu, takes care of device emulation in the kernel;
it registers virtual device with appripriate drivers and creates corresponding device
nodes. It also creates a special character device that is used for communication
with userspace.

As device is accessed, requests are generated by kernel, which are in fact SCSI
commands. These are passed to userspace daemon via afore-mentioned character
device. Once daemon processes the request, it returns appropriate data and
status to kernel, thus completing the request.

The whole process is very similar to accessing real device, except that requests
are passed to userspace daemon instead to hardware.

2.2. Daemon
~~~~~~~~~~~

This is the part that these docs (should) belong to. The daemon receives SCSI
commands from kernel module and processes them, passing the requested data back
to the kernel.

Daemon implements the actual virtual device; one instance per each device
registered by kernel module. It uses libMirage, an image access library that is
part of the cdemu suite, for the image access (e.g. sector reading).

Daemon is controlled through methods that are exposed via D-BUS. It is written
in C and based on GLib (and thus GObjects), but being controlled over D-BUS, it
allows for different clients written in different languages.

2.3. Clients
~~~~~~~~~~~~

Clients are used to control the daemon; examples of the tasks that can be
achieved by using daemon's D-BUS interface are: loading and unloading a device,
checking device(s) status, setting the debug mask, etc.

A client can be written in any language, as long as it has D-BUS bindings; it can
be either a CLI or a GUI application. For illustration, two clients are included
as part of cdemu:
 - cdemu-client: a simple CLI client
 - gcdemu: a Gtk3-based GUI client
For more information about these particular clients, consult their documentation.

Should you be interested in writing your own client, there is a section in this
document that describes the daemon's interface, methods and signals.


3. Requirements
~~~~~~~~~~~~~~~

CDEmu daemon has the following software requirements:

 - CMake >= 3.7.0
 - GLib >= 2.38
 - libao >= 0.8.0

 - libMirage >= 3.2.0 (part of the suite)
 - VHBA module >= 20170610 (part of the suite)


4. Installation and set up
~~~~~~~~~~~~~~~~~~~~~~~~~~

Please read the INSTALL file. Note however that there are some quirks one should
be aware of.

libMirage, which is part of the cdemu suite, is also required. If you
are building and installing it yourself, make sure that its .pc file is visible
to pkg-config utility; if you are using /usr prefix, you should be fine, but in
case /usr/local or something else is used and you haven't set up pkg-config to
look there, you might need to force it to do so.

For example, if libMirage was installed to /usr/local, CMake would have to
be run as this way:

export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig"
mkdir build && cd build
cmake ..

VHBA module is not a build-time dependency, but it might be a good idea to have
it installed at this point.

By default, the daemon registers its interface on session D-BUS' bus
(it is also possible to use system bus instead, but as explained in
Section 12, this is discouraged). We provide example service files for
deploying the daemon as D-BUS activated systemd service; for details, see
Section 14.

We use a single libao backend to support CD-audio playback. This allows you to
select from a number of available audio drivers. Valid choices are the driver
names used by libao as well as "default" and "null". CDEmu is usually
configured to use the "default" libao audio driver, which means that the
audio driver specified in libao's config file ("/etc/libao.conf" or "~/.libao")
is used. If "null" is specified, audio is sent to the null driver, essentially
turning off audio playback. For a full list of valid driver names have a look
at the libao documentation, in particular the "libao.conf" manpage.

Also note that most media players on Linux are capable of digital audio
extraction, meaning they can play CD-audio directly without relying on the
"analog" playback capabilities of the virtual optical device. Because of this
it's possible to use the libao "null" driver and still play CDs normally.


5. Troubleshooting (When bad things happen to good people)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Q: I built and installed the module, but I can't insert it ('modprobe vhba'
results in something along the lines of 'FATAL: Module vhba not found.').

A: Try running 'depmod -a' after you have installed the module.


Q: Daemon fails to start with the following message:
    'cdemu0: Kernel I/O: failed to open control device /dev/vhba_ctl: No such file or directory!
     cdemu: Daemon: failed to start device #0!
     cdemu: Daemon: failed to create device!
     Daemon initialization and start failed!'

A: The message indicates that vhba module is not loaded. Please make
   sure that vhba module is installed and loaded.


Q: Daemon fails to start with the following message:
    'cdemu0: Kernel I/O: failed to open control device /dev/vhba_ctl: Permission denied!
     cdemu: Daemon: failed to start device #0!
     cdemu: Daemon: failed to create device!
     Daemon initialization and start failed!'

A: The message indicates that you don't have read/write permissions for
   /dev/vhba_ctl. You need to set read/write permissions on vhba control
   device for your username - either manually, or by means of a udev rule.


Q: Daemon fails to start with the following message:
    'cdemu: cdemud_daemon_initialize: failed to get name on system bus!
     Daemon initialization failed: Name request on D-BUS failed.'

A: The message indicates that name registration on the system bus has failed.
   In case you are trying to run the daemon on system bus, the most likely cause
   of error are improper permissions. Make sure that CDEmu daemon's D-BUS configuration
   file is in proper place and that you are running the daemon as root.
   If you are trying to run the daemon on session bus, you need to run the daemon
   as the user who owns the (X11) session. Running from Virtual Terminals (VTs) with
   session bus might also fail (depending on your configuration), because by default,
   D-BUS' session bus is tied to the X11 log-in session.


Q: Daemon fails to start with the following message:
   cdemu0: cdemud_audio_initialize: failed to open audio device
   (driver: 'default')!

A: Most likely you will need to specify a working audio driver in libao's config
   file (/etc/libao.conf or ~/.libao).


6. CDEmu daemon D-BUS interface (a.k.a. writing your own client)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Communication between CDEmu daemon and a client is done via D-BUS. CDEmu daemon
registers itself on either sytem or session bus, where it exposes the interface
which can be used by client to control the daemon.

The interface is versioned using a dual-number scheme, where version
consists of a major and minor component. Such scheme allows interfaces to
be declared as backwards-compatible. Whenever daemon's interface is changed
in backwards-compatible way, the minor version is incremented; if changes
break backwards-compatibility, the major version is incremented and the
minor version is reset to 0.

Currently implemented interface version: 7.0


6.1. D-BUS name and object path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The name CDEmu daemon requests on the system bus is "net.sf.cdemu.CDEmuDaemon",
whereas the object path is "/Daemon". The name of the interface is
"net.sf.cdemu.CDEmuDaemon".

To illustrate, a simple python program connecting to daemon registered on system
bus would therefore look like this:

import dbus
if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
    import dbus.glib

system_bus = dbus.SystemBus()
dbus_proxy = system_bus.get_object('net.sf.cdemu.CDEmuDaemon', '/Daemon')
dbus_iface = dbus.Interface(dbus_proxy, 'net.sf.cdemu.CDEmuDaemon')

6.2. Methods
~~~~~~~~~~~~

For more information on D-BUS methods, argument direction and signatures or
language-specific data type mappings, please consult the D-BUS documentation.

CDEmu daemon's interface consists of the following methods that can be used to
control the daemon:

* GetDaemonVersion (version)
    + version: out; "s"
        Daemon version string.

    - Returns daemon version string.

* GetLibraryVersion (version)
    + version: out; "s"
        Library version string

    - Returns library version string of libMirage library used by
      the daemon.

* GetDaemonInterfaceVersion (version)
    + version: out; "i"
        Daemon interface (major) version

    - Returns daemon interface version, which should be used to detect
      if client can use the interface or not.

* GetDaemonInterfaceVersion2 (version)
    + major: out; "i"
        Daemon interface major version
    + minor: out; "i"
        Daemon interface minor version

    - Returns daemon interface version, which should be used to detect
      if client can use the interface or not.

* EnumDaemonDebugMasks (type, masks)
    + masks: out; "a(si)"
        Array of structures containing supported debug masks. Each structure
        has two fields; debug mask name (string) and debug mask value (int).

    - Returns debug masks supported by the daemon.

* EnumLibraryDebugMasks (type, masks)
    + masks: out; "a(si)"
        Array of structures containing supported debug masks. Each structure
        has two fields; debug mask name (string) and debug mask value (int).

    - Returns debug masks supported by the libMirage library that is used by
      the daemon.

* EnumSupportedParsers (parsers)
    + parsers: out; "a(ssa(ss))"
        Array of structures containing information about supported parsers.
        Each structure has multiple fields; parser ID (string), parser name
        (string), and array of supported file types, each comprising a file
        type description (string) and image file MIME type
        (string).

    - Returns supported image parsers.

* EnumSupportedWriters (writers)
    + writers: out; "a(sss)"
        Array of structures containing information about supported writers.
        Each structure has multiple fields; writer ID (string), writer name
        (string), and a writer's parameter sheet XML, which describes the
        writer's parameters.

    - Returns supported image writers.

* EnumSupportedFilterStreams (filter_streams)
    + filter_streams: out; "a(ssba(ss))"
        Array of structures containing information about supported filter
        streams. Each structure has multiple fields; filter stream ID
        (string), filter stream name (string), a flag indicating whether
        filter stream supports writing, and an array of supported
        file types, each comprising a file type description (string)
        and file type MIME type (string).

    - Returns supported filter streams.

* EnumWriterParameters (writer_id, parameter_sheet)
    + writer_id: in; "s"
        Writer ID string.
    + parameter_sheet: out; "a(sssvas)"
        Array of structures containing information about image writer's
        parameters. Each structure has multiple fields: parameter ID (string),
        parameter name (string), parameter description (string), default
        value for parameter (variant) - this one also determines parameter
        value type, and array of valid enum values (array of strings) -
        if this field is non-empty, then the parameter is of enum type.

    - Retrieves parameter sheet for image writer with specified ID.

* GetNumberOfDevices (number_of_devices)
    + number_of_devices: out; "i"
        Number of devices (int).

    - Returns number of virtual devices.

* DeviceGetMapping (device_number, sr_device, sg_device)
    + device_number: in; "i"
        Device you are requesting mapping for (int).
    + sr_device: out; "s"
        /dev/srX device node for specified device (string)
    + sg_device: out; "s"
        /dev/sgY device node for specified device (string)

* DeviceGetStatus (device_number, loaded, file_names)
    + device_number: in; "i"
        Device you are requesting status for (int).
    + loaded: out; "b"
        Boolean denoting whether device is loaded or not.
    + file_names: out; "as"
        Image's file name(s) (string). If device is not loaded, an empty array is
        returned.

    - Returns the status of specified device.

* DeviceLoad (device_number, filenames, parameters)
    + device_number: in; "i"
        Device that is to be loaded (int).
    + filenames: in; "as"
        File name(s) of the image to be loaded (array of strings).
    + parameters: in; "a{sv}"
        Additional (optional) parameters, stored in a D-BUS dictionary type. If
        no parameters are needed, empty dictionary should be sent.
        Currently supported parameters:
            - "password": password for encrypted images (string)
            - "encoding": encoding for text-based images (string)

    - Attempts to load the image into specified device.
    - The client might wish to detect MIRAGE_E_NEEDPASSWORD error, which
      indicates that the image is encrypted and needs a password provided via
      parameters.

* DeviceCreateBlank (device_number, filename, parameters)
    + device_number: in; "i"
        Device on which blank disc should be created (int).
    + filename: in; "s"
        Filename/basename for image file to be created.
    + parameters: in; "a{sv}"
        Image writer parameters, stored in a D-BUS dictionary type. The
        following parameters are supported directly:
            - "writer-id": image writer ID (string); MANDATORY
            - "medium-type": medium type (string): optional; valid values:
                + "cdr74": CD-R 74 min (650 MB)
                + "cdr80": CD-R 80 min (700 MB)
                + "cdr90": CD-R 90 min (800 MB)
                + "cdr99": CD-R 99 min (900 MB)
                + "dvd+r": DVD+R, Single-Layer
        Additionally, the parameters from writer's parameter sheet may
        be passed, but they need to be prefixed with "writer.", i.e.:
            - "writer.writer_parameter_id": parameter value

    - Creates blank recordable disc in the specified device.

* DeviceUnload (device_number)
    + device_number: in; "i"
        Device that is to be unloaded (int).

    - Attempts to unload the device.

* DeviceGetOption (device_number, option_name, option_values)
    + device_number: in; "i"
        Device for which the specified option's value is to be retrieved (int).
    + option_name: in; "s"
        Name of the option (string).
    + option_values: out; "v"
        Option value (variant). The actual content depends on the option.

    - This method retrieves the value(s) of specified option for specified device.
      For more information on supported options, see Section 7.

* DeviceSetOption (device_number, option_name, option_values)
    + device_number: in; "i"
        Device for which the specified option's value is to be set (int).
    + option_name: in; "s"
        Name of the option (string).
    + option_values: in; "av"
        Option value (variant). The actual content depends on the option.

    - This method sets the value(s) of specified option for specified device.
      For more information on supported options, see Section 7.

* AddDevice ()
    - Creates additional virtual device

* RemoveDevice ()
    - Removes the last-created virtual device

6.3. Signals
~~~~~~~~~~~~

In addition to the methods, CDEmu daemon's interface emits the following signals
in response to the change of status of either the daemon or one of the devices:

* DeviceStatusChanged
    + device_number: "i"
        Device that emitted the signal (int).

    - emitted when device is loaded/unloaded

* DeviceOptionChanged
    + device_number: "i"
        Device that emitted the signal (int).
    + option: "s"
        Option that has been changed (string).

    - emitted when device's option is changed

* DeviceMappingReady
    + device_number: "i"
        Device that emitted the signal (int).

    - emitted when the device's mapping to /dev/srX and /dev/sgY are established



Daemon start/stop detection:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To detect daemon start/stop events, clients should monitor the
"NameOwnerChanged" signal on the org.freedesktop.DBus interface.

The daemon registers itself on the bus after all devices have been created so
when the name ownership request is detected, the daemon and devices are ready
for use. At this point devices' mappings are not ready yet; when they become
available, each device emits "DeviceMappingReady" signal.


7. Device options
~~~~~~~~~~~~~~~~~

CDEmu virtual devices have the following options that can be get/set via the
DeviceGetOption/DeviceSetOption API. Please note that number of arguments and
argument types for DeviceSetOption function are strictly checked; i.e. tbe
method call will fail, for example, if argument for the 'dpm-emulation option'
is of type G_TYPE_INT.

* dpm-emulation
   + arguments: enabled (boolean - "b")

   - DPM emulation flag. Determines whether DPM emulation is performed.

* tr-emulation
   + arguments: enabled (boolean - "b")

   - Transfer rate emulation flag. Determines whether transfer rate emulation is
     performed

* bad-sector-emulation
   + arguments: enabled (boolean - "b")

   - Bad sector emulation flag. Determines whether bad sector emulation is
     performed. This involves reading sector's data, computing error detection
     code (EDC) over it, and comparing it to stored EDC; if the two do not
     match, sector is proclaimed as a bad one. Some copy-protection schemes
     rely on this behavior.

* dvd-report-css
   + arguments: enabled (boolean - "b")

   - A boolean indicating whether the DVD should report CSS/CPPM or not.
     This flag might be required by some media players when a raw
     image of a CSS-protected DVD is loaded into virtual device.

* device-id
   + arguments: vendor_id, product_id, revision, vendor_specific  (tuple of strings:  - "(ssss)"

   - Device ID. Determines the device identifier (vendor identifier, product
     identifier, product revision and vendor-specific string) as returned by
     INQUIRY command. Changing the ID might be useful in cases when an
     application doesn't like the default ID for some reason.

   - Note that the length of argument strings should be as following: vendor_id
     8 characters, product_id 16 characters, revision 4 characters and
     vendor_specific 20 characters. The actual arguments can surpass these
     lengths, but only specified amount of characters will actually be used by
     the device.

* daemon-debug-mask
   + arguments: mask (integer - "i")

   - Daemon debug mask. Determines the amount of verbosity of daemon's code.

* library-debug-mask
   + arguments: mask (integer - "i")

   - Library debug mask. Determines the amount of verbosity of libMirage library
     used by the daemon.


8. Debugging
~~~~~~~~~~~~

Both CDEmu daemon and the underlying libMirage contain debugging code that
supports changing the verbosity of debug traces while the daemon is running
and processing requests.

The details of changing the debug mask vary from client to client, but in
general it should be possible to change the debug mask of every device for
either the daemon or the library. Supported masks can be obtained from the
daemon for both components. The actual mask is combination of these masks and
determines which traces get printed and which not.

When daemon is run in non-daemon mode, it prints the traces into console. When
run in daemon mode, system logger (i.e. syslogd) is used.

Using appropriate debug mask and monitoring the output, the source of problem
can be quickly found, be it either a failure in loading an image or incorrect
response to the given command.

If you are debugging the daemon using the GNU Debugger (gdb) and get an error
reading "failed to open control device" then you need to check your permissions.
GDB doesn't honor any set-UID or set-GID flags on the daemon executable so you
will have to make sure that your user has read and write permissions on the
control device.


9. Hard-disk images
~~~~~~~~~~~~~~~~~~~

It possible to use CDEmu to mount certain hard-disk images that are
supported by libMirage. However, hard-disk device emulation is not
implemented, but rather the data is simply laid out in a fashion
according to standard 2048-sector data CD-ROMs. Due to the lack of
block-device access, you may run into some problems when attempting to
mount some images.

The mount command may complain that it could not set a sector size of
512 which is the de-facto standard hard-disk sector size. Mount may
also complain that it was unable to find filesystem signatures, and
therefore refuse to mount the CDEmu device. To work around this, a
loopback device can be used.

Say for instance you have loaded an Apple Disk image (.img.bin) and
Linux will not mount the CDEmu device (for instance /dev/sr1).
You can solve this by loopback mounting the device like so:

mount -t hfsplus -o loop /dev/sr1 /mnt/hfsvolume

where /mnt/hfsvolume is your mountpoint. Alternatively, you can use
the losetup program to achieve the same. Losetup also have some
other neat features like setting the offset and size of the image
or device to mount, so if you know the size and offset of
a partitioned image you could for instance choose to loopback mount
only one single partition. Note that in the case of HFS/HFS+ you can
also specify the partition number to mount via the -o part=# option.


10. Encrypted images and password supplying
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

libMirage offers basic support for encrypted images which is supported by
the CDEmu daemon as well.

Encrypted images require password to decrypt the data. When image loading is
performed in libMirage, the parser detects whether password is required, and if
it is, it issues a callback to obtain it from the user.

The problem is that CDEmu daemon and its clients use synchronous communication,
which means that there is no way to propagate the password request from the
callback back to the client, i.e. by the means of emitting signal from daemon
(because technically, the image loading function is still in progress and the
client is waiting for its return status).

Therefore, if no password is provided via 'parameters' argument of DeviceLoad
method and the image loading requires password, the method will fail and return
error MIRAGE_E_NEEDPASSWORD. In this case, client might want to prompt the user
for password and then call DeviceLoad again, this time with password set in
'parameters' argument. If password is incorrect, the method will fail, returning
error MIRAGE_E_WRONGPASSWORD. Otherwise, the image should be loaded successfully
(provided no other errors occured).

Of course, nothing prevents the client to allow the user to enter password as an
optional argument the first time image is loaded.


11. System bus vs. session bus
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

CDEmu daemon registers a D-BUS interface that can be used by clients to communicate with it;
from the initial release on, the interface could be registered either on system or session bus.

A session bus instance is created for every user session, and is visible only within that session.
On the other hand, there's only one instance of system bus, which is visible system-wide.

This means that when session bus is used, every user can run its own instance of CDEmu daemon, as
long as device number limit of VHBA module is not reached. There can be only one instance of the
daemon running on system bus, but it is visible to all users. Also, a single instance of daemon on
system bus and multiple instances on session busses can be running at the same time.

Note that running on system bus requires special permissions; to this end, CDEmu daemon installs a
D-BUS config file which by default allows root to run daemon on system bus. Session bus requires
no such permissions, but the user running the daemon must have read/write permissions to VHBA
character control device.


12. Deprecation of running on system bus
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Running the daemon on system bus is considered deprecated and should be avoided
for various reasons listed below.

First and foremost, running the CDEmu daemon on the system bus leads to security issues in
multi-user environment; any user with access to the daemon over D-BUS is able to load every single
image on the whole system (assuming the daemon is running as root). Effectively, it is also possible
to check existence of files in folders where the user does not have access (by attempting to load a
file as an image and look at the error).

Additionally, some of the services that CDEmu might (indirectly) depend on, are nowdays run in session
mode as well, and require to be accessed from within the session. One example would be PulseAudio audio
daemon, which is commonly configured to be run in per-session mode and might be use by CDEmu's audio
backend. The other example would be GVFS, which might provide the user access to images stored on remote
filesystems (e.g. via CIFS or SSH).


13. Configuration file
~~~~~~~~~~~~~~~~~~~~~~

The command-line arguments that are passed to daemon (e.g., --num-devices, --audio-driver; for full list,
see the manual page or run the daemon with --help option) can be optionally collected into a configuration
file that is passed to the daemon via the --config-file option.

The configuration file must adhere to the syntax used by glib's GKeyFile parser. The file must contain
a section called [settings], in which the options are specified as key=value pairs, with keys corresponding
to long names of the command-line arguments. For example, passing the following configuration file via
--config-file=example.config is equivalent to passing --num-devices=2 --audio-driver=pulse directly to the
daemon:

# example.config
[settings]
num-devices=2
audio-driver=pulse

If  an  option  is specified in both configuration file and on command-line, the latter takes precedence.
This allows the configuration file to be used as a preset base, which is further tweaked/overridden via
command-line.

If the specified configuration file does not exist, it is silently  ignored. If  the specified configuration
file is invalid (e.g., has invalid syntax, or does not contain a section), an error is raised. This allows
start up script to use pre-determined paths to optional user-provided configuration files without having
to check for their existence.


14. CDEmu as D-BUS on-demand service (the daemon autostart)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

D-BUS offers on-demand startup of services; when a client attempts to contact a service that is not running,
D-BUS can launch that service. The service itself can be deployed either as a regular executable or shell
script, or as a SystemD-controlled service.

CDEmu daemon provides example service files for deploying the daemon as D-BUS activated SystemD user service.
These service files are *not* installed automatically by CMake; instead, they need to be deployed manually
by the user or packaged at packager's discretion (which also allows the use of different startup mechanism).

The example service files are located in the "service-example" directory, along with a README.md file
containing deployment instructions.

NOTE: the service files are provided as an example. Alternative deployments that do not involve SystemD are
also possible; for example, earlier versions of CDEmu daemon used D-BUS service with launcher shell script
instead.


15. Contact information
~~~~~~~~~~~~~~~~~~~~~~

CDEmu project's web page: http://cdemu.sourceforge.net
CDEmu project's mailing list: cdemu-devel@lists.sourceforge.net

Author can be directly contacted via e-mail address listed in AUTHORS file.