branch master updated (5a71476 -> 21ee5cc)

[git repository hosting]

This is an automated email from the git hooks/post-receive script.

rharwood pushed a change to branch master
in repository gssproxy.

      from  5a71476   Always choose highest requested debug level
       new  de179f7   Add docs link to README.md
       new  966e056   Add generic service README
       new  21ee5cc   Rename README.style -> STYLE.txt so pagure stops picking it up

The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "adds" were already present in the repository and have only
been added to this reference.


Summary of changes:
 README.md                 |   3 +
 README.style => STYLE.txt |   0
 docs/README.md            | 152 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 155 insertions(+)
 rename README.style => STYLE.txt (100%)
 create mode 100644 docs/README.md

-- 
To stop receiving notification emails like this one, please contact
the administrator of this repository.

01/03: Add docs link to README.md

[git repository hosting]

This is an automated email from the git hooks/post-receive script.

rharwood pushed a commit to branch master
in repository gssproxy.

commit de179f70c0452b00fbcfe0fcc45cf689df3f5cd2
Author: Robbie Harwood <rharwood(a)redhat.com&gt;
Date:   Tue May 8 11:01:39 2018 -0400

    Add docs link to README.md
    
    Signed-off-by: Robbie Harwood <rharwood(a)redhat.com&gt;
    Reviewed-by: Simo Sorce <simo(a)redhat.com&gt;
    Merges: #230
---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index 98d749c..20c3ce4 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,8 @@
 This is the gss-proxy project.
 
+Documentation lives in the [docs folder of this
+repository](https://pagure.io/gssproxy/blob/master/f/docs).
+
 The goal is to have a GSS-API proxy, with standardizable protocol and a
 (somewhat portable) reference client and server implementation.  There
 are several motivations for this some of which are:

-- 
To stop receiving notification emails like this one, please contact
the administrator of this repository.

02/03: Add generic service README

[git repository hosting]

This is an automated email from the git hooks/post-receive script.

rharwood pushed a commit to branch master
in repository gssproxy.

commit 966e056644bde5f1ead4c1d74a1204262aaa6516
Author: Robbie Harwood <rharwood(a)redhat.com&gt;
Date:   Tue May 8 13:35:47 2018 -0400

    Add generic service README
    
    Signed-off-by: Robbie Harwood <rharwood(a)redhat.com&gt;
    Reviewed-by: Simo Sorce <simo(a)redhat.com&gt;
    Reviewed-by: Alexander Scheel <ascheel(a)redhat.com&gt;
    Merges: #230
---
 docs/README.md | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..63471b2
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,152 @@
+# Getting started with gssproxy
+
+In this folder is detailed documentation on how gssproxy works internally
+(Behavior, ProtocolDocumentation) as well as configuration walkthroughs for
+specific services (Apache, NFS) and information on our releases
+(ReleaseProcess, Releases).
+
+This document attempts to cover how to use gssproxy with any simple,
+well-behaved service, and explain in broad strokes what each step
+accomplishes.  All commands should be run as root.
+
+## Background
+
+The GSSAPI (Generic Security Services API) is a RFC-standardized interface for
+applications that wish to use security libraries.  Most commonly, GSSAPI is
+used as an interface to Kerberos, though there are other mechanisms provided
+as well (e.g., SPNEGO for Single-Sign On on the web; see the Apache docs in
+this folder for more information on that).
+
+When an application uses GSSAPI, typically it will have direct access to its
+security credentials, and all cryptographic operations are performed in the
+application's process.  This is undesirable, but fortunately gssproxy can help
+in almost all use cases!  gssproxy provides privilege separation to
+applications using the GSSAPI: the gssproxy daemon runs on the system, holds
+the application's credentials, and performs operations on behalf of the
+application.
+
+This is completely transparent to the application.  However, some
+configuration is required, which we'll now go through.
+
+## Configuring gssproxy
+
+(For a detailed explanation of any of the options described in this section,
+see the man page for gssproxy.conf (`man 5 gssproxy.conf`).)
+
+gssproxy configuration typically lives in **/etc/gssproxy**.  On most systems,
+this directory will already contain a couple files, which can usually be
+ignored (but will be explained briefly anyway).
+
+- **gssproxy.conf** is the main gssproxy configuration file: options affecting
+  operation of the daemon itself live here (e.g., logging levels).
+  
+- **##-servicename.conf** are the service configuration files (where "##" is a
+  two-digit number; the files are loaded in numeric order by gssproxy).
+  
+We will be making one of the latter file for your application.  Pick a useful
+name for your service - it will be used in log files.
+
+gssproxy configuration snippets are INI-style, so start with a service header:
+`[service/my_app]`.
+
+Then set the mechanisms we wish to allow: `mechs = krb5`.
+
+If the application has any keytabs, tell gssproxy about them: `cred_store =
+keytab:/etc/path/to.keytab`.  Then change the user and group permissions on
+the keytab so that the application can't read them (but gssproxy can): `chown
+root:root /etc/path/to.keytab`.
+
+The next step is to figure out what sets your application apart from others
+that may be running on the system.  gssproxy requires specifying a uid (`euid
+= appuser`), but if it runs as root, that may not be enough.
+
+Fortunately, gssproxy also allows executable name matching.  This checks the
+canonical, full path to an executable.  Your program must be a native ELF (or
+similar) - it cannot be an interpreted program (as that would allow all
+programs running under the interpreter to access gssproxy as if they were
+yours).  This field is therefore optional.
+
+(If that's still not enough to distinguish your application, don't worry -
+just see the later section on using a custom socket.)
+
+In the end, we would end up with a config file that looks a bit like this:
+
+```INI
+[service/my_app]
+    mechs = krb5
+    cred_store = keytab:/etc/path/to.keytab
+    euid = appuser
+    program = /usr/local/bin/my_app
+```
+
+And tell gssproxy to use the new configuration file: `systemctl
+try-reload-or-restart gssproxy`
+
+## Configuring the application
+
+In order for the application to attempt to use gssproxy, it needs an
+environment variable set: `GSS_USE_PROXY=yes`.  (For more information on
+environment variable configuration, see the man page for gssproxy-mech - `man
+8 gssproxy-mech`.)
+
+How this is configured will of course vary application to application.
+
+If launching by hand from a shell, just prepend it to the invocation:
+`GSS_USE_PROXY=yes my_app`.
+
+If launching using sysvinit, you'll probably need to edit the invocation in
+**/etc/init.d/my_app** (there may be a nicer way, but it's system-dependent).
+
+If launching using systemd (these instructions assume Fedora), create a new
+file at **/etc/systemd/system/my_app.service** and make it look like this:
+
+```INI
+.include /lib/systemd/system/my_app.service
+[Service]
+Environment=GSS_USE_PROXY=1
+```
+
+and then reload the systemd state: `systemctl daemon-reload`.
+
+From there, (re)start your application and you're off to the races!
+
+## Aside: using a custom socket
+
+Normally, gssproxy traffic all runs over the same socket, which typically
+lives in **/var/lib/gssproxy/default.sock**.  However, gssproxy can listen on
+many sockets, and can distinguish services this way.  Using a custom socket
+for your service is a two part configuration: configure the client, and
+configure gssproxy.
+
+To configure gssproxy, we need to tell the daemon to open another socket.
+Pick a path (**/var/lib/gssproxy/my_app.sock** is good) and modify the service
+configuration to use it: `socket = /var/lib/gssproxy/my_app.sock`.  Then
+reload gssproxy's configuration: `systemctl try-reload-or-restart gssproxy`.
+
+To configure the client, we need to set another environment variable:
+`GSSPROXY_SOCKET`.  So, we set that in the same way we set `GSS_USE_PROXY`
+(i.e., `GSSPROXY_SOCKET=/var/lib/gssproxy/my_app.sock`), and launch.
+
+## How to know it's working
+
+By far the easiest way to tell is to have a configuration working *without*
+gssproxy, and then migrate to one *with* gssproxy.  If the environment
+variable is set in the process, and everything keeps working, then you know
+everything is all set.
+
+A similar thing is true of the keytabs: if the application can't read them,
+but continues to function, then everything is working correctly.
+
+That's not always possible, though.  In that case, you can look at gssproxy's
+logs to see connections from your service.  First, set `debug_level = 1` in
+**/etc/gssproxy/gssproxy.conf**, and then have gssproxy reload its
+configuration (`systemctl reload gssproxy`).  Then, in the gssproxy logs (for
+systemd, this is `journalctl -xfu gssproxy`), you should see lines like:
+
+    may 08 12:48:52 freeipa.rharwood.biz gssproxy[27144]: [CID 13][2018/05/08 16:48:52]:
gp_rpc_execute: executing 6 (GSSX_ACQUIRE_CRED) for service "ipa-httpd", euid:
48,socket: (null)
+
+This happens to be taken from a user connecting to the webui on a freeipa
+instance.  It was preceeded at some point by a line announcing the conection.
+This line says that it's executing a call to (something like)
+`gss_acquire_cred()` on behalf of the "ipa-httpd" configured service, which is
+uid 48 (i.e., apache), and that it's assigned ID 13 to this session.

-- 
To stop receiving notification emails like this one, please contact
the administrator of this repository.

03/03: Rename README.style -> STYLE.txt so pagure stops picking it up

[git repository hosting]

This is an automated email from the git hooks/post-receive script.

rharwood pushed a commit to branch master
in repository gssproxy.

commit 21ee5ccf5826f33fb824f343d063dd68aeb6379c
Author: Robbie Harwood <rharwood(a)redhat.com&gt;
Date:   Tue May 8 13:50:43 2018 -0400

    Rename README.style -> STYLE.txt so pagure stops picking it up
    
    Signed-off-by: Robbie Harwood <rharwood(a)redhat.com&gt;
    Reviewed-by: Simo Sorce <simo(a)redhat.com&gt;
    Merges: #230
---
 README.style => STYLE.txt | 0
 1 file changed, 0 insertions(+), 0 deletions(-)

diff --git a/README.style b/STYLE.txt
similarity index 100%
rename from README.style
rename to STYLE.txt

-- 
To stop receiving notification emails like this one, please contact
the administrator of this repository.