Storage AWS

OpenList 4.2.9 on AWS User Guide

| Product: OpenList 4.2.9 on Ubuntu 24.04 on AWS

Overview

This guide covers launching and using the OpenList 4.2.9 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg file sharing and sync listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

OpenList is the open source, community maintained successor of AList: a self hosted file list and file manager. It shows the instance's own disk and any storage accounts you connect (S3 compatible object storage, WebDAV, FTP and SFTP servers, OneDrive, Google Drive and many more) as one folder tree in the browser. Your users can browse, preview, upload, rename, move, copy and delete files, create share links, and mount the whole tree as a WebDAV drive. An administrator decides who may see and do what.

The cloudimg image locks OpenList down:

  • No default administrator and no setup wizard. The image ships no database, no configuration file and no password. First boot creates the admin account with a password unique to your instance and writes it to /root/openlist-credentials.txt (root only). The setup wizard is only ever reached over the loopback address while the web server is still stopped, and the web server answers it with 404 afterwards.
  • Per instance secrets. OpenList's JWT signing secret (64 characters), its admin API token, the administrator password and the TLS key are all generated on your instance's first boot. None of them exists in the image.
  • Guest access closed. OpenList's built in guest account is disabled, and its upstream default password is replaced with a random one nobody holds, so anonymous visitors see nothing.
  • HTTPS from the first boot. nginx serves OpenList on port 443 with a certificate generated on your instance. Port 80 redirects to HTTPS, and requests for a host name the instance does not serve are dropped. OpenList itself listens on 127.0.0.1:5244 only, as the unprivileged openlist account.
  • Cross site requests refused. A request that changes something and comes from another website's page is refused, and OpenList only answers browser requests from its own address (CORS). The server side media proxy and the sign out link additionally refuse cross site navigation. Signed download and share links keep working when you send them to someone.
  • Metadata service blocked. OpenList fetches URLs on the server for its storage drivers and for offline downloads. OpenList, nginx and the first boot step cannot reach the EC2 instance metadata service, so nobody can use those features to read the instance's role credentials.
  • Rebuilt with current security fixes. cloudimg compiles OpenList 4.2.9 from its source tag with Go 1.27.3 and updated Go modules (see Source code and licence below), so govulncheck reports no affecting vulnerability in the shipped binary.
  • Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: OpenList 4.2.9 (GNU AGPL 3.0; web interface MIT), built by cloudimg from the upstream source, nginx, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent. The complete source is on the image in /usr/share/doc/cloudimg/openlist/source and is offered to every user of your OpenList at https://<your-host>/cloudimg-source/.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

  • An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet.
  • A security group that allows TCP 22 (SSH), TCP 443 (OpenList) and TCP 80 (redirects to HTTPS) from your own networks only.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick OpenList 4.2.9 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large, your key pair, a security group as above, and a subnet.

Files you upload to the instance itself are stored on the root volume (8 GiB in the AMI). If you will keep files on the instance rather than only in connected cloud storage, raise the root volume under Configure storage; Ubuntu grows the file system to the volume size at boot.

With the AWS CLI (replace the values in angle brackets; this sets the root volume to 50 GiB):

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 \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=50,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=openlist}]'

Step 2: Connect to your instance

Version SSH user
OpenList 4.2.9 on Ubuntu 24.04 ubuntu 
ssh -i <your-key.pem> ubuntu@<public-ip>

Step 3: Check the services

First boot works out the instance's name, generates the certificate and the secrets, creates the administrator and then starts the site. It takes a few seconds:

systemctl is-active openlist-set-host openlist-firstboot openlist nginx

active
active
active
active

Only SSH (22) and nginx (80, 443) listen on the network. OpenList listens on the loopback address only; the two :53 entries are Ubuntu's local DNS resolver. OpenList's own S3, FTP and SFTP servers are switched off:

sudo ss -lntp | awk 'NR>1 {print $4}' | sort -u

0.0.0.0:22
0.0.0.0:443
0.0.0.0:80
127.0.0.1:5244
127.0.0.53%lo:53
127.0.0.54:53
[::]:22
[::]:443
[::]:80

If nginx is not running, first boot has not finished (or failed, in which case the site is never served). Check systemctl status openlist-firstboot and journalctl -u openlist-firstboot.

Step 4: Get your URL and password

sudo cat /root/openlist-credentials.txt

The file is readable by root only and holds the address and this instance's administrator sign in:

# OpenList on Ubuntu 24.04 (cloudimg AWS Marketplace image) - this instance's administrator sign-in.
# Generated on this instance at first boot; unique to it and not known to cloudimg or the OpenList project.
...
OPENLIST_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/
openlist.admin.user=admin
openlist.admin.pass=<OPENLIST_ADMIN_PASSWORD>

You can confirm the sign in from the instance itself. The helper checks, through nginx, that OpenList answers and reports version 4.2.9, that anonymous access and a wrong password are refused, that the setup wizard is closed, and that the password from the credentials file signs in as an administrator:

sudo /usr/local/sbin/openlist-verify.sh

openlist: ping pong, v4.2.9, anonymous refused, wrong password refused, setup wizard 404, per-instance admin signed in (role 2)
OPENLIST_ROUNDTRIP_OK

Step 5: Sign in

Open the OPENLIST_URL address in your browser. The certificate is self signed (see Step 10), so the browser asks you to accept it once; compare the fingerprint it shows with the one on the instance:

sudo openssl x509 -in /etc/ssl/openlist/openlist.crt -noout -fingerprint -sha256

Sign in as admin with the password from Step 4. A new instance always shows the sign in page, never a setup form. Browse as a guest is refused, because the guest account is disabled:

The OpenList sign in page

Change the administrator password to one of your own under Manage, Profile. The credentials file is not updated when you do; delete it (sudo rm /root/openlist-credentials.txt) once you no longer need it (openlist-verify.sh reads it, so the check stops working then).

Step 6: Browse and upload files

OpenList opens on the root folder, which is the instance's own storage (/var/lib/openlist/files). The notice at the top right points every user to the source code of the server (see Source code and licence below); close it with the cross.

The round button at the bottom right opens the toolbar: refresh, new file, new folder, move, batch rename, upload, offline download and the local settings. Upload accepts several files or a whole folder, and shows each file's progress:

Two files uploaded through the OpenList uploader

Click a file to preview it (text, Markdown, images, audio and video play in the browser) or download it. Select files with the check boxes to move, copy, rename, delete or download them together:

The OpenList root folder with the uploaded files

Things to know:

  • Download links are signed. A file's direct link carries a signature made with this instance's own key; a link without it, or with a changed one, is refused. You can paste a signed link into another application or a media player.
  • Share links. Create a share for a file or folder from its menu, optionally with a password and an expiry, and manage them under Manage, Shares.
  • Offline download fetches a URL on the server straight into a folder (OpenList's built in HTTP downloader). It, and every storage driver, can reach the internet but not the EC2 instance metadata service.
  • Office, PDF and EPUB previews use outside viewers. OpenList's default preview settings open Office documents in Microsoft's or Google's online viewer and PDF and EPUB files in viewers hosted by the OpenList project; the viewer is given a signed link to the file, and must be able to reach your instance to show it. If your files must not leave the instance, remove those entries under Manage, Settings, Preview (iframe previews).
  • The text editor loads its code editor component from the jsDelivr CDN in your browser the first time you open a file for editing.

Step 7: Connect storage

Under Manage, Storages the image ships one storage: Local, mounted at /, which is the instance's /var/lib/openlist/files folder. Choose Add to connect more: S3 compatible object storage (Amazon S3 included), WebDAV, FTP, SFTP, SMB, OneDrive, Google Drive, Dropbox and the other drivers OpenList offers. Each storage is mounted at a path you choose and appears as a folder in the tree:

Manage, Storages with the cloudimg default storage

For Amazon S3, create an IAM user (or access key) limited to the bucket you mount and enter its access key in the storage form. The instance's own IAM role is not available to OpenList, because OpenList cannot reach the instance metadata service.

Step 8: Add users

Under Manage, Users add an account for each person and choose its base path (the folder it sees as its root) and its permissions (upload, rename, move, copy, delete, create shares, WebDAV read and write, and so on). The built in guest account is listed as not available; leave it that way unless you want anonymous visitors to browse:

Manage, Users with the guest account disabled

After five wrong passwords from one address, OpenList refuses further sign ins from that address for five minutes, and nginx limits how fast sign ins can be attempted.

Step 9: Mount OpenList as a WebDAV drive

OpenList serves the same folder tree over WebDAV at https://<your-host>/dav/, for users whose permissions include WebDAV. Sign in with the OpenList user name and password. For example, in macOS Finder choose Go, Connect to Server and enter the address; on Linux use davfs2 or rclone; on Windows map a network drive (Windows needs a certificate it trusts, see Step 10).

Step 10: Use your own host name

Point a DNS record at the instance (an Elastic IP keeps the address across stop and start), then tell the instance its name. This generates a new self signed certificate for that name, updates the nginx host rule, the cross site guard, OpenList's site address and allowed origin, and the address in the credentials file, and keeps the name across reboots:

sudo openlist-set-hostname files.example.com

The certificate stays self signed. At every boot the image checks that the certificate is the one it generated for the configured name and the instance's addresses, and generates a new one if not, so a certificate copied over /etc/ssl/openlist/openlist.crt is replaced at the next boot. If your users need a publicly trusted certificate, put a load balancer or reverse proxy that holds that certificate (for example an AWS Certificate Manager certificate) in front of the instance and forward to it on 443. Behind a proxy, every sign in arrives from the proxy's address, so the five failure lock out then applies to everyone behind it.

Step 11: Where your data lives, backups and updates

OpenList's configuration (config.json, with this instance's JWT secret) and its database (data.db: users, password hashes, storages, shares and settings) are in /var/lib/openlist/data; files stored on the Local storage are in /var/lib/openlist/files. Both folders belong to the openlist account and nobody else can read them:

sudo ls -la /var/lib/openlist

total 16
drwxr-xr-x  4 root     root     4096 Oct 30 22:11 .
drwxr-xr-x 49 root     root     4096 Oct 30 22:06 ..
drwx------  3 openlist openlist 4096 Oct 30 22:10 data
drwx------  2 openlist openlist 4096 Oct 30 22:20 files

To copy files in over SSH, write them as that account so OpenList can manage them, for example:

sudo -u openlist cp /home/ubuntu/report.pdf /var/lib/openlist/files/

Every service is enabled, so OpenList returns after a reboot or a stop and start, with your users, storages and files as they were. Unattended security upgrades keep the operating system and nginx patched:

systemctl is-enabled openlist-set-host openlist-firstboot openlist nginx unattended-upgrades

enabled
enabled
enabled
enabled
enabled

To back up, take an EBS snapshot of the root volume (or use AWS Backup on the instance); Manage, Backup & Restore also exports OpenList's settings, users and storages as a file. cloudimg publishes a new version of the image when a newer OpenList release is available.

Security notes

Secrets. The credentials file, config.json (JWT secret), the database (admin API token, password hashes) and the TLS key are each readable by one account only. The root owned /etc/openlist/openlist.env holds no secret; it pins the settings OpenList must not change:

sudo stat -c '%a %U:%G %n' /root/openlist-credentials.txt /var/lib/openlist/data/config.json /var/lib/openlist/data/data.db /etc/openlist/openlist.env /etc/ssl/openlist/openlist.key

600 root:root /root/openlist-credentials.txt
600 openlist:openlist /var/lib/openlist/data/config.json
600 openlist:openlist /var/lib/openlist/data/data.db
640 root:openlist /etc/openlist/openlist.env
600 root:root /etc/ssl/openlist/openlist.key

The JWT secret that signs every OpenList session was generated on your instance (this prints only its length):

sudo python3 -I -c 'import json; c = json.load(open("/var/lib/openlist/data/config.json")); print("jwt_secret:", len(c["jwt_secret"]), "characters")'

jwt_secret: 64 characters

Pinned listener and servers. OpenList reads these after its own config.json, so a change made in the web interface cannot reopen a port:

sudo grep -E '^OPENLIST_(ADDR|HTTP_PORT|HTTPS_PORT|S3_ENABLE|FTP_ENABLE|SFTP_ENABLE|MCP_ENABLE|TLS_INSECURE_SKIP_VERIFY)=' /etc/openlist/openlist.env

OPENLIST_ADDR=127.0.0.1
OPENLIST_HTTP_PORT=5244
OPENLIST_HTTPS_PORT=-1
OPENLIST_S3_ENABLE=false
OPENLIST_FTP_ENABLE=false
OPENLIST_SFTP_ENABLE=false
OPENLIST_MCP_ENABLE=false
OPENLIST_TLS_INSECURE_SKIP_VERIFY=false

Certificate. The per instance certificate names the instance and cannot sign other certificates:

sudo openssl x509 -in /etc/ssl/openlist/openlist.crt -noout -subject -ext basicConstraints,extendedKeyUsage

subject=CN = ec2-203-0-113-10.compute-1.amazonaws.com, O = cloudimg
X509v3 Basic Constraints: critical
    CA:FALSE
X509v3 Extended Key Usage: 
    TLS Web Server Authentication

Redirect and unknown names. Port 80 answers the instance's own name with a redirect to HTTPS and closes the connection for any other name (000 means no response):

H=$(cat /etc/cloudimg/openlist-served-host)
curl -s -o /dev/null -w '%{http_code}\n' -H "Host: $H" http://127.0.0.1/
curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: not-this-server.example' http://127.0.0.1/ || true

301
000

Guest disabled. An anonymous request is refused:

H=$(cat /etc/cloudimg/openlist-served-host)
curl -s --resolve "$H:443:127.0.0.1" --cacert /etc/ssl/openlist/openlist.crt "https://$H/api/me"; echo

{"code":401,"message":"Guest user is disabled, login please","data":null}

Cross site guard. A request that changes something and carries another website's Origin is refused before it reaches OpenList, and so is a cross site request to the media proxy (which would otherwise fetch a URL on the server):

H=$(cat /etc/cloudimg/openlist-served-host)
curl -s -o /dev/null -w '%{http_code}\n' --resolve "$H:443:127.0.0.1" --cacert /etc/ssl/openlist/openlist.crt -X POST -H 'Origin: https://attacker.example' -H 'Content-Type: application/json' -d '{"path":"/x"}' "https://$H/api/fs/mkdir"
curl -s -o /dev/null -w '%{http_code}\n' --resolve "$H:443:127.0.0.1" --cacert /etc/ssl/openlist/openlist.crt -H 'Sec-Fetch-Site: cross-site' "https://$H/api/public/media/proxy?url=http://169.254.169.254/latest/meta-data/"

403
403

OpenList's API authenticates with an Authorization header, never a cookie, so another website cannot borrow a signed in user's session. Native clients (WebDAV drives, scripts using the API) send no Origin and are not affected.

Metadata service blocked. OpenList, nginx and the first boot step run with a systemd address filter that drops traffic to the EC2 instance metadata service (and its IPv6 address):

systemctl show -p IPAddressDeny openlist nginx openlist-firstboot

IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32

IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32

IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32

cloudimg tests this on every build from inside the running services: an offline download of a public URL succeeds, and the same download from http://169.254.169.254/ is refused (OpenList 4.2.9 also refuses cloud metadata addresses itself). Only openlist-set-host, which looks up the instance's public name at boot, uses the metadata service (IMDSv2).

Sandbox. OpenList runs as openlist with no capabilities, can write only /var/lib/openlist/data and /var/lib/openlist/files, and cannot read the credentials file or the TLS key. Its program in /opt/openlist is owned by root.

Security fixes and remaining advisories. OpenList 4.2.9 includes the fixes for every published OpenList advisory (all fixed in 4.2.6 or earlier). Upstream's 4.2.9 release binary carries Go modules with published advisories that its code reaches (golang.org/x/net HTTP/2 and HTML); cloudimg's rebuild raises golang.org/x/net to 0.62.0, google.golang.org/grpc to 1.85.0 and filippo.io/edwards25519 to 1.1.1, and govulncheck finds no affecting vulnerability in the source or the shipped binary. Three Go advisories have no fix and are not called by OpenList: GO-2022-0635 and GO-2022-0646 (AWS S3 client side encryption, which OpenList does not use) and GO-2026-5932 (an OpenPGP module). In the web interface, copies of DOMPurify bundled inside the diagram and code editor components carry advisories that only affect options OpenList never sets, and KaTeX carries a low severity advisory; they run in your browser, not on the server.

Third party addresses. The default site logo and favicon are loaded by your browser from res.oplist.org (the OpenList project); change them under Manage, Settings, Site if you prefer. Cloud drive storage drivers that need it talk to their providers and, for some, to the OpenList project's token renewal service, only when you add such a storage.

Restrict 22/tcp to your management network, and 80/443 to the networks that use OpenList.

Source code and licence

OpenList is licensed under the GNU Affero General Public License 3.0, and its web interface under the MIT licence. Under the AGPL, the users of your OpenList server are entitled to its source code. This image carries it, and the server offers it to every user: the notice on the home page links to https://<your-host>/cloudimg-source/, which nginx serves read only from /usr/share/doc/cloudimg/openlist/source:

The source code directory served at /cloudimg-source/

ls -l /usr/share/doc/cloudimg/openlist/source/

total 1464
-rw-r--r-- 1 root root   28856 Oct 30 22:10 BUILD-PROVENANCE.txt
-rw-r--r-- 1 root root   34523 Oct 30 22:10 LICENSE
-rw-r--r-- 1 root root    1864 Oct 30 22:10 SOURCE.txt
-rw-r--r-- 1 root root   15676 Oct 30 22:10 go.mod.cloudimg
-rw-r--r-- 1 root root     956 Oct 30 22:10 go.mod.cloudimg.diff
-rw-r--r-- 1 root root  107775 Oct 30 22:10 go.sum.cloudimg
-rw-r--r-- 1 root root 1293420 Oct 30 22:10 openlist-v4.2.9-source.tar.gz
  • openlist-v4.2.9-source.tar.gz is the unmodified upstream source of tag v4.2.9 (commit 0497ee8538).
  • go.mod.cloudimg and go.sum.cloudimg are the module files the binary was built with; go.mod.cloudimg.diff shows the only change from the tag: the three module raises above and the dependency versions they bring with them. No OpenList source file is changed.
  • BUILD-PROVENANCE.txt lists the Go toolchain, the build commands and flags and the checksums (the build is reproducible), and SOURCE.txt is the written offer and the upstream addresses. LICENSE is the AGPL text.

The source archive's checksum matches the one recorded in BUILD-PROVENANCE.txt:

sha256sum /usr/share/doc/cloudimg/openlist/source/openlist-v4.2.9-source.tar.gz

a762ff50b71b384f03af2996cac2aba471b0d5ec44aad0255e646a41c8af7f49  /usr/share/doc/cloudimg/openlist/source/openlist-v4.2.9-source.tar.gz

If you change OpenList's code and let others use your server, the AGPL asks you to offer them your changed source in the same way.

Architecture summary

Component Detail
File manager OpenList 4.2.9 (AGPL 3.0, web interface MIT), cloudimg rebuild in /opt/openlist, account openlist
Listener 127.0.0.1:5244 only; S3, FTP, SFTP and MCP servers off (/etc/openlist/openlist.env)
Web server nginx on 443 (HTTPS, per instance certificate in /etc/ssl/openlist), 80 redirects to HTTPS
Sign in OpenList users in /var/lib/openlist/data/data.db; administrator admin; guest disabled
Your files Local storage at / = /var/lib/openlist/files on the root volume; more storages under Manage, Storages
Credentials /root/openlist-credentials.txt, mode 0600, root only
First boot openlist-set-host.service (host name and certificate), openlist-firstboot.service (secrets and administrator)
Tools openlist-set-hostname, openlist-verify.sh
Source /usr/share/doc/cloudimg/openlist/source, served at /cloudimg-source/
Ports 22 SSH, 80 redirect, 443 OpenList (web, API and WebDAV at /dav/)
Base image Ubuntu 24.04 LTS, fully patched, unattended security upgrades enabled, IMDSv2 required

Support

cloudimg images come with 24/7 support. Email support@cloudimg.co.uk with your AWS account ID and the instance ID. For OpenList itself, see the OpenList project on GitHub and its documentation.

OpenList is an open source project by the OpenList team and contributors. cloudimg is not affiliated with or endorsed by the OpenList project.