HF PanelDocsv1.0.0

Troubleshooting

Common problems on an HF Panel server — the panel, sign-in, SSL, email, DNS, websites and services — and how to fix them.

Start with the server's own checks, then find your problem below.

bash
hf-panel health              # services, configuration, disk, memory, SSL, clock, mail queue
hf-panel dns-setup --check   # the DNS records, as public DNS sees them
hf-panel portals             # each panel's address, DNS and SSL

Server Admin › Server › Server health checks more (DNS, reverse DNS, blocklists, updates, backups) and has a one-click fix for many items. Server Admin › Server › Services shows every service's state and restarts it.

For problems during the installation itself, see Troubleshoot the installation.

The panel

I can't open the panel

  • Use the address with the port: https://server.yourdomain.com:8443. Without the port, the name goes to your website.
  • Check that port 8443 is open in your provider's cloud firewall as well as on the server (ufw status).
  • Check that the name points at the server: hf-panel portals.

The panel shows "502 Bad Gateway", or nothing loads

The panel program (hf-api) is stopped, or Nginx can't reach it.

bash
systemctl status hostfog-api --no-pager      # running? restarting in a loop?
journalctl -u hostfog-api -n 50 --no-pager   # the reason is at the end
/usr/local/hostfog/bin/hf-api restart        # restart it

If it doesn't come back:

  1. The settings file. A JSON mistake in /etc/hostfog/config.json after a hand edit stops the panel. python3 -m json.tool /etc/hostfog/config.json names the line. Fix it, or change settings with hf-api config set, which never writes broken JSON.
  2. Nginx. Run nginx -t, then tail /var/log/nginx/error.log. Permission denied on api.sock means the socket's permissions are wrong: run the update again from the release folder, which rewrites the service. No such file means hf-api isn't running. Connection refused is cured by the restart above.
  3. The database is locked. database is locked in the journal means another process is using the panel database, such as a long nightly job or a restore. Wait for it to finish (fuser /var/lib/hostfog/hostfog.sqlite shows which).
  4. The disk is full. df -h /. Free space; old copies in /var/lib/hostfog/panel-backups/ and customers' backup folders are the usual places to look.

"Server is busy, try again"

Another job holds the panel's lock for longer than 5 minutes: a big backup, a restore, an account move or an update. Let it finish. To see what holds it:

bash
ps -eo pid,etime,cmd | grep '[h]f-agent'

A command that has been there for hours with no child process is stuck: stop it with kill <pid>, then run the job again from the panel.

Everyone was signed out / the session folder is full

The panel removes idle sign-in sessions every 10 minutes. If thousands of sess_* files build up in /var/lib/hostfog, the folder's permissions are wrong. Fix them:

bash
chown hostfog:hostfog /var/lib/hostfog /var/lib/hostfog/sess_*
chmod 700 /var/lib/hostfog

Signing in

I forgot my password

On the server:

bash
hf-panel reset-password <username>

Customers and resellers can also use Forgotten your password? on the sign-in page.

I lost my phone (two-factor login)

bash
hf-panel reset-2fa <username>

Then sign in with the password and switch two-factor login on again.

Someone can't sign in on a panel's address

Each panel has its own sign-in, and only the people it is for can sign in there. Customers sign in at panel.yourdomain.com:8443, resellers at reseller.yourdomain.com:8443, administrators at server.yourdomain.com:8443.

The panel is locked

The licence isn't valid. Open Server Admin › Billing › Licence for the reason. Websites, email and DNS keep running. See Licensing.

SSL certificates

The panel shows a certificate warning

The name didn't point at the server when the certificate was made. Once the DNS is right, the real certificate is installed by itself within 5 minutes. To ask for it now:

bash
hf-panel ssl-now

Check that port 80 is open, too: Let's Encrypt checks the server over HTTP.

A customer's domain has no SSL

Open Domains › SSL/TLS in that customer's Control Panel (use Log in on the account). It shows why AutoSSL is still waiting: usually the domain (or www) doesn't point at the server yet, or port 80 is closed. AutoSSL tries again by itself. Details: /var/log/hostfog-autossl.log.

A DNS provider proxies the panel names

If your DNS provider proxies web traffic, set the server's names to DNS only. Ports 8443 and 2087, mail and FTP don't pass through a web proxy.

Email

Email goes to spam

  1. Set the reverse DNS (PTR) of the server's IP to your mail server name, mail.yourdomain.com, at your server provider. Servers that still have mx. or smtp.yourdomain.com there must change it.
  2. Check Server Admin › Email › Mail health (customers: Email › Deliverability) until SPF, DKIM and DMARC are green.
  3. Check that the server's IP isn't on a blocklist: Mail health shows it.

Mail isn't delivered at all

  • Your provider may block outgoing port 25. Ask them to open it.

  • Look at the mail log and the queue:

    bash
    tail -n 100 /var/log/mail.log
mailq

  • Server Admin › Email › Mail delivery log shows what happened to each message and what the other server said.

Incoming mail doesn't arrive

  • Check the domain's MX record points at mail.yourdomain.com, and that mail.yourdomain.com points at the server.
  • Check port 25 is open in your provider's firewall.

Mail apps can't connect

Mail apps use imap.yourdomain.com (IMAP 993, POP3 995) and smtp.yourdomain.com (587 STARTTLS, 465 SSL/TLS), with the full email address as the login. Check those names point at the server, and ports 465, 587, 993 and 995 are open. To recreate the automatic set-up files: hf-panel mail-autoconfig.

DNS

Which DNS records do I still need?

bash
hf-panel dns-setup           # the list
hf-panel dns-setup --check   # marks the ones public DNS doesn't show yet

A customer's domain doesn't resolve

  • If it uses your nameservers, check the registrar has ns1. and ns2.yourdomain.com, and that your glue records exist.
  • If its DNS is elsewhere, the Control Panel's DNS setup page shows which records to add there.
  • Port 53 (TCP and UDP) must be open for your DNS server.

Websites

Websites are down but the panel works

bash
nginx -t
apache2ctl configtest
systemctl status 'php*-fpm' --no-pager

Apache won't start

bash
hf-panel apache-fix

It repairs the usual causes (a port clash, missing log folders, leftover sites) and, if Apache still can't start, prints its real error.

A website shows "500 Internal Server Error"

Look at the website's error and PHP error logs in /home/<user>/logs/, or under Websites › Logs in the Control Panel. Usually it is a mistake in .htaccess or the site's PHP code.

A scheduled job didn't run

Look at /var/log/hostfog-cron.log, check that cron runs (systemctl status cron), and that /etc/cron.d/hostfog exists.

Getting help

When you contact support, send:

  • the system: cat /etc/os-release
  • the HF Panel version: cat /etc/hostfog/VERSION
  • the last 100 lines of journalctl -u hostfog-api
  • the log lines that match the problem (see Logs)
  • what was done just before

Remove passwords first. Contact us.