1REALM(8)                         User Commands                        REALM(8)
2
3
4

NAME

6       realm - Manage enrollment in realms
7

SYNOPSIS

9       realm discover [realm-name]
10
11       realm join [-U user] [realm-name]
12
13       realm leave [-U user] [realm-name]
14
15       realm list
16
17       realm permit [-ax] [-R realm] {user@domain...}
18
19       realm deny -a [-R realm]
20

DESCRIPTION

22       realm is a command line tool that can be used to manage enrollment in
23       kerberos realms, like Active Directory domains or IPA domains.
24
25       See the various sub commands below. The following global options can be
26       used:
27
28       -i, --install=/path
29           Run in install mode. This makes realmd chroot into the directory
30           specified by an absolute path and place files in appropriate
31           locations for use during an installer. No packages will be
32           installed or services will be started when running in this mode.
33
34       --unattended
35           Run in unattended mode without prompting for input.
36
37       -v, --verbose
38           Display verbose diagnostics while doing running commands.
39

DISCOVER

41       Discover a realm and its capabilities.
42
43           $ realm discover
44
45           $ realm discover domain.example.com
46
47       After discovering a realm, its name, type and capabilities are
48       displayed.
49
50       If no domain is specified, then the domain assigned through DHCP is
51       used as a default.
52
53       The following options can be used:
54
55       -a, --all
56           Show all discovered realms (in various configurations).
57
58       --client-software=xxx
59           Only discover realms for which we can use the given client
60           software. Possible values include sssd or winbind.
61
62       -n, --name
63           Only show the names of the discovered realms.
64
65       --server-software=xxx
66           Only discover realms which run the given server software. Possible
67           values include active-directory or ipa.
68
69       --membership-software=xxx
70           Only discover realms for which the given membership software can be
71           used to subsequently perform enrollment. Possible values include
72           samba or adcli.
73
74       --use-ldaps
75           See option description in the section called “JOIN”.
76

JOIN

78       Configure the local machine for use with a realm.
79
80           $ realm join domain.example.com
81
82           $ realm join --user=admin --computer-ou=OU=Special domain.example.com
83
84       The realm is first discovered, as we would with the discover command.
85       If no domain is specified, then the domain assigned through DHCP is
86       used as a default.
87
88       After a successful join, the computer will be in a state where it is
89       able to resolve remote user and group names from the realm. For
90       kerberos realms, a computer account and host keytab is created.
91
92       Joining arbitrary kerberos realms is not supported. The realm must have
93       a supported mechanism for joining from a client machine, such as Active
94       Directory or IPA.
95
96       If the domain has been preconfigured, and unless --user is explicitly
97       specified, an automatic join is attempted first.
98
99       Note that the --user, --no-password, and --one-time-password options
100       are mutually exclusive. At most one of them can be specified.
101
102       It is generally possible to use kerberos credentials to perform a join
103       operation. Use the kinit command to acquire credentials prior to
104       starting the join. Do not specify the --user argument, the user will be
105       selected automatically from the credential cache. The realm respects
106       the KRB5_CCACHE environment variable, but uses the default kerberos
107       credential cache if it's not present. Not all types of servers can be
108       joined using kerberos credentials, some (like IPA) insist on prompting
109       for a password.
110
111       The following options can be used:
112
113       --automatic-id-mapping=no
114           Do not perform UID/GID mapping for users and groups, but expect
115           these identifiers to be present in the domain already.
116
117       --client-software=xxx
118           Only join realms for which we can use the given client software.
119           Possible values include sssd or winbind. Not all values are
120           supported for all realms. By default the client software is
121           automatically selected.
122
123       --computer-ou=OU=xxx
124           The distinguished name of an organizational unit to create the
125           computer account. The exact format of the distinguished name
126           depends on the client software and membership software. You can
127           usually omit the root DSE portion of distinguished name. This is an
128           Active Directory specific option.
129
130       --membership-software=xxx
131           The software to use when joining to the realm. Possible values
132           include samba or adcli. Not all values are supported for all
133           realms. By default the membership software is automatically
134           selected.
135
136       --computer-name=xxx
137           This option only applies to Active Directory realms. Specify this
138           option to override the default name used when creating the computer
139           account. The system's FQDN will still be saved in the dNSHostName
140           attribute.
141
142           Specify the name as a string of 15 or fewer characters that is a
143           valid NetBIOS computer name.
144
145       --no-password
146           Perform the join automatically without a password.
147
148       --one-time-password=xxxx
149           Perform the join using a one time password specified on the command
150           line. This is not possible with all types of realms.
151
152       --os-name=xxx
153           The name of the operation system of the client. When joining an AD
154           domain the value is store in the matching AD attribute.
155
156       --os-version=xxx
157           The version of the operation system of the client. When joining an
158           AD domain the value is store in the matching AD attribute.
159
160       --server-software=xxx
161           Only join realms for run the given server software. Possible values
162           include active-directory or ipa.
163
164       -U, --user=xxx
165           The user name to be used to authenticate with when joining the
166           machine to the realm. You will be prompted for a password.
167
168       --user-principal=host/name@REALM
169           Set the userPrincipalName field of the computer account to this
170           kerberos principal. If you omit the value for this option, then a
171           principal will be set based on the defaults of the membership
172           software.
173
174           AD makes a distinction between user and service principals. Only
175           with user principals you can request a Kerberos
176           Ticket-Granting-Ticket (TGT), i.e. only user principals can be used
177           with the kinit command. By default the user principal and the
178           canonical principal name of an AD computer account is
179           shortname$@AD.DOMAIN, where shortname is the NetBIOS name which is
180           limited to 15 characters.
181
182           If there are applications which are not aware of the AD default and
183           are using a hard-coded default principal the --user-principal can
184           be used to make AD aware of this principal. Please note that
185           userPrincipalName is a single value LDAP attribute, i.e. only one
186           alternative user principal besides the AD default user principal
187           can be set.
188
189       --use-ldaps
190           Use the ldaps port when connecting to AD where possible. In general
191           this option is not needed because realmd itself only read public
192           information from the Active Directory domain controller which is
193           available anonymously. The supported membership software products
194           will use encrypted connections protected with GSS-SPNEGO/GSSAPI
195           which offers a comparable level of security than ldaps. This option
196           is only needed if the standard LDAP port (389/tcp) is blocked by a
197           firewall and only the LDAPS port (636/tcp) is available. Given that
198           and to lower the initial effort to discover a remote domain realmd
199           does not require a strict certificate check. If the validation of
200           the LDAP server certificate fails realmd will continue to setup the
201           encrypted connection to the LDAP server.
202
203           If this option is set to yes realmd will use the ldaps port when
204           reading the rootDSE and call the adcli membership software with the
205           option --use-ldaps. The Samba base membership currently offers only
206           deprecated ways to enable ldaps. Support will be added in realmd
207           when a new way is available.
208

LEAVE

210       Deconfigure the local machine for use with a realm.
211
212           $ realm leave
213
214           $ realm leave domain.example.com
215
216       If no realm name is specified, then the first configured realm will be
217       used.
218
219       The following options can be used:
220
221       --client-software=xxx
222           Only leave the realm which is using the given client software.
223           Possible values include sssd or winbind.
224
225       --server-software=xxx
226           Only leave the realm which is using the given server software.
227           Possible values include active-directory or ipa.
228
229       --remove
230           Remove or disable computer account from the directory while leaving
231           the realm. This will usually prompt for a pasword.
232
233       -U, --user
234           The user name to be used to authenticate with when leaving the
235           realm. You will be prompted for a password. Implies --remove.
236
237       --use-ldaps
238           See option description in the section called “JOIN”.
239

LIST

241       List all the discovered and configured realms.
242
243           $ realm list
244
245       By default, realms that have been discovered, but not configured (using
246       the join command), are not displayed. Also, by default, the list of
247       realm details displayed is verbose. The options below can be used to
248       change this default behavior
249
250       The following options can be used:
251
252       --all
253           Show all discovered realms (whether or not they have been
254           configured).
255
256       --name-only
257           Display only realm names (as opposed to verbose output).
258

PERMIT

260       Permit local login by users of the realm.
261
262           $ realm permit --all
263           $ realm permit user@example.com
264           $ realm permit DOMAIN\\User2
265           $ realm permit --withdraw user@example.com
266
267       The current login policy and format of the user names can be seen by
268       using the realm list command.
269
270       The following options can be used:
271
272       --all, -a
273           Permit logins using realm accounts on the local machine according
274           to the realm policy.This usually defaults to allowing any realm
275           user to log in.
276
277       --groups, -g
278           Treat the specified names as groups rather than user login names.
279           Permit login by users in the specified groups.
280
281       --realm, -R
282           Specify the of the realm to change login policy for.
283
284       --withdraw, -x
285           Remove a login from the list of realm accounts permitted to log
286           into the machine.
287

DENY

289       Deny local login by realm accounts.
290
291           $ realm deny --all
292
293       This command prevents realm accounts from logging into the local
294       machine. Use realm permit to restrict logins to specific accounts.
295
296       The following options can be used:
297
298       --all, -a
299           This option should be specified
300
301       --realm, -R
302           Specify the name of the realm to deny users login to.
303

SEE ALSO

305       realmd.conf(5)
306

AUTHOR

308       Stef Walter <stef@thewalter.net>
309           Maintainer
310
311
312
313realmd                            01/21/2022                          REALM(8)
Impressum