Percona Server for MongoDB 305

Percona Server for MongoDBDocumentation

Release 3.0.5-rc7

Percona LLC and/or its affiliates 2015

September 16, 2015

CONTENTS

1 Installation 31.1 Installing Percona Server for MongoDB 5.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Replacing MongoDB with Percona Server for MongoDB . . . . . . . . . . . . . . . . . . . . . . . . 81.3 Building Pecona Server for MongoDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2 Features 132.1 External Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.2 Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3 Reference 233.1 Percona Server for MongoDB Release notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233.2 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233.3 Copyright and Licensing Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243.4 Trademark Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Index 27

i

Percona Server for MongoDB Documentation, Release 3.0.5-rc7

Percona Server for MongoDB is a highly scalable, zero-maintenance downtime database supporting the MongoDBv3.0 protocol and drivers. It extends MongoDB with RocksDB and PerconaFT storage engines, as well as features likeexternal authentication and audit logging. Percona Server for MongoDB requires no changes to MongoDB applicationsor 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 1


2 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 areavailable:

• 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 (.debpackages 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 system’s packagemanager. This is the recommend way of installing where possible.

Following guides describe the installation process for using the official Percona repositories for .deb and .rpmpackages.

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

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)

3

http://www.percona.com/downloads/Percona-Server-for-MongoDB/LATEST/

http://www.percona.com/downloads/Percona-Server-for-MongoDB/LATEST/


What’s 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 MongoDBsharded cluster query router.

The percona-server-mongodb-tools package contains Mongo tools for high-performance MongoDB forkfrom 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 Percona’s GPG key. Before using therepository, 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 you’re getting timeouts when using keys.gnupg.net as an alternative you can fetchthe key from keyserver.ubuntu.com.

2. Create the apt source list for Percona’s 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.list.d/percona.list

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/sources.list.d/percona.list

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 addthe 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 thename of your distribution):

deb http://repo.percona.com/apt VERSION main testingdeb-src http://repo.percona.com/apt VERSION main testing

4 Chapter 1. Installation


Apt-Pinning the packages In some cases you might need to “pin” the selected packages to avoid the upgrades fromthe distribution repositories. You’ll need to make a new file /etc/apt/preferences.d/00percona.prefand add the following lines in it:

Package: *Pin: release o=Percona Development TeamPin-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 configura-tion 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 duringthe 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 soyou 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 you’ll need to remove all the installed packages. Removing packages withapt-get remove will leave the configuration and data files. Removing the packages with apt-get purge willremove all the packages with configuration files and data files (all the databases). Depending on your needs you canchoose 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. Incase you don’t need them you’ll need to remove them manually.

1.1. Installing Percona Server for MongoDB 5.6 5

http://wiki.debian.org/AptPreferences

http://freedesktop.org/wiki/Software/systemd/


$ 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 Perconayum 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 PerconaGPG 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 theserver.

Supported Platforms:

• x86_64 (also known as amd64)

What’s 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 clientutilities, server software, default configuration, and init.d scripts.

The Percona-Server-MongoDB-debuginfo package contains debug symbols and information for the serverpackage.

The Percona-Server-MongoDB-server package contains Percona Server for MongoDB server software, de-fault 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 MongoDBsharded cluster query router.

The Percona-Server-MongoDB-tools package contains Mongo tools for high-performance MongoDB forkfrom Percona.

1 “Current Stable”: We support only the current stable RHEL6/CentOS6 release, because there is no official (i.e. RedHat provided) method tosupport or download the latest OpenSSL on RHEL/CentOS versions prior to 6.5. Similarly, and also as a result thereof, there is no official Perconaway to support the latest Percona Server builds on RHEL/CentOS versions prior to 6.5. Additionally, many users will need to upgrade to OpenSSL1.0.1g or later (due to the Heartbleed vulnerability), and this OpenSSL version is not available for download from any official RHEL/Centosrepository for versions 6.4 and prior. For any officially unsupported system, src.rpm packages may be used to rebuild Percona Server for anyenvironment. Please contact our support service if you require further information on this.


http://www.percona.com/downloads/Percona-Server-for-MongoDB/

https://www.percona.com/downloads/RPM-GPG-KEY-percona

https://www.percona.com/downloads/RPM-GPG-KEY-percona

http://www.percona.com/resources/ceo-customer-advisory-heartbleed

http://www.percona.com/products/mysql-support


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

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.noarch.rpmPreparing... ########################################### [100%]

1:percona-release ########################################### [100%]

Note: RHEL/Centos 5 doesn’t support installing the packages directly from the remote location so you’ll need todownload 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.rpmrpm -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 3.0.5-rel0.7rc.el6 percona-release-x86_64Percona-Server-MongoDB-debuginfo.x86_64 3.0.5-rel0.7rc.el6 percona-release-x86_64Percona-Server-MongoDB-mongos.x86_64 3.0.5-rel0.7rc.el6 percona-release-x86_64Percona-Server-MongoDB-server.x86_64 3.0.5-rel0.7rc.el6 percona-release-x86_64Percona-Server-MongoDB-shell.x86_64 3.0.5-rel0.7rc.el6 percona-release-x86_64Percona-Server-MongoDB-tools.x86_64 3.0.5-rel0.7rc.el6 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 reposi-tory. To subscribe to the testing repository, you’ll need to enable the testing repository in/etc/yum.repos.d/percona-release.repo. To do so, set both percona-testing-$basearch andpercona-testing-noarch to enabled = 1 (Note that there are 3 sections in this file: release, testing andexperimental - in this case it is the second section that requires updating). NOTE: You’ll need to install the Perconarepository first (ref above) if this hasn’t 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 configura-tion 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 7


Percona Server for MongoDB isn’t started automatically on RHEL and CentOS after it gets installed. Youshould 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 theabove commands with sytemctl instead of service. Currently both are supported.

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 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/mongodbrm -f /etc/mongod.cnf

Warning: This will remove all the packages and delete all the data files (databases, tables, logs, etc.), you mightwant 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 stoppingthe server, removing the old packages, installing the new server and starting it with the same data files. While theymay not be suitable for high-complexity environments, they may be adequate for many scenarios.

Warning: Before starting the upgrade process it’s recommended that you perform a full backup (if you don’t haveone already).


http://freedesktop.org/wiki/Software/systemd/


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_64mongodb-org-server-3.0.6-1.el6.x86_64mongodb-org-shell-3.0.6-1.el6.x86_64mongodb-org-mongos-3.0.6-1.el6.x86_64mongodb-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 EnterpriseLinux 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 mongodb-org 3.0.6 amd64 MongoDB open source document-oriented database system (metapackage)ii mongodb-org-mongos 3.0.6 amd64 MongoDB sharded cluster query routerii mongodb-org-server 3.0.6 amd64 MongoDB database serverii mongodb-org-shell 3.0.6 amd64 MongoDB shell clientii mongodb-org-tools 3.0.6 amd64 MongoDB tools

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 9


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


http://golang.org/

https://github.com/mongodb/mongo-tools

http://www.mongodb.org/about/contributors/tutorial/build-mongodb-from-source/

http://www.mongodb.org/downloads

http://www.mongodb.org/about/contributors/tutorial/build-mongodb-from-source/#windows-specific-instructions


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-thread-dev

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

http://brew.sh

http://www.macports.org

CHAPTER

TWO

FEATURES

2.1 External Authentication

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

2.1.1 Environment Prerequisites

This guides describes how to set up a suitable environment for testing the implementation of LDAP authentication forMongoDB. The setup steps should be performed on a given Linux distribution, and certain open-source componentsmust 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 theOpenLDAP source code, build it locally, and install it in an arbitrary test directory local to the current workingdirectory.

Installing SASL

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

13


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 configura-tion file. Also note the username: openldapper. It is important that the user starting the service, and adding entries tothe 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 forsaslauthd to authenticate against during MongoDB external authentication. The -d option is for helpful debugginginformation to help track incoming LDAP requests and responses.

An LDAP configuration file, with simple settings suitable for testing, would have contents like this:

database mdbsuffix "dc=example,dc=com"rootdn "cn=openldapper,dc=example,dc=com"rootpw secretdirectory /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.

Note: We use the mdb database here because we don’t want to add a dependency on a Berkeley DB installation. TheMDB 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 newentries 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


Adding SASL support

Both client and server components (mongo and mongod/mongos), must be specially compiled to enable externalauthentication.

To set up the initial build environment, you need to follow the basic build instructions: Building Pecona Server forMongoDB.

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 NOTstatically linked, so any user planning on running either the client or server binaries will need the SASL library installedin 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 externalauthentication. It assumes that those binaries have been installed in the proper locations and an LDAP service has beensetup, 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, saslauthdrelies on a configuration file.

OpenLDAP

These are the typical settings required for saslauthd to connect to a local OpenLDAP service (the server addressMUST match the OpenLDAP installation):

ldap_servers: ldap://127.0.0.1:9009ldap_search_base: dc=example,dc=comldap_filter: (cn=%u)ldap_bind_dn: cn=openldapper,dc=example,dc=comldap_password: secret

Note the LDAP password and bind domain name. This allows the saslauthd service to connect to the LDAP serviceas 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


Microsoft Windows Active Directory

In order for LDAP operations to be performed against a Windows Active Directory server, a user record must becreated to perform the lookups.

For saslauthd to successfully communicate with an Active Directory server, it must use the following configurationparameters:

ldap_servers: <ldap uri>ldap_mech: PLAINldap_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.10ldap_mech: PLAINldap_search_base: CN=Users,DC=example,DC=comldap_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 MicrosoftLDP 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 LDAPservice, 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: saslauthdsaslauthd_path: /var/run/saslauthd/muxlog_level: 5mech_list: plain

The first two entries (pwcheck_method and saslauthd_path) are required for mongod/mongos to success-fully 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 theinstallation method.

Configure mongod/mongos Server

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


https://technet.microsoft.com/en-us/library/Cc772839%28v=WS.10%29.aspx


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

This assumes that libsasl2 has been installed in the system as a dynamic library (libsasl2.so). You may seean error on the command line or in the logs if that library is missing from your server’s 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. Thecommand is a hybrid of 2.4 and 2.6 administration methods. This also assumes that you have set up the server-wideadmin 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 databasesimply 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-basedTokuMX implementation.

These newer driver clients expect the external user to only authenticate against the $external database, not a regularlocal database. The driver may need to be modified to detect the mechanism field being set, and then take the externalauthentication path, using the local database name instead of $external. Drivers that are totally compatible withthe 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.xdocker image or bare bones machine.



• 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 transparenthuge page feature of modern Linux kernels to be disabled. Before running the server with the Percona Fractal Tree, itis important to disable this feature on the machine. If you are building and testing under Docker, you will need to setthese in the host machine’s 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 mayneed 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.io/ubuntu:14.10 /bin/bash

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




$ 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 OpenL-DAP/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 testsuite.

Build

The following script will install the tool chain, download all of the sources, compile and package the result into atarball.

$ 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 ofscripts/build_ubuntu14.sh to build the Debug version.

Install

The packages will be built in the ~/git/mongo repository location.


$ 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 runthe 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: ) [OK]Database Setup Script [OK]mongod shutdown [OK]mongod startup (opts: --auth) [OK]Add Local Users [OK]Add External Users [OK]Test invalid account names and passwords [OK]External user with read (only) access to ’test’ [OK]External user with readWrite access to ’test’ [OK]Local user with read (only) access to ’test’ [OK]Local user with readWrite access to ’test’ [OK]External user with read (only) access to ’other’ [OK]External user with readWrite access to ’other’ [OK]Local user with read (only) access to ’other’ [OK]Local user with readWrite access to ’other’ [OK]



External user with read (only) access to both ’test’ and ’other’ [OK]External user with readWrite access to both ’test’ and ’other’ [OK]External user with read (only) on ’test’ and readWrite on ’other’ [OK]External user with readWrite on ’test’ and read (only) on ’other’ [OK]mongod shutdown [OK]

2.1.4 Overview

Normally, a client needs to authenticate themselves against the MongoDB server user database before doing any workor reading any data from a mongod or mongos instance. External authentication allows the MongoDB server to verifythe client’s 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 mecha-nism (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 thesaslauthd daemon.

7. The saslauthd daemon passes the payload on to the LDAP service to get a YES or NO authenticationresponse (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", digestPassword:false})



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 generatean audit log file. This file contains information about different user events including authentication, authorizationfailures, 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, norlinked 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 serverinstance.

--auditDestination

By default, even when auditing functionality is compiled into the server executable, audit logging isdisabled. Auditing and audit log generation are activated when this parameter is present on the commandline at server startup.

The argument to this parameter is the type of audit log the server will create when storing events. InPercona 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 canonly be set to JSON. The default value for this parameter is also JSON, thus this parameter is optionaland is only provided for application and driver compatibility.

$ mongod --auditDestination=file --auditFormat=JSON

--auditPath

2.2. Auditing 21

http://cyrusimap.web.cmu.edu/docs/cyrus-sasl/2.1.25/


This is the fully qualified path to the file you want the server to create. If this parameter is not specifiedthen auditLog.json file will be created in server’s 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 thelogRotate command. The time of the rotation will be added to the old file’s name.

--auditFilter

This parameter specifies a filter to apply to incoming audit events, enabling the administrator to onlycapture 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 thatmatches this query will be logged. Events which do not match this query will be ignored. If this parameteris 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 thefollowing:

$ 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 whichresmoke.py is run. Typically this location is the top level MongoDB build/source directory.


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 areavailable 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 iseither fully applied or not at all.

Consistency Consistency means that each transaction that modifies the database takes it from one consistent state toanother.

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 tablemust 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 softwarewe 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

https://www.percona.com/downloads/percona-server-for-mongodb

http://www.jenkins-ci.org


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 CreativeCommons 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 receivehas really been developed, approved, tested and maintained by Percona. Trademarks help to prevent confusion in themarketplace, 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 thesemarks. 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 Perconaproduct.

Second, when Percona has released a product under a version of the GNU General Public License (“GPL”), you mayuse the appropriate Percona mark when distributing a verbatim copy of that product in accordance with the terms andconditions of the GPL.

Third, you may use the appropriate Percona mark to refer to a distribution of GPL-released Percona software that hasbeen modified with minor changes for the sole purpose of allowing the software to operate on an operating systemor hardware platform for which Percona has not yet released the software, provided that those third party changesdo not affect the behavior, functionality, features, design or performance of the software. Users who acquire thisPercona-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 Perconabelieves that your modification is beyond the scope of the limited license granted in this Policy or that your useof the Percona mark is detrimental to Percona, Percona will revoke this authorization. Upon revocation, you mustimmediately cease using the applicable Percona mark. If you do not immediately cease using the Percona mark uponrevocation, Percona may take action to protect its rights and interests in the Percona mark. Percona does not grant anylicense to use any Percona mark for any other modified versions of Percona software; such use will require our priorwritten permission.

Neither trademark law nor any of the exceptions set forth in this Trademark Policy permit you to truncate, modify orotherwise use any Percona mark as part of your own brand. For example, if XYZ creates a modified version of thePercona Server, XYZ may not brand that modification as “XYZ Percona Server” or “Percona XYZ Server”, even ifthat 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 fromtime to time. For instance, any mention of Percona trademarks should include the full trademarked name, with properspelling and capitalization, along with attribution of ownership to Percona Inc. For example, the full proper name forXtraBackup is Percona XtraBackup. However, it is acceptable to omit the word “Percona” for brevity on the secondand 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 [email protected] for assistance and we will do our very best to be helpful.

24 Chapter 3. Reference

http://creativecommons.org/licenses/by-sa/2.0/

http://creativecommons.org/licenses/by-sa/2.0/

mailto:[email protected]


• genindex

3.4. Trademark Policy 25


26 Chapter 3. Reference

INDEX

Symbols3.0.5-rc7 (release notes), 23

AACID, 23Atomicity, 23

CConsistency, 23

DDurability, 23

FForeign Key, 23

IIsolation, 23

JJenkins, 23

27

Percona Server for MongoDB 305

Documents

Transcript of Percona Server for MongoDB 305