Percona Server For MongoDB4.4.5
Percona Server For MongoDB4.4.5
4
Documentation
Release 4.4.5-7
I Introduction 3
II Installation 7
III Features 25
IV Reference 67
i
ii
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Percona Server for MongoDB is a free, enhanced, fully compatible, open source, drop-in replacement for MongoDB
4.4 Community Edition with enterprise-grade features. It requires no changes to MongoDB applications or code.
Hint: To see which version of Percona Server for MongoDB you are using check the value of the psmdbVersion
key in the output of the buildInfo database command. If this key does not exist Percona Server for MongoDB is
not installed on the server.
See also:
MongoDB Documentation: buildInfo Database Command https://docs.mongodb.com/manual/reference/
command/buildInfo/#dbcmd.buildInfo
CONTENTS 1
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
2 CONTENTS
Part I
Introduction
3
CHAPTER
ONE
Percona Server for MongoDB 4.4 is based on MongoDB 4.4. Percona Server for MongoDB extends MongoDB
Community Edition to include the functionality that is otherwise only available in MongoDB Enterprise Edition.
PSMDB MongoDB
Storage Engines
• WiredTiger (default) • WiredTiger (default)
• Percona Memory Engine • In-Memory (Enterprise only)
Encryption-at-Rest
• Key server = Hashicorp Vault • Key server = KMIP
• Fully opensource • Enterprise only
Profiling Rate Limiting was added to Percona Server for MongoDB in v3.4 with --rateLimit argument. Since v3.6
MongoDB Community (and Enterprise) Edition includes a similar option slowOpSampleRate. Please see Profiling
Rate Limit for more information.
5
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Installation
7
CHAPTER
TWO
Percona provides installation packages of Percona Server for MongoDB for the most 64-bit Linux distributions. Find
the full list of supported platforms on the Percona Software and Platform Lifecycle page.
The recommended installation method is from Percona repositories. Follow the links below for the installation in-
structions for your operating system.
• Install on Debian or Ubuntu
• Install on RHEL or CentOS
You can also download packages from the Percona website and install them manually using dpkg or rpm.
Note: In this case, you will have to make sure that all dependencies are satisfied.
If you want more control over the installation, you can install Percona Server for MongoDB from binary tarballs.
Note: This method is for advanced users with specific needs that are not addressed by DEB and RPM packages.
If you want to run Percona Server for MongoDB in a Docker container, see Running Percona Server for MongoDB in
a Docker Container.
Upgrade Instructions
Use this document to install Percona Server for MongoDB from Percona repositories on DEB-based distributions.
Note: Percona Server for MongoDB should work on other DEB-based distributions, but it is tested only on platforms
listed on the Percona Software and Platform Lifecycle page.
9
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
• Package Contents
• Installing from Percona repositories
– Configure Percona repository
– Install the latest version
– Install a specific version
• Running Percona Server for MongoDB
• Uninstalling Percona Server for MongoDB
Package Contents
Package Contains
percona-server-mongodb The mongo shell, import/export tools, other client utilities, server software, default
configuration, and init.d scripts.
percona-server- The mongod server, default configuration files, and init.d scripts
mongodb-server
percona-server- The mongo shell
mongodb-shell
percona-server- The mongos sharded cluster query router
mongodb-mongos
percona-server- Mongo tools for high-performance MongoDB fork from Percona
mongodb-tools
percona-server- Debug symbols for the server
mongodb-dbg
It is recommended to install Percona Server for MongoDB from official Percona repositories using the
percona-release utility.
Once you install this package the Percona repositories should be added. You can check the repository setup in
the /etc/apt/sources.list.d/percona-release.list file.
3. Enable the repository: percona-release enable psmdb-44 release
4. Remember to update the local cache: apt-get update
Run the following command to install the latest version of Percona Server for MongoDB:
Sample Output
2. Install a specific version packages. You must specify each package with the version number. For example, to
install Percona Server for MongoDB 4.4.0-1, run the following command:
˓→percona-server-mongodb-server=4.4.0-1.buster percona-server-mongodb-tools=4.4.0-
˓→1.buster
By default, Percona Server for MongoDB stores data files in /var/lib/mongodb/ and configuration parameters
in /etc/mongod.conf.
Run the following commands as root or by using the sudo command
Starting the service Percona Server for MongoDB is started automatically after installation unless it encounters er-
rors during the installation process. You can also manually start it using the following command:
Confirming that the service is running Check the service status using the following command:
Stopping the service Stop the service using the following command:
Restarting the service Restart the service using the following command:
To uninstall Percona Server for MongoDB, remove all the installed packages. Removing packages with apt-get
remove will leave the configuration and data files. Removing the packages with apt purge will remove all the
packages with configuration files and data. Depending on your needs you can choose which command better suits
you.
Run the following commands as root or by using the sudo command
1. Stop the mongod server: systemctl stop mongod
2. Remove the packages. There are two options. To keep the configuration and data files, run apt-get remove
percona-server-mongodb*. If you want to delete the configuration and data files as well as the packages,
use apt purge: apt purge percona-server-mongodb*
Installing Percona Server for MongoDB on Red Hat Enterprise Linux and CentOS
Use this document to install Percona Server for MongoDB on RPM-based distributions from Percona repositories.
Note: Percona Server for MongoDB should work on other RPM-based distributions (for example, Amazon Linux
AMI and Oracle Linux), but it is tested only on platforms listed on the Percona Software and Platform Lifecycle page.1
• Package Contents
• Installing from Percona repositories
– Configure Percona repository
– Install the latest version
– Install a specific version
• Running Percona Server for MongoDB
– Running after reboot
• Uninstalling Percona Server for MongoDB
1 We support only the current stable RHEL 6 and CentOS 6 releases, because there is no official (i.e. RedHat provided) method to support or
download the latest OpenSSL on RHEL and CentOS versions prior to 6.5. Similarly, and also as a result thereof, there is no official Percona way
to support the latest Percona Server builds on RHEL and CentOS versions prior to 6.5. Additionally, many users will need to upgrade to OpenSSL
1.0.1g or later (due to the Heartbleed vulnerability), and this OpenSSL version is not available for download from any official RHEL and CentOS
repositories for versions 6.4 and prior. For any officially unsupported system, src.rpm packages can be used to rebuild Percona Server for any
environment. Please contact our support service if you require further information on this.
Package Contents
Package Contains
percona-server-mongodb The mongo shell, import/export tools, other client utilities, server software, default
configuration, and init.d scripts.
percona-server- The mongod server, default configuration files, and init.d scripts
mongodb-server
percona-server- The mongo shell
mongodb-shell
percona-server- The mongos sharded cluster query router
mongodb-mongos
percona-server- Mongo tools for high-performance MongoDB fork from Percona
mongodb-tools
percona-server- Debug symbols for the server
mongodb-dbg
The preferable way to install Percona Server for MongoDB is from Percona repositories. Percona repositories are
managed using the percona-release tool.
Example of Output
Retrieving https://repo.percona.com/yum/percona-release-latest.noarch.rpm
Preparing... ########################################### [100%]
1:percona-release ########################################### [100%]
To install the latest version of Percona Server for MongoDB, use the following command:
Sample Output
Available Packages
percona-server-mongodb.x86_64 4.4.0-1.el8 psmdb-44-release-x86_64
2. Install a specific version packages. For example, to install Percona Server for MongoDB 4.4.0-1, run the fol-
lowing command:
Warning: If you have SELinux security module installed, it will conflict with Percona Server for MongoDB.
There are several options to deal with this:
• Remove the SELinux packages. This is not recommended, because it may violate security.
• Disable SELinux by setting SELINUX in /etc/selinux/config to disabled. This change takes
effect after you reboot.
• Run SELinux in permissive mode by setting SELINUX in /etc/selinux/config to permissive.
This change takes effect after you reboot.
You can also enforce permissive mode at runtime using the setenforce 0 command. However, this will
not affect the configuration after a reboot.
Percona Server for MongoDB stores data files in /var/lib/mongodb/ by default. The configuration file is /etc/
mongod.conf.
Starting the service Percona Server for MongoDB is not started automatically after installation. Start it manually
using the following command:
Confirming that service is running Check the service status using the following command: systemctl status
mongod
Stopping the service Stop the service using the following command: systemctl stop mongod
Restarting the service Restart the service using the following command: systemctl restart mongod
The mongod service is not automatically started after you reboot the system.
For RHEL or CentOS versions 5 and 6, you can use the chkconfig utility to enable auto-start as follows:
For RHEL or CentOS version 7, you can use the systemctl utility:
To completely uninstall Percona Server for MongoDB you’ll need to remove all the installed packages and data files:
Run the following commands as root or by using the sudo command
1. Stop the Percona Server for MongoDB service:
Warning: This will remove all the packages and delete all the data files (databases, tables, logs, etc.). You might
want to back up your data before doing this in case you need the data later.
You can find links to the binary tarballs under the Generic Linux menu item on the Percona website
There are two tarballs available:
• percona-server-mongodb-4.4.1-2-x86_64.glibc2.17.tar.gz is the general tarball, compat-
ible with any operation system but for Centos 6.
• percona-server-mongodb-4.4.1-2-x86_64.glibc2.12.tar.gz is the tarball for Centos 6.
1. Fetch and extract the correct binary tarball. For example, if you are running Debian 10 (“buster”):
$ wget https://www.percona.com/downloads/percona-server-mongodb-4.4/percona-
˓→server-mongodb-4.4.1-2/binary/tarball/percona-server-mongodb-4.4.1-2-x86_64.
˓→glibc2.17.tar.gz\
$ export PATH=~/percona-server-mongodb-4.4.1-2/bin/:$PATH`
$ mkdir -p /data/db
4. Make sure that you have read and write permissions for the data directory and run mongod.
Docker images of Percona Server for MongoDB are hosted publicly on Docker Hub at https://hub.docker.com/r/
percona/percona-server-mongodb/.
For more information about using Docker, see the Docker Docs.
Note: Make sure that you are using the latest version of Docker. The ones provided via apt and yum may be outdated
and cause errors.
Note: By default, Docker will pull the image from Docker Hub if it is not available locally.
To run the latest Percona Server for MongoDB 4.4 in a Docker container, use the following command:
Run this command as root or by using the sudo command
The Percona Server for MongoDB container exposes standard MongoDB port (27017), which can be used for connec-
tion from an application running in another container. To link the application container to the psmdb container, use
the --link psmdb option when running the container with your app.
To start another container with the mongo shell that connects to your Percona Server for Mon-
goDB container, run the following comand: docker run -it --link psmdb --rm percona/
percona-server-mongodb:mongo mongo -h psmdb
THREE
An in-place upgrade is done with existing data in the server. Generally speaking, this is stopping the mongod service,
removing the old packages, installing the new server and starting it with the same db data directory. An in-place
upgrade is suitable for most environments, except the ones that use ephemeral storage and/or host addresses.
Note: MongoDB creates a user that belongs to two groups, which is a potential security risk. This is fixed in Percona
Server for MongoDB: the user is included only in the mongod group. To avoid problems with current MongoDB
setups, existing user group membership is not changed when you migrate to Percona Server for MongoDB. Instead, a
new mongod user is created during installation, and it belongs to the mongod group.
This document describes an in-place upgrade of a mongod instance. If you are using data at rest encryption, refer to
the Upgrading to Percona Server for MongoDB with data at rest encryption enabled section.
• Prerequisites
• Upgrading on Debian or Ubuntu
• Upgrading on Red Hat Enterprise Linux or CentOS
• Upgrading to Percona Server for MongoDB with data at rest encryption enabled
Prerequisites
Before you start the upgrade, update the MongoDB configuration file (/etc/mongod.conf) to contain the follow-
ing settings.
processManagement:
fork: true
pidFilePath: /var/run/mongod.pid
Troubleshooting tip: The pidFilePath setting in mongod.conf must match the PIDFile option in the
systemd mongod service unit. Otherwise, the service will kill the mongod process after a timeout.
Warning: Before starting the upgrade, we recommend to perform a full backup of your data.
19
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Output
Output
mongodb-org-mongos-4.4.0-1.el6.x86_64
mongodb-org-shell-4.4.0-1.el6.x86_64
mongodb-org-server-4.4.0-1.el6.x86_64
mongodb-org-tools-4.4.0-1.el6.x86_64
mongodb-org-4.4.0-1.el6.x86_64
$ yum remove \
mongodb-org-mongos-4.4.0-1.el6.x86_64 \
mongodb-org-shell-4.4.0-1.el6.x86_64 \
mongodb-org-server-4.4.0-1.el6.x86_64 \
mongodb-org-tools-4.4.0-1.el6.x86_64 \
mongodb-org-4.4.0-1.el6.x86_64
Note: When you remove old packages, your existing configuration file is saved as /etc/mongod.conf.
rpmsave. If you want to use this configuration with the new version, replace the default /etc/mongod.conf
file. For example, existing data may not be compatible with the default WiredTiger storage engine.
To upgrade a replica set or a sharded cluster, use the rolling restart method. It allows you to perform the upgrade with
minimum downtime. You upgrade the nodes one by one, while the whole cluster / replica set remains operational.
See also:
MongoDB Documentation:
• Upgrade a Replica Set
• Upgrade a Sharded Cluster
Steps to upgrade from MongoDB 4.4 Community Edition with data encryption enabled to Percona Server for Mon-
goDB are different. mongod requires an empty dbPath data directory because it cannot encrypt data files in place. It
must receive data from other replica set members during the initial sync. Please refer to the Switching Storage Engines
for more information on migration of encrypted data. Contact us for working at the detailed migration steps, if further
assistance is needed.
3.4. Upgrading to Percona Server for MongoDB with data at rest encryption enabled 21
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
FOUR
To upgrade Percona Server for MongoDB to version 4.4, you must be running version 4.2. Upgrades from earlier
versions are not supported.
Before upgrading your production Percona Server for MongoDB deployments, test all your applications in a testing
environment to make sure they are compatible with the new version. For more information, see Compatibility Changes
in MongoDB 4.4
The general procedure for performing an in-place upgrade (where your existing data and configuration files are pre-
served) includes the following steps:
1. Stop the mongod instance
2. Enable Percona repository for Percona Server for MongoDB 4.4
3. Install new packages. Old packages are considered obsolete and automatically removed
4. Start the mongod instance
It is recommended to upgrade Percona Server for MongoDB from official Percona repositories using the corresponding
package manager for your system. For more information, see Installing Percona Server for MongoDB.
Warning: Perform a full backup of your data and configuration files before upgrading.
See also:
23
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
MongoDB Documentation:
• Upgrade a Standalone
• Upgrade a Replica Set
• Upgrade a Sharded Cluster
See also:
MongoDB Documentation:
• Upgrade a Standalone
• Upgrade a Replica Set
• Upgrade a Sharded Cluster
Features
25
CHAPTER
FIVE
Percona Memory Engine is a special configuration of WiredTiger that does not store user data on disk. Data fully
resides in the main memory, making processing much faster and smoother. Keep in mind that you need to have
enough memory to hold the data set, and ensure that the server does not shut down.
The Percona Memory Engine is available in Percona Server for MongoDB along with the default MongoDB engine
WiredTiger.
As of version 3.2, Percona Server for MongoDB runs with WiredTiger by default. You can select a storage engine using
the --storageEngine command-line option when you start mongod. Alternatively, you can set the storage.
engine variable in the configuration file (by default, /etc/mongod.conf):
See also:
MongoDB Documentation: Configuration File Options
• storage.engine Options
• storage.wiredTiger Options
• storage.inmemory Options
Data files created by one storage engine are not compatible with other storage engines, because each one has its own
data model.
When changing the storage engine, the mongod node requires an empty dbPath data directory when it is restarted.
Though Percona Memory Engine stores all data in memory, some metadata files, diagnostics logs and statistics metrics
are still written to disk. This is controlled using the --inMemoryStatisticsLogDelaySecs option.
To change a storage engine, you have the following options:
• If you simply want to temporarily test Percona Memory Engine, set a different data directory for the dbPath
variable in the configuration file. Make sure that the user running mongod has read and write permissions for
the new data directory.
27
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
• If you want to permanently switch to Percona Memory Engine and do not have any valuable data in your
database, clean out the dbPath data directory (by default, /var/lib/mongodb) and edit the configuration
file:
$ service mongod stop
$ rm -rf <dbpathDataDir>
$ # Update the configuration file by setting the new
$ # value for the storage.engine variable
$ # set the engine-specific settings such as
$ # storage.inMemory.engineConfig.inMemorySizeGB
$ service mongod start
• If there is data that you want to migrate and make compatible with Percona Memory Engine, use the following
methods:
– for replica sets, use the “rolling restart” process. Switch to the Percona Memory Engine on the secondary
node. Clean out the dbPath data directory and edit the configuration file:
$ service mongod stop
$ rm -rf <dbpathDataDir>
$ # Update the configuration file by setting the new
$ # value for the storage.engine variable
$ # set the engine-specific settings such as
$ # storage.inMemory.engineConfig.inMemorySizeGB
$ service mongod start
Wait for the node to rejoin with the other nodes and report the SECONDARY status.
Repeat the procedure to switch the remaining nodes to Percona Memory Engine.
– for a standalone instance or a single-node replica set, use the mongodump and mongorestore utilities:
$ mongodump --out <dumpDir>
$ service mongod stop
$ rm -rf <dbpathDataDir>
$ # Update the configuration file by setting the new
$ # value for the storage.engine variable
$ # set the engine-specific settings such as
$ # storage.inMemory.engineConfig.inMemorySizeGB
$ service mongod start
$ mongorestore <dumpDir>
You can configure the Percona Memory Engine using either command-line options or corresponding parameters in the
/etc/mongod.conf file. The configuration file is formatted in YAML. For example:
storage:
engine: inMemory
inMemory:
engineConfig:
inMemorySizeGB: 140
statisticsLogDelaySecs: 0
Setting parameters in the previous example configuration file is the same as starting the mongod daemon with the
following options:
$ mongod --storageEngine=inMemory \
--inMemorySizeGB=140 \
--inMemoryStatisticsLogDelaySecs=0
The following options are available (with corresponding YAML configuration file parameters):
option --inMemorySizeGB
Config storage.inMemory.engineConfig.inMemorySizeGB
Default 50% of total memory minus 1024 MB, but not less than 256 MB
Specifies the maximum memory in gigabytes to use for data.
option --inMemoryStatisticsLogDelaySecs
Config storage.inMemory.engineConfig.statisticsLogDelaySecs
Default 0
Specifies the number of seconds between writes to statistics log. If 0 is specified then statistics are not logged.
SIX
HOT BACKUP
Percona Server for MongoDB includes an integrated open-source hot backup system for the default WiredTiger storage
engine. It creates a physical data backup on a running server without notable performance and operating degradation.
• Making a backup
• Saving a backup to a TAR archive
• Streaming hot backups to a remote destination
– Credentials
– Examples
• Restoring data from backup
Making a backup
To take a hot backup of the database in your current dbpath, do the following:
• Make sure to provide access to the backup directory for the mongod user
chown mongod:mongod <backupDir>
• Run the createBackup command as administrator on the admin database and specify the backup directory.
> use admin
switched to db admin
> db.runCommand({createBackup: 1, backupDir: <backup_data_path})
{ "ok" : 1 }
If the backup was successful, you should receive an { "ok" : 1 } object. If there was an error, you will receive
a failing ok status with the error message, for example:
> db.runCommand({createBackup: 1, backupDir: ""})
{ "ok" : 0, "errmsg" : "Destination path must be absolute" }
Implementation details
31
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Percona Server for MongoDB enables uploading hot backups to an Amazon S3 or a compatible storage service, such
as MinIO.
This method requires that you provide the bucket field in the s3 object:
In addition to the mandatory bucket field, the s3 object may contain the following fields:
Field Type Description
bucket string The only mandatory field. Names are subject to restrictions described in the Bucket
Restrictions and Limitations section of Amazon S3 documentation
path string The virtual path inside the specified bucket where the backup will be created. If the path is
not specified then the backup is created in the root of the bucket. If there are any objects
under the specified path, the backup will not be created and an error will be reported.
endpoint string The endpoint address and port - mainly for AWS S3 compatible servers such as the MinIO
server. For a local MinIO server, this can be “127.0.0.1:9000”. For AWS S3 this field can be
omitted.
scheme string “HTTP” or “HTTPS” (default). For a local MinIO server started with the minio server
command this should field should contain HTTP.
useVirtual- bool The style of addressing buckets in the URL. By default ‘true’. For MinIO servers, set this
Addressing field to false. For more information, see Virtual Hosting of Buckets in the Amazon S3
documentation.
region string The name of an AWS region. The default region is US_EAST_1. For more information see
AWS Service Endpoints in the Amazon S3 documentation.
profile string The name of a credentials profile in the credentials configuration file. If not specified, the
profile named default is used.
ac- string The access key id
cessKeyId
secretAc- string The secret access key
cessKey
Credentials
If the user provides the access key id and the secret access key parameters, these are used as credentials.
If the access key id parameter is not specified then the credentials are loaded from the credentials configuration file.
By default, it is ~/.aws/credentials.
[default]
aws_access_key_id = ABC123XYZ456QQQAAAFFF
aws_secret_access_key = zuf+secretkey0secretkey1secretkey2
[localminio]
aws_access_key_id = ABCABCABCABC55566678
aws_secret_access_key = secretaccesskey1secretaccesskey2secretaccesskey3
Examples
See also:
AWS Documentation: Providing AWS Credentials https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/
credentials.html
To restore your database on a standalone server, stop the mongod service, clean out the data directory and copy files
from the backup directory to the data directory. The mongod user requires access to those files to start the service.
Therefore, make the mongod user the owner of the data directory and all files and subdirectories under it, and restart
the mongod service.
Run the following commands as root or by using the sudo command
The recommended way to restore the replica set from a backup is to restore it into a standalone node and then initiate
it as the first member of a new replica set.
Note: If you try to restore the node into the existing replica set and there is more recent data, the restored node detects
that it is out of date with the other replica set members, deletes the data and makes an initial sync.
2. Clean the data directory and then copy the files from the backup directory to your data directory. Assuming that
the data directory is /var/lib/mongodb/, use the following commands:
$ rm -rf /var/lib/mongodb/*
$ cp -RT <backup_data_path> /var/lib/mongodb/
4. Make sure the replication is disabled in the config file and start the mongod service.
5. Connect to your standalone node via the mongo shell and drop the local database
> mongo
> use local
> db.dropDatabase()
SEVEN
Percona Server for MongoDB can limit the number of queries collected by the database profiler to decrease its impact
on performance. Rate limit is an integer between 1 and 1000 and represents the fraction of queries to be profiled. For
example, if you set it to 20, then every 20th query will be logged. For compatibility reasons, rate limit of 0 is the same
as setting it to 1, and will effectively disable the feature meaning that every query will be profiled.
The MongoDB database profiler can operate in one of three modes:
• 0: Profiling is disabled. This is the default setting.
• 1: The profiler collects data only for slow queries. By default, queries that take more than 100 milliseconds to
execute are considered slow.
• 2: Collects profiling data for all database operations.
Mode 1 ignores all fast queries, which may be the cause of problems that you are trying to find. Mode 2 provides a
comprehensive picture of database performance, but may introduce unnecessary overhead.
With rate limiting you can collect profiling data for all database operations and reduce overhead by sampling queries.
Slow queries ignore rate limiting and are always collected by the profiler.
The sampleRate option (= slowOpSampleRate config file option) is a similar concept to rateLimit. But it works
at different profile level, completely ignores operations faster than slowOpsThresholdMs (a.k.a. slowMs), and
affects the log file printing, too.
sampleRate rateLimit
Affects profiling level 1 yes no
Affects profiling level 2 no yes
Discards/filters slow ops yes no
Discards/filters fast ops no yes
Affects log file yes no
Example value of option 0.02 50
rateLimit is a better way to have continuous profiling for monitoring or live analysis purposes. sampleRate
requires setting slowOpsThresholdMs to zero if you want to sample all types of operations. sampleRate has an
effect on the log file which may either decrease or increase the log volume.
To enable rate limiting, set the profiler mode to 2 and specify the value of the rate limit. Optionally, you can also
change the default threshold for slow queries, which will not be sampled by rate limiting.
37
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
For example, to set the rate limit to 100 (profile every 100th fast query) and the slow query threshold to 200 (profile
all queries slower than 200 milliseconds), run the mongod instance as follows:
To do the same at runtime, use the profile command. It returns the previous settings and "ok" : 1 indicates
that the operation was successful:
If you want to set or get just the rate limit value, use the profilingRateLimit parameter on the admin database:
{ "was" : 1, "ok" : 1 }
> db.getSiblingDB('admin').runCommand( { getParameter: 1, "profilingRateLimit": 1 } );
{ "profilingRateLimit" : 100, "ok" : 1 }
If you want rate limiting to persist when you restart mongod, set the corresponding variables in the MongoDB con-
figuration file (by default, /etc/mongod.conf):
operationProfiling:
mode: all
slowOpThresholdMs: 200
rateLimit: 100
Note: The value of the operationProfiling.mode variable is a string, which you can set to either off,
slowOp, or all, corresponding to profiling modes 0, 1, and 2.
Each document in the system.profile collection includes an additional rateLimit field. This field always has
the value of 1 for slow queries and the current rate limit value for fast queries.
EIGHT
EXTERNAL AUTHENTICATION
Normally, a client needs to authenticate themselves against the MongoDB server user database before doing any work
or reading any data from a mongod or mongos instance. External authentication allows the MongoDB server to
verify the client’s user name and password against a separate service, such as OpenLDAP or Active Directory. This
allows users accessing the database with the same credentials they use for their emails or workstations.
Percona Server for MongoDB supports the following external authentication mechanisms:
• LDAP authentication using SASL
• Authentication and Authorization with Direct Binding to LDAP
• Kerberos Authentication
Overview
39
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
This section describes an example configuration suitable only to test out the external authentication functionality in a
non-production environment. Use common sense to adapt these guidelines to your production.
The following components are required:
• slapd: OpenLDAP server.
• libsasl2 version 2.1.25 or later.
• saslauthd: SASL Authentication Daemon (distinct from libsasl2).
The following steps will help you configure your environment:
• Configuring saslauthd
– Microsoft Windows Active Directory
• Sanity check
• Configuring libsasl2
• Configuring mongod Server
Assumptions
Configuring saslauthd
1. Install the SASL packages. Depending on your OS, use the following command:
For RedHat and CentOS:
For RedHat/CentOS, specify the ldap value for the --MECH option using the following command:
MECH=ldap
For Debian/Ubuntu, use the following commands to enable the saslauthd to auto-run on startup and to set
the ldap value for the --MECHANISMS option:
START=yes
MECHANISMS="ldap"
3. Create the /etc/saslauthd.conf configuration file and specify these settings required for saslauthd
to connect to a local OpenLDAP service (the server address MUST match the OpenLDAP installation):
ldap_servers: ldap://localhost
ldap_mech: PLAIN
ldap_search_base: dc=example,dc=com
ldap_filter: (cn=%u)
ldap_bind_dn: cn=admin,dc=example,dc=com
ldap_password: secret
Note the LDAP password and bind domain name. This allows the saslauthd service to connect to the LDAP
service as root. In production, this would not be the case; users should not store administrative passwords in
unencrypted files.
In order for LDAP operations to be performed against a Windows Active Directory server, a user record must be
created to perform the lookups.
The following example shows configuration parameters for saslauthd to communicate with an Active Directory
server:
ldap_servers: ldap://localhost
ldap_mech: PLAIN
ldap_search_base: CN=Users,DC=example,DC=com
ldap_filter: (sAMAccountName=%ucn=%u)
ldap_bind_dn: CN=ldapmgr,CN=Users,DC=<AD Domain>,DC=<AD TLD>
ldap_password: ld@pmgr_Pa55word
In order to determine and test the correct search base and filter for your Active Directory installation, the Microsoft
LDP GUI Tool can be used to bind and search the LDAP-compatible directory.
1. Give write permissions to the /run/saslauthd folder for the mongod. Either change permissions to the
/run/saslauthd folder:
Sanity check
Verify that the saslauthd service can authenticate against the users created in the LDAP service:
This should return 0:OK "Success". If it doesn’t, then either the user name and password are not in the LDAP
service, or sasaluthd is not configured properly.
Configuring libsasl2
The mongod also uses the SASL library for communications. To configure the SASL library, create a configuration
file.
The configuration file must be named mongodb.conf and placed in a directory where libsasl2 can find and read
it. libsasl2 is hard-coded to look in certain directories at build time. This location may be different depending on
the installation method.
In the configuration file, specify the following:
pwcheck_method: saslauthd
saslauthd_path: /var/run/saslauthd/mux
log_level: 5
mech_list: plain
The first two entries (pwcheck_method and saslauthd_path) are required for mongod to successfully use the
saslauthd service. The log_level is optional but may help determine configuration errors.
See also:
SASL documentation:
To enable external authentication, you must create a user with the root privileges in the admin database. If you have
already created this user, skip this step. Otherwise, run the following command to create the admin user:
security:
authorization: enabled
setParameter:
authenticationMechanisms: PLAIN,SCRAM-SHA-1
When everything is configured properly, you can use the External Authentication Commands.
Use the following command to add an external user to the mongod server:
The previous example assumes that you have set up the server-wide admin user/role and have successfully authenti-
cated as that user locally.
Note: External users cannot have roles assigned in the admin database.
When running the mongo client, a user can authenticate against a given database using the following command:
This feature has been supported in MongoDB Enterprise since its version 3.4.
As of version 4.4.2-4, Percona Server for MongoDB supports LDAP referrals as defined in RFC 4511 4.1.10. For
security reasons, LDAP referrals are disabled by default. Double-check that using referrals is safe before enabling
them.
To enable LDAP referrals, set the ldapFollowReferrals server parameter to true either using the
setParameter command or editing the configuration file.
setParameter:
ldapFollowReferrals: true
Connection pool
As of version 4.4.2-4, Percona Server for MongoDB always uses a connection pool to LDAP server to process authen-
tication requests. The connection pool is enabled by default. The default connection pool size is 2 connections.
You can change the connection pool size either at the server startup or dynamically by specifying the value for the
ldapConnectionPoolSizePerHost server parameter.
For example, to set the number of connections in the pool to 5, use the setParameter command:
setParameter:
ldapConnectionPoolSizePerHost: 5
As of version 4.4.3-5, you can specify multiple LDAP servers for failover. Percona Server for MongoDB sends
authentication requests to the first server defined in the list. When this server is down or unavailable, it sends requests
to the next server and so on. Note that Percona Server for MongoDB keeps sending requests to this server even after
the unavailable server recovers.
Specify the LDAP servers as a comma-separated list in the format <host>:<port> for the –ldapServers option.
You can define the option value at the server startup by editing the configuration file.
security:
authorization: "enabled"
ldap:
servers: "ldap1.example.net,ldap2.example.net"
See also:
MongoDB Documentation:
• LDAP Authorization
• Authenticate and Authorize Users Using Active Directory via Native LDAP
• LDAP referrals
Kerberos Authentication
Percona Server for MongoDB supports Kerberos authentication starting from release 4.2.6-6. It is implemented the
same way as in MongoDB Enterprise.
See also:
MongoDB Documentation:
• Kerberos Authentication
NINE
AUDITING
Auditing allows administrators to track and log user activity on a MongoDB server. With auditing enabled, the server
will generate an audit log file. This file contains information about different user events including authentication,
authorization failures, and so on.
To enable audit logging, specify where to send audit events using the --auditDestination option on the com-
mand line or the auditLog.destination variable in the configuration file.
If you want to output events to a file, also specify the format of the file using the --auditFormat option or the
auditLog.format variable, and the path to the file using the --auditPath option or the auditLog.path
variable.
To filter recorded events, use the --auditFilter option or the auditLog.filter variable.
For example, to log only events from a user named tim and write them to a JSON file /var/log/psmdb/audit.
json, start the server with the following parameters:
mongod \
--dbpath data/db
--auditDestination file \
--auditFormat JSON \
--auditPath /var/log/psmdb/audit.json \
--auditFilter '{ "users.user" : "tim" }'
The options in the previous example can be used as variables in the MongoDB configuration file:
storage:
dbPath: data/db
auditLog:
destination: file
format: JSON
path: /var/log/psmdb/audit.json
filter: '{ "users.user" : "tim" }'
This example shows how to send audit events to the syslog. Specify the following parameters:
mongod \
--dbpath data/db
--auditDestination syslog \
storage:
dbPath: data/db
auditLog:
destination: syslog
47
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Note: If you start the server with auditing enabled, it cannot be disabled dynamically during runtime.
Audit Options
Audit log events that match this query will be logged. Events that do not match this query will be ignored.
For more information, see Audit Filter Examples.
option --auditFormat
Variable auditLog.format
Type String
Specifies the format of the audit log file, if you set the --auditDestination option to file.
The default value is JSON. Alternatively, you can set it to BSON.
option --auditPath
Variable auditLog.path
Type String
Specifies the fully qualified path to the file where audit log events are written, if you set the
--auditDestination option to file.
If this option is not specified, then the auditLog.json file is created in the server’s configured log path. If
log path is not configured on the server, then the auditLog.json file is created in the current directory (from
which mongod was started).
48 Chapter 9. Auditing
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Note: This file will rotate in the same manner as the system log path, either on server reboot or using the
logRotate command. The time of rotation will be added to the old file’s name.
Audit logging writes messages in JSON format with the following syntax:
{
atype: <String>,
ts : { "$date": <timestamp> },
local: { ip: <String>, port: <int> },
remote: { ip: <String>, port: <int> },
users : [ { user: <String>, db: <String> }, ... ],
roles: [ { role: <String>, db: <String> }, ... ],
param: <document>,
result: <int>
}
auditLog:
destination: file
filter: '{atype: {$in: [
"authenticate", "authCheck",
"renameCollection", "dropCollection", "dropDatabase",
"createUser", "dropUser", "dropAllUsersFromDatabase", "updateuser",
"grantRolesToUser", "revokeRolesFromUser", "createRole", "updateRole",
"dropRole", "dropAllRolesFromDatabase", "grantRolesToRole",
˓→"revokeRolesFromRole",
"grantPrivilegesToRole", "revokePrivilegesFromRole",
"replSetReconfig",
"enableSharding", "shardCollection", "addShard", "removeShard",
"shutdown",
"applicationMessage"
]}}'
You can use query selectors, such as $eq, $in, $gt, $lt, $ne, and others to log multiple event types.
For example, to log only the dropCollection and dropDatabase events:
• Command line:
--auditDestination file --auditFilter '{ atype: { $in: [ "dropCollection",
˓→"dropDatabase" ] } }'
• Config file:
auditLog:
destination: file
filter: '{ atype: { $in: [ "dropCollection", "dropDatabase" ] } }'
Regular Expressions
• Config file:
auditLog:
destination: file
filter: '{ "atype" : /^drop.*/ }'
By default, operations with successful authorization are not logged, so for this filter to work, enable
auditAuthorizationSuccess parameter, as described in Enabling Auditing of Authorization Success.
For example, to filter read and write operations on all the collections in the test database:
Note: The dot (.) after the database name in the regular expression must be escaped with two backslashes (\\).
• Command line:
--setParameter auditAuthorizationSuccess=true --auditDestination file --
˓→auditFilter '{ atype: "authCheck", "param.command": { $in: [ "find", "insert",
50 Chapter 9. Auditing
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
• Config file:
auditLog:
destination: file
filter: '{ atype: "authCheck", "param.command": { $in: [ "find", "insert",
˓→"delete", "update", "findandmodify" ] }, "param.ns": /^test\\./ } }'
By default, only authorization failures for the authCheck action are logged by the audit system. authCheck is for
authorization by role-based access control, it does not concern authentication at logins.
To enable logging of authorization successes, set the auditAuthorizationSuccess parameter to true. Audit
events will then be triggered by every command, including CRUD ones.
Warning: Enabling the auditAuthorizationSuccess parameter heavily impacts the performance com-
pared to logging only authorization failures.
To enable it on the command line, use the following option when running mongod or mongos process:
--setParameter auditAuthorizationSuccess=true
setParameter:
auditAuthorizationSuccess: true
52 Chapter 9. Auditing
CHAPTER
TEN
LOG REDACTION
Percona Server for MongoDB can prevent writing sensitive data to the diagnostic log by redacting messages of events
before they are logged. To enable log redaction, run mongod with the --redactClientLogData option.
Note: Metadata such as error or operation codes, line numbers, and source file names remain visible in the logs.
Log redaction is important for complying with security requirements, but it can make troubleshooting and diagnostics
more difficult due to the lack of data related to the log event. For this reason, debug messages are not redacted even
when log redaction is enabled. Keep this in mind when switching between log levels.
You can permanently enable log redaction by adding the following to the configuration file:
security:
redactClientLogData: true
db.adminCommand(
{ setParameter: 1, redactClientLogData : true }
)
53
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
ELEVEN
ENABLING AUTHENTICATION
By default, Percona Server for MongoDB does not restrict access to data and configuration.
To enable authentication and automatically set it up, run the /usr/bin/
percona-server-mongodb-enable-auth.sh script as root or using sudo. This script creates the
dba user with the root role. The password is randomly generated and printed out in the output. Then it restarts
Percona Server for MongoDB with access control enabled. The dba user has full superuser privileges on the server.
You can add other users with various roles depending on your needs.
For usage information, run the script with the -h option.
To enable access control manually:
1. Add the following lines to the configuration file:
security:
authorization: enabled
55
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
TWELVE
Data at rest encryption for the WiredTiger storage engine in MongoDB was introduced in MongoDB Enterprise version
3.2 to ensure that encrypted data files can be decrypted and read by parties with the decryption key.
See also:
MongoDB Documentation: Encryption at Rest https://docs.mongodb.com/manual/core/
security-encryption-at-rest/#encryption-at-rest
The data encryption at rest in Percona Server for MongoDB is introduced in version 3.6 to be compatible with data
encryption at rest interface in MongoDB. In the current release of Percona Server for MongoDB, the data encryp-
tion at rest does not include support for KMIP (Key Management Interoperability Protocol), or Amazon AWS key
management services.
Two types of keys are used for data at rest encryption:
• Database keys to encrypt data. They are stored internally, near the data that they encrypt.
• The master key to encrypt database keys. It is kept separately from the data and database keys and requires
external management.
To manage the master key, use one of the supported key management options:
• Integration with an external key server (recommended). Percona Server for MongoDB is integrated with
HashiCorp Vault for this purpose.
• Local key management using a keyfile.
Note that you can use only one of the key management options at a time. However, you can switch from one man-
agement option to another (e.g. from a keyfile to HashiCorp Vault). Refer to Migrating from Key File Encryption to
HashiCorp Vault Encryption section for details.
Important: You can only enable data at rest encryption and provide all encryption settings on an empty database,
when you start the mongod instance for the first time. You cannot enable or disable encryption while the Percona
Server for MongoDB server is already running and / or has some data. Nor can you change the effective encryption
mode by simply restarting the server. Every time you restart the server, the encryption settings must be the same.
57
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Percona Server for MongoDB supports the encryptionCipherMode option where you choose one of the follow-
ing cipher modes:
• AES256-CBC
• AES256-GCM
By default, the AES256-CBC cipher mode is applied. The following example demonstrates how to apply the AES256-
GCM cipher mode when starting the mongod service:
See also:
MongoDB Documentation: encryptionCipherMode Option https://docs.mongodb.com/manual/reference/
program/mongod/#cmdoption-mongod-encryptionciphermode
Percona Server for MongoDB is integrated with HashiCorp Vault. HashiCorp Vault supports different secrets engines.
Percona Server for MongoDB only supports the HashiCorp Vault back end with KV Secrets Engine - Version 2 (API)
with versioning enabled.
See also:
Percona Blog: Using Vault to Store the Master Key for Data at Rest Encryption on Percona Server for MongoDB
https://www.percona.com/blog/2020/04/21/using-vault-to-store-the-master-key-for-data-at-rest-encryption-on-percona-server-fo
How to configure the KV Engine: https://www.vaultproject.io/api/secret/kv/kv-v2.html
˓→<custom_path>
where:
•
<vault_secret_mount>
is your Vault KV
Secrets Engine;
• data is the manda-
tory path prefix re-
quired by Version 2
API;
• <custom_path>
is your secrets path
Example:
secret_v2/data/
˓→psmdb-test/rs1-
˓→27017
Note: It is recommended
to use different secret
paths for every database
node.
vaultRotateMasterKey security.vault.rotateMasterKey
switch Enables master key rota-
tion
vaultServerCAFile security.vault.serverCAFile string The path to the TLS cer-
tificate file
vaultDisableTLSForTesting security.vault.disableTLSForTesting
switch Disables secure connec-
tion to HashiCorp Vault
using SSL/TLS client cer-
tificates
security:
enableEncryption: true
vault:
serverName: 127.0.0.1
port: 8200
tokenFile: /home/user/path/token
secret: secret/data/hello
During the first run of the Percona Server for MongoDB, the process generates a secure key and writes the key to the
vault.
During the subsequent start, the server tries to read the master key from the vault. If the configured secret does not
exist, vault responds with HTTP 404 error.
Key Rotation
Key rotation is replacing the old master key with a new one. This process helps to comply with regulatory require-
ments.
To rotate the keys for a single mongod instance, do the following:
1. Stop the mongod process
2. Add --vaultRotateMasterKey option via the command line or security.vault.
rotateMasterKey to the config file.
3. Run the mongod process with the selected option, the process will perform the key rotation and exit.
4. Remove the selected option from the startup command or the config file.
5. Start mongod again.
Rotating the master key process also re-encrypts the keystore using the new master key. The new master key is stored
in the vault. The entire dataset is not re-encrypted.
For a replica set, the steps are the following:
1. Rotate the master key for the secondary nodes one by one.
2. Step down the primary and wait for another primary to be elected.
3. Rotate the master key for the previous primary node.
The key file must contain a 32 character string encoded in base64. You can generate a random key and save it to a file
by using the openssl command:
Then, as the owner of the mongod process, update the file permissions: only the owner should be able to read and
modify this file. The effective permissions specified with the chmod command can be:
• 600 - only the owner may read and modify the file
Enable the data encryption at rest in Percona Server for MongoDB by setting these options:
• --enableEncryption to enable data at rest encryption
• --encryptionKeyFile to specify the path to a file that contains the encryption key
By default, Percona Server for MongoDB uses the AES256-CBC cipher mode. If you want to use the AES256-GCM
cipher mode, then use the encryptionCipherMode parameter to change it.
If mongod is started with the --relaxPermChecks option and the key file is owned by root, then mongod can
read the file based on the group bit set accordingly. The effective key file permissions in this case are:
• 440 - both the owner and the group can only read the file, or
• 640 - only the owner can read and the change the file, the group can only read the file.
See also:
MongoDB Documentation: Configure Encryption https://docs.mongodb.com/manual/tutorial/
configure-encryption/#local-key-management
Percona Blog: WiredTiger Encryption at Rest with Percona Server for MongoDB https://www.percona.com/
blog/2018/11/01/wiredtiger-encryption-at-rest-percona-server-for-mongodb/
All these options can be specified in the configuration file:
security:
enableEncryption: <boolean>
encryptionCipherMode: <string>
encryptionKeyFile: <string>
relaxPermChecks: <boolean>
See also:
MongoDB Documentation: How to set options in a configuration file https://docs.mongodb.com/manual/
reference/configuration-options/index.html#configuration-file
Starting from version 3.6, Percona Server for MongoDB also encrypts rollback files when data at rest encryption is
enabled. To inspect the contents of these files, use perconadecrypt. This is a tool that you run from the command
line as follows:
When decrypting, the cipher mode must match the cipher mode which was used for the encryption. By default, the
--encryptionCipherMode option uses the AES256-CBC mode.
Parameters of perconadecrypt
Option Purpose
–encryptionKeyFile The path to the encryption key file
– The cipher mode for decryption. The supported values are AES256-CBC or
encryptionCipherMode AES256-GCM
–inputPath The path to the encrypted rollback file
–outputPath The path to save the decrypted rollback file
The steps below describe how to migrate from the key file encryption to using HashiCorp Vault.
Note: This is a simple guideline and it should be used for testing purposes only. We recommend to use Percona
Consulting Services to assist you with migration in production environment.
Assumptions
We assume that you have installed and configured the vault server and enabled the KV Secrets Engine as the secrets
storage for it.
1. Stop mongod.
2. Insert the key from keyfile into the HashiCorp Vault server to the desired secret path.
Note: Vault KV Secrets Engine uses different read and write secrets paths. To insert data to vault, specify the
secret path without the data/ prefix.
3. Edit the configuration file to provision the HashiCorp Vault configuration options instead of the key file encryp-
tion options.
security:
enableEncryption: true
vault:
serverName: 10.0.2.15
port: 8200
secret: secret/data/dc/psmongodb1
tokenFile: /etc/mongodb/token
serverCAFile: /etc/mongodb/vault.crt
THIRTEEN
The ngram text search algorithm is useful for searching text for a specific string of characters in a field of a collection.
This feature can be used to find exact sub-string matches, which provides an alternative to parsing text from languages
other than the list of European languages already supported by MongoDB Community’s full text search engine. It
may also turn out to be more convenient when working with the text where symbols like dash(‘-‘), underscore(‘_’), or
slash(“/”) are not token delimiters.
Unlike MongoDB full text search engine, ngram search algorithm uses only the following token delimiter characters
that do not count as word characters in human languages:
• Horizontal tab
• Vertical tab
• Line feed
• Carriage return
• Space
The ngram text search is slower than MongoDB full text search.
Usage
To use ngram, create a text index on a collection setting the default_language parameter to ngram:
ngram search algorithm treats special characters like individual terms. Therefore, you don’t have to enclose the search
string in escaped double quotes (\") to query the text index. For example, to search for documents that contain the
date 2021-02-12, specify the following:
However, both ngram and MongoDB full text search engine treat words with the hyphen-minus - sign in front of them
as negated (e.g. “-coffee”) and exclude such words from the search results.
See also:
MongoDB documentation:
• Text search
• Text indexes
• $text operator
65
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Reference
67
CHAPTER
FOURTEEN
By default, Percona Server for MongoDB runs with WiredTiger. There is also the original MMAPv1 storage engine,
as well as an optional Percona Memory Engine storage engine to choose from. Each storage engine is designed for
specific purposes and workloads.
You can select a storage engine using the --storageEngine command-line option when you start mongod. Alter-
natively, you can set the storage.engine variable in the configuration file (by default, /etc/mongod.conf).
See also:
MongoDB Documentation: Configuration File Options
• storage.engine Options
• storage.wiredTiger Options
• storage.inmemory Options
Data files created by one storage engine are not compatible with the other storage engines, because each one has its
own data model.
When changing the storage engine, the mongod node requires an empty dbPath data directory when it is restarted
even when using Percona Memory Engine. Though in-memory storage engine stores all data in memory, some meta-
data files, diagnostics logs and statistics metrics are still written to disk.
Creating a new dbPath data directory for a different storage engine is the simplest solution. Yet when you switch
between disk-using storage engines (e.g. from WiredTiger to Percona Memory Engine), you may have to delete the
old data if there is not enough disk space for both. Double-check that your backups are solid and/or the replica set
nodes are healthy to before you switch to the new storage engine.
If there is data that you want to migrate and make compatible with the new storage engine, use the following methods:
• for replica sets, use the “rolling restart” process.
Switch to the new storage engine on the secondary node. Clean out the dbPath data directory (by default ,
/var/lib/mongodb) and edit the configuration file:
Wait for the node to rejoin with the other replica set members and report the SECONDARY status.
Repeat the procedure on the remaining nodes.
69
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
• for a standalone instance or a single-node replica set, use the mongodump and mongorestore utilities:
Using Data at Rest Encryption means using the same storage.* configuration options as for WiredTiger. To
change from normal to Data at Rest Encryption mode or backward, you must clean up the dbPath data directory,
just as if you change the storage engine. This is because mongod cannot convert the data files to an encrypted format
‘in place’. It must get the document data again either via the initial sync from another replica set member, or from
imported backup dump.
FIFTEEN
Percona Server for MongoDB includes several parameters that can be changed in one of the following ways:
• The setParameter variables in the configuration file for persistent changes in production:
setParameter:
cursorTimeoutMillis: <int>
failIndexKeyTooLong: <boolean>
internalQueryPlannerEnableIndexIntersection: <boolean>
ttlMonitorEnabled: <boolean>
ttlMonitorSleepSecs: <int>
• The --setParameter option arguments when running the mongod process for development or testing pur-
poses:
$ mongod \
--setParameter cursorTimeoutMillis=<int> \
--setParameter failIndexKeyTooLong=<boolean> \
--setParameter internalQueryPlannerEnableIndexIntersection=<boolean> \
--setParameter ttlMonitorEnabled=<boolean> \
--setParameter ttlMonitorSleepSecs=<int>
> db = db.getSiblingDB('admin')
> db.runCommand( { setParameter: 1, cursorTimeoutMillis: <int> } )
> db.runCommand( { setParameter: 1, failIndexKeyTooLong: <boolean> } )
> db.runCommand( { setParameter: 1, internalQueryPlannerEnableIndexIntersection:
˓→<boolean> } )
variable cursorTimeoutMillis
Value Type integer
Default 600000 (ten minutes)
Sets the duration of time after which idle query cursors are removed from memory.
variable failIndexKeyTooLong
Value Type boolean
Default true
71
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Versions of MongoDB prior to 2.6 would insert and update documents even if an index key was too long. The
documents would not be included in the index. Newer versions of MongoDB ignore documents with long index
key. By setting this value to false, the old behavior is enabled.
variable internalQueryPlannerEnableIndexIntersection
Value Type boolean
Default true
Due to changes introduced in MongoDB 2.6.4, some queries that reference multiple indexed fields, where one
field matches no documents, may choose a non-optimal single-index plan. Setting this value to false will
enable the old behavior and select the index intersection plan.
variable ttlMonitorEnabled
Value Type boolean
Default true
If this option is set to false, the worker thread that monitors TTL Indexes and removes old documents will be
disabled.
variable ttlMonitorSleepSecs
Value Type integer
Default 60 (one minute)
Defines the number of seconds to wait between checking TTL Indexes for old documents and removing them.
SIXTEEN
Note: Please search the forum for similar questions and discussions before openning a new thread.
You will need to sign up for an account to post in the forum.
If you want to explore source code and contribute to the project use the GitHub repo.
Note: Search existing pull requests and recent commits for code that may fix what you are planning to suggest.
You will need a public GitHub account and request contributor access to the repo.
If you want to report a bug or feature request, use the PSMDB project in JIRA.
Note: Search JIRA for existing tickets before submitting a bug or feature request.
You will need a JIRA account to report bugs.
73
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
SEVENTEEN
Bugs Fixed
• PSMDB-817: LDAP ConnectionPoller always uses up CPU of one core (Thanks to user cleiton.domazak for
reporting this issue)
Improvements
75
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Bugs Fixed
• PSMDB-788: Fix LDAP rebind procedure to allow LDAP referrals to work with ldapBindMethod==sasl
Improvements
Bugs Fixed
Percona Server for MongoDB 4.4.1-2 is an enhanced, open source, and highly-scalable database that is a fully-
compatible, drop-in replacement for MongoDB 4.4.1 Community Edition. It supports MongoDB 4.4.1 protocols
and drivers.
Bugs Fixed
• PSMDB-707: LDAP authentication randomly fails with the “Bad parameter to an ldap routine” message in the
log
• PSMDB-677: mongosh cannot authenticate LDAP user
• PSMDB-674: Provide binary tarball with shared libs and glibc suffix
EIGHTEEN
GLOSSARY
ACID Set of properties that guarantee database transactions are processed reliably. Stands for Atomicity, Consistency,
Isolation, Durability.
Atomicity Atomicity means that database operations are applied following a “all or nothing” rule. A transaction is
either fully applied or not at all.
Consistency Consistency means that each transaction that modifies the database takes it from one consistent state to
another.
Durability Once a transaction is committed, it will remain so.
Foreign Key A referential constraint between two tables. Example: A purchase order in the purchase_orders table
must have been made by a customer that exists in the customers table.
Isolation The Isolation requirement means that no transaction can interfere with another.
Jenkins Jenkins is a continuous integration system that we use to help ensure the continued quality of the software
we produce. It helps us achieve the aims of:
• no failed tests in trunk on any platform,
• aid developers in ensuring merge requests build and test on all platforms,
• no known performance regressions (without a damn good explanation).
Rolling restart A rolling restart (rolling upgrade) is shutting down and upgrading nodes one by one. The whole
cluster remains operational. There is no interruption to clients assuming the elections are short and all writes
directed to the old primary use the retryWrite mechanism.
79
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
NINETEEN
Documentation Licensing
This software documentation is (C)2016-2021 Percona LLC and/or its affiliates and is distributed under the Creative
Commons Attribution 4.0 International License.
Software License
81
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
TWENTY
TRADEMARK POLICY
This Trademark Policy is to ensure that users of Percona-branded products or services know that what they receive
has really been developed, approved, tested and maintained by Percona. Trademarks help to prevent confusion in the
marketplace, by distinguishing one company’s or person’s products and services from another’s.
Percona owns a number of marks, including but not limited to Percona, XtraDB, Percona XtraDB, XtraBackup, Per-
cona XtraBackup, Percona Server, and Percona Live, plus the distinctive visual icons and logos associated with these
marks. Both the unregistered and registered marks of Percona are protected.
Use of any Percona trademark in the name, URL, or other identifying characteristic of any product, service, website,
or other use is not permitted without Percona’s written permission with the following three limited exceptions.
First, you may use the appropriate Percona mark when making a nominative fair use reference to a bona fide Percona
product.
Second, when Percona has released a product under a version of the GNU General Public License (“GPL”), you may
use the appropriate Percona mark when distributing a verbatim copy of that product in accordance with the terms and
conditions of the GPL.
Third, you may use the appropriate Percona mark to refer to a distribution of GPL-released Percona software that has
been modified with minor changes for the sole purpose of allowing the software to operate on an operating system
or hardware platform for which Percona has not yet released the software, provided that those third party changes
do not affect the behavior, functionality, features, design or performance of the software. Users who acquire this
Percona-branded software receive substantially exact implementations of the Percona software.
Percona reserves the right to revoke this authorization at any time in its sole discretion. For example, if Percona
believes that your modification is beyond the scope of the limited license granted in this Policy or that your use
of the Percona mark is detrimental to Percona, Percona will revoke this authorization. Upon revocation, you must
immediately cease using the applicable Percona mark. If you do not immediately cease using the Percona mark upon
revocation, Percona may take action to protect its rights and interests in the Percona mark. Percona does not grant any
license to use any Percona mark for any other modified versions of Percona software; such use will require our prior
written permission.
Neither trademark law nor any of the exceptions set forth in this Trademark Policy permit you to truncate, modify or
otherwise use any Percona mark as part of your own brand. For example, if XYZ creates a modified version of the
Percona Server, XYZ may not brand that modification as “XYZ Percona Server” or “Percona XYZ Server”, even if
that modification otherwise complies with the third exception noted above.
In all cases, you must comply with applicable law, the underlying license, and this Trademark Policy, as amended from
time to time. For instance, any mention of Percona trademarks should include the full trademarked name, with proper
spelling and capitalization, along with attribution of ownership to Percona Inc. For example, the full proper name for
XtraBackup is Percona XtraBackup. However, it is acceptable to omit the word “Percona” for brevity on the second
and subsequent uses, where such omission does not cause confusion.
In the event of doubt as to any of the conditions or exceptions outlined in this Trademark Policy, please contact
[email protected] for assistance and we will do our very best to be helpful.
83
Percona Server for MongoDB 4.4 Documentation, Release 4.4.5-7
Symbols
–auditDestination (option), 48
–auditFilter (option), 48
–auditFormat (option), 48
–auditPath (option), 48
–inMemorySizeGB (option), 29
–inMemoryStatisticsLogDelaySecs (option), 29
A
ACID, 79
Atomicity, 79
C
Consistency, 79
cursorTimeoutMillis (variable), 71
D
Durability, 79
F
failIndexKeyTooLong (variable), 71
Foreign Key, 79
I
internalQueryPlannerEnableIndexIntersection (variable),
72
Isolation, 79
J
Jenkins, 79
R
Rolling restart, 79
T
ttlMonitorEnabled (variable), 72
ttlMonitorSleepSecs (variable), 72
85