..
.. NB:  This file is machine generated, DO NOT EDIT!
..
.. Edit vmod.vcc and run make instead
..

.. role:: ref(emphasis)

.. _vmod_unix(3):

=========
vmod_unix
=========

---------------------------------
utilities for Unix domain sockets
---------------------------------

:Manual section: 3

SYNOPSIS
========


::

   import unix [from "path"] ;
   
   STRING user()
  
   STRING group()
  
   INT uid()
  
   INT gid()
  




CONTENTS
========

* :ref:`func_gid`
* :ref:`func_group`
* :ref:`func_uid`
* :ref:`func_user`



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

This VMOD provides information about the credentials of the peer
process (user and group of the process owner) that is connected to a
Varnish 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 Varnish 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.


.. _func_user:

STRING user()
-------------

Return the user name of the peer process owner.


.. _func_group:

STRING group()
--------------

Return the group name of the peer process owner.


.. _func_uid:

INT uid()
---------

Return the numeric user id of the peer process owner.


.. _func_gid:

INT gid()
---------

Return the numeric group id of the peer process owner.

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 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 (``vmod_user`` and
  ``vmod_group``) return NULL, while the INT functions (``vmod_uid``
  and ``vmod_gid``) return -1.

SEE ALSO
========

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


COPYRIGHT
=========

::

  This document is licensed under the same conditions as Varnish itself.
  See LICENSE for details.
 
  Authors: Geoffrey Simmons <geoffrey.simmons@uplex.de>