1REALM(8) User Commands REALM(8)
2
6 realm - Manage enrollment in realms
7
9 realm discover [realm-name]
10 realm join [-U user] [realm-name]
12 realm leave [-U user] [realm-name]
14 realm list
16 realm permit [-ax] [-R realm] {user@domain...}
18 realm deny -a [-R realm]
20
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 See the various sub commands below. The following global options can be
26 used:
27 -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 --unattended
35 Run in unattended mode without prompting for input.
36 -v, --verbose
38 Display verbose diagnostics while doing running commands.
39
41 Discover a realm and its capabilities.
42 $ realm discover
44 $ realm discover domain.example.com
46 After discovering a realm, its name, type and capabilities are
48 displayed.
49 If no domain is specified, then the domain assigned through DHCP is
51 used as a default.
52 The following options can be used:
54 -a, --all
56 Show all discovered realms (in various configurations).
57 --client-software=xxx
59 Only discover realms for which we can use the given client
60 software. Possible values include sssd or winbind.
61 -n, --name
63 Only show the names of the discovered realms.
64 --server-software=xxx
66 Only discover realms which run the given server software. Possible
67 values include active-directory or ipa.
68 --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 --use-ldaps
75 See option description in the section called “JOIN”.
76
78 Configure the local machine for use with a realm.
79 $ realm join domain.example.com
81 $ realm join --user=admin --computer-ou=OU=Special domain.example.com
83 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 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 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 If the domain has been preconfigured, and unless --user is explicitly
97 specified, an automatic join is attempted first.
98 Note that the --user, --no-password, and --one-time-password options
100 are mutually exclusive. At most one of them can be specified.
101 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 The following options can be used:
112 --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 --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 --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 --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 --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 Specify the name as a string of 15 or fewer characters that is a
143 valid NetBIOS computer name.
144 --no-password
146 Perform the join automatically without a password.
147 --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 --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 --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 --server-software=xxx
161 Only join realms for run the given server software. Possible values
162 include active-directory or ipa.
163 -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 --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 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 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 --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 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 --do-not-touch-config
210 Run the join operation but do not touch the local configuration of
211 the client except adding new Kerberos keys to the keytab. The
212 purpose of this option is to synchronize the keytab entries with
213 the ones stored in AD or recreate the computer object in AD without
214 changing the local configuration which might contain changes which
215 would get overwritten by a fully leave/join cycle.
216 If running realm join with this options does not help to fix issues
218 it is recommended to call realm leave followed by realm join to
219 enforce a fresh configuration with default settings. Since this
220 might overwrite manual changes to the related configuration files
221 it is recommend to save those change before running the commands.
222 This options is only available when joining AD domains.
224
226 Deconfigure the local machine for use with a realm.
227 $ realm leave
229 $ realm leave domain.example.com
231 If no realm name is specified, then the first configured realm will be
233 used.
234 The following options can be used:
236 --client-software=xxx
238 Only leave the realm which is using the given client software.
239 Possible values include sssd or winbind.
240 --server-software=xxx
242 Only leave the realm which is using the given server software.
243 Possible values include active-directory or ipa.
244 --remove
246 Remove or disable computer account from the directory while leaving
247 the realm. This will usually prompt for a pasword.
248 -U, --user
250 The user name to be used to authenticate with when leaving the
251 realm. You will be prompted for a password. Implies --remove.
252 --use-ldaps
254 See option description in the section called “JOIN”.
255
257 List all the discovered and configured realms.
258 $ realm list
260 By default, realms that have been discovered, but not configured (using
262 the join command), are not displayed. Also, by default, the list of
263 realm details displayed is verbose. The options below can be used to
264 change this default behavior
265 The following options can be used:
267 --all
269 Show all discovered realms (whether or not they have been
270 configured).
271 --name-only
273 Display only realm names (as opposed to verbose output).
274
276 Permit local login by users of the realm.
277 $ realm permit --all
279 $ realm permit user@example.com
280 $ realm permit DOMAIN\\User2
281 $ realm permit --withdraw user@example.com
282 The current login policy and format of the user names can be seen by
284 using the realm list command.
285 The following options can be used:
287 --all, -a
289 Permit logins using realm accounts on the local machine according
290 to the realm policy.This usually defaults to allowing any realm
291 user to log in.
292 --groups, -g
294 Treat the specified names as groups rather than user login names.
295 Permit login by users in the specified groups.
296 --realm, -R
298 Specify the of the realm to change login policy for.
299 --withdraw, -x
301 Remove a login from the list of realm accounts permitted to log
302 into the machine.
303
305 Deny local login by realm accounts.
306 $ realm deny --all
308 This command prevents realm accounts from logging into the local
310 machine. Use realm permit to restrict logins to specific accounts.
311 The following options can be used:
313 --all, -a
315 This option should be specified
316 --realm, -R
318 Specify the name of the realm to deny users login to.
319
321 realmd.conf(5)
322
324 Stef Walter <stef@thewalter.net>
325 Maintainer
326realmd 01/20/2023 REALM(8)