Panel Hostname change rewrites Nginx to use /run/opterius-panel.sock, but installer does not create that PHP-FPM socket

[craigwileman]

Description

After a fresh Opterius installation, the panel works correctly using the standard PHP-FPM socket created by Ubuntu/PHP.

However, after configuring a custom Panel Hostname from within Opterius, the panel's Nginx configuration is rewritten to use:

/run/opterius-panel.sock

That socket does not exist on the server, causing the panel to immediately return:

502 Bad Gateway

The issue appears to be that the initial installer and the Panel Hostname/agent configuration paths disagree about which PHP-FPM socket the panel should use.

Environment

Opterius Agent: v2.9.17
OS: Ubuntu 24.04 amd64
PHP: 8.4
Web server: Nginx 1.24.0
Installation type: Fresh Opterius install

Installation was performed using the documented installer:

curl -sL https://get.opterius.com/install.sh -o /tmp/install.sh
bash /tmp/install.sh

The server hostname is:

node.example.com

The configured panel hostname is:

panel.example.com

Steps to reproduce

1. Provision a fresh Ubuntu 24.04 server.
2. Run the standard Opterius installer:

curl -sL https://get.opterius.com/install.sh -o /tmp/install.sh
bash /tmp/install.sh

3. Complete the initial Opterius setup and create the admin account.
4. Confirm the panel is operating correctly.
5. Navigate to the Panel Hostname configuration.
6. Configure a hostname such as:

panel.example.com

7. Ensure the hostname resolves correctly to the server and allow Opterius to complete the hostname/Let's Encrypt configuration.
8. Save the Panel Hostname.
9. Attempt to load the panel using the newly configured hostname.

Actual result

The panel starts returning:

502 Bad Gateway

Nginx itself remains healthy:

nginx: configuration file /etc/nginx/nginx.conf test is successful

The generated panel Nginx configuration contains:

location ~ \.php$ {
    fastcgi_pass unix:/run/opterius-panel.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_read_timeout 600;
    include fastcgi_params;
}

However:

/run/opterius-panel.sock

does not exist.

The Nginx error log consequently reports:

connect() to unix:/run/opterius-panel.sock failed (2: No such file or directory) while connecting to upstream

This was reproducible for all subsequent panel requests.

PHP 8.4 FPM itself is running normally:

php8.4-fpm.service loaded active running

Expected result

Changing the Panel Hostname should preserve a valid PHP-FPM upstream.

Either:

/run/php/php8.4-fpm.sock

should continue to be used, matching the initial installer configuration,

or the installer should create and configure a dedicated Opterius PHP-FPM pool that provides:

/run/opterius-panel.sock

If the intention is for the Opterius panel to run using a dedicated PHP-FPM pool, I would personally prefer that architecture, but the corresponding pool/socket currently does not appear to be created by the installer.

Installer investigation

I checked the current installer/install.sh.

For Debian/Ubuntu, the installer determines the panel PHP-FPM socket using:

if [[ "$PKG_MANAGER" == "apt" ]]; then
    FPM_SOCK="/run/php/php${PHP_VERSION}-fpm.sock"
else
    FPM_SOCK="/run/php-fpm/www.sock"
fi

The panel Nginx vhost is then generated using:

fastcgi_pass unix:${FPM_SOCK};

On this Ubuntu 24.04 installation running PHP 8.4, that resolves to:

/run/php/php8.4-fpm.sock

I also searched the installer for the following:

opterius-panel.sock
pool.d
php-fpm.d
listen.owner

and could not find any logic that creates a dedicated PHP-FPM pool or /run/opterius-panel.sock.

The initial installer therefore appears to intentionally use the standard PHP-FPM socket.

What appears to happen

The configuration flow appears to be:

Fresh installation
        │
        ▼
/run/php/php8.4-fpm.sock
        │
        │ Panel works correctly
        ▼
Configure Panel Hostname
        │
        ▼
Agent rewrites Nginx configuration
        │
        ▼
/run/opterius-panel.sock
        │
        │ Socket does not exist
        ▼
502 Bad Gateway

The Panel Hostname action is performed through the Opterius agent, so I suspect the hostname-change logic expects a dedicated opterius-panel PHP-FPM pool that is either:

1. no longer created by the installer,
2. planned but not yet implemented in the installer, or
3. inadvertently referenced by the hostname-change configuration.

Workaround

Changing:

fastcgi_pass unix:/run/opterius-panel.sock;

back to:

fastcgi_pass unix:/run/php/php8.4-fpm.sock;

and reloading Nginx resolves the problem immediately:

nginx -t && systemctl reload nginx

The panel then works correctly at the new hostname.

The generated vhost otherwise appears valid, including the newly issued Let's Encrypt certificate and the updated hostname.

The Laravel application URL was also successfully updated to:

APP_URL=https://panel.example.com:8443

Suggested resolution

It would be useful to confirm which PHP-FPM architecture is intended.

If the panel should use the system PHP-FPM pool, the Panel Hostname operation should retain the socket already configured by the installer, for example:

/run/php/php8.4-fpm.sock

If the panel is intended to use its own dedicated PHP-FPM pool, which would arguably provide better isolation, the installer should create something similar to:

/etc/php/8.4/fpm/pool.d/opterius-panel.conf

with a socket such as:

/run/opterius-panel.sock

and appropriate ownership, permissions and PHP-FPM configuration.

The important part is that the installer and the Panel Hostname/agent configuration should use the same PHP-FPM upstream.

Impact

This is potentially quite disruptive because configuring the Panel Hostname is a normal post-installation action.

The hostname and certificate configuration can appear to complete successfully, but immediately afterwards the administrator loses access to the entire panel with a 502 Bad Gateway.

Because the failure is caused by the generated Nginx upstream rather than DNS or SSL, an administrator may initially assume the hostname or certificate configuration failed when the actual issue is the missing PHP-FPM socket.