openvpn/plugin/auth-pam/README

   1 openvpn-auth-pam
   2
   3 SYNOPSIS
   4
   5 The openvpn-auth-pam module implements username/password
   6 authentication via PAM, and essentially allows any authentication
   7 method supported by PAM (such as LDAP, RADIUS, or Linux Shadow
   8 passwords) to be used with OpenVPN.  While PAM supports
   9 username/password authentication, this can be combined with X509
  10 certificates to provide two indepedent levels of authentication.
  11
  12 This module uses a split privilege execution model which will
  13 function even if you drop openvpn daemon privileges using the user,
  14 group, or chroot directives.
  15
  16 BUILD
  17
  18 To build openvpn-auth-pam, you will need to have the pam-devel
  19 package installed.
  20
  21 Build with the "make" command.  The module will be named
  22 openvpn-auth-pam.so
  23
  24 USAGE
  25
  26 To use this plugin module, add to your OpenVPN config file:
  27
  28   plugin openvpn-auth-pam.so service-type
  29
  30 The required service-type parameter corresponds to
  31 the PAM service definition file usually found
  32 in /etc/pam.d.
  33
  34 This plugin also supports the usage of a list of name/value
  35 pairs to answer PAM module queries.
  36
  37 For example:
  38
  39   plugin openvpn-auth-pam.so "login login USERNAME password PASSWORD"
  40
  41 tells auth-pam to (a) use the "login" PAM module, (b) answer a
  42 "login" query with the username given by the OpenVPN client, and
  43 (c) answer a "password" query with the password given by the
  44 OpenVPN client.  This provides flexibility in dealing with the different
  45 types of query strings which different PAM modules might generate.
  46 For example, suppose you were using a PAM module called
  47 "test" which queried for "name" rather than "login":
  48
  49   plugin openvpn-auth-pam.so "test name USERNAME password PASSWORD"
  50
  51 While "USERNAME" and "PASSWORD" are special strings which substitute
  52 to client-supplied values, it is also possible to name literal values
  53 to use as PAM module query responses.  For example, suppose that the
  54 login module queried for a third parameter, "domain" which
  55 is to be answered with the constant value "mydomain.com":
  56
  57   plugin openvpn-auth-pam.so "login login USERNAME password PASSWORD domain mydomain.com"
  58
  59 The following OpenVPN directives can also influence
  60 the operation of this plugin:
  61
  62   client-cert-not-required
  63   username-as-common-name
  64
  65 Run OpenVPN with --verb 7 or higher to get debugging output from
  66 this plugin, including the list of queries presented by the
  67 underlying PAM module.  This is a useful debugging tool to figure
  68 out which queries a given PAM module is making, so that you can
  69 craft the appropriate plugin directive to answer it.
  70
  71 CAVEATS
  72
  73 This module will only work on *nix systems which support PAM,
  74 not Windows.