A simple and lightweight cloud written in C99 plus POSIX.1-2008 extensions.
Go to file
Xavier Del Campo Romero 32af8ddd3d
README.md: Fix CMake build instructions
The previous instructions were simply wrong because `cmake ..` would
attempt to configure the project from the parent directory, instead of
the build directory.
2024-05-05 01:07:01 +02:00
cmake CMake: Find system libweb or dynstr if available 2023-10-25 13:45:12 +02:00
doc man1: Replace LICENSE/AUTHORS with COPYRIGHT 2023-09-27 22:13:52 +02:00
libweb@b4930f72bb Bump libweb to 0.3.0 2024-02-19 23:35:08 +01:00
.gitignore .gitignore: Ignore only ./Makefile 2023-11-24 01:52:00 +01:00
.gitmodules Apply slweb renaming to libweb 2023-10-11 00:08:40 +02:00
CMakeLists.txt Bump libweb to 0.3.0 2024-02-19 23:35:08 +01:00
LICENSE Initial commit 2023-02-28 01:43:56 +01:00
README.md README.md: Fix CMake build instructions 2024-05-05 01:07:01 +02:00
auth.c auth.c: Fix potential signed integer overflow 2023-10-14 13:08:25 +02:00
auth.h Apply slweb renaming to libweb 2023-10-11 00:08:40 +02:00
base64.c Initial commit 2023-02-28 01:43:56 +01:00
base64.h Initial commit 2023-02-28 01:43:56 +01:00
cftw.c cftw: Allow user callback to stop recursive search 2023-07-11 13:27:49 +02:00
cftw.h cftw: Allow user callback to stop recursive search 2023-07-11 13:27:49 +02:00
configure configure: Avoid file extension conversion 2024-01-26 20:31:18 +01:00
hex.c Move decode_hex into its own file 2023-03-09 01:14:10 +01:00
hex.h Move decode_hex into its own file 2023-03-09 01:14:10 +01:00
jwt.c Initial commit 2023-02-28 01:43:56 +01:00
jwt.h Initial commit 2023-02-28 01:43:56 +01:00
main.c main.c: Improve relative path detection 2024-02-20 21:24:17 +01:00
page.c page.c: Do not get filename on previews 2024-03-01 00:06:03 +01:00
page.h Implement HEAD support 2023-10-14 01:08:02 +02:00
style.c Allow admins to define their own stylesheet 2023-07-11 01:49:12 +02:00
style.h Allow admins to define their own stylesheet 2023-07-11 01:49:12 +02:00
usergen usergen: Do not abort on existing directory 2024-02-20 21:44:53 +01:00
wildcard_cmp.c wildcard_cmp.c: Fix out-of-bounds cmp 2023-07-09 05:54:56 +02:00
wildcard_cmp.h wildcard_cmp: Allow case-insensitive searches 2023-06-06 03:48:50 +02:00


slcl, a simple and lightweight cloud

slcl is a simple and lightweight implementation of a web file server, commonly known as "cloud storage" or simply "cloud", written in C99 plus POSIX.1-2008 extensions.


Screenshot of slcl's login page

Screenshot of an example user directory


Intentionally, slcl does not share some of the philosophical views from the suckless project. However, it still strives towards portability, minimalism, simplicity and efficiency.


  • Private access directory with file uploading, with configurable quota.
  • Read-only public file sharing.
  • Uses libweb, a tiny web framework.
  • A simple JSON file as the credentials database.
  • No JavaScript.


In order to maintain simplicity and reduce the risk for security bugs, slcl does not implement TLS support. Instead, this should be provided by a reverse proxy, such as caddy.

Root permissions

slcl is expected to listen to connections from any port number so that root access is not required. So, in order to avoid the risk for security bugs, please do not run slcl as root.


Since no client-side JavaScript is used, files are uploaded unencrypted to slcl. If required, encryption should be done before uploading e.g.: using gpg.


  • A POSIX environment.
  • OpenSSL >= 2.0.
  • cJSON >= 1.7.15.
  • dynstr (provided as a git submodule by libweb).
  • libweb (provided as a git submodule).
  • jq (for usergen only).
  • CMake (optional).

Ubuntu / Debian

Mandatory packages

sudo apt install build-essential libcjson-dev libssl-dev m4 jq

Optional packages

sudo apt install cmake

How to use


Two build environments are provided for slcl - feel free to choose any of them:

slcl can be built using the standard build process:


$ ./configure
$ make


$ cmake -B build
$ cmake --build build/

Setting up

slcl consumes a path to a directory with the following tree structure:

├── db.json
├── public
└── user


  • db.json is the credentials database. Details are explained below.
    • Note: slcl creates a database with no users if not found, with file mode bits set to 0600.
  • public is a directory containing read-only files that can be accessed without authentication. Internally, they are implemented as simlinks to other files.
    • Note: slcl creates this directory if it does not exist, with directory mode bits set to 0700.
  • user is a directory containing user directories, which in turn contain anything users put into them.
    • Note: slcl creates this directory if it does not exist, with directory mode bits set to 0700.

Note: slcl creates the given directory if it does not exist.

A more complete example:

├── db.json
├── public
│   └── 44e03ab1bc3b0eff1567c76619186596 -> user/alice/file.txt
└── user
    ├── alice
    │   └── file.txt
    └── john
        └── file2.txt

Credentials database

slcl reads credentials from the db.json database, with the following schema:

    "users": [{
        "name":	"...",
        "password":	"...",
        "salt":	"...",
        "key":	"...",
        "quota": "..."

usergen is an interactive script that consumes a directory, a username, a password and, optionally, a user quota in MiB. A salt is randomly generated using openssl and passwords are hashed multiple times beforehand - see usergen and auth.c for further reference. Also, a random key is generated that is later used to sign HTTP cookies.

Then, usergen appends a JSON object to the users JSON array in the db.json file located inside the given directory. Also, usergen creates the user directory inside the user/ directory.

When users authenticate from a web browser, slcl sends a SHA256HMAC-signed JSON Web Token, using the random key generated by usergen. No session data is kept on the server.


To run slcl, simply run the executable with the path to a directory including the files listed above. By default, slcl will listen to incoming connections on a random TCP port number. To set a specific port number, use the -p command line option. For example:

slcl -p 7822 ~/my-db/

slcl requires a temporary directory where files uploaded by users are temporarily stored until moved to the user directory. By default, slcl attempts to retrieve the path to the temporary directory by inspecting the TMPDIR environment variable, and falls back to /tmp if undefined.

If a custom temporary directory is required, it can be defined via command line option -t. For example:

slcl -t ~/my-tmp -p 7822 ~/my-db

Note: system-level temporary directories such as /tmp might reside on a filesytem different than the one where the database resides. This would force slcl to copy the contents from uploaded files from the temporary directory to the database, which might be an expensive operation. Therefore, in order to avoid expensive copies, define a custom temporary directory that resides on the same filesystem.

Why this project?

Previously, I had been recommended Nextcloud as an alternative to proprietary services like Dropbox. Unfortunately, despite being a very flexible piece of software, Nextcloud is way too heavy on resources, specially on lower end hardware such as the Raspberry Pi 3:

  • It uses around 30% RAM on my Raspberry Pi 3, configured with 973 MiB of RAM, and of course it gets worse with several simultaneous users.
  • Simple operations like searching and previewing files cause large amounts of I/O and RAM usage, so much that it locks the whole server up more often than not.
  • Nextcloud pages are bloated. Even the login page is over 15 MiB (!).
  • Requires clients to run JavaScript, which also has a significant performance penalty on the web browser. Also, some users do not feel comfortable running JavaScript from their web browsers, and thus prefer to disable it.

After years of recurring frustration as a Nextcloud administrator and user, I looked for alternatives that stripped out most of the unneeded bloat from Nextcloud, while providing the required features listed above. However, I could not find any that fit them, so I felt challenged to design a new implementation.

On the other hand, command line-based solutions like rsync might not be as convenient for non-technical people, compared to a web browser, or might not be even available e.g.: phones.


slcl, a simple and lightweight cloud.
Copyright (C) 2023  Xavier Del Campo Romero

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Also, see LICENSE.