Directory Password Protection

Directory password protection lets you restrict access to a folder on your site. When enabled, visitors browsing to that folder are prompted by their browser for a username and password before any file inside the folder is served.

This is the same mechanism used by cPanel's "Directory Privacy" feature and is the standard HTTP Basic Authentication built into every browser.

Common Use Cases#

• Protecting an admin or staging area (/admin, /staging)
• Restricting access to a development version of your site
• Hiding internal documentation or files from public crawlers
• Adding a quick second layer of authentication on top of an application's own login

How It Works#

Opterius stores your usernames and password hashes in a system-wide htpasswd file at /etc/opterius/htpasswd/{domain}/{path}. This file is not inside your web root, so it can never be accessed directly by visitors.

When a request arrives for a protected directory:

• Apache mode (.htaccess enabled): Apache reads the .htaccess file inside the protected directory, which references the htpasswd file. Apache prompts for credentials before serving anything.
• Nginx direct mode (default): Nginx serves the file. The agent generates an auth_basic location block in a per-domain include file. Nginx prompts for credentials before serving anything.

In both modes, the same htpasswd file is used. The password format is APR1 (md5_crypt) which both Apache and Nginx accept.

Setting Up Protection#

1. Open the Security → Directory Protection page in the sidebar.
2. Find the domain you want to protect and click + Add protected directory.
3. Enter:
   • Path: relative to your public_html (e.g. admin, wp-admin, private/files).
   • Realm label (optional): the message shown in the browser prompt (e.g. "Restricted Area").
   • Username and Password: the first user that will be allowed to access the directory.
4. Click Create.

The directory is now protected. Try visiting it in your browser to verify — you should see an authentication prompt.

Adding More Users#

You can add as many usernames as you want to the same protected directory. Each user has their own password.

1. Find the protected directory in the list.
2. Use the inline form at the bottom (username + password) to add another user.
3. Click Add user.

Removing a User#

Each user in the list has a small remove link next to their name. Click it to remove that user.

If you remove the last user from a protected directory, the entire protection is removed automatically.

Removing Protection from a Directory#

Click Remove protection at the top of any protected directory card. This deletes the htpasswd file, removes the .htaccess rules (if in Apache mode), and updates the Nginx include file.

The directory becomes publicly accessible again immediately.

Security Notes#

• Use strong passwords. HTTP Basic Authentication transmits credentials in base64 — which is not encrypted. Always use HTTPS for any directory you protect with passwords. Opterius generates SSL certificates automatically via Let's Encrypt.
• Browser-based protection only. Directory protection blocks browser access. It does not protect files from being accessed by other server-side processes or by direct file system access. If you need to protect data from PHP scripts, use application-level access control instead.
• Hashed storage. Passwords are never stored in plaintext. They are hashed with crypt(APR1) and stored only in the htpasswd file.

Troubleshooting#

The browser prompt does not appear. Check that the directory exists in your public_html. Opterius will create it if missing, but if there is a typo in the path, the protection rules will not match the actual directory.

I can still access the directory after enabling protection. Clear your browser's cached credentials or try in an incognito window. Browsers cache HTTP Basic credentials for the duration of the session.

I get a 500 Internal Server Error. This usually means Apache could not read the htpasswd file. Check the error log for your domain at /home/{user}/{domain}/logs/error.log. The most common cause is incorrect file permissions, which Opterius normally handles automatically — re-saving the protection from the panel will fix it.

The protected files inside the directory return PHP code instead of executing. The Nginx include file declares a PHP location handler inside the protected location. If you removed and re-added the protection but PHP files still don't run, ask the support team to inspect the per-domain include file at /etc/nginx/opterius-includes/{domain}-dirs.conf.