Skip to content

Commit 8b2072e

Browse files
patrickbirchpatrickbirch
authored
Merge pull request #698 from percona/ps-10986-8.4
PS-10986 [DOCS] [feedback] Your instructions don't work for ubuntu 8.4
2 parents f2675b2 + b836549 commit 8b2072e

3 files changed

Lines changed: 137 additions & 67 deletions

File tree

‎docs/apt-repo.md‎

Lines changed: 110 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -2,110 +2,116 @@
22

33
Ready-to-use packages are available from the Percona Server for MySQL software repositories and the [Percona downloads :octicons-link-external-16:](https://www.percona.com/downloads/Percona-Server-{{vers}}/) page.
44

5-
Specific information on the supported platforms, products, and versions is described in [Percona Software and Platform Lifecycle :octicons-link-external-16:](https://www.percona.com/services/policies/percona-software-platform-lifecycle#mysql).
5+
Specific information on the supported platforms, products, and versions—including which Debian and Ubuntu releases and CPU architectures (DEB packages include `arm64`, among others)—is described in [Percona Software and Platform Lifecycle :octicons-link-external-16:](https://www.percona.com/services/policies/percona-software-platform-lifecycle#mysql).
66

77
--8<-- "percona-release.md"
88

99
We gather [Telemetry data] in the Percona packages and Docker images.
1010

1111
--8<--- "get-help-snip.md"
1212

13-
## Version changes
14-
15-
Percona supports DEB builds with ARM packages with the `arm64.deb` extension on supported Debian and Ubuntu releases.
16-
17-
## Unattended installations
18-
19-
--8<-- "install-flag.md"
20-
2113
## Install Percona Server for MySQL using APT
2214

15+
If you are new to installing Percona Server on Debian or Ubuntu, copy the first command block below and run the commands in order. Use [Configure authentication](#configure-authentication) when the installer asks about the default authentication plugin. After the server packages are installed, open [Next Steps](#next-steps) for securing and configuring the instance. Expand the step-by-step section when you want an explanation of each command; use [Non-interactive installs and debconf](#non-interactive-installs-and-debconf) and [Unattended installations](#unattended-installations) only for scripted automation.
16+
2317
Run the following commands as a `root` user or with sudo:
2418

2519
```shell
2620
sudo apt update
27-
sudo apt install curl
21+
sudo apt install -y curl
2822
curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb
29-
sudo apt install gnupg2 lsb-release ./percona-release_latest.generic_all.deb
23+
sudo apt install -y gnupg2 lsb-release ./percona-release_latest.generic_all.deb
24+
sudo percona-release setup {{pkg}} --scheme https
25+
sudo percona-release enable {{pkg}} release --scheme https
3026
sudo apt update
31-
sudo percona-release enable-only {{pkg}} release
32-
sudo apt install percona-server-server
27+
sudo apt install -y percona-server-server
3328
```
3429

35-
In MySQL 8.4, the `mysql_native_password` plugin is no longer loaded by default. When the package manager prompts you during installation, you must follow the choices and steps in [Configure authentication](#configure-authentication). If you choose legacy authentication but do not enable the plugin in configuration, clients may be unable to connect or the service may fail to start.
30+
The command sequence matches [Install Percona Server for MySQL and create a database on Ubuntu](quickstart-apt.md) (installation steps 1–6 there).
3631

37-
The following sections provide detailed explanations for each step:
32+
??? note "`percona-release` flag: `--scheme`"
3833

39-
1. This command updates the package lists for upgrades and new package installations. `sudo` runs the command with superuser privileges; `apt update` resynchronizes the package index files from the sources in your system's `sources.list`.
34+
The command examples on the page pass `--scheme https` so repository URLs in APT source lists use HTTPS. The [Percona Software Repositories — `percona-release` :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/percona-release.html) documentation describes the Flags section: the available flag is `--scheme`, with supported values HTTP and HTTPS; without the flag, the tool defaults to HTTP.
4035

41-
```shell
42-
sudo apt update
43-
```
36+
You can add `--scheme https` to subcommands such as `setup`, `enable`, `enable-only`, or `disable` following the same pattern as the examples. See the linked documentation for the full command reference.
4437

45-
2. This command installs the `curl` package. `curl` is a command-line tool used to transfer data over networks and is required to download the Percona repository package.
38+
Starting in {{vers}}, the `mysql_native_password` plugin is no longer loaded by default. When the package manager may prompt you during installation (depending on the package and distribution), follow the choices and steps in [Configure authentication](#configure-authentication). If you choose legacy authentication but do not enable the plugin in configuration, clients may be unable to connect or the Percona Server service may fail to start.
4639

47-
```shell
48-
sudo apt install curl
49-
```
40+
??? note "Step-by-step: what each command does"
5041

51-
3. This command downloads the `percona-release_latest.generic_all.deb` file from the Percona APT repository. The `-O` option saves the file with the same name as in the URL.
42+
The following sections provide detailed explanations for each step:
5243

53-
```shell
54-
curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb
55-
```
44+
1. The `apt update` command shown below updates the package lists for upgrades and new package installations. `sudo` runs the command with superuser privileges; `apt update` resynchronizes the package index files from the sources configured in `/etc/apt/sources.list` and `/etc/apt/sources.list.d/`.
5645

57-
4. This command installs `gnupg2` (for package signature verification), `lsb-release` (for distribution information), and the downloaded Percona release package. Together they configure the Percona APT repository on your system.
46+
```shell
47+
sudo apt update
48+
```
5849

59-
```shell
60-
sudo apt install gnupg2 lsb-release ./percona-release_latest.generic_all.deb
61-
```
50+
2. The `sudo apt install -y curl` command installs the `curl` package. `curl` is a command-line tool used to transfer data over networks and is required to download the Percona repository package.
6251

63-
5. This command refreshes the package lists so the system recognizes the newly enabled Percona repository and the latest package versions.
52+
```shell
53+
sudo apt install -y curl
54+
```
6455

65-
```shell
66-
sudo apt update
67-
```
56+
3. The `curl -O` command shown below downloads the `percona-release_latest.generic_all.deb` file from the Percona APT repository. The `-O` option saves the file with the same name as in the URL.
6857

69-
6. This command enables the Percona Server for MySQL {{vers}} release repository. It configures `apt` to install packages from the Percona repository.
58+
```shell
59+
curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb
60+
```
7061

71-
```shell
72-
sudo percona-release enable-only {{pkg}} release
73-
```
62+
4. The `sudo apt install -y gnupg2 lsb-release ./percona-release_latest.generic_all.deb` command installs `gnupg2` (for package signature verification), `lsb-release` (for distribution information), and the downloaded Percona release package. Together, `gnupg2`, `lsb-release`, and the Percona release `.deb` configure the Percona APT repository on your system.
7463

75-
7. You can verify the repository setup by checking the Percona release list in `/etc/apt/sources.list.d/percona-original-release.list`.
64+
```shell
65+
sudo apt install -y gnupg2 lsb-release ./percona-release_latest.generic_all.deb
66+
```
7667

77-
8. This command installs the `percona-server-server` package. During installation, the package manager will prompt you to select the default authentication plugin; follow the [Configure authentication](#configure-authentication) section below.
68+
5. The `percona-release setup {{pkg}} --scheme https` command disables all current Percona repository locations on the system, then enables the release repositories that match Percona Server for MySQL {{vers}} for your distribution over HTTPS (see the [Percona Software Repositories :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/percona-release.html) documentation). Omit `--scheme https` only if you intentionally want HTTP repository URLs (the tool default).
7869

79-
```shell
80-
sudo apt install --scheme https percona-server-server
81-
```
70+
```shell
71+
sudo percona-release setup {{pkg}} --scheme https
72+
```
73+
74+
6. The `percona-release enable {{pkg}} release --scheme https` command turns on the Percona Server for MySQL release repository location with HTTPS URLs. Run `apt update` afterward so APT loads package indexes for that repository (including `percona-server-server` and related packages).
75+
76+
```shell
77+
sudo percona-release enable {{pkg}} release --scheme https
78+
sudo apt update
79+
```
80+
81+
7. You can verify the repository setup by inspecting the `.list` files under `/etc/apt/sources.list.d/` (for example `percona-original-release.list`, depending on your `percona-release` version).
82+
83+
8. The `sudo apt install -y percona-server-server` command installs the `percona-server-server` package. During installation, the package manager may prompt you to select the default authentication plugin (some builds use only debconf or post-install configuration); follow the [Configure authentication](#configure-authentication) section when a prompt or post-install step applies.
84+
85+
```shell
86+
sudo apt install -y percona-server-server
87+
```
8288

8389
### Configure authentication
8490

85-
During the installation process, the package manager will prompt you to select the default authentication plugin.
91+
During the installation process, the package manager may prompt you to select the default authentication plugin, or you may need to adjust authentication only after install—see your installer output and [Non-interactive installs and debconf](#non-interactive-installs-and-debconf) when automating.
8692

87-
!!! warning "Important Change in MySQL 8.4"
93+
!!! warning "Important change in {{vers}}"
8894

89-
Percona Server for MySQL 8.4 inherits the upstream change where the `mysql_native_password` plugin is **disabled by default**.
95+
Percona Server for MySQL {{vers}} inherits the upstream change where the `mysql_native_password` plugin is disabled by default.
9096

9197
=== "Option 1: Recommended (Strong Password Encryption)"
9298

93-
**Select this option if you are setting up a new server or using modern application drivers.**
99+
Select Option 1 if you are setting up a new server or using modern application drivers.
94100

95-
This uses the `caching_sha2_password` plugin, providing superior security and performance. No further configuration is required.
101+
The recommended option uses the `caching_sha2_password` plugin, providing superior security and performance. No further configuration is required.
96102

97103
=== "Option 2: Legacy (Native Password)"
98104

99-
**Select this option only if you must support legacy applications that cannot be updated.**
105+
Select Option 2 only if you must support legacy applications that cannot be updated.
100106

101-
If you choose this option, you **must** manually enable the plugin after installation, or the server will fail to authenticate users using this method.
107+
If you choose Option 2, you must manually enable the plugin after installation, or the server will fail to authenticate users who rely on native-password authentication.
102108

103109
1. Open your configuration file (e.g., `/etc/mysql/mysql.conf.d/mysqld.cnf`).
104110

105111
2. Add the following to the `[mysqld]` section:
106112
```ini
107113
[mysqld]
108-
mysql-native-password=ON
114+
mysql_native_password=ON
109115
```
110116

111117
3. Restart the service:
@@ -121,6 +127,52 @@ See [Configuring Percona repositories with `percona-release` :octicons-link-exte
121127

122128
After successful installation, see [Post-installation](post-installation.md) for detailed steps to configure and secure your Percona Server for MySQL installation.
123129

130+
## Non-interactive installs and debconf
131+
132+
Adding `-y` to `apt install` only skips APT confirmation prompts. The `percona-server-server` packages still run maintainer scripts that may ask debconf questions (for example the MySQL `root` password, whether to reuse an existing data directory, or lowercase table names, depending on your version and what is already on the disk).
133+
134+
To automate those prompts:
135+
136+
1. Discover the questions your package version uses. On a lab host, install once interactively or inspect templates, then run:
137+
138+
```shell
139+
sudo debconf-show percona-server-server
140+
```
141+
142+
Template definitions are also shipped with the package (paths such as `/var/lib/dpkg/info/percona-server-server.templates`).
143+
144+
Verify for each target: preseed names and choices can differ by distribution, point release, and `percona-server-server` package version. Re-run `debconf-show` after upgrades or when you change base image. For production automation, keep a short checklist (distro + package version → saved `debconf-show` output) so scripts stay aligned with what the package actually asks.
145+
146+
2. Preseed answers with `debconf-set-selections` before `apt install`. For the templates shipped with many Percona Server for MySQL {{vers}} packages, password prompts use the `percona-server-server/root-pass` and `percona-server-server/re-root-pass` names—for example:
147+
148+
```shell
149+
echo "percona-server-server percona-server-server/root-pass password choose-a-strong-secret" | sudo debconf-set-selections
150+
echo "percona-server-server percona-server-server/re-root-pass password choose-a-strong-secret" | sudo debconf-set-selections
151+
```
152+
153+
Other prompts (for example `percona-server-server/lowercase-table-names` or `percona-server-server/remove-data-dir`) appear only in some upgrade or edge-case paths—use `debconf-show` output to add matching lines. Do not commit real passwords to version control or broad shell history.
154+
155+
3. Optional: set `DEBIAN_FRONTEND=noninteractive` for the install so debconf does not try to open a UI. Noninteractive installs are usually combined with preseeding; without defaults for required questions, the configure step can still fail or leave the server in an unexpected state.
156+
157+
```shell
158+
sudo DEBIAN_FRONTEND=noninteractive apt install -y percona-server-server
159+
```
160+
161+
Default authentication plugin: if your distribution or package adds a debconf choice for the authentication plugin, that question shows up under `debconf-show` for `percona-server-server`. If the distribution or package does not add such a question, unattended installs still follow the same rules as an interactive install: use [Configure authentication](#configure-authentication) after the package is installed (for example `mysql_native_password=ON` in `my.cnf` when you need legacy auth).
162+
163+
See also
164+
165+
* [Telemetry](telemetry.md) — disable collection for package installs with `PERCONA_TELEMETRY_DISABLE=1` on the same `apt` command line.
166+
* [Authentication methods](authentication-methods.md) — options for `mysql_native_password`, `caching_sha2_password`, and related settings.
167+
* [Post-installation](post-installation.md) — secure and configure the server after packages are installed.
168+
* [Debian Wiki — debconf :octicons-link-external-16:](https://wiki.debian.org/debconf) — how debconf and preseeding work on Debian-derived systems.
169+
170+
## Unattended installations
171+
172+
For the same `apt` / `percona-release` sequence as in [Install Percona Server for MySQL using APT](#install-percona-server-for-mysql-using-apt), add `-y` to each `sudo apt install` line where you need non-interactive APT confirmations, and use non-interactive options for `percona-release` as in the following snippet.
173+
174+
--8<-- "install-flag.md"
175+
124176
## Install Percona Toolkit UDFs (Optional)
125177

126178
Percona Server for MySQL includes user-defined functions (UDFs) from [Percona Toolkit :octicons-link-external-16:](https://docs.percona.com/percona-toolkit/). These UDFs provide faster checksum calculations:
@@ -131,9 +183,9 @@ Percona Server for MySQL includes user-defined functions (UDFs) from [Percona To
131183

132184
* `murmur_hash`: High-performance hash function
133185

134-
User-Defined Functions (UDFs) are custom functions you can add to MySQL to extend its capabilities. These particular UDFs are useful for data integrity checks and performance monitoring.
186+
User-Defined Functions (UDFs) are custom functions you can add to MySQL to extend MySQL capabilities. The Percona Toolkit UDFs are useful for data integrity checks and performance monitoring.
135187

136-
To install these functions after installation:
188+
To install the Percona Toolkit UDFs after installation:
137189

138190
```{.sql data-prompt="mysql>"}
139191
INSTALL COMPONENT 'file://component_percona_udf';
@@ -145,16 +197,16 @@ INSTALL COMPONENT 'file://component_percona_udf';
145197
Query OK, 0 rows affected (0.01 sec)
146198
```
147199

148-
You can now use these functions in your SQL queries. For example: `SELECT fnv_64('test_string');`
200+
You can now use the UDFs in your SQL queries. For example: `SELECT fnv_64('test_string');`
149201

150-
For detailed information about these functions, see [Percona Toolkit UDF functions](udf-percona-toolkit.md).
202+
For detailed information about the UDFs, see [Percona Toolkit UDF functions](udf-percona-toolkit.md).
151203

152204
## Install the Percona testing repository using APT
153205

154-
Percona offers pre-release builds from the testing repository. As a superuser, run `percona-release` with the `testing` argument to enable it:
206+
Percona offers pre-release builds from the testing repository. As a superuser, run `percona-release` with the `testing` argument to enable the testing repository:
155207

156208
```shell
157-
sudo percona-release enable {{pkg}} testing
209+
sudo percona-release enable {{pkg}} testing --scheme https
158210
```
159211

160212
Do not run testing repository builds in production. The build may not contain all the features available in the final release and may change without notice.

‎docs/quickstart-apt.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,13 @@ Do the following steps to install the server:
4040
4. Set up the Percona Server for MySQL 8.4 repository:
4141

4242
```shell
43-
sudo percona-release setup {{pkg}}
43+
sudo percona-release setup {{pkg}} --scheme https
4444
```
4545

4646
5. Enable the Percona Server for MySQL release repository:
4747

4848
```shell
49-
sudo percona-release enable {{pkg}} release
49+
sudo percona-release enable {{pkg}} release --scheme https
5050
sudo apt update
5151
```
5252

@@ -56,13 +56,13 @@ Do the following steps to install the server:
5656
sudo apt install -y percona-server-server
5757
```
5858

59-
During installation, you will be prompted to:
59+
During installation, you may be prompted to:
6060

6161
* Enter a root password (use `secret` for these examples, or choose your own)
6262

6363
* Confirm the password
6464

65-
* Choose authentication method (Strong password encryption recommended)
65+
* Choose an authentication method, if the installer asks (Strong password encryption recommended)
6666

6767
7. [Optional] Secure the installation:
6868

0 commit comments

Comments
 (0)