prog_cgroup_sysctl.rst 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
  1. .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
  2. ===========================
  3. BPF_PROG_TYPE_CGROUP_SYSCTL
  4. ===========================
  5. This document describes ``BPF_PROG_TYPE_CGROUP_SYSCTL`` program type that
  6. provides cgroup-bpf hook for sysctl.
  7. The hook has to be attached to a cgroup and will be called every time a
  8. process inside that cgroup tries to read from or write to sysctl knob in proc.
  9. 1. Attach type
  10. **************
  11. ``BPF_CGROUP_SYSCTL`` attach type has to be used to attach
  12. ``BPF_PROG_TYPE_CGROUP_SYSCTL`` program to a cgroup.
  13. 2. Context
  14. **********
  15. ``BPF_PROG_TYPE_CGROUP_SYSCTL`` provides access to the following context from
  16. BPF program::
  17. struct bpf_sysctl {
  18. __u32 write;
  19. __u32 file_pos;
  20. };
  21. * ``write`` indicates whether sysctl value is being read (``0``) or written
  22. (``1``). This field is read-only.
  23. * ``file_pos`` indicates file position sysctl is being accessed at, read
  24. or written. This field is read-write. Writing to the field sets the starting
  25. position in sysctl proc file ``read(2)`` will be reading from or ``write(2)``
  26. will be writing to. Writing zero to the field can be used e.g. to override
  27. whole sysctl value by ``bpf_sysctl_set_new_value()`` on ``write(2)`` even
  28. when it's called by user space on ``file_pos > 0``. Writing non-zero
  29. value to the field can be used to access part of sysctl value starting from
  30. specified ``file_pos``. Not all sysctl support access with ``file_pos !=
  31. 0``, e.g. writes to numeric sysctl entries must always be at file position
  32. ``0``. See also ``kernel.sysctl_writes_strict`` sysctl.
  33. See `linux/bpf.h`_ for more details on how context field can be accessed.
  34. 3. Return code
  35. **************
  36. ``BPF_PROG_TYPE_CGROUP_SYSCTL`` program must return one of the following
  37. return codes:
  38. * ``0`` means "reject access to sysctl";
  39. * ``1`` means "proceed with access".
  40. If program returns ``0`` user space will get ``-1`` from ``read(2)`` or
  41. ``write(2)`` and ``errno`` will be set to ``EPERM``.
  42. 4. Helpers
  43. **********
  44. Since sysctl knob is represented by a name and a value, sysctl specific BPF
  45. helpers focus on providing access to these properties:
  46. * ``bpf_sysctl_get_name()`` to get sysctl name as it is visible in
  47. ``/proc/sys`` into provided by BPF program buffer;
  48. * ``bpf_sysctl_get_current_value()`` to get string value currently held by
  49. sysctl into provided by BPF program buffer. This helper is available on both
  50. ``read(2)`` from and ``write(2)`` to sysctl;
  51. * ``bpf_sysctl_get_new_value()`` to get new string value currently being
  52. written to sysctl before actual write happens. This helper can be used only
  53. on ``ctx->write == 1``;
  54. * ``bpf_sysctl_set_new_value()`` to override new string value currently being
  55. written to sysctl before actual write happens. Sysctl value will be
  56. overridden starting from the current ``ctx->file_pos``. If the whole value
  57. has to be overridden BPF program can set ``file_pos`` to zero before calling
  58. to the helper. This helper can be used only on ``ctx->write == 1``. New
  59. string value set by the helper is treated and verified by kernel same way as
  60. an equivalent string passed by user space.
  61. BPF program sees sysctl value same way as user space does in proc filesystem,
  62. i.e. as a string. Since many sysctl values represent an integer or a vector
  63. of integers, the following helpers can be used to get numeric value from the
  64. string:
  65. * ``bpf_strtol()`` to convert initial part of the string to long integer
  66. similar to user space `strtol(3)`_;
  67. * ``bpf_strtoul()`` to convert initial part of the string to unsigned long
  68. integer similar to user space `strtoul(3)`_;
  69. See `linux/bpf.h`_ for more details on helpers described here.
  70. 5. Examples
  71. ***********
  72. See `test_sysctl_prog.c`_ for an example of BPF program in C that access
  73. sysctl name and value, parses string value to get vector of integers and uses
  74. the result to make decision whether to allow or deny access to sysctl.
  75. 6. Notes
  76. ********
  77. ``BPF_PROG_TYPE_CGROUP_SYSCTL`` is intended to be used in **trusted** root
  78. environment, for example to monitor sysctl usage or catch unreasonable values
  79. an application, running as root in a separate cgroup, is trying to set.
  80. Since `task_dfl_cgroup(current)` is called at `sys_read` / `sys_write` time it
  81. may return results different from that at `sys_open` time, i.e. process that
  82. opened sysctl file in proc filesystem may differ from process that is trying
  83. to read from / write to it and two such processes may run in different
  84. cgroups, what means ``BPF_PROG_TYPE_CGROUP_SYSCTL`` should not be used as a
  85. security mechanism to limit sysctl usage.
  86. As with any cgroup-bpf program additional care should be taken if an
  87. application running as root in a cgroup should not be allowed to
  88. detach/replace BPF program attached by administrator.
  89. .. Links
  90. .. _linux/bpf.h: ../../include/uapi/linux/bpf.h
  91. .. _strtol(3): http://man7.org/linux/man-pages/man3/strtol.3p.html
  92. .. _strtoul(3): http://man7.org/linux/man-pages/man3/strtoul.3p.html
  93. .. _test_sysctl_prog.c:
  94. ../../tools/testing/selftests/bpf/progs/test_sysctl_prog.c