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. For more information regarding canary-based RT watchdogs, see the Acknowledgments section below. 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/high priority. (Please note that gettid() is not available in glibc, you need to implement that manually using syscall(). Consult the reference client implementation for details.) 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: <snip> struct sched_param p; memset(&p, 0, sizeof(p)); p.sched_priority = 3; sched_setscheduler(0, SCHED_RR|SCHED_RESET_ON_FORK, &p); </snip> by this: <snip> 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); </snip> 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). DAEMON: The daemon is automatically started on first use via D-Bus system bus activation. Currently the daemon does not read on any configuration file, however it can be configured with command line parameters. You can edit /usr/share/dbus-1/system-services/org.freedesktop.RealtimeKit1.service to set those. Run /usr/libexec/rtkit-daemon --help to get a quick overview on the supported parameters and their defaults. Many of them should be obvious in their meaning. For the remaining ones see below: --max-realtime-priority= may be used to specify the maximum realtime priority a client can acquire through RealtimeKit. Please note that this value must be smaller than the value passed to --our-realtime-priority=. --our-realtime-priority= may be used to specify the realtime priority of the daemon itself. Please note that this priority is only used for a very short time while processing a client request. Normally the daemon will not be running with a realtime scheduling policy. The real-time priorities handed out to the user must be lower than this value. (see above). --min-nice-level= may be used to specify the minimum nice level a client can acquire through RealtimeKit. --our-nice-level= may be used to specify the nice level the the daemon itself uses most of the time (except when processing requests, see above). It is probably a good idea to set this to a small positive value, to make sure that if the system is overloaded already handing out further RT scheduling will be delayed a bit. --rttime-usec-max= may be used to control which RLIMIT_RTTIME value clients need to have chosen at minumum before they may acquire RT scheduling through RealtimeKit. --users-max= specifies how many users may acquire RT scheduling at the same time for one or multiple of their processes. --processes-per-user-max= specifies how many processes per user may acquire RT scheduling at the same time. --threads-per-user-max= specifies how many threads per user may acquire RT scheduling at the same time. Of course this value should be set higher than --process-per-user-max=. --actions-burst-sec= may be used to influence the rate limiting logic in RealtimeKit. The daemon will only pass realtime scheduling privileges to a maximum number of threads within this timeframe (see below). --actions-per-burst-max= may be used to influence the rate limiting logic in RealtimeKit. The daemon will only pass realtime scheduling privileges to this number of threads within the time frame configured via --actions-burst-sec=. When this limit is reached clients need to wait until that time passes before requesting RT scheduling again. --canary-cheep-msec= may be used to control how often the canary thread shall cheep. --canary-watchdog-msec= may be used to control how quickly the watchdog thread expects to receive a cheep from the canary thread. This value must be chosen larger than --canary-cheep-msec=. If the former is set 10s and the latter to 7s, then the canary thread can trigger and deliver the cheep with a maximum latency of 3s. ACKNOWLEDGMENTS: The canary 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