.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "GROUPS.CONF" "5" "2025-01-23" "1.9.3" "ClusterShell User Manual"
.SH NAME
groups.conf \- Configuration file for ClusterShell node groups
.SH DESCRIPTION
.sp
The ClusterShell library obtains its node groups configuration from the
following sources in the following order:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
user configuration file (\fI$XDG_CONFIG_HOME/clustershell/groups.conf\fP)
.IP 2. 3
local pip user installation (\fI$HOME/.local/etc/clustershell/groups.conf\fP)
.IP 3. 3
Global configuration file (\fI$CLUSTERSHELL_CFGDIR/groups.conf\fP, defaults to
\fI/etc/clustershell/groups.conf\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If no \fIgroups.conf\fP is found, group support will be disabled.
.sp
Additional configuration files are also read from the directories set by the
confdir option, if present.  See the \fBconfdir\fP option below for further
details.
.sp
Configuration files have a format in the style of RFC 822 potentially composed
of several sections which may be present in any order. There are two types of
sections: Main and \fIGroup_source\fP:
.INDENT 0.0
.TP
.B Main
Global configuration options. There should be only one Main section.
.TP
.B \fIGroup_source\fP
The \fIGroup_source\fP section(s) define the configuration for each node group
source (or namespace). This configuration consists in external commands
definition (map, all, list and reverse).
.UNINDENT
.sp
Only \fIGroup_source\fP section(s) are allowed in additional configuration files.
.SS [Main] OPTIONS
.sp
Configuration parameters of the \fBMain\fP section are described below.
.INDENT 0.0
.TP
.B default
Specify the default group source (group namespace) used by the NodeSet parser
when the user does not explicitly specify the group source (eg. \(dq@io\(dq).
.TP
.B confdir
Optional list of directories where the ClusterShell library should look for
\fB\&.conf\fP files which define group sources to use. Each file in these
directories with the .conf suffix should contain one or more \fIGroup_source\fP
sections as documented in [\fIGroup_source\fP] options below. These will be merged
with the group sources defined in \fI/etc/clustershell/groups.conf\fP to form the
complete set of group sources that ClusterShell will use. Duplicate
\fIGroup_source\fP sections are not allowed.  Note: .conf files that are not
readable by the current user are ignored (except the one that defines the
default group source). The variable \fI$CFGDIR\fP is replaced by the path of the
highest priority configuration directory found (where groups.conf resides).
The default confdir value enables both system\-wide and any installed user
configuration (thanks to \fI$CFGDIR\fP). Duplicate directory paths are ignored.
.TP
.B autodir
Optional list of directories where the ClusterShell library should look for
\fB\&.yaml\fP files that define in\-file group dictionaries. No need to call
external commands for these files, they are parsed by the ClusterShell library
itself.  Multiple group source definitions in the same file is supported. The
variable \fI$CFGDIR\fP is replaced by the path of the highest priority
configuration directory found (where groups.conf resides). The default
confdir value enables both system\-wide and any installed user configuration
(thanks to \fI$CFGDIR\fP). Duplicate directory paths are ignored.
.UNINDENT
.SS [\fIGroup_source\fP] OPTIONS
.sp
Configuration parameters of each group source section are described below.
.INDENT 0.0
.TP
.B map
Specify the external shell command used to resolve a group name into a
nodeset, list of nodes or list of nodeset (separated by space characters or
by carriage returns). The variable \fI$GROUP\fP is replaced before executing the
command.
.TP
.B all
Optional external shell command that should return a nodeset, list of
nodes or list of nodeset of all nodes for this group source. If not
specified, the library will try to resolve all nodes by using the \fBlist\fP
external command in the same group source followed by \fBmap\fP for each group.
.TP
.B list
Optional external shell command that should return the list of all groups
for this group source (separated by space characters or by carriage
returns).
.TP
.B reverse
Optional external shell command used to find the group(s) of a single
node. The variable $NODE is previously replaced. If this upcall is not
specified, the reverse operation is computed in memory by the library from
the \fIlist\fP and \fImap\fP external calls. Also, if the number of nodes to
reverse is greater than the number of available groups, the \fIreverse\fP
external command is avoided automatically.
.TP
.B cache_time
Number of seconds each upcall result is kept in cache, in memory only.
Default is 3600 seconds. This is useful only for daemons using nodegroups.
.UNINDENT
.sp
When the library executes a group source external shell command, the current
working directory is previously set to the corresponding confdir. This
allows the use of relative paths for third party files in the command.
.sp
In addition to context\-dependent $GROUP and $NODE variables described above, the
two following variables are always available and also replaced before executing
shell commands:
.INDENT 0.0
.IP \(bu 2
\fI$CFGDIR\fP is replaced by groups.conf highest priority base directory path
.IP \(bu 2
\fI$SOURCE\fP is replaced by current source name
.UNINDENT
.sp
Each external command might return a non\-zero return code when the operation
is not doable. But if the call return zero, for instance, for a non\-existing
group, the user will not receive any error when trying to resolve such unknown
group.  The desired behaviour is up to the system administrator.
.SH RESOURCE USAGE
.sp
All external command results are cached in memory to avoid multiple calls. Each
result is kept for a limited amount of time. See cache_time option to tune
this behaviour.
.SH EXAMPLES
.sp
Simple configuration file for local groups and slurm partitions binding.
.SS \fIgroups.conf\fP
.nf
[Main]
default: local
confdir: /etc/clustershell/groups.conf.d $CFGDIR/groups.conf.d
autodir: /etc/clustershell/groups.d $CFGDIR/groups.d

[local]
map: sed \-n \(aqs/^$GROUP:(.*)/1/p\(aq /etc/clustershell/groups
list: sed \-n \(aqs/^\e(\fB[0\-9A\-Za\-z_\-]\fP*\e):.*/\e1/p\(aq /etc/clustershell/groups

[slurm]
map: sinfo \-h \-o \(dq%N\(dq \-p $GROUP
all: sinfo \-h \-o \(dq%N\(dq
list: sinfo \-h \-o \(dq%P\(dq
reverse: sinfo \-h \-N \-o \(dq%P\(dq \-n $NODE
.fi
.sp
.SH FILES
.INDENT 0.0
.TP
.B \fI$CLUSTERSHELL_CFGDIR/groups.conf\fP (defaults to \fI/etc/clustershell/groups.conf\fP)
Global node groups configuration file.
.TP
.B \fI$CLUSTERSHELL_CFGDIR/groups.conf.d/\fP (defaults to
\fI/etc/clustershell/groups.conf.d/\fP)
Recommended directory for additional configuration files.
.TP
.B \fI$CLUSTERSHELL_CFGDIR/groups.d/\fP (defaults to \fI/etc/clustershell/groups.d/\fP)
Recommended directory for \fIautodir\fP, where native group definition files
(.yaml files) are found.
.TP
.B \fI$XDG_CONFIG_HOME/clustershell/groups.conf\fP
Main user groups.conf configuration file. If $XDG_CONFIG_HOME is not defined,
\fI$HOME/.config/clustershell/groups.conf\fP is used instead.
.TP
.B \fI$HOME/.local/etc/clustershell/groups.conf\fP
Local groups.conf user configuration file (default installation for pip \-\-user)
.UNINDENT
.SH SEE ALSO
.sp
\fBclubak\fP(1), \fBcluset\fP(1), \fBclush\fP(1), \fBnodeset\fP(1)
.sp
 <http://clustershell.readthedocs.org/> 
.SH AUTHOR
Stephane Thiell, <sthiell@stanford.edu>
.SH COPYRIGHT
GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
.\" Generated by docutils manpage writer.
.