vmod\_unix(3) Library Functions Manual vmod\_unix(3)

# [Name](#Name)

vmod\_unix - Utilities for Unix domain sockets

# [SYNOPSIS](#SYNOPSIS)

```
import unix [as name] [from "path"]
STRING user()
STRING group()
INT uid()
INT gid()
```

# [DESCRIPTION](#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 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)*](/man/os/varnish/getpeereid.3) (such as FreeBSD and other BSD-derived systems)
- the socket option **SO\_PEERCRED** for [*getsockopt(2)*](/man/os/varnish/getsockopt.2) (Linux)
- [*getpeerucred(3C)*](/man/os/varnish/getpeerucred.3C) (SunOS and descendants)

On SunOS and friends, the **PRIV\_PROC\_INFO** privilege set is added to the *varnishd* child process while the VMOD is loaded, see [*setppriv(2)*](/man/os/varnish/setppriv.2).

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

## [STRING user()](#STRING_user%28%29)

Return the user name of the peer process owner.

Restricted to: **client**, **backend**.

## [STRING group()](#STRING_group%28%29)

Return the group name of the peer process owner.

Restricted to: **client**, **backend**.

## [INT uid()](#INT_uid%28%29)

Return the numeric user id of the peer process owner.

Restricted to: **client**, **backend**.

## [INT gid()](#INT_gid%28%29)

Return the numeric group id of the peer process owner.

Restricted to: **client**, **backend**.

# [ERRORS](#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](#SEE_ALSO)

- [*varnishd(1)*](/man/os/varnish/varnishd.1)
- [*vcl(7)*](/man/os/varnish/vcl.7)
- [*getpeereid(3)*](/man/os/varnish/getpeereid.3)
- [*getsockopt(2)*](/man/os/varnish/getsockopt.2)
- [*getpeerucred(3C)*](/man/os/varnish/getpeerucred.3C)
- [*setppriv(2)*](/man/os/varnish/setppriv.2)

# [COPYRIGHT](#COPYRIGHT)

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

---

Document: vmod_unix(3) from varnish 9.1.0-r3 (Chainguard OS)
Source: https://github.com/varnish/varnish