Directory Lister 5.8.1

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick Directory Lister 5.8.1 on Ubuntu 24.04 as the software version, select your Region, and choose Launch through EC2.

Choose m5.large, your key pair and a security group as above. Directory Lister is very light, so a smaller instance is fine for a small listing. Give the instance enough disk for the files you will serve, or attach a separate EBS volume for them (Step 7).

With the AWS CLI (replace the values in angle brackets):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=directory-lister}]'

• Directory Lister 5.8.1 on Ubuntu 24.04: SSH user ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

First boot takes a few seconds. After that, nginx, PHP and the first boot unit are active:

systemctl is-active nginx php8.3-fpm directory-lister-firstboot

active active active

nginx serves ports 80 and 443. PHP listens on a local socket only, and there is no database, so the only open ports are 22, 80 and 443:

sudo ss -tlnp | awk 'NR==1 || /nginx|sshd|php/' | awk '{print $1, $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g'

State Local Peer LISTEN 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx")) LISTEN 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx")) LISTEN 0.0.0.0:22 users:(("sshd"),("systemd")) LISTEN [::]:443 users:(("nginx"),("nginx"),("nginx")) LISTEN [::]:80 users:(("nginx"),("nginx"),("nginx")) LISTEN [::]:22 users:(("sshd"),("systemd"))

grep -m1 -oE "'pretty_version' => '[0-9.]+'" /var/www/directory-lister/files/.directory-lister/app/vendor/composer/installed.php php -v | head -1

'pretty_version' => '5.8.1' PHP 8.3.6 (cli) (built: Oct 19 2026 15:16:58) (NTS)

The credentials file holds the address the listing is served as (your instance's public DNS name by default), the user name and the password generated on this instance. Show the file with:

sudo cat /root/directory-lister-credentials.txt

DIRECTORY_LISTER_URL=https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/ DIRECTORY_LISTER_USER=admin DIRECTORY_LISTER_PASSWORD=<24 letters and digits>

Open DIRECTORY_LISTER_URL in your browser. The certificate is self-signed (generated on your instance), so accept the browser warning once, or install your own certificate (Step 11).

The browser asks for a user name and password. Sign in as admin with DIRECTORY_LISTER_PASSWORD. Your browser remembers the sign-in until you close it.

The home page lists the served folder, with its README rendered underneath:

Click a folder to open it. The breadcrumb at the top takes you back. Click a file to open or download it. Use the download arrow at the top right to download the folder you are in as a zip archive.

Type in the search box to find files by name anywhere in the served folder.

Hover over a file and click the information icon to see its MD5, SHA-1 and SHA-256 hashes. Whoever downloads the file can use them to check the copy they received.

The light bulb in the header switches between the light and dark themes.

The served folder is /var/www/directory-lister/files. Copy your files into it over SSH and they appear in the listing at once. There is nothing to restart. Remove the sample files you do not want:

sudo rm -r /var/www/directory-lister/files/documents /var/www/directory-lister/files/data /var/www/directory-lister/files/images scp -i <your-key.pem> -r <your-folder> ubuntu@<public-ip>:/tmp/upload
sudo cp -r /tmp/upload/. /var/www/directory-lister/files/ && rm -rf /tmp/upload

Files must be readable by everyone on the instance, because PHP reads them as its own unprivileged user. Use mode 644 for files and 755 for folders, which cp gives you by default.

Edit /var/www/directory-lister/files/README.md (or delete it) to change the text under the listing. Any folder can have its own README.md.

Three rules keep the folder safe:

• Keep the hidden .directory-lister folder. It holds the application and must stay inside the served folder. Do not delete it, and do not point FILES_PATH anywhere else. PHP is confined to the served folder, which stops visitors climbing out of it.
• Dot files are never shown. Any file or folder whose name starts with a dot is hidden from the listing, search, zips and downloads.
• Use a mount, not a symbolic link, to serve another disk. A symbolic link that points outside the served folder is refused, and the folder that contains it cannot be listed. To serve a separate EBS volume, mount it on a folder inside the served folder, for example sudo mkdir /var/www/directory-lister/files/shared && sudo mount /dev/nvme1n1 /var/www/directory-lister/files/shared. Add it to /etc/fstab by UUID to keep it across reboots.

Directory Lister reads its settings from /var/www/directory-lister/files/.directory-lister/.env. You can change these:

• The page title (SITE_TITLE).
• The sort order (SORT_ORDER, REVERSE_SORT).
• Whether READMEs are shown (DISPLAY_READMES, READMES_FIRST).
• Whether folders can be downloaded as zips (ZIP_DOWNLOADS).

Then restart PHP so that it reads the new values:

sudo nano /var/www/directory-lister/files/.directory-lister/.env
sudo systemctl restart php8.3-fpm

Leave FILES_PATH, HIDDEN_FILES_LIST and APP_DEBUG=false as they are. Directory Lister's documentation at docs.directorylister.com lists every setting.

The listing is private, so every visitor needs the admin password. To publish the folder to anyone who can reach port 443, make it public deliberately. Make it private again the same way:

sudo directory-lister-set-access public
sudo directory-lister-set-access private
sudo directory-lister-set-access status

Only make it public for files you mean to publish to the world. Keeping it private and restricting port 443 in the security group to your own networks is safer still.

Port 80 sends browsers to HTTPS, the listing asks for the password, and the health endpoint answers for load balancer checks. Requests for a host name that the instance does not serve are dropped:

H=$(sed -n 's/^set \$dl_host "\(.*\)";$/\1/p' /etc/nginx/directory-lister-host.conf)
curl -s -o /dev/null -w 'port 80: %{http_code} -> %{redirect_url}\n' --resolve "$H:80:127.0.0.1" "http://$H/"
curl -sk -o /dev/null -w 'no password: %{http_code}\n' --resolve "$H:443:127.0.0.1" "https://$H/"
curl -sk --resolve "$H:443:127.0.0.1" "https://$H/healthz"
curl -s -o /dev/null -w 'unknown host name: %{http_code}\n' -H 'Host: example.com' http://127.0.0.1/ || true

port 80: 301 -> https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/ no password: 401 ok unknown host name: 000

000 means nginx closed the connection without an answer.

Signed in, a folder opens, while paths out of the folder, the application's own files and the hidden folder are refused. This block hands the password to curl from the credentials file without printing it:

H=$(sed -n 's/^set \$dl_host "\(.*\)";$/\1/p' /etc/nginx/directory-lister-host.conf) for q in "dir=documents" "file=../../../../etc/passwd" "file=..%2F..%2F..%2Fetc%2Fpasswd" "file=.directory-lister/.env" "dir=.directory-lister" "zip=.."; do curl -sk -K <(sudo sed -n 's/^DIRECTORY_LISTER_PASSWORD=\(.*\)/user = "admin:\1"/p' /root/directory-lister-credentials.txt) \
  -o /dev/null -w "?$q: %{http_code}\n" --resolve "$H:443:127.0.0.1" "https://$H/?$q" done

?dir=documents: 200 ?file=../../../../etc/passwd: 404 ?file=..%2F..%2F..%2Fetc%2Fpasswd: 404 ?file=.directory-lister/.env: 404 ?dir=.directory-lister: 404 ?zip=..: 404

The credentials file is readable by root only, and the password hash file by root and nginx only. The served folder belongs to root, and PHP can write only the application's cache. The hash file holds one user, admin, with a bcrypt hash:

sudo stat -c '%a %U:%G %n' /root/directory-lister-credentials.txt /etc/nginx/directory-lister.htpasswd /var/www/directory-lister/files /var/www/directory-lister/files/.directory-lister/app/cache
sudo cut -c1-13 /etc/nginx/directory-lister.htpasswd grep auth_basic /etc/nginx/directory-lister-access.conf

600 root:root /root/directory-lister-credentials.txt 640 root:www-data /etc/nginx/directory-lister.htpasswd 755 root:root /var/www/directory-lister/files 750 dirlister:dirlister /var/www/directory-lister/files/.directory-lister/app/cache admin:$2y$10$ auth_basic "Directory Lister"; auth_basic_user_file /etc/nginx/directory-lister.htpasswd;

nginx and PHP cannot reach the instance metadata service, and PHP runs as dirlister, confined to the served folder, with no shell commands and no URL access:

systemctl show nginx -p IPAddressDeny
systemctl show php8.3-fpm -p IPAddressDeny grep -E '^(user|php_admin_value\[open_basedir\]|php_admin_value\[disable_functions\]|php_admin_flag\[allow_url_fopen\])' /etc/php/8.3/fpm/pool.d/dirlister.conf

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128 IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128 user = dirlister php_admin_value[open_basedir] = /var/www/directory-lister/files php_admin_value[disable_functions] = exec,passthru,shell_exec,system,proc_open,popen,pcntl_exec php_admin_flag[allow_url_fopen] = off

The certificate was generated on this instance and names its own addresses:

H=$(sed -n 's/^set \$dl_host "\(.*\)";$/\1/p' /etc/nginx/directory-lister-host.conf)
echo | openssl s_client -connect 127.0.0.1:443 -servername "$H" 2>/dev/null | openssl x509 -noout -subject -ext subjectAltName

subject=CN = ec2-<public-ip-dashed>.<region>.compute.amazonaws.com, O = sac X509v3 Subject Alternative Name: DNS:ec2-<public-ip-dashed>.<region>.compute.amazonaws.com, IP Address:<public-ip>, IP Address:<private-ip>, IP Address:127.0.0.1, DNS:localhost

Point a DNS record at the instance, then set the name that the listing is served as. This command mints a new self-signed certificate for the name, updates nginx and the URL in /root/directory-lister-credentials.txt, and keeps the name across reboots:

sudo directory-lister-set-hostname <your-domain>

To use a certificate from your own certificate authority instead, copy it over the generated pair and reload nginx. Running directory-lister-set-hostname again replaces it with a self-signed one:

sudo install -m 0644 <your-domain>.crt /etc/nginx/ssl/directory-lister.crt
sudo install -m 0600 <your-domain>.key /etc/nginx/ssl/directory-lister.key
sudo nginx -t && sudo systemctl reload nginx

Once browsers trust the certificate, you can also add an HSTS header (add_header Strict-Transport-Security "max-age=31536000" always;) to /etc/nginx/snippets/sac-directory-lister-headers.conf. The image does not send one, because browsers ignore HSTS from a site whose certificate they do not trust.

directory-lister-set-password gives admin a new random password, writes its bcrypt hash for nginx and records it in /root/directory-lister-credentials.txt. Browsers that saved the old password are asked to sign in again.

Run it without arguments, or pass your own password (24 to 64 letters and digits) on stdin:

sudo directory-lister-set-password printf '%s\n' '<your-new-password>' | sudo directory-lister-set-password --stdin

If you lock yourself out with too many fast requests, wait a few seconds. The limit clears itself.

To upgrade to a later Directory Lister release, snapshot the instance and download the release archive from the Directory Lister releases page. Replace the contents of /var/www/directory-lister/files/.directory-lister with it. Keep .env and hidden-files.txt, empty app/cache, and leave the tree owned by root (with app/cache owned by dirlister).

Your files are untouched, because they live outside the application folder.

• Served folder (your files): /var/www/directory-lister/files
• Directory Lister (hidden, root-owned): /var/www/directory-lister/files/.directory-lister
• Settings: /var/www/directory-lister/files/.directory-lister/.env
• nginx site: /etc/nginx/sites-available/sac-directory-lister
• Sign-in switch and password hash: /etc/nginx/directory-lister-access.conf, /etc/nginx/directory-lister.htpasswd
• PHP pool: /etc/php/8.3/fpm/pool.d/dirlister.conf
• Certificate and key: /etc/nginx/ssl/
• First boot script: /usr/local/sbin/directory-lister-firstboot.sh
• Helpers: /usr/local/sbin/directory-lister-set-access, /usr/local/sbin/directory-lister-set-password, /usr/local/sbin/directory-lister-set-hostname
• License and release record: /usr/share/doc/directory-lister/
• Credentials: /root/directory-lister-credentials.txt (mode 0600)

• Allow port 22 in the security group from your own networks only, and port 443 from the networks that should see the files.
• Keep the listing private unless you mean to publish every file in it, and keep the password secret. Rotate it with Step 12 if it may have been shared.
• Use your own DNS name and a certificate your browsers trust (Step 11).
• If you add a .customizations.html file (Directory Lister's way to add analytics or custom scripts), note that the listing page only runs its own scripts. Extend the Content-Security-Policy in /etc/nginx/sites-available/sac-directory-lister for the sources you add.
• Keep the operating system patched. Unattended security upgrades are on, and sudo apt-get update && sudo apt-get upgrade applies everything else.
• PHP-FPM and the PHP zip extension (with its libzip library) come from Ubuntu's universe repository. sudo pro security-status --esm-apps shows whether Ubuntu Pro (ESM Apps) has security updates for them. None were pending when the image was built.
• Back up your files with EBS snapshots of the instance's volumes.