Implement an IPA Foreman smartproxy server

This currently server supports only host and hostgroup commands for
retrieving, adding and deleting entries.

The incoming requests are completely unauthenticated and by default
requests must be local.

Utilize GSS-Proxy to manage the TGT.

Configuration information is in the ipa-smartproxy man page.

Design: http://www.freeipa.org/page/V3/Smart_Proxy

https://fedorahosted.org/freeipa/ticket/4128

Reviewed-By: Petr Viktorin <pviktori@redhat.com>

3 files changed, 186 insertions, 0 deletions

diff --git a/smartproxy/man/Makefile.am b/smartproxy/man/Makefile.am
new file mode 100644
index 000000000..6626b3cb2
--- /dev/null
+++ b/smartproxy/man/Makefile.am
@@ -0,0 +1,19 @@
+# This file will be processed with automake-1.7 to create Makefile.in
+
+AUTOMAKE_OPTIONS = 1.7
+
+NULL =
+
+man1_MANS = 				\
+		ipa-smartproxy.1
+
+man5_MANS =				\
+		ipa-smartproxy.conf.5
+
+install-data-hook:
+	@for i in $(man1_MANS) ; do gzip -f $(DESTDIR)$(man1dir)/$$i ; done
+	@for i in $(man5_MANS) ; do gzip -f $(DESTDIR)$(man5dir)/$$i ; done
+
+MAINTAINERCLEANFILES =          \
+	Makefile.in		\
+	$(NULL)
diff --git a/smartproxy/man/ipa-smartproxy.1 b/smartproxy/man/ipa-smartproxy.1
new file mode 100644
index 000000000..1fb31bab4
--- /dev/null
+++ b/smartproxy/man/ipa-smartproxy.1
@@ -0,0 +1,105 @@
+.\" A man page for ipa-smartproxy
+.\" Copyright (C) 2014 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 "ipa-smartproxy" "1" "Jan 8 2014" "FreeIPA" "FreeIPA Manual Pages"
+.SH "NAME"
+ipa\-smartproxy \- IPA Foreman Smartproxy server
+.SH "SYNOPSIS"
+ipa\-smartproxy [\fIOPTION\fR]...
+.SH "DESCRIPTION"
+A WSGI service that provides a RESTful API for a use as a Foreman smart proxy. It is run in the context of the Apache web server.
+
+The RESTful interface is not authenticated so it is expected that the server is not generally accessible. By default it listens only on the localhost interface.
+
+The server needs access to an principal that is granted permission to perform host and hostgroup operations on an IPA master.
+
+Smartproxy server\-specific privileges and roles can be created with this:
+
+.na
+ $ ipa privilege\-add 'Smart Proxy Host Management' \-\-desc='Smartproxy host management'
+ $ ipa privilege\-add\-permission 'Smart Proxy Host Management' \-\-permission='add hosts' \-\-permission='remove hosts'
+ $ ipa permission-add 'modify host password' --permissions='write' --type='host' --attrs='userpassword'
+ $ ipa permission-add 'write host certificate' --permissions='write' --type='host' --attrs='usercertificate'
+ $ ipa permission-add 'modify host userclass' --permissions='write' --type='host' --attrs='userclass'
+ $ ipa privilege-add-permission 'Smart Proxy Host Management' --permission='add hosts'  --permission='remove hosts' --permission='modify host password' --permission='modify host userclass' --permission='modify hosts' --permission='revoke certificate' --permission='manage host keytab' --permission='write host certificate' --permissions='retrieve certificates from the ca' --permissions='modify services' --permissions='manage service keytab' --permission='read dns entries' --permission='add dns entries' --permissions='update dns entries' --permissions='remove dns entries'
+ $ ipa role\-add 'Smartproxy management' \-\-desc='Smartproxy management'
+ $ ipa role\-add\-privilege 'Smartproxy management' \-\-privilege='Smart Proxy Host Management' \-\-privilege='Host Group Administrators'
+
+Create a host or user whose credentials will be used by the server to make requests and add it to the role:
+
+ $ ipa user\-add smartproxy \-\-first=Smartproxy \-\-last=Server --shell=/sbin/nologin --homedir=/var/www
+ $ ipa role\-add\-member \-\-users=smartproxy 'Smartproxy management'
+
+On the smartproxy server create a keytab for this user:
+
+ # kinit admin
+ # ipa\-getkeytab \-s ipa.example.com \-p smartproxy@EXAMPLE.COM \-k /etc/ipa/ipa\-smartproxy.keytab
+ # chown root:root /etc/ipa/ipa\-smartproxy.keytab
+ # chmod 600 /etc/ipa/ipa\-smartproxy.keytab
+
+Configure the GSS\-Proxy to manage the credentials. Add this to the top of the gssproxy configuration file (by default /etc/gssproxy/gssproxy.conf), before any other services:
+
+  [service/smartproxy]
+    mechs = krb5
+    cred_store = client_keytab:/etc/ipa/ipa\-smartproxy.keytab
+    cred_store = ccache:/var/lib/gssproxy/clients/krb5cc_%U
+    cred_usage = initiate
+    euid = <uid of the smartproxy user>
+
+Restart GSS\-Proxy
+
+ # systemctl restart gssproxy
+
+Configure Apache to enable GSS\-Proxy. Create the directory /etc/systemd/system/httpd.service.d/ and create the file smartproxy.conf in it:
+
+ # mkdir /etc/systemd/system/httpd.service.d/
+ # cat > /etc/systemd/system/httpd.service.d/smartproxy.conf <<EOF
+ [Service]
+ Environment=GSS_USE_PROXY=1
+ EOF
+ # systemctl daemon-reload
+
+Copy /usr/share/doc/freeipa-server-foreman-smartproxy/ipa-smartproxy-apache.conf to /etc/httpd/conf.d/ipa-smartproxy.conf . This will configure the smartproxy WSGI application.
+
+Add a SELinux rule so Apache can use the port
+
+ # semanage port -a -t http_port_t -p tcp 8090
+
+Restart Apache
+
+ # systemctl restart httpd
+
+.SH "TEST"
+
+To do simple verification that the proxy was installed properly and is working first confirm that it is providing the realm feature:
+
+ # curl http://localhost:8090/features
+ ["realm"]
+
+Retrieve information on the current host, using your Kerberos realm in place of EXAMPLE.COM:
+
+ # curl http://localhost:8090/realm/EXAMPLE.COM/`hostname`
+ {
+   "dn": "fqdn=..."
+   "fqdn": [
+      ...
+   ]
+   "has_keytab": true,
+   ...
+ }
+.SH "SEE ALSO"
+.BR ipa\-smartproxy.conf(5)
diff --git a/smartproxy/man/ipa-smartproxy.conf.5 b/smartproxy/man/ipa-smartproxy.conf.5
new file mode 100644
index 000000000..29adec8cd
--- /dev/null
+++ b/smartproxy/man/ipa-smartproxy.conf.5
@@ -0,0 +1,62 @@
+.\" A man page for ipa-smartproxy.conf
+.\" Copyright (C) 2014 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 "ipa-smartproxy.conf" "5" "Jan 8 2014" "FreeIPA" "FreeIPA Manual Pages"
+.SH "NAME"
+ipa\-smartproxy.conf \- IPA Smartproxy server configuration file
+.SH "SYNOPSIS"
+/etc/ipa/ipa\-smartproxy.conf
+.SH "DESCRIPTION"
+The \fIipa\-smartproxy.conf \fRconfiguration file is used to set system\-wide defaults to be applied when running the IPA Foreman Smartproxy server.
+.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.
+
+The value is a Python object so needs to adhere to Python rules. If the value should be an integer then it needs to be passed as an integer (like port). If the value is a string then it must be quoted.
+
+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 the IPA Foreman Smartproxy server. Be careful of misspellings, they will not be rejected.
+.SH "OPTIONS"
+The server runs using the CherryPy so all the CherryPy configuration options are valid. Here are some common ones.
+
+.TP
+.B server.socket_port\fR <port>
+Port for the server to listen on. The default port is 8090.
+.TP
+.B server.socket_host\fR <host>
+If not specified then the server will listen on localhost. This is the expected mode. Specifiy a hostname or IP address to listen on another address. See also the .B local_only\fR option if setting this to something other than a local address.
+.B request.show_tracebacks\fR <boolean>
+Display tracebacks to the client when errors occur. Errors will always log on the server side. The default is False.
+.TP
+.B local_only\fR <boolean>
+If True then requires that all requests be local. It is not recommended that this be enabled because this server accepts unathenticated requests to manage IPA entries.
+.TP
+.B remove_dns\fR <boolean>
+Remove DNS entries when deleting a host
+.SH "FILES"
+.TP
+.I /etc/ipa/ipa\-smartproxy.conf
+IPA Foreman Smartproxy server configuration file
+.SH "SEE ALSO"
+.BR ipa\-smartproxy (1)