simplefiles

A lightweight C CGI web application for managing files.
git clone https://scm.kuandu.systems/git-raw/simplefiles.git
Log | Files | Refs | README | LICENSE

README.md (5954B)

      1 # SimpleFiles
      2 
      3 SimpleFiles is a lightweight C CGI web application for managing files stored in
      4 separate filesystem-backed repositories.
      5 
      6 It provides a browser-based interface for browsing, uploading, downloading,
      7 renaming, and deleting files.
      8 
      9 The current reference deployment uses OpenBSD `httpd` with `slowcgi`. Other
     10 CGI-capable web servers may work, but have not yet been tested.
     11 
     12 > **Security status:** SimpleFiles is currently pre-release software and
     13 > is undergoing security hardening. It should not yet be considered suitable
     14 > for production deployments where files are exposed to untrusted users or
     15 > hostile input.
     16 >
     17 > Known areas still under review include concurrent upload disk-space
     18 > accounting, strict multipart parsing, filesystem TOCTOU handling, and the
     19 > filesystem trust model. See `SECURITY.md` for details.
     20 
     21 ## Concepts
     22 
     23 A **repository** is a directory managed by SimpleFiles that contains uploaded
     24 files and optional repository-specific configuration.
     25 
     26 Repositories are stored below the configured storage root:
     27 
     28 ```text
     29 /storage/
     30 └── default/
     31 ```
     32 
     33 SimpleFiles does not provide user authentication itself. Authentication is
     34 expected to be handled by the web server, which may provide the authenticated
     35 username through `REMOTE_USER`.
     36 
     37 ## How to install
     38 
     39 SimpleFiles requires a CGI-capable web server and a POSIX-compatible
     40 environment.
     41 
     42 The following installation layout describes the filesystem as seen by the CGI
     43 application. When using a web server with a chroot environment, such as the
     44 default OpenBSD `httpd` setup, these paths must exist inside that environment.
     45 
     46 ### 1. Create the directories
     47 
     48 The default installation uses:
     49 
     50 | Path | Purpose | CGI user |
     51 | --- | --- | --- |
     52 | `/storage` | Repository files | read/write |
     53 | `/simplefiles` | HTML templates | read |
     54 | `/run/simplefiles/lock` | Repository locks | read/write |
     55 | `/run/simplefiles/uploads` | Temporary uploads | read/write |
     56 | `/etc/simplefiles.conf` | Global configuration | read |
     57 
     58 For example, if CGI runs as `www-data`:
     59 
     60 ```sh
     61 mkdir -p /storage
     62 mkdir -p /simplefiles
     63 mkdir -p /run/simplefiles/lock
     64 mkdir -p /run/simplefiles/uploads
     65 
     66 chown www-data:www-data /storage
     67 chown www-data:www-data /run/simplefiles/lock
     68 chown www-data:www-data /run/simplefiles/uploads
     69 
     70 chmod 750 /storage
     71 chmod 755 /simplefiles
     72 chmod 750 /run/simplefiles/lock
     73 chmod 750 /run/simplefiles/uploads
     74 ```
     75 
     76 The upload directory must not be group- or world-writable.
     77 
     78 ### 2. Install the templates
     79 
     80 Copy these files into `/simplefiles`:
     81 
     82 ```text
     83 upload.html.template
     84 delete.html.template
     85 list.html.template
     86 list-readonly.html.template
     87 rename.html.template
     88 ```
     89 
     90 They only need to be readable by the CGI user.
     91 
     92 ### 3. Build and install the CGI programs
     93 
     94 Compile the C sources and install the resulting CGI programs in a directory
     95 configured for CGI execution by the web server.
     96 
     97 The source distribution does not currently include a Makefile or web-server
     98 configuration examples.
     99 
    100 The CGI programs must run as an unprivileged user with the permissions described
    101 above.
    102 
    103 ## Reference deployment
    104 
    105 SimpleFiles is currently developed and tested with:
    106 
    107 - OpenBSD `httpd`
    108 - OpenBSD `slowcgi`
    109 - CGI execution within the web server's runtime filesystem environment
    110 
    111 OpenBSD `httpd` normally uses a chroot environment. When using this setup, all
    112 SimpleFiles paths, including storage, templates, configuration, locks, and
    113 temporary uploads, must be available inside the chroot environment.
    114 
    115 ## Configuration
    116 
    117 Create:
    118 
    119 ```text
    120 /etc/simplefiles.conf
    121 ```
    122 
    123 with at least:
    124 
    125 ```text
    126 CSRF_ORIGIN=https://files.example.com
    127 ```
    128 
    129 Replace the URL with the origin used to access the application.
    130 
    131 ### Global configuration
    132 
    133 `/etc/simplefiles.conf`:
    134 
    135 | Setting | Description |
    136 | --- | --- |
    137 | `CSRF_ORIGIN` | Required origin for modifying POST requests |
    138 
    139 The configuration file can be relocated with `SIMPLEFILES_CONFIG`.
    140 
    141 ### Repository configuration
    142 
    143 `/storage/<repository>/.config`:
    144 
    145 | Setting | Default | Description |
    146 | --- | ---: | --- |
    147 | `MAX_UPLOAD` | `104857600` | Maximum upload size in bytes |
    148 | `QUOTA` | `5368709120` | Maximum repository size in bytes |
    149 | `READ_ONLY` | `0` | Set to `1` to disable modifications |
    150 | `ADMIN_USER` | unset | Restrict administration to this `REMOTE_USER` |
    151 
    152 Example:
    153 
    154 ```text
    155 MAX_UPLOAD=52428800
    156 QUOTA=1073741824
    157 ADMIN_USER=alice
    158 ```
    159 
    160 ## Runtime settings
    161 
    162 The default paths can be changed with environment variables when supported by
    163 the CGI server:
    164 
    165 | Variable | Default |
    166 | --- | --- |
    167 | `STORAGE_ROOT` | `/storage` |
    168 | `SIMPLEFILES_ROOT` | `/simplefiles` |
    169 | `REPOSITORY_LOCK_DIR` | `/run/simplefiles/lock` |
    170 | `UPLOAD_TMP_DIR` | `/run/simplefiles/uploads` |
    171 | `SIMPLEFILES_CONFIG` | `/etc/simplefiles.conf` |
    172 
    173 The following limits can also be overridden:
    174 
    175 | Variable | Default |
    176 | --- | ---: |
    177 | `REPO_QUOTA_BYTES` | repository `QUOTA` |
    178 | `MIN_FREE_BYTES` | `1073741824` |
    179 
    180 > Note: OpenBSD `httpd` does not provide a way to configure arbitrary CGI
    181 environment variables. On OpenBSD, use the default paths or provide a wrapper
    182 mechanism if custom values are required.
    183 
    184 ## Web server
    185 
    186 Configure the CGI programs with the web server and ensure it supplies:
    187 
    188 ```text
    189 REQUEST_METHOD
    190 SCRIPT_NAME
    191 QUERY_STRING
    192 CONTENT_TYPE
    193 CONTENT_LENGTH
    194 HTTP_ORIGIN
    195 REMOTE_USER
    196 ```
    197 
    198 `REMOTE_USER` is only needed when `ADMIN_USER` is configured.
    199 
    200 Do not expose `/storage` as a static web directory.
    201 
    202 ## Security
    203 
    204 For a production deployment:
    205 
    206 - Run CGI as a dedicated, unprivileged user.
    207 - Keep `/storage` inaccessible as a static web directory.
    208 - Keep `/run/simplefiles/uploads` non-world-writable.
    209 - Configure `CSRF_ORIGIN`.
    210 - Use the web server for authentication when `ADMIN_USER` is used.
    211 
    212 Repositories are trusted filesystem locations. SimpleFiles does not currently
    213 protect against a malicious local user modifying repository contents outside the
    214 application.
    215 
    216 ## Default limits
    217 
    218 - Maximum upload: **100 MiB**
    219 - Repository quota: **5 GiB**
    220 - Minimum free space: **1 GiB**