Troubleshooting

Start with the logs: most problems leave a line there that names the cause. Run the commands below as root (sudo -i).

Configuration files lists the others.

The panel does not open#

1. Use the right address: the host name and the port, https://panel.example.com:8083. Without the port you reach the web server of the sites, not the panel.

2. Check the service:

   Copy

   systemctl status arcpanel
   systemctl restart arcpanel
   

   arcpanel.service runs the panel's own NGINX and PHP-FPM. An error page instead of the sign-in page usually means its PHP-FPM is down; the restart brings it back.

3. Check the firewall of your provider: some providers filter ports in their own firewall. Allow TCP 8083 there.

4. Check whether your address is banned after failed sign-ins; see the next section.

You cannot sign in#

• Your address is banned. After five failed sign-ins Fail2Ban bans the address in the ARCPANEL chain, and the panel stops answering from it. From another address or the provider's console:

  Copy

  v-list-firewall-ban
  v-delete-firewall-ban 198.51.100.7 ALL
  

• You forgot the password. Set a new one on the server; without a password the command asks for it:

  Copy

  v-change-user-password arcadmin
  

• You lost the authenticator of two-factor authentication. Use Forgot Token on the sign-in page with the 2FA reset code (First login), or turn it off on the server with v-delete-user-2fa arcadmin.

• The account is not allowed to log in. Do not allow user to log in to Control Panel or the IP allow list on the user's Security tab refuse the sign-in; an administrator changes them.

A certificate is not issued#

Let's Encrypt checks each name of the certificate over the internet, so:

• every name, the domain and each alias such as www, needs an A record that points to this server; check with dig +short example.com;
• port 80 must be open from the internet, also when the site uses HTTPS;
• a wildcard alias (*.example.com) is checked through DNS, so the domain's zone must be on this server;
• Let's Encrypt allows five certificates for the same names per week; after a run of failures, wait an hour before you try again.

The reason is in /var/log/arcpanel/LE-<user>-<domain>.log. Remove the aliases that do not point here yet, issue the certificate, and add them later. Renewals run each night for certificates with less than 31 days left.

v-add-letsencrypt-domain alice example.com www.example.com

A site shows an error#

For a Node.js or Docker app, open the app's Logs tab: an app that exits at start shows the reason there. It must listen on 127.0.0.1 on its port.

When the configuration of a domain is broken, for example after a template was edited, write it again:

v-rebuild-web-domains alice

Mail is not sent or not received#

• Outgoing mail does not arrive: many providers block port 25 for new servers. Check with telnet gmail-smtp-in.l.google.com 25 from the server; if it does not connect, ask your provider to open it, or send through a relay (Mail).
• Mail goes to spam: publish the records of the mail domain's DNS Records page (SPF, DKIM, DMARC), and set a reverse DNS (PTR) record for the server's address at your provider, with the panel's host name.
• Incoming mail does not arrive: the domain's MX record must point to this server. A sender's error message names the reason; the server's side is in /var/log/exim4/mainlog.
• A user cannot read mail: check the mailbox password and the quota on its General tab, and /var/log/dovecot.log.
• A mailbox stopped sending: it reached its Rate Limit of messages per hour; a high count often means a stolen password.

A backup fails#

The owner gets an e-mail with the reason, and /var/log/arcpanel/backup.log has the details. The usual causes:

• Not enough disk space: a backup needs about twice the size of the account free in /backup.
• The server is busy: backups wait while the load average is at or above the number of CPU cores, and run later.
• The remote host refuses the upload: check its address, user and password in Server › Configure › Backups.

The disk is full#

v-list-sys-disk-status
du -xh --max-depth=1 /home /backup /var/log | sort -h | tail

Old backup archives, logs and mail of large mailboxes are the usual suspects. Lower Backups in the packages to keep fewer archives, and give users disk quotas (Disk Quota under Plugins).

A command or a change fails#

The panel shows the message of the failed command; /var/log/arcpanel/error.log keeps each failure with its exit code. Exit codes says what each code means. A service that does not restart after a change (E_RESTART) names its configuration error in its own log:

v-list-sys-services
journalctl -u nginx -n 50

After an update#

Automatic updates install patch releases at night and write /var/log/arcpanel/autoupdate.log. Check the version and the state of the services:

v-list-sys-info
v-list-sys-services

If the configuration of a user's objects looks wrong after an update, v-rebuild-user alice writes it again.

Still stuck?#

Note what you did, the message you saw and the lines of the logs above, then ask for support.