---
name: "vmod_unix"
section: "3"
platform: "linux"
package: "vinyl-cache"
version: "9.1.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/vmod_unix"
---

# vmod\_unix(3)

Utilities for Unix domain sockets

## Name

vmod\_unix - Utilities for Unix domain sockets

## SYNOPSIS

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

## 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)](/getpeereid/3.md)* (such as FreeBSD and other BSD-derived systems)

- •

  the socket option **SO\_PEERCRED** for *[getsockopt(2)](/getsockopt/2.md)* (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.

### STRING user()

Return the user name of the peer process owner.

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

### STRING group()

Return the group name of the peer process owner.

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

### INT uid()

Return the numeric user id of the peer process owner.

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

### INT gid()

Return the numeric group id of the peer process owner.

Restricted to: **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

- •

  *[vinyld(1)](/vinyld/1.md)*

- •

  *[vcl(7)](/vcl/7.md)*

- •

  *[getpeereid(3)](/getpeereid/3.md)*

- •

  *[getsockopt(2)](/getsockopt/2.md)*

- •

  *getpeerucred(3C)*

- •

  *setppriv(2)*

## COPYRIGHT

```
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>
```