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