.\" 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)