'\" t
.\"     Title: realmd.conf
.\"    Author: Stef Walter <stef@thewalter.net>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/10/2024
.\"    Manual: File Formats
.\"    Source: realmd
.\"  Language: English
.\"
.TH "REALMD\&.CONF" "5" "03/10/2024" "realmd" "File Formats"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
realmd.conf \- Tweak behavior of realmd
.SH "CONFIGURATION FILE"
.PP
\fBrealmd\fR
can be tweaked by network administrators to act in specific ways\&. This is done by placing settings in a
/etc/realmd\&.conf\&. This file does not exist by default\&. The syntax of this file is the same as an INI file or Desktop Entry file\&. If the file is changed and
\fBrealmd\fR
is running
\fBrealmd\fR
must be restarted to read the new values\&.
.PP
In general, settings in this file only apply at the point of joining a domain or realm\&. Once the realm has been setup the settings have no effect\&. You may choose to configure
\m[blue]\fBSSSD\fR\m[]\&\s-2\u[1]\d\s+2
or
\m[blue]\fBWinbind\fR\m[]\&\s-2\u[2]\d\s+2
directly\&.
.PP
Only specify the settings you wish to override in the
/etc/realmd\&.conf
file\&. Settings not specified will be loaded from their packaged defaults which can be found in
/usr/lib/realmd/realmd\-defaults\&.conf
and
/usr/lib/realmd/realmd\-distro\&.conf\&. Only override the settings below\&. You may find other settings if you look through the
\fBrealmd\fR
source code\&. However these are not guaranteed to remain stable\&.
.PP
There are various sections in the config file\&. Some sections are global topic sections, and are listed below\&. Other sections are specific to a given realm\&. These realm specific sections should always contain the domain name in lower case as their section header\&.
.PP
Examples of each setting is found below, including the header of the section it should be placed in\&. However in the resulting file only include each section once, and combine the various section setting together as lines underneath the section\&. For example
.sp
.if n \{\
.RS 4
.\}
.nf
[users]
default\-home = /home/%U
default\-shell = /bin/bash
.fi
.if n \{\
.RE
.\}
.SH "ACTIVE\-DIRECTORY"
.PP
These options should go in an
\fB[active\-directory]\fR
section of the
/etc/realmd\&.conf
file\&. Only specify the settings you wish to override\&.
.PP
\fBdefault\-client\fR
.RS 4
Specify the
\fBdefault\-client\fR
setting in order to control which client software is the preferred default for use with Active Directory\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[active\-directory]
default\-client = sssd
# default\-client = winbind

.fi
.if n \{\
.RE
.\}
The default setting for this is
\fBsssd\fR
which uses
\m[blue]\fBSSSD\fR\m[]\&\s-2\u[1]\d\s+2
as the Active Directory client\&. You can also specify
\fBwinbind\fR
to use
\m[blue]\fBSamba Winbind\fR\m[]\&\s-2\u[2]\d\s+2\&.
.sp
Some callers of
\fBrealmd\fR
such as the
\fBrealm\fR
command line tool allow specifying which client software should be used\&. Others, such as GNOME Control Center, simplify choose the default\&.
.sp
You can verify the preferred default client softawre by running the following command\&. The realm with the preferred client software will be listed first\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBrealm discover domain\&.example\&.com\fR
domain\&.example\&.com
  configured: no
  server\-software: active\-directory
  client\-software: sssd
  type: kerberos
  realm\-name: AD\&.THEWALTER\&.LAN
  domain\-name: ad\&.thewalter\&.lan
domain\&.example\&.com
  configured: no
  server\-software: active\-directory
  client\-software: winbind
  type: kerberos
  realm\-name: AD\&.THEWALTER\&.LAN
  domain\-name: ad\&.thewalter\&.lan
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBuse\-ldaps\fR
.RS 4
Use the ldaps port when connecting to AD where possible\&. In general this option is not needed because
\fBrealmd\fR
itself only read public information from the Active Directory domain controller which is available anonymously\&. The supported membership software products will use encrypted connections protected with GSS\-SPNEGO/GSSAPI which offers a comparable level of security than ldaps\&. This option is only needed if the standard LDAP port (389/tcp) is blocked by a firewall and only the LDAPS port (636/tcp) is available\&.
.sp
If this option is set to
\fIyes\fR
\fBrealmd\fR
will use the ldaps port when reading the rootDSE and call the
\fBadcli\fR
membership software with the option
\fB\-\-use\-ldaps\fR\&. The Samba base membership currently offers only deprecated ways to enable ldaps\&. Support will be added in
\fBrealmd\fR
when a new way is available\&.
.RE
.PP
\fBos\-name\fR
.RS 4
(see below)
.RE
.PP
\fBos\-version\fR
.RS 4
Specify the
\fBos\-name\fR
and/or
\fBos\-version\fR
settings to control the values that are placed in the computer account
\fBoperatingSystem\fR
and
\fBoperatingSystemVersion\fR
attributes\&.
.sp
This is an Active Directory specific option\&.
.sp
It is also possible to use the
\fB\-\-os\-name\fR
or
\fB\-\-os\-version\fR
argument of the
\fBrealm\fR
command to override the default values\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[active\-directory]
os\-name = Gentoo Linux
os\-version = 9\&.9\&.9\&.9\&.9
.fi
.if n \{\
.RE
.\}
.RE
.SH "SERVICE"
.PP
These options should go in an
\fB[service]\fR
section of the
/etc/realmd\&.conf
file\&. Only specify the settings you wish to override\&.
.PP
\fBautomatic\-install\fR
.RS 4
Set this to
\fIno\fR
to disable automatic installation of packages via package\-kit\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[service]
automatic\-install = no
# automatic\-install = yes
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBlegacy\-samba\-config\fR
.RS 4
Set this to
\fIyes\fR
to create a Samba configuration file with id\-mapping options used by Samba\-3\&.5 and earlier version\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[service]
legacy\-samba\-config = no
# legacy\-samba\-config = yes
.fi
.if n \{\
.RE
.\}
.RE
.SH "USERS"
.PP
These options should go in an
\fB[users]\fR
section of the
/etc/realmd\&.conf
file\&. Only specify the settings you wish to override\&.
.PP
\fBdefault\-home\fR
.RS 4
Specify the
\fBdefault\-home\fR
setting in order to control how to set the home directory for accounts that have no home directory explicitly set\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[users]
default\-home = /home/%U@%D
# default\-home = /nfs/home/%D\-%U
# default\-home = /home/%D/%U

.fi
.if n \{\
.RE
.\}
The default setting for this is
\fB/home/%U@%D\fR\&. The
\fB%D\fR
format is replaced by the domain name\&. The
\fB%U\fR
format is replaced by the user name\&.
.sp
You can verify the home directory for a user by running the following command\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBgetent passwd \*(AqDOMAIN/User\*(Aq\fR
DOMAIN\euser:*:13445:13446:Name:/home/DOMAIN/user:/bin/bash
.fi
.if n \{\
.RE
.\}
Note that in the case of IPA domains, most users already have a home directory configured in the domain\&. Therefore this configuration setting may rarely show through\&.
.RE
.PP
\fBdefault\-shell\fR
.RS 4
Specify the
\fBdefault\-shell\fR
setting in order to control how to set the Unix shell for accounts that have no shell explicitly set\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[users]
default\-shell = /bin/bash
# default\-shell = /bin/sh

.fi
.if n \{\
.RE
.\}
The default setting for this is
\fB/bin/bash\fR
shell\&. The shell should be a valid shell if you expect the domain users be able to log in\&. For example it should exist in the
/etc/shells
file\&.
.sp
You can verify the shell for a user by running the following command\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBgetent passwd \*(AqDOMAIN/User\*(Aq\fR
DOMAIN\euser:*:13445:13446:Name:/home/DOMAIN/user:/bin/bash
.fi
.if n \{\
.RE
.\}
Note that in the case of IPA domains, most users already have a shell configured in the domain\&. Therefore this configuration setting may rarely show through\&.
.RE
.SH "PATHS"
.PP
These options should go in an
\fB[paths]\fR
section of the
/etc/realmd\&.conf
file\&. Only specify the settings you wish to override\&.
.PP
\fBkrb5\&.conf\fR
.RS 4
Path to the Kerberos configuration file, typically
/etc/krb5\&.conf\&. It can also be the path of a file included by
/etc/krb5\&.conf, e\&.g\&.
/etc/krb5\&.conf\&.d/realmd_settings, if the file does not exist if will be created\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[paths]
krb5\&.conf = /etc/krb5\&.conf\&.d/realmd_settings

.fi
.if n \{\
.RE
.\}
When joining an Active Directory domain
\fBrealmd\fR
will set the
\fBdefault_realm\fR
and
\fBudp_preference_limit\fR
options in the Kerberos configuration:
.sp
.if n \{\
.RS 4
.\}
.nf
default_realm = DOMAIN\&.EXAMPLE\&.COM
udp_preference_limit = 0

.fi
.if n \{\
.RE
.\}
The
\fBdefault_realm\fR
option is e\&.g\&. needed when trying to resolve enterprise principals and makes it more convenient to request Kerberos tickets for users of the default realm\&. Instead of specifying the whole principal just
\fBkinit username\fR
can be used\&.
.sp
With
\fBudp_preference_limit = 0\fR
always TCP will be used to send Kerberos request to domain controller\&. This is useful in Active Directory environments because Kerberos will typically switch to TCP after initially starting with UDP because AD Kerberos tickets are often larger than UDP can handle\&. Using TCP by default will avoid those extra UDP round trips\&. Additionally it helps to avoid issues with password changes when the DC does not reply soon enough and the client will send a second UDP request\&. The DC might reply with a reply error to the second request although the original password change request was successful and the client will no know if the request was successful or not\&. When using TCP this cannot happen because the client will never send a second request but waits on the connection until the server replies\&.
.sp
Please note that
\fBrealmd\fR
will not remove those options while leaving the domain since they are useful in general\&. When joining a new domain
\fBrealmd\fR
will of course overwrite
\fBdefault_realm\fR\&.
.RE
.SH "REALM SPECIFIC SETTINGS"
.PP
These options should go in an section with the same name as the realm in the
/etc/realmd\&.conf
file\&. For example for the
\fBdomain\&.example\&.com\fR
domain the section would be called
\fB[domain\&.example\&.com]\fR\&. To figure out the canonical name for a realm use the
\fBrealm\fR
command:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBrealm discover \-\-name\-only DOMAIN\&.example\&.com\fR
domain\&.example\&.com
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.PP
Only specify the settings you wish to override\&.
.PP
\fBcomputer\-ou\fR
.RS 4
Specify this option to create directory computer accounts in a location other than the default\&. This currently only works with Active Directory domains\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[domain\&.example\&.com]
computer\-ou = OU=Linux Computers,DC=domain,DC=example,DC=com
# computer\-ou = OU=Linux Computers,

.fi
.if n \{\
.RE
.\}
Specify the OU as an LDAP DN\&. It can be relative to the Root DSE, or a complete LDAP DN\&. Obviously the OU must exist in the directory\&.
.sp
It is also possible to use the
\fB\-\-computer\-ou\fR
argument of the
\fBrealm\fR
command to create a computer account at a specific OU\&.
.RE
.PP
\fBcomputer\-name\fR
.RS 4
This option only applied to Active Directory realms\&. Specify this option to override the default name used when creating the computer account\&. The system\*(Aqs FQDN will still be saved in the dNSHostName attribute\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[domain\&.example\&.com]
computer\-name = SERVER01
.fi
.if n \{\
.RE
.\}
Specify the name as a string of 15 or fewer characters that is a valid NetBIOS computer name\&.
.sp
It is also possible to use the
\fB\-\-computer\-name\fR
argument of the
\fBrealm\fR
command to override the default computer account name\&.
.RE
.PP
\fBuser\-principal\fR
.RS 4
Set the
\fBuser\-principal\fR
to
yes
to create
\fBuserPrincipalName\fR
attribute for the computer accounts in the realm\&. The exact value depends on the defaults of the used membership software\&. To have full control over the value please use the
\fB\-\-user\-principal\fR
option of the
\fBrealm\fR
command, see
\fBrealm\fR(8)
for details\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[domain\&.example\&.com]
user\-principal = yes
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBautomatic\-join\fR
.RS 4
This option only applies to Active Directory realms\&. This option is off by default\&. In Active Directory domains, a computer account can be preset with a known computer account password\&. This can be used for automatic joins without authentication\&.
.sp
When automatic joins are used there is no mutual authentication between the machine and the domain during the join process\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[domain\&.example\&.com]
automatic\-join = yes
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBautomatic\-id\-mapping\fR
.RS 4
This option is on by default for Active Directory realms\&. Turn it off to use UID and GID information stored in the directory (as\-per RFC2307) rather than automatically generating UID and GID numbers\&.
.sp
This option only makes sense for Active Directory realms\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[domain\&.example\&.com]
automatic\-id\-mapping = no
# automatic\-id\-mapping = yes
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBmanage\-system\fR
.RS 4
This option is on by default\&. Normally joining a realm affects many aspects of the configuration and management of the system\&. Turning this off limits the interaction with the realm or domain to authentication and identity\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[domain\&.example\&.com]
manage\-system = no
# manage\-system = yes

.fi
.if n \{\
.RE
.\}
When this option is turned on
\fBrealmd\fR
defaults to using domain policy to control who can log into this machine\&. Further adjustments to login policy can be made with the
\fBrealm permit\fR
command\&.
.RE
.PP
\fBfully\-qualified\-names\fR
.RS 4
This option is on by default\&. If turned off then realm user and group names are not qualified their name\&. This may cause them to conflict with local user and group names\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[domain\&.example\&.com]
fully\-qualified\-names = no
# fully\-qualified\-names = yes
.fi
.if n \{\
.RE
.\}
.RE
.SH "SEE ALSO"
.PP
\fBrealm\fR(8)
.SH "AUTHOR"
.PP
\fBStef Walter\fR <\&stef@thewalter\&.net\&>
.RS 4
Maintainer
.RE
.SH "NOTES"
.IP " 1." 4
SSSD
.RS 4
\%https://fedorahosted.org/sssd/
.RE
.IP " 2." 4
Winbind
.RS 4
\%http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/winbind.html
.RE