Uploading Books
Stump has an opt-in feature that allows your users to upload books to your server.
This functionality allows files to be uploaded to your server, so it should be used with caution.
This feature must be manually enabled by the server owner by setting the enable_upload
configuration variable to true.
Enabling upload
Uploading is disabled by default, and is gated behind the enable_upload configuration variable (true enables uploading). This variable can be set by modifying your Stump.toml file to set enable_upload = true or by setting the environment variable STUMP_ENABLE_UPLOAD=true.
When uploading is not enabled, the routes for uploading will not be attached to your server and, consequently, the web UI will not show the upload interface. Attempting to upload directly through the API will result in HTTP Error 404.
Permissions
Only users with permission to upload are allowed to add files to the server. Users will need the following permissions:
file:uploadmanage:library
The server owner can assign these permissions to users on the user management settings page. For more information on that process, see the user permissions guide.
Configuration
The server limits the maximum upload size based on your configuration, you can change max_file_upload_size in Stump.toml or the STUMP_MAX_FILE_UPLOAD_SIZE environment variable to set the maximum allowed upload size in bytes.
How it works
This feature allows users to upload books or an entire collection of files and directories via series upload. To use it, navigate to the “Files” menu for a library and click the icon to open the upload dropdown. Select “Add books” to upload one or more book files. Select “Add series” to upload a single .zip archive containing the content you wish to upload.
After an upload finishes, a library scan will automatically be started to add the newly uploaded books.
Uploading books
This menu is accessed from ” Add books” in the upload dropdown. It allows users to upload one or more book files (e.g., .cbz, .cbr, .epub, and .pdf files) to a specific library directory.
Add books
Drag and drop one or more book files into the drop zone or click the drop zone to browse to the files you want to add.
Review the books you want to add
Review the list of books you have chosen to add in the “Added files” list below the dropzone.
If you added a file that you do not want to upload, you can remove it by clicking on “Remove” to the right of the file info.
Click “Upload” to begin the upload!
Clicking “Upload” starts your upload. Watch the corner of the screen for a toast confirming that your upload was successful.
Uploading series
This menu is accessed from ” Add series” in the upload dropdown. It allows users to upload a .zip file containing multiple books, images, or metadata in an arbitrary directory structure. The archive will be extracted to the location specified when uploading.
Add a zip file
Drag and drop one .zip file onto the drop zone or click the drop zone to browse to the zip archive you want to add.
Enter a name for the series
Enter a name for the series below the drop zone. This is the name of the directory to which your zip archive will be unpacked.
Confirm the zip file you want to add
Confirm that you added the right file in the “Added files” list below the “Series name” field.
If you added a file that you do not want to upload, you can remove it by clicking on “Remove” to the right of the file info and select a new file.
Click “Upload” to begin the upload!
Clicking “Upload” starts your upload. Watch the corner of the screen for a toast confirming that your upload was successful.
Troubleshooting
This section provides explanations for possible errors you may encounter when uploading files.
400 Bad request
A bad request error will be returned if the request includes disallowed files or attempts to access a path outside the library for which the upload is intended.
401 Unauthorized
This error indicates that the user attempting to upload files does not have the required file:upload or manage:library permissions.
404 Not found
This error may indicate that uploading has not been enabled for your server. Double check that you have enable_upload = true in your Stump.toml or STUMP_ENABLE_UPLOAD = true set in your environment.
413 Payload too large
The uploaded files exceeded your configured maximum upload size. Consider increasing the value of max_file_upload_size in Stump.toml or changing the value of the STUMP_MAX_FILE_UPLOAD_SIZE environment variable.
Security considerations
Stump attempts to validate uploads in order to protect the host system from misuse of upload functionality, but it should be used with care. The following section describes the validation Stump applies to incoming upload requests.
Validations
- File type: Only certain file types are permitted in uploads.
- Books: Only
.cbr,.cbz,.epub, and.pdffiles are allowed. - Series: Only
.ziparchives can be uploaded.- The contents of the archive must also be limited to:
.cbr,.cbz,.epub,.pdf,.xml,.jsonand image file types.
- The contents of the archive must also be limited to:
- Books: Only
- Content-Type: The server attempts to validate content-type of uploads to reject anything not matching the files above.
- Path validation: The server will not allow uploads outside the library for which they are intended, and special path components like
..will be rejected entirely. - Overwrite protection: An upload cannot overwrite an existing file.
It may be possible to construct input that circumvents this validation. Server owners are encouraged to only enable this functionality if they need it and to only allow trusted users permission to upload files.
If you have any questions or encounter issues, please open an issue on GitHub.