Percona Server for MongoDB

Documentation
Release 3.0.5-rc7

Percona LLC and/or its affiliates 2015

September 16, 2015

CONTENTS

Installation
1.1 Installing Percona Server for MongoDB 5.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Replacing MongoDB with Percona Server for MongoDB . . . . . . . . . . . . . . . . . . . . . . . .
1.3 Building Pecona Server for MongoDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3
3
8
9

Features
2.1 External Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13
13
21

Reference
3.1 Percona Server for MongoDB Release notes
3.2 Glossary . . . . . . . . . . . . . . . . . . .
3.3 Copyright and Licensing Information . . . .
3.4 Trademark Policy . . . . . . . . . . . . . . .

23
23
23
24
24

Index

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

27

ii

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDB
v3.0 protocol and drivers. It extends MongoDB with RocksDB and PerconaFT storage engines, as well as features like
external authentication and audit logging. Percona Server for MongoDB requires no changes to MongoDB applications
or code. The main benefits of Percona Server for MongoDB are:
Improved single-threaded and multi-threaded performance
Compression
Fully ACID and MVCC transaction support
No maintenance or scheduled downtime necessary
Clustering key support for query acceleration
Better read scaling and reduced lag on replica sets
Low-impact migrations and accelerated range queries with clustering shard keys
Fast, read-free updates
Hot Backup
Point-in-time Recovery
Audit Logging
Reduced SSD wear
Geospatial Indexes
Includes all MongoDB v3.0 functionality except Text Search

CONTENTS

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

CONTENTS

CHAPTER

ONE

INSTALLATION

1.1 Installing Percona Server for MongoDB 5.6

This page provides the information on how to you can install Percona Server for MongoDB. Following options are
available:
Installing Percona Server for MongoDB from Repositories
Before installing, you might want to read the Percona Server for MongoDB Release notes.

1.1.1 Installing Percona Server for MongoDB from Repositories

Percona provides repositories for yum (RPM packages for Red Hat, CentOS and Amazon Linux AMI) and apt (.deb
packages for Ubuntu and Debian) for software such as Percona Server, Percona XtraBackup, and Percona Toolkit.
This makes it easy to install and update your software and its dependencies through your operating systems package
manager. This is the recommend way of installing where possible.
Following guides describe the installation process for using the official Percona repositories for .deb and .rpm
packages.
Installing Percona Server for MongoDB on Debian and Ubuntu
Ready-to-use packages are available from the Percona Server for MongoDB software repositories and the download
page.
Supported Releases:
Debian:
8.0 (jessie)
Ubuntu:
12.04LTS (precise)
14.04LTS (trusty)
14.10 (utopic)
15.04 (vivid)
Supported Platforms:
x86_64 (also known as amd64)

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Whats in each DEB package?

The percona-server-mongodb package will install the mongo shell, import/export tools, other client utilities,
server software, default configuration, and init.d scripts.
The percona-server-mongodb-server package contains the Percona Server for MongoDB server software,
default configuration files and init.d scripts.
The percona-server-mongodb-shell package contains the Percona Server for MongoDB shell
The percona-server-mongodb-mongos package contains mongos - the Percona Server for MongoDB
sharded cluster query router.
The percona-server-mongodb-tools package contains Mongo tools for high-performance MongoDB fork
from Percona.
The percona-server-mongodb-dbg package contains debug symbols for the server.
Installing Percona Server for MongoDB from Percona apt repository

1. Import the public key for the package management system

Debian and Ubuntu packages from Percona are signed with the Perconas GPG key. Before using the
repository, you should add the key to apt. To do that, run the following commands as root or with sudo:
$ sudo apt-key adv --keyserver keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A

Note: In case youre getting timeouts when using keys.gnupg.net as an alternative you can fetch
the key from keyserver.ubuntu.com.
2. Create the apt source list for Perconas repository:
You can create the source list and add the percona repository by running:

$ echo "deb http://repo.percona.com/apt "$(lsb_release -sc)" main" | sudo tee /etc/apt/sources.l

Additionally you can enable the source package repository by running:

$ echo "deb-src http://repo.percona.com/apt "$(lsb_release -sc)" main" | sudo tee -a /etc/apt/so

3. Remember to update the local cache:

$ sudo apt-get update

4. After that you can install the server package:

$ sudo apt-get install percona-server-mongodb

Percona apt Testing repository Percona offers pre-release builds from the testing repository. To enable it add
the just add the testing word at the end of the Percona repository definition in your repository file (default
/etc/apt/sources.list.d/percona.list). It should looks like this (in this example VERSION is the
name of your distribution):
deb http://repo.percona.com/apt VERSION main testing
deb-src http://repo.percona.com/apt VERSION main testing

Chapter 1. Installation

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Apt-Pinning the packages In some cases you might need to pin the selected packages to avoid the upgrades from
the distribution repositories. Youll need to make a new file /etc/apt/preferences.d/00percona.pref
and add the following lines in it:
Package: *
Pin: release o=Percona Development Team
Pin-Priority: 1001

For more information about the pinning you can check the official debian wiki.
Running Percona Server for MongoDB

Percona Server for MongoDB stores the data files in /var/lib/mongodb/ by default. You can find the configuration file that is used to manage Percona Server for MongoDB in /etc/mongod.conf.
1. Starting the service
Percona Server for MongoDB is started automatically after it gets installed unless it encounters errors during
the installation process. You can also manually start it by running:
$ sudo service mongod start

2. Confirming that service is running

You can check the service status by running:
$ service mongod status

3. Stopping the service

You can stop the service by running:
$ sudo service mongod stop

4. Restarting the service

You can restart the service by running:
$ sudo service mongod restart

Note: Debian 8.0 (jessie) and Ubuntu 15.04 (vivid) come with systemd as the default system and service manager so
you can invoke all the above commands with sytemctl instead of service. Currently both are supported.

Uninstalling Percona Server for MongoDB

To uninstall Percona Server for MongoDB youll need to 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 files (all the databases). Depending on your needs you can
choose which command better suits you.
1. Stop the Percona Server for MongoDB service
$ sudo service mongod stop

2. Remove the packages

(a) Remove the packages. This will leave the data files (databases, tables, logs, configuration, etc.) behind. In
case you dont need them youll need to remove them manually.

1.1. Installing Percona Server for MongoDB 5.6

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

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

(a) Purge the packages. NOTE: This will remove all the packages and delete all the data files (databases,
tables, logs, etc.)
$ sudo apt-get purge percona-server-mongodb*

Installing Percona Server for MongoDB on Red Hat Enterprise Linux and CentOS
Ready-to-use packages are available from the Percona software repositories and the download page. The Percona
yum repository supports popular RPM-based operating systems, including the Amazon Linux AMI.
The easiest way to install the Percona Yum repository is to install an RPM that configures yum and installs the Percona
GPG key.
Supported Releases:
CentOS 5 and RHEL 5
CentOS 6 and RHEL 6 (Current Stable) 1
CentOS 7 and RHEL 7
The CentOS repositories should work well with Red Hat Enterprise Linux too, provided that yum is installed on the
server.
Supported Platforms:
x86_64 (also known as amd64)
Whats in each RPM package?

Each of the Percona Server for MongoDB RPM packages have a particular purpose.
The Percona-Server-MongoDB meta package will install the mongo shell, import/export tools, other client
utilities, server software, default configuration, and init.d scripts.
The Percona-Server-MongoDB-debuginfo package contains debug symbols and information for the server
package.
The Percona-Server-MongoDB-server package contains Percona Server for MongoDB server software, default configuration files and service management scripts.
The Percona-Server-MongoDB-shell package contains the Percona Server for MongoDB shell.
The Percona-Server-MongoDB-mongos package contains mongos - the Percona Server for MongoDB
sharded cluster query router.
The Percona-Server-MongoDB-tools package contains Mongo tools for high-performance MongoDB fork
from Percona.
1 Current Stable: We support only the current stable RHEL6/CentOS6 release, because there is no official (i.e. RedHat provided) method to
support or download the latest OpenSSL on RHEL/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/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/Centos
repository for versions 6.4 and prior. For any officially unsupported system, src.rpm packages may be used to rebuild Percona Server for any
environment. Please contact our support service if you require further information on this.

Chapter 1. Installation

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Installing Percona Server for MongoDB from Percona yum repository

1. Install the Percona repository

You can install Percona yum repository by running the following command as a root user or with sudo:

yum install http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.

You should see some output such as the following:

Retrieving http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.n
Preparing...
########################################### [100%]
1:percona-release
########################################### [100%]

Note: RHEL/Centos 5 doesnt support installing the packages directly from the remote location so youll need to
download the package first and install it manually with rpm:

wget http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.
rpm -ivH percona-release-0.1-3.noarch.rpm

2. Testing the repository

Make sure packages are now available from the repository, by executing the following command:
yum list | grep percona

You should see output similar to the following:

...
Percona-Server-MongoDB.x86_64
Percona-Server-MongoDB-debuginfo.x86_64
Percona-Server-MongoDB-mongos.x86_64
Percona-Server-MongoDB-server.x86_64
Percona-Server-MongoDB-shell.x86_64
Percona-Server-MongoDB-tools.x86_64
...

3.0.5-rel0.7rc.el6
3.0.5-rel0.7rc.el6
3.0.5-rel0.7rc.el6
3.0.5-rel0.7rc.el6
3.0.5-rel0.7rc.el6
3.0.5-rel0.7rc.el6

percona-release-x86_64
percona-release-x86_64
percona-release-x86_64
percona-release-x86_64
percona-release-x86_64
percona-release-x86_64

3. Install the packages

You can now install Percona Server by running:
yum install Percona-Server-MongoDB

Percona yum Testing repository Percona offers pre-release builds from our testing repository.
To subscribe to the testing repository, youll need to enable the testing repository in
/etc/yum.repos.d/percona-release.repo. To do so, set both percona-testing-$basearch and
percona-testing-noarch to enabled = 1 (Note that there are 3 sections in this file: release, testing and
experimental - in this case it is the second section that requires updating). NOTE: Youll need to install the Percona
repository first (ref above) if this hasnt been done already.
Running Percona Server for MongoDB

Percona Server for MongoDB stores the data files in /var/lib/mongodb/ by default. You can find the configuration file that is used to manage Percona Server in /etc/mongod.cnf.
1. Starting the service

1.1. Installing Percona Server for MongoDB 5.6

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Percona Server for MongoDB isnt started automatically on RHEL and CentOS after it gets installed. You
should start it by running:
service mongod start

2. Confirming that service is running

You can check the service status by running:
service mongod status

3. Stopping the service

You can stop the service by running:
service mongod stop

4. Restarting the service

You can restart the service by running:
service mongod restart

Note: RHEL 7 and CentOS 7 come with systemd as the default system and service manager so you can invoke all the
above commands with sytemctl instead of service. Currently both are supported.

Uninstalling Percona Server for MongoDB

To completely uninstall Percona Server for MongoDB youll need to remove all the installed packages and data files.
1. Stop the Percona Server for MongDB service
service mongod stop

2. Remove the packages

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 take a backup before doing this in case you need the data.

1.2 Replacing MongoDB with Percona Server for MongoDB

In-place upgrades are those which are done using the 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 they
may not be suitable for high-complexity environments, they may be adequate for many scenarios.
Warning: Before starting the upgrade process its recommended that you perform a full backup (if you dont have
one already).

Chapter 1. Installation

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

1.2.1 Replacing MongoDB on CentOS/RHEL

1. Stop the mongod process:
$ service mongod stop

2. Check for the 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 the 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. You can now proceed with steps described in Installing Percona Server for MongoDB on Red Hat Enterprise
Linux and CentOS.

1.2.2 Replacing MongoDB on Debian/Ubuntu

1. Stop the mongod process:
$ service mongod stop

2. Check for the installed packages:

$ dpkg -l | grep mongod
ii
ii
ii
ii
ii

mongodb-org
mongodb-org-mongos
mongodb-org-server
mongodb-org-shell
mongodb-org-tools

3.0.6
3.0.6
3.0.6
3.0.6
3.0.6

amd64
amd64
amd64
amd64
amd64

MongoDB
MongoDB
MongoDB
MongoDB
MongoDB

3. Remove the installed packages:

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

4. You can now proceed with steps described in Installing Percona Server for MongoDB on Debian and Ubuntu.

1.3 Building Pecona Server for MongoDB

To build Pecona Server for MongoDB, you will need:
One of the following C++ compilers:
GCC 4.8.2 or newer
Clang 3.4 (or Apple XCode 5.1.1 Clang) or newer

1.3. Building Pecona Server for MongoDB

open
shard
datab
shell
tools

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Visual Studio 2013 Update 2 or newer

Python 2.7
SCons 2.3

1.3.1 MongoDB Tools

The MongoDB command-line tools (mongodump, mongorestore, mongoimport, mongoexport, etc) have
been rewritten in Go and are no longer included in this repository.
The source for the tools is now available at Github.

1.3.2 SCons
For detailed information about building, please see the build manual
If you want to build everything (mongod, mongo, tests, etc):
$ scons all

If you only want to build the database:

$ scons

To install:
$ scons --prefix=/opt/mongo install

Please note that prebuilt binaries are available from MongoDB Downloads and may be the easiest way to get started.

1.3.3 SCons Targets

mongod
mongos
mongo
core (includes mongod, mongos, mongo)
all

1.3.4 Windows
See the Windows build manual
Build requirements:
Visual Studio 2013 Update 2 or newer
Python 2.7, ActiveState ActivePython 2.7.x Community Edition for Windows is recommended
SCons
Or download a prebuilt binary for Windows from MongoDB.

10

Chapter 1. Installation

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

1.3.5 Debian/Ubuntu
To install dependencies on Debian or Ubuntu systems:

# aptitude install scons build-essential

# aptitude install libboost-filesystem-dev libboost-program-options-dev libboost-system-dev libboost-

To run tests as well, you will need PyMongo:

# aptitude install python-pymongo

Then build as usual:

$ scons all

1.3.6 OS X
Using Homebrew:
$ brew install mongodb

Using MacPorts:
$ sudo port install mongodb

1.3.7 FreeBSD
Install the following ports:
devel/libexecinfo
devel/scons
lang/gcc
lang/python
Optional components if you want to use system libraries instead of the libraries included with MongoDB:
archivers/snappy
lang/v8
devel/boost
devel/pcre

1.3.8 OpenBSD
Install the following ports:
devel/libexecinfo
devel/scons
lang/gcc
lang/python

1.3. Building Pecona Server for MongoDB

11

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

12

Chapter 1. Installation

CHAPTER

TWO

FEATURES

2.1 External Authentication

This section describes how to create a one-machine installation of all the components necessary for testing LDAP
authentication in MongoDB.

2.1.1 Environment Prerequisites

This guides describes how to set up a suitable environment for testing the implementation of LDAP authentication for
MongoDB. The setup steps should be performed on a given Linux distribution, and certain open-source components
must be installed and then specially configured.
Component Installation
Installing SASL
Environment Configuration
Running the LDAP service
Enter users into LDAP service
Building MongoDB
Adding SASL support

Component Installation
The following components are required:
libsasl2 version 2.1.25: C library used in client and server code.
saslauthd: SASL Authentication Daemon. This is distinct from libsasl2.
slapd: OpenLDAP Server.
Note: We have been sandboxing the slapd daemon on our test machines. This means we just download the
OpenLDAP source code, build it locally, and install it in an arbitrary test directory local to the current working
directory.

Installing SASL

There are two SASL components that need to be installed. First is the SASL library itself, libsasl2, along with its
development header sasl.h. Second is saslauthd, the authentication daemon.
13

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Both SASL components can be downloaded, built and installed from source.
On Ubuntu, the following packages should be installed:
libsasl2-2
libsasl2-dev
libsasl2-modules
sasl2-bin
ldap-utils
Optional packages:
cyrus-sasl2-dbg
cyrus-sasl2-doc
Environment Configuration
Running the LDAP service

Start the LDAP server in the background or in a dedicated tmux pane for testing. 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 -d 1

The URL argument will be used for both entering data into the LDAP database, verifying entries, and as an endpoint for
saslauthd to authenticate against during MongoDB external authentication. The -d option is for helpful debugging
information to help track incoming LDAP requests and responses.
An LDAP configuration file, with simple settings suitable for testing, would have contents like this:
database
suffix
rootdn
rootpw
directory

mdb
"dc=example,dc=com"
"cn=openldapper,dc=example,dc=com"
secret
/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. OpenLDAP installations have a sample slapd.conf file that has the above and other required entries, such as include,
pidfile, and argsfile.
Note: We use the mdb database here because we dont want to add a dependency on a Berkeley DB installation. The
MDB database is an in-memory database compiled as part of the OpenLDAP installation.

Enter users into LDAP service

OpenLDAP comes with a few programs to communicate with the LDAP daemon/service. For example, to enter new
entries into the LDAP database, you could use ldapadd or ldapmodify, with an associated .ldif file.
Building MongoDB
To connect to these services, MongoDB must be built with extra information.

14

Chapter 2. Features

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Adding SASL support

Both client and server components (mongo and mongod/mongos), must be specially compiled to enable external
authentication.
To set up the initial build environment, you need to follow the basic build instructions: Building Pecona Server for
MongoDB.
Both the client and server must be linked with libsasl2.so.
This just means that an extra flag
--use-sasl-client must be passed to SCons at build configuration time. A quick build would look like this:
$ cd percona-server-mongodb
$ git checkout v3.0
$ scons --use-sasl-client -j8 mongo mongod

Once configured, the mongo binaries can be built, installed, and packaged as usual. Note that libsasl2 is NOT
statically linked, so any user planning on running either the client or server binaries will need the SASL library installed
in the same place it was installed at build time.

2.1.2 Client and Server Setup

This document describes how to configure saslauthd, libsasl2, mongo, and mongod/mongos to use external
authentication. It assumes that those binaries have been installed in the proper locations and an LDAP service has been
setup, is reachable, and has users and credentials installed.
Configure saslauthd
OpenLDAP
Microsoft Windows Active Directory
Sanity Check
Configure libsasl2
Configure mongod/mongos Server
Adding external users
Client Authentication

Configure saslauthd
First, we have to make sure saslauthd is configured correctly. Like other systems in this project, saslauthd
relies on a configuration file.
OpenLDAP

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.
This is a temporary setup for testing.
2.1. External Authentication

15

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

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.
For saslauthd to successfully communicate with an Active Directory server, it must use the following configuration
parameters:
ldap_servers: <ldap uri>
ldap_mech: PLAIN
ldap_search_base: CN=Users,DC=<AD Domain>,DC=<AD TLD>
ldap_filter: (sAMAccountName=%u)
ldap_bind_dn: CN=<AD LDAP lookup user name>,CN=Users,DC=<AD Domain>,DC=<AD TLD>
ldap_password: <AD LDAP lookup password>

For example:
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=<AD Domain>,DC=<AD TLD>
ldap_password: ld@pmgr_Pa55word

In order to determine and test the correct search base and filter for your Active Directory installation, the Microsoft
LDP GUI Tool can be used to bind and search the LDAP-compatible directory.
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 doesnt, then either the user name and password are not in the LDAP
service, or sasaluthd is not configured properly.
Configure libsasl2
The SASL library used by mongod/mongos must also be configured properly via a configuration file.
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/mongos 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.
Configure mongod/mongos Server
External authentication is enabled the same way as local authentication. Simply start the server with the --auth
option:

16

Chapter 2. Features

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

$ ./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 servers environment.
Adding external users
Use the following command to add an external user to the mongod server:
$ db.getSiblingDB("$external").createUser( {user : christian, roles: [ {role: "read", db: "test"} ]}

Currently, you can only add externally authenticated users via the mongo shell included with the TokuMX build. The
command is a hybrid of 2.4 and 2.6 administration methods. This also assumes that you have set up the server-wide
admin user/role and have successfully locally authenticated as that admin user.
The mongo client will add an external user to each database filed in the roles array. To remove a user from a database
simply use the existing 2.4 call db.removeUser().
Note: There is no single command to remove the external user from all the databases. The removeUser()
command must be called on each database for the given user.
Note: External users cannot have roles assigned in the admin database.

Client Authentication
When running the mongo client, a user can authenticate against a given database using the following command:
$ db.auth({ mechanism:"PLAIN", user:"christian", pwd:"secret", digestPassword:false})

The other MongoDB drivers need to support the 2.4 interface for authenticating externally. This means they must:
Be compiled/run with SASL authentication support. Should include usage of the libsasl2 library.
Allow users to specify a BSON argument for auth() calls.
Allow users to specify the authentication mechanism field in the BSON argument.
Allow users to specify the digestPassword field.
Our implementation follows the 2.4 mongo client code, although some drivers diverge from this logic. For example,
some driver versions only conform to the 2.6 external authentication API, which will not work with the 2.4-based
TokuMX implementation.
These newer driver clients expect the external user to only authenticate against the $external database, not a regular
local database. The driver may need to be modified to detect the mechanism field being set, and then take the external
authentication path, using the local database name instead of $external. Drivers that are totally compatible with
the 2.4 mongo client should work as expected.

2.1.3 Building and Testing

This guide describes how to build Percona Server for MongoDB and test external authentication on Ubuntu 14.x
docker image or bare bones machine.

2.1. External Authentication

17

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Build and Test Requirements

Transparent Huge Pages
Using Docker
Download the source
Deploying OpenLDAP Server and Cyrus SASL
Build
Install
Run Tests

Build and Test Requirements

A bare bones Ubuntu 14.x or Debian 7.x installation
Minimum 3 GB RAM
Minimum 20 GB free space
An internet connection to download tools and source code
Transparent Huge Pages
Percona Server for MongoDB comes with the Percona Fractal Tree storage engine. This engine requires the transparent
huge page feature of modern Linux kernels to be disabled. Before running the server with the Percona Fractal Tree, it
is important to disable this feature on the machine. If you are building and testing under Docker, you will need to set
these in the host machines kernel before running the container.
$ sudo /bin/bash -c echo never > /sys/kernel/mm/transparent_hugepage/enabled
$ sudo /bin/bash -c echo never > /sys/kernel/mm/transparent_hugepage/defrag

Using Docker
Most default Docker installations do not provide enough free space to build and test external authentication. You may
need to use the --volume option to map a host directory to the Docker container.

$ mkdir $HOME/percona-server-mongodb
$ docker run -ti --name=percona-server-mongodb --volume=$HOME/percona-server-mongodb:/root docker.i

Download the source

Execute the following as root:
$
$
$
$
$

apt-get update -y
apt-get install -y git
mkdir -p ~/git
cd ~/git
git clone https://github.com/Percona/percona-server-mongodb.git

Deploying OpenLDAP Server and Cyrus SASL

Execute the following as root:

18

Chapter 2. Features

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

$ cd ~/git/percona-server-mongodb/support-files/ldap-sasl
$ ./deploy_ldap_and_sasl.sh

After the script runs you should see 0: OK "Success." reported at the end. To run a test of the OpenLDAP/Cyrus SASL installation you can run the check_saslauthd.sh script.
This will ensure all the proper LDAP authentication for all of the accounts used in the external authentication test
suite.
Build
The following script will install the tool chain, download all of the sources, compile and package the result into a
tarball.
$ cd ~/git/percona-server-mongodb/scripts
$ ./build_ubuntu14.sh

Note: The script builds the binaries without debug symbols by default. You may edit the value at the top of
scripts/build_ubuntu14.sh to build the Debug version.

Install
The packages will be built in the ~/git/mongo repository location.
Execute the following as root:
$ cd ~
$ tar xzvf ~/git/percona-server-mongodb/......tar.gz

Run Tests
Once the executables have been compiled and installed, and OpenLDAP and Cyrus SASL are running, you can run
the external authentication test suite:
$ cd ~/git/percona-server-mongodb/jstests/external_auth
$ export MONGODB_HOME=$HOME/tokumx-2.0.1-linux-x86_64
$ ./run.sh

The output should resemble the following:

mongod startup (opts: )
Database Setup Script
mongod shutdown
mongod startup (opts: --auth)
Add Local Users
Add External Users
Test invalid account names and passwords
External user with read (only) access to test
External user with readWrite access to test
Local user with read (only) access to test
Local user with readWrite access to test
External user with read (only) access to other
External user with readWrite access to other
Local user with read (only) access to other
Local user with readWrite access to other

2.1. External Authentication

[OK]
[OK]
[OK]
[OK]
[OK]
[OK]
[OK]
[OK]
[OK]
[OK]
[OK]
[OK]
[OK]
[OK]
[OK]

19

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

External user with

External user with
External user with
External user with
mongod shutdown

read (only) access to both test and other

readWrite access to both test and other
read (only) on test and readWrite on other
readWrite on test and read (only) on other

[OK]
[OK]
[OK]
[OK]
[OK]

2.1.4 Overview
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 clients user name and password against a separate service, such as OpenLDAP or Active Directory.
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 authentication mechanism-specific data.
Authentication Sequence
An authentication session in this environment moves from component to component in the following way:
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 mechanism (in this case 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.

2.1.5 Client Authentication

Use the following command to add an external user to the mongod server:
$ db.getSiblingDB("$external").createUser( {user : christian, roles: [ {role: "read", db: "test"} ]}

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", digestPasswo

20

Chapter 2. Features

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

See Also
SASL documentation:

2.2 Auditing
This document describes how to build, enable, configure and test auditing in Percona Server for MongoDB.
Auditing allows administrators to track and log user activity on a 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.
Building
Activation and Configuration
Testing

2.2.1 Building
By default, when building Percona Server for MongoDB from source, audit functionality is neither compiled with, nor
linked into, the final binary executable. To enable auditing, execute SCons with the --audit option:
$ scons <other options> --audit <targets>

2.2.2 Activation and Configuration

The following server parameters control auditing. They are entered at the command line when starting a server
instance.
--auditDestination
By default, even when auditing functionality is compiled into the server executable, 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 is the type of audit log the server will create when storing events. In
Percona Server for MongoDB, this can only be set to file.
$ mongod --auditDestination=file

Note: Auditing remains active until shutdown, it cannot be disabled dynamically at runtime.
--auditFormat
This is the format of each audit event stored in the audit log. In Percona Server for MongoDB, this can
only be set to JSON. The default value for this parameter is also JSON, thus this parameter is optional
and is only provided for application and driver compatibility.
$ mongod --auditDestination=file --auditFormat=JSON

--auditPath

2.2. Auditing

21

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

This is the fully qualified path to the file you want the server to create. If this parameter is not specified
then auditLog.json file will be created in servers configured log path.
$ mongod --auditDestination=file --auditPath /var/log/tokumx/audit.json

If log path is not configured then auditLog.json will be created in the current directory.
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 the rotation will be added to the old files name.
--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/tokumx/audit.json \
--auditFilter { "users.user" : "tim" }

2.2.3 Testing
There are dedicated audit JavaScript tests under the jstests/audit directory. To execute all of them, run the
following:
$ python buildscripts/resmoke.py --audit

Note: the mongoimport utility is required to run the audit tests. It must be placed in the same directory from which
resmoke.py is run. Typically this location is the top level MongoDB build/source directory.

22

Chapter 2. Features

CHAPTER

THREE

REFERENCE

3.1 Percona Server for MongoDB Release notes

3.1.1 Percona Server for MongoDB 3.0.5-rc7
Percona is glad to announce the release of Percona Server for MongoDB on September 16th, 2015. Downloads are
available here and from the Percona Software Repositories.
New Features

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

23

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

3.3 Copyright and Licensing Information

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

3.3.2 Software License

3.4 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 companys or persons products and services from anothers.
Percona owns a number of marks, including but not limited to Percona, XtraDB, Percona XtraDB, XtraBackup, Percona 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 Perconas 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
trademarks@percona.com for assistance and we will do our very best to be helpful.
24

Chapter 3. Reference

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

genindex

3.4. Trademark Policy

25

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

26

Chapter 3. Reference

INDEX

Symbols
3.0.5-rc7 (release notes), 23

A
ACID, 23
Atomicity, 23

C
Consistency, 23

D
Durability, 23

F
Foreign Key, 23

I
Isolation, 23

J
Jenkins, 23

27