Quick and dirty NGINX directory listing behind login and HTTPS

This guide explains how to set up a simple NGINX autoindex directory listing page behind HTTP digest authentication and a self-signed HTTPS certificate. The goal is to set up a "poor man's" directory listing with minimal dependencies and bare minimum authentication and HTTPS features.

The NGINX autoindex is a very simple web page generated by NGINX that presents files and folders located in the server's filesystem, like a very simple file manager. But there is no upload ability and no in-browser preview features. For a fully fletched file manager solution, look elsewhere. The advantage of the autoindex, however, is the extreme simplicity and having no external dependencies.

The solution shown here should only be considered for personal use. It will not meet the expectation of general users. The self-signed HTTPS certificate will produce a warning in the browser and the HTTP digest login is very primitive without the ability to manage users or even to log out again.

Setup guide

Install NGINX if not already installed:

  • sudo apt install nginx

Prepare a folder for the files related to the page, and cd into it. Let's name the page quickdir:

  • sudo mkdir -p /var/www/quickdir
  • cd /var/www/quickdir

Specify the login credentials using the following printf one-liner that will ask for username and password and make a htpasswd file. The one-liner needs to run fully as root, hence sudo su:

  • sudo su
  • printf "`read -p Username:\ ; echo $REPLY`:`openssl passwd -apr1`\n" >> htpasswd
  • exit

This command makes the self-signed certificate, without password protection:

  • sudo openssl req -x509 -newkey rsa:4096 -keyout self-signed.key -out self-signed.crt -sha256 -days 365 -nodes

It's good practice to have a conf file with up-to-date SSL settings. The following is a reduced version of the conf file in Digital Ocean's guide.

  • sudo nano ssl-params.conf and enter:
ssl_protocols TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_dhparam /etc/nginx/dhparam.pem; 
ssl_ecdh_curve secp384r1;
ssl_session_timeout  10m;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
# Disable strict transport security for now. You can uncomment the following
# line if you understand the implications.
#add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";

This SSL configuration requires a dhparam.pem file for perfect forward secrecy. Make it with the following command, and a bit of patience! It takes a while:

  • sudo openssl dhparam -out /etc/nginx/dhparam.pem 4096

Finally, let's make a symlink to the folder to be shared. In this example, let's expose a tmp folder in the user's home dir:

  • sudo ln -s /home/lars/tmp quickdir

At this point there should be the following files in /var/www/quickdir:

/var/www/quickdir$ ls -la
total 24
drwxr-xr-x 2 root root 4096 Nov  6 11:52 .
drwxr-xr-x 4 root root 4096 Nov  6 11:30 ..
-rw-r--r-- 1 root root   86 Nov  6 12:02 htpasswd
lrwxrwxrwx 1 root root   14 Nov  6 11:52 quickdir -> /home/lars/tmp
-rw-r--r-- 1 root root 1939 Nov  6 11:45 self-signed.crt
-rw------- 1 root root 3268 Nov  6 11:44 self-signed.key
-rw-r--r-- 1 root root  570 Nov  6 11:45 ssl-params.conf

It's time to make the NGINX server block for the page:

  • sudo nano /etc/nginx/sites-available/quickdir and enter:
server {
    listen 443 ssl;
    listen [::]:443 ssl;

    ssl_certificate /var/www/quickdir/self-signed.crt;
    ssl_certificate_key /var/www/quickdir/self-signed.key;
    include /var/www/quickdir/ssl-params.conf;

    location /quickdir/ {   
        auth_basic            "Quickdir Access";
        auth_basic_user_file  /var/www/quickdir/htpasswd;
        root /var/www/quickdir/; 
        autoindex on;

Enable it by a symlink in the sites-available folder:

  • cd /etc/nginx/sites-enabled
  • sudo ln -s /etc/nginx/sites-available/quickdir .

And we are ready to test and reload the nginx configuration. If the nginx -t command presents errors, fix them before reloading nginx.

  • sudo nginx -t
  • sudo service nginx reload

Open a browser and access the page from the following URL: https://localhost/quickdir/ Remember the final / and https. There are no redirection conveniences here.

Permission issues

If the browser reports 403 Forbidden at this point, despite entering the correct login credentials, there is a permission issue accessing the files.

Let's take a look in the nginx error log:

2022/11/06 12:04:00 [error] 23959#23959: *4 "/var/www/quickdir/quickdir/index.html" is forbidden (13: Permission denied), client:, server: , request: "GET /quickdir/ HTTP/1.1", host: "localhost"

If we take a close look at /var/www/quickdir/quickdir, which is the same as /home/lars/tmp due to the symlink, we see:

$ ls -la /home/lars/tmp
total 1016
drwxrwxr-x  4 lars lars   4096 Nov  1 18:11 .
drwxr-x--- 41 lars lars   4096 Nov  6 10:44 ..
-rw-rw-r--  1 lars lars      0 Nov  6 12:07 some-file.txt

The tmp folder: . is executable and readable by other users: r-x, but the parent folder: .. is not. Thus NGINX fails when it tries to access the folder using the default www-data user.

One solution is to set the necessary permissions for other users to access the full path leading to the tmp folder. Note that both read and executable bits are necessary to enter directories. In this case it was only necessary to modify the parent folder:

  • sudo chmod 755 /home/lars

Refresh the browser, and things should be working.

I hope you enjoyed this content!

ko-fi donate


Comments powered by Talkyard