Percona Server for MongoDB Documentation Release 3.2.22-3.13

Percona LLC and/or its affiliates 2015-2018

Jan 16, 2019

CONTENTS

I Introduction3

II Installation7

III Features 21

IV Reference 51

i ii Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Percona Server for MongoDB is a free, enhanced, fully compatible, open source, drop-in replacement for MongoDB 3.2 Community Edition with enterprise-grade features. It requires no changes to MongoDB applications or code. Percona Server for MongoDB provides the following features: • MongoDB’s original MMAPv1 storage engine, and the default WiredTiger engine • Optional PerconaFT, Percona Memory Engine, and MongoRocks storage engines • Percona TokuBackup for creating dynamic backups while data remains fully accessible and writable (hot backup) • External SASL authentication using OpenLDAP or Active Directory • Audit logging to track and query database interactions of users or applications

Note: PerconaFT has been deprecated and will not be available in future releases.

CONTENTS 1 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

2 CONTENTS Part I

Introduction

3

CHAPTER ONE

PERCONA SERVER FOR MONGODB FEATURE COMPARISON

Percona Server for MongoDB is based on MongoDB 3.2, and it is the successor to Percona TokuMX, which is based on MongoDB 2.4. Both MongoDB and Percona Server for MongoDB include a pluggable storage engine API. This enables you to select from a variety of storage engines depending on your needs. Previous MongoDB versions (before 3.0) and Percona TokuMX can run with only one default storage engine. The following table will help you evaluate the differences. PSMDB MongoDB TokuMX Storage Engines Built-in storage engine • WiredTiger (de- • WiredTiger (de- based on the Fractal Tree fault) fault) index • MMAPv1 • MMAPv1 • Percona Memory • In-Memory (Enter- Engine prise only) • MongoRocks • PerconaFT (depre- cated)

Hot Backup YES (for WiredTiger and NO YES MongoRocks) Audit Logging YES Enterprise only YES External SASL Authenti- YES Enterprise only NO cation Profiling Rate Limit YES NO NO Geospatial Indexes YES YES YES Text Search YES YES NO ACID and MVCC compli- NO NO YES ant Clustering Key Support NO NO YES Sharding with Clustering NO NO YES Keys Point-in-time Recovery NO Enterprise only YES

5 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

6 Chapter 1. Percona Server for MongoDB Feature Comparison Part II

Installation

7

CHAPTER TWO

INSTALLING PERCONA SERVER FOR MONGODB

Percona Server for MongoDB supports most 64-bit Linux distributions. Percona provides packages for the following systems:

Table 2.1: Linux distributions supported by Percona Server for MongoDB Supported Distributions Instructions Install on Debian or Ubuntu • Debian 8 (“jessie”) • Debian 9 (“stretch”) • Ubuntu 14.04 LTS (Trusty Tahr) • Ubuntu 16.04 LTS (Xenial Xerus) • Ubuntu 16.10 (Yakkety Yak) • Ubuntu 17.04 (Zesty Zapus)

Install on RHEL or CentOS • Red Hat Enterprise Linux / CentOS 5 • Red Hat Enterprise Linux / CentOS 6 • Red Hat Enterprise Linux / CentOS 7

Note: Percona Server for MongoDB should work on other Linux distributions (for example, Amazon Linux AMI and Oracle Linux), but it is tested only on platforms listed in the previous table.

Alternative Install Instructions

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

9 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Upgrade Instructions

If you are currently using MongoDB, see Upgrading from MongoDB.

Installing Percona Server for MongoDB on Debian and Ubuntu

Percona provides .deb packages for 64-bit versions of the following distributions: • Debian 8 (“jessie”) • Debian 9 (“stretch”) • Ubuntu 14.04 LTS (Trusty Tahr) • Ubuntu 16.04 LTS (Xenial Xerus) • Ubuntu 17.04 (Zesty Zapus) • Ubuntu 17.10 (Artful Aardvark)

Note: Percona Server for MongoDB should work on other DEB-based distributions, but it is tested only on platforms listed above.

• Package Contents • Installing from Repositories • Using Percona Server for MongoDB • Uninstalling Percona Server for MongoDB

Package Contents

percona-server-mongodb-32 Installs the mongo shell, import/export tools, other client utilities, server software, default configuration, and init.d scripts. percona-server-mongodb-32-server Contains the mongod server, default configuration files, and init.d scripts. percona-server-mongodb-32-shell Contains the mongo shell. percona-server-mongodb-32-mongos Contains the mongos sharded cluster query router. percona-server-mongodb-32-tools Contains Mongo tools for high-performance MongoDB fork from Percona. percona-server-mongodb-32-dbg Contains debug symbols for the server.

Installing from Repositories

It is recommended to install Percona Server for MongoDB from official Percona repositories: 1. Configure Percona repositories as described in Percona Software Repositories Documentation.

10 Chapter 2. Installing Percona Server for MongoDB Percona Server for MongoDB Documentation, Release 3.2.22-3.13

2. Install the required Percona Server for MongoDB package using apt-get. For example, to install the full package, run the following:

$ sudo apt-get install percona-server-mongodb-32

Using Percona Server for MongoDB

By default, Percona Server for MongoDB stores data files in /var/lib/mongodb/ and configuration parameters in /etc/mongod.conf. • Starting the service Percona Server for MongoDB is started automatically after installation unless it encounters errors during the installation process. You can also manually start it using the following command:

$ sudo service mongod start

• Confirming that service is running Check the service status using the following command:

$ sudo service mongod status

• Stopping the service Stop the service using the following command:

$ sudo service mongod stop

• Restarting the service Restart the service using the following command:

$ sudo service mongod restart

Note: On Debian 8, Ubuntu 16.04 and later versions you can also invoke all the above commands with sytemctl instead of service.

Uninstalling Percona Server for MongoDB

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-get purge will remove all the packages with configuration files and data. Depending on your needs you can choose which command better suits you. 1. Stop the server:

$ sudo service mongod stop

2. Remove the packages. • If you want to leave configuration and data files:

$ sudo apt-get remove percona-server-mongodb*

2.2. Upgrade Instructions 11 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

• If you want to delete configuration and data files as well as the packages:

$ sudo apt-get purge percona-server-mongodb*

Installing Percona Server for MongoDB on Red Hat Enterprise Linux and CentOS

Percona provides .rpm packages for 64-bit versions of the following distributions: • Red Hat Enterprise Linux / CentOS 5 • Red Hat Enterprise Linux / CentOS 61 • Red Hat Enterprise Linux / CentOS 7

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

• Package Contents • Installing from Percona Repository • Using Percona Server for MongoDB – Running after reboot • Uninstalling Percona Server for MongoDB

Package Contents

Percona-Server-MongoDB-32 Installs the mongo shell, import/export tools, other client utilities, server software, default configuration, and init.d scripts. Percona-Server-MongoDB-32-server Contains the mongod server, default configuration files, and init.d scripts. Percona-Server-MongoDB-32-shell Contains the mongo shell. Percona-Server-MongoDB-32-mongos Contains the mongos sharded cluster query router. Percona-Server-MongoDB-32-tools Contains Mongo tools for high-performance MongoDB fork from Percona. Percona-Server-MongoDB-32-debuginfo Contains debug symbols for the server.

Installing from Percona Repository

It is recommended to intall Percona Server for MongoDB from official Percona repositories: 1. Configure Percona repositories as described in Percona Software Repositories Documentation.

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.

12 Chapter 2. Installing Percona Server for MongoDB Percona Server for MongoDB Documentation, Release 3.2.22-3.13

2. Install the required Percona Server for MongoDB package using yum. For example, to install the full package, run the following:

$ sudo yum install Percona-Server-MongoDB-32

Using Percona Server for MongoDB

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 or not install them at all. 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. It runs as a service named mongod. • Starting the service Percona Server for MongoDB is not started automatically after installation. Start it manually using the following command:

$ sudo service mongod start

• Confirming that service is running Check the service status using the following command:

$ sudo service mongod status

• Stopping the service Stop the service using the following command:

$ sudo service mongod stop

• Restarting the service Restart the service using the following command:

$ sudo service mongod restart

Note: On Red Hat Enterprise Linux and CentOS 7 you can also invoke all the above commands with sytemctl instead of service.

2.2. Upgrade Instructions 13 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Running after reboot

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:

$ chkconfig --add mongod

For RHEL or CentOS version 7, you can use the systemctl utility as follows:

$ systemctl enable mongod

Uninstalling Percona Server for MongoDB

To completely uninstall Percona Server for MongoDB you’ll need to remove all the installed packages and data files: 1. Stop the Percona Server for MongoDB service:

$ sudo service mongod stop

2. Remove the packages:

$ sudo yum remove Percona-Server-MongoDB*

3. Remove the data and configuration files:

$ rm -rf /var/lib/mongodb $ rm -f /etc/mongod.cnf

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.

Installing Percona Server for MongoDB from Binary Tarball

You can find links to the binary tarballs from the Percona Server for MongoDB download page. 1. Fetch and extract the correct binary tarball. For example, if you are running Debian 8 (“jessie”):

wget https://www.percona.com/redir/downloads/percona-server-mongodb-3.2/LATEST/

˓→binary/debian/jessie/x86_64/psmdb-3.2.6-1.0-r24-jessie-x86_64-bundle.tar tar xfz psmdb-3.2.6-1.0-r24-jessie-x86_64-bundle.tar

2. Copy the extracted binaries to the target directory, for example:

mkdir ~/psmdb cp -r -n psmdb-3.2.6-1.0-r24-jessie-x86_64-bundle/bin ~/psmdb/

3. Add the location of the binaries to the PATH variable:

export PATH ~/psmdb/bin:$PATH

4. Create the default data directory:

14 Chapter 2. Installing Percona Server for MongoDB Percona Server for MongoDB Documentation, Release 3.2.22-3.13

mkdir -p /data/db

5. Make sure that you have read and write permissions for the data directory and run mongod.

Running Percona Server for MongoDB in a Docker Container

Docker images of Percona Server for MongoDB are hosted publicly on Decker 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 Percona Server for MongoDB 3.2 in a Docker container, use the following command:

docker run-d \ --name psmdb \ --restart always \ percona/percona-server-mongodb:3.2

The previous command does the following: • The docker run command instructs the docker daemon to run a container from an image. • The -d option starts the container in detached mode (that is, in the background). • The --name option assigns a custom name for the container that you can use to reference the container within a Docker network. In this case: psmdb. • The --restart option defines the container’s restart policy. Setting it to always ensures that the Docker daemon will start the container on startup and restart it if the container exits. • percona/percona-server-mongodb:3.2 is the name and version tag of the image to derive the con- tainer from. For full list of tags, see https://hub.docker.com/r/percona/percona-server-mongodb/tags/

Connecting from Another Docker Container

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.

Connecting with the Mongo Shell

To start another container with the mongo shell that connects to your Percona Server for MongoDB container, run the following comand:

docker run-it--link psmdb--rm percona/percona-server-mongodb:mongo mongo-h psmdb

2.2. Upgrade Instructions 15 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

If you are currently using Percona TokuMX, see Upgrading from Percona TokuMX.

16 Chapter 2. Installing Percona Server for MongoDB CHAPTER THREE

UPGRADING FROM MONGODB COMMUNITY EDITION TO PERCONA SERVER FOR MONGODB

Note: MongoDB creates a user that belongs to two groups, which is a potential security risk. This is fixed in Percona Server for MongoDB: 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.

An in-place upgrade is done with existing data in the server. Generally speaking, this is stopping the server, removing the old packages, installing the new server and starting it with the same data files. While an in-place upgrade may not be suitable for high-complexity environments, it should work in most cases. Upgrading from an earlier version of Percona Server for MongoDB (for example, from 3.0) is the same as upgrading from MongoDB 3.0 or 3.2.

Warning: Before starting the upgrade process it is recommended to perform a full backup of your data.

The upgrade process depends on the distribution you are using:

• Upgrading on Debian or Ubuntu • Upgrading on Red Hat Enterprise Linux or CentOS

Upgrading on Debian or Ubuntu

1. Stop the mongod process:

$ service mongod stop

2. Check for installed packages:

$ dpkg -l | grep mongod

ii mongodb-org3.0.6 amd64

˓→ MongoDB open source document-oriented database system(metapackage) ii mongodb-org-mongos3.0.6 amd64

˓→ MongoDB sharded cluster query router ii mongodb-org-server3.0.6 amd64

˓→ MongoDB database server

17 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

ii mongodb-org-shell3.0.6 amd64

˓→ MongoDB shell client ii mongodb-org-tools3.0.6 amd64

˓→ MongoDB tools

3. Remove installed packages:

apt-get remove mongodb-org mongodb-org-mongos mongodb-org-server \ mongodb-org-shell mongodb-org-tools

4. Install Percona Server for MongoDB using apt.

Upgrading on Red Hat Enterprise Linux or CentOS

1. Stop the mongod process:

$ service mongod stop

2. Check for installed packages:

$ rpm -qa | grep mongo

mongodb-org-3.0.6-1.el6.x86_64 mongodb-org-server-3.0.6-1.el6.x86_64 mongodb-org-shell-3.0.6-1.el6.x86_64 mongodb-org-mongos-3.0.6-1.el6.x86_64 mongodb-org-tools-3.0.6-1.el6.x86_64

3. Remove installed packages:

yum remove \ mongodb-org-3.0.6-1.el6.x86_64 mongodb-org-server-3.0.6-1.el6.x86_64 \ mongodb-org-shell-3.0.6-1.el6.x86_64 mongodb-org-mongos-3.0.6-1.el6.x86_64 \ mongodb-org-tools-3.0.6-1.el6.x86_64

4. Install Percona Server for MongoDB using yum.

18 Chapter 3. Upgrading from MongoDB Community Edition to Percona Server for MongoDB CHAPTER FOUR

UPGRADING FROM PERCONA TOKUMX TO PERCONA SERVER FOR MONGODB

This guide describes how to upgrade existing Percona TokuMX instance to Percona Server for MongoDB. The same process should work when upgrading from MongoDB prior to version 3.0 (such as, 2.4 and 2.6). The following JavaScript files are required to perform the upgrade: • allDbStats.js • tokumx_dump_indexes.js • psmdb_restore_indexes.js You can download those files from GitHub.

Warning: Before starting the upgrade process, it is recommended that you perform a full backup.

To performa the upgrade: 1. Restart the TokuMX server without the --auth parameter:

$ service tokumx stop $ sed -i'' s/^auth/#auth/ /etc/tokumx.conf $ service tokumx start

2. Run the allDbStats.js script to record database state before migration:

$ mongo ./allDbStats.js > ~/allDbStats.before.out

3. Perform a dump of the database:

$ mongodump --out /your/dump/path

4. Perform a dump of the indexes:

$ ./tokumx_dump_indexes.js > /your/dump/path/tokumxIndexes.json

5. Stop the TokuMX server:

$ service tokumx stop

6. Move the data directory and copy the configuration for safekeeping.

$ mv /var/lib/tokumx /var/lib/tokumx.bak $ cp /etc/tokumx.conf /etc/tokumx.conf.bak

19 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

7. Uninstall all TokuMX packages. If you are using a Debian or Ubuntu based distribution:

$ dpkg -P --force-all`dpkg -l | grep tokumx | awk '{print $2}'`

If you are using a Red Hat or CentOS based distribution:

$ yum remove -y tokumx-enterprise-common-2.0.2-1.el6.x86_64 \ tokumx-enterprise-server-2.0.2-1.el6.x86_64 \ tokumx-enterprise-2.0.2-1.el6.x86_64

8. Install Percona Server for MongoDB as described in the Installation Guide. 9. Stop the mongod service, configure the storage.engine parameter to run PerconaFT, and disable --auth in /etc/mongod.conf:

$ service mongod stop $ sed -i '/engine: \*PerconaFT/s/#//g' /etc/mongod.conf $ sed -i'' s/^auth/#auth/ /etc/mongod.conf

For more information about configuring the storage engine, see Switching Storage Engines. 10. Start the mongod server:

$ service mongod start

11. Restore the collections without indexes:

$ mongorestore --noIndexRestore /your/dump/path

12. Restore the indexes (this may take a while). This step will remove clustering options to the collections before inserting.

$ ./psmdb_restore_indexes.js --eval " data='/your/dump/path/tokumxIndexes.

˓→json' "

13. Run the allDbStats.js script to record database state after migration:

$ mongo ./allDbStats.js > ~/allDbStats.after.out

14. Restart the mongod server with authentication:

$ service mongod stop $ sed -i'' s/^i#auth/auth/ /etc/mongod.conf $ service mongod start

20 Chapter 4. Upgrading from Percona TokuMX to Percona Server for MongoDB Part III

Features

21

CHAPTER FIVE

MONGOROCKS

MongoRocks is a storage engine for MongoDB based on the RocksDB key-value store optimized for fast storage. It is developed by Facebook and designed to handle write-intensive workloads.

• Using MongoRocks • Configuring MongoRocks

The MongoRocks storage engine is available in Percona Server for MongoDB along with the standard MongoDB engines (the original MMAPv1 and the default WiredTiger), as well as Percona Memory Engine.

Using MongoRocks

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): Data created by one storage engine is not compatible with other storage engines, because each one has its own data model. When changing the storage engine, you have to do one of the following: • If you simply want to temporarily test MongoRocks, change to a different data directory with the --dbpath command-line option:

$ service mongod stop $ mongod --storageEngine rocksdb --dbpath

Note: Make sure that the user running mongod has read and write permissons for the new data directory.

• If you want to permanently switch to MongoRocks and do not have any valuable data in your database, clean out the default data directory and edit the configuration file:

$ service mongod stop $ rm -rf /var/lib/mongodb/* $ sed -i '/engine: \*rocksdb/s/#//g' /etc/mongod.conf $ service mongod start

• If there is data that you want to migrate and make compatible with MongoRocks, use the mongodump and mongorestore utilities:

23 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

$ mongodump --out $ service mongod stop $ rm -rf /var/lib/mongodb/* $ sed -i '/engine: \*rocksdb/s/#//g' /etc/mongod.conf $ service mongod start $ mongorestore

Configuring MongoRocks

You can configure MongoRocks using either command-line options or corresponding parameters in the /etc/ mongod.conf file. The configuration file is formatted in YAML. For example, the following sample configuration is suggested as the default for running Percona Server for MongoDB with MongoRocks:

storage: engine: rocksdb rocksdb: cacheSizeGB: 1 compression: snappy maxWriteMBPerSec: 1024 crashSafeCounters: false counters: true singleDeleteIndex: false

Setting parameters in the previous example configuration file is the same as starting the mongod daemon with the following options:

mongod --storageEngine=rocksdb \ --rocksdbCacheSizeGB=1 \ --rocksdbCompression=snappy \ --rocksdbMaxWriteMBPerSec=1024 \ --rocksdbCrashSafeCounters=false \ --rocksdbCounters=true \ --rocksdbSingleDeleteIndex=false

See also: YAML Specification https://yaml.org/spec/1.2/spec.html The following options are available (with corresponding YAML configuration file parameters): option --rocksdbCacheSizeGB Variable storage.rocksdb.cacheSizeGB Type Integer Default 30% of physical memory Specifies the amount of memory (in gigabytes) to allocate for block cache. Block cache is used to store uncom- pressed pages. Compressed pages are stored in kernel’s page cache. To configure block cache size dynamically, set the rocksdbRuntimeConfigCacheSizeGB parameter at runtime:

db.adminCommand({setParameter:1, rocksdbRuntimeConfigCacheSizeGB: 10})

option --rocksdbCompression

24 Chapter 5. MongoRocks Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Variable storage.rocksdb.compression Type String Default snappy Specifies the block compression algorithm for data collection. Possible values: none, snappy, zlib, lz4, lz4hc. option --rocksdbMaxWriteMBPerSec Variable storage.rocksdb.maxWriteMBPerSec Type Integer Default 1024 (1 GB/sec) Specifies the maximum speed at which MongoRocks writes to storage (in megabytes per second). Decrease this value to reduce read latency spikes during compactions. However, reducing it too much might slow down writes. To configure write speed dynamically, set the rocksdbRuntimeConfigMaxWriteMBPerSec parameter at runtime:

db.adminCommand({setParameter:1, rocksdbRuntimeConfigMaxWriteMBPerSec:30})

option --rocksdbCrashSafeCounters Variable storage.rocksdb.crashSafeCounters Type Boolean Default false Specifies whether to correct counters after a crash. Enabling this can affect write performance. option --rocksdbCounters Variable storage.rocksdb.counters Type Boolean Default true Specifies whether to use advanced counters for MongoRocks. You can disable them to improve write perfor- mance. option --rocksdbSingleDeleteIndex Variable storage.rocksdb.singleDeleteIndex Type Boolean Default false This is an experimental feature. Enable it only if you know what you are doing.

5.2. Configuring MongoRocks 25 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

26 Chapter 5. MongoRocks CHAPTER SIX

PERCONA MEMORY ENGINE

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.

• Using Percona Memory Engine • Configuring Percona Memory Engine

The Percona Memory Engine is available in Percona Server for MongoDB along with the standard MongoDB engines (the original MMAPv1 and the default WiredTiger), as well as MongoRocks and PerconaFT Storage Engine.

Note: PerconaFT has been deprecated and will be removed in future releases.

Using Percona Memory Engine

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 option in the configuration file (by default, /etc/mongod.conf): Data created by one storage engine is not compatible with other storage engines, because each one has its own data model. When changing the storage engine, you have to do one of the following: • If you simply want to temporarily test a Percona Memory Engine, change to a different data directory with the --dbpath command-line option:

service mongod stop mongod --storageEngine inMemory --dbpath

Note: Make sure that the user running mongod has read and write permissons for the new data directory.

Note: Although Percona Memory Engine stores all data in memory, some diagnostics and statistics are still written to disk. This is controlled using the --inMemoryStatisticsLogDelaySecs option.

• If you want to permanently switch to Percona Memory Engine and do not have any valuable data in your database, clean out the default data directory and edit the configuration file:

27 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

service mongod stop rm -rf /var/lib/mongodb/* sed -i '/engine: \*inMemory/s/#//g' /etc/mongod.conf service mongod start

• If there is data that you want to migrate and make compatible with Percona Memory Engine, use the mongodump and mongorestore utilities:

mongodump --out service mongod stop rm -rf /var/lib/mongodb/* sed -i '/engine: \*inMemory/s/#//g' /etc/mongod.conf service mongod start mongorestore

Configuring Percona Memory Engine

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

See also: YAML Specification https://yaml.org/spec/1.2/spec.html The following options are available (with corresponding YAML configuration file parameters): option --inMemorySizeGB Config storage.inMemory.engineConfig.inMemorySizeGB Default 60% 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.

28 Chapter 6. Percona Memory Engine CHAPTER SEVEN

PERCONAFT STORAGE ENGINE

PerconaFT is a storage engine based on the Fractal Tree Index model, which is optimized for fast disk I/O. The Fractal Tree data structure contains buffers to temporarily store insertions. When a buffer is full, it is flushed to children nodes. This ensures that an I/O operation performs a lot of useful work when messages reach leaves on disk, instead of just a small write per I/O.

• Switching Storage Engines • Configuring PerconaFT

The PerconaFT storage engine is available in Percona Server for MongoDB along with the standard MongoDB engines (MMAPv1 and WiredTiger), as well as MongoRocks.

Note: PerconaFT has been deprecated and will be removed in future releases.

To help you decide which is better for you, the table below lists features available in various storage engines: MMAPv1 WiredTiger MongoRocks PerconaFT Available in MongoDB YES YES NO NO Document-level locking NO YES YES YES High compression NO YES YES YES Fast insertions NO NO YES YES Hot Backup NO NO YES YES

Note: PerconaFT is not supported on 32-bit systems.

Warning: Transparent huge pages is a feature in newer Linux kernel versions that causes problems for the memory usage tracking calculations in PerconaFT and can lead to memory overcommit. If you have this feature enabled, PerconaFT will not start, and you should turn it off. If you want to run with transparent huge pages on, you can set an environment variable TOKU_HUGE_PAGES_OK=1, but only do this for testing, and only with a small cache size.

Switching Storage Engines

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.

29 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

engine option in the configuration file (by default, /etc/mongod.conf). Data created by one storage engine is not compatible with other storage engines, because each one has its own data model. When changing the storage engine, you have to do one of the following: • If you simply want to temporarily test a storage engine, change to a different data directory with the --dbpath command-line option:

$ service mongod stop $ mongod --storageEngine PerconaFT --dbpath

Note: Make sure that the user running mongod has read and write permissons for the new data directory.

• If you want to permanently switch to a different storage engine and do not have any valuable data in your database, clean out the default data directory and edit the configuration file:

$ service mongod stop $ rm -rf /var/lib/mongodb/* $ sed -i '/engine: \*PerconaFT/s/#//g' /etc/mongod.conf $ service mongod start

• If there is data that you want to migrate and make compatible with the new storage engine, use the mongodump and mongorestore utilities:

$ mongodump --out $ service mongod stop $ rm -rf /var/lib/mongodb/* $ sed -i '/engine: \*PerconaFT/s/#//g' /etc/mongod.conf $ service mongod start $ mongorestore

Configuring PerconaFT

You can configure the PerconaFT storage 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: PerconaFT PerconaFT: engineOptions: cacheSize: 53687091200 journalCommitInterval: 100 collectionOptions: compression: zlib indexOptions: compression: zlib

Setting parameters in the previous example configuration file is the same as starting the mongod daemon with the following options:

$ mongod --storageEngine PerconaFT \ --PerconaFTEngineCacheSize 53687091200 \ --PerconaFTEngineJournalCommitInterval 100 \

30 Chapter 7. PerconaFT Storage Engine Percona Server for MongoDB Documentation, Release 3.2.22-3.13

--PerconaFTCollectionCompression zlib \ --PerconaFTIndexCompression zlib

See also: YAML Specification https://yaml.org/spec/1.2/spec.html The following options are available (with corresponding YAML configuration file parameters): option --PerconaFTCollectionCompression Config storage.PerconaFT.collectionOptions.compression Default zlib Values none, zlib, lzma, quicklz Specifies the PerconaFT collection compression method. option --PerconaFTCollectionFanout Config storage.PerconaFT.collectionOptions.fanout Default 16 Specifies the PerconaFT collection fanout. option --PerconaFTCollectionPageSize Config storage.PerconaFT.collectionOptions.pageSize Default 4194304 (4 MiB) Specifies the PerconaFT collection page size in bytes. option --PerconaFTCollectionReadPageSize Config storage.PerconaFT.collectionOptions.readPageSize Default 65536 (64 KiB) Specifies the PerconaFT collection read page size in bytes. option --PerconaFTEngineCacheSize Config storage.PerconaFT.engineOptions.cacheSize Default 0 Specifies the PerconaFT storage engine cache size in bytes. option --PerconaFTEngineCleanerIterations Config storage.PerconaFT.engineOptions.cleanerIterations Default 5 Specifies the number of PerconaFT storage engine cleaner iterations. option --PerconaFTEngineCleanerPeriod Config storage.PerconaFT.engineOptions.cleanerPeriod Default 2 Specifies the PerconaFT storage engine cleaner period in seconds. option --PerconaFTEngineCompressBuffersBeforeEviction Config storage.PerconaFT.engineOptions.compressBuffersBeforeEviction

7.2. Configuring PerconaFT 31 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Default false Specifies whether the PerconaFT storage engine should compress buffers before eviction. option --PerconaFTEngineDirectio Config storage.PerconaFT.engineOptions.directio Default false Specifies whether the PerconaFT storage engine should use Direct I/O. option --PerconaFTEngineFsRedzone Config storage.PerconaFT.engineOptions.fsRedzone Default 5 Specifies the PerconaFT storage engine filesystem redzone. option --PerconaFTEngineJournalCommitInterval Config storage.PerconaFT.engineOptions.journalCommitInterval Default 100 Specifies the PerconaFT storage engine journal commit interval in milliseconds. option --PerconaFTEngineLockTimeout Config storage.PerconaFT.engineOptions.lockTimeout Default 100 Specifies the PerconaFT storage engine lock wait timeout in milliseconds. option --PerconaFTEngineLocktreeMaxMemory Config storage.PerconaFT.engineOptions.locktreeMaxMemory Default 0 Specifies the PerconaFT storage engine locktree size in bytes. option --PerconaFTEngineLogDir Config storage.PerconaFT.engineOptions.logDir Default Specifies the directory for the PerconaFT storage engine transaction log. option --PerconaFTEngineNumCachetableBucketMutexes Config storage.PerconaFT.engineOptions.numCachetableBucketMutexes Default 1048576 Specifies the number of PerconaFT storage engine num cachetable bucket mutexes. option --PerconaFTIndexCompression Config storage.PerconaFT.indexOptions.compression Default zlib Values none, zlib, lzma, quicklz Specifies the PerconaFT index compression method. option ---PerconaFTIndexFanout

32 Chapter 7. PerconaFT Storage Engine Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Config storage.PerconaFT.indexOptions.fanout Default 16 Specifies the PerconaFT index fanout. option --PerconaFTIndexPageSize Config storage.PerconaFT.indexOptions.pageSize Default 4194304 (4 MiB) Specifies the PerconaFT index page size in bytes. option --PerconaFTIndexReadPageSize Config storage.PerconaFT.indexOptions.readPageSize Default 65536 (64 KiB) Specifies the PerconaFT index read page size in bytes.

7.2. Configuring PerconaFT 33 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

34 Chapter 7. PerconaFT Storage Engine CHAPTER EIGHT

PERCONA TOKUBACKUP

Percona TokuBackup is an integrated open-source hot backup system for MongoDB servers running the PerconaFT storage engine (including Percona Server for MongoDB). It creates a physical data backup on a running server without performance degradation or capacity planning, and provides a more recent backup than a snapshot at the file system level.

Note: PerconaFT has been deprecated and will be removed in future releases.

• Architectural Overview • Making a Backup • Checking Backup Progress • Controlling Backup Rate • Restoring From Backup • Creating New Replicas • Sharding

Architectural Overview

TokuBackup copies the data in the dbpath (and logDir if different) to a backup directory. The following subsystems are used to complete the backup: • One component copies files directly, in the background. This component’s I/O consumption can be controlled with the backupThrottle command. • The other component ensures consistency between the original database files and the backup copy, even while there are read and write workloads occuring in the database. This is possible because TokuBackup is essentially a shim between the mongod process and the operating system. It intercepts all relvant file system calls, and creates some state in the memory that mirrors the same state in the file system. Since all writes to database files are applied to their corresponding files in the backup directory, the state of the files in the backup directory is identical to the database files at the time the backup completes. Compare this with backups performed with file system level snapshots, where the backup data is as it was at the beginning of the backup. Another effect of mirrored writes is that the write I/O done by clients is doubled for the duration of the backup. As Fractal Tree indexes are write-optimized, this is usually not a problem, but is important to know for capacity planning.

35 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Making a Backup

TokuBackup is included with Percona Server for MongoDB.

Note: TokuBackup is available only if you are running the PerconaFT storage engine.

To take a backup of the database files in your current dbpath, you can execute the following command as an admin- istrator on the admin database:

> use admin switched to db admin > db.runCommand({backupStart:"/my/backup/data/path"}) { "ok" : 1 }

You should receive an { "ok" : 1 } object as a return value if the backup was successful. If there was an error, you will receive an error message along with failing ok status. For example:

> db.runCommand({backupStart:""}) { "ok" : 0, "errmsg" : "invalid destination directory: ''" }

Checking Backup Progress

For long running backups, with lots of data to copy, it is helpful to see how much data the backup process has copied. To see the high level status of a backup use the following command:

> db.runCommand({backupStatus:1}) { "inProgress" : false, "bytesCopied" : NumberLong(0), "filesCopied" : 0, "ok" : 1 }

In this case, there is no backup in progress. The inProgress field will return true when there is a backup executing. The bytesCopied and the filesCopied fields will increase as data is copied from the source files to the backup destination directory.

Controlling Backup Rate

Throttling backups can help reduce the impact on a running server. The rate at which TokuBackup copies files from source directories (like those in your dbpath setting) can be controlled using the backupThrottle command. For example, to limit the backup rate to 128 KB/s, run the following command:

> db.runCommand({backupThrottle:128000})

Note: By default, backup rate is not limited.

36 Chapter 8. Percona TokuBackup Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Restoring From Backup

To restore from backup, simply stop mongod and run it with --dbpath option pointing to the location of the backup.

Note: The server to which you are restoring must be the same MongoDB version as the one used when you created the backup.

Creating New Replicas

A great use case for TokuBackup is creating new secondaries in a replica set. The normal initial sync procedure can use normal queries that need to decompress and deserialize data on disk, and then marshall it and send it across the network. Then on the secondary, it needs to be indexed, serialized, and compressed all over again. This is a slow process, and furthermore it poisons the cache of the machine being synced from with data that may be irrelevant to the application. Instead, a hot backup can be used to initialize a replica set secondary. This is both faster and less intrusive to application queries and the sync source server’s cache. To create a secondary using TokuBackup, move the backup files to the new machine, start the server with the --replSet option and additionally with --fastsync, then use rs.add() on the primary to add the new sec- ondary. After the secondary has been added, you should remove the --fastsync option for future server startups.

Warning: In order to find the oplog position in common between the new secondary and the existing members of the set, the oplog must be present in the backup. Therefore, when initially creating a replica set from a single server, it is necessary to run rs.initiate() first before taking a backup for the new secondary.

Note: To minimize impact on a running application, it is recommended to use a backup of an existing secondary to create a new secondary, rather than backing up the primary.

Sharding

Since TokuBackup captures the state of a server at the end of the backup operation, it can be difficult to capture a time-consistent backup of multiple shards simultaneously. The recommended procedure for taking a backup of a sharded cluster in Percona Server for MongoDB is to discon- nect one secondary from each shard at the same time, then back up those secondaries with any backup procedure. Additionally, one configuration server must be backed up at the same time as well. For most applications, getting a truly consistent backup of a sharded cluster requires that the application pauses all writes and the balancer, waits for one secondary on each shard to catch up fully with the primary, then disconnects one configuration server and a secondary from each shard. After this, the application can continue (and the balancer as well, once the configuration server has been backed up), and when the backup is finished, the secondaries will need to catch up again.

8.5. Restoring From Backup 37 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

38 Chapter 8. Percona TokuBackup CHAPTER NINE

HOT BACKUP

Percona Server for MongoDB includes an integrated open-source hot backup system for the default WiredTiger and alternative MongoRocks storage engine. It creates a physical data backup on a running server without performance degradation. To take a hot backup of the database in your current dbpath, 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: "/my/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" }

39 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

40 Chapter 9. Hot Backup CHAPTER TEN

PROFILING RATE LIMIT

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.

Enabling the Rate Limit

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

$ mongod --profile 2 --slowms 200 --rateLimit 100

To do the same at runtime, use the profile command. It returns the previous settings and "ok" : 1 indicates that the operation was successful:

> db.runCommand( { profile:2, slowms: 200, ratelimit: 100}); {"was":0,"slowms": 100,"ratelimit":1,"ok":1}

To check the current settings, run profile: -1:

> db.runCommand( { profile:-1}); {"was":2,"slowms": 200,"ratelimit": 100,"ok":1}

If you want to set or get just the rate limit value, use the profilingRateLimit parameter on the admin database:

41 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

> db.getSiblingDB('admin').runCommand( { setParameter:1,"profilingRateLimit": 100}

˓→); {"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.

Profiler Collection Extension

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.

42 Chapter 10. Profiling Rate Limit CHAPTER ELEVEN

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.

• Overview • External Authentication Commands • Environment Setup and Configuration

Overview

The following components are necessary for external authentication to work: • LDAP Server: Remotely stores all user credentials (i.e. user name and associated password). • SASL Daemon: Used as a MongoDB server-local proxy for the remote LDAP service. • SASL Library: Used by the MongoDB client and server to create data necessary for the authentication mecha- nism. The following image illustrates this architecture:

43 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

An authentication session uses the following sequence: 1.A mongo client connects to a running mongod instance. 2. The client creates a special authentication request using the SASL library and a selected authentication mecha- nism (for example, PLAIN). 3. The client then sends this SASL request to the server as a special Mongo command. 4. The mongod server receives this SASL Message, with its authentication request payload. 5. The server then creates a SASL session scoped to this client, using its own reference to the SASL library. 6. Then the server passes the authentication payload to the SASL library, which in turn passes it on to the saslauthd daemon. 7. The saslauthd daemon passes the payload on to the LDAP service to get a YES or NO authentication response (in other words, does this user exist and is the password correct). 8. The YES/NO response moves back from saslauthd, through the SASL library, to mongod. 9. The mongod server uses this YES/NO response to authenticate the client or reject the request. 10. If successful, the client has authenticated and can proceed.

External Authentication Commands

Use the following command to add an external user to the mongod server:

> db.getSiblingDB("$external").createUser( {user : christian, roles: [ {role: "read",

˓→db: "test"} ]} );

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.

44 Chapter 11. External Authentication Percona Server for MongoDB Documentation, Release 3.2.22-3.13

When running the mongo client, a user can authenticate against a given database using the following command:

> db.getSiblingDB("$external").auth({ mechanism:"PLAIN", user:"christian", pwd:"secret

˓→", digestPassword:false})

Environment Setup and Configuration

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:

• Running the LDAP service • Adding Users to LDAP • Configuring saslauthd – Microsoft Windows Active Directory • Sanity Check • Configuring libsasl2 • Configuring mongod Server

Running the LDAP service

Start the LDAP server. Note the given URL and configuration file. Also note the username: openldapper. It is important that the user starting the service, and adding entries to the LDAP database, has permissions to do so.

$ slapd -h ldap://127.0.0.1:9009/ -u openldapper -f /etc/openldap/slapd.conf

The URL argument will be used for entering data into the LDAP database, verifying entries, and as an endpoint for saslauthd to authenticate against during MongoDB external authentication. A simple LDAP configuration file can have the following contents:

database mdb suffix "dc=example,dc=com" rootdn "cn=openldapper,dc=example,dc=com" rootpw secret directory /home/openldapper/ldap/tests/openldap/install/var/openldap-data

There are other entries in the slapd.conf file that are important for successfully starting the LDAP service. OpenL- DAP installations have a sample slapd.conf file that has the above and other required entries, such as include, pidfile, and argsfile.

11.3. Environment Setup and Configuration 45 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Adding Users to LDAP

OpenLDAP comes with a few programs to communicate with the LDAP daemon/service. For example, to add new users to the LDAP database, you can use ldapadd or ldapmodify, with an associated .ldif file.

Configuring saslauthd

These are the typical settings required for saslauthd to connect to a local OpenLDAP service (the server address MUST match the OpenLDAP installation): ldap_servers: ldap://127.0.0.1:9009 ldap_search_base: dc=example,dc=com ldap_filter: (cn=%u) ldap_bind_dn: cn=openldapper,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 unecrypted files.

Microsoft Windows Active Directory

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://198.51.100.10 ldap_mech: PLAIN ldap_search_base: CN=Users,DC=example,DC=com ldap_filter: (sAMAccountName=%u) ldap_bind_dn: CN=ldapmgr,CN=Users,DC=,DC= 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.

Sanity Check

Verify that the saslauthd service can authenticate against the users created in the LDAP service:

$ testsaslauthd -u christian -p secret -f /var/run/saslauthd/mux

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 SASL library used by mongod must also be configured properly via a configuration file:

46 Chapter 11. External Authentication Percona Server for MongoDB Documentation, Release 3.2.22-3.13

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

Configuring mongod Server

External authentication is enabled the same way as local authentication. Simply start the server with the --auth option:

$ ./mongod --dbpath=/data/db --auth

This assumes that libsasl2 has been installed in the system as a dynamic library (libsasl2.so). You may see an error on the command line or in the logs if that library is missing from your server’s environment. When everything is configured properly, you can use the External Authentication Commands.

See Also

• SASL documentation:

11.3. Environment Setup and Configuration 47 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

48 Chapter 11. External Authentication CHAPTER TWELVE

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. The following server parameters control auditing. They are entered at the command line when starting a mongod server instance. --auditDestination By default, audit logging is disabled. Auditing and audit log generation are activated when this parameter is present on the command line at server startup. The argument to this parameter designates where the log output is directed: file, syslog, or console. By default, it is saved to a log file.

mongod --auditDestination=file

Note: Auditing remains active until shutdown, it cannot be disabled dynamically at runtime.

--auditPath This is the fully qualified path to the file you want the server to create, if you set --auditDestination to file. If this parameter is not specified, then auditLog.json file will be created in the server’s configured log path.

mongod --auditDestination=file --auditPath /var/log/psmdb/audit.json

If log path is not configured on the server, then auditLog.json will be created in the current directory (from which mongod was started).

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.

--auditFormat This is the format of each audit event stored in the audit log. The argument to this parameter can be either JSON or BSON. The default value for this parameter is JSON.

Note: If you set it to BSON, then --auditDestination must be set to file, and also --auditPath must be specified. For example:

49 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

mongod --auditDestination=file --auditFormat=BSON --auditPath /var/log/psmdb/

˓→audit.bson

--auditFilter This parameter specifies a filter to apply to incoming audit events, enabling the administrator to only capture a subset of all possible audit events. This filter should be a JSON string that can be interpreted as a query object. Each audit log event that matches this query will be logged. Events which do not match this query will be ignored. If this parameter is not specified, then all audit events are stored in the audit log. For example, to log only events from a user named tim, start the server with the following parameters:

mongod \ --auditDestination file \ --auditFormat JSON \ --auditPath /var/log/psmdb/audit.json \ --auditFilter '{ "users.user" : "tim" }'

Enabling Auditing of Authorization Success

By default, only authorization failures for the authCheck action are logged by the audit system. To enable logging of authorization successes, set the auditAuthorizationSuccess parameter to true.

Note: Enabling this parameter is required if you want to filter CRUD operations in the audit log, because CRUD operations are logged under authCheck action.

You can enable it on a running server using the following command: db.adminCommand( { setParameter:1, auditAuthorizationSuccess: true } )

To enable it on the command line, use the following option when running mongod or mongos process:

--setParameter auditAuthorizationSuccess=true

You can also add it to the configuration file as follows: setParameter: auditAuthorizationSuccess: true

Warning: Enabling auditAuthorizationSuccess can impact performance compared to logging only authorization failures.

50 Chapter 12. Auditing Part IV

Reference

51

CHAPTER THIRTEEN

SWITCHING STORAGE ENGINES

By default, Percona Server for MongoDB runs with WiredTiger. There is also the original MMAPv1 storage engine, as well as optional PerconaFT Storage Engine, Percona Memory Engine and MongoRocks storage engines to choose from. Each one 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). Data created by one storage engine is not compatible with other storage engines, because each one has its own data model. When changing the storage engine, you have to do one of the following: • If you simply want to temporarily test a storage engine, you can change to a different data directory using the --dbpath command-line option:

$ service mongod stop $ mongod --storageEngine rocksdb --dbpath

Note: Make sure that the user running mongod has read and write permissons for the new data directory.

• If you want to permanently switch to a different storage engine and do not have any valuable data in your database, clean out the default data directory and edit the configuration file:

$ service mongod stop $ rm -rf /var/lib/mongodb/* $ sed -i '/engine: \*rocksdb/s/#//g' /etc/mongod.conf $ service mongod start

• If there is data that you want to migrate and make compatible with the new storage engine, use the mongodump and mongorestore utilities:

$ mongodump --out $ service mongod stop $ rm -rf /var/lib/mongodb/* $ sed -i '/engine: \*rocksdb/s/#//g' /etc/mongod.conf $ service mongod start $ mongorestore

53 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

54 Chapter 13. Switching Storage Engines CHAPTER FOURTEEN

STORAGE ENGINE CONFIGURATION TEMPLATES

The default configuration file provided with Percona Server for MongoDB (/etc/mongod.conf) contains tem- plates for running any of the bundled storage engine. The suggested values do not cover all cases, but they are a good reference point to start customizing the configuration. The following hints may help you: • On very high volume systems, you may need to increase the maximum number of concurrent transactions for WiredTiger and Percona Memory Engine (default is 128). These are controlled using the following MongoDB parameters: – wiredTigerConcurrentReadTransactions – wiredTigerConcurrentWriteTransactions • On systems with more than roughly 24,000 collections running MMAPv1, increase the storage.mmapv1. nsSize variable. • Also for MMAPv1 you can set storage.mmapv1.smallFiles to true to use a smaller default file size, if you have a large number of databases that each holds a small amount of data. • The storage.rocksdb.counters variable must be set to true if you are running MongoRocks and want to use Percona Monitoring and Management. • The default maximum internal cache size that WiredTiger uses is the larger of either: – 60% of RAM minus 1 GB – 1 GB • The default maximum internal cache size that MongoRocks uses is 30% of RAM.

55 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

56 Chapter 14. Storage Engine Configuration Templates CHAPTER FIFTEEN

PERCONA SERVER FOR MONGODB PARAMETER TUNING GUIDE

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: failIndexKeyTooLong: internalQueryPlannerEnableIndexIntersection: ttlMonitorEnabled: ttlMonitorSleepSecs:

• The --setParameter option arguments when running the mongod process for development or testing pur- poses:

$ mongod \ --setParameter cursorTimeoutMillis= \ --setParameter failIndexKeyTooLong= \ --setParameter internalQueryPlannerEnableIndexIntersection= \ --setParameter ttlMonitorEnabled= \ --setParameter ttlMonitorSleepSecs=

• The setParameter command on the admin database to make changes at runtime:

> db = db.getSiblingDB('admin') > db.runCommand( { setParameter: 1, cursorTimeoutMillis: } ) > db.runCommand( { setParameter: 1, failIndexKeyTooLong: } ) > db.runCommand( { setParameter: 1, internalQueryPlannerEnableIndexIntersection:

˓→ } ) > db.runCommand( { setParameter: 1, ttlMonitorEnabled: } ) > db.runCommand( { setParameter: 1, ttlMonitorSleepSecs: } ) 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

57 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

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.

58 Chapter 15. Percona Server for MongoDB Parameter Tuning Guide CHAPTER SIXTEEN

PERCONA SERVER FOR MONGODB 3.2 RELEASE NOTES

Percona Server for MongoDB 3.2.22-3.13

Percona is glad to announce the release of Percona Server for MongoDB 3.2.22-3.13 on January, 16 2019. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is an enhanced, open source, and highly-scalable database that is a fully-compatible, drop-in replacement for MongoDB 3.2 Community Edition. It supports MongoDB 3.2 protocols and drivers. Percona Server for MongoDB extends the functionality of MongoDB Community Edition by including the Percona Memory Engine storage engine, as well as several enterprise-grade features. Percona Server for MongoDB requires no changes to MongoDB applications or code. This release is based on MongoDB 3.2.22. There are no additional improvements or new features on top of those upstream fixes.

Percona Server for MongoDB 3.2.21-3.12

Percona is glad to announce the release of Percona Server for MongoDB 3.2.21-3.12 on September 18, 2018. Down- loads are available here and from the Percona Software Repositories. Percona Server for MongoDB is an enhanced, open source, and highly-scalable database that is a fully-compatible, drop-in replacement for MongoDB 3.2 Community Edition. It supports MongoDB 3.2 protocols and drivers. Percona Server for MongoDB extends MongoDB Community Edition functionality by including the Percona Memory Engine storage engine, as well as several enterprise-grade features. Percona Server for MongoDB requires no changes to MongoDB applications or code. This release updates the MongoDB portion of the Percona Server for MongoDB code base to 3.2.21.

Percona Server for MongoDB 3.2.20-3.11

Percona is glad to announce the release of Percona Server for MongoDB 3.2.20-3.11 on May 21, 2018. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is an enhanced, open source, and highly-scalable database that is a fully-compatible, drop-in replacement for MongoDB 3.2 Community Edition. It supports MongoDB 3.2 protocols and drivers. Percona Server for MongoDB extends MongoDB Community Edition functionality by including the Percona Memory Engine and MongoRocks storage engines, as well as several enterprise-grade features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

59 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

This release is based on MongoDB 3.2.20 and does not include any additional changes.

Percona Server for MongoDB 3.2.19-3.10

Percona is glad to announce the release of Percona Server for MongoDB 3.2.19-3.10 on March 16, 2018. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is an enhanced, open source, and highly-scalable database that is a fully-compatible, drop-in replacement for MongoDB 3.2 Community Edition. It supports MongoDB 3.2 protocols and drivers. Percona Server for MongoDB extends MongoDB Community Edition functionality by including the Percona Memory Engine and MongoRocks storage engines, as well as several enterprise-grade features. Percona Server for MongoDB requires no changes to MongoDB applications or code. This release is based on MongoDB 3.2.19 and includes the following additional change: • #PSMDB-191: Fixed a bug in MongoRocks engine initialization code which caused wrong initialization of _maxPrefix value. This could lead to reuse of dropped prefix and to accidental removal of data from the collection using reused prefix. In some specific conditions data records could disappear at arbitrary moment of time from the collections or indexes created after server restart. This could happen as the result of the following sequence of events: 1. User deletes one or more indexes or collections. These should be the ones using maximum existing prefixes values. 2. User shuts down the server before MongoRocks compaction thread executes compactions of deleted ranges. 3. User restarts the server and creates new collections. Due to the bug those new collections and their indexes may get the same prefix values which were deleted and not yet compacted. User inserts some data into the new collections. 4. After the server restart MongoRocks compaction thread continues executing compactions of the deleted ranges and this process may eventually delete data from the collections sharing prefixes with deleted ranges.

Percona Server for MongoDB 3.2.18-3.9

Percona is glad to announce the release of Percona Server for MongoDB 3.2.18-3.9 on December 11, 2017. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.18 and includes the following additional change: • oplog searches have been optimized in MongoRocks, this should also increase overall performance.

60 Chapter 16. Percona Server for MongoDB 3.2 Release Notes Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Percona Server for MongoDB 3.2.17-3.8

Percona is glad to announce the release of Percona Server for MongoDB 3.2.17-3.8 on October 31, 2017. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.17 and does not include any additional changes.

Percona Server for MongoDB 3.2.16-3.7

Percona is glad to announce the release of Percona Server for MongoDB 3.2.16-3.7 on September 27, 2017. Down- loads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.16 and includes the following additional changes: • #PSMDB-164: Fixed MongoRocks failure to repair if database metadata is inconsistent with dropped collections and indexes. • Added packages for Debian 9 (“stretch”).

Percona Server for MongoDB 3.2.16-3.6

Percona is glad to announce the release of Percona Server for MongoDB 3.2.16-3.6 on August 21, 2017. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.16 and does not include any additional changes.

16.6. Percona Server for MongoDB 3.2.17-3.8 61 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Percona Server for MongoDB 3.2.15-3.5

Percona is glad to announce the release of Percona Server for MongoDB 3.2.15-3.5 on July 26, 2017. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.15 and does not include any additional changes.

Percona Server for MongoDB 3.2.14-3.4

Percona is glad to announce the release of Percona Server for MongoDB 3.2.14-3.4 on July 17, 2017. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.14 and includes the following additional changes:

New Features

• #PSMDB-135: Exposed MongoRocks engine details in the serverStatus command output.

Bugs Fixed

• #PSMDB-67: Fixed mongod service status messages.

Percona Server for MongoDB 3.2.13-3.3

Percona is glad to announce the release of Percona Server for MongoDB 3.2.13-3.3 on May 15, 2017. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

62 Chapter 16. Percona Server for MongoDB 3.2 Release Notes Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.13 and includes the following additional fixes: • #PSMDB-127: Fixed cleanup of deleted documents and indexes for MongoRocks. When you upgrade to this release, deferred compaction may occur and cause database size to decrease significantly. • #PSMDB-133: Added the wiredTigerCheckpointSizeMB variable, set to 1000 in the configration tem- plate for WiredTiger. Valid values are 32 to 2048 (2GB), with the latter being default. • #PSMDB-138: Implemented SERVER-23418 for MongoRocks.

Percona Server for MongoDB 3.2.12-3.2

Percona is glad to announce the release of Percona Server for MongoDB 3.2.12-3.2 on March 9, 2017. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.12 and includes the following additional fixes: • #PSMDB-17: Changed welcome message in the shell to mention Percona Server for MongoDB instead of MongoDB • #PSMDB-90: Added error message for storage engines that do not support Hot Backup • #PSMDB-91: Deprecated audit configuration section and added auditLog instead • #PSMDB-95: Fixed version dependencies for subpackages so that all corresponding packages get updated accordingly • #PSMDB-96: Excluded diagnostic.data directory when using Percona TokuBackup with PerconaFT Storage Engine • #PSMDB-98: Improved Hot Backup to create destination folder if it does not exist • #PSMDB-101: Implemented the auditAuthorizationSuccess parameter to enable auditing of autho- rization success • #PSMDB-104: Updated links in client shell output to point to Percona Server for MongoDB documentation and forum • #PSMDB-107: Fixed behavior when creating the audit log file • #PSMDB-123: Fixed the creation of proper subdirectories inside the backup destination directory • #PSMDB-126: Added index and collection name to duplicate key error message • Fixed startup scripts for Ubuntu 14.04.5 LTS (Trusty Tahr) • Fixed a number of other small issues and bugs

16.12. Percona Server for MongoDB 3.2.12-3.2 63 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Percona Server for MongoDB 3.2.11-3.1

Percona is glad to announce the release of Percona Server for MongoDB 3.2.11-3.1 on December 8, 2016. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.11 and includes the following additional fixes: • #PSMDB-93: Fixed hang during shutdown of mongod when started with the --storageEngine=PerconaFT and --nojournal options • #PSMDB-92: Added Hot Backup to Ubuntu/Debian packages • #PSMDB-83: Updated default configuration file to include recommended settings templates for various storage engines • Added support for Ubuntu 16.10 (Yakkety Yak) • Added binary tarballs for Ubuntu 16.04 LTS (Xenial Xerus)

Percona Server for MongoDB 3.2.10-3.0

Percona is glad to announce the release of Percona Server for MongoDB 3.2.10-3.0 on October 31, 2016. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.10 and includes the following additional new features and improvements.

New Features

Universal Hot Backup This release introduces an integrated hot backup for the default WiredTiger and alternative MongoRocks engine. It creates a physical data backup on a running server without performance degradation. For more information, see Hot Backup. Profiling Rate Limit Rate limiting enables to seed logged queries and thus decrease the impact of profiling on database perfor- mance. For more information, see Profiling Rate Limit.

64 Chapter 16. Percona Server for MongoDB 3.2 Release Notes Percona Server for MongoDB Documentation, Release 3.2.22-3.13

Bug Fixes

• Fixed crash when running out of WiredTiger cache under Percona Memory Engine.

Percona Server for MongoDB 3.2.9-2.1

Percona is glad to announce the release of Percona Server for MongoDB 3.2.9-2.1 on September 19, 2016. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.9. There are no additional improvements or new features on top of those upstream fixes.

Percona Server for MongoDB 3.2.8-2.0

Percona is glad to announce the release of Percona Server for MongoDB 3.2.8-2.0 on August 11, 2016 Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. It extends MongoDB with MongoRocks, Percona Memory Engine, and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release is based on MongoDB 3.2.8, and includes the following additional changes: New Features • Introducing the new Percona Memory Engine, which is based on a special configuration of WiredTiger that stores data in memory instead of the disk. • --auditDestination can now be set to file, syslog, or console. • --auditFormat can now be set to JSON or BSON.

Note: For more information, see Auditing.

• The MongoRocks engine now supports LZ4 compression. This is an upstream feature of MongoRocks con- tributed by Percona. To enable it, use the --rocksdbCompression option when running Percona Server for MongoDB with the MongoRocks storage engine. For example:

16.15. Percona Server for MongoDB 3.2.9-2.1 65 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

./mongod --dbpath=./data --storageEngine=rocksdb --rocksdbCompression=lz4

For a high-compression variant of LZ4:

./mongod --dbpath=./data --storageEngine=rocksdb --rocksdbCompression=lz4hc

Note: If you want to configure this permanently, set the following parameters in the /etc/mongod.conf file:

storage: engine: rocksdb rocksdb: compression: lz4

Percona Server for MongoDB 3.2.7-1.1

Percona is glad to announce the release of Percona Server for MongoDB 3.2.7-1.1 on June 29, 2016. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. The latest release is based on MongoDB 3.2.7, extending MongoDB with MongoRocks and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release includes all changes from MongoDB 3.2.7, as well as the following: • Fixed the software version incorrectly reported by the --version option. • Added recommended ulimit values for the mongod process

Percona Server for MongoDB 3.2.6-1.0

Percona is glad to announce the release of Percona Server for MongoDB 3.2.6-1.0 on June 3, 2016. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. The latest release is based on MongoDB 3.2.6, extending MongoDB with MongoRocks and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The PerconaFT storage engine has been deprecated and will not be available in future releases.

This release includes all changes from MongoDB 3.2.6, as well as the following: • PerconaFT has been deprecated. It is still available, but is no longer recommended for production use. Per- conaFT will be removed in future releases.

66 Chapter 16. Percona Server for MongoDB 3.2 Release Notes Percona Server for MongoDB Documentation, Release 3.2.22-3.13

• MongoRocks is no longer considered experimental and is now recommended for production.

Note: As of version 3.2, MongoDB uses WiredTiger as the default storage engine, instead of MMAPv1.

Percona Server for MongoDB 3.2.4-1.0rc2

Percona is glad to announce the release of Percona Server for MongoDB 3.2.4-1.0rc2 on April 19, 2016. Downloads are available here and from the Percona Software Repositories. Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB v3.2 protocol and drivers. The latest release is based on MongoDB 3.2.4, extending MongoDB with MongoRocks and PerconaFT storage engines, as well as several enterprise features. Percona Server for MongoDB requires no changes to MongoDB applications or code.

Note: The MongoRocks storage engine is still under development. There is currently no officially released ver- sion of MongoRocks that can be recommended for production. Percona Server for MongoDB 3.2.4-1.0rc2 includes MongoRocks 3.2.4, which is based on RocksDB 4.4.

This release includes all changes from MongoDB 3.2.4, there are no additional improvements or new features on top of those upstream fixes.

Note: As of version 3.2, MongoDB uses WiredTiger as the default storage engine, instead of MMAPv1.

16.19. Percona Server for MongoDB 3.2.4-1.0rc2 67 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

68 Chapter 16. Percona Server for MongoDB 3.2 Release Notes CHAPTER SEVENTEEN

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

69 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

70 Chapter 17. Glossary CHAPTER EIGHTEEN

COPYRIGHT AND LICENSING INFORMATION

Documentation Licensing

This software documentation is (C)2015-2017 Percona LLC and/or its affiliates and is distributed under the Creative Commons Attribution-ShareAlike 2.0 Generic license.

Software License

71 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

72 Chapter 18. Copyright and Licensing Information CHAPTER NINETEEN

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.

73 Percona Server for MongoDB Documentation, Release 3.2.22-3.13

74 Chapter 19. Trademark Policy INDEX

Symbols F —PerconaFTIndexFanout (option), 32 failIndexKeyTooLong (variable), 57 –PerconaFTCollectionCompression (option), 31 Foreign Key, 69 –PerconaFTCollectionFanout (option), 31 –PerconaFTCollectionPageSize (option), 31 I –PerconaFTCollectionReadPageSize (option), 31 internalQueryPlannerEnableIndexIntersection (variable), –PerconaFTEngineCacheSize (option), 31 58 –PerconaFTEngineCleanerIterations (option), 31 Isolation, 69 –PerconaFTEngineCleanerPeriod (option), 31 –PerconaFTEngineCompressBuffersBeforeEviction (op- J tion), 31 Jenkins, 69 –PerconaFTEngineDirectio (option), 32 –PerconaFTEngineFsRedzone (option), 32 T –PerconaFTEngineJournalCommitInterval (option), 32 ttlMonitorEnabled (variable), 58 –PerconaFTEngineLockTimeout (option), 32 ttlMonitorSleepSecs (variable), 58 –PerconaFTEngineLocktreeMaxMemory (option), 32 –PerconaFTEngineLogDir (option), 32 –PerconaFTEngineNumCachetableBucketMutexes (option), 32 –PerconaFTIndexCompression (option), 32 –PerconaFTIndexPageSize (option), 33 –PerconaFTIndexReadPageSize (option), 33 –inMemorySizeGB (option), 28 –inMemoryStatisticsLogDelaySecs (option), 28 –rocksdbCacheSizeGB (option), 24 –rocksdbCompression (option), 24 –rocksdbCounters (option), 25 –rocksdbCrashSafeCounters (option), 25 –rocksdbMaxWriteMBPerSec (option), 25 –rocksdbSingleDeleteIndex (option), 25 A ACID, 69 Atomicity, 69 C Consistency, 69 cursorTimeoutMillis (variable), 57 D Durability, 69

75