---
name: "pure-authd"
section: "8"
platform: "linux"
package: "pure-ftpd-common"
version: "1.0.50-2.2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pure-authd"
---

# pure-authd(8)

External authentication agent for Pure-FTPd.

## NAME

pure-authd - External authentication agent for Pure-FTPd.

## SYNTAX

pure-authd \[*-p* \<*/path/to/pidfile*\>\] \[*-u* uid\] \[*-g* gid\] \[*-B*\] \<*-s* /path/to/socket\> *-r* /program/to/run

## DESCRIPTION

pure-authd is a daemon that forks an authentication program, waits for an authentication reply, and feed them to an application server.

pure-authd listens to a local Unix socket. A new connection to that socket should feed pure-authd the following structure:

-

  account:xxx

  password:xxx

  localhost:xxx

  localport:xxx

  peer:xxx

  end

(replace xxx with appropriate values) . localhost, localport and peer are numeric IP addresses and ports. peer is the IP address of the remote client.

These arguments are passed to the authentication program, as environment variables:

-

  AUTHD\_ACCOUNT

  AUTHD\_PASSWORD

  AUTHD\_LOCAL\_IP

  AUTHD\_LOCAL\_PORT

  AUTHD\_REMOTE\_IP

  AUTHD\_ENCRYPTED

The authentication program should take appropriate actions to fetch account info according to these arguments, and reply to the standard output a structure like the following one:

-

  auth\_ok:1

  uid:42

  gid:21

  dir:/home/j

  end

- **auth\_ok:**xxx

  If xxx is 0, the user was not found (the next authentication method passed to pure-ftpd will be tried) . If xxx is -1, the user was found, but there was a fatal authentication error: user is root, password is wrong, account has expired, etc (next authentication methods will not be tried) . If xxx is 1, the user was found and successfully authenticated.

- **uid:**xxx

  The system uid to be assigned to that user. Must be \> 0.

- **gid:**xxx

  The primary system gid. Must be \> 0.

- **dir:**xxx

  The absolute path to the home directory. Can contain /./ for a chroot jail.

- **slow\_tilde\_expansion:**xxx *(optional, default is 1)*

  When the command 'cd ~user' is issued, it's handy to go to that user's home directory, as expected in a shell environment. But fetching account info can be an expensive operation for non-system accounts. If xxx is 0, 'cd ~user' will expand to the system user home directory. If xxx is 1, 'cd ~user' won't expand. You should use 1 in most cases with external authentication, when your FTP users don't match system users. You can also set xxx to 1 if you're using slow nss\_\* system authentication modules.

- **throttling\_bandwidth\_ul:**xxx *(optional)*

  The allocated bandwidth for uploads, in bytes per second.

- **throttling\_bandwidth\_dl:**xxx *(optional)*

  The allocated bandwidth for downloads, in bytes per second.

- **user\_quota\_size:**xxx *(optional)*

  The maximal total size for this account, in bytes.

- **user\_quota\_files:**xxx *(optional)*

  The maximal number of files for this account.

- **ratio\_upload:**xxx *(optional)*

  - **radio\_download:**xxx *(optional)*

  The user must match a ratio\_upload:ratio\_download ratio.

*Only one authentication program is forked at a time. It must return quickly.*

## OPTIONS

- **-u** \<*uid*\>

  Have the daemon run with that uid.

- **-g** \<*gid*\>

  Have the daemon run with that gid.

- **-B**

  Fork in background (daemonization).

- **-s** \<*/path/to/socket*\>

  Set the full path to the local Unix socket.

- **-r** \<*/path/to/program*\>

  Set the full path to the authentication program.

- **-h**

  Output help information and exit.

## EXAMPLES

To run this program the standard way type:

pure-authd -s /var/run/ftpd.sock -r /usr/bin/my-auth-program &

pure-ftpd -lextauth:/var/run/ftpd.sock &

- /usr/bin/my-auth-program can be as simple as:

  \#! /bin/sh

  echo 'auth\_ok:1'

  echo 'uid:42'

  echo 'gid:21'

  echo 'dir:/home/j'

  echo 'end'

## AUTHORS

Frank DENIS \<j at pureftpd dot org\>

## SEE ALSO

**[ftp(1)](/ftp/1.md)**, **[pure-ftpd(8)](/pure-ftpd/8.md)** **[pure-ftpwho(8)](/pure-ftpwho/8.md)** **[pure-mrtginfo(8)](/pure-mrtginfo/8.md)** **[pure-uploadscript(8)](/pure-uploadscript/8.md)** **[pure-statsdecode(8)](/pure-statsdecode/8.md)** **[pure-pw(8)](/pure-pw/8.md)** **[pure-quotacheck(8)](/pure-quotacheck/8.md)** **[pure-authd(8)](/pure-authd/8.md)** **[pure-certd(8)](/pure-certd/8.md)**

**RFC 959**, **RFC 2389**, **RFC 2228** and **RFC 2428**.