Docs 菜单

mongokerberos

MongoDB Enterprise provides mongokerberos for testing MongoDB's Kerberos and GSSAPI configuration options against a running Kerberos deployment. mongokerberos can be used in one of two modes: server and 客户端.

模式
说明

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. 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. 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.

  • Linux MongoDB clients authenticating to Windows Active Directory deployments.

注意

MongoDB Enterprise and mongokerberos only support the MIT implementation of Kerberos.

Generally, when configuring options related to Kerberos authentication, it is good practice to verify your configuration with 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:

This document provides a complete overview of all command line options for mongokerberos

mongokerberos工具是MongoDB database Tools Extra包的一部分,可以与MongoDB Server一起安装,也可以独立安装。

要在安装mongokerberos MongoDB EnterpriseMongoDB Server时安装 :

要将mongokerberos作为独立安装进行安装:

  • 点击MongoDB Enterprise的下载链接: MongoDB Enterprise下载中心

  • 从下拉菜单中选择您的Platform (操作系统),然后根据下表选择适合您平台的Package

    OS
    安装包

    Linux

    tgz

    Windows

    zip

    macOS

    tgz

  • 下载后,解压缩存档并将mongokerberos复制到硬盘上的某个位置。

    提示

    Linux 和 macOS 用户可能希望将mongokerberos复制到$PATH环境变量中定义的文件系统位置,例如/usr/bin 。 这样做可以直接在命令行上按名称引用mongokerberos ,而无需指定其完整路径,或先导航到其父目录。 有关更多信息,请参阅适用于您的平台的安装指南

mongokerberos can be run in two modes: server and 客户端.

从系统命令行运行mongokerberos ,而不是在mongosh中。

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.

Before you can use mongokerberos in server mode, you must:

  1. Configure Kerberos on your platform according to your platform's documentation.

  2. Create the MongoDB service principal for use with your mongod or mongos instance, as described in the following steps:

Once you have completed these steps, you can run mongokerberos in server mode using the --server flag as follows:

mongokerberos --server

If Kerberos has been configured properly on the server, and the service principal created successfully, the output might resemble the following:

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.

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. Running mongokerberos in client mode simulates the client authentication procedure of mongosh

Before you can use mongokerberos in client mode, you must first have configured Kerberos on your platform according to your platform's documentation. 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.

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 --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.

If the provided credentials are valid, and the Kerberos options in the configuration files are valid, the output might resemble the following:

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.

--server

Runs mongokerberos in server mode to test that your platform's Kerberos configuration is valid for use with 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. Requires specifying a valid username with --username when running in client mode. mongokerberos will request a Kerberos ticket for this username as part of the validation procedure. Running mongokerberos in client mode simulates the client authentication procedure of mongosh

See Client Mode for example usage and expected output.

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

指定运行时配置选项的配置文件。 这些选项相当于命令行配置选项。 有关更多信息,请参阅自管理配置文件选项

mongokerberos will read the values for saslHostName and saslServiceName from this file if present. These values can alteratively be specified with the --setParameter option instead.

Ensure the configuration file uses ASCII encoding. The mongokerberos instance does not support configuration files with non-ASCII encoding, including UTF-8.

Only valid in server mode.

--setParameter <options>

Sets a configurable parameter. You can specify multiple setParameter fields.

While you can use any supported parameters with setParameter, mongokerberos only checks for the value of the following:

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.

Valid in both server mode and client mode.

--host <hostname>

Specify the hostname of the MongoDB server to connect to when testing authentication.

If --host is not specified, mongokerberos does not perform any DNS validation of the hostname (i.e. PTR record verification)

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.

Only valid in client mode.

--gssapiServiceName <servicename>

default: 'mongodb'

Service principal name to use when authenticating using GSSAPI/Kerberos.

Only valid in client mode.

--gssapiHostName <hostname>

Remote hostname to use for purpose of GSSAPI/Kerberos authentication.

Only valid in client mode.