README

REALTIMEKIT Realtime Policy and Watchdog Daemon

GIT:
        https://github.com/heftig/rtkit

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 there 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!  (Please
        note that gettid() is not available in glibc, you need to
        implement that manually using syscall(). Consult the reference
        client implementation for details.)
        
        It is possible to promote thread in process to realtime/high
        priority from another process, that will make the DBUS call,
        using:
        
                void MakeThreadRealtimeWithPID(u64 process, u64 thread_id, u32 priority);

                void MakeThreadHighPriorityWithPID(u64 process, u64 thread_id, s32 priority);

        where process is the PID of the process that has thread thread_id.
        
        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 minimum 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:

        https://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

OPTIONAL DEPENDENCIES:
        libsystemd - to let rtkit talk to systemd using the sd-daemon API