1AUTHSELECT-MIGRATIO(7)                                  AUTHSELECT-MIGRATIO(7)
2
3
4

NAME

6       authselect-migration - A guide how to migrate from authconfig to
7       authselect.
8

DESCRIPTION

10       This manual page explains the main differences between authconfig, the
11       previous tool to configure system authentication and identity sources,
12       and authselect which replaces it. It also explains what actions need to
13       be done in order to migrate from authconfig to authselect.
14

MAIN DIFFERENCES

16       Authselect takes a completely different approach to system
17       configuration than the previous tool authconfig.
18
19       Authconfig tries its best to keep users’s manual changes to the files
20       it generates. It generates not only PAM configuration files and
21       nsswitch.conf (to setup authentication modules and identity sources)
22       but it also generates simple configuration files for several services
23       such as LDAP and Kerberos.
24
25       Authselect does no such things. It does not generate any configuration
26       files beside PAM and nsswitch.conf and it strictly prohibits any manual
27       changes to generated configuration. It provides a set of files called
28       profiles. Each profile describes how the resulting configuration should
29       look like and it can be slightly modified by enabling or disabling
30       certain optional features. If a need arises for a different profile
31       than what authselect ships, the administrator has an option to create a
32       whole new profile and use it with authselect. See
33       authselect-profiles(5) to learn more about profiles.
34
35       This may seem like a big disadvantage but the truth is the opposite.
36       Authconfig is a very old tool and the applications providing required
37       services have changed rapidly over the years. Typically, there is no
38       longer a need to have multiple authentication modules in PAM and
39       nsswitch.conf, because the vast majority of use-cases is covered by
40       SSSD. Therefore there is no need to add or remove them specifically.
41       There are also better tools to generate configuration for system
42       daemons that can help you automate the process of joining to a remote
43       domain such as realm. In addition, the shipped profiles give us
44       comprehensive and deterministic system configuration that can be fully
45       tested and is much less error prone. It is also much easier to
46       distribute such configuration across many systems.
47
48       Probably the most controversial change is that authselect only ships
49       profiles for sssd and winbind providers. Those two providers cover all
50       modern use cases from providing local users and legacy LDAP domain to
51       complex configurations with IPA or Active Directory servers. The
52       profiles no longer contain support for nss-pam-ldapd and users are
53       encouraged to switch to sssd.
54

JOINING REMOTE DOMAINS

56       You can use either ipa-client-install or realm to join an IPA domain
57       and realm to join an Active Directory domain. These tools will make
58       sure that the correct authselect profile is selected and all daemons
59       and services are properly configured.
60

CONVERTING YOUR SCRIPTS

62       If you use ipa-client-install or realm to join a domain, you can just
63       remove any authconfig call in your scripts. If this is not an option,
64       you need to replace each authconfig call with its equivalent authselect
65       call to select a correct profile with desired features. Then you also
66       need to write configuration file for required services.
67
68       Table 1. Relation of authconfig options to authselect profiles
69       ┌────────────────────┬────────────────────┐
70       │                    │                    │
71Authconfig options  Authselect profile 
72       ├────────────────────┼────────────────────┤
73       │                    │                    │
74       │--enableldap        │ sssd               │
75       │--enableldapauth    │                    │
76       ├────────────────────┼────────────────────┤
77       │                    │                    │
78       │--enablesssd        │ sssd               │
79       │--enablesssdauth    │                    │
80       ├────────────────────┼────────────────────┤
81       │                    │                    │
82       │--enablekrb5        │ sssd               │
83       ├────────────────────┼────────────────────┤
84       │                    │                    │
85       │--enablewinbind     │ winbind            │
86       │--enablewinbindauth │                    │
87       ├────────────────────┼────────────────────┤
88       │                    │                    │
89       │--enablenis         │ nis                │
90       └────────────────────┴────────────────────┘
91
92       Table 2. Relation of authconfig options to authselect profile features
93       ┌────────────────────┬────────────────────────────┐
94       │                    │                            │
95Authconfig options  Authselect profile feature 
96       ├────────────────────┼────────────────────────────┤
97       │                    │                            │
98       │--enablesmartcard   │ with-smartcard             │
99       ├────────────────────┼────────────────────────────┤
100       │                    │                            │
101       │--enablefingerprint │ with-fingerprint           │
102       ├────────────────────┼────────────────────────────┤
103       │                    │                            │
104       │--enableecryptfs    │ with-ecryptfs              │
105       ├────────────────────┼────────────────────────────┤
106       │                    │                            │
107       │--enablemkhomedir   │ with-mkhomedir             │
108       ├────────────────────┼────────────────────────────┤
109       │                    │                            │
110       │--enablefaillock    │ with-faillock              │
111       ├────────────────────┼────────────────────────────┤
112       │                    │                            │
113       │--enablepamaccess   │ with-pamaccess             │
114       ├────────────────────┼────────────────────────────┤
115       │                    │                            │
116       │--enablewinbindkrb5 │ with-krb5                  │
117       └────────────────────┴────────────────────────────┘
118
119       Examples.
120
121           authconfig --enableldap --enableldapauth --enablefaillock --updateall
122           authselect select sssd with-faillock
123
124           authconfig --enablesssd --enablesssdauth --enablesmartcard --smartcardmodule=sssd --updateall
125           authselect select sssd with-smartcard
126
127           authconfig --enableecryptfs --enablepamaccess --updateall
128           authselect select sssd with-ecryptfs with-pamaccess
129
130           authconfig --enablewinbind --enablewinbindauth --winbindjoin=Administrator --updateall
131           realm join -U Administrator --client-software=winbind WINBINDDOMAIN
132
133

CONFIGURATION FILES

135       This section contains snippets for minimal configuration of various
136       services.
137
138   LDAP
139       Even if LDAP is not directly used through pam_ldap and nss_ldap, it is
140       still useful to configure ldap.conf to configure openldap-libs and
141       indirectly, e.g. LDAP tools such as ldapsearch.
142
143       /etc/openldap/ldap.conf.
144
145           # Set the default base dn
146           BASE   dc=example,dc=com
147
148           # Set the default LDAP server
149           URI    ldap://ldap.example.com ldap://ldap-master.example.com:666
150
151
152   KERBEROS
153       If you use Kerberos, the default Kerberos realm should be configured in
154       order for krb5-libs and therefore tools such as kinit to work out of
155       the box.
156
157       /etc/krb5.conf.
158
159           [libdefaults]
160            default_realm = MYREALM
161
162           [realms]
163            MYREALM = {
164             kdc = kdc.myrealm.org
165            }
166
167           [domain_realm]
168            myrealm.org = MYREALM
169            .myrealm.org = MYREALM
170
171
172   SSSD
173       Authselect encourages users to use SSSD wherever possible. There are
174       many configuration options, see sssd.conf(5). This is a minimal
175       configuration that creates one LDAP domain called default. The LDAP
176       server is auto-discovered through DNS lookups.
177
178       /etc/sssd/sssd.conf.
179
180           [sssd]
181           config_file_version = 2
182           domains = default
183
184           [domain/default]
185           id_provider = ldap
186           ldap_uri = _srv_
187           dns_discovery_domain = myrealm
188
189       And here is a configuration snippet for the same domain but now the
190       authentication is done over Kerberos. The KDC server is auto-discovered
191       through DNS lookups.
192
193       /etc/sssd/sssd.conf.
194
195           [sssd]
196           config_file_version = 2
197           domains = default
198
199           [domain/default]
200           id_provider = ldap
201           auth_provider = krb5
202           ldap_uri = _srv_
203           krb5_server = _srv_
204           krb5_realm = MYREALM
205           dns_discovery_domain = myrealm
206
207       If you want to configure SSSD for an IPA or Active Directory domain,
208       use the realm tool. This will perform an initial setup which involves
209       creating a Kerberos keytab and generating basic SSSD configuration. You
210       can then tune it up by modifying /etc/sssd/sssd.conf.
211
212   WINBIND
213       If you want to configure the machine to use Winbind, use realm. This
214       will perform an initial setup which involves creating a Kerberos keytab
215       and running adcli to join the domain. It also makes changes to
216       smb.conf. You can then tune it up by modifying /etc/samba/smb.conf.
217
218   NIS
219       There are several places that needs to be configured in order to make
220       NIS authentication work. First, you need to set NIS domain and
221       optionally also NIS server in /etc/yp.conf.
222
223       /etc/yp.conf.
224
225           domain mydomain broadcast
226           # or
227           # domain mydomain server myserver
228
229       NIS domain must be also set in system network configuration.
230
231       /etc/sysconfig/network.
232
233           NISDOMAIN=mydomain
234
235       Now, you can set the domain name with command line so there is no need
236       to reboot your system. Additionaly, it may be necessary to enable NIS
237       in selinux.
238
239           $ domainname mydomain
240           $ setsebool -P allow_ypbind 1
241
242   PASSWORD QUALITY
243       Authselect enables pam_pwquality module to enforce password quality
244       restrictions. This module is enabled only for local users. Remote users
245       should use the password policy that is enforced by the respective
246       remote server.
247
248       The pam_pwquality module can be configured in
249       /etc/security/pwquality.conf. See pam_pwquality(8) to see its
250       configuration options and defaults.
251

STARTING SERVICES

253       Depending on your configuration, you need to start required services
254       manually with systemd.
255
256       ·   SSSD
257
258               systemctl enable sssd.service ; systemctl start sssd.service
259
260       ·   Winbind
261
262               systemctl enable winbind.service ; systemctl start winbind.service
263
264       ·   NIS
265
266               systemctl enable rpcbind.service ; systemctl start rpcbind.service
267               systemctl enable ypbind.service ; systemctl start ypbind.service
268
269       ·   If mkhomedir feature is enabled
270
271               systemctl enable oddjobd.service ; systemctl start oddjobd.service
272

AUTHCONFIG TOOLS

274       Authconfig shipped a tool called cacertdir_rehash. If you depend on
275       this tool, please switch to native openssl command: openssl rehash
276       <directory> that serves the same purpose.
277

SEE ALSO

279       authselect(8), authselect-profiles(5), realm(8), ipa-client-install(1),
280       sssd.conf(5), smb.conf(5), ldap.conf(5), krb5.conf(5)
281
282
283
284                                  2018-03-18            AUTHSELECT-MIGRATIO(7)
Impressum