ProxySQL - openSUSE Package Notes
==================================
Official documentation: https://proxysql.com/documentation/
Release notes: https://github.com/sysown/proxysql/releases
Upstream wiki: https://github.com/sysown/proxysql/wiki
This document covers installation, initial configuration, and openSUSE-specific
considerations including SELinux and firewall setup.
CONTENTS
--------
1. Quick Start
2. Configuration
3. Starting and Managing the Service
4. Connecting to the Admin Interface
5. SELinux
6. Firewall (firewalld)
7. Log Files and Logrotate
8. Upgrading
------------------------------------------------------------------------
1. QUICK START
------------------------------------------------------------------------
After installation ProxySQL will NOT start automatically. You must
configure it and then enable the service yourself:
1. Review and edit the main configuration file:
/etc/proxysql.cnf
2. Enable and start the service:
systemctl enable --now proxysql.service
3. Connect to the admin interface to configure backends and users:
mysql -u admin -padmin -h 127.0.0.1 -P 6032 \
--prompt='ProxySQL Admin> '
IMPORTANT: The default admin credentials (admin/admin) MUST be changed
before exposing ProxySQL to any network. See section 2 for details.
------------------------------------------------------------------------
2. CONFIGURATION
------------------------------------------------------------------------
Main configuration file: /etc/proxysql.cnf
Data directory: /var/lib/proxysql/
Log directory: /var/log/proxysql/
On FIRST startup ProxySQL reads /etc/proxysql.cnf and initialises its
SQLite database at /var/lib/proxysql/proxysql.db. On SUBSEQUENT starts
that database is used directly, and proxysql.cnf is ignored.
To force a full re-initialisation from the config file (e.g. after a
manual edit) use the companion one-shot unit:
systemctl start proxysql-initial.service
WARNING: this deletes the existing database. Back it up first.
Default network ports
6033 MySQL/MariaDB proxy (where application clients connect)
6032 Admin interface (never expose publicly; 127.0.0.1 only)
6070 Web stats / REST API (optional; disabled by default in config)
Changing the admin credentials (do this immediately after first start):
Connect to the admin interface, then:
UPDATE global_variables
SET variable_value = 'newadmin:newpassword'
WHERE variable_name = 'admin-admin_credentials';
LOAD ADMIN VARIABLES TO RUNTIME;
SAVE ADMIN VARIABLES TO DISK;
Extra startup flags (e.g. --idle-threads, --reuseport) can be set via
the PROXYSQL_OPTS variable in:
/etc/sysconfig/proxysql
------------------------------------------------------------------------
3. STARTING AND MANAGING THE SERVICE
------------------------------------------------------------------------
Enable and start at boot:
systemctl enable --now proxysql.service
Stop:
systemctl stop proxysql.service
Reload without dropping connections (most config changes can be applied
live from the admin interface instead -- see section 4):
systemctl restart proxysql.service
Re-initialise from /etc/proxysql.cnf (overwrites the SQLite database):
systemctl start proxysql-initial.service
Check status:
systemctl status proxysql.service
Follow the journal in real time:
journalctl -u proxysql.service -f
------------------------------------------------------------------------
4. CONNECTING TO THE ADMIN INTERFACE
------------------------------------------------------------------------
ProxySQL exposes a MySQL-protocol admin socket on 127.0.0.1:6032.
Connect with any MySQL client:
mysql -u admin -padmin -h 127.0.0.1 -P 6032
Useful admin queries:
SHOW TABLES;
SELECT * FROM mysql_servers;
SELECT * FROM mysql_users;
SELECT * FROM stats_mysql_query_digest
ORDER BY sum_time DESC LIMIT 10;
After making changes always apply and persist them:
LOAD MYSQL SERVERS TO RUNTIME; SAVE MYSQL SERVERS TO DISK;
LOAD MYSQL USERS TO RUNTIME; SAVE MYSQL USERS TO DISK;
LOAD MYSQL QUERY RULES TO RUNTIME; SAVE MYSQL QUERY RULES TO DISK;
The full list of LOAD/SAVE targets is in the upstream docs at:
https://proxysql.com/documentation/
------------------------------------------------------------------------
5. SELINUX
------------------------------------------------------------------------
openSUSE Leap 16.0 and later ship with SELinux (targeted policy) present
in the base system. The following describes how this package integrates
with it.
WHAT THE PACKAGE DOES AUTOMATICALLY AT INSTALL TIME
The %post scriptlet (conditional on selinuxenabled returning true):
a) Runs restorecon on all installed paths so files carry the correct
context from the active policy:
/usr/sbin/proxysql
/etc/proxysql/
/var/lib/proxysql/
/var/log/proxysql/
/usr/lib/systemd/system/proxysql*.service
b) Labels ProxySQL's three non-standard TCP ports if they are not yet
assigned by the running policy:
6033 -> mysqld_port_t (MySQL proxy listener)
6032 -> mysqld_port_t (admin interface)
6070 -> http_port_t (web stats)
These operations require policycoreutils (restorecon) and
python3-policycoreutils (semanage), both listed as Recommends.
At uninstall time the three port labels are removed.
IMPORTANT NOTE ON PROCESS CONFINEMENT
This package does NOT currently ship a dedicated type-enforcement (.te)
policy module. ProxySQL therefore runs in the default init daemon
domain provided by the base selinux-policy (typically a permissive or
unconfined variant until a dedicated module is added). File contexts
and port labels are set correctly, but full per-process MAC confinement
is not yet enforced. A dedicated proxysql.te module is planned.
CHECKING WHETHER SELINUX IS BLOCKING PROXYSQL
If ProxySQL fails to start or misbehaves, check for AVC denials first:
# Summary with explanations
ausearch -c proxysql --raw | audit2why
# Full denial log (recent entries)
ausearch -m avc -ts recent
# Current enforcement mode
getenforce
TEMPORARILY PERMITTING PROXYSQL TO COLLECT DENIALS
Put the system in permissive mode to let ProxySQL run while you gather
the denials you need to build a policy (NOT for production use):
setenforce 0 # reverts on next reboot
GENERATING A LOCAL ALLOW MODULE FROM OBSERVED DENIALS
Once you have AVC denials in the audit log:
ausearch -c proxysql --raw | audit2allow -M proxysql-local
# REVIEW proxysql-local.te before loading
semodule -i proxysql-local.pp
To remove the local module later:
semodule -r proxysql-local
CUSTOM BACKEND PORTS
If your MySQL or PostgreSQL backends run on non-standard ports, label
them so SELinux permits outbound connections from ProxySQL:
# MySQL backend on a non-standard port
semanage port -a -t mysqld_port_t -p tcp 3307
# PostgreSQL backend on a non-standard port
semanage port -a -t postgresql_port_t -p tcp 5433
CUSTOM PROXYSQL LISTENER PORTS
If you configure ProxySQL to listen on different ports than the
defaults, label them before starting the service:
semanage port -a -t mysqld_port_t -p tcp <proxy_port>
semanage port -a -t mysqld_port_t -p tcp <admin_port>
semanage port -a -t http_port_t -p tcp <web_port>
If the port is already assigned to another type, use -m instead of -a:
semanage port -m -t mysqld_port_t -p tcp <port>
semanage is provided by the python3-policycoreutils package.
RELABELLING AFTER AN UPGRADE
If a package upgrade changes file paths or contexts, re-run restorecon:
restorecon -Rv \
/usr/sbin/proxysql \
/etc/proxysql/ \
/var/lib/proxysql/ \
/var/log/proxysql/
------------------------------------------------------------------------
6. FIREWALL (firewalld)
------------------------------------------------------------------------
ProxySQL's ports are NOT opened in the firewall automatically.
Open the MySQL proxy port for application clients:
firewall-cmd --permanent --add-port=6033/tcp
firewall-cmd --reload
The admin interface (6032) should stay bound to 127.0.0.1 only and
must NOT be opened in the firewall on internet-facing hosts.
If the web stats endpoint is enabled and must be accessible remotely:
firewall-cmd --permanent --add-port=6070/tcp
firewall-cmd --reload
------------------------------------------------------------------------
7. LOG FILES AND LOGROTATE
------------------------------------------------------------------------
ProxySQL writes its log to:
/var/log/proxysql/proxysql.log
The logrotate configuration is at:
/etc/logrotate.d/proxysql
To increase log verbosity, set in the admin interface:
UPDATE global_variables
SET variable_value = '7'
WHERE variable_name = 'mysql-eventslog_default_log';
LOAD MYSQL VARIABLES TO RUNTIME;
Startup and crash information is also available via systemd journal:
journalctl -u proxysql.service --since today
------------------------------------------------------------------------
8. UPGRADING
------------------------------------------------------------------------
ProxySQL persists its entire runtime configuration in the SQLite database
at /var/lib/proxysql/proxysql.db. A package upgrade will NOT overwrite
this file; your running configuration survives the upgrade intact.
Recommended upgrade procedure:
1. Back up the database:
cp /var/lib/proxysql/proxysql.db \
/var/lib/proxysql/proxysql.db.$(date +%Y%m%d)
2. Upgrade the package:
zypper update proxysql
3. Restart the service:
systemctl restart proxysql.service
4. Verify normal operation, then remove old backups when satisfied.
If the upgrade involves port or file-context changes, the %post scriptlet
will relabel files and re-apply port labels automatically (when SELinux is
enabled). You can also run restorecon manually as described in section 5.