PAM limits

docs/.vuepress/config.js

@@ -242,6 +242,7 @@ module.exports = {
 			},
 			"admin/FTP",
 			"admin/Monitoring",
+			"admin/Limits",
 			"admin/Resource enforcement",
 			"admin/Metrics",
 			"admin/Kernel",

docs/admin/Limits.md

@@ -0,0 +1,86 @@
+## Process limits
+
+Limits are a per-process resource enforcement mechanism. This system provides a rudimentary backstop against runaway processes. [cgroup](Resource%20enforcement.md) is intended for account-wide resource limits.
+
+Process limits are applied using a PAM wrapper on PAM-aware applications, which include any login service (FTP, mail, SSH, crond).
+
+## Format
+
+Limits may be overridden in Bootstrapper or by including a lexicographically higher file than [`10-apnscp-system.conf`](https://gitlab.com/apisnetworks/apnscp/-/blob/master/resources/playbooks/roles/system/limits/templates/apnscp.conf.j2) in `FST/siteinfo/etc/security/limits.d` (see [Filesystem.md](Filesystem.md#filesystem-template). Files published within this location are inherited by all sites.
+
+Settings take the following form:
+
+```
+#DOMAIN   TYPE RESOURCE VALUE
+# Disable coredumps for everyone
+*         -    core     0
+# Enable coredumps for users under "site12"
+@foobar  soft core     unlimited
+# Restrict number of files opened by PHP-FPM
+nobody    soft nfiles   2048
+# Limit any account with a user "phil" from running more than 25 processes
+phil      hard nproc    25
+```
+
+::: tip Domain resolution
+User resolution is completed inside the virtual environment. In the above example "phil" applies to *any account* with a user named "phil". Often it is inappropriate to publish limits within the FST except as stopgap limits for runaway resource consumption for all users (`*`) or the unprivileged [PHP-FPM](./PHP-FPM.md) user, `apache`.
+:::
+
+A **domain** may be of the form:
+
+- username, resolved within the [vfs](Filesystem.md).
+- group name using `@group` syntax
+- wildcard `*` for default entry
+- wildcard `%`, can be also used with `%group` syntax, for `maxlogin` limit
+
+## Resources
+
+The following table summarizes available resource limits.
+
+| Value        | Units     | Remarks                                         |
+| ------------ | --------- | ----------------------------------------------- |
+| core         | KB†       | Limits core file size. `0` disables core files. |
+| data         | KB†       | Maximum data segment size.                      |
+| fsize        | KB†       | Maximum filesize.                               |
+| memlock      | KB        | Maximum locked-in-memory address space.         |
+| nofile       | [0,2^20]† | Maximum number of open file descriptors.        |
+| rss          | KB†       | Ignored.                                        |
+| stack        | KB        | Maximum stack size.                             |
+| cpu          | minutes   | Maximum CPU time.                               |
+| nproc        | [0,2^63)  | Max number of processes.                        |
+| as           | KB†       | Address space limit (vmem).                     |
+| maxlogins    | —         | Max number of logins for this user.             |
+| maxsyslogins | —         | Max number of global logins for system.         |
+| priority     | [0,2^63)  | Real-time process priority.                     |
+| locks        | [0,2^63)† | Max number of locks.                            |
+| sigpending   | [0,2^63)  | Max number of pending signals.                  |
+| msgqueue     | B         | Max memory used by POSIX message queues.        |
+| nice         | [-20, 19] | Max nice priority allowed to raise.             |
+| rtprio       | [0,2^63)  | Max real-time priority.                         |
+
+***†** values specified accept `unlimited` as a value.*
+
+## Hard and soft
+
+Type may either be "hard" or "soft". A hard limit is the maximal value allowed for a resource. Only root may change this. Soft values may be changed by a user up to the hard limit. 
+
+Consider the following in `site1/fst/etc/security/limits.d/nice-limit.conf`:
+
+```
+* soft nice 0
+* hard nice -5
+```
+
+```bash
+su site1
+whoami
+# Reports admin
+renice 0 $$
+# 30307 (process ID) old priority 19, new priority 0
+renice -1 $$
+# renice: failed to set priority for 30307 (process ID): permission denied
+```
+
+::: tip Explanation
+A user is able to increase process priority from 19 down to 0 but may not specify a negative process priority, which preempts other processes on the system. A priority of 0 gives equal weighting to all system processes while a value greater than 0 would deprioritize.
+:::

docs/admin/Resource enforcement.md

@@ -395,7 +395,7 @@ cat /sys/fs/cgroup/memory/site1/memory.usage_in_bytes
 
 This can be confirmed by examining `memory.stat` in the cgroup home. Likewise memory reported by a process may be higher than memory reported by cgroup, this is because cgroup only accounts for memory uniquely reserved by the application. A fork shares its parent's memory pages and copies-on-write at which point the newly claimed memory is charged to the cgroup.
 
-## CloudLinux terminology
+## CloudLinux equivalences
 
 Both ApisCP and CloudLinux utilize cgroups for resource enforcement. The table below summarizes the relationships between CloudLinux limit variables and ApisCP's equivalent settings.