diff --git a/.gitignore b/.gitignore index 7f3d471f8..85e899f37 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ build source/percona-theme/ source/ext/psdom.pyc +*~ \ No newline at end of file diff --git a/source/.res/replace.program.rst~ b/source/.res/replace.program.rst~ new file mode 100644 index 000000000..ae49dfac6 --- /dev/null +++ b/source/.res/replace.program.rst~ @@ -0,0 +1,3 @@ + +.. |mongod| replace:: :program:`mongod` +.. |apt.purge| replace:: :program:`apt purge` diff --git a/source/.res/replace.program.txt b/source/.res/replace.program.txt new file mode 100644 index 000000000..c71bbee7c --- /dev/null +++ b/source/.res/replace.program.txt @@ -0,0 +1,13 @@ + +.. |apt.purge.percona-server-mongodb| replace:: :bash:`apt purge percona-server-mongodb*` +.. |apt.purge| replace:: :program:`apt purge` +.. |apt.remove.percona-server-mongodb| replace:: :bash:`apt remove percona-server-mongodb*` +.. |apt.remove| replace:: :program:`apt remove` +.. |apt.update| replace:: :bash:`apt update` +.. |mongod| replace:: :program:`mongod` +.. |service.mongod.restart| replace:: :bash:`service mongod restart` +.. |service.mongod.start| replace:: :bash:`service mongod start` +.. |service.mongod.status| replace:: :bash:`service mongod status` +.. |service.mongod.stop| replace:: :bash:`service mongod stop` +.. |systemctl.enable.mongod| replace:: :bash:`systemctl enable mongod` +.. |yum.remove.percona-server-mongodb| replace:: :bash:`yum remove percona-server-mongodb*` diff --git a/source/.res/replace.txt b/source/.res/replace.txt new file mode 100644 index 000000000..0c23d39e1 --- /dev/null +++ b/source/.res/replace.txt @@ -0,0 +1,6 @@ + +.. |prev-version| replace:: 3.6 +.. |mongodb-ce| replace:: MongoDB Community Edition +.. |docker| replace:: Docker +.. |tip.run-all.root| replace:: Run the following commands as root or by using the :program:`sudo` command +.. |tip.run-this.root| replace:: Run this command as root or by using the :program:`sudo` command diff --git a/source/.res/replace.txt~ b/source/.res/replace.txt~ new file mode 100644 index 000000000..9bfa1aab7 --- /dev/null +++ b/source/.res/replace.txt~ @@ -0,0 +1,3 @@ + +.. |tip.run-all.root| replace:: Run the following commands as root or by using the :program:`sudo` command +.. |tip.run-this.root| replace:: Run this command as root or by using the :program:`sudo` command diff --git a/source/.res/url.txt b/source/.res/url.txt new file mode 100644 index 000000000..1c3e3ef1d --- /dev/null +++ b/source/.res/url.txt @@ -0,0 +1,6 @@ +.. _Percona website: https://www.percona.com/downloads/percona-server-mongodb-4.0/ +.. _Percona software repositories: https://www.percona.com/doc/percona-server-for-mongodb/4.0/install/index.html +.. _`MMAPv1`: https://docs.mongodb.org/manual/core/mmapv1/ +.. _`WiredTiger`: https://docs.mongodb.org/manual/core/wiredtiger/ +.. _`MongoRocks`: http://rocksdb.org +.. _`Docker Docs`: https://docs.docker.com/ diff --git a/source/.res/url.txt~ b/source/.res/url.txt~ new file mode 100644 index 000000000..7e6e8b9f4 --- /dev/null +++ b/source/.res/url.txt~ @@ -0,0 +1,2 @@ +.. _Percona website: https://www.percona.com/downloads/percona-server-mongodb-4.0/ +.. _Percona software repositories: https://www.percona.com/doc/percona-server-for-mongodb/4.0/install/index.html diff --git a/source/comparison.rst b/source/comparison.rst index 94157c5d5..202fc75d8 100644 --- a/source/comparison.rst +++ b/source/comparison.rst @@ -1,19 +1,17 @@ .. _compare: -============================================= +================================================================================ Percona Server for MongoDB Feature Comparison -============================================= +================================================================================ -|PSMDB| is based on MongoDB 3.6, and it is the successor to Percona TokuMX, +|PSMDB| 4.0 is based on MongoDB 4.0. |PSMDB| is the successor to Percona TokuMX, which is based on MongoDB 2.4. -Both MongoDB and |PSMDB| 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. -For more information about about using various storage engines, -see :ref:`switch_storage_engines`. +Both MongoDB and |PSMDB| 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 could run with only +one default storage engine. For more information about about using various +storage engines, see :ref:`switch_storage_engines`. The following table will help you evaluate the differences. @@ -29,13 +27,12 @@ The following table will help you evaluate the differences. - * WiredTiger_ (default) * MMAPv1_ * :ref:`inmemory` - * :ref:`mongorocks` - * WiredTiger_ (default) * MMAPv1_ * In-Memory_ (Enterprise only) - Built-in storage engine based on the Fractal Tree index * - :ref:`Hot Backup ` - - YES for WiredTiger_ and :ref:`mongorocks` + - YES for WiredTiger_ - NO - YES * - :ref:`Audit Logging ` diff --git a/source/conf.py b/source/conf.py index db1404798..573c146e2 100644 --- a/source/conf.py +++ b/source/conf.py @@ -43,18 +43,19 @@ # The master toctree document. master_doc = 'index' -# General information about the project. -project = u'Percona Server for MongoDB 3.6 documentation' -copyright = u'Percona LLC and/or its affiliates 2015-2018' - # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -# + # The short X.Y version. -version = '3.6' +version = '4.0' # The full version, including alpha/beta/rc tags. -release = '3.6.8-2.0' +release = ".".join([version, '4-1']) + +# General information about the project. +product_name = 'Percona Server for MongoDB' +project = ' '.join([product_name, version, 'Documentation']) +copyright = u'Percona LLC and/or its affiliates 2015-2018' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -91,10 +92,16 @@ rst_prolog = ''' +.. role:: dir(file) + +.. role:: bash(code) + :language: bash + + .. _`MMAPv1`: https://docs.mongodb.org/manual/core/mmapv1/ .. _`WiredTiger`: https://docs.mongodb.org/manual/core/wiredtiger/ .. _`RocksDB`: http://rocksdb.org -.. _`In-Memory`: https://docs.mongodb.com/v3.6/core/inmemory/ +.. _`In-Memory`: https://docs.mongodb.com/v4.0/core/inmemory/ .. |check| replace:: ``|[[---CHECK---]]|`` @@ -136,7 +143,9 @@ ''' -extlinks = {'jirabug': ('https://jira.percona.com/browse/%s', '#')} +extlinks = {'psmdb-bug': ('https://jira.percona.com/browse/PSMDB-%s', 'PSMDB'), + 'jirabug': ('https://jira.percona.com/browse/%s', '#') +} # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] @@ -157,10 +166,10 @@ # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = 'Percona Server for MongoDB 3.6 Documentation' +html_title = project # A shorter title for the navigation bar. Default is the same as html_title. -html_short_title = 'Percona Server for MongoDB 3.6 Documentation' +html_short_title = project # The name of an image file (relative to this directory) to place at the top # of the sidebar. @@ -221,9 +230,9 @@ #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'PerconaServerforMongoDBdocs' - - +#htmlhelp_basename = 'PerconaServerforMongoDBdocs' +htmlhelp_basename = "".join(["".join(product_name.split()), 'docs']) + # -- Options for LaTeX output -------------------------------------------------- # The paper size ('letter' or 'a4'). @@ -234,10 +243,13 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'Percona-Server-for-MongoDB.tex', u'Percona Server for MongoDB 3.6 Documentation', - u'Percona LLC and/or its affiliates 2015-2018', 'manual'), -] + +# 'Percona-Server-for-MongoDB.tex', u'Percona Server for MongoDB 3.6 Documentation', +# u'Percona LLC and/or its affiliates 2015-2018', 'manual'), + + +latex_documents = [('index', ''.join(['-'.join(product_name.split()), '.tex']), + project, copyright, 'manual')] # The name of an image file (relative to this directory) to place at the top of # the title page. diff --git a/source/data_at_rest_encryption.rst b/source/data_at_rest_encryption.rst index 043812702..ff99ba56b 100644 --- a/source/data_at_rest_encryption.rst +++ b/source/data_at_rest_encryption.rst @@ -4,8 +4,11 @@ Data at Rest Encryption ================================================================================ +:Availability: In |PSMDB| 4.0, this feature is in the *General Availability* + state and is ready for use in a production environment. + Data at rest encryption for the WiredTiger storage engine in |mongodb| was -introduced in |mongodb-enterprise| version 3.2. to ensure that encrypted data +introduced in |mongodb-enterprise| version 3.2 to ensure that encrypted data files can be decrypted and read by parties with the decryption key. .. seealso:: @@ -15,16 +18,11 @@ files can be decrypted and read by parties with the decryption key. .. rubric:: Differences from Upstream -The |feature| in |PSMDB| is introduced in version 3.6 to be compatible with +The |feature| in |PSMDB| was introduced in version 3.6 to be compatible with |feature| in |mongodb|. In the current release of |PSMDB|, the |feature| does not include support for |abbr.kmip|, |vault| or |amazon-aws| key management services. -.. important:: - - This feature is considered **BETA** quality. Do not use the |feature| in a - production environment. - .. rubric:: Important Configuration Options |PSMDB| supports the ``encryptionCipherMode`` option where you choose one of the diff --git a/source/hot-backup.rst b/source/hot-backup.rst index d646d94a8..ccad9df67 100644 --- a/source/hot-backup.rst +++ b/source/hot-backup.rst @@ -1,17 +1,16 @@ .. _hot-backup: -========== +================================================================================ Hot Backup -========== +================================================================================ -|PSMDB| includes an integrated open-source hot backup system -for the default WiredTiger_ and alternative :ref:`mongorocks` storage engine. -It creates a physical data backup on a running server -without notable performance and operating degradation. +|PSMDB| includes an integrated open-source hot backup system for the default +WiredTiger_ storage engine. It creates a physical data backup on a running +server without notable performance and operating degradation. -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. +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. .. code-block:: text diff --git a/source/index.rst b/source/index.rst index b9995a078..c6066506a 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,8 +1,8 @@ .. _dochome: -================================================== +================================================================================ Percona Server for MongoDB |version| Documentation -================================================== +================================================================================ |PSMDB| is a free, enhanced, fully compatible, open source, drop-in replacement for MongoDB 3.6 Community Edition with enterprise-grade features. @@ -10,21 +10,20 @@ It requires no changes to MongoDB applications or code. |PSMDB| provides the following features: -* MongoDB's original MMAPv1_ storage engine, - and the default WiredTiger_ engine -* Optional :ref:`inmemory` and :ref:`mongorocks` storage engines -* :ref:`External SASL authentication ` +- MongoDB's original MMAPv1_ storage engine, and the default + WiredTiger_ engine +- Optional :ref:`inmemory` storage engine +- :ref:`External SASL authentication ` using OpenLDAP or Active Directory -* :ref:`Audit logging ` +- :ref:`Audit logging ` to track and query database interactions of users or applications -* :ref:`hot-backup` for the default WiredTiger_ - and alternative :ref:`mongorocks` storage engine -* :ref:`rate-limit` to decrease the impact of the profiler on performance +- :ref:`hot-backup` for the default WiredTiger_ +- :ref:`rate-limit` to decrease the impact of the profiler on performance ------ +-------------------------------------------------------------------------------- Introduction -============ +================================================================================ .. toctree:: :maxdepth: 1 @@ -32,7 +31,7 @@ Introduction Feature Comparison Installation -============ +================================================================================ .. toctree:: :maxdepth: 2 @@ -40,17 +39,16 @@ Installation :titlesonly: install/index - Upgrading from MongoDB Community Edition - Upgrading from Version 3.4 + install/upgrade_from_mongodb + install/upgrade_from_36 Features -======== +================================================================================ .. toctree:: :maxdepth: 1 inmemory - mongorocks hot-backup rate-limit authentication @@ -60,7 +58,7 @@ Features data_at_rest_encryption Reference -========= +================================================================================ .. toctree:: :maxdepth: 1 @@ -73,3 +71,4 @@ Reference copyright trademark-policy +.. include:: .res/replace.txt diff --git a/source/inmemory.rst b/source/inmemory.rst index 9ce52c0c6..7928f93e7 100644 --- a/source/inmemory.rst +++ b/source/inmemory.rst @@ -1,111 +1,101 @@ .. _inmemory: -===================== +================================================================================ 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. +*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. .. contents:: :local: :depth: 1 -The *Percona Memory Engine* is available in |PSMDB| -along with the standard MongoDB engines -(the original `MMAPv1`_ and the default `WiredTiger`_), -as well as `MongoRocks`_. +The *Percona Memory Engine* is available in |PSMDB| along with the standard +MongoDB engines (the original `MMAPv1`_ and the default `WiredTiger`_). + Using Percona Memory Engine -=========================== +================================================================================ -As of version 3.2, |PSMDB| 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, :file:`/etc/mongod.conf`): +As of version 3.2, |PSMDB| 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, :file:`/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: +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 Percona Memory Engine, - change to a different data directory with the ``--dbpath`` - command-line option: +* If you simply want to temporarily test Percona Memory Engine, change + to a different data directory with the ``--dbpath`` command-line + option. Make sure that the user running |mongod| has read and write + permissons for the new data directory. .. code-block:: bash $ 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:: - .. note:: Although *Percona Memory Engine* stores all data in memory, + Although *Percona Memory Engine* stores all data in memory, some diagnostics and statistics are still written to disk. This is controlled using the :option:`--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: +* 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: .. code-block:: bash $ service mongod stop $ rm -rf /var/lib/mongodb/* - $ sed -i '/engine: \*inMemory/s/#//g' /etc/mongod.conf + $ sed -i '/engine: *inMemory/s/#//g' 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: +* If there is data that you want to migrate and make compatible with Percona + Memory Engine, use the ``mongodump`` and ``mongorestore`` utilities: .. code-block:: bash $ mongodump --out $ service mongod stop $ rm -rf /var/lib/mongodb/* - $ sed -i '/engine: \*inMemory/s/#//g' /etc/mongod.conf + $ sed -i '/engine: *inMemory/s/#//g' mongod.conf $ service mongod start $ mongorestore -.. _`MMAPv1`: https://docs.mongodb.org/manual/core/mmapv1/ -.. _`WiredTiger`: https://docs.mongodb.org/manual/core/wiredtiger/ -.. _`MongoRocks`: http://rocksdb.org - Configuring Percona Memory Engine -================================= - -You can configure the Percona Memory Engine using either command-line options -or corresponding parameters in the :file:`/etc/mongod.conf` file. -The configuration file is formatted in YAML. For example: +================================================================================ -.. code-block:: text +You can configure the Percona Memory Engine using either command-line options or +corresponding parameters in the :file:`/etc/mongod.conf` file. The +configuration file is formatted in YAML. For example: - storage: - engine: inMemory - inMemory: - engineConfig: - inMemorySizeGB: 140 - statisticsLogDelaySecs: 0 +.. code-block:: yaml -Setting parameters in the previous example configuration file -is the same as starting the ``mongod`` daemon with the following options: + 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: .. code-block:: bash - mongod --storageEngine=inMemory \ + $ mongod --storageEngine=inMemory \ --inMemorySizeGB=140 \ --inMemoryStatisticsLogDelaySecs=0 -The following options are available -(with corresponding YAML configuration file parameters): +The following options are available (with corresponding YAML configuration file +parameters): .. option:: --inMemorySizeGB @@ -119,6 +109,8 @@ The following options are available :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. + Specifies the number of seconds between writes to statistics log. If 0 is + specified then statistics are not logged. +.. include:: .res/url.txt +.. include:: .res/replace.program.txt diff --git a/source/install/apt.rst b/source/install/apt.rst index f34885918..c2bd0559d 100644 --- a/source/install/apt.rst +++ b/source/install/apt.rst @@ -7,8 +7,8 @@ Installing Percona Server for MongoDB on Debian and Ubuntu Percona provides :file:`.deb` packages for 64-bit versions of the following distributions: -* Debian 8 ("jessie") -* Debian 9 ("stretch") +* Debian 8 (jessie) +* Debian 9 (stretch) * Ubuntu 14.04 LTS (Trusty Tahr) * Ubuntu 16.04 LTS (Xenial Xerus) * Ubuntu 16.10 (Yakkety Yak) @@ -23,116 +23,89 @@ of the following distributions: :local: Package Contents -================ - -:``percona-server-mongodb-36``: - Installs the ``mongo`` shell, import/export tools, other client utilities, - server software, default configuration, and init.d scripts. - -:``percona-server-mongodb-36-server``: - Contains the ``mongod`` server, default configuration files, - and init.d scripts. - -:``percona-server-mongodb-36-shell``: - Contains the ``mongo`` shell. - -:``percona-server-mongodb-36-mongos``: - Contains the ``mongos`` sharded cluster query router. - -:``percona-server-mongodb-36-tools``: - Contains Mongo tools for high-performance MongoDB fork from Percona. - -:``percona-server-mongodb-36-dbg``: - Contains debug symbols for the server. +================================================================================ + +.. list-table:: + :widths: 25 75 + + * - Package + - Contains + * - percona-server-mongodb-40 + - The ``mongo`` shell, import/export tools, other client + utilities, server software, default configuration, and init.d scripts. + * - percona-server-mongodb-40-server + - The :program:`mongod` server, default configuration files, and :dir:`init.d` + scripts + * - percona-server-mongodb-40-shell + - The ``mongo`` shell + * - percona-server-mongodb-40-mongos + - The ``mongos`` sharded cluster query router + * - percona-server-mongodb-40-tools + - Mongo tools for high-performance MongoDB fork from Percona + * - percona-server-mongodb-40-dbg + - Debug symbols for the server Installing from Percona Repositories -==================================== +================================================================================ It is recommended to install |PSMDB| from official Percona repositories: -1. Configure Percona repositories as described in - `Percona Software Repositories Documentation - `_. - -#. Install the required |PSMDB| package using :command:`apt-get`. - For example, to install the full package, run the following: +|tip.run-all.root| - .. code-block:: bash - - $ sudo apt-get install percona-server-mongodb-34 +1. Fetch the repository packages from Percona web: :bash:`wget https://repo.percona.com/apt/percona-release_0.1-8.$(lsb_release -sc)_all.deb` +#. Install the downloaded package with :program:`dpkg`: :bash:`dpkg -i + percona-release_0.1-8.$(lsb_release -sc)_all.deb` Once you install this + package the |Percona| repositories should be added. You can check the + repository setup in the :file:`/etc/apt/sources.list.d/percona-release.list` + file. +#. Enable the repository: :bash:`percona-release enable-only tools release` +#. Remember to update the local cache: |apt.update| +#. Install the |PSMDB| package: :bash:`apt install percona-server-mongodb-40` Using Percona Server for MongoDB -================================ +================================================================================ By default, |PSMDB| stores data files in :file:`/var/lib/mongodb/` and configuration parameters in :file:`/etc/mongod.conf`. -* **Starting the service** +|tip.run-all.root| +Starting the service |PSMDB| is started automatically after installation unless it encounters errors during the installation process. You can also manually start it using the following command: + |service.mongod.start| - .. code-block:: bash - - $ sudo service mongod start - -* **Confirming that service is running** - +Confirming that service is running** Check the service status using the following command: + |service.mongod.status| - .. code-block:: bash - - $ sudo service mongod status - -* **Stopping the service** +Stopping the service + Stop the service using the following command: |service.mongod.stop| - Stop the service using the following command: +Restarting the service + Restart the service using the following command: |service.mongod.restart| - .. code-block:: bash +.. note:: - $ sudo service mongod stop - -* **Restarting the service** - - Restart the service using the following command: - - .. code-block:: bash - - $ 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``. + 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 |PSMDB|, remove all the installed packages. -Removing packages with :command:`apt-get remove` -will leave the configuration and data files. -Removing the packages with :command:`apt-get purge` -will remove all the packages with configuration files and data. +To uninstall |PSMDB|, remove all the installed packages. Removing packages with +|apt.remove| will leave the configuration and data files. Removing the packages +with |apt.purge| will remove all the packages with configuration files and data. Depending on your needs you can choose which command better suits you. -1. Stop the server: - - .. code-block:: bash - - $ sudo service mongod stop - -#. Remove the packages. - - * If you want to leave configuration and data files: - - .. code-block:: bash - - $ sudo apt-get remove percona-server-mongodb* - - * If you want to delete configuration and data files - as well as the packages: - - .. code-block:: bash +|tip.run-all.root| - $ sudo apt-get purge percona-server-mongodb* +1. Stop the |mongod| server: |service.mongod.stop| +#. Remove the packages. There are two options. To keep the configuration and + data files, run |apt.remove.percona-server-mongodb|. If you want to delete + the configuration and data files as well as the packages, use |apt.purge|: + |apt.purge.percona-server-mongodb| +.. include:: ../.res/replace.txt +.. include:: ../.res/replace.program.txt diff --git a/source/install/docker.rst b/source/install/docker.rst index 1a02f94de..b2655271e 100644 --- a/source/install/docker.rst +++ b/source/install/docker.rst @@ -1,29 +1,30 @@ .. _docker: -===================================== +================================================================================ Running |PSMDB| in a Docker Container -===================================== +================================================================================ Docker images of |PSMDB| 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`_. -.. _`Docker Docs`: https://docs.docker.com/ +.. note:: -.. 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. + Make sure that you are using the latest version of Docker. The ones provided + via ``apt`` and ``yum`` may be outdated and cause errors. .. note:: By default, Docker will pull the image from Docker Hub if it is not available locally. -To run the latest |PSMDB| 3.6 in a Docker container, use the following command:: +To run the latest |PSMDB| |version| in a Docker container, use the following command: - docker run -d \ - --name psmdb \ - --restart always \ - percona/percona-server-mongodb:3.6 +|tip.run-this.root| + +.. code-block:: bash + + $ docker run -d --name psmdb --restart always \ + percona/percona-server-mongodb:4.0 The previous command does the following: @@ -42,14 +43,16 @@ The previous command does the following: will start the container on startup and restart it if the container exits. -* ``percona/percona-server-mongodb:3.6`` is the name and version tag +* ``percona/percona-server-mongodb:4.0`` is the name and version tag of the image to derive the container from. - For full list of tags, - see https://hub.docker.com/r/percona/percona-server-mongodb/tags/ +.. seealso:: + + |docker| Documentation: the full list of tags + https://hub.docker.com/r/percona/percona-server-mongodb/tags/ Connecting from Another Docker Container -======================================== +================================================================================ The |PSMDB| container exposes standard MongoDB port (27017), which can be used for connection from an application @@ -58,11 +61,11 @@ 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 |PSMDB| container, -run the following comand:: - - docker run -it --link psmdb --rm percona/percona-server-mongodb:mongo mongo -h psmdb +run the following comand: :bash:`docker run -it --link psmdb --rm percona/percona-server-mongodb:mongo mongo -h psmdb` +.. include:: ../.res/replace.txt +.. include:: ../.res/url.txt diff --git a/source/install/index.rst b/source/install/index.rst index f9307f406..e3eed6df2 100644 --- a/source/install/index.rst +++ b/source/install/index.rst @@ -15,8 +15,7 @@ Percona provides packages for the following systems: - Instructions * - * Debian 8 ("jessie") * Debian 9 ("stretch") - * Ubuntu 14.04 LTS (Trusty Tahr) - * Ubuntu 16.04 LTS (Xenial Xerus) + * Ubuntu 16.04 (Xenial Xerus) * Ubuntu 17.04 (Zesty Zapus) * Ubuntu 17.10 (Artful Aardvark) * Ubuntu 18.04 LTS (Bionic Beaver) @@ -30,31 +29,32 @@ Percona provides packages for the following systems: 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 :command:`dpkg` or :command:`rpm`. +You can also download packages from the `Percona website`_ and install them +manually using :command:`dpkg` or :command:`rpm`. -.. note:: In this case, you will have to manually make sure - that all dependencies are satisfied. +.. note:: -If you want more control over the installation, you can -:ref:`install Percona Server for MongoDB from binary tarballs `. + In this case, you will have to make sure that all dependencies are satisfied. -.. note:: This method is for advanced users with specific needs - that are not addressed by DEB and RPM packages. +If you want more control over the installation, you can :ref:`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 |PSMDB| in a Docker container, see :ref:`docker`. Upgrade Instructions -==================== +================================================================================ -If you are currently using MongoDB, -see :ref:`Upgrading from MongoDB `. +If you are currently using MongoDB, see :ref:`Upgrading from MongoDB +`. -If you are running an earlier version of |PSMDB|, -see :ref:`Upgrading from Version 3.4 `. +If you are running an earlier version of |PSMDB|, see :ref:`Upgrading from Version 3.6 `. .. toctree:: :hidden: @@ -64,3 +64,4 @@ see :ref:`Upgrading from Version 3.4 `. Install from Binary Tarball Run in a Docker Container +.. include:: ../.res/url.txt diff --git a/source/install/tarball.rst b/source/install/tarball.rst index 9930daee8..b0969a571 100644 --- a/source/install/tarball.rst +++ b/source/install/tarball.rst @@ -1,39 +1,32 @@ .. _tarball: -========================================================= +================================================================================ Installing Percona Server for MongoDB from Binary Tarball -========================================================= +================================================================================ -You can find links to the binary tarballs from the -`Percona Server for MongoDB download page `_. +You can find links to the binary tarballs from the `Percona website`_ -1. Fetch and extract the correct binary tarball. - For example, if you are running Debian 8 ("jessie"): +1. Fetch and extract the correct binary tarball. For example, if you + are running Debian 8 ("jessie"): .. code-block:: bash - wget https://www.percona.com/downloads/percona-server-mongodb-3.6/percona-server-mongodb-3.6.5-1.3/binary/debian/jessie/x86_64/percona-server-mongodb-3.6.5-1.3-ra1cb178-jessie-x86_64-bundle.tar - tar xfz percona-server-mongodb-3.6.5-1.3-ra1cb178-jessie-x86_64-bundle.tar + $ wget https://www.percona.com/downloads/percona-server-mongodb-4.0/\ + percona-server-mongodb-4.0.4-1/binary/debian/jessie/x86_64/\ + percona-server-mongodb-4.0.4-1-ra1cb178-jessie-x86_64-bundle.tar + $ tar xfz percona-server-mongodb-4.0.4-1-ra1cb178-jessie-x86_64-bundle.tar -2. Copy the extracted binaries to the target directory, for example: +#. Copy the extracted binaries to the target directory, for example: .. code-block:: bash mkdir ~/psmdb cp -r -n percona-server-mongodb-3.6.5-1.3-ra1cb178-jessie-x86_64-bundle/bin ~/psmdb/ -3. Add the location of the binaries to the ``PATH`` variable: - - .. code-block:: bash - - export PATH ~/psmdb/bin:$PATH - -4. Create the default data directory: - - .. code-block:: bash - - mkdir -p /data/db - -5. Make sure that you have read and write permissions for the data directory - and run ``mongod``. +#. Add the location of the binaries to the ``PATH`` variable: :bash:`export PATH ~/psmdb/bin:$PATH` +#. Create the default data directory: :bash:`mkdir -p /data/db` +#. Make sure that you have read and write permissions for the data + directory and run |mongod|. +.. include:: ../.res/url.txt +.. include:: ../.res/replace.program.txt diff --git a/source/install/upgrade_from_34.rst b/source/install/upgrade_from_34.rst deleted file mode 100644 index 292d0af51..000000000 --- a/source/install/upgrade_from_34.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. _upgrade_from_34: - -================================= -Upgrading from |PSMDB| 3.4 to 3.6 -================================= - -.. important:: **MongoRocks is deprecated in Percona Server for MongoDB 3.6.** - If you are using |PSMDB| 3.4 with MongoRocks, and you wish to upgrade to - version 3.6, please read the note at the top of the MongoRocks page before - upgrading: - https://www.percona.com/doc/percona-server-for-mongodb/3.6/mongorocks.html - -To upgrade |PSMDB| to version 3.6, you must be running version 3.4. -Upgrades from earlier versions are not supported. - -Before upgrading your production |PSMDB| deployments, -test all your applications in a testing environment -to make sure they are compatible with the new version. - -The general procedure for performing an in-place upgrade -(where your existing data and configuration files are preserved) -includes the following steps: - -1. Stop the ``mongod`` instance. - -#. Remove old packages. - -#. Install new packages. - -#. Start the ``mongod`` instance. - -It is recommended to upgrade |PSMDB| from official Percona repositories -using the corresponding package manager for your system. -For more information, see :ref:`install`. - -.. warning:: Perform a full backup of your data and configuration files - before upgrading. - -Upgrading on Debian or Ubuntu -============================= - -1. Stop the ``mongod`` instance:: - - sudo service mongod stop - -#. Remove |PSMDB| 3.4 packages:: - - sudo apt-get remove percona-server-mongodb-34* - -#. Install |PSMDB| 3.6 packages:: - - sudo apt-get install percona-server-mongodb-36 - -#. Start the ``mongod`` instance:: - - sudo service mongod start - -For more information, see :ref:`apt`. - -Upgrading on RHEL and CentOS -============================ - -1. Stop the ``mongod`` instance:: - - sudo service mongod stop - -#. Remove |PSMDB| 3.4 packages:: - - sudo yum remove Percona-Server-MongoDB-34* - -#. Install |PSMDB| 3.6 packages:: - - sudo yum install Percona-Server-MongoDB-36 - -#. Start the ``mongod`` instance:: - - sudo service mongod start - -For more information, see :ref:`yum`. - diff --git a/source/install/upgrade_from_36.rst b/source/install/upgrade_from_36.rst new file mode 100644 index 000000000..a5d278662 --- /dev/null +++ b/source/install/upgrade_from_36.rst @@ -0,0 +1,54 @@ +.. _upgrade_from_36: + +================================================================================ +Upgrading from |PSMDB| |prev-version| to |version| +================================================================================ + +:Availability: MongoRocks has been removed from |PSMDB| |version| + +To upgrade |PSMDB| to version |version|, you must be running version +|prev-version| Upgrades from earlier versions are not supported. + +Before upgrading your production |PSMDB| deployments, test all your applications +in a testing environment to make sure they are compatible with the new version. + +The general procedure for performing an in-place upgrade (where your existing +data and configuration files are preserved) includes the following steps: + +1. Stop the :program:`mongod` instance +#. Remove old packages +#. Install new packages +#. Start the :program`mongod` instance + +It is recommended to upgrade |PSMDB| from official Percona repositories using +the corresponding package manager for your system. For more information, see +:ref:`install`. + +.. warning:: + + Perform a full backup of your data and configuration files before upgrading. + +Upgrading on Debian or Ubuntu +================================================================================ + +|tip.run-all.root| + +1. Stop the ``mongod`` instance: :bash:`service mongod stop` +#. Remove |PSMDB| |prev-version| packages: :bash:`apt-get remove percona-server-mongodb-36*` +#. Install |PSMDB| |version| packages: :bash:`sudo apt-get install percona-server-mongodb-40` +#. Start the ``mongod`` instance: :bash:`service mongod start` + +For more information, see :ref:`apt`. + +Upgrading on RHEL and CentOS +================================================================================ + +|tip.run-all.root| + +1. Stop the ``mongod`` instance: :bash:`sudo service mongod stop` +#. Install |PSMDB| |version| packages: :bash:`yum install Percona-Server-MongoDB-40` +#. Start the ``mongod`` instance:: :bash:`service mongod start` + +For more information, see :ref:`yum`. + +.. include:: ../.res/replace.txt diff --git a/source/install/upgrade_from_mongodb.rst b/source/install/upgrade_from_mongodb.rst index 368f506dd..22fcdc4ce 100644 --- a/source/install/upgrade_from_mongodb.rst +++ b/source/install/upgrade_from_mongodb.rst @@ -1,26 +1,28 @@ .. _upgrade_from_mongodb: -====================================================================== -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 |PSMDB|: 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 |PSMDB|. - 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. - -.. warning:: Before starting the upgrade process - it is recommended to perform a full backup of your data. +================================================================================ +Upgrading from |mongodb-ce| +================================================================================ + +.. note:: + + MongoDB creates a user that belongs to two groups, which is a potential + security risk. This is fixed in |PSMDB|: 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 |PSMDB|. 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. + +.. 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: @@ -28,72 +30,71 @@ The upgrade process depends on the distribution you are using: :local: Upgrading on Debian or Ubuntu -============================= +================================================================================ -1. Stop the mongod process: +|tip.run-all.root| - .. code-block:: bash +1. Stop the mongod process: |service.mongod.stop| - $ service mongod stop +2. Check for installed packages: :bash:`dpkg -l | grep mongod` -2. Check for installed packages: + .. admonition:: Output - .. code-block:: bash + .. code-block:: guess - $ dpkg -l | grep mongod + ii mongodb-org 4.0.4 amd64 MongoDB open source document-oriented database system (metapackage) + ii mongodb-org-mongos 4.0.4 amd64 MongoDB sharded cluster query router + ii mongodb-org-server 4.0.4 amd64 MongoDB database server + ii mongodb-org-shell 4.0.4 amd64 MongoDB shell client + ii mongodb-org-tools 4.0.4 amd64 MongoDB tools - ii mongodb-org 3.6.2 amd64 MongoDB open source document-oriented database system (metapackage) - ii mongodb-org-mongos 3.6.2 amd64 MongoDB sharded cluster query router - ii mongodb-org-server 3.6.2 amd64 MongoDB database server - ii mongodb-org-shell 3.6.2 amd64 MongoDB shell client - ii mongodb-org-tools 3.6.2 amd64 MongoDB tools - -3. Remove installed packages: +3. Remove the installed packages: .. code-block:: bash - apt-get remove mongodb-org mongodb-org-mongos mongodb-org-server \ - mongodb-org-shell mongodb-org-tools + $ apt-get remove mongodb-org mongodb-org-mongos mongodb-org-server \ + $ mongodb-org-shell mongodb-org-tools -4. Install Percona Server for MongoDB :ref:`using apt `. +4. Install |PSMDB| :ref:`using apt `. Upgrading on Red Hat Enterprise Linux or CentOS -=============================================== - -1. Stop the mongod process: - - .. code-block:: bash +================================================================================ - $ service mongod stop +|tip.run-all.root| -2. Check for installed packages: +1. Stop the mongod process: |service.mongod.stop| +#. Check for installed packages: :bash:`rpm -qa | grep mongo` - .. code-block:: bash + .. admonition:: Output - $ rpm -qa | grep mongo + .. code-block:: guess - mongodb-org-mongos-3.6.2-1.el6.x86_64 - mongodb-org-shell-3.6.2-1.el6.x86_64 - mongodb-org-server-3.6.2-1.el6.x86_64 - mongodb-org-tools-3.6.2-1.el6.x86_64 - mongodb-org-3.6.2-1.el6.x86_64 + mongodb-org-mongos-4.0.4-1.el6.x86_64 + mongodb-org-shell-4.0.4-1.el6.x86_64 + mongodb-org-server-4.0.4-1.el6.x86_64 + mongodb-org-tools-4.0.4-1.el6.x86_64 + mongodb-org-4.0.4-1.el6.x86_64 -3. Remove installed packages: +3. Remove the installed packages: .. code-block:: bash - yum remove \ - mongodb-org-mongos-3.6.2-1.el6.x86_64 mongodb-org-shell-3.6.2-1.el6.x86_64 \ - mongodb-org-server-3.6.2-1.el6.x86_64 mongodb-org-tools-3.6.2-1.el6.x86_64 \ - mongodb-org-3.6.2-1.el6.x86_64 + $ yum remove \ + mongodb-org-mongos-4.0.4-1.el6.x86_64 \ + mongodb-org-shell-4.0.4-1.el6.x86_64 \ + mongodb-org-server-4.0.4-1.el6.x86_64 \ + mongodb-org-tools-4.0.4-1.el6.x86_64 \ + mongodb-org-4.0.4-1.el6.x86_64 4. Install Percona Server for MongoDB :ref:`using yum `. -.. note:: When you remove old packages, - your existing configuration file is saved - as :file:`/etc/mongod.conf.rpmsave`. - If you want to use this configuration with the new version, - replace the default :file:`/etc/mongod.conf` file. - For example, existing data may not be compatible - with the default WiredTiger storage engine. +.. note:: + + When you remove old packages, your existing configuration file is saved as + :file:`/etc/mongod.conf.rpmsave`. If you want to use this configuration with + the new version, replace the default :file:`/etc/mongod.conf` file. For + example, existing data may not be compatible with the default WiredTiger + storage engine. +.. include:: ../.res/replace.txt +.. include:: ../.res/replace.program.txt diff --git a/source/install/yum.rst b/source/install/yum.rst index 6295d1720..44ed18aeb 100644 --- a/source/install/yum.rst +++ b/source/install/yum.rst @@ -18,50 +18,55 @@ of the following distributions: :local: Package Contents -================ +================================================================================ + +.. list-table:: + :widths: 25 75 + + * - Package + - Contains + * - percona-server-mongodb-40 + - The ``mongo`` shell, import/export tools, other client + utilities, server software, default configuration, and init.d scripts. + * - percona-server-mongodb-40-server + - The :program:`mongod` server, default configuration files, and :dir:`init.d` + scripts + * - percona-server-mongodb-40-shell + - The ``mongo`` shell + * - percona-server-mongodb-40-mongos + - The ``mongos`` sharded cluster query router + * - percona-server-mongodb-40-tools + - Mongo tools for high-performance MongoDB fork from Percona + * - percona-server-mongodb-40-dbg + - Debug symbols for the server -:``Percona-Server-MongoDB-36``: - Installs the ``mongo`` shell, import/export tools, other client utilities, - server software, default configuration, and init.d scripts. - -:``Percona-Server-MongoDB-36-server``: - Contains the ``mongod`` server, default configuration files, - and init.d scripts. - -:``Percona-Server-MongoDB-36-shell``: - Contains the ``mongo`` shell. - -:``Percona-Server-MongoDB-36-mongos``: - Contains the ``mongos`` sharded cluster query router. +Installing from Percona Repositories +================================================================================ -:``Percona-Server-MongoDB-36-tools``: - Contains Mongo tools for high-performance MongoDB fork from Percona. +It is recommended to intall |PSMDB| from official Percona repositories: -:``Percona-Server-MongoDB-36-debuginfo``: - Contains debug symbols for the server. +|tip.run-all.root| -Installing from Percona Repositories -==================================== +1. Install the Percona repository: :bash:`yum install https://repo.percona.com/centos/7/RPMS/noarch/percona-release-0.1-8.noarch.rpm` -It is recommended to intall |PSMDB| from official Percona repositories: + .. admonition:: Example of Output -1. Configure Percona repositories as described in - `Percona Software Repositories Documentation - `_. + .. code-block:: bash -#. Install the required |PSMDB| package using :command:`yum`. - For example, to install the full package, run the following: + Retrieving http://www.percona.com/downloads/percona-release/redhat/0.1-6/percona-release-0.1-8.noarch.rpm + Preparing... ########################################### [100%] + 1:percona-release ########################################### [100%] - .. code-block:: bash +#. Enable the repository: :bash:`percona-release enable-only tools release` +#. Install the packages: :bash:`yum install percona-server-mongodb-40` - $ sudo yum install Percona-Server-MongoDB-34 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: +.. warning:: If you have SELinux security module installed, it will + conflict with Percona Server for MongoDB. There are several + options to deal with this: * Remove the SELinux packages. This is not recommended, because it may violate security. @@ -78,48 +83,29 @@ Using Percona Server for MongoDB using the ``setenforce 0`` command. However, this will not affect the configuration after a reboot. -|PSMDB| stores data files in :file:`/var/lib/mongodb/` by default. +|PSMDB| stores data files in :dir:`/var/lib/mongodb/` by default. The configuration file is :file:`/etc/mongod.conf`. -* **Starting the service** - +Starting the service |PSMDB| is not started automatically after installation. - Start it manually using the following command: - - .. code-block:: bash - - $ sudo service mongod start - -* **Confirming that service is running** - - Check the service status using the following command: - - .. code-block:: bash - - $ sudo service mongod status - -* **Stopping the service** + Start it manually using the following command: |service.mongod.start| - Stop the service using the following command: +Confirming that service is running + Check the service status using the following command: |service.mongod.status| - .. code-block:: bash +Stopping the service + Stop the service using the following command: |service.mongod.stop| - $ sudo service mongod stop +Restarting the service + Restart the service using the following command: |service.mongod.restart| -* **Restarting the service** +.. note:: - Restart the service using the following command: - - .. code-block:: bash - - $ 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``. + On Red Hat Enterprise Linux and CentOS 7 you can also invoke all + the above commands with ``sytemctl`` instead of ``service``. Running after reboot --------------------- +-------------------------------------------------------------------------------- The ``mongod`` service is not automatically started after you reboot the system. @@ -131,30 +117,18 @@ to enable auto-start as follows: $ chkconfig --add mongod -For RHEL or CentOS version 7, you can use the ``systemctl`` utility as follows: - -.. code-block:: bash - - $ systemctl enable mongod +For RHEL or CentOS version 7, you can use the ``systemctl`` utility: |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: - - .. code-block:: bash - - $ sudo service mongod stop - -#. Remove the packages: - - .. code-block:: bash - - $ sudo yum remove Percona-Server-MongoDB* +|tip.run-all.root| +1. Stop the Percona Server for MongoDB service: |service.mongod.stop| +#. Remove the packages: |yum.remove.percona-server-mongodb| #. Remove the data and configuration files: .. code-block:: bash @@ -162,9 +136,10 @@ you'll need to remove all the installed packages and data 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 +.. 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. .. rubric:: Footnotes @@ -186,3 +161,6 @@ you'll need to remove all the installed packages and data files: `_ if you require further information on this. + +.. include:: ../.res/replace.txt +.. include:: ../.res/replace.program.txt diff --git a/source/mongorocks.rst b/source/mongorocks.rst deleted file mode 100644 index 62cb0f41c..000000000 --- a/source/mongorocks.rst +++ /dev/null @@ -1,218 +0,0 @@ -.. _mongorocks: - -========== -MongoRocks -========== - -.. important:: **MongoRocks is deprecated in Percona Server for MongoDB 3.6.** - -MongoRocks is deprecated in |PSMDB| 3.6 and it will be fully removed in the -next major version of |PSMDB|. Feature compatibility version is set to 3.4 when -using |PSMDB| 3.6 with MongoRocks, so 3.6 features, such as retryable writes -and causal consistency, cannot be used. Additionally, read concern majority may -produce unreliable results. - -If you are using MongoRocks with |PSMDB| 3.4 or older, we strongly encourage -you to migrate from MongoRocks to WiredTiger before upgrading to |PSMDB| 3.6. -Instructions on how to change storage engines are located in this Percona blog -post: https://www.percona.com/blog/2017/03/07/how-to-change-mongodb-storage-engines-without-downtime/. - -If you install |PSMDB| 3.6 with the RocksDB storage engine, you will receive -the following error message when trying to start mongod: - -.. code-block:: text - - [ERROR] There are known issues with MongoDB 3.6 and MongoRocks. To learn about these issues and how to enable MongoRocks with Percona Server for MongoDB 3.6, please read https://www.percona.com/doc/percona-server-for-mongodb/3.6/mongorocks.html, terminating - -.. note:: changing feature compatibility version to 3.6 when using MongoRocks - will produce the following error: ``storage engine does not support - upgrading featureCompatibilityVersion to 3.6`` - -To continue using |PSMDB| 3.6 with MongoRocks, use one of the following two -methods: - - - Add ``--useDeprecatedMongoRocks`` to ``mongod`` startup options - Update the config file with the following parameter: - -.. code-block:: text - - storage: - engine: rocksdb - useDeprecatedMongoRocks: true - - -*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. - -.. contents:: - :local: - :depth: 1 - -The *MongoRocks* storage engine is available in |PSMDB| -along with the standard MongoDB engines -(the original `MMAPv1`_ and the default `WiredTiger`_), -as well as :ref:`inmemory`. - -Using MongoRocks -================ - -As of version 3.2, |PSMDB| runs with `WiredTiger`_ by default. -If you still would like to use the deprecated *MongoRocks* storage -engine, please use the ``--storageEngine rocksdb`` command-line option -accompanied by ``--useDeprecatedMongoRocks`` when you start -``mongod``. Alternatively, you can set the ``storage.engine`` and -``useDeprecatedMongoRocks`` variables in the configuration file (by -default, :file:`/etc/mongod.conf`) as shown below. - -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: - - .. code-block:: bash - - $ service mongod stop - $ mongod --storageEngine rocksdb --useDeprecatedMongoRocks --dbpath - - .. note:: Make sure that the user running ``mongod`` - has read and write permissions 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: - - .. code-block:: bash - - $ 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: - - .. code-block:: bash - - $ mongodump --out - $ service mongod stop - $ rm -rf /var/lib/mongodb/* - $ sed -i '/engine: \*rocksdb/s/#//g' /etc/mongod.conf - $ service mongod start - $ mongorestore - -.. _`MMAPv1`: https://docs.mongodb.org/manual/core/mmapv1/ -.. _`WiredTiger`: https://docs.mongodb.org/manual/core/wiredtiger/ - -Configuring MongoRocks -====================== - -You can configure *MongoRocks* using either command-line options -or corresponding parameters in the :file:`/etc/mongod.conf` file. -The configuration file is formatted in YAML. -For example, the following sample configuration is suggested -as the default for running |PSMDB| with *MongoRocks*: - -.. code-block:: text - - storage: - engine: rocksdb - useDeprecatedMongoRocks: true - 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: - -.. code-block:: bash - - mongod --storageEngine=rocksdb \ - --useDeprecatedMongoRocks \ - --rocksdbCacheSizeGB=1 \ - --rocksdbCompression=snappy \ - --rocksdbMaxWriteMBPerSec=1024 \ - --rocksdbCrashSafeCounters=false \ - --rocksdbCounters=true \ - --rocksdbSingleDeleteIndex=false - -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 uncompressed 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 - - :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 performance. - -.. 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. - diff --git a/source/release_notes/3.6.1-1.0beta.rst b/source/release_notes/3.6.1-1.0beta.rst deleted file mode 100644 index ea98e9d93..000000000 --- a/source/release_notes/3.6.1-1.0beta.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _3.6.1-1.0beta: - -====================== -|PSMDB| 3.6.1-1.0 Beta -====================== - -:Date: January 23, 2018 -:Download: http://www.percona.com/downloads/percona-server-mongodb-3.6/ -:Installation: :ref:`install` - -.. note:: - - This version is considered *BETA* quality and it's not intended to - be used in production. - -This release is based on `MongoDB 3.6.1 -`_ -and provides the following features: - -* MongoDB's original MMAPv1_ storage engine, - and the default WiredTiger_ engine -* Optional :ref:`inmemory` and :ref:`mongorocks` storage engines -* :ref:`External SASL authentication ` - using OpenLDAP or Active Directory -* :ref:`Audit logging ` - to track and query database interactions of users or applications -* :ref:`hot-backup` for the default WiredTiger_ - and alternative :ref:`mongorocks` storage engine -* :ref:`rate-limit` to decrease the impact of the profiler on performance - -Known Issues ------------- - -* :jirabug:`PSMDB-184` - MongoRocks reindexing collection or repairing database - commands can cause inconsistency when doing immediate majority read in - replica set. - -* :jirabug:`PSMDB-185` - MongoDB has its own notion of time, including an - expected commit order for transactions that may be inconsistent with the - order assigned by MongoRocks. - This can cause majority read inconsistencies in highly concurrent - environments in replica set mode. diff --git a/source/release_notes/3.6.3-1.1.rst b/source/release_notes/3.6.3-1.1.rst deleted file mode 100644 index 770f9754c..000000000 --- a/source/release_notes/3.6.3-1.1.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _3.6.3-1.1: - -================= -|PSMDB| 3.6.3-1.1 -================= - -:Date: April 24, 2018 -:Download: http://www.percona.com/downloads/percona-server-mongodb-3.6/ -:Installation: :ref:`install` - -|PSMDB| is an enhanced, open source, and highly-scalable database that is -a fully-compatible, drop-in replacement for MongoDB 3.6 Community Edition. -It supports MongoDB 3.6 protocols and drivers. - -|PSMDB| extends Community Edition functionality by including the -:ref:`inmemory` storage engine, as well as several enterprise-grade features. -|PSMDB| requires no changes to MongoDB applications or code. - -This release is based on `MongoDB 3.6.3 -`_ -and provides the following additional changes: - -* MongoRocks is deprecated in Percona Server for MongoDB 3.6 and it will be - fully removed in the next major version of |PSMDB|. Feature compatibility - version is set to 3.4 when using |PSMDB| 3.6 with MongoRocks, so 3.6 - features, such as retryable writes and causal consistency, cannot be used. - Additionally, read concern majority may produce unreliable results. - -* :jirabug:`PSMDB-191`: Fixed a bug in :ref:`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 :ref:`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 :ref:`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. - -* :jirabug:`PSMDB-178`: RocksSnapshotManager was reworked to match the new model - of interaction between MongoDB and storage engine's snapshot manager. - - diff --git a/source/release_notes/3.6.4-1.2.rst b/source/release_notes/3.6.4-1.2.rst deleted file mode 100644 index e3903b607..000000000 --- a/source/release_notes/3.6.4-1.2.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _3.6.4-1.2: - -================= -|PSMDB| 3.6.4-1.2 -================= - -:Date: May 23, 2018 -:Download: http://www.percona.com/downloads/percona-server-mongodb-3.6/ -:Installation: :ref:`install` - -|PSMDB| is an enhanced, open source, and highly-scalable database that is -a fully-compatible, drop-in replacement for MongoDB 3.6 Community Edition. -It supports MongoDB 3.6 protocols and drivers. - -|PSMDB| extends Community Edition functionality by including the -:ref:`inmemory` storage engine, as well as several enterprise-grade features. -Also it includes :ref:`mongorocks` storage engine, which is now deprecated. -|PSMDB| requires no changes to MongoDB applications or code. - -This release is based on `MongoDB 3.6.4 -`_ -and provides the following additional changes: - -* :jirabug:`PSMDB-205`: ``mongod`` failed to initialize if audit filter was - set to record Action type events specified with the ``$in`` expression. - -* :jirabug:`PSMDB-207`: a premature initialization of the feature compatibility - version in global parameters was fixed for the RocksDB storage engine. - -* :jirabug:`PSMDB-209`: CentOS 6 and CentOS 7 RPM packages contained config - file with a wrong link to the online Percona Memory Engine documentation. - -.. note:: As mentioned in the |PSMDB| 3.6.3-1.1 Release Notes, MongoRocks is - deprecated in |PSMDB| 3.6. diff --git a/source/release_notes/3.6.5-1.3.rst b/source/release_notes/3.6.5-1.3.rst deleted file mode 100644 index e833f25d8..000000000 --- a/source/release_notes/3.6.5-1.3.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _3.6.5-1.3: - -================= -|PSMDB| 3.6.5-1.3 -================= - -:Date: July 11, 2018 -:Download: http://www.percona.com/downloads/percona-server-mongodb-3.6/ -:Installation: :ref:`install` - -|PSMDB| is an enhanced, open source, and highly-scalable database that is -a fully-compatible, drop-in replacement for MongoDB 3.6 Community Edition. -It supports MongoDB 3.6 protocols and drivers. - -|PSMDB| extends Community Edition functionality by including the -:ref:`inmemory` storage engine, as well as several enterprise-grade features. -Also it includes :ref:`mongorocks` storage engine, which is now deprecated. -|PSMDB| requires no changes to MongoDB applications or code. - -This release is based on `MongoDB 3.6.5 -`_ -and does not include any additional changes. diff --git a/source/release_notes/3.6.6-1.4.rst b/source/release_notes/3.6.6-1.4.rst deleted file mode 100644 index 94725d966..000000000 --- a/source/release_notes/3.6.6-1.4.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _3.6.6-1.4: - -================= -|PSMDB| 3.6.6-1.4 -================= - -:Date: August 3, 2018 -:Download: http://www.percona.com/downloads/percona-server-mongodb-3.6/ -:Installation: :ref:`install` - -|PSMDB| is an enhanced, open source, and highly-scalable database that is -a fully-compatible, drop-in replacement for MongoDB 3.6 Community Edition. -It supports MongoDB 3.6 protocols and drivers. - -|PSMDB| extends Community Edition functionality by including the -:ref:`inmemory` storage engine, as well as several enterprise-grade features. -Also it includes :ref:`mongorocks` storage engine, which is now deprecated. -|PSMDB| requires no changes to MongoDB applications or code. - -This release is based on `MongoDB 3.6.6 -`_ -and does not include any additional changes. diff --git a/source/release_notes/3.6.7-1.5.rst b/source/release_notes/3.6.7-1.5.rst deleted file mode 100644 index f86c25862..000000000 --- a/source/release_notes/3.6.7-1.5.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _3.6.7-1.5: - -================= -|PSMDB| 3.6.7-1.5 -================= - -:Date: September 17, 2018 -:Download: http://www.percona.com/downloads/percona-server-mongodb-3.6/ -:Installation: :ref:`install` - -|PSMDB| is an enhanced, open source, and highly-scalable database that is -a fully-compatible, drop-in replacement for MongoDB 3.6 Community Edition. -It supports MongoDB 3.6 protocols and drivers. - -|PSMDB| extends Community Edition functionality by including the -:ref:`inmemory` storage engine, as well as several enterprise-grade features. -Also it includes :ref:`mongorocks` storage engine, which is now deprecated. -|PSMDB| requires no changes to MongoDB applications or code. - -This release is based on `MongoDB 3.6.7 -`_ -and does not include any additional changes. diff --git a/source/release_notes/3.6.8-2.0.rst b/source/release_notes/3.6.8-2.0.rst deleted file mode 100644 index 893a7d9da..000000000 --- a/source/release_notes/3.6.8-2.0.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _3.6.8-2.0: - -================================================================================ -|PSMDB| |version| -================================================================================ - -:Date: October 31, 2018 -:Download: http://www.percona.com/downloads/percona-server-mongodb-3.6/ -:Installation: :ref:`install` - -Percona announces the release of Percona Server for MongoDB |version| -on October 31, 2018. Download the latest version from the `Percona -website `_ or the `Percona Software Repositories -`_. - -|PSMDB| is an enhanced, open source, and highly-scalable database that is a -fully-compatible, drop-in replacement for MongoDB 3.6 Community Edition. It -supports MongoDB 3.6 protocols and drivers. - -|PSMDB| extends Community Edition functionality by including the :ref:`inmemory` -storage engine, as well as several enterprise-grade features. Also, it includes -:ref:`mongorocks` storage engine, which is now deprecated. |PSMDB| requires no -changes to MongoDB applications or code. - -This release introduces data at rest encryption for the WiredTiger storage engine. Data at -rest encryption for WiredTiger in |PSMDB| is compatible with the upstream -implementation. In this release of |PSMDB|, this feature is of **BETA** quality -and should not be used in a production environment. - -Note that |PSMDB| 3.6.8-2.0 is based on `MongoDB 3.6.8 -`_ -which is distributed under the GNU AGPLv3 license. Subsequent releases -of |PSMDB| will change its license to `SSPL (Server Side Public -License) `_ when we move -to the SSPL codebase released by |mongodb|. For more information, see -`Percona Statement on MongoDB Community Server License Change -`_. - -This release also contains a fix for bug :jirabug:`PSMDB-238` - -Known Issues -================================================================================ - -- :jirabug:`PSMDB-233`: When starting |PSMDB| 3.6 with WiredTiger encryption - options but using a different storage engine, the server starts normally and - produces no warnings that these options are ignored. -- :jirabug:`PSMDB-239`: WiredTiger encryption is not disabled with using the - :ref:`inmemory` storage engine. -- :jirabug:`PSMDB-245`: KeyDB's WiredTiger logs are not properly rotated without - restarting the server. - -.. |version| replace:: 3.6.8-2.0 -.. |mongodb| replace:: MongoDB diff --git a/source/release_notes/4.0.4-1.rst b/source/release_notes/4.0.4-1.rst new file mode 100644 index 000000000..88c4c5ccd --- /dev/null +++ b/source/release_notes/4.0.4-1.rst @@ -0,0 +1,68 @@ +.. _4.0.4-1: + +================================================================================ +|PSMDB| |release| +================================================================================ + +:Date: |date| +:Download: `Percona website`_ +:Installation: :ref:`install` + +Percona announces the GA release of |PSMDB| |release| on |date|. Download the +latest version from the `Percona website`_ or the `Percona software repositories`_. + +|PSMDB| is an enhanced, open source, and highly-scalable database that is a +fully-compatible, drop-in replacement for |mongodb-ce|. It supports |mongodb| +4.0 protocols and drivers. + +|PSMDB| extends the functionality of the |mongodb-ce| by including the +:ref:`inmemory` storage engine, as well as several enterprise-grade +features. |PSMDB| requires no changes to |mongodb| applications or code. + +This release `includes all features +`_ of |mongodb-ce| +4.0. Most notable among these are: + +- `Multi-Document ACID transactions + `_ +- `Type conversion through the new aggregation operators + `_ +- `Enhancements to the Change Streams support + `_ + +Note that the `MMAPv1 storage engine is deprecated +`_ +in |mongodb-ce| 4.0. + +In |PSMDB| |release|, *data at rest encryption* is General Availability +feature. It is ready for use in a production environment. + +Bugs Fixed +================================================================================ + +- :psmdb-bug:`235`: In some cases, hot backup did not back up the + :dir:`keydb` directory; |mongod| could crash after restore. +- :psmdb-bug:`233`: When starting |PSMDB| with WiredTiger + encryption options but using a different storage engine, the server started + normally and produced no warnings that these options had been ignored +- :psmdb-bug:`239`: The WiredTiger encryption was not disabled when using the + `Percona Memory Engine + `_ + storage engine. +- :psmdb-bug:`241`: WiredTiger per database encryption keys were not + purged when the database was deleted +- :psmdb-bug:`243`: A log message was added to indicate that the + server is running with encryption +- :psmdb-bug:`245`: KeyDB’s WiredTiger logs were not properly rotated + without restarting the server. +- :psmdb-bug:`246`: The server would not start after restoring an + encrypted database from hotbackup where a wrong master key was + specified + +.. |release| replace:: 4.0.4-1 +.. |date| replace:: December 18, 2018 +.. |mongodb-ce| replace:: MongoDB 4.0 Community Edition +.. |mongodb| replace:: MongoDB + +.. include:: ../.res/url.txt +.. include:: ../.res/replace.program.txt diff --git a/source/release_notes/index.rst b/source/release_notes/index.rst index f43b9f029..b8ad4b117 100644 --- a/source/release_notes/index.rst +++ b/source/release_notes/index.rst @@ -7,10 +7,4 @@ Percona Server for MongoDB |version| Release Notes .. toctree:: :maxdepth: 1 - 3.6.8-2.0 - 3.6.7-1.5 - 3.6.6-1.4 - 3.6.5-1.3 - 3.6.4-1.2 - 3.6.3-1.1 - 3.6.1-1.0beta + 4.0.4-1 diff --git a/source/switch_storage_engines.rst b/source/switch_storage_engines.rst index f771220e6..0c4890a0a 100644 --- a/source/switch_storage_engines.rst +++ b/source/switch_storage_engines.rst @@ -1,95 +1,93 @@ .. _switch_storage_engines: +================================================================================ Switching Storage Engines -========================= +================================================================================ -By default, |PSMDB| runs with WiredTiger_. -There is also the original MMAPv1_ storage engine, -as well as optional :ref:`inmemory` and :ref:`mongorocks` storage engines -to choose from. -Each one is designed for specific purposes and workloads. +By default, |PSMDB| runs with WiredTiger_. There is also the original MMAPv1_ +storage engine, as well as an optional :ref:`inmemory` storage engine to choose +from. Each storage engine is designed for specific purposes and workloads. -You can select a storage engine -using the ``--storageEngine`` command-line option when you start ``mongod``. -Alternatively, you can set the ``storage.engine`` variable -in the configuration file (by default, :file:`/etc/mongod.conf`). +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, +:file:`/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, +- If you simply want to temporarily test a storage engine, you can change to a different data directory using the ``--dbpath`` command-line option: .. code-block:: bash - $ service mongod stop - $ mongod --storageEngine rocksdb --dbpath + $ 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:: -* If you want to permanently switch to a different storage engine + Make sure that the user running :program:`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: .. code-block:: bash - $ service mongod stop - $ rm -rf /var/lib/mongodb/* - $ sed -i '/engine: \*rocksdb/s/#//g' /etc/mongod.conf - $ service mongod start + $ 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 the new +- If there is data that you want to migrate and make compatible with the new storage engine, use the ``mongodump`` and ``mongorestore`` utilities: .. code-block:: bash - $ mongodump --out - $ service mongod stop - $ rm -rf /var/lib/mongodb/* - $ sed -i '/engine: \*rocksdb/s/#//g' /etc/mongod.conf - $ service mongod start - $ mongorestore + $ mongodump --out + $ service mongod stop + $ rm -rf /var/lib/mongodb/* + $ sed -i '/engine: \*inmemory/s/#//g' /etc/mongod.conf + $ service mongod start + $ mongorestore Storage Engine Configuration Templates -====================================== +================================================================================ The default configuration file provided with |PSMDB| (:file:`/etc/mongod.conf`) -contains templates 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 :ref:`inmemory` (default is 128). +contains templates 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 :ref:`inmemory` (default is 128). These are controlled using the following MongoDB parameters: - * ``wiredTigerConcurrentReadTransactions`` - * ``wiredTigerConcurrentWriteTransactions`` + - ``wiredTigerConcurrentReadTransactions`` + - ``wiredTigerConcurrentWriteTransactions`` -* On systems with more than roughly 24,000 collections running MMAPv1_, +- 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. +- 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 :ref:`mongorocks` - and want to use `Percona Monitoring and Management - `_. -* The default maximum internal cache size that WiredTiger_ uses +- The default maximum internal cache size that WiredTiger_ uses is the larger of either: - * 50% of RAM minus 1 GB - * 256 MB + - 50% of RAM minus 1 GB + - 256 MB + +.. $The ``storage.rocksdb.counters`` variable must be set to ``true`` +.. $if you are running :ref:`mongorocks` +.. $and want to use `Percona Monitoring and Management +.. $`_. + -* The default maximum internal cache size that :ref:`mongorocks` uses - is 30% of RAM.