'\" t
.\"     Title: realmd.conf
.\"    Author: Stef Walter <stef@thewalter.net>
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 08/15/2016
.\"    Manual: File Formats
.\"    Source: realmd
.\"  Language: English
.\"
.TH "REALMD\&.CONF" "5" "08/15/2016" "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\&.
.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\&. 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
\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
.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 "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 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\-prinicpal\fR
.RS 4
Set the
\fBuser\-prinicpal\fR
to
yes
to create
\fBuserPrincipalName\fR
attributes for the computer account in the realm, in the form
host/computer@REALM
.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 "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