This adds documentation on how to operate, and develop against the Checmate LSM and Cgroup controller. Signed-off-by: Sargun Dhillon <sargun@xxxxxxxxx> --- Documentation/security/Checmate.txt | 54 +++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 Documentation/security/Checmate.txt diff --git a/Documentation/security/Checmate.txt b/Documentation/security/Checmate.txt new file mode 100644 index 0000000..d409785 --- /dev/null +++ b/Documentation/security/Checmate.txt @@ -0,0 +1,54 @@ +--- What is Checmate? --- + +Checmate is a flexible programmable, extensible minor LSM that's coupled with +cgroups and BPF. It is designed to enforce container-specific policies. By +default, it does not enforce any policies. It is selectable at build time +with CONFIG_SECURITY_CHECMATE, and it is controlled through the unified cgroups +controller hierarchy. + +# How to use Checmate +In order to use Checmate, you have to enable the controller on the cgroup2 +hierarchy. In order to prevent a centralized configuration daemon from mounting +Checmate on the V1 hierarchy you may want to add 'cgroup_no_v1=checmate' to your +boot command line. + +Enabling the controller: + mount -t cgroup2 none $MOUNT_POINT + cd $MOUNT_POINT + echo +checmate > cgroup.subtree_control + +Once you do this, immediate children of this node on the hierarchy will have a +number of control files that begin with 'checmate.'. Each of these is mapped +to an LSM hook by the same name. If you read the file, it will return the +number of filters attached to that given hook. Details of the hooks can be +found in lsm_hooks.h. + +All tasks which are members of a cgroup will have no only the checmate filters +at that level enforced, but all levels above as well. If there is a need +to exempt a specific sub-cgroup, a program can use current_task_under_cgroup +along with a bpf map. + +## Adding filters: +If you would like to add a filter, you must compile a BPF_PROG_TYPE_CHECMATE BPF +program. You can then write the '%d\n' formatted version of the BPF program +file descriptor to the relevant control file. + +## Removing filters: +If you would like to remove a specific filter, you can write the negative file +descriptor of the BPF program to the control file (a la '-%d\n'). If you would +like to do this, then it is recommended that you pin your programs. + +If you would like to remove all filters from a specific hook, simply write '0' +to the control file. During normal operation, you shouldn't have the bpf syscall +return '0' for a given program, please take proper precautions to work around +this. + +# Caveats +## Hook Limit: +Each hook is limited to having MAX_CHECMATE_INSTANCES (32) hooks per level +in the hierarchy. The write call will return ENOSPC if you hit this condition. + +## CGroup v2 interaction with CGroup v1: +Because the cgroups subsystem is in transition, using the net_prio or the +net_classid v1 cgroups will render Checmate inoperable on all network +hooks that inspect sockets. \ No newline at end of file -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe cgroups" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
