summaryrefslogtreecommitdiff
path: root/debian/mongokerberos.1
blob: 75165b963c6edd78cc7f32805dc18204fd261d5b (plain)
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
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
.\" Man page generated from reStructuredText.
.
.TH "MONGOKERBEROS" "1" "Jun 23, 2020" "4.4" "mongodb-manual"
.SH NAME
mongokerberos \- MongoDB Kerberos Validation Utility
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SS On this page
.INDENT 0.0
.IP \(bu 2
\fI\%Synopsis\fP
.IP \(bu 2
\fI\%Installation\fP
.IP \(bu 2
\fI\%Usage\fP
.IP \(bu 2
\fI\%Options\fP
.UNINDENT
.sp
New in version 4.4: MongoDB Enterprise

.SH SYNOPSIS
.sp
Starting in version 4.4, MongoDB Enterprise provides
\fI\%mongokerberos\fP for testing MongoDB\(aqs Kerberos and GSSAPI
configuration options against a
running Kerberos deployment. \fI\%mongokerberos\fP can be used
in one of two modes: \fIserver\fP and \fIclient\fP\&.
.TS
center;
|l|l|.
_
T{
Mode
T}	T{
Description
T}
_
T{
Server
T}	T{
In \fIserver mode\fP, \fI\%mongokerberos\fP analyzes
Kerberos\-related configurations on the server, and returns a
report which includes error messages for any configurations that
are problematic. For usage, see \fI\%Server Mode\fP
T}
_
T{
Client
T}	T{
In \fIclient mode\fP, \fI\%mongokerberos\fP tests Kerberos
authentication for a provided username, and returns a report
which includes the success or failure of each step in the
Kerberos authentication procedure. For usage, see
\fI\%Client Mode\fP
T}
_
.TE
.sp
Error messages for both modes include information on specific errors
encountered and potential advice for resolving the error.
.sp
\fI\%mongokerberos\fP supports the following deployment types,
in both server and client modes:
.INDENT 0.0
.IP \(bu 2
Linux MongoDB clients authenticating to MIT Kerberos deployments on
supported Linux platforms\&.
.IP \(bu 2
Windows MongoDB clients authenticating to Windows Active Directory
deployments on
supported Windows platforms\&.
.IP \(bu 2
Linux MongoDB clients authenticating to Windows Active Directory
deployments.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
MongoDB Enterprise and \fI\%mongokerberos\fP only support the
\fI\%MIT implementation\fP
of Kerberos.
.UNINDENT
.UNINDENT
.sp
Generally, when configuring options related to
Kerberos authentication, it is good practice
to verify your configuration with \fI\%mongokerberos\fP\&.
.sp
\fI\%mongokerberos\fP is a testing and verification tool; it does not
edit any files or configure any services. For configuring Kerberos on
your platform please consult the \fI\%MIT Kerberos documentation\fP, or your platform\(aqs
documentation. For configuring MongoDB to authenticate using Kerberos,
please reference the following tutorials:
.INDENT 0.0
.IP \(bu 2
/tutorial/control\-access\-to\-mongodb\-with\-kerberos\-authentication
.IP \(bu 2
/tutorial/control\-access\-to\-mongodb\-windows\-with\-kerberos\-authentication\&.
.UNINDENT
.sp
This document provides a complete overview of all command line options
for \fI\%mongokerberos\fP\&.
.SH INSTALLATION
.sp
The \fI\%mongokerberos\fP tool is part of the \fIMongoDB Database Tools Extra\fP
package, and can be \fI\%installed with the MongoDB Server\fP or as a
\fI\%standalone installation\fP\&.
.SS Install with Server
.sp
To install \fI\%mongokerberos\fP as part of a MongoDB Enterprise Server
installation:
.INDENT 0.0
.IP \(bu 2
Follow the instructions for your platform:
Install MongoDB Enterprise Server
.IP \(bu 2
After completing the installation, \fI\%mongokerberos\fP and the other
included tools are available in the same location as the Server.
.sp
\fBNOTE:\fP
.INDENT 2.0
.INDENT 3.5
For the Windows \fB\&.msi\fP installer wizard, the
Complete installation option includes \fI\%mongokerberos\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Install as Standalone
.sp
To install \fI\%mongokerberos\fP as a standalone installation:
.INDENT 0.0
.IP \(bu 2
Follow the download link for MongoDB Enterprise Edition:
\fI\%MongoDB Enterprise Download Center\fP
.IP \(bu 2
Select your Platform (operating system) from the dropdown
menu, then select the appropriate Package for your
platform according to the following chart:
.TS
center;
|l|l|.
_
T{
OS
T}	T{
Package
T}
_
T{
\fILinux\fP
T}	T{
\fBtgz\fP package
T}
_
T{
\fIWindows\fP
T}	T{
\fBzip\fP package
T}
_
T{
\fImacOS\fP
T}	T{
\fBtgz\fP package
T}
_
.TE
.IP \(bu 2
Once downloaded, unpack the archive and copy \fI\%mongokerberos\fP to a
location on your hard drive.
.INDENT 2.0
.INDENT 3.5
.SS Tip
.sp
Linux and macOS users may wish to copy \fI\%mongokerberos\fP to a filesystem
location that is defined in the \fB$PATH\fP environment variable, such
as \fB/usr/bin\fP\&. Doing so allows referencing \fI\%mongokerberos\fP directly
on the command line by name, without needing to specify its full
path, or first navigating to its parent directory. See the
installation guide for your platform
for more information.
.UNINDENT
.UNINDENT
.UNINDENT
.SH USAGE
.sp
\fI\%mongokerberos\fP can be run in two modes: \fIserver\fP and
\fIclient\fP\&.
.sp
Run \fI\%mongokerberos\fP from the system command line, not the \fBmongo\fP shell.
.SS Server Mode
.sp
Running \fI\%mongokerberos\fP in server mode performs a series of
verification steps against your system\(aqs Kerberos configuration,
including checking for proper DNS resolution, validation of the Kerberos
system keytab file, and testing against the MongoDB service principal
for your \fBmongod\fP or \fBmongos\fP instance.
.sp
Before you can use \fI\%mongokerberos\fP in server mode, you must:
.INDENT 0.0
.IP 1. 3
Configure Kerberos on your platform according to your platform\(aqs
documentation.
.IP 2. 3
Create the MongoDB service principal for use with your
\fBmongod\fP or \fBmongos\fP instance, as described
in the following steps:
.INDENT 3.0
.IP \(bu 2
Configure Service Principal on Linux
.IP \(bu 2
Configure Service Principal on Windows
.UNINDENT
.UNINDENT
.sp
Once you have completed these steps, you can run
\fI\%mongokerberos\fP in server mode using the
\fB\-\-server\fP flag as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongokerberos \-\-server
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If Kerberos has been configured properly on the server, and the service
principal created successfully, the output might resemble the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Resolving kerberos environment...
[OK] Kerberos environment resolved without errors.

Verifying DNS resolution works with Kerberos service at <hostname>...
[OK] DNS test successful.

Getting MIT Kerberos KRB5 environment variables...
  * KRB5CCNAME: not set.
  * KRB5_CLIENT_KTNAME: not set.
  * KRB5_CONFIG: not set.
  * KRB5_KTNAME: not set.
  * KRB5_TRACE: not set.
[OK]

Verifying existence of KRB5 keytab FILE:/etc/krb5.keytab...
[OK] KRB5 keytab exists and is populated.

Checking principal(s) in KRB5 keytab...
Found the following principals for MongoDB service mongodb:
  * mongodb/server.example.com@SERVER.EXAMPLE.COM
Found the following kvnos in keytab entries for service mongodb:
  * 3
[OK] KRB5 keytab is valid.

Fetching KRB5 Config...
KRB5 config profile resolved as:
   <Your Kerberos profile file will be output here>
[OK] KRB5 config profile resolved without errors.

Attempting to initiate security context with service credentials...
[OK] Security context initiated successfully.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The final message indicates that the system\(aqs Kerberos configuration is
ready to be used with MongoDB. If any errors are encountered with
the configuration, they will be presented as part of the above output.
.SS Client Mode
.sp
Running \fI\%mongokerberos\fP in client mode tests authentication
against your system\(aqs Kerberos environment, performing each step in the
Kerberos authentication process, including checking for proper DNS
resolution, verification of the Kerberos client keytab file, and testing
whether a ticket can be successfully granted. Running
\fI\%mongokerberos\fP in client mode simulates the client
authentication procedure of the \fBmongo\fP shell.
.sp
Before you can use \fI\%mongokerberos\fP in client mode, you must
first have configured Kerberos on your platform according to your
platform\(aqs documentation. Optionally, you may also choose to run
\fI\%mongokerberos\fP in
\fI\%server mode\fP first to verify that your
platform\(aqs Kerberos configuration is valid before using client mode.
.sp
Once you have completed these steps, you can run
\fI\%mongokerberos\fP in client mode to test user authentication,
using the \fB\-\-client\fP flag as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongokerberos \-\-client \-\-username <username>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You must provide a valid username, which is used to request a Kerberos
ticket as part of the authentication procedure. Your platform\(aqs
Kerberos infrastructure must be aware of this user.
.sp
If the provided credentials are valid, and the Kerberos options in the
configuration files are valid, the output might resemble the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
 Resolving kerberos environment...
 [OK] Kerberos environment resolved without errors.

 Verifying DNS resolution works with Kerberos service at <hostname>...
 [OK] DNS test successful.

 Getting MIT Kerberos KRB5 environment variables...
   * KRB5CCNAME: not set.
   * KRB5_CLIENT_KTNAME: not set.
   * KRB5_CONFIG: not set.
   * KRB5_KTNAME: not set.
   * KRB5_TRACE: not set.
 [OK]

 Verifying existence of KRB5 client keytab FILE:/path/to/client.keytab...
 [OK] KRB5 client keytab exists and is populated.

 Checking principal(s) in KRB5 keytab...
 [OK] KRB5 keytab is valid.

 Fetching KRB5 Config...
 KRB5 config profile resolved as:
    <Your Kerberos profile file will be output here>
 [OK] KRB5 config profile resolved without errors.

 Attempting client half of GSSAPI conversation...
 [OK] Client half of GSSAPI conversation completed successfully.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The final message indicates that client authentication completed
successfully for the user provided.  If any errors are encountered
during the authentication steps, they will be presented as part of the
above output.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-\-server
Runs \fI\%mongokerberos\fP in server mode to test that your
platform\(aqs Kerberos configuration is valid for use with MongoDB.
.sp
See \fI\%Server Mode\fP for example usage and expected
output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-client
Runs \fI\%mongokerberos\fP in client mode to test client
authentication against your system\(aqs Kerberos environment. Requires
specifying a valid username with \fI\%\-\-username\fP when running in
client mode. \fI\%mongokerberos\fP will request a Kerberos ticket
for this username as part of the validation procedure. Running
\fI\%mongokerberos\fP in client mode simulates the client
authentication procedure of the \fBmongo\fP shell.
.sp
See \fI\%Client Mode\fP for example usage and expected
output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-config <filename>, \-f <filename>
Specifies a configuration file for runtime configuration options.
The options are equivalent to the command\-line
configuration options. See /reference/configuration\-options for
more information.
.sp
\fI\%mongokerberos\fP will read the values for
\fBsaslHostName\fP and \fBsaslServiceName\fP from this
file if present. These values can alteratively be specified with the
\fI\%\-\-setParameter\fP option instead.
.sp
Ensure the configuration file uses ASCII encoding. The
\fI\%mongokerberos\fP instance does not support configuration
files with non\-ASCII encoding, including UTF\-8.
.sp
Only valid in \fI\%server mode\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-setParameter <options>
Sets a configurable parameter. You can specify multiple
\fBsetParameter\fP fields.
.sp
While you can use any supported parameters with \fBsetParameter\fP,
\fI\%mongokerberos\fP only checks for the value of the following:
.INDENT 7.0
.IP \(bu 2
\fBsaslHostName\fP
.IP \(bu 2
\fBsaslServiceName\fP
.UNINDENT
.sp
If using the \fI\%\-\-config\fP option with a configuration file that
also contains these values, the \fBsetParameter\fP values will
override the values from the configuration file.
.sp
Valid in both \fI\%server mode\fP
and \fI\%client mode\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-host <hostname>
Specify the hostname of the MongoDB server to connect to when testing
authentication.
.sp
If \fI\%\-\-host\fP is not specified, \fI\%mongokerberos\fP does
not perform any DNS validation of the hostname (i.e. PTR record
verification)
.sp
Only valid in \fI\%client mode\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-username <username>, \-u <username>
Username for \fI\%mongokerberos\fP to use when attempting Kerberos
authentication. This value is required when running in
\fI\%client mode\fP\&.
.sp
Only valid in \fI\%client mode\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-gssapiServiceName <servicename>
\fIdefault: \(aqmongodb\(aq\fP
.sp
Service principal name to use when authenticating using
GSSAPI/Kerberos.
.sp
Only valid in \fI\%client mode\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-gssapiHostName <hostname>
Remote hostname to use for purpose of GSSAPI/Kerberos authentication.
.sp
Only valid in \fI\%client mode\fP\&.
.UNINDENT
.SH AUTHOR
MongoDB Documentation Project
.SH COPYRIGHT
2008-2020
.\" Generated by docutils manpage writer.
.