GoAdmio

directory

Password-protect a directory with HTTP Basic authentication, or remove the protection

On this page: Overview · Quick start · Syntax · Arguments · Output · Examples · Troubleshooting · Details · See also


Overview

/go/directory puts a username and password in front of a folder on a website. Visitors must log in before they can see anything in it. It uses Apache's Basic authentication, which relies on two files in the folder:

It also records the protected folder in the GoAdmio database, and it can remove the protection again.

[!WARNING] The command replaces any existing .htaccess file in the folder, and removing the protection deletes that file entirely. Rules such as URL rewrites (used by WordPress and other CMSs) are lost. Back up the folder's .htaccess first.

This command does not turn directory listings on or off. To change which index files the server looks for in every folder, such as index.html, use directoryindex.


Quick start

# Protect a folder with one login
/go/directory example.com /home/example.com/www/private editor S3cure_Pass9

# Remove the protection
/go/directory example.com /home/example.com/www/private delete

Syntax

# Protect a directory
/go/directory <account> <directory> <user> <password>

# Remove the protection
/go/directory <account> <directory> delete

Run the command as root.


Arguments

Position Argument Required Notes
1 <account> Yes The GoAdmio account username, not the domain name (although the two are the same by default). It is only stored in the database.
2 <directory> Yes The full path of the folder, such as /home/example.com/www/private. It must already exist.
3 <user> Yes The login name visitors will type. The word delete removes the protection instead, so it can't be used as a login name.
4 <password> To protect The login password. Not used with delete.

Avoid spaces, quotes, and shell or SQL special characters ($ & ; | ' ") in the directory, user, and password. They are used without quoting and can break the command.


Output

Message Meaning
Adding password for user <user> Printed by htpasswd when the login is created.
Directory <directory> has been protected The folder is now password-protected.
Directory privacy has been deleted The protection was removed.
No output The directory doesn't exist. Nothing was changed.

The command exits with status 0 in every case, so don't rely on the exit status. Check the message, or test the site.


Examples

# Protect a folder, then check that the server asks for a login (expect 401)
/go/directory example.com /home/example.com/www/private editor S3cure_Pass9
curl -I https://example.com/private/
# Back up an existing .htaccess before protecting the folder
cp -a /home/example.com/www/private/.htaccess /root/htaccess.private.bak
/go/directory example.com /home/example.com/www/private editor S3cure_Pass9
# Add a second login without replacing the first
sudo htpasswd -b /home/example.com/www/private/.htpasswd second_user An0ther_Pass
# Remove the protection
/go/directory example.com /home/example.com/www/private delete

Troubleshooting

Symptom Likely cause Fix
Nothing happens and nothing is printed The directory path doesn't exist. Check the path. Use the full path, starting with /home/.
Redirects or permalinks stopped working in the folder The existing .htaccess was overwritten. Restore your backup and add the four authentication lines to it by hand (see What it creates).
Only one person can log in The command recreates .htpasswd every time, so each run replaces the previous login. Add extra logins with htpasswd -b (without -c), as in the examples.
The login fails or the command errors with some passwords The password has special characters. Use letters, numbers, and underscores.
The folder is not protected The server runs Nginx, which ignores .htaccess unless GoAdmio's Nginx setup handles it. Or Apache isn't allowed to use .htaccess there. Check with curl -I. You should get 401 Unauthorized.
500 error after protecting a folder The path in .htaccess is wrong, or Apache can't read the files. Check /home/.../.htaccess and the Apache error log.
The Name column in the database is empty The script never sets a name. Expected.
The same folder is listed more than once Each protect run adds a new database row. Remove the protection first, then protect it again.

Details

What it creates

Protecting a directory writes these files inside it:

File Content
.htpasswd The login name and a hashed password, created with htpasswd -b -c.
.htaccess Four lines, shown below.
AuthName "Enter Password"
AuthType Basic
AuthUserFile <directory>/.htpasswd
Require valid-user

Both files are created by root, so they are owned by root.

What it does

flowchart TD
    A["directory account dir user pass"] --> B{"Directory exists?"}
    B -- "No" --> X["Do nothing, print nothing"]
    B -- "Yes" --> C{"user is delete?"}
    C -- "Yes" --> D["Delete .htaccess and .htpasswd"]
    D --> E["Delete the database row"]
    E --> F["Print Directory privacy has been deleted"]
    C -- "No" --> G["Create .htpasswd with the login"]
    G --> H["Write .htaccess"]
    H --> I["Insert a database row"]
    I --> J["Print Directory has been protected"]
  1. Appends the call to /var/log/go/directory.log.
  2. Checks that the directory exists. If it doesn't, the command ends silently.
  3. With delete: removes .htaccess and .htpasswd from the folder, deletes the folder's row from /var/lib/sqlite/directory.db, and prints the message.
  4. Otherwise: creates .htpasswd with the login (replacing any existing one), overwrites .htaccess, adds a row to directory.db, and prints the message.

What is stored

Each protected folder adds a row to the Directory table in /var/lib/sqlite/directory.db:

Column Value
Name Always empty.
Directory The folder path.
User The login name.
Pass The login password, in plain text.
Username The account username.
TimeStamp The time of the change, as a Unix timestamp.

Security

[!WARNING] The password appears in the process list while the command runs, and in your shell history. It is also saved unhashed in directory.db. Use a password that you don't use anywhere else.


See also

Command Description
directoryindex Show or set the default index files for the whole server (Apache DirectoryIndex and Nginx index)
permission Enable or disable FTP permissions for a domain
fix Fix GoAdmio file and folder permissions
create Create a GoAdmio account from the command line
delete Delete a GoAdmio account from the command line