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