VMOD_UNIX(3)

💖 VMOD_UNIX 💖

okay bestie, we're in the Library Functions Manual and this one is vmod_unix — 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 🫶

So basically, this VMOD hands you the credentials of the peer process — like, the user and the group of whoever owns the process — that's connected to a Varnish listener over a Unix domain socket. That's it, that's the vibe. But only if the platform supports it, bestie. No cap. 🙈

Examples, because we love a demo:

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) );
      }
}

Getting the peer credentials is a whole thing that's only possible on a platform that supports one of these, periodt:

• getpeereid(3) — like on FreeBSD and other BSD-derived systems 🍓
• the socket option SO_PEERCRED for getsockopt(2) — that's the Linux girlies 💅
• getpeerucred(3C) — SunOS and its descendants ☀️

On SunOS and friends, the PRIV_PROC_INFO privilege set gets added to the Varnish child process while the VMOD is loaded — see setppriv(2). iconic behaviour honestly 👑

On most platforms, what you get back is the effective user or group that was valid back when the peer process initiated the connection. iykyk

---

🌈 STRING user()

Returns the user name of the peer process owner. 🎀

Restricted to: client, backend.

---

🧚 STRING group()

Returns the group name of the peer process owner. 💜

Restricted to: client, backend.

---

⭐ INT uid()

Returns the numeric user id of the peer process owner. 🔥

Restricted to: client, backend.

---

🌸 INT gid()

Returns the numeric group id of the peer process owner. 🦋

Restricted to: client, backend.

---

💀 ERRORS 💀

Every single function in this VMOD has to live by these rules, no exceptions bestie:

• 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 fails to load, with an error message from the VMOD. not the moment, truly 😭
• If it's called on a platform that isn't supported, then VCL failure is invoked. An error message gets 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 happens during vcl_synth{}, then vcl_synth{} is aborted, and the response line "503 VCL failed" is sent. rip 🫠

• 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 👀

• varnishd(1)
• 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.

SPDX-License-Identifier: BSD-2-Clause

Authors: Geoffrey Simmons <geoffrey.simmons@uplex.de>

---

and that's the whole page, bestie 💖 this was VMOD_UNIX(3) from the Library Functions Manual — go off, you understood all of it, main character energy fr fr ✨🎀🦋