From c36b63ef166f72a100da157680ba22b6c6d9323f Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 16 Jun 2009 22:15:14 +0200 Subject: add README --- Makefile.am | 1 + README | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+) create mode 100644 README diff --git a/Makefile.am b/Makefile.am index e77a5a9..65ab36c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -22,6 +22,7 @@ dbussystemdir = $(sysconfdir)/dbus-1/system.d/ dbusservicedir = $(datadir)/dbus-1/system-services/ EXTRA_DIST = \ + README \ GPL \ LICENSE \ org.freedesktop.RealtimeKit1.policy \ diff --git a/README b/README new file mode 100644 index 0000000..9080b65 --- /dev/null +++ b/README @@ -0,0 +1,134 @@ +REALTIMEKIT Realtime Policy and Watchdog Daemon + +GIT: + git://git.0pointer.de/rtkit.git + +GITWEB: + http://git.0pointer.de/?p=rtkit.git + +NOTES: + RealtimeKit is a D-Bus system service that changes the + scheduling policy of user processes/threads to SCHED_RR + (i.e. realtime scheduling mode) on request. It is intended to + be used as a secure mechanism to allow real-time scheduling to + be used by normal user processes. + + RealtimeKit enforces strict policies when handing out + real-time security to user threads: + + * Only clients with RLIMIT_RTTIME set will get RT scheduling + + * RT scheduling will only be handed out to processes with + SCHED_RESET_ON_FORK set to guarantee that the scheduling + settings cannot 'leak' to child processes, thus making sure + that 'RT fork bombs' cannot be used to bypass RLIMIT_RTTIME + and take the system down. + + * Limits are enforced on all user controllable resources, only + a maximum number of users, processes, threads can request RT + scheduling at the same time. + + * Only a limited number of threads may be made RT in a + specific time frame. + + * Client authorization is verified with PolicyKit + + RealtimeKit can also be used to hand outh high priority + scheduling (i.e. negative nice level) to user processes. + + In addition to this a-priori policy enforcement, RealtimeKit + also provides a-posteriori policy enforcement, i.e. it + includes a canary-based watchdog that automatically demotes + all real-time threads to SCHED_OTHER should the system + overload despite the logic pointed out above. + + In its duty to manage real-time scheduling *securely* + RealtimeKit runs as unpriviliged user, and uses capabalities, + resource limits and chroot() to minimize its security impact. + + RealtimeKit probably has little use in embedded or server use + cases, use RLIMIT_RTPRIO tehre instead. + +WHY: + If processes that have real-time scheduling privileges enter a + busy loop they can freeze the entire the system. To make sure + such run-away processes cannot do this RLIMIT_RTTIME has been + introduced. Being a per-process limit it is however easily + cirumvented by combining a fork bomb with a busy loop. + + RealtimeKit hands out RT scheduling to specific threads that + ask for it -- but only to those and due to SCHED_RESET_ON_FORK + it can be sure that this won't "leak". + + In contrast to RLIMIT_RTPRIO the RealtimeKit logic makes sure + that only a certain number of threads can be made realtime, + per user, per process and per time interval. + + +CLIENTS: + To be able to make use of realtime scheduling clients may + request so with a small D-Bus interface that is accessible on + the interface org.freedesktop.RealtimeKit1 as object + /org/freedesktop/RealtimeKit1 on the service + org.freedesktop.RealtimeKit1: + + void MakeThreadRealtime(u64 thread_id, u32 priority); + + void MakeThreadHighPriority(u64 thread_id, s32 priority); + + The thread IDs need to be passed as kernel tids as returned by + gettid(), not a pthread_t! Only threads belonging to the + calling process can be made realtime. + + A BSD-licensed reference implementation of the client is + available in rtkit.[ch] as part of the package. You may copy + this into your sources if you wish. However given how simple + the D-Bus interface is you might choose to implement your own + client implementation. + + It is advisable to try acquiring realtime scheduling with + sched_setsheduler() first, so that systems where RLIMIT_RTPRIO + is set can be supported. + + Here's an example using the reference implementation. Replace + this: + + + struct sched_param p; + memset(&p, 0, sizeof(p)); + p.sched_priority = 3; + sched_setscheduler(0, SCHED_RR|SCHED_RESET_ON_FORK, &p); + + + by this: + + + struct sched_param p; + memset(&p, 0, sizeof(p)); + p.sched_priority = 3; + if (sched_setscheduler(0, SCHED_RR|SCHED_RESET_ON_FORK, &p) < 0 + && errno == EPERM) + rtkit_make_realtime(system_bus, 0, p.sched_priority); + + + But of course add more appropriate error checking! Also, + falling back to plain SCHED_RR when SCHED_RESET_ON_FORK causes + EINVAL migt be advisable). + +ACKNOWLEDGMENTS: + The watchdog logic is inspired by previous work of Vernon + Mauery, Florian Schmidt, Kjetil Matheussen: + + http://rt.wiki.kernel.org/index.php/RT_Watchdog + +LICENSE: + GPLv3+ for the daemon + BSD for the client reference implementation + +AUTHOR: + Lennart Poettering + +REQUIREMENTS: + Linux kernel >= 2.6.31 + D-Bus + PolicyKit >= 0.92 -- cgit