doc/design update

Signed-off-by: Denys Vlasenko <dvlasenk@redhat.com>

1 files changed, 54 insertions, 46 deletions

diff --git a/doc/design b/doc/design
index 6074457b..5da16cc2 100644
--- a/doc/design
+++ b/doc/design
@@ -40,68 +40,76 @@ to a dedicated server(s) for processing (backtrace, etc).
 Abrt design should be flexible enough to accomodate all
 of the above usage scenarios.
 
-The description below is not what abrt does now.
-It is (currently incomplete) design notes on how we want
-it to achieve design goals.
-
 Since currently we do not know how to dump oops on demand,
-we can only poll for it. There is a small daemon which polls
-kernel message buffer and dumps oopses when it sees them.
-The dump is written into /var/spool/abrt/DIR.
-After this, daemon spawns "abrt-process -d /var/spool/abrt/DIR"
-which processes it according to configuration in /etc/abrt/*.conf.
+we can only poll for it. There is a small daemon, abrt-dump-oops,
+which polls syslog file and saves oopses when it sees them.
+The oops dump is written into /var/spool/abrt/DIR.
+[TODO? abrt-dump-oops spawns "abrt-handle-crashdump -d /var/spool/abrt/DIR"
+which processes it according to configuration in /etc/abrt/*.conf]
 
 In order to catch binary crashes, we install a handler for it
 in /proc/sys/kernel/core_pattern (by setting it to
-"|/usr/libexec/abrt-hook-ccpp /var/spool/abrt %p %s %u").
+"|/usr/libexec/abrt-hook-ccpp /var/spool/abrt ....").
 When process dumps core, the dump is written into /var/spool/abrt/DIR.
-After this, abrt-hook-ccpp spawns "abrt-process -d /var/spool/abrt/DIR"
-and terminates.
-
-When python program crashes, it invokes internel python subroutine
-which dumps crash info into ~/abrt/spool/DIR.
-[this is a tentative plan, currently we dump in /var/spool/abrt/DIR]
-After this, it spawns "abrt-process -d ~/abrt/spool/DIR"
-and terminates.
-
-[Problem: dumping to /var/spool/abrt/DIR needs world-writable
-/var/spool/abrt and allows user to go way over his
-disk quota. Dumping to ~/abrt/spool/DIR makes it difficult
-to present a list of all crashes which happened on the machine -
-for example, root-owned processes cannot even access user data
-in ~user/* if /home is on NFS4...
-]
+[TODO? after this, abrt-hook-ccpp spawns "abrt-handle-crashdump
+-d /var/spool/abrt/DIR"]
+Then abrt-hook-ccpp terminates.
+
+When python program crashes, it invokes internal python subroutine
+which connects to abrtd via /var/run/abrt/abrt.socket and sends
+crash data to abrtd. abrtd creates dump dir /var/spool/abrt/DIR.
+
+abrtd daemon watches /var/spool/abrt for new directories.
+When new directory is noticed, abrtd runs "post-create" event
+on it, and emits a dbus signal. This dbus signal is used
+to inform online users about the new crash: if abrt-applet
+is running in X session, it sees the signal and starts blinking.
+
+[The above scheme is somewhat suboptimal. It's stupid that abrtd
+uses inotify to watch for crashes. Instead the programs which create crashes
+can trigger their initial ("post-create") processing themselves]
+
+Crashes conceptually go through "events" in their lives.
+Apart from "post-create" event decribed above, they may have
+"analyze" event, "reanalyze" event, "report[_FOO]" events,
+ans arbitrarily-named other events.
+abrt-handle-crashdump tool can be used to "run" an event on a directory,
+or to query list of possible events for a directory.
+/etc/abrt/abrt_event.conf file describes what should be done on each event.
 
 When user (admin) wants to see the list of dumped crashes and
 process them, he runs abrt-gui or abrt-cli. These programs
 perform a dbus call to "com.redhat.abrt" on a system dbus.
 If there is no program with this name on it, dbus autostart
-will invoke "abrt-process", which registers "com.redhat.abrt"
+will invoke abrtd, which registers "com.redhat.abrt"
 and processes the call(s).
 
-abrt-process will terminate after a timeout (a few minutes)
-if no new dbus calls are arriving to it.
-
-The key dbus calls served by abrt-process are:
+The key dbus calls served by abrtd are:
 
 - GetCrashInfos(): returns a vector_map_crash_data_t (vector_map_vector_string_t)
      of crashes for given uid
      v[N]["executable"/"uid"/"kernel"/"backtrace"][N] = "contents"
-[see above the problem with producing this list]
-- CreateReport(UUID): starts creating a report for /var/spool/abrt/DIR with this UUID.
+- CreateReport(/var/spool/abrt/DIR): starts creating a report.
      Returns job id (uint64).
-     After it returns, when report creation thread has finished,
-     JobDone(client_dbus_ID,UUID) dbus signal is emitted.
+     Then abrtd run "analyze" event on the DIR.
+     After it completes, when report creation thread has finished,
+     JobDone(client_dbus_ID,/var/spool/abrt/DIR) dbus signal is emitted.
   [Problem: how to do privilegged plugin specific actions?]
     Solution: if plugin needs an access to some root only accessible dir then
     abrt should be run by root anyway
     - debuginfo gets installed using pk-debuginfo-install, which cares about
     privileges itself, so no problem here
-- GetJobResult(UUID): returns map_crash_data_t (map_vector_string_t)
+- GetJobResult(/var/spool/abrt/DIR): returns map_crash_data_t (map_vector_string_t)
 - Report(map_crash_data_t (map_vector_string_t)):
-     "Please report this crash": calls Report() of all registered reporter plugins
-     Returns report_status_t (map_vector_string_t) - the status of each call
-- DeleteDebugDump(UUID): delete corresponding /var/spool/abrt/DIR. Returns bool
+     "Please report this crash": 
+     abrtd run "report[_FOO]" event(s) on the DIR.
+     Returns report_status_t (map_vector_string_t) - the status of each event
+- DeleteDebugDump(/var/spool/abrt/DIR): delete /var/spool/abrt/DIR. Returns bool
+
+[Note: we are in the process of reducing/eliminating
+dbus communication between abrt-gui/abrt-cli and abrtd.
+It seems we will be able to reduce dbus messages to "crash occurred"
+signal and "DeleteDebugDump(DIR)" call]
 
 
 	Development plan
@@ -112,17 +120,17 @@ change the code to "morph" it into the desired shape.
 Done:
 
 * Make abrtd dbus startable.
-* Add -t TIMEOUT_SEC option to abrtd. {done}
+* Add -t TIMEOUT_SEC option to abrtd.
 * Make abrt-gui start abrtd on demand, so that abrt-gui can be started
-  even if abrtd does not run at the moment. (doesn't work in some cases!)
-
-Planned steps:
-
+  even if abrtd does not run at the moment.
 * make kerneloops plugin into separate daemon (convert it to a hook
   and get rid of "cron plugins" which are wrong idea since the begining)
-  - and make it to the service (write an initscript)
 * make C/C++ hook to be started by init script
-  - init scritp would run ccpp-hook --init whic shoudl just set the core_pattern, which is now done by the C analyzer plugin
+* add "include FILE" feature to abrt_event.conf
+
+Planned steps:
+
+* make kerneloops plugin into separate service?
 * hooks will start the daemon on-demand using dbus
   - this is something I'm not sure if it's good idea, but dbus is becoming
     to be "un-installable" on Fedora, it's probably ok