]>
Commit | Line | Data |
---|---|---|
b27cb676 | 1 | --- |
cafed7b3 | 2 | title: User/Group Name Syntax |
5fe63895 | 3 | category: Users, Groups and Home Directories |
cafed7b3 | 4 | layout: default |
0aff7b75 | 5 | SPDX-License-Identifier: LGPL-2.1-or-later |
cafed7b3 LP |
6 | --- |
7 | ||
8 | # User/Group Name Syntax | |
9 | ||
07cf50ec | 10 | The precise set of allowed user and group names on Linux systems is weakly defined. |
11 | Depending on the distribution a different set of requirements and | |
cafed7b3 | 12 | restrictions on the syntax of user/group names are enforced — on some |
07cf50ec | 13 | distributions the accepted syntax is even configurable by the administrator. |
14 | In the interest of interoperability systemd enforces different rules when | |
cafed7b3 | 15 | processing users/group defined by other subsystems and when defining users/groups |
07cf50ec | 16 | itself, following the principle of "Be conservative in what you send, be liberal in what you accept". |
17 | Also in the interest of interoperability systemd will enforce the same rules everywhere and not make them configurable or distribution dependent. | |
18 | The precise rules are described below. | |
cafed7b3 LP |
19 | |
20 | Generally, the same rules apply for user as for group names. | |
21 | ||
22 | ## Other Systems | |
23 | ||
07cf50ec | 24 | * On POSIX the set of |
25 | [valid user names](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_437) | |
26 | is defined as | |
27 | [lower and upper case ASCII letters, digits, period, underscore, and hyphen](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282), | |
28 | with the restriction that hyphen is not allowed as first character of the user name. | |
29 | Interestingly no size limit is declared, i.e. in neither | |
e347d53a | 30 | direction, meaning that strictly speaking, according to POSIX, both the empty |
cafed7b3 LP |
31 | string is a valid user name as well as a string of gigabytes in length. |
32 | ||
07cf50ec | 33 | * Debian/Ubuntu based systems enforce the regular expression `^[a-z][-a-z0-9]*$`, i.e. |
34 | only lower case ASCII letters, digits and hyphens. | |
35 | As first character only lowercase ASCII letters are allowed. | |
36 | This regular expression is configurable by the administrator at runtime though. | |
37 | This rule enforces a minimum length of one character but no maximum length. | |
cafed7b3 LP |
38 | |
39 | * Upstream shadow-utils enforces the regular expression | |
07cf50ec | 40 | `^[a-z_][a-z0-9_-]*[$]$`, i.e.is similar to the Debian/Ubuntu rule, |
41 | but allows underscores and hyphens, but the latter not as first character. | |
42 | Also, an optional trailing dollar character is permitted. | |
cafed7b3 LP |
43 | |
44 | * Fedora/Red Hat based systems enforce the regular expression of | |
45 | `^[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,30}[a-zA-Z0-9_.$-]?$`, i.e. a size limit of | |
07cf50ec | 46 | 32 characters, with upper and lower case letters, digits, underscores, hyphens and periods. |
47 | No hyphen as first character though, and the last character may be a dollar character. | |
48 | On top of that, `.` and `..` are not allowed as user/group names. | |
cafed7b3 LP |
49 | |
50 | * sssd is known to generate user names with embedded `@` and white-space | |
51 | characters, as well as non-ASCII (i.e. UTF-8) user/group names. | |
52 | ||
53 | * winbindd is known to generate user/group names with embedded `\` and | |
54 | white-space characters, as well as non-ASCII (i.e. UTF-8) user/group names. | |
55 | ||
56 | Other operating systems enforce different rules; in this documentation we'll | |
07cf50ec | 57 | focus on Linux systems only however, hence those are out of scope. |
58 | That said, software like Samba is frequently deployed on Linux for providing compatibility | |
cafed7b3 LP |
59 | with Windows systems; on such systems it might be wise to stick to user/group |
60 | names also valid according to Windows rules. | |
61 | ||
62 | ## Rules systemd enforces | |
63 | ||
07cf50ec | 64 | Distilled from the above, below are the rules systemd enforces on user/group names. |
65 | An additional, common rule between both modes listed below is that empty strings are not valid user/group names. | |
cafed7b3 | 66 | |
6b000af4 LP |
67 | Philosophically, the strict mode described below enforces an allow list of |
68 | what's allowed and prohibits everything else, while the relaxed mode described | |
69 | below implements a deny list of what's not allowed and permits everything else. | |
cafed7b3 LP |
70 | |
71 | ### Strict mode | |
72 | ||
73 | Strict user/group name syntax is enforced whenever a systemd component is used | |
74 | to register a user or group in the system, for example a system user/group | |
75 | using | |
76 | [`systemd-sysusers.service`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.html) | |
77 | or a regular user with | |
78 | [`systemd-homed.service`](https://www.freedesktop.org/software/systemd/man/systemd-homed.html). | |
79 | ||
80 | In strict mode, only uppercase and lowercase characters are allowed, as well as | |
07cf50ec | 81 | digits, underscores and hyphens. |
82 | The first character may not be a digit or hyphen. A size limit is enforced: the minimum of `sysconf(_SC_LOGIN_NAME_MAX)` | |
cafed7b3 LP |
83 | (typically 256 on Linux; rationale: this is how POSIX suggests to detect the |
84 | limit), `UT_NAMESIZE-1` (typically 31 on Linux; rationale: names longer than | |
85 | this cannot correctly appear in `utmp`/`wtmp` and create ambiguity with login | |
932401fd | 86 | accounting) and `NAME_MAX` (255 on Linux; rationale: user names typically |
07cf50ec | 87 | appear in directory names, i.e. the home directory), thus MIN(256, 31, 255) = 31. |
cafed7b3 LP |
88 | |
89 | Note that these rules are both more strict and more relaxed than all of the | |
07cf50ec | 90 | rules enforced by other systems listed above. |
91 | A user/group name conforming to systemd's strict rules will not necessarily pass a test by the rules enforced | |
cafed7b3 LP |
92 | by these other subsystems. |
93 | ||
94 | Written as regular expression the above is: `^[a-zA-Z_][a-zA-Z0-9_-]{0,30}$` | |
95 | ||
96 | ### Relaxed mode | |
97 | ||
98 | Relaxed user/group name syntax is enforced whenever a systemd component accepts | |
99 | and makes use of user/group names registered by other (non-systemd) | |
100 | components of the system, for example in | |
101 | [`systemd-logind.service`](https://www.freedesktop.org/software/systemd/man/systemd-logind.html). | |
102 | ||
103 | Relaxed syntax is also enforced by the `User=` setting in service unit files, | |
07cf50ec | 104 | i.e. for system services used for running services. |
105 | Since these users may be registered by a variety of tools relaxed mode is used, but since the primary | |
cafed7b3 LP |
106 | purpose of these users is to run a system service and thus a job for systemd a |
107 | warning is shown if the specified user name does not qualify by the strict | |
108 | rules above. | |
109 | ||
110 | * No embedded NUL bytes (rationale: handling in C must be possible and | |
4bb37359 | 111 | straightforward) |
cafed7b3 LP |
112 | |
113 | * No names consisting fully of digits (rationale: avoid confusion with numeric | |
114 | UID/GID specifications) | |
115 | ||
116 | * Similar, no names consisting of an initial hyphen and otherwise entirely made | |
117 | up of digits (rationale: avoid confusion with negative, numeric UID/GID | |
118 | specifications, e.g. `-1`) | |
119 | ||
120 | * No strings that do not qualify as valid UTF-8 (rationale: we want to be able | |
121 | to embed these strings in JSON, with permits only valid UTF-8 in its strings; | |
122 | user names using other character sets, such as JIS/Shift-JIS will cause | |
123 | validation errors) | |
124 | ||
125 | * No control characters (i.e. characters in ASCII range 1…31; rationale: they | |
126 | tend to have special meaning when output on a terminal in other contexts, | |
127 | moreover the newline character — as a specific control character — is used as | |
128 | record separator in `/etc/passwd`, and hence it's crucial to avoid | |
129 | ambiguities here) | |
130 | ||
131 | * No colon characters (rationale: it is used as field separator in `/etc/passwd`) | |
132 | ||
133 | * The two strings `.` and `..` are not permitted, as these have special meaning | |
134 | in file system paths, and user names are frequently included in file system | |
135 | paths, in particular for the purpose of home directories. | |
136 | ||
137 | * Similar, no slashes, as these have special meaning in file system paths | |
138 | ||
139 | * No leading or trailing white-space is permitted; and hence no user/group names | |
140 | consisting of white-space only either (rationale: this typically indicates | |
141 | parsing errors, and creates confusion since not visible on screen) | |
142 | ||
143 | Note that these relaxed rules are implied by the strict rules above, i.e. all | |
144 | user/group names accepted by the strict rules are also accepted by the relaxed | |
145 | rules, but not vice versa. | |
146 | ||
07cf50ec | 147 | Note that this relaxed mode does not refuse a couple of very questionable syntaxes. |
148 | For example, it permits a leading or embedded period. | |
149 | A leading period is problematic because the matching home directory would typically be hidden | |
150 | from the user's/administrator's view. | |
151 | An embedded period is problematic since it creates ambiguity in traditional `chown` syntax (which is still accepted | |
cafed7b3 LP |
152 | today) that uses it to separate user and group names in the command's |
153 | parameter: without consulting the user/group databases it is not possible to | |
07cf50ec | 154 | determine if a `chown` invocation would change just the owning user or both the owning user and group. |
155 | It also allows embedding `@` (which is confusing to MTAs). | |
cafed7b3 LP |
156 | |
157 | ## Common Core | |
158 | ||
159 | Combining all rules listed above, user/group names that shall be considered | |
160 | valid in all systemd contexts and on all Linux systems should match the | |
161 | following regular expression (at least according to our understanding): | |
162 | ||
163 | `^[a-z][a-z0-9-]{0,30}$` |