PS-11564 [DOCS] - Update documentation for ps-admin script 9.7

docs/index-keywords.md

@@ -325,7 +325,7 @@ performance
 :   [DEB repository package list - Percona Server for MySQL {{vers}}](apt-files.md), [Use an APT repository to install Percona Server for MySQL {{vers}}](apt-repo.md), [Audit log filter functions, options, and variables](audit-log-filter-variables.md), [Audit log plugin](audit-log-plugin.md), [Authentication methods](authentication-methods.md), [Binary logs and replication improvements](binlogging-replication-improvements.md), [Data masking component functions and variables](data-masking-function-list.md), [Data masking overview](data-masking-overview.md), [Common data types](data-types-basic.md), [Introduction to Databases and SQL](database.md), [DELETE statement](delete.md), [Development of Percona Server for MySQL](development.md), [Running Percona Server for MySQL in a Docker Container](docker.md), [Downgrade Percona Server for MySQL](downgrade.md), [Encryption functions](encryption-functions.md), [Percona Server for MySQL feature comparison](feature-comparison.md), [Functions](functions.md), [Get help from Percona](get-help.md), [Glossary](glossary.md), [Improved MEMORY storage engine](improved-memory-engine.md), [Index](index-contents.md), [Percona Server for MySQL {{vers}} - Documentation](index.md), [Extended show engine InnoDB status](innodb-show-status.md), [INSERT statement](insert.md), [Isolation levels](isolation-levels.md), [js_lang stored procedure and function overview](js-lang-overview.md), [Kill idle transaction](kill-idle-trx.md), [Using libcoredumper](libcoredumper.md), [Too many connections warning](log-connection-error.md), [Percona MyRocks introduction](myrocks-index.md), [MyRocks server variables](myrocks-server-variables.md), [List of features available in Percona Server for MySQL releases](percona-server-versions-comparison.md), [The Percona XtraDB storage engine](percona-xtradb.md), [Performance Schema MyRocks changes](performance-schema-myrocks-changes.md), [The ProcFS plugin](procfs-plugin.md), [Install Percona Server for MySQL and create a database on Ubuntu](quickstart-apt.md), [Quickstart - Run Percona Server for MySQL container images with Docker](quickstart-docker.md), [Next steps](quickstart-next-steps.md), [Overview](quickstart-overview.md), [Install Percona Server for MySQL and create a database on Oracle Linux](quickstart-yum.md), [Restrict dynamic log file locations](restrict-dynamic-log-locations.md), [Secure Percona Server for MySQL with SELinux](selinux.md), [Slow query log](slow-extended.md), [SQL syntax](sql-syntax.md), [Stack trace](stacktrace.md), [Start transaction with consistent snapshot](start-transaction-with-consistent-snapshot.md), [Error handling in stored procedures](stored-procedure-error-handling.md), [Stored Procedures](stored-procedures.md), [Introduction to database tables](table.md), [Thread based profiling](thread-based-profiling.md), [Thread pool](threadpool.md), [Trademark policy](trademark-policy.md), [Trigger updates](trigger-updates.md), [Triggers](triggers.md), [UPDATE statement](update.md), [Upgrade checklist for {{vers}}](upgrade-checklist-9.7.md), [Upgrade from 8.4 to {{vers}} overview](upgrade.md), [UUID_VX component](uuid-versions.md), [Views](views.md), [Write audit_log_filter definitons](write-filter-definitions.md), [XtraDB performance improvements for I/O-bound highly-concurrent workloads](xtradb-performance-improvements.md), [Install Percona Server for MySQL using downloaded RPM packages](yum-download-rpm.md), [Yum repository package list - Percona Server for MySQL {{vers}}](yum-files.md), [Install using DNF](yum-repo.md)
 
 plugin
-:   [DEB repository package list - Percona Server for MySQL {{vers}}](apt-files.md), [Audit log plugin](audit-log-plugin.md), [Authentication methods](authentication-methods.md), [Build APT packages](build-apt-packages.md), [MySQL Clone plugin](clone-plugin.md), [Data at Rest Encryption](data-at-rest-encryption.md), [Encrypt binary log files and relay log files](encrypt-binary-relay-log-files.md), [Encrypt schema or general tablespace](encrypt-tablespaces.md), [Extended SET VAR optimizer hint](extended-set-var.md), [Percona Server for MySQL feature comparison](feature-comparison.md), [FIDO authentication plugin](fido-authentication-plugin.md), [Index](index-contents.md), [Index of INFORMATION_SCHEMA tables](index-info-schema-tables.md), [Percona Server for MySQL {{vers}} - Documentation](index.md), [Install the audit log filter](install-audit-log-filter.md), [Percona MyRocks installation guide](install-myrocks.md), [Using LDAP authentication plugins](ldap-authentication.md), [LDAP authentication plugin system variables](ldap-system-variables.md), [MyRocks Information Schema tables](myrocks-information-schema-tables.md), [PAM authentication plugin](pam-plugin.md), [List of features available in Percona Server for MySQL releases](percona-server-versions-comparison.md), [Post-installation](post-installation.md), [The ProcFS plugin](procfs-plugin.md), [Thread pool](threadpool.md), [Uninstall Audit Log Filter](uninstall-audit-log-filter.md), [Upgrade checklist for {{vers}}](upgrade-checklist-9.7.md), [Upgrade from plugins to components](upgrade-components.md), [Upgrade from 8.4 to {{vers}} overview](upgrade.md), [Use the keyring file component](use-keyring-file.md), [Yum repository package list - Percona Server for MySQL {{vers}}](yum-files.md)
+:   [DEB repository package list - Percona Server for MySQL {{vers}}](apt-files.md), [Audit log plugin](audit-log-plugin.md), [Authentication methods](authentication-methods.md), [Build APT packages](build-apt-packages.md), [MySQL Clone plugin](clone-plugin.md), [Data at Rest Encryption](data-at-rest-encryption.md), [Encrypt binary log files and relay log files](encrypt-binary-relay-log-files.md), [Encrypt schema or general tablespace](encrypt-tablespaces.md), [Extended SET VAR optimizer hint](extended-set-var.md), [Percona Server for MySQL feature comparison](feature-comparison.md), [FIDO authentication plugin](fido-authentication-plugin.md), [Index](index-contents.md), [Index of INFORMATION_SCHEMA tables](index-info-schema-tables.md), [Percona Server for MySQL {{vers}} - Documentation](index.md), [Install the audit log filter](install-audit-log-filter.md), [Percona MyRocks installation guide](install-myrocks.md), [Using LDAP authentication plugins](ldap-authentication.md), [LDAP authentication plugin system variables](ldap-system-variables.md), [MyRocks Information Schema tables](myrocks-information-schema-tables.md), [PAM authentication plugin](pam-plugin.md), [List of features available in Percona Server for MySQL releases](percona-server-versions-comparison.md), [Post-installation](post-installation.md), [The ProcFS plugin](procfs-plugin.md), [The ps-admin script](ps-admin.md), [Thread pool](threadpool.md), [Uninstall Audit Log Filter](uninstall-audit-log-filter.md), [Upgrade checklist for {{vers}}](upgrade-checklist-9.7.md), [Upgrade from plugins to components](upgrade-components.md), [Upgrade from 8.4 to {{vers}} overview](upgrade.md), [Use the keyring file component](use-keyring-file.md), [Yum repository package list - Percona Server for MySQL {{vers}}](yum-files.md)
 
 privilege
 :   [Additional PERFORMANCE_SCHEMA tables](additional-performance-schema-tables.md), [Audit Log Filter overview](audit-log-filter-overview.md), [Backup locks](backup-locks.md), [Binary logs and replication improvements](binlogging-replication-improvements.md), [Compressed columns with dictionaries](compressed-columns.md), [Create a table](create-table.md), [Data masking component functions and variables](data-masking-function-list.md), [Introduction to Databases and SQL](database.md), [Disable Audit Log Filter logging](disable-audit-log-filter.md), [Encrypt binary log files and relay log files](encrypt-binary-relay-log-files.md), [Encrypt system tablespace](encrypt-system-tablespace.md), [Review effective privileges with SHOW EFFECTIVE GRANTS](extended-show-grants.md), [FIDO authentication plugin](fido-authentication-plugin.md), [Filter the Audit Log Filter logs](filter-audit-log-filter-files.md), [Install the data masking component](install-data-masking-component.md), [Install js_lang component](install-js-lang.md), [Percona MyRocks installation guide](install-myrocks.md), [js_lang privileges](js-lang-privileges.md), [js_lang stored function or procedure](js-lang-procedures.md), [Manage the Audit Log Filter files](manage-audit-log-filter.md), [Post-installation](post-installation.md), [The ProcFS plugin](procfs-plugin.md), [Install Percona Server for MySQL and create a database on Ubuntu](quickstart-apt.md), [Install Percona Server for MySQL and create a database on Oracle Linux](quickstart-yum.md), [Rotate the master encryption key](rotate-master-key.md), [UNINSTALL COMPONENT](uninstall-component.md), [User statistics](user-stats.md), [Verify the encryption for tables, tablespaces, and schemas](verify-encryption.md), [Write audit_log_filter definitons](write-filter-definitions.md), [Install using DNF](yum-repo.md)
@@ -410,6 +410,7 @@ storage engine
 * [Telemetry on Percona Server for MySQL](telemetry.md)
 * [The Percona XtraDB storage engine](percona-xtradb.md)
 * [The ProcFS plugin](procfs-plugin.md)
+* [The ps-admin script](ps-admin.md)
 * [Thread based profiling](thread-based-profiling.md)
 * [Thread pool](threadpool.md)
 * [Too many connections warning](log-connection-error.md)

docs/install-myrocks.md

@@ -70,11 +70,7 @@ $ sudo ps-admin --enable-rocksdb -u root -pPassw0rd
 
 !!! note
 
-    When you use the `ps-admin` script to enable Percona MyRocks, it performs the following:
-
-    * Disables Transparent huge pages
-
-    * Installs and enables the RocksDB plugin
+    When you use the `ps-admin` script to enable Percona MyRocks, the script locates `ha_rocksdb.so` and installs the RocksDB engine plugin and the related MyRocks information schema plugins. For command options and troubleshooting, see [The ps-admin script](ps-admin.md).
 
 If the script returns no errors,
 Percona MyRocks should be successfully enabled on the server.

docs/pam-plugin.md

@@ -27,12 +27,34 @@ A plugin may not be supported in later releases of MySQL or Percona Server for M
 
 ## Installation
 
-This plugin requires manual installation because it isn’t installed by default.
+This plugin requires manual installation because the plugin is not installed by default.
+
+You can install the plugin with SQL, or with the `ps-admin` script. For script options, see [The ps-admin script](ps-admin.md).
+
+Install the full PAM plugin (`auth_pam`) with SQL:
 
 ```sql
 INSTALL PLUGIN auth_pam SONAME 'auth_pam.so';
 ```
 
+Or run the following command:
+
+```shell
+$ sudo ps-admin --enable-pam -u root -p
+```
+
+Install the Oracle-compatible PAM plugin (`auth_pam_compat`) with SQL:
+
+```sql
+INSTALL PLUGIN auth_pam_compat SONAME 'auth_pam_compat.so';
+```
+
+Or run the following command:
+
+```shell
+$ sudo ps-admin --enable-pam-compat -u root -p
+```
+
 After the plugin has been installed it should be present in the plugins list. To check if the plugin has been correctly installed and active
 
 ```sql

docs/ps-admin.md

@@ -0,0 +1,275 @@
+# The ps-admin script
+
+The `ps-admin` script is an administrative helper in Percona Server for MySQL {{vers}}.
+
+The script enables or disables optional plugins and the MyRocks storage engine on a running server.
+
+The script connects with administrator credentials and runs the required `INSTALL PLUGIN` or `UNINSTALL PLUGIN` statements.
+
+## Requirements
+
+Meet the following requirements before you run `ps-admin`:
+
+* Install and start Percona Server for MySQL {{vers}}.
+
+* Keep the `mysql` client in the same directory as `ps-admin`.
+
+* Grant the MySQL user privilege to install or uninstall plugins.
+
+* Confirm that the plugin shared library exists in the server plugin directory.
+
+Run `ps-admin` as the operating system `root` user or with `sudo`.
+
+Install the `percona-server-rocksdb` package before you enable MyRocks.
+
+## Command syntax
+
+The following syntax is the general form of the command:
+
+```shell
+sudo ps-admin <ACTION> -u <MYSQL_ADMIN_USER> -p[<MYSQL_ADMIN_PASSWORD>] \
+    [-S <SOCKET>] [-h <HOST> -P <PORT>]
+```
+
+Replace `<ACTION>` with one enable option or one disable option.
+
+Specify at least one `--enable-*` option or one `--disable-*` option.
+
+Use only `--enable-rocksdb` or only `--disable-rocksdb` for MyRocks. Apply the same rule to each plugin.
+
+Print the option list with the following command:
+
+```shell
+ps-admin --help
+```
+
+## Connection options
+
+The following table lists options that control the MySQL connection:
+
+| Option | Short option | Description |
+| --- | --- | --- |
+| `--user=<USER_NAME>` | `-u` | MySQL administrator user name. The default value is `root`. |
+| `--password[=<PASSWORD>]` | `-p` | MySQL administrator password. An empty `-p` value prompts for the password. |
+| `--socket=<PATH>` | `-S` | Unix socket file for the connection |
+| `--host=<HOST_NAME>` | `-h` | Host name for a TCP connection |
+| `--port=<PORT_NUM>` | `-P` | Port number for a TCP connection |
+| `--config-file=<FILE>` | `-c` | File that provides credentials and options |
+
+## Plugin and engine options
+
+The following table lists options that enable or disable plugins and MyRocks:
+
+| Option | Short option | Action |
+| --- | --- | --- |
+| `--enable-rocksdb` | `-k` | Enable the MyRocks (`ROCKSDB`) storage engine |
+| `--disable-rocksdb` | `-o` | Disable the MyRocks storage engine |
+| `--enable-pam` | `-i` | Enable the Pluggable Authentication Modules (PAM) plugin (`auth_pam`) |
+| `--disable-pam` | `-n` | Disable the PAM plugin |
+| `--enable-pam-compat` | `-j` | Enable the Oracle-compatible PAM plugin (`auth_pam_compat`) |
+| `--disable-pam-compat` | `-K` | Disable the Oracle-compatible PAM plugin |
+| `--enable-mysqlx` | `-x` | Enable the MySQL X plugin (`mysqlx`) |
+| `--disable-mysqlx` | `-g` | Disable the MySQL X plugin |
+
+## Enable MyRocks
+
+Install the MyRocks package first. For package steps, see [Percona MyRocks installation guide](install-myrocks.md).
+
+Enable MyRocks with the following command:
+
+```shell
+sudo ps-admin --enable-rocksdb -u root -p
+```
+
+The script searches for `ha_rocksdb.so` in the following locations:
+
+* `../lib/plugin` relative to the `ps-admin` directory
+
+* `/usr/lib64/mysql/plugin`
+
+* `/usr/lib/mysql/plugin`
+
+The script then installs the MyRocks plugins from `ha_rocksdb.so` on the running server. The install list includes `ROCKSDB` and the related MyRocks information schema plugins.
+
+Verify the engine with the following statement:
+
+```sql
+SHOW ENGINES;
+```
+
+The `ROCKSDB` row must show `YES` in the `Support` column.
+
+InnoDB remains the default storage engine after the enable command. To create tables on MyRocks, set `default-storage-engine=rocksdb` in the `[mysqld]` section of `my.cnf`, or add `ENGINE=RocksDB` to each `CREATE TABLE` statement.
+
+For more detail, see [Percona MyRocks installation guide](install-myrocks.md).
+
+## Enable the PAM authentication plugin
+
+Enable the full PAM plugin with the following command:
+
+```shell
+sudo ps-admin --enable-pam -u root -p
+```
+
+The script runs the following statement:
+
+```sql
+INSTALL PLUGIN auth_pam SONAME 'auth_pam.so';
+```
+
+Enable the Oracle-compatible PAM plugin with the following command:
+
+```shell
+sudo ps-admin --enable-pam-compat -u root -p
+```
+
+The script runs the following statement:
+
+```sql
+INSTALL PLUGIN auth_pam_compat SONAME 'auth_pam_compat.so';
+```
+
+Configure the PAM stack after the plugin is active. For PAM files, user accounts, and client requirements, see [PAM authentication plugin](pam-plugin.md).
+
+## Enable the MySQL X plugin
+
+The MySQL X plugin provides X Protocol support. The plugin is enabled by default in Percona Server for MySQL {{vers}}. Use `--enable-mysqlx` only if `SHOW PLUGINS` does not list `mysqlx` as `ACTIVE`.
+
+Enable the MySQL X plugin with the following command:
+
+```shell
+sudo ps-admin --enable-mysqlx -u root -p
+```
+
+The script runs the following statement:
+
+```sql
+INSTALL PLUGIN mysqlx SONAME 'mysqlx.so';
+```
+
+For X Protocol and plugin options, see the [X Plugin :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/x-plugin.html) documentation.
+
+## Disable a plugin or engine
+
+Disable MyRocks with the following command:
+
+```shell
+sudo ps-admin --disable-rocksdb -u root -p
+```
+
+Convert MyRocks tables to another engine before you disable MyRocks if you still need the data.
+
+Disable other plugins with the matching `--disable-*` option.
+
+The following examples disable each supported plugin:
+
+```shell
+sudo ps-admin --disable-pam -u root -p
+```
+
+```shell
+sudo ps-admin --disable-pam-compat -u root -p
+```
+
+```shell
+sudo ps-admin --disable-mysqlx -u root -p
+```
+
+## Verify plugin status
+
+The script checks `INFORMATION_SCHEMA.PLUGINS` before each change.
+
+Confirm the result with the following statement:
+
+```sql
+SELECT PLUGIN_NAME, PLUGIN_STATUS, PLUGIN_TYPE
+FROM INFORMATION_SCHEMA.PLUGINS
+WHERE PLUGIN_NAME IN (
+  'ROCKSDB',
+  'auth_pam',
+  'auth_pam_compat',
+  'mysqlx'
+);
+```
+
+The `PLUGIN_STATUS` value is `ACTIVE` after a successful enable operation.
+
+An empty result after a disable operation means the plugin is not loaded.
+
+## Connection examples
+
+Prompt for the password on a local socket:
+
+```shell
+sudo ps-admin --enable-pam -u root -p -S /var/run/mysqld/mysqld.sock
+```
+
+Connect over TCP:
+
+```shell
+sudo ps-admin --enable-rocksdb -u root -pPassw0rd -h 127.0.0.1 -P 3306
+```
+
+## Troubleshoot
+
+Use the following actions after a script error:
+
+* Check the user name, password, host, port, or socket after a plugin list failure.
+
+* Install the MyRocks package after a missing `ha_rocksdb.so` library message.
+
+* Uninstall leftover MyRocks plugins by hand after a partial install, then run `--enable-rocksdb` again.
+
+* Verify the plugin library path and MySQL plugin privileges after an install failure.
+
+Review the server error log after an install or uninstall failure.
+
+## Removed Audit Log options
+
+The Audit Log plugin (`audit_log`) is removed in Percona Server for MySQL {{vers}}. The plugin library `audit_log.so` is not built or packaged, so you cannot install the plugin.
+
+The script still parses `--enable-audit` (`-a`) and `--disable-audit` (`-w`). Those flags do not install the plugin. `--enable-audit` runs `INSTALL PLUGIN audit_log SONAME 'audit_log.so';`, which fails because the library is not present.
+
+Use the [Audit Log Filter component](audit-log-filter-overview.md) instead. See [Install the audit log filter](install-audit-log-filter.md) and [Migrate to the audit log filter component](migrate-to-audit-log-filter-component.md).
+
+## Removed TokuDB options
+
+The script still parses the following TokuDB and TokuBackup flags:
+
+* `--enable-tokudb`
+
+* `--disable-tokudb`
+
+* `--enable-tokubackup`
+
+* `--disable-tokubackup`
+
+* `--defaults-file`
+
+* `--force-mycnf`
+
+* `--force-envfile`
+
+If you pass any of these flags, the script prints an error and exits. The script does not enable or disable TokuDB or TokuBackup. The TokuDB storage engine and the TokuBackup plugin were removed in Percona Server for MySQL 8.0.28-19 and are not available in {{vers}}.
+
+## Other reading
+
+The following topics describe the features that `ps-admin` enables or disables:
+
+* [Percona MyRocks installation guide](install-myrocks.md)
+
+* [Show storage engines](show-engines.md)
+
+* [PAM authentication plugin](pam-plugin.md)
+
+* [Authentication methods](authentication-methods.md)
+
+* [Audit Log Filter overview](audit-log-filter-overview.md)
+
+* [Install the audit log filter](install-audit-log-filter.md)
+
+* [Migrate to the audit log filter component](migrate-to-audit-log-filter-component.md)
+
+* [Post-installation](post-installation.md)
+
+* [X Plugin :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/x-plugin.html) — MySQL documentation for X Protocol. Percona Server for MySQL has no dedicated X Plugin page.

mkdocs-base.yml

@@ -334,6 +334,7 @@ nav:
     - extended-show-grants.md
     - restrict-dynamic-log-locations.md
     - clone-plugin.md
+    - ps-admin.md
     - Manage components:
       - install-component.md
       - uninstall-component.md