diff options
Diffstat (limited to 'debian/mongokerberos.1')
| -rw-r--r-- | debian/mongokerberos.1 | 489 |
1 files changed, 489 insertions, 0 deletions
diff --git a/debian/mongokerberos.1 b/debian/mongokerberos.1 new file mode 100644 index 00000000000..75165b963c6 --- /dev/null +++ b/debian/mongokerberos.1 @@ -0,0 +1,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. +. |