mirror of
https://github.com/systemd/systemd.git
synced 2024-10-30 06:25:37 +03:00
5c90c67a34
Allows for links to work both on systemd.io (or forks) and when viewed on https://github.com/systemd/systemd/tree/main/docs Note that the markdown links are converted by jekyll-relative-links[1] to html. This plugin is enabled by default on github pages[2][3]. Due to a bug in jekyll-relative-links – see https://github.com/benbalter/jekyll-relative-links/issues/61 – we need to avoid line-wrapped links when using relative markdown links. [1] https://github.com/benbalter/jekyll-relative-links [2] https://github.blog/2016-12-05-relative-links-for-github-pages/ [3] https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#plugins
164 lines
6.0 KiB
Markdown
164 lines
6.0 KiB
Markdown
---
|
|
title: JSON Group Records
|
|
category: Users, Groups and Home Directories
|
|
layout: default
|
|
SPDX-License-Identifier: LGPL-2.1-or-later
|
|
---
|
|
|
|
# JSON Group Records
|
|
|
|
Long story short: JSON Group Records are to `struct group` what
|
|
[JSON User Records](USER_RECORD.md) are to `struct passwd`.
|
|
|
|
Conceptually, much of what applies to JSON user records also applies to JSON
|
|
group records. They also consist of seven sections, with similar properties and
|
|
they carry some identical (or at least very similar) fields.
|
|
|
|
## Fields in the `regular` section
|
|
|
|
`groupName` → A string with the UNIX group name. Matches the `gr_name` field of
|
|
UNIX/glibc NSS `struct group`, or the shadow structure `struct sgrp`'s
|
|
`sg_namp` field.
|
|
|
|
`realm` → The "realm" the group belongs to, conceptually identical to the same
|
|
field of user records. A string in DNS domain name syntax.
|
|
|
|
`description` → A descriptive string for the group. This is similar to the
|
|
`realName` field of user records, and accepts arbitrary strings, as long as
|
|
they follow the same GECOS syntax requirements as `realName`.
|
|
|
|
`disposition` → The disposition of the group, conceptually identical to the
|
|
same field of user records. A string.
|
|
|
|
`service` → A string, an identifier for the service managing this group record
|
|
(this field is typically in reverse domain name syntax.)
|
|
|
|
`lastChangeUSec` → An unsigned 64bit integer, a timestamp (in µs since the UNIX
|
|
epoch 1970) of the last time the group record has been modified. (Covers only
|
|
the `regular`, `perMachine` and `privileged` sections).
|
|
|
|
`gid` → An unsigned integer in the range 0…4294967295: the numeric UNIX group
|
|
ID (GID) to use for the group. This corresponds to the `gr_gid` field of
|
|
`struct group`.
|
|
|
|
`members` → An array of strings, listing user names that are members of this
|
|
group. Note that JSON user records also contain a `memberOf` field, or in other
|
|
words a group membership can either be denoted in the JSON user record or in
|
|
the JSON group record, or in both. The list of memberships should be determined
|
|
as the combination of both lists (plus optionally others). If a user is listed
|
|
as member of a group and doesn't exist it should be ignored. This field
|
|
corresponds to the `gr_mem` field of `struct group` and the `sg_mem` field of
|
|
`struct sgrp`.
|
|
|
|
`administrators` → Similarly, an array of strings, listing user names that
|
|
shall be considered "administrators" of this group. This field corresponds to
|
|
the `sg_adm` field of `struct sgrp`.
|
|
|
|
`privileged`/`perMachine`/`binding`/`status`/`signature`/`secret` → The
|
|
objects/arrays for the other six group record sections. These are organized the
|
|
same way as for the JSON user records, and have the same semantics.
|
|
|
|
## Fields in the `privileged` section
|
|
|
|
The following fields are defined:
|
|
|
|
`hashedPassword` → An array of strings with UNIX hashed passwords; see the
|
|
matching field for user records for details. This field corresponds to the
|
|
`sg_passwd` field of `struct sgrp` (and `gr_passwd` of `struct group` in a
|
|
way).
|
|
|
|
## Fields in the `perMachine` section
|
|
|
|
`matchMachineId`/`matchHostname` → Strings, match expressions similar as for
|
|
user records, see the user record documentation for details.
|
|
|
|
The following fields are defined for the `perMachine` section and are defined
|
|
equivalent to the fields of the same name in the `regular` section, and
|
|
override those:
|
|
|
|
`gid`, `members`, `administrators`
|
|
|
|
## Fields in the `binding` section
|
|
|
|
The following fields are defined for the `binding` section, and are equivalent
|
|
to the fields of the same name in the `regular` and `perMachine` sections:
|
|
|
|
`gid`
|
|
|
|
## Fields in the `status` section
|
|
|
|
The following fields are defined in the `status` section, and are mostly
|
|
equivalent to the fields of the same name in the `regular` section, though with
|
|
slightly different conceptual semantics, see the same fields in the user record
|
|
documentation:
|
|
|
|
`service`
|
|
|
|
## Fields in the `signature` section
|
|
|
|
The fields in this section are defined identically to those in the matching
|
|
section in the user record.
|
|
|
|
## Fields in the `secret` section
|
|
|
|
Currently no fields are defined in this section for group records.
|
|
|
|
## Mapping to `struct group` and `struct sgrp`
|
|
|
|
When mapping classic UNIX group records (i.e. `struct group` and `struct sgrp`)
|
|
to JSON group records the following mappings should be applied:
|
|
|
|
| Structure | Field | Section | Field | Condition |
|
|
|----------------|-------------|--------------|------------------|----------------------------|
|
|
| `struct group` | `gr_name` | `regular` | `groupName` | |
|
|
| `struct group` | `gr_passwd` | `privileged` | `password` | (See notes below) |
|
|
| `struct group` | `gr_gid` | `regular` | `gid` | |
|
|
| `struct group` | `gr_mem` | `regular` | `members` | |
|
|
| `struct sgrp` | `sg_namp` | `regular` | `groupName` | |
|
|
| `struct sgrp` | `sg_passwd` | `privileged` | `password` | (See notes below) |
|
|
| `struct sgrp` | `sg_adm` | `regular` | `administrators` | |
|
|
| `struct sgrp` | `sg_mem` | `regular` | `members` | |
|
|
|
|
At this time almost all Linux machines employ shadow passwords, thus the
|
|
`gr_passwd` field in `struct group` is set to `"x"`, and the actual password
|
|
is stored in the shadow entry `struct sgrp`'s field `sg_passwd`.
|
|
|
|
## Extending These Records
|
|
|
|
The same logic and recommendations apply as for JSON user records.
|
|
|
|
## Examples
|
|
|
|
A reasonable group record for a system group might look like this:
|
|
|
|
```json
|
|
{
|
|
"groupName" : "systemd-resolve",
|
|
"gid" : 193,
|
|
"status" : {
|
|
"6b18704270e94aa896b003b4340978f1" : {
|
|
"service" : "io.systemd.NameServiceSwitch"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
And here's a more complete one for a regular group:
|
|
|
|
```json
|
|
{
|
|
"groupName" : "grobie",
|
|
"binding" : {
|
|
"6b18704270e94aa896b003b4340978f1" : {
|
|
"gid" : 60232
|
|
}
|
|
},
|
|
"disposition" : "regular",
|
|
"status" : {
|
|
"6b18704270e94aa896b003b4340978f1" : {
|
|
"service" : "io.systemd.Home"
|
|
}
|
|
}
|
|
}
|
|
```
|