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