#-
# This document is licensed under the same conditions as Vinyl Cache itself.
# See LICENSE for details.
#
# SPDX-License-Identifier: BSD-2-Clause
#
# Authors: Geoffrey Simmons <geoffrey.simmons@uplex.de>
#

$ABI strict
$Module unix 3 "Utilities for Unix domain sockets"

DESCRIPTION
===========

This VMOD provides information about the credentials of the peer
process (user and group of the process owner) that is connected to a
Vinyl Cache listener via a Unix domain socket, if the platform supports
it.

Examples::

  import unix;

  sub vcl_recv {
	# Return "403 Forbidden" if the connected peer is
	# not running as the user "trusteduser".
	if (unix.user() != "trusteduser") {
		return( synth(403) );
	}

	# Require the connected peer to run in the group
	# "trustedgroup".
	if (unix.group() != "trustedgroup") {
		return( synth(403) );
	}

	# Require the connected peer to run under a specific numeric
	# user id.
	if (unix.uid() != 4711) {
		return( synth(403) );
	}

	# Require the connected peer to run under a numeric group id.
	if (unix.gid() != 815) {
		return( synth(403) );
	}
  }

Obtaining the peer credentials is possible on a platform that supports
one of the following:

* `getpeereid(3)` (such as FreeBSD and other BSD-derived systems)

* the socket option ``SO_PEERCRED`` for `getsockopt(2)` (Linux)

* `getpeerucred(3C)` (SunOS and descendants)

On SunOS and friends, the ``PRIV_PROC_INFO`` privilege set is added to
the `vinyld` child process while the VMOD is loaded, see
`setppriv(2)`.

On most platforms, the value returned is the effective user or group
that was valid when the peer process initiated the connection.

$Function STRING user()

Return the user name of the peer process owner.

$Restrict client backend

$Function STRING group()

Return the group name of the peer process owner.

$Restrict client backend

$Function INT uid()

Return the numeric user id of the peer process owner.

$Restrict client backend

$Function INT gid()

Return the numeric group id of the peer process owner.

$Restrict client backend

ERRORS
======

All functions in this VMOD are subject to the following constraints:

* None of them may be called in ``vcl_init{}`` or ``vcl_fini{}``. If
  one of them is called in ``vcl_init{}``, then the VCL program will
  fail to load, with an error message from the VMOD.

* If called on a platform that is not supported, then VCL failure is
  invoked. An error message is written to the log (with the
  ``VCL_Error`` tag), and for all VCL subroutines except for
  ``vcl_synth{}``, control is directed immediately to ``vcl_synth{}``,
  with the response status set to 503 and the reason string set to
  "VCL failed".

  If the failure occurs during ``vcl_synth{}``, then ``vcl_synth{}``
  is aborted, and the response line "503 VCL failed" is sent.

* If the current listener is not a Unix domain socket, or if the
  attempt to read credentials fails, then a ``VCL_Error`` message is
  written to the log. The STRING functions (`unix.user()`_ and
  `unix.group()`_) return ``NULL``, while the INT functions
  (`unix.uid()`_ and `unix.gid()`_) return -1.

SEE ALSO
========

* :ref:`vinyld(1)`
* :ref:`vcl(7)`
* `getpeereid(3)`
* `getsockopt(2)`
* `getpeerucred(3C)`
* `setppriv(2)`
