IPA-EPN: First version.

EPN stands for Expiring Password Notification. It is a standalone
tool designed to build a list of users whose password would expire
in the near future, and either display the list in a machine-readable
format, or send email notifications to these users.

EPN provides command-line options to display the list of affected users.
This provides data introspection and helps understand how many emails
would be sent for a given day, or a given date range.
The command-line options can also be used by a monitoring system to alert
whenever a number of emails over the SMTP quota would be sent.

EPN is meant to be launched once a day from an IPA client (preferred)
or replica from a systemd timer.

EPN does not keep state. The list of affected users is built at runtime
but never kept.

TLS/STARTTLS SMTP code is untested and unlikely to work as-is.

Parts of code contributed by Rob Crittenden.
Ideas and feedback contributed by Christian Heimes and Michal Polovka.

Fixes: https://pagure.io/freeipa/issue/3687
Signed-off-by: François Cami <[email protected]>
Signed-off-by: Rob Crittenden <[email protected]>
Reviewed-By: Michal Polovka <[email protected]>
Reviewed-By: Christian Heimes <[email protected]>

client/Makefile.am

@@ -44,6 +44,7 @@ sbin_SCRIPTS =			\
 	ipa-client-automount	\
 	ipa-client-install	\
 	ipa-client-samba	\
+	ipa-epn                 \
 	$(NULL)
 
 ipa_getkeytab_SOURCES =		\
@@ -91,10 +92,12 @@ ipa_join_LDADD = 		\
 	$(NULL)
 
 SUBDIRS =			\
-	share		\
+	share		        \
 	man			\
-	sysconfig	\
+	sysconfig	        \
 	$(NULL)
+#       init                    
+
 
 noinst_HEADERS =		\
 	ipa-client-common.h
@@ -104,6 +107,7 @@ EXTRA_DIST =			\
 	ipa-client-automount.in	\
 	ipa-client-install.in	\
 	ipa-client-samba.in	\
+	ipa-epn.in              \
 	$(NULL)
 
 install-data-hook:

client/ipa-epn.in

@@ -0,0 +1,25 @@
+#!/usr/bin/python3
+#
+# Copyright (C) 2020  FreeIPA Contributors see COPYING for license
+#
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""This tool prepares then sends email notifications to users
+   whose passwords are expiring in the near future.
+"""
+
+from ipaclient.install.ipa_epn import EPN
+
+EPN.run_cli()

client/man/Makefile.am

@@ -10,7 +10,9 @@ dist_man1_MANS =			\
 		ipa-client-samba.1	\
 		ipa-certupdate.1	\
 		ipa-join.1		\
+		ipa-epn.1               \
 		ipa.1
 
 dist_man5_MANS =			\
-		default.conf.5
+		default.conf.5          \
+		epn.conf.5

client/man/epn.conf.5

@@ -0,0 +1,76 @@
+.\" A man page for epn.conf
+.\" Copyright (C) 2020 Red Hat, Inc.
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+.\" General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
+.\"
+.\" Author: Rob Crittenden <rcritten@@redhat.com>
+.\"
+.TH "epn.conf" "5" "Apr 28 2020" "FreeIPA" "FreeIPA Manual Pages"
+.SH "NAME"
+epn.conf \- Expiring Password Notification configuration file
+.SH "SYNOPSIS"
+/etc/ipa/epn.conf
+.SH "DESCRIPTION"
+The \fIepn.conf \fRconfiguration file is used to set the options for the ipa-epn tool to notify users of upcoming password expiration.
+
+.SH "SYNTAX"
+The configuration options are not case sensitive. The values may be case sensitive, depending on the option.
+
+Blank lines are ignored.
+Lines beginning with # are comments and are ignored.
+
+Valid lines consist of an option name, an equals sign and a value. Spaces surrounding equals sign are ignored. An option terminates at the end of a line.
+
+Values should not be quoted, the quotes will not be stripped.
+
+.RS L
+    # Wrong \- don't include quotes
+    verbose = "True"
+
+    # Right \- Properly formatted options
+    verbose = True
+    verbose=True
+.RE
+
+Options must appear in the section named [global]. There are no other sections defined or used currently.
+
+Options may be defined that are not used by IPA. Be careful of misspellings, they will not be rejected.
+.SH "OPTIONS"
+.TP
+.B smtp_server\fR <fqdn>
+Specifies the SMTP server to use. The default is localhost.
+.TP
+.B smtp_port <port>
+Specifies the SMTP port. The default is 25.
+.TP
+.B smtp_user <user>
+Specifies the id of the user to authenticate with the SMTP server. Default None.
+.TP
+.B smtp_password <password>
+Specifies the password for the authorized user. Default None.
+.TP
+.B smtp_timeout <seconds>
+Specifies the number of seconds to wait for SMTP to respond. Default 60.
+.TP
+.B smtp_security <security>
+Specifies the type of secure connection to make. Options are: none, starttls and ssl. The default is none.
+.TP
+.B notify_ttls <list of days>
+This is the list of days before a password expiration when ipa-epn shoould notify a user that their password will soon require a reset. If this value is not specified then the default list will be used: 28, 14, 7, 3, 1.
+.SH "FILES"
+.TP
+.I /etc/ipa/epn.conf
+Configuration file
+.SH "SEE ALSO"
+.BR ipa-epn (1)

client/man/ipa-epn.1

@@ -0,0 +1,119 @@
+.\" A man page for ipa-epn
+.\" Copyright (C) 2020 Red Hat, Inc.
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+.\" General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
+.\"
+.\"
+.TH "ipa-epn" "1" "Apr 24 2020" "FreeIPA" "FreeIPA Manual Pages"
+.SH "NAME"
+ipa\-epn \- Send expiring password nofications
+.SH "SYNOPSIS"
+ipa\-epn \[options\]
+
+.SH "DESCRIPTION"
+ipa\-epn provides a method to warn users via email that their IPA account password is about to expire. 
+
+It can be used in dry\-run mode which is recommmended during setup. The output is always JSON in this case.
+
+It can also be launched daily by its systemd timer.
+In this case it will parse its configuration file epn.conf(5) and send an email to users whose passwords are expiring within the defined future date ranges.
+
+See the OPTIONS section below and the epn.conf(5) man page on how to configure the tool.
+
+.SH "OPTIONS"
+.TP
+\fB\-\-to-nbdays\fR \fI<number of days>\fR
+The \-\-to\-nbdays CLI option can be used to determine the number of notifications that would be sent in a given timeframe.
+
+If \fB\-\-from\-nbdays\fR is not specified, ipa\-epn will look within a 24\-hour long time range in <number of days> days.
+
+if \fB\-\-from\-nbdays\fR is specified, the date range starts at \fB\-\-from\-nbdays\fR days in the future and ends at \fB\-\-to\-nbdays\fR in the future. 
+
+Together, these two CLI options can be used to determine how many emails would be sent in a specific time in the future.
+
+The \fB\-\-to\-nbdays\fR CLI option implies \fB\-\-dry\-run\fR.
+.TP
+\fB\-\-from\-nbdays\fR \fI<number of days>\fR
+See \fB\-\-to\-nbdays\fR for an explanation. This option must be used in conjonction with \fB\-\-to\-nbdays\fR.
+.TP
+\fB\-\-dry\-run\fR
+The \fB\-\-dry\-run\fR CLI option is intented to test ipa\-epn's configuration.
+
+For instance, if notify_ttls is set to 21, 14, 3, \fB\-\-dry-run\fR would display the list of users whose passwords would expire in 21, 14, and 3 days in the future.
+
+
+.SH "EXAMPLES"
+.nf
+   # date
+   Sun 12 Apr 2020 06:23:08 AM CEST
+   # ipa\-epn \-\-dry\-run
+   [
+      {
+         "uid": "user5",
+         "cn": "user 5",
+         "krbpasswordexpiration": "2020\-04\-17 15:51:53",
+         "mail": "['[email protected]']"
+      }
+   ]
+   The IPA\-EPN command was successful
+
+   # ipa\-epn \-\-to\-nbdays 6 \-\-dry-run 
+   [
+      {
+         "uid": "user5",
+         "cn": "user 5",
+         "krbpasswordexpiration": "2020\-04\-17 15:51:53",
+         "mail": "['[email protected]']"
+      }
+   ]
+   The IPA\-EPN command was successful
+
+   # ipa\-epn \-\-from-nbdays 2 \-\-to-nbdays 6 \-\-dry\-run
+   [
+      {
+         "uid": "user5",
+         "cn": "user 5",
+         "krbpasswordexpiration": "2020\-04\-17 15:51:53",
+         "mail": "['[email protected]']"
+      }
+   ]
+   The IPA\-EPN command was successful
+
+   # ipa\-epn \-\-from\-nbdays 8 \-\-to\-nbdays 12 \-\-dry\-run
+   [
+      {
+         "uid": "user3",
+         "cn": "user 5",
+         "krbpasswordexpiration": "2020\-04\-21 00:00:08",
+         "mail": "['[email protected]']"
+      }
+   ]
+   The IPA\-EPN command was successful
+
+
+.SH "EXIT STATUS"
+The exit status is 0 on success, nonzero on error.
+
+.SH "SEE ALSO"
+   RFE: https://pagure.io/freeipa/issue/3687
+   Design document: https://github.com/freeipa/freeipa/blob/master/doc/designs/expiring-password-notification.md
+
+
+.SH "KNOWN BUGS"
+   None yet.
+
+.SH "REPORTING BUGS AND ENHANCEMENT IDEAS"
+.nf
+   Please make sure first the issue is not already reported by searching at https://pagure.io/freeipa/issues. If it is not, file a new issue at https://pagure.io/freeipa/new_issue.
+

freeipa.spec.in

@@ -588,6 +588,15 @@ Requires: cifs-utils
 This package provides command-line tools to deploy Samba domain member
 on the machine enrolled into a FreeIPA environment
 
+%package client-epn
+Summary: Tools to configure Expiring Password Notification in IPA
+Group: System Environment/Base
+Requires: %{name}-client = %{version}-%{release}
+
+%description client-epn
+This package provides a service to collect and send expiring password
+notifications via email (SMTP).
+
 %package -n python3-ipaclient
 Summary: Python libraries used by IPA client
 Group: System Environment/Libraries
@@ -1345,6 +1354,16 @@ fi
 %{_sbindir}/ipa-client-samba
 %{_mandir}/man1/ipa-client-samba.1*
 
+
+%files client-epn
+%doc README.md Contributors.txt
+%license COPYING
+%{_sbindir}/ipa-epn
+%{_mandir}/man1/ipa-epn.1*
+%{_mandir}/man5/epn.conf.5*
+%attr(644,root,root) %{_unitdir}/ipa-epn.service
+%attr(644,root,root) %{_unitdir}/ipa-epn.timer
+
 %files -n python3-ipaclient
 %doc README.md Contributors.txt
 %license COPYING

init/systemd/Makefile.am

@@ -4,11 +4,15 @@ AUTOMAKE_OPTIONS = 1.7
 
 dist_noinst_DATA = 			\
 	ipa-custodia.service.in		\
-	ipa.service.in
+	ipa.service.in			\
+	ipa-epn.service.in		\
+	ipa-epn.timer.in
 
 systemdsystemunit_DATA = 	\
 	ipa-custodia.service	\
-	ipa.service
+	ipa.service				\
+	ipa-epn.service			\
+	ipa-epn.timer
 
 CLEANFILES = $(systemdsystemunit_DATA)
 

init/systemd/ipa-epn.service.in

@@ -0,0 +1,9 @@
+[Unit]
+Description=Execute IPA Expiring Password Notification (EPN)
+
+[Service]
+Type=simple
+ExecStart=@sbindir@/ipa-epn
+
+[Install]
+WantedBy=multi-user.target

init/systemd/ipa-epn.timer.in

@@ -0,0 +1,9 @@
+[Unit]
+Description=Execute IPA Expiring Password Notification (EPN) every day at 1AM
+
+[Timer]
+OnCalendar=*-*-* 01:00:00
+Unit=ipa-epn.service
+
+[Install]
+WantedBy=multi-user.target