man: refine mdb-backed page.

Initial for #160

Author: erthink

doc/man/en/man5/slapd-mdb.soelim

@@ -21,9 +21,9 @@ slapd\-mdb \- ReOpenLDAP's reliable Memory-Mapped DB backend to slapd
 .B @SYSCONFDIR@/slapd.conf
 
 .SH DESCRIPTION
-The \fBmdb\fP backend to
+In the ReopenLDAP \fBmdb\fP backend
 .BR slapd (8)
-uses ReOpenLDAP's reliable Lightning Memory-Mapped DB (MDBX) library to store data.
+uses Extended Lightning Memory-Mapped Data Base (\fBlibmdbx\fP) library to store data.
 It relies completely on the underlying operating system for memory
 management and does no caching of its own. It is the recommended
 primary database backend.
@@ -84,7 +84,7 @@ manual page.
 .BI checkpoint \ <kbyte>\ <sec>
 Specify the frequency for flushing the database disk buffers.
 This setting is helpful when using the \fBdbnosync\fP option
-or the \fBnosync\fR, \fBnometasync\fR and \fBmapasync\fR flags
+or the \fBnosync\fR, \fBlazysync\fR, \fBnometasync\fR and \fBmapasync\fR flags
 in the \fBenvflags\fR option. Otherwise, flushing
 is done every time a write operation (transaction) is completed;
 generating any additional checkpoints makes no sense.
@@ -101,6 +101,12 @@ regardless of which mode is enabled by the \fBnosync\fR option's flags.
 With the original OpenLDAP project, there is a chance that the database
 may be corrupted in some scenarios when \fBwritemap\fR is combined
 with \fBnosync\fR, \fBnometasync\fR and \fBmapasync\fR.
+However, PLEASE NOTE, in \fBnosync\fR, \fBlazysync\fR and \fBnometasync\fR modes
+after abnormal (disaster) shutdown \fBlibmdbx\fP storage engine will rollback all
+changes to the last commit checkpoint on disk,
+formed in accordance with the parameters of \fBcheckpoint\fR option.
+Accordingly, if \fBcheckpoint\fR is not used, it may be lost
+all changes after the last regular (non disaster) shutdown of \fBslapd\fR.
 .LP
 Note2:
 ReOpenLDAP implements support for the \fI<kbyte>\fP setting. The data
@@ -126,7 +132,7 @@ By default, a full data flush/sync is performed when each
 transaction is committed.
 .TP
 .BI directory \ <directory>
-Specify the directory where the LMDB files containing this database and
+Specify the directory where the MDBX-files containing this database and
 associated indexes live.
 A separate directory must be specified for each database.
 The default is
@@ -135,7 +141,7 @@ The default is
 .BI dreamcatcher \ <lag>\ <percentage>
 Manage restarts of long-lasting read operations that
 make it impossible to free and reuse pages used
-in older database version snapshots (results of past write transactions) in the LMDB.
+in older database version snapshots (results of past write transactions) in the \fBlibmdbx\fP.
 With a lot of changes being made in a short span of time, such operations
 can lead to consumption of all available space in the database and a failure.
 The first parameter called \fI<lag>\fP specifies a transaction lag threshold which,
@@ -189,8 +195,8 @@ Note2:
 .RE
 .TP
 .TP
-.BI envflags \ [nosync]\ [nometasync]\ [writemap]\ [mapasync]\ [nordahead]\ [lifo]\ [coalesce]
-Specify flags for finer-grained control of the LMDB library's operation.
+.BI envflags \ [nosync]\ [lazysync]\ [nometasync]\ [writemap]\ [mapasync]\ [nordahead]\ [lifo]\ [coalesce]
+Specify flags for finer-grained control of the \fBlibmdbx\fP operation.
 Note: The above flags for \fBenvflags\fR should be defined in slapd.conf without
 any brackets or commas, using spaces or tabs as separators.
 .RS
@@ -202,6 +208,11 @@ directive.
 .RE
 .RS
 .TP
+.B lazysync
+Will be described later. Please see Russian man page.
+.RE
+.RS
+.TP
 .B nometasync
 Flush the data on a commit, but skip the sync of the meta page. This mode is
 slightly faster than doing a full sync, but can potentially lose the last
@@ -242,9 +253,8 @@ is larger than RAM. This option is not implemented on Windows.
 .RS
 .TP
 .B lifo
-Turn on LIFO (reverse) internal reclaiming within \fBmdb\fP of FreeDB entries
-which specify the pages being freed when re-processing old database
-versions (results of past write transactions). Consequently, it is most likely
+Turn on LIFO (reverse) internal reclaiming within \fBlibmdbx\fP garbage collector.
+Consequently, it is most likely
 that the set of pages in use recurs from transaction to transaction.
 This, in turn, makes it possible for the storage subsystem
 to use the internal caching and writeback mechanisms efficiently,
@@ -257,7 +267,7 @@ is not available in the original OpenLDAP.
 .RS
 .TP
 .B coalesce
-Turn on coagulation of FreeDB entries within \fBmdb\fP (merging the lists of
+Turn on coagulation of entries within \fBlibmdb\fP garbage collector (merging the lists of
 free pages), which reduces the amount of internal indexes and the number of pages
 updated upon any changes. As a result, the load on the storage subsystem
 diminishes slightly in most scenarios.
@@ -304,7 +314,7 @@ of the indices online in a background task.
 Specify the maximum number of threads that may have concurrent read access
 to the database. Tools such as slapcat count as a single thread,
 in addition to threads in any active slapd processes. The
-default is 126.
+default is 61.
 .TP
 .BI maxsize \ <bytes>
 Specify the maximum size of the database in bytes. A memory map of this
@@ -356,6 +366,7 @@ default
 .B slapd
 configuration file
 .SH SEE ALSO
+.BR libmdbx (https://github.com/leo-yuriev/libmdbx/README.md),
 .BR slapd.conf (5),
 .BR slapd\-config (5),
 .BR slapd (8),

doc/man/ru/man5/slapd-mdb.soelim

@@ -21,9 +21,9 @@ slapd\-mdb \- механизм манипуляции данными для slap
 .B @SYSCONFDIR@/slapd.conf
 
 .SH ОПИСАНИЕ
-Механизм манипуляции данными для
+В ReOpenLDAP механизм манипуляции данными для
 .BR slapd (8)
-\fBmdb\fP использует для хранения данных библиотеку ReOpenLDAP reliable Lightning Memory-Mapped DB (MDBX).
+\fBmdb\fP использует для хранения данных библиотеку Extended Lightning Memory-Mapped Data Base (\fBlibmdbx\fP).
 Библиотека не имеет собственных механизмов кэширования, полагаясь на средства
 управления виртуальной памятью операционной системы, в которой она работает.
 \fBmdb\fP является рекомендуемым первичным механизмом для работы с базами данных.
@@ -77,7 +77,7 @@ slapd\-mdb \- механизм манипуляции данными для slap
 .BI checkpoint \ <kbyte>\ <min>
 Указывает частоту синхронизации образа базы данных в оперативной памяти
 с записанным на диске. Эта установка полезна при использовании директивы
-\fBdbnosync\fP, либо флагов \fBnosync\fR, \fBnometasync\fR, \fBmapasync\fR
+\fBdbnosync\fP, либо флагов \fBnosync\fR, \fBlazysync\fR, \fBnometasync\fR, \fBmapasync\fR
 в директиве \fBenvflags\fR. Иначе синхронизация выполняется
 при завершении каждой операции (транзакции) записи и дополнительное
 формирование контрольных точек теряет смысл.
@@ -91,15 +91,21 @@ slapd\-mdb \- механизм манипуляции данными для slap
 \fIПримечание 1:\fP
 В ReOpenLDAP гарантируется консистентность данных на диске в каждой
 контрольной точке, вне зависимости от режима заданного флагами директивы \fBnosync\fR.
-Исходный проект OpenLDAP в некоторых сценариях допускает вероятность разрушения
+Оригинальный OpenLDAP в некоторых сценариях допускает полное разрушение
 базы данных при комбинировании \fBwritemap\fR с \fBnosync\fR, \fBnometasync\fR
 и \fBmapasync\fR.
+Однако, ОБРАТИТЕ ВНИМАНИЕ, в режимах \fBnosync\fR,
+\fBlazysync\fR и \fBnometasync\fR после нештатно (аварийного)
+завершения опорный движок хранения \fBlibmdbx\fP откатит все
+изменения до последней контрольной точки фиксации на диске,
+сформированной в соответствии с параметрами опции \fBcheckpoint\fR.
+Соответственно, если \fBcheckpoint\fR не используется, то могут быть потеряны
+все изменения в DIT после последнего штатного (не аварийного) завершения \fBslapd\fR.
 .LP
 \fIПримечание 2:\fP
 В ReOpenLDAP реализована поддержка установки \fI<kbyte>\fP. При этом под объемом
 данных подразумевается суммарный размер измененных страниц внутри \fBmdb\fP.
-Однако в исходном проекте OpenLDAP в настоящее время эта установка
-по-прежнему не обслуживается.
+В оригинальном OpenLDAP эта опция по-прежнему не обслуживается.
 .LP
 \fIПримечание 3:\fP
 В ReOpenLDAP интерпретация значения \fI<min>\fP зависит от режима задаваемого
@@ -110,20 +116,23 @@ slapd\-mdb \- механизм манипуляции данными для slap
 .RE
 .TP
 .B dbnosync
-Указывает, что содержимое базы данных на диске не должно немедленно синхронизироваться
-при изменении содержимого базы данных в памяти. Включение этой опции может повысить
-производительность за счёт увеличения риска потери данных. В частности, если до синхронизации
-изменений произойдёт крах операционной системы, некоторое количество транзакций может быть потеряно.
-По умолчанию при фиксации каждой транзакции выполняется полная синхронизация данных.
+Указывает, что содержимое базы данных на диске не должно
+немедленно синхронизироваться при изменении содержимого базы
+данных в памяти. Включение этой опции может повысить
+производительность за счёт увеличения риска потери данных. В
+частности, если до синхронизации изменений произойдёт крах
+операционной системы, существенное количество транзакций
+(изменений) может быть потеряно. По умолчанию при фиксации
+каждой транзакции выполняется полная синхронизация данных.
 .TP
 .BI directory \ <directory>
-Указывает директорию, где находятся LMDB-файлы, содержащие эту базу данных
+Указывает директорию, где находятся MDBX-файлы, содержащие эту базу данных
 и ассоциированные с ней индексы. Для каждой базы данных должна быть определена
 отдельная директория. По умолчанию -
 .BR @LOCALSTATEDIR@/reopenldap\-data .
 .TP
 .BI dreamcatcher \ <lag>\ <percentage>
-Управляет механизмом перезапуска долгих операций чтения, которые в LMDB
+Управляет механизмом перезапуска долгих операций чтения, которые в \fBlibmdbx\fP
 останавливают освобождение и повторное использование страниц, использованных
 в старых версиях-снимках базы данных (результатов прошлых транзакций записи),
 что при интенсивном потоке изменений приводит к полному заполнению базы и отказу.
@@ -178,8 +187,8 @@ slapd\-mdb \- механизм манипуляции данными для slap
 .RE
 .TP
 .TP
-.BI envflags \ [nosync]\ [nometasync]\ [writemap]\ [mapasync]\ [nordahead]\ [lifo]\ [coalesce]
-Указывает флаги для более детального контроля работы библиотеки LMDB.
+.BI envflags \ [nosync]\ [lazysync]\ [nometasync]\ [writemap]\ [mapasync]\ [nordahead]\ [lifo]\ [coalesce]
+Указывает флаги для более детального контроля работы опорного движка \fBlibmdbx\fP.
 \fIПримечание:\fP в slapd.conf перечисленные флаги для \fBenvflags\fR необходимо
 задавать без скобок и запятых, разделяя пробелами или символами табуляции.
 .RS
@@ -190,10 +199,15 @@ slapd\-mdb \- механизм манипуляции данными для slap
 .RE
 .RS
 .TP
+.B lazysync
+Опция будет документирована позже.
+.RE
+.RS
+.TP
 .B nometasync
 При фиксации транзакции данные синхронизируются, а синхронизация метастраницы пропускается.
 Этот метод несколько быстрее, чем выполнение полной синхронизации, но существует вероятность потери
-последних зафиксированных транзакций при крахе операционной системы. Если выставлены оба флага
+последней транзакций при крахе операционной системы. Если выставлены оба флага
 .I nometasync
 и
 .IR nosync ,
@@ -223,30 +237,27 @@ slapd\-mdb \- механизм манипуляции данными для slap
 Отключает упреждающее чтение файла. Обычно операционная система выполняет упреждающее чтение при каждом запросе на чтение.
 Как правило, это повышает производительность операций чтения, но может ухудшить производительность при чтении
 с произвольным доступом, если системная память заполнена и размер базы данных больше чем объём RAM.
-Эта опция не реализована на Windows.
 .RE
 .RS
 .TP
 .B lifo
-Включает LIFO (обратный) порядок переработки внутри \fBmdb\fP записей FreeDB,
-в которых указываются страницы освобождающиеся при переработке старых версий
-базы данных (результатов прошлых транзакций записи).
+Включает LIFO (обратный) порядок переработки внутри сборщикам мусора \fBlibmdbx\fP.
 Вследствие чего, с большой вероятностью, от транзакции к транзакции используется
 повторяющийся набор страниц. Это, в свою очередь, позволяет подсистеме хранения
 эффективно использовать внутренние механизмы кеширования и обратной записи,
 объединяя такие повторные операции. В результате может существенно увеличиться
 общая производительность одновременно со снижением реальной нагрузки
 на подсистему хранения (диски).
-Режим \fIlifo\fP доступен только в ReOpenLDAP и отсутствует в исходном OpenLDAP.
+Режим \fIlifo\fP доступен только в ReOpenLDAP.
 .RE
 .RS
 .TP
 .B coalesce
-Включает коагуляцию записей FreeDB внутри \fBmdb\fP (объединение списков
+Включает коагуляцию записей сборщика мусора внутри \fBlibmdbx\fP (объединение списков
 свободных страниц), что уменьшает объем внутренних индексов и количество
 обновляемых страниц при любых изменениях. В результате в большинстве
 сценариев несколько уменьшается нагрузка на подсистему хранения.
-Режим \fIcoalesce\fP доступен только в ReOpenLDAP и отсутствует в исходном OpenLDAP.
+Режим \fIcoalesce\fP доступен только в ReOpenLDAP.
 .RE
 .TP
 \fBindex \fR{\fI<attrlist>\fR|\fBdefault\fR} [\fBpres\fR,\fBeq\fR,\fBapprox\fR,\fBsub\fR,\fI<special>\fR]
@@ -281,7 +292,7 @@ slapd\-mdb \- механизм манипуляции данными для slap
 .BI maxreaders \ <integer>
 Указывает максимальное количество потоков, которые могут параллельно получать доступ на чтение к базе данных.
 Работа таких инструментов, как slapcat, считается за один поток в дополнение к потокам
-в любых активных процессах slapd. Значение по умолчанию - 126.
+в любых активных процессах slapd. Значение по умолчанию - 61.
 .TP
 .BI maxsize \ <bytes>
 Указывает максимальный размер базы данных в байтах. При запуске под отображение базы данных в памяти
@@ -329,6 +340,7 @@ slapd\-mdb \- механизм манипуляции данными для slap
 .B slapd
 по умолчанию.
 .SH СМОТРИТЕ ТАКЖЕ
+.BR libmdbx (https://github.com/leo-yuriev/libmdbx/README-RU.md),
 .BR slapd.conf (5),
 .BR slapd\-config (5),
 .BR slapd (8),

servers/slapd/back-mdb/config.c

@@ -369,7 +369,7 @@ mdb_cf_gen( ConfigArgs *c )
 
 		case MDB_ENVFLAGS:
 			if ( mdb->mi_dbenv_flags == MDBX_UTTERLY_NOSYNC )
-				rc = 1;
+				rc = 1; /* report "no flags", but return "ok" for MDB_DBNOSYNC/dbnosync */
 			else {
 				if ( mdb->mi_dbenv_flags )
 					mask_to_verbs( mdb_envflags, mdb->mi_dbenv_flags, &c->rvalue_vals );