Docs Menu

Upgrade Self-Managed MongoDB from Keyfile Authentication to X.509 Authentication

To upgrade clusters that are currently using keyfile authentication to X.509 authentication, use the following rolling upgrade processes.

注意

MongoDB は、TLS 1.1 + が利用可能なシステムで TLS 1.0暗号化のサポートを無効にします。

注意

MongoDB は、 net.ssl設定(および--sslコマンドライン オプション)に対応するnet.tls設定(および--tlsコマンドライン オプション)を提供します。 MongoDB は常に TLS 1.0以降をサポートしているため、新しいtls設定はssl設定と同じ機能を提供します。

The procedures in this section use the tls settings/options. For procedures using the ssl settings/options, see Upgrade Procedures (Using ssl Options).

注意

The procedure uses the tls settings/options. For procedures using the ssl settings/options, see Clusters Currently Using TLS/SSL (Using ssl Options).

For clusters using TLS/SSL and keyfile authentication, to upgrade to X.509 cluster authentication, use the following rolling upgrade process:

  1. For each member of a cluster, add the following settings to the 構成ファイル and restart:

    • security.clusterAuthMode
      Set to sendKeyFile. With this setting value, each node continues to send its keyfile to authenticate itself as a member. However, each node can receive either a keyfile or an X.509 certificate from other members to authenticate those members.
    • net.tls.clusterFile
      Set to the appropriate path of the node's certificate key file for membership authentication. The mongod / mongos presents this file to other members of the cluster to identify itself as a member.

    Include other TLS/SSL options and any other options as appropriate for your specific configuration.

    以下に例を挙げます。

    net:
    tls:
    mode: requireTLS
    certificateKeyFile: /etc/ssl/mongodb.pem
    CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
    clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
    security:
    clusterAuthMode: sendKeyFile
    keyFile: /my/securely/located/membershipkey
    replication:
    replSetName: myReplicaSet
    net:
    bindIp: localhost,mongodb0.example.net
    port: 27017
    systemLog:
    destination: file
    path: "/var/log/mongodb/mongod.log"
    logAppend: true
    storage:
    dbPath: "/var/lib/mongodb"
    processManagement:
    fork: true

    Update all nodes of the cluster to include the security.clusterAuthMode and net.tls.clusterFile settings before continuing.

  2. Connect to each node and use the setParameter command to update the clusterAuthMode to sendX509. [1]

    db.adminCommand( { setParameter: 1, clusterAuthMode: "sendX509" } )

    With sendX509, each node sends its net.tls.clusterFile to authenticate itself as a member. However, each node can receive either a keyfile or an X.509 certificate from other members to authenticate those members.

    Upgrade all nodes of the cluster to this setting before continuing.

  3. Optional but recommended. Finally, for each node of the cluster, connect to the node and use the setParameter command to update the clusterAuthMode to x509 to only use the X.509 certificate for authentication. [1]

    db.adminCommand( { setParameter: 1, clusterAuthMode: "x509" } )
  4. After the upgrade of all nodes, edit the 構成ファイル with the appropriate X.509 settings to ensure that upon subsequent restarts, the cluster uses X.509 authentication. For example:

    net:
    tls:
    mode: requireTLS
    certificateKeyFile: /etc/ssl/mongodb.pem
    CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
    clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
    security.clusterAuthMode: x509
    replication:
    replSetName: myReplicaSet
    net:
    bindIp: localhost,mongodb0.example.net
    port: 27017
    systemLog:
    destination: file
    path: "/var/log/mongodb/mongod.log"
    logAppend: true
    storage:
    dbPath: "/var/lib/mongodb"
    processManagement:
    fork: true

Tip

以下も参照してください。

構成ファイルの代わりにコマンドライン オプションを使用して mongodmongos を設定することもできます。

注意

The procedure uses the tls options. For procedures using the ssl settings/options, see Clusters Currently Not Using TLS/SSL (Using ssl Options).

For clusters using keyfile authentication but not TLS/SSL, to upgrade to X.509 membership authentication and TLS/SSL connections:

  1. For each member of a cluster, add the following settings to the 構成ファイル and restart:

    • net.tls.mode
      Set to allowTLS. This value allows the node to accept both TLS/SSL and non-TLS/non-SSL incoming connections. Its outgoing connections do not use TLS/SSL.
    • net.tls.certificateKeyFile
      Set to the path of the file that contains the TLS/SSL certificate and key. The mongod / mongos presents this file to its clients to establish the instance's identity. Required when using TLS/SSL.
    • net.tls.clusterFile
      Set to the appropriate path of the node's certificate key file for membership authentication. The mongod / mongos presents this file to other members of the cluster to identify itself as a member.
    • net.tls.CAFile
      Set to the path of the file that contains the certificate chain for verifying received certificates.
    • security.clusterAuthMode
      Set to sendKeyFile. This allows each node continues to send its keyfile to authenticate itself as a member. However, each node can receive either a keyfile or an X.509 certificate from other members to authenticate those members.

    Include other TLS/SSL options and any other options as appropriate for your specific configuration.

    以下に例を挙げます。

    net:
    tls:
    mode: allowTLS
    certificateKeyFile: /etc/ssl/mongodb.pem
    clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
    CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
    security:
    clusterAuthMode: sendKeyFile
    keyFile: /my/securely/located/membershipkey
    replication:
    replSetName: myReplicaSet
    net:
    bindIp: localhost,mongodb0.example.net
    port: 27017
    systemLog:
    destination: file
    path: "/var/log/mongodb/mongod.log"
    logAppend: true
    storage:
    dbPath: "/var/lib/mongodb"
    processManagement:
    fork: true

    Upgrade all nodes of the cluster to include net.tls.mode, net.tls.certificateKeyFile, net.tls.clusterFile, and security.clusterAuthMode.

  2. Connect to each node and use the setParameter command [1] to:

    1. Update the tlsMode to preferSSL. With the tlsMode set to preferTLS, the node accepts both TLS/SSL and non-TLS/non-SSL incoming connections, and its outgoing connections use TLS/SSL.

    2. Update the clusterAuthMode to sendX509. With the clusterAuthMode set to sendX509, each node sends its net.tls.clusterFile to authenticate itself as a member. However, each node continues to accept either a keyfile or an X.509 certificate from other members to authenticate those members.

    db.adminCommand( { setParameter: 1, tlsMode: "preferTLS" } );
    db.adminCommand( { setParameter: 1, clusterAuthMode: "sendX509" } );

    Upgrade all nodes of the cluster to these settings before continuing.

  3. After the upgrade of all nodes, edit the 構成ファイル with the appropriate TLS/SSL and X.509 settings to ensure that upon subsequent restarts, the cluster uses X.509 authentication.

    net:
    tls:
    mode: preferTLS
    certificateKeyFile: /etc/ssl/mongodb.pem
    clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
    CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
    security:
    clusterAuthMode: sendX509
    replication:
    replSetName: myReplicaSet
    net:
    bindIp: localhost,mongodb0.example.net
    port: 27017
    systemLog:
    destination: file
    path: "/var/log/mongodb/mongod.log"
    logAppend: true
    storage:
    dbPath: "/var/lib/mongodb"
    processManagement:
    fork: true

    注意

    At this point,

    • The nodes in the cluster use TLS/SSL connections. However, the nodes can accept non-TLS/SSL connections from client applications.

    • The nodes send their X.509 certificates for membership authentication, but can accept either X.509 certificates or keyfiles from other nodes to verify the other nodes' membership.

    To enforce TLS/SSL connections from client applications as well as only accept X.509 for membership authentication, see next step.

  4. Optional but recommended. Update all nodes to use only TLS/SSL connections and only X.509 certificate for membership authentication.

    重要

    This TLS/SSL connection requirement applies to all connections; that is, with the clients as well as with the members of the cluster. That is, clients must specify TLS/SSL connections and presents its certificate key file when connecting to the cluster. See クライアント証明書を必要とする MongoDB インスタンスへの接続 for more information on connecting with TLS/SSL. See also クライアントが証明書を提示した場合のみ検証する.

    Update the net.tls.mode to requireTLS and security.clusterAuthMode to x509.

    以下に例を挙げます。

    net:
    tls:
    mode: requireTLS
    certificateKeyFile: /etc/ssl/mongodb.pem
    clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
    CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
    security:
    clusterAuthMode: x509
    replication:
    replSetName: myReplicaSet
    net:
    bindIp: localhost,mongodb0.example.net
    port: 27017
    systemLog:
    destination: file
    path: "/var/log/mongodb/mongod.log"
    logAppend: true
    storage:
    dbPath: "/var/lib/mongodb"
    processManagement:
    fork: true

Tip

以下も参照してください。

構成ファイルの代わりにコマンドライン オプションを使用して mongodmongos を設定することもできます。

注意

MongoDB は、 net.ssl設定(および--sslコマンドライン オプション)に対応するnet.tls設定(および--tlsコマンドライン オプション)を提供します。 MongoDB は常に TLS 1.0以降をサポートしているため、新しいtls設定はssl設定と同じ機能を提供します。

The procedures in this section use the ssl options. For procedures using the tls options, see Upgrade Procedures (Using tls Options).

注意

The procedure uses the ssl options. For procedures using the tls options, see Clusters Currently Using TLS/SSL (Using ssl Options).

For clusters using TLS/SSL and keyfile authentication, to upgrade to X.509 cluster authentication, use the following rolling upgrade process:

  1. For each node of a cluster, start the node with the option --clusterAuthMode set to sendKeyFile and the option --sslClusterFile set to the appropriate path of the node's certificate. Include other TLS/SSL options as well as any other options that are required for your specific configuration. For example:

    mongod --replSet <name> --sslMode requireSSL --clusterAuthMode sendKeyFile --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to TLS/SSL Certificate and key PEM file> --sslCAFile <path to root CA PEM file> --bind_ip localhost,<hostname(s)|ip address(es)>

    With this setting, each node continues to use its keyfile to authenticate itself as a member. However, each node can now accept either a keyfile or an X.509 certificate from other members to authenticate those members. Upgrade all nodes of the cluster to this setting.

  2. Then, for each node of a cluster, connect to the node and use the setParameter command to update the clusterAuthMode to sendX509. [1] For example,

    db.adminCommand( { setParameter: 1, clusterAuthMode: "sendX509" } )

    With this setting, each node uses its X.509 certificate, specified with the --sslClusterFile option in the previous step, to authenticate itself as a member. However, each node continues to accept either a keyfile or an X.509 certificate from other members to authenticate those members. Upgrade all nodes of the cluster to this setting.

  3. Optional but recommended. Finally, for each node of the cluster, connect to the node and use the setParameter command to update the clusterAuthMode to x509 to only use the X.509 certificate for authentication. [1] For example:

    db.adminCommand( { setParameter: 1, clusterAuthMode: "x509" } )
  4. After the upgrade of all nodes, edit the 構成ファイル with the appropriate X.509 settings to ensure that upon subsequent restarts, the cluster uses X.509 authentication.

See --clusterAuthMode for the various modes and their descriptions.

注意

The procedure uses the ssl options. For procedures using the tls options, see Update (Using tls Options) Clusters Using Keyfile but Not TLS/SSL.

For clusters using keyfile authentication but not TLS/SSL, to upgrade to X.509 authentication, use the following rolling upgrade process:

  1. For each node of a cluster, start the node with the option --sslMode set to allowSSL, the option --clusterAuthMode set to sendKeyFile and the option --sslClusterFile set to the appropriate path of the node's certificate. Include other TLS/SSL options as well as any other options that are required for your specific configuration. For example:

    mongod --replSet <name> --sslMode allowSSL --clusterAuthMode sendKeyFile --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to TLS/SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file> --bind_ip localhost,<hostname(s)|ip address(es)>

    The --sslMode allowSSL setting allows the node to accept both TLS/SSL and non-TLS/non-SSL incoming connections. The node's outgoing connections do not use TLS/SSL.

    The --clusterAuthMode sendKeyFile setting allows each node continues to use its keyfile to authenticate itself as a member. However, each node can now accept either a keyfile or an X.509 certificate from other members to authenticate those members.

    Upgrade all nodes of the cluster to these settings.

  2. Then, for each node of a cluster, connect to the node and use the setParameter command to update the sslMode to preferSSL and the clusterAuthMode to sendX509. [1] For example:

    db.adminCommand( { setParameter: 1, sslMode: "preferSSL", clusterAuthMode: "sendX509" } )

    With the sslMode set to preferSSL, the node accepts both TLS/SSL and non-TLS/non-SSL incoming connections, and its outgoing connections use TLS/SSL.

    With the clusterAuthMode set to sendX509, each node uses its X.509 certificate, specified with the --sslClusterFile option in the previous step, to authenticate itself as a member. However, each node continues to accept either a keyfile or an X.509 certificate from other members to authenticate those members.

    Upgrade all nodes of the cluster to these settings.

  3. Optional but recommended. Finally, for each node of the cluster, connect to the node and use the setParameter command to update the sslMode to requireSSL and the clusterAuthMode to x509. [1] For example:

    db.adminCommand( { setParameter: 1, sslMode: "requireSSL", clusterAuthMode: "x509" } )

    With the sslMode set to requireSSL, the node only uses TLS/SSLs connections.

    With the clusterAuthMode set to x509, the node only uses the X.509 certificate for authentication.

  4. After the upgrade of all nodes, edit the 構成ファイル with the appropriate TLS/SSL and X.509 settings to ensure that upon subsequent restarts, the cluster uses X.509 authentication.

See --clusterAuthMode for the various modes and their descriptions.

[1](1, 2, 3, 4, 5, 6, 7) As an alternative to using the setParameter command, you can also restart the nodes with the appropriate TLS/SSL and x509 options and values.