diff --git a/source/administration.txt b/source/administration.txt index ba0ee9ae545..6b0bb9b821e 100644 --- a/source/administration.txt +++ b/source/administration.txt @@ -7,41 +7,9 @@ Administration The documentation in this section outlines core administrative tasks and practices that operators of MongoDB will want to consider. -Background ----------- +.. include:: /includes/dfn-list-spec-administration-landing.rst -.. toctree:: - :titlesonly: - - /administration/configuration - /administration/backups - /data-center-awareness - /core/journaling - /administration/monitoring - /core/import-export - -Processes ---------- - -.. toctree:: - :titlesonly: - - /tutorial - /tutorial/manage-the-database-profiler - /tutorial/use-database-commands - /tutorial/configure-ssl - /tutorial/monitor-with-snmp - /tutorial/manage-mongodb-processes - /tutorial/rotate-log-files - -Reference ---------- - -.. toctree:: - :titlesonly: - - /reference/ulimit - /administration/production-notes +.. include:: /includes/toc-administration-landing.rst .. seealso:: diff --git a/source/administration/administration-backup-and-recovery.txt b/source/administration/administration-backup-and-recovery.txt new file mode 100644 index 00000000000..716e9b907ed --- /dev/null +++ b/source/administration/administration-backup-and-recovery.txt @@ -0,0 +1,12 @@ +=================== +Backup and Recovery +=================== + +.. default-domain:: mongodb + +The following tutorials describe backup and restoration for a +:program:`mongod` instance: + +.. include:: /includes/dfn-list-administration-backup-and-recovery.rst + +.. include:: /includes/toc-administration-backup-and-recovery.rst diff --git a/source/administration/administration-backup-sharded-clusters.txt b/source/administration/administration-backup-sharded-clusters.txt new file mode 100644 index 00000000000..8b09d453b34 --- /dev/null +++ b/source/administration/administration-backup-sharded-clusters.txt @@ -0,0 +1,11 @@ +=================================== +Backup and Restore Sharded Clusters +=================================== + +.. default-domain:: mongodb + +The following tutorials describe backup and restoration for sharded clusters: + +.. include:: /includes/dfn-list-administration-backup-sharded-clusters.rst + +.. include:: /includes/toc-administration-backup-sharded-clusters.rst diff --git a/source/administration/administration-basic-operations.txt b/source/administration/administration-basic-operations.txt new file mode 100644 index 00000000000..9d400d28a1d --- /dev/null +++ b/source/administration/administration-basic-operations.txt @@ -0,0 +1,11 @@ +=============================== +Basic Administrative Operations +=============================== + +.. default-domain:: mongodb + +The following tutorials describe basic administrative operations: + +.. include:: /includes/dfn-list-administration-basic-operations.rst + +.. include:: /includes/toc-administration-basic-operations.rst diff --git a/source/administration/backups.txt b/source/administration/backups.txt deleted file mode 100644 index 0b4105a6c9f..00000000000 --- a/source/administration/backups.txt +++ /dev/null @@ -1,44 +0,0 @@ -========================================== -Backup and Recovery Operations for MongoDB -========================================== - -.. toctree:: - :titlesonly: - - /core/backups - -For an overview of backup strategies and considerations for all -MongoDB deployments, consider, :doc:`/core/backups`. - -.. note:: - - .. include:: /includes/fact-mms-backup-service-notice.rst - -For practical instructions and example backup procedures consider the -documents in this section. - -Backup and Recovery Procedures ------------------------------- - -.. toctree:: - :maxdepth: 1 - - /tutorial/backup-databases-with-binary-database-dumps - /tutorial/backup-databases-with-filesystem-snapshots - /tutorial/copy-databases-between-instances - /tutorial/recover-data-following-unexpected-shutdown - -.. _backup-and-restore-sharded-clusters: - -Backup and Restore Sharded Clusters ------------------------------------ - -.. toctree:: - :maxdepth: 1 - - /tutorial/backup-small-sharded-cluster-with-mongodump - /tutorial/backup-sharded-cluster-with-filesystem-snapshots - /tutorial/backup-sharded-cluster-with-database-dumps - /tutorial/restore-single-shard - /tutorial/restore-sharded-cluster - /tutorial/schedule-backup-window-for-sharded-clusters diff --git a/source/administration/procedures.txt b/source/administration/procedures.txt new file mode 100644 index 00000000000..ce035561bd4 --- /dev/null +++ b/source/administration/procedures.txt @@ -0,0 +1,12 @@ +======================== +Administration Tutorials +======================== + +.. default-domain:: mongodb + +The following tutorials describe common administrative operations in +MongoDB: + +.. include:: /includes/dfn-list-spec-administration-tutorials-landing.rst + +.. include:: /includes/toc-administration-tutorials-landing.rst diff --git a/source/administration/sharded-cluster-maintenance.txt b/source/administration/sharded-cluster-maintenance.txt index 3bc8e20e92c..3a3b4a94e28 100644 --- a/source/administration/sharded-cluster-maintenance.txt +++ b/source/administration/sharded-cluster-maintenance.txt @@ -10,4 +10,4 @@ The following tutorials provide information in maintaining sharded clusters. .. include:: /includes/toc-sharded-cluster-maintenance.rst -.. seealso:: :ref:`backup-and-restore-sharded-clusters` +.. seealso:: :doc:`/administration/administration-backup-sharded-clusters` diff --git a/source/core/administration.txt b/source/core/administration.txt new file mode 100644 index 00000000000..81e376bc431 --- /dev/null +++ b/source/core/administration.txt @@ -0,0 +1,11 @@ +======================= +Administration Concepts +======================= + +.. default-domain:: mongodb + +The following documents present an overview of MongoDB administration. + +.. include:: /includes/dfn-list-administration-concepts.rst + +.. include:: /includes/toc-administration-concepts.rst diff --git a/source/core/backups.txt b/source/core/backups.txt index 942a71a3b31..a2d579b1d9c 100644 --- a/source/core/backups.txt +++ b/source/core/backups.txt @@ -10,9 +10,7 @@ and usable state, and operators must be able to automate both the backup and the recovery operations. Also test all components of the backup system to ensure that you can recover backed up data as needed. If you cannot effectively restore your database from the -backup, then your backups are useless. This document addresses higher -level backup strategies, consider the :doc:`/administration/backups` -tutorials for documentation of specific backup procedures. +backup, then your backups are useless. .. note:: @@ -51,8 +49,8 @@ the following factors: .. _backup-approaches: -Approaches to Backing Up MongoDB Systems ----------------------------------------- +Backup Approaches +----------------- There are two main methodologies for backing up MongoDB instances. Creating binary "dumps" of the database using @@ -75,17 +73,17 @@ disaster recovery needs. Typically, filesystem snapshots are because of their accuracy and simplicity; however, :program:`mongodump` is a viable option used often to generate backups of MongoDB systems. -The following documents provide details and procedures on the two -approaches: - -- :doc:`/tutorial/backup-databases-with-filesystem-snapshots`. -- :doc:`/tutorial/backup-databases-with-binary-database-dumps`. - In some cases, taking backups is difficult or impossible because of large data volumes, distributed architectures, and data transmission speeds. In these situations, increase the number of members in your replica set or sets. +Backup and Recovery Procedures +------------------------------ + +For tutorials on the backup approaches, see +:doc:`/administration/administration-backup-and-recovery`. + Backup Strategies for MongoDB Deployments ----------------------------------------- @@ -110,15 +108,8 @@ same moment. If you decide to use an approximate-point-in-time backup method, ensure that your application can operate using a copy of the data that does not reflect a single moment in time. -The following documents describe sharded cluster related backup -procedures: - -- :doc:`/tutorial/backup-small-sharded-cluster-with-mongodump` -- :doc:`/tutorial/backup-sharded-cluster-with-filesystem-snapshots` -- :doc:`/tutorial/backup-sharded-cluster-with-database-dumps` -- :doc:`/tutorial/schedule-backup-window-for-sharded-clusters` -- :doc:`/tutorial/restore-single-shard` -- :doc:`/tutorial/restore-sharded-cluster` +For backup procedures for sharded clusters, see +:doc:`/administration/administration-backup-sharded-clusters`. .. _replica-set-backups: diff --git a/source/core/operational-segregation.txt b/source/core/operational-segregation.txt index 93597c3b3fe..189691d9d3c 100644 --- a/source/core/operational-segregation.txt +++ b/source/core/operational-segregation.txt @@ -1,6 +1,6 @@ -============================================================= -Operational Segregation in MongoDB Operations and Deployments -============================================================= +============================================== +Operational Segregation in MongoDB Deployments +============================================== .. default-domain:: mongodb diff --git a/source/data-center-awareness.txt b/source/data-center-awareness.txt index 09f5c2093ae..36d4286bb02 100644 --- a/source/data-center-awareness.txt +++ b/source/data-center-awareness.txt @@ -18,17 +18,15 @@ instances are only used for reporting workloads or that certain high-frequency portions of a sharded collection only exist on specific shards. -Consider the following documents: +.. include:: /includes/dfn-list-data-center-awareness.rst -.. toctree:: - :maxdepth: 1 +.. include:: /includes/toc-data-center-awareness.rst - /core/operational-segregation - /core/tag-aware-sharding - /tutorial/administer-shard-tags +Further Reading +--------------- -- :doc:`/tutorial/deploy-geographically-distributed-replica-set` +- The :doc:`/core/write-concern` and :doc:`/core/read-preference` + documents, which address capabilities related to data center + awareness. -Additionally, consider the :doc:`/core/write-concern` and -:doc:`/core/read-preference` documents, which addresses -capabilities related to data center awareness. +- :doc:`/tutorial/deploy-geographically-distributed-replica-set`. diff --git a/source/includes/toc-administration-backup-and-recovery.yaml b/source/includes/toc-administration-backup-and-recovery.yaml new file mode 100644 index 00000000000..a50a0db7d4a --- /dev/null +++ b/source/includes/toc-administration-backup-and-recovery.yaml @@ -0,0 +1,18 @@ +file: /tutorial/backup-databases-with-binary-database-dumps +description: | + Export the contents of a database to a binary file. +--- +file: /tutorial/backup-databases-with-filesystem-snapshots +description: | + Backup a database using a system-level tool, such as :term:`LVM` or + storage appliance. +--- +file: /tutorial/copy-databases-between-instances +description: | + Copy a database between :program:`mongod` instances or within a + :program:`mongod` instance. +--- +file: /tutorial/recover-data-following-unexpected-shutdown +description: | + Recover data that is in an inconsistent state. +... diff --git a/source/includes/toc-administration-backup-sharded-clusters.yaml b/source/includes/toc-administration-backup-sharded-clusters.yaml new file mode 100644 index 00000000000..9464bb61029 --- /dev/null +++ b/source/includes/toc-administration-backup-sharded-clusters.yaml @@ -0,0 +1,27 @@ +file: /tutorial/backup-small-sharded-cluster-with-mongodump +description: | + Backup a :term:`sharded cluster` that holds a small data set. +--- +file: /tutorial/backup-sharded-cluster-with-filesystem-snapshots +description: | + Backup each component of a sharded cluster using file-system + snapshots to capture each :program:`mongod` instance. +--- +file: /tutorial/backup-sharded-cluster-with-database-dumps +description: | + Backup each component of a sharded cluster using :program:`mongodump` + to create dumps of each :program:`mongod` instance. +--- +file: /tutorial/schedule-backup-window-for-sharded-clusters +description: | + Define a balancing window so that the balancer is always disabled + during your automated backup operation. +--- +file: /tutorial/restore-single-shard +description: | + Restore single shard from a backup. +--- +file: /tutorial/restore-sharded-cluster +description: | + Restore an entire sharded cluster. +... \ No newline at end of file diff --git a/source/includes/toc-administration-basic-operations.yaml b/source/includes/toc-administration-basic-operations.yaml new file mode 100644 index 00000000000..438371bcf37 --- /dev/null +++ b/source/includes/toc-administration-basic-operations.yaml @@ -0,0 +1,31 @@ +file: /tutorial/use-database-commands +description: | + Issue an instruction to the database. +--- +file: /tutorial/manage-mongodb-processes +description: | + Start and configure a the :program:`mongod` process. +--- +file: /tutorial/manage-the-database-profiler +description: | + Use the database profiler to collect and query data about a + :program:`mongod` instance. +--- +file: /tutorial/configure-ssl +description: | + Use MongoDB's SSL, which supports encrypted connections to + :program:`mongod` instances. +--- +file: /tutorial/monitor-with-snmp +description: | + Use MongoDB's SNMP extension. The extension is available only in the + MongoDB Enterprise version. +--- +file: /tutorial/rotate-log-files +description: | + Archive the current log files and start new ones. +--- +file: /tutorial +description: | + This section lists all MongoDB tutorials. +... \ No newline at end of file diff --git a/source/includes/toc-administration-concepts.yaml b/source/includes/toc-administration-concepts.yaml new file mode 100644 index 00000000000..e1e182dea2d --- /dev/null +++ b/source/includes/toc-administration-concepts.yaml @@ -0,0 +1,30 @@ +file: /administration/configuration +description: | + Describes common configurations and examples of best-practice + configurations. +--- +file: /core/backups +description: | + Describes approaches and considerations for backing up a MongoDB + database. +--- +file: /data-center-awareness +description: | + Describes how to configure location-based operations for the members + of a :term:`sharded cluster` or :term:`replica set`. +--- +file: /core/journaling +description: | + Describes how the MongoDB journal provides durability and crash + resiliency. +--- +file: /administration/monitoring +description: | + Describes monitoring tools, diagnostic strategies, and approaches to + monitoring replica sets and sharded clusters. +--- +file: /core/import-export +description: | + Describes the :program:`mongoimport` and :program:`mongoexport` tools + used to import and export data. +... \ No newline at end of file diff --git a/source/includes/toc-administration-landing.yaml b/source/includes/toc-administration-landing.yaml new file mode 100644 index 00000000000..42763303460 --- /dev/null +++ b/source/includes/toc-administration-landing.yaml @@ -0,0 +1,12 @@ +file: /core/administration +description: | + The core documentation of administrative approaches to MongoDB. +--- +file: /administration/procedures +description: | + Tutorials that describe common administrative operations for MongoDB. +--- +file: /reference/administration +description: | + Reference for administrative functions and operations. +... diff --git a/source/includes/toc-administration-reference.yaml b/source/includes/toc-administration-reference.yaml new file mode 100644 index 00000000000..b5faff64da5 --- /dev/null +++ b/source/includes/toc-administration-reference.yaml @@ -0,0 +1,9 @@ +file: /reference/ulimit +description: | + Describes how to check system limits and control the use of system + resources. +--- +file: /administration/production-notes +description: | + Production notes detail system configurations that affect MongoDB. +... \ No newline at end of file diff --git a/source/includes/toc-administration-tutorials-landing.yaml b/source/includes/toc-administration-tutorials-landing.yaml new file mode 100644 index 00000000000..4e5dfa13b43 --- /dev/null +++ b/source/includes/toc-administration-tutorials-landing.yaml @@ -0,0 +1,13 @@ +file: /administration/administration-basic-operations +description: | + Describes routine management operations, including configuration and + performance analysis. +--- +file: /administration/administration-backup-and-recovery +description: | + Describes backup and restoration for a :program:`mongod` instance. +--- +file: /administration/administration-backup-sharded-clusters +description: | + Describes backup and restoration for sharded clusters. +... \ No newline at end of file diff --git a/source/includes/toc-data-center-awareness.yaml b/source/includes/toc-data-center-awareness.yaml new file mode 100644 index 00000000000..8d5ea25b245 --- /dev/null +++ b/source/includes/toc-data-center-awareness.yaml @@ -0,0 +1,14 @@ +file: /core/operational-segregation +description: | + MongoDB lets you specify that certain application operations use + certain :program:`mongod` instances. +--- +file: /core/tag-aware-sharding +description: | + MongoDB lets you associate ranges of :term:`shard key` values with + specific :term:`shards `. +--- +file: /tutorial/administer-shard-tags +description: | + Associate ranges of shard key values with specific shards. +... diff --git a/source/includes/toc-spec-administration-landing.yaml b/source/includes/toc-spec-administration-landing.yaml new file mode 100644 index 00000000000..a0a280965a4 --- /dev/null +++ b/source/includes/toc-spec-administration-landing.yaml @@ -0,0 +1,23 @@ +sources: + - toc-administration-landing.yaml + - toc-administration-concepts.yaml +files: + - file: /core/administration + level: 1 + - file: /administration/configuration + level: 2 + - file: /core/backups + level: 2 + - file: /data-center-awareness + level: 2 + - file: /core/journaling + level: 2 + - file: /administration/monitoring + level: 2 + - file: /core/import-export + level: 2 + - file: /administration/procedures + level: 1 + - file: /reference/administration + level: 1 +... \ No newline at end of file diff --git a/source/includes/toc-spec-administration-tutorials-landing.yaml b/source/includes/toc-spec-administration-tutorials-landing.yaml new file mode 100644 index 00000000000..26500c5f981 --- /dev/null +++ b/source/includes/toc-spec-administration-tutorials-landing.yaml @@ -0,0 +1,47 @@ +sources: + - toc-administration-tutorials-landing.yaml + - toc-administration-basic-operations.yaml + - toc-administration-backup-and-recovery.yaml + - toc-administration-backup-sharded-clusters.yaml +files: + - file: /administration/administration-basic-operations + level: 1 + - file: /tutorial/use-database-commands + level: 2 + - file: /tutorial/manage-mongodb-processes + level: 2 + - file: /tutorial/manage-the-database-profiler + level: 2 + - file: /tutorial/configure-ssl + level: 2 + - file: /tutorial/monitor-with-snmp + level: 2 + - file: /tutorial/rotate-log-files + level: 2 + - file: /tutorial + level: 2 + - file: /administration/administration-backup-and-recovery + level: 1 + - file: /tutorial/backup-databases-with-binary-database-dumps + level: 2 + - file: /tutorial/backup-databases-with-filesystem-snapshots + level: 2 + - file: /tutorial/copy-databases-between-instances + level: 2 + - file: /tutorial/recover-data-following-unexpected-shutdown + level: 2 + - file: /administration/administration-backup-sharded-clusters + level: 1 + - file: /tutorial/backup-small-sharded-cluster-with-mongodump + level: 2 + - file: /tutorial/backup-sharded-cluster-with-filesystem-snapshots + level: 2 + - file: /tutorial/backup-sharded-cluster-with-database-dumps + level: 2 + - file: /tutorial/schedule-backup-window-for-sharded-clusters + level: 2 + - file: /tutorial/restore-single-shard + level: 2 + - file: /tutorial/restore-sharded-cluster + level: 2 +... \ No newline at end of file diff --git a/source/reference/administration.txt b/source/reference/administration.txt new file mode 100644 index 00000000000..402ddf83f68 --- /dev/null +++ b/source/reference/administration.txt @@ -0,0 +1,12 @@ +======================== +Administration Reference +======================== + +.. default-domain:: mongodb + +The following provides reference information for administrative +functions and operations: + +.. include:: /includes/dfn-list-administration-reference.rst + +.. include:: /includes/toc-administration-reference.rst diff --git a/source/tutorial/administer-shard-tags.txt b/source/tutorial/administer-shard-tags.txt index cbe0b4fe5d9..85b58941416 100644 --- a/source/tutorial/administer-shard-tags.txt +++ b/source/tutorial/administer-shard-tags.txt @@ -1,6 +1,6 @@ -================================ -Administer and Manage Shard Tags -================================ +================= +Manage Shard Tags +================= .. default-domain:: mongodb