From 07ea7da211bf7f6ca6ee938c53714d20ec12e476 Mon Sep 17 00:00:00 2001 From: Moe Jette <jette1@llnl.gov> Date: Wed, 24 Feb 2010 23:31:04 +0000 Subject: [PATCH] add procgrack/cgroup documentation --- doc/html/configurator.html.in | 3 + doc/man/Makefile.am | 1 + doc/man/Makefile.in | 1 + doc/man/man5/cgroup.conf.5 | 161 ++++++++++++++++++++++++++++++++++ doc/man/man5/slurm.conf.5 | 28 +++--- etc/cgroup.conf.example | 2 +- 6 files changed, 183 insertions(+), 13 deletions(-) create mode 100644 doc/man/man5/cgroup.conf.5 diff --git a/doc/html/configurator.html.in b/doc/html/configurator.html.in index 77e5b41a85e..860902a50e3 100644 --- a/doc/html/configurator.html.in +++ b/doc/html/configurator.html.in @@ -580,6 +580,9 @@ with a job step.<BR> Select one value for <B>ProctrackType</B>:<BR> <input type="radio" name="proctrack_type" value="aix"> <B>AIX</B>: Use AIX kernel extension, recommended for AIX systems<BR> +<input type="radio" name="proctrack_type" value="cgroup"> <B>Cgroup</B>: Use +Linux <i>cgroups</i> to create a job container and track processes. +Build a <i>cgroup.conf</i> file as well<BR> <input type="radio" name="proctrack_type" value="pgid" checked> <B>Pgid</B>: Use Unix Process Group ID, processes changing their process group ID can escape from SLURM control<BR> diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 6dc61e4d584..3b9e83b49ab 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -147,6 +147,7 @@ man3_MANS = man3/slurm_hostlist_create.3 \ man3/slurm_update_step.3 man5_MANS = man5/bluegene.conf.5 \ + man5/cgroup.conf.5 \ man5/slurm.conf.5 \ man5/slurmdbd.conf.5 \ man5/topology.conf.5 \ diff --git a/doc/man/Makefile.in b/doc/man/Makefile.in index 3f97a917b23..a24024c2369 100644 --- a/doc/man/Makefile.in +++ b/doc/man/Makefile.in @@ -440,6 +440,7 @@ man3_MANS = man3/slurm_hostlist_create.3 \ man3/slurm_update_step.3 man5_MANS = man5/bluegene.conf.5 \ + man5/cgroup.conf.5 \ man5/slurm.conf.5 \ man5/slurmdbd.conf.5 \ man5/topology.conf.5 \ diff --git a/doc/man/man5/cgroup.conf.5 b/doc/man/man5/cgroup.conf.5 new file mode 100644 index 00000000000..166c42a982f --- /dev/null +++ b/doc/man/man5/cgroup.conf.5 @@ -0,0 +1,161 @@ +.TH "cgroup.conf" "5" "February 2010" "cgroup.conf 2.2" "Slurm configuration file" + +.SH "NAME" +cgroup.conf \- Slurm configuration file for the cgroup support + +.SH "DESCRIPTION" +\fB/etc/cgroup.conf\fP is an ASCII file which defines parameters used by +Slurm's proctrack/cgroup plugin in support of Linux cgroups being used as a +job container. The file will always be located in the same directory as the +\fBslurm.conf\fP file. +.LP +Parameter names are case insensitive. +Any text following a "#" in the configuration file is treated +as a comment through the end of that line. +The size of each line in the file is limited to 1024 characters. +Changes to the configuration file take effect upon restart of +SLURM daemons, daemon receipt of the SIGHUP signal, or execution +of the command "scontrol reconfigure" unless otherwise noted. +.LP +Slurm cgroup proctrack plugin creates a hierarchical set of +directories for each step, putting the step tasks into the leaf. +This directory structure is like the following: +.br +/dev/cgroup/slurm/uid_%uid/job_%jobid/step_%stepid +.LP +Slurm cgroup proctrack plugin can constrain cores, RAM and swap space for +jobs and set a variety of default job and job step parameters for cgroups. +.LP +The configuration parameters available include: + + +.TP +\fBAllowedRAMSpace\fR=<number> +Constrain the job cgroup RAM to this percentage of the allocated memory. +The default value is 100. +If the limit is exceeded, the job steps will be killed and a warning message +will be written to standard error. +Also see \fBConstrainRAMSpace\fR. + +.TP +\fBAllowedSwapSpace\fR=<number> +Constrain the job cgroup swap space to this percentage of the allocated memory. +The default value is 0. +If the limit is exceeded, the job steps will be killed and a warning message +will be written to standard error. +Also see \fBConstrainSwapSpace\fR. + +.TP +\fBCgroupAutomount\fR=<yes|no> +Slurm cgroup plugins require a valid and functional cgroup system mounted on +/dev/cgroup. When launched, plugins check cgroup availability. If cgroup is +not available, the plugin launch fails unless CgroupAutomount is set to yes. +In that case, the plugin will first try to mount the cgroup system. + +.TP +\fBCgroupMountOptions\fR=<options> +Used to tune the cgroup system behavior. + +.TP +\fBCgroupReleaseAgent\fR=<path_to_program> +Used to tune the cgroup system behavior. + +.TP +\fBConstrainCores\fR=<yes|no> +If configured to "yes" then constrain allowed cores to the subset of +allocated resources. +The default value is "no". + +.TP +\fBConstrainRAMSpace\fR=<yes|no> +If configured to "yes" then constraing the job's RAM usage. +The default value is "no". +Also see \fBAllowedRAMSpace\fR. + +.TP +\fBConstrainSwapSpace\fR=<yes|no> +If configured to "yes" then constraing the job's swap space usage. +The default value is "no". +Also see \fBAllowedSwapSpace\fR. + +.TP +\fBJobCgroupParams\fR=<options> +Used to tune job cgroup. The format of the parameter is the following: +"a=b c=d e=f" where a,c,d corresponds to files under the cgroup +directory and b,d,f the values to write in these files. + +.TP +\fBJobStepCgroupParams\fR=<options> +Used to tune job step cgroup. The format of the parameter is the following: +"a=b c=d e=f" where a,c,d corresponds to files under the cgroup +directory and b,d,f the values to write in these files. + + +.SH "EXAMPLE" +.LP +.br +### +.br +# Slurm cgroup support configuration file +.br +### +.br +CgroupAutomount=yes +.br +CgroupMountOptions="memory,cpuset" +.br +CgroupReleaseAgent="/etc/slurm/cgroup.release_agent" +.br +JobCgroupParams="memory.swappiness=30" +.br +JobStepCgroupParams="" +.br +# +.br +# Constrain RAM at 100% of allocation and +.br +# Total space (RAM + swap) at 110% of allocation +.br +# +.br +ConstrainRAMSpace=yes +.br +AllowedRAMSpace=100 +.br +ConstrainSwapSpace=yes +.br +AllowedSwapSpace=10 +.br +ConstrainCores=yes + +.SH "NOTES" +Proctrack/cgroup is not compatable with the task/affinity plugin configured +to use cpusets, although this may be addressed in the future. +.LP +Only one instance of a cgroup subsystem is valid at a time in the kernel. +If you try to mount another cgroup hierarchy that uses the same cpuset +subsystem it will fail. +However you can mount another cgroup hierarchy for a different cpuset +subsystem. + +.SH "COPYING" +Copyright (C) 2010 Lawrence Livermore National Security. +Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). +CODE\-OCEC\-09\-009. All rights reserved. +.LP +This file is part of SLURM, a resource management program. +For details, see <https://computing.llnl.gov/linux/slurm/>. +.LP +SLURM is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free +Software Foundation; either version 2 of the License, or (at your option) +any later version. +.LP +SLURM is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +details. + +.SH "SEE ALSO" +.LP +\fBslurm.conf\fR(5) diff --git a/doc/man/man5/slurm.conf.5 b/doc/man/man5/slurm.conf.5 index 96c7b947b9b..c882bf4c0fe 100644 --- a/doc/man/man5/slurm.conf.5 +++ b/doc/man/man5/slurm.conf.5 @@ -983,22 +983,26 @@ utilizing kernel modifications is preferable. NOTE: "proctrack/linuxproc" is not compatible with "switch/elan." Acceptable values at present include: .RS +.TP 20 +\fBproctrack/aix\fR +which uses an AIX kernel extension and is the default for AIX systems .TP -\fBproctrack/aix\fR which uses an AIX kernel extension and is -the default for AIX systems +\fBproctrack/cgroup\fR +which uses linux cgroups to constrain and track processes. +NOTE: see "man cgroup.conf" for configuration details .TP -\fBproctrack/linuxproc\fR which uses linux process tree using -parent process IDs +\fBproctrack/linuxproc\fR +which uses linux process tree using parent process IDs .TP -\fBproctrack/rms\fR which uses Quadrics kernel patch and is the -default if "SwitchType=switch/elan" +\fBproctrack/rms\fR +which uses Quadrics kernel patch and is the default if "SwitchType=switch/elan" .TP -\fBproctrack/sgi_job\fR which uses SGI's Process Aggregates (PAGG) -kernel module, see \fIhttp://oss.sgi.com/projects/pagg/\fR -for more information +\fBproctrack/sgi_job\fR +which uses SGI's Process Aggregates (PAGG) kernel module, +see \fIhttp://oss.sgi.com/projects/pagg/\fR for more information .TP -\fBproctrack/pgid\fR which uses process group IDs and is the -default for all other systems +\fBproctrack/pgid\fR +which uses process group IDs and is the default for all other systems .RE .TP @@ -2702,7 +2706,7 @@ details. .SH "SEE ALSO" .LP -\fBbluegene.conf\fR(5), \fBgethostbyname\fR(3), +\fBbluegene.conf\fR(5), \fBcgroup.conf\fR(5), \fBgethostbyname\fR(3), \fBgetrlimit\fR(2), \fBgroup\fR(5), \fBhostname\fR(1), \fBscontrol\fR(1), \fBslurmctld\fR(8), \fBslurmd\fR(8), \fBslurmdbd\fR(8), \fBslurmdbd.conf\fR(5), \fBsrun(1)\fR, diff --git a/etc/cgroup.conf.example b/etc/cgroup.conf.example index ba3f1fa0427..615faa6c98c 100644 --- a/etc/cgroup.conf.example +++ b/etc/cgroup.conf.example @@ -37,7 +37,7 @@ JobStepCgroupParams="" #-- # Slurm cgroup proctrack plugin can constrain memory usage at the job # level. The constraints correspond to the amount of RAM space allowed -# to the whole job as well as the amount of additionnal swap space. +# to the whole job as well as the amount of additional swap space. # # The amount of space of these two notions are expressed in percent of # the memory limit set to the job on the execution node. -- GitLab