ipa-client-samba: a tool to configure Samba domain member on IPA client

Introduces new utility to configure Samba on an IPA domain member.

The tool sets up Samba configuration and internal databases, creates
cifs/... Kerberos service and makes sure that a keytab for this service
contains the key with the same randomly generated password that is set
in the internal Samba databases.

Samba configuration is created by querying an IPA master about details
of trust to Active Directory configuration. All known identity ranges
added to the configuration to allow Samba to properly handle them
(read-only) via idmap_sss.

Resulting configuration allows connection with both NTLMSSP and Kerberos
authentication for IPA users. Access controls for the shared content
should be set by utilizing POSIX ACLs on the file system under a
specific share.

The utility is packaged as freeipa-client-samba package to allow pulling
in all required dependencies for Samba and cifs.ko (smb3.ko) kernel
module. This allows an IPA client to become both an SMB server and an
SMB client.

Fixes: https://pagure.io/freeipa/issue/3999
Signed-off-by: Alexander Bokovoy <[email protected]>
Reviewed-By: Rob Crittenden <[email protected]>
Reviewed-By: Christian Heimes <[email protected]>

.gitignore

@@ -127,6 +127,7 @@ makeapi
 client/ipa-certupdate
 client/ipa-client-automount
 client/ipa-client-install
+client/ipa-client-samba
 daemons/dnssec/ipa-dnskeysyncd
 daemons/dnssec/ipa-dnskeysync-replica
 daemons/dnssec/ipa-ods-exporter

client/Makefile.am

@@ -43,6 +43,7 @@ sbin_SCRIPTS =			\
 	ipa-certupdate		\
 	ipa-client-automount	\
 	ipa-client-install	\
+	ipa-client-samba	\
 	$(NULL)
 
 ipa_getkeytab_SOURCES =		\
@@ -102,6 +103,7 @@ EXTRA_DIST =			\
 	ipa-certupdate.in	\
 	ipa-client-automount.in	\
 	ipa-client-install.in	\
+	ipa-client-samba.in	\
 	$(NULL)
 
 install-data-hook:

client/ipa-client-samba.in

@@ -0,0 +1,21 @@
+#!/usr/bin/python3
+#
+# Copyright (C) 2019  FreeIPA Contributors see COPYING for license
+#
+# Configure the Samba suite to operate as domain member in IPA domain
+
+import os
+import sys
+from ipaclient.install import ipa_client_samba
+
+try:
+    if not os.geteuid() == 0:
+        sys.exit("\nMust be run as root\n")
+
+    sys.exit(ipa_client_samba.run())
+except SystemExit as e:
+    sys.exit(e)
+except RuntimeError as e:
+    sys.exit(e)
+except (KeyboardInterrupt, EOFError):
+    sys.exit(1)

client/man/Makefile.am

@@ -7,6 +7,7 @@ dist_man1_MANS =			\
 		ipa-rmkeytab.1		\
 		ipa-client-install.1	\
 		ipa-client-automount.1	\
+		ipa-client-samba.1	\
 		ipa-certupdate.1	\
 		ipa-join.1		\
 		ipa.1

client/man/ipa-client-samba.1

@@ -0,0 +1,88 @@
+.\" A man page for ipa-client-samba
+.\" Copyright (C) 2008-2016  FreeIPA Contributors see COPYING for license
+.\"
+.TH "ipa-client-samba" "1" "Jun 10 2019" "FreeIPA" "FreeIPA Manual Pages"
+.SH "NAME"
+ipa\-client\-samba \- Configure Samba file server on an IPA client
+.SH "SYNOPSIS"
+ipa\-client\-samba [\fIOPTION\fR]...
+.SH "DESCRIPTION"
+Configures a Samba file server on the client machine to use IPA domain controller for authentication and identity services.
+
+The tool configures Samba file server to be a domain member of IPA domain. Samba file server will use SSSD to resolve information about users and groups, and will use IPA master it is enrolled against as its domain controller.
+
+It is not possible to reconciliate original Samba environment if that was pre-existing on the client with new configuration. Samba databases will be updated to follow IPA domain details and \fBsmb.conf\fR configuration will will be overwritten. It is recommended to enable Samba suite on a freshly deployed IPA client.
+
+.TP
+During the configuration process, the tool will perform following steps:
+
+1. Discover details of IPA domain: realm, domain SID, domain ID range
+
+2. Discover details of trusted Actvide Directory domains: domain name, domain SID, domain ID range
+
+3. Create Samba configuration file using the details discovered above.
+
+4. Create Samba Kerberos service using host credentials and fetch its keytab into /etc/samba/samba.keytab. The Kerberos service key is pre-set to a randomly generated value that is shared with Samba.
+
+5. Populate Samba databases by setting the domain details and the randomly generated machine account password from the previous step.
+
+6. Create a default [homes] share to allow users to log in to their home directories unless \-\-no\-homes option was specified.
+
+.TP
+The tool does not start nor does it enable Samba file services after the configuration. In order to enable and start Samba file services, one needs to enable both \fBsmb.service\fR and \fBwinbind.service\fR system services. Please check that \fB/etc/samba/smb.conf\fR contains all settings for your use case as starting Samba service will make identity mapping details written into the Samba databases. To enable and start Samba file services at the same time one can use \fBsystemctl enable \-\-now\fR command:
+
+systemctl enable --now smb winbind
+
+.SS "Assumptions"
+The ipa\-client\-samba script assumes that the machine has alreaby been enrolled into IPA.
+
+.SS "IPA Master Requirements"
+At least one IPA master must hold a \fBTrust Controller\fR role. This can be achieved by running ipa\-adtrust\-install on the IPA master. The utility will configure IPA master to be a domain controller for IPA domain.
+
+IPA master holding a \fBTrust Controller\fR role has also to have support for a special service command to create SMB service, \fBipa service-add-smb\fR. This command is available with FreeIPA 4.8.0 or later release.
+
+.SH "OPTIONS"
+.SS "BASIC OPTIONS"
+.TP
+\fB\-\-server\fR=\fISERVER\fR
+Set the FQDN of the IPA server to connect to. Under normal circumstances, this option is not needed as the server to use is discovered automatically.
+.TP
+\fB\-\-no\-homes\fR
+Do not configure a \fB[homes]\fR share by default to allow users to access their home directories.
+.TP
+\fB\-\-no\-nfs\fR
+Do not enable SELinux booleans to allow Samba to re-share NFS shares.
+.TP
+\fB\-\-netbios-name\fR=\fINETBIOS_NAME\fR
+NetBIOS name of this machine. If not provided then this is determined based on the leading component of the hostname.
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+Print debugging information to stdout
+.TP
+\fB\-U\fR, \fB\-\-unattended\fR
+Unattended installation. The user will not be prompted.
+.TP
+\fB\-\-uninstall\fR
+Revert Samba suite configuration changes and remove SMB service principal. It is not possible to preserve original Samba configuration: while \fBsmb.conf\fR configuration file will be restored, various Samba databases would not be restored. In general, it is not possible to restore full original Samba environment.
+.TP
+\fB\-\-force\fR
+Force through the installation steps even if they were done before
+
+.SH "FILES"
+.TP
+Files that will be replaced if Samba is configured:
+
+/etc/samba/smb.conf
+.br
+/etc/samba/samba.keytab
+
+.SH "EXIT STATUS"
+0 if the installation was successful
+
+1 if an error occurred
+
+.SH "SEE ALSO"
+.BR smb.conf(5),
+.BR krb5.conf(5),
+.BR sssd.conf(5),
+.BR systemctl(1)

freeipa.spec.in

@@ -520,6 +520,22 @@ If your network uses IPA for authentication, this package should be
 installed on every client machine.
 This package provides command-line tools for IPA administrators.
 
+%package client-samba
+Summary: Tools to configure Samba on IPA client
+Group: System Environment/Base
+Requires: %{name}-client = %{version}-%{release}
+Requires: python3-samba
+Requires: samba-client
+Requires: samba-winbind
+Requires: samba-common-tools
+Requires: samba
+Requires: sssd-winbind-idmap
+Requires: tdb-tools
+Requires: cifs-utils
+
+%description client-samba
+This package provides command-line tools to deploy Samba domain member
+on the machine enrolled into a FreeIPA environment
 
 %package -n python3-ipaclient
 Summary: Python libraries used by IPA client
@@ -1207,6 +1223,11 @@ fi
 %{_mandir}/man1/ipa-certupdate.1*
 %{_mandir}/man1/ipa-join.1*
 
+%files client-samba
+%doc README.md Contributors.txt
+%license COPYING
+%{_sbindir}/ipa-client-samba
+%{_mandir}/man1/ipa-client-samba.1*
 
 %files -n python3-ipaclient
 %doc README.md Contributors.txt