← Back to branch summary

~ubuntu-branches/ubuntu/saucy/openvpn/saucy-proposed

« back to all changes in this revision

Viewing changes to src/plugins/auth-pam/README.auth-pam

  • Committer: Package Import Robot
  • Author(s): Stéphane Graber
  • Date: 2013-05-24 17:42:45 UTC
  • mfrom: (1.1.19) (10.2.22 sid)
  • Revision ID: package-import@ubuntu.com-20130524174245-g9y6wlforycufqy5
Tags: 2.3.1-2ubuntu1
* Merge from Debian unstable. Remaining changes:
  - debian/openvpn.init.d:
    + Do not use start-stop-daemon and </dev/null to avoid blocking boot.
    + Show per-VPN result messages.
    + Add "--script-security 2" by default for backwards compatabliity.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/plugins/auth-pam/README.auth-pam
 
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" "COMMONNAME" 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.