docs/GROUP_RECORD.md

   1 ---
   2 title: JSON Group Records
   3 category: Users, Groups and Home Directories
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 # JSON Group Records
   9
  10 Long story short: JSON Group Records are to `struct group` what
  11 [JSON User Records](USER_RECORD.md) are to `struct passwd`.
  12
  13 Conceptually, much of what applies to JSON user records also applies to JSON
  14 group records. They also consist of seven sections, with similar properties and
  15 they carry some identical (or at least very similar) fields.
  16
  17 ## Fields in the `regular` section
  18
  19 `groupName` → A string with the UNIX group name. Matches the `gr_name` field of
  20 UNIX/glibc NSS `struct group`, or the shadow structure `struct sgrp`'s
  21 `sg_namp` field.
  22
  23 `realm` → The "realm" the group belongs to, conceptually identical to the same
  24 field of user records. A string in DNS domain name syntax.
  25
  26 `description` → A descriptive string for the group. This is similar to the
  27 `realName` field of user records, and accepts arbitrary strings, as long as
  28 they follow the same GECOS syntax requirements as `realName`.
  29
  30 `disposition` → The disposition of the group, conceptually identical to the
  31 same field of user records. A string.
  32
  33 `service` → A string, an identifier for the service managing this group record
  34 (this field is typically in reverse domain name syntax.)
  35
  36 `lastChangeUSec` → An unsigned 64-bit integer, a timestamp (in µs since the UNIX
  37 epoch 1970) of the last time the group record has been modified. (Covers only
  38 the `regular`, `perMachine` and `privileged` sections).
  39
  40 `gid` → An unsigned integer in the range 0…4294967295: the numeric UNIX group
  41 ID (GID) to use for the group. This corresponds to the `gr_gid` field of
  42 `struct group`.
  43
  44 `members` → An array of strings, listing user names that are members of this
  45 group. Note that JSON user records also contain a `memberOf` field, or in other
  46 words a group membership can either be denoted in the JSON user record or in
  47 the JSON group record, or in both. The list of memberships should be determined
  48 as the combination of both lists (plus optionally others). If a user is listed
  49 as member of a group and doesn't exist it should be ignored. This field
  50 corresponds to the `gr_mem` field of `struct group` and the `sg_mem` field of
  51 `struct sgrp`.
  52
  53 `administrators` → Similarly, an array of strings, listing user names that
  54 shall be considered "administrators" of this group. This field corresponds to
  55 the `sg_adm` field of `struct sgrp`.
  56
  57 `privileged`/`perMachine`/`binding`/`status`/`signature`/`secret` → The
  58 objects/arrays for the other six group record sections. These are organized the
  59 same way as for the JSON user records, and have the same semantics.
  60
  61 ## Fields in the `privileged` section
  62
  63 The following fields are defined:
  64
  65 `hashedPassword` → An array of strings with UNIX hashed passwords; see the
  66 matching field for user records for details. This field corresponds to the
  67 `sg_passwd` field of `struct sgrp` (and `gr_passwd` of `struct group` in a
  68 way).
  69
  70 ## Fields in the `perMachine` section
  71
  72 `matchMachineId`/`matchHostname` → Strings, match expressions similar as for
  73 user records, see the user record documentation for details.
  74
  75 The following fields are defined for the `perMachine` section and are defined
  76 equivalent to the fields of the same name in the `regular` section, and
  77 override those:
  78
  79 `gid`, `members`, `administrators`
  80
  81 ## Fields in the `binding` section
  82
  83 The following fields are defined for the `binding` section, and are equivalent
  84 to the fields of the same name in the `regular` and `perMachine` sections:
  85
  86 `gid`
  87
  88 ## Fields in the `status` section
  89
  90 The following fields are defined in the `status` section, and are mostly
  91 equivalent to the fields of the same name in the `regular` section, though with
  92 slightly different conceptual semantics, see the same fields in the user record
  93 documentation:
  94
  95 `service`
  96
  97 ## Fields in the `signature` section
  98
  99 The fields in this section are defined identically to those in the matching
 100 section in the user record.
 101
 102 ## Fields in the `secret` section
 103
 104 Currently no fields are defined in this section for group records.
 105
 106 ## Mapping to `struct group` and `struct sgrp`
 107
 108 When mapping classic UNIX group records (i.e. `struct group` and `struct sgrp`)
 109 to JSON group records the following mappings should be applied:
 110
 111 | Structure      | Field       | Section      | Field            | Condition                  |
 112 |----------------|-------------|--------------|------------------|----------------------------|
 113 | `struct group` | `gr_name`   | `regular`    | `groupName`      |                            |
 114 | `struct group` | `gr_passwd` | `privileged` | `password`       | (See notes below)          |
 115 | `struct group` | `gr_gid`    | `regular`    | `gid`            |                            |
 116 | `struct group` | `gr_mem`    | `regular`    | `members`        |                            |
 117 | `struct sgrp`  | `sg_namp`   | `regular`    | `groupName`      |                            |
 118 | `struct sgrp`  | `sg_passwd` | `privileged` | `password`       | (See notes below)          |
 119 | `struct sgrp`  | `sg_adm`    | `regular`    | `administrators` |                            |
 120 | `struct sgrp`  | `sg_mem`    | `regular`    | `members`        |                            |
 121
 122 At this time almost all Linux machines employ shadow passwords, thus the
 123 `gr_passwd` field in `struct group` is set to `"x"`, and the actual password
 124 is stored in the shadow entry `struct sgrp`'s field `sg_passwd`.
 125
 126 ## Extending These Records
 127
 128 The same logic and recommendations apply as for JSON user records.
 129
 130 ## Examples
 131
 132 A reasonable group record for a system group might look like this:
 133
 134 ```json
 135 {
 136         "groupName" : "systemd-resolve",
 137         "gid" : 193,
 138         "status" : {
 139                 "6b18704270e94aa896b003b4340978f1" : {
 140                         "service" : "io.systemd.NameServiceSwitch"
 141                 }
 142         }
 143 }
 144 ```
 145
 146 And here's a more complete one for a regular group:
 147
 148 ```json
 149 {
 150         "groupName" : "grobie",
 151         "binding" : {
 152                 "6b18704270e94aa896b003b4340978f1" : {
 153                         "gid" : 60232
 154                 }
 155         },
 156         "disposition" : "regular",
 157         "status" : {
 158                 "6b18704270e94aa896b003b4340978f1" : {
 159                         "service" : "io.systemd.Home"
 160                 }
 161         }
 162 }
 163 ```