Initial version of faultd documentation

Change-Id: If93c514d6fe5cf13cdf00be43e81aaaef580f461
Signed-off-by: Krzysztof Opasiak <k.opasiak@samsung.com>

diff --git a/doc/HOWTO.rst b/doc/HOWTO.rst
new file mode 100644 (file)
index 0000000..27534a0
--- /dev/null
+++ b/doc/HOWTO.rst
@@ -0,0 +1,91 @@
+Introduction
+============
+
+From the milky way's point of view, faultd is just a dummy daemon for event processing.
+So faultd just listens for some events and executes some action when they arrive.
+Additionally, to make those events traceable, faultd maintains a database where it stores details about all detected events and actions taken.
+
+faultd has a modular architecture.
+Those modules can be grouped based on their responsibility:
+
+1) Core
+   faultd core is a set of modules that provides an event processing framework.
+
+2) Database
+   This is a set of modules that allow to insert and retrieve data from the database.
+   Thanks to this abstraction, it is possible to change the type of database used by the faultd without changing all other modules.
+
+3) Listeners
+   Those modules are responsible for detecting events in the system that should be handled by faultd and reporting them to the core.
+
+#) Decision Makers
+   Those modules are responsible for handling events reported by listeners.
+   Their functionality is to make a decision what should be done when an event arrives.
+   There are two basic types of decisions.
+   First one is to simply ignore the event and do nothing.
+   Second one is to execute some action.
+
+#) Actions
+   Those are modules that interfere with other part of the system by executing some actions like reboot, restart service etc.
+   Every action is identified by a unique string in reverse domain notation.
+
+Usage
+=====
+
+Easiest way to use faultd is to build it into single binary file.
+It should be started during system boot up as early as possible to start it's listener modules.
+All events that appeared in the system before faultd has been started are lost.
+For details about command line parameters please run faultd with -h option.
+
+Configuration
+-------------
+
+faultd configuration is written in json and can be divided into two parts.
+
+First of them is configuration of faultd itself and its modules.
+This is usually placed in /etc/faultd/faultd.conf file.
+Whole file is a single json object.
+Children of that object are configuration node related to given modules.
+So for example child "xxx" is a configuration node related to xxx module.
+This node contains module specific option.
+To find a list of available options check module source code.
+
+Second one is configuration related to particular system service.
+This consist of multiple files placed in /etc/faultd/conf.d/.
+The name of the file in this directory should reflect the systemd service name plus .conf suffix.
+So for example if the configuration is related to bluez.service in should be placed in bluez.service.conf file.
+For now those files are used for two purposes:
+
+1) Set the service type ("ServiceType")
+   To determine if the service is critical for the system and requires special handling ("org.tizen.faultd.service.VIP") or not.
+
+2) To set recovery unit ("RecoveryUnit")
+   This option allows to set which unit should be lunched if service failed.
+
+Plugins management
+------------------
+
+Thanks to faultd modularity it is possible to separate out parts of it's functionality into shared libraries.
+This allows to reduce the size of faultd binary and install some additional functionality when it's needed.
+
+Theoretically every module can be build as a shared library.
+In practice core module should be always built in.
+When module is built as a shared library it is by default placed in /usr/lib/faultd/available-modules.
+There is also a symbolic link to it in /etc/faultd/available-modules.
+To enable particular module it is necessary to create another symbolic link in /etc/faultd/enabled-modules.
+Only modules listed in that directory will be loaded by faultd during start up.
+
+Under the hood
+==============
+
+Architecture
+------------
+
+Core
+----
+
+Modules
+-------
+
+Plugins
+-------