Database Manual / Self-Managed Deployments / Installation / MongoDB Package Components

mongokerberos

Synopsis简介

MongoDB Enterprise provides mongokerberos for testing MongoDB's Kerberos and GSSAPI configuration options against a running Kerberos deployment. MongoDB Enterprise提供mongokerberos，用于针对正在运行的Kerberos部署测试MongoDB的Kerberos和GSSAPI配置选项。mongokerberos can be used in one of two modes: server and client.可以在两种模式之一中使用：服务器和客户端。

Mode模式Description描述
Server服务器In server mode, mongokerberos analyzes Kerberos-related configurations on the server, and returns a report which includes error messages for any configurations that are problematic. 在服务器模式下，mongokerberos分析服务器上与Kerberos相关的配置，并返回一份报告，其中包括任何有问题的配置的错误消息。For usage, see Server Mode有关用法，请参阅服务器模式
Client客户In client mode, mongokerberos 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. 在客户端模式下，mongokerberos测试所提供用户名的Kerberos身份验证，并返回一份报告，其中包括Kerberos身份验证过程中每个步骤的成功或失败。For usage, see Client Mode有关用法，请参阅客户端模式

Error messages for both modes include information on specific errors encountered and potential advice for resolving the error.两种模式的错误消息都包括遇到的特定错误的信息以及解决错误的潜在建议。

mongokerberos supports the following deployment types, in both server and client modes:在服务器和客户端模式下支持以下部署类型：

  • Linux MongoDB clients authenticating to MIT Kerberos deployments on supported Linux platforms.
  • Windows MongoDB clients authenticating to Windows Active Directory deployments on supported Windows platforms.Windows MongoDB客户端在受支持的Windows平台上对Windows 活动目录部署进行身份验证。
  • Linux MongoDB clients authenticating to Windows Active Directory deployments.Linux MongoDB客户端对Windows 活动目录部署进行身份验证。

Note

MongoDB Enterprise and mongokerberos only support the MIT implementation of Kerberos.MongoDB Enterprise和mongokerberos只支持Kerberos的MIT实现。

Generally, when configuring options related to Kerberos authentication, it is good practice to verify your configuration with mongokerberos.通常，在配置与Kerberos身份验证相关的选项时，最好使用mongokerberos验证配置。

mongokerberos 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 MIT Kerberos documentation, or your platform's documentation. For configuring MongoDB to authenticate using Kerberos, please reference the following tutorials:要在平台上配置Kerberos，请参阅MIT Kerberos文档或平台文档。要配置MongoDB使用Kerberos进行身份验证，请参考以下教程：

This document provides a complete overview of all command line options for mongokerberos.本文档提供了mongokerberos所有命令行选项的完整概述。

Installation安装

The mongokerberos tool is part of the MongoDB Database Tools Extra package, and can be installed with the MongoDB Server or as a standalone installation.mongokerberos工具是MongoDB数据库工具Extra包的一部分，可以与MongoDB服务器一起安装，也可以作为独立安装。

Install with Server与服务器一起安装

To install mongokerberos as part of a MongoDB Enterprise Server installation:要将mongokerberos作为MongoDB Enterprise Server安装的一部分进行安装，请执行以下操作：

  • Follow the instructions for your platform: Install MongoDB Enterprise Server按照您平台的说明进行操作：安装MongoDB Enterprise Server

  • After completing the installation, mongokerberos and the other included tools are available in the same location as the Server.安装完成后，mongokerberos和其他包含的工具可以在服务器的同一位置使用。

    Note

    For the Windows .msi installer wizard, the Complete installation option includes mongokerberos.对于Windows .msi安装程序向导，完整安装选项包括mongokerberos。

Install as Standalone独立安装

To install mongokerberos as a standalone installation:要将mongokerberos安装为独立安装：

  • Follow the download link for MongoDB Enterprise Edition: MongoDB Enterprise Download Center请点击MongoDB企业版的下载链接：MongoDB企业版下载中心

  • Select your Platform (operating system) from the dropdown menu, then select the appropriate Package for your platform according to the following chart:从下拉菜单中选择平台（操作系统），然后根据下图为平台选择合适的软件包：

    OSPackage
    Linuxtgz package包裹
    Windowszip package包裹
    macOStgz package包裹

  • Once downloaded, unpack the archive and copy mongokerberos to a location on your hard drive.下载后，解压缩存档并将mongokerberos复制到硬盘上的某个位置。

    Tip

    Linux and macOS users may wish to copy mongokerberos to a filesystem location that is defined in the $PATH environment variable, such as /usr/bin. Linux和macOS用户可能希望将mongokerberos复制到$PATH环境变量中定义的文件系统位置，如/usr/bin。Doing so allows referencing mongokerberos directly on the command line by name, without needing to specify its full path, or first navigating to its parent directory. 这样做允许直接在命令行上按名称引用mongokerberos，而不需要指定其完整路径，也不需要首先导航到其父目录。See the installation guide for your platform for more information.有关更多信息，请参阅平台的安装指南。

Usage用法

mongokerberos can be run in two modes: server and client.可以在两种模式下运行：服务器和客户端。

Run mongokerberos from the system command line, not in the mongosh.从系统命令行运行mongokerberos，而不是在mongosh中运行。

Server Mode服务器模式

Running mongokerberos in server mode performs a series of verification steps against your system's Kerberos configuration, including checking for proper DNS resolution, validation of the Kerberos system keytab file, and testing against the MongoDB service principal for your mongod or mongos instance.在服务器模式下运行mongokerberos会对系统的Kerberos配置执行一系列验证步骤，包括检查DNS解析是否正确、验证Kerberos系统键表文件，以及针对mongod或mongos实例的MongoDB服务主体进行测试。

Before you can use mongokerberos in server mode, you must:在服务器模式下使用mongokerberos之前，您必须：

  1. Configure Kerberos on your platform according to your platform's documentation.根据平台文档在平台上配置Kerberos。

  2. Create the MongoDB service principal for use with your mongod or mongos instance, as described in the following steps:创建MongoDB服务主体，以便与mongod或mongos实例一起使用，如以下步骤所述：

Once you have completed these steps, you can run mongokerberos in server mode using the --server flag as follows:完成这些步骤后，您可以使用--server标志在服务器模式下运行mongokerberos，如下所示：

mongokerberos --server

If Kerberos has been configured properly on the server, and the service principal created successfully, the output might resemble the following:如果服务器上正确配置了Kerberos，并且成功创建了服务主体，则输出可能类似于以下内容：

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.

The final message indicates that the system's 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.最后一条消息表示系统的Kerberos配置已准备好与MongoDB一起使用。如果配置中遇到任何错误，它们将作为上述输出的一部分显示。

Client Mode客户端模式

Running mongokerberos in client mode tests authentication against your system's 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. 在客户端模式下运行mongokerberos可以测试针对系统Kerberos环境的身份验证，执行Kerberos身份验证过程中的每个步骤，包括检查DNS解析是否正确、验证Kerberos客户端键表文件以及测试是否可以成功授予票证。Running mongokerberos in client mode simulates the client authentication procedure of mongosh.在客户端模式下运行mongokerberos模拟了mongosh的客户端身份验证过程。

Before you can use mongokerberos in client mode, you must first have configured Kerberos on your platform according to your platform's documentation. 在客户端模式下使用mongokerberos之前，您必须首先根据平台的文档在平台上配置Kerberos。Optionally, you may also choose to run mongokerberos in server mode first to verify that your platform's Kerberos configuration is valid before using client mode.您也可以选择先在服务器模式下运行mongokerberos，以验证平台的Kerberos配置是否有效，然后再使用客户端模式。

Once you have completed these steps, you can run mongokerberos in client mode to test user authentication, using the --client flag as follows:完成这些步骤后，您可以在客户端模式下运行mongokerberos来测试用户身份验证，使用--client标志，如下所示：

mongokerberos --client --username <username>

You must provide a valid username, which is used to request a Kerberos ticket as part of the authentication procedure. Your platform's Kerberos infrastructure must be aware of this user.您必须提供一个有效的用户名，作为身份验证过程的一部分，该用户名用于请求Kerberos票证。平台的Kerberos基础架构必须知道此用户。

If the provided credentials are valid, and the Kerberos options in the configuration files are valid, the output might resemble the following:如果提供的凭据有效，并且配置文件中的Kerberos选项有效，则输出可能类似于以下内容：

 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.

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.最后一条消息表示所提供用户的客户端身份验证已成功完成。如果在身份验证步骤中遇到任何错误，它们将作为上述输出的一部分显示。

Options选项

--server

Runs mongokerberos in server mode to test that your platform's Kerberos configuration is valid for use with MongoDB.在服务器模式下运行mongokerberos，以测试平台的Kerberos配置是否适用于MongoDB。

See Server Mode for example usage and expected output.有关示例用法和预期输出，请参阅服务器模式。

--client

Runs mongokerberos in client mode to test client authentication against your system's Kerberos environment. 在客户端模式下运行mongokerberos，以根据系统的Kerberos环境测试客户端身份验证。Requires specifying a valid username with --username when running in client mode. 在客户端模式下运行时，需要使用--username指定有效的用户名。mongokerberos will request a Kerberos ticket for this username as part of the validation procedure. 将请求此用户名的Kerberos票证作为验证过程的一部分。Running mongokerberos in client mode simulates the client authentication procedure of mongosh.在客户端模式下运行mongokerberos模拟了mongosh的客户端身份验证过程。

See Client Mode for example usage and expected output.有关示例用法和预期输出，请参阅客户端模式。

--config <filename>, -f <filename>

Specifies a configuration file for runtime configuration options. The options are equivalent to the command-line configuration options. See Self-Managed Configuration File Options for more information.指定运行时配置选项的配置文件。这些选项与命令行配置选项等效。有关详细信息，请参阅自我管理配置文件选项。

mongokerberos will read the values for saslHostName and saslServiceName from this file if present. 将从该文件中读取saslHostName和saslServiceName的值（如果存在）。These values can alteratively be specified with the --setParameter option instead.这些值也可以用--setParameter选项指定。

Ensure the configuration file uses ASCII encoding. The mongokerberos instance does not support configuration files with non-ASCII encoding, including UTF-8.确保配置文件使用ASCII编码。mongokerberos实例不支持非ASCII编码的配置文件，包括UTF-8。

Only valid in server mode.仅在服务器模式下有效。

--setParameter <options>

Sets a configurable parameter. You can specify multiple setParameter fields.设置可配置参数。您可以指定多个setParameter字段。

While you can use any supported parameters with setParameter, mongokerberos only checks for the value of the following:虽然您可以在setParameter中使用任何支持的参数，但mongokerberos只检查以下值：

If using the --config option with a configuration file that also contains these values, the setParameter values will override the values from the configuration file.如果对也包含这些值的配置文件使用--config选项，则setParameter值将覆盖配置文件中的值。

Valid in both server mode and client mode.在服务器模式和客户端模式下都有效。

--host <hostname>

Specify the hostname of the MongoDB server to connect to when testing authentication.指定测试身份验证时要连接的MongoDB服务器的主机名。

If --host is not specified, mongokerberos does not perform any DNS validation of the hostname (i.e. PTR record verification)如果未指定--host，mongokerberos不会对主机名执行任何DNS验证（即PTR记录验证）

Only valid in client mode.仅在客户端模式下有效。

--username <username>, -u <username>

Username for mongokerberos to use when attempting Kerberos authentication. This value is required when running in client mode.尝试Kerberos身份验证时使用的mongokerberos的用户名。在客户端模式下运行时需要此值。

Only valid in client mode.仅在客户端模式下有效。

--gssapiServiceName <servicename>

default: 'mongodb'

Service principal name to use when authenticating using GSSAPI/Kerberos.使用GSSAPI/Kerberos进行身份验证时使用的服务主体名称。

Only valid in client mode.仅在客户端模式下有效。

--gssapiHostName <hostname>

Remote hostname to use for purpose of GSSAPI/Kerberos authentication.用于GSSAPI/Kerberos身份验证的远程主机名。

Only valid in client mode.