File: krb5-sync.8

package info (click to toggle)
krb5-sync 3.0-4
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 2,488 kB
  • ctags: 731
  • sloc: sh: 11,822; ansic: 6,413; perl: 636; makefile: 129
file content (304 lines) | stat: -rw-r--r-- 10,590 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "KRB5-SYNC 8"
.TH KRB5-SYNC 8 "2013-12-09" "3.0" "krb5-sync"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
krb5\-sync \- Synchronize passwords and status with Active Directory
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBkrb5\-sync\fR [\fB\-d\fR | \fB\-e\fR] [\fB\-p\fR \fIpassword\fR] \fIuser\fR
.PP
\&\fBkrb5\-sync\fR \fB\-f\fR \fIfile\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBkrb5\-sync\fR provides a command-line interface to the same functions
provided by the password and status synchronization plugin.  It can push a
new password to Active Directory (actually, to any password store that
supports the Kerberos set-password protocol) or activate or deactivate an
account in Active Directory.
.PP
To synchronize passwords, provide the \fB\-p\fR option and specify the
password.  Note that the password is given on the command line and must be
quoted if it contains special characters, and the password will be exposed
to any other users on the system where this command is run.  This is
useful primarily for testing and should not be used with production
passwords.  Synchronization to Active Directory will be attempted based on
the configuration in \fIkrb5.conf\fR (see below).
.PP
To enable or disable an account, provide the \fB\-e\fR or \fB\-d\fR option
respectively.  These options can also be provided in conjunction with the
\&\fB\-p\fR option to take both actions at once.
.PP
In either case, \fIuser\fR should be the principal name for which these
actions should be taken.  \fIuser\fR may be either unqualified or in the
local realm; either way, the Active Directory realm in which to make
changes will be taken from the \fIkrb5.conf\fR configuration.
.PP
Alternately, \fBkrb5\-sync\fR also supports processing actions from a file.
To do this, use the \fB\-f\fR flag and give the file on the command line.  The
format of the file should be as follows:
.PP
.Vb 4
\&    <account>
\&    ad
\&    password | enable | disable
\&    <password>
.Ve
.PP
where the fourth line is present only if the <action> is \f(CW\*(C`password\*(C'\fR.
<account> should be the unqualified name of the account.  The second line
should be the string \f(CW\*(C`ad\*(C'\fR to push the change to Windows Active Directory.
The third line should be one of \f(CW\*(C`password\*(C'\fR, \f(CW\*(C`enable\*(C'\fR, or \f(CW\*(C`disable\*(C'\fR,
corresponding to the \fB\-p\fR, \fB\-e\fR, and \fB\-d\fR options respectively.  The
\&\f(CW\*(C`enable\*(C'\fR and \f(CW\*(C`disable\*(C'\fR actions are only supported for \s-1AD.\s0
.PP
The file format is not particularly forgiving.  In particular, all of the
keywords are case-sensitive and there must not be any whitespace at the
beginning or end of the lines (except in the password, and only if that
whitespace is part of the password), just a single newline terminating
each line.
.PP
When the \fB\-f\fR option is given, the file will be deleted if the action was
successful but left alone if the action failed.
.PP
The configuration block in \fIkrb5.conf\fR should look something like this:
.PP
.Vb 7
\&    krb5\-sync = {
\&        ad_keytab       = /etc/krb5kdc/ad\-keytab
\&        ad_principal    = service/sync@WINDOWS.EXAMPLE.COM
\&        ad_realm        = WINDOWS.EXAMPLE.COM
\&        ad_admin_server = dc1.windows.example.com
\&        ad_ldap_base    = ou=People
\&    }
.Ve
.PP
If the configuration required for an action is not given, that action will
not be performed but will apparently succeed from the perspective of the
\&\fBkrb5\-sync\fR utility.  Therefore, if this utility reports success but no
change is happening, double-check the configuration to ensure that all
required options are present.
.PP
The \f(CW\*(C`ad_keytab\*(C'\fR option specifies the location of a keytab for
authenticating to the other realm, the \f(CW\*(C`ad_principal\*(C'\fR option specifies
the principal to authenticate as (using the key in the keytab), and the
\&\f(CW\*(C`ad_realm\*(C'\fR option specifies the foreign realm.  \f(CW\*(C`ad_admin_server\*(C'\fR is the
host to contact via \s-1LDAP\s0 to push account status changes.  \f(CW\*(C`ad_ldap_base\*(C'\fR
specifies the base tree inside Active Directory where account information
is stored.  Omit the trailing \f(CW\*(C`dc=\*(C'\fR part; it will be added automatically
from \f(CW\*(C`ad_realm\*(C'\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-d\fR" 4
.IX Item "-d"
Disable the specified user in Active Directory.  Requires that all of the
ad_* options be set in \fIkrb5.conf\fR.  This option may not be specified at
the same time as \fB\-e\fR.
.IP "\fB\-e\fR" 4
.IX Item "-e"
Enable the specified user in Active Directory.  Requires that all of the
ad_* options be set in \fIkrb5.conf\fR.  This option may not be specified at
the same time as \fB\-e\fR.
.IP "\fB\-f\fR \fIfile\fR" 4
.IX Item "-f file"
Rather than perform a particular action based on a username given on the
command line, read a queue file and take action based on it.  The format
of the queue file is described above.  If the action fails, the file will
be left alone.  If the action succeeds, the file will be deleted.
.IP "\fB\-p\fR \fIpassword\fR" 4
.IX Item "-p password"
Change the user's password to \fIpassword\fR in Active Directory.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Disable the account \*(L"jdoe\*(R" in Active Directory (using the \s-1AD\s0 configuration
found in \fIkrb5.conf\fR):
.PP
.Vb 1
\&    krb5\-sync \-d jdoe
.Ve
.PP
Change the password of the account \f(CW\*(C`testuser\*(C'\fR in Active Directory to
\&\f(CW\*(C`changeme\*(C'\fR:
.PP
.Vb 1
\&    krb5\-sync \-p changeme testuser@EXAMPLE.COM
.Ve
.PP
The same, except also enable the account in Active Directory:
.PP
.Vb 1
\&    krb5\-sync \-e \-p changeme testuser
.Ve
.PP
Note that the realm for the user given on the command line is optional and
ignored.
.PP
Given a file named \fIjdoe\-ad\-1168560492\fR containing:
.PP
.Vb 4
\&    jdoe
\&    ad
\&    password
\&    changeme
.Ve
.PP
the command:
.PP
.Vb 1
\&    krb5\-sync \-f jdoe\-ad\-1168560492
.Ve
.PP
will change jdoe's password to \f(CW\*(C`changeme\*(C'\fR in Active Directory and then
delete the file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The current version of this program is available from its web page at
<http://www.eyrie.org/~eagle/software/krb5\-sync/>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Russ Allbery <eagle@eyrie.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2007, 2008, 2010, 2012 The Board of Trustees of the Leland
Stanford Junior University
.PP
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and
this notice are preserved.  This file is offered as-is, without any
warranty.