Zum Inhalt

Concepts and components of PFS

This document describes the concept and components of ProtectedFileServer. If you want to run your own PFS instance, it is important to understand these concepts to configure them properly.

PFS Instances

A single TomatenHTTP server can manage multiple PFS instances. Each PFS instance has its own configuration, its own data, and its own user system. The PFS instances behave like separate PFS installations, even though they run on the same server. Each PFS instance must have a unique URL-path to be accessible.

PFS uses the app system of TomatenHTTP. Each PFS instance is represented by an TomatenHTTP app. The PFS instance can be configured using the configuration of the respective app.

The default configuration defines a PFS instance named example.

Volumes

PFS uses volumes to store data. Volumes are an abstract storage that can store files and directories. PFS supports two implementations of volumes: file and veracrypt. File volumes are directories on a file system. The files inside that directory are the data of that volume. VeraCrypt volumes are encrypted VeraCrypt containers. VeraCrypt volumes are only mounted when needed. For example, if a user wants to access a file from that volume.

There are two categories of volumes: The main volume and data volumes.

Data Volumes

Data volumes contain the files and directories that should be accessible as the content of the server. The data volumes also store the Transform files that define how the content is displayed. The PFS server only reads the content of data volumes, so data volumes are never modified by the server itself. The content of data volumes has to be created by the admins of the PFS instance.

There can be multiple data volumes for a single PFS instance. The contents of these data volumes are displayed in the web interface as if they were in a single directory. This can be useful if the size of the content exceeds a few terabytes and don't fit on a single drive. So, instead of creating a RAID array using multiple drives, you can also configure multiple drives as multiple data volumes and use each drive individually.

Transform files

The purpose of Transform files is to set attributes for files and directories. A Transform file is usually a text file called transform.txt or <filename>.transform.txt. Transform files allow admins to customize how files and directories are displayed in the web interface. For example, transform files can change the display name of files, change their thumbnail image as well as show additional information.

Since Transform files have decent scripting capabilities, admins can also use Transform files to implement complex customizations.

Main Volume

The main volume stores the file index and the metadata as well as the attributes for all files. This information allows to navigate the files of the PFS server without the need to mount all volumes. The main volume might also store user data and cache files.

In general, the main volume is a lot smaller than the data volumes. While the main volume stores the file index and caches some files, the data volumes contain the actual data. In most cases, a few gigabytes of space should be sufficient for the main volume.

Don't modify the content of the main volume

The content of the main volume is written by the PFS server itself during a rebuild process. It is not recommended to modify the content of the main volume manually.

Rebuild

Admins are able to start a Rebuild process. This process traverses all data volumes, runs all Transform files and updates the file index and attributes accordingly. The rebuild process can take some time depending on the size of the data volumes.

Admins can start the rebuild process using the button at the top of the Volumes panel. Non-admin users are not able to start the rebuild process themselves.

Don't stop while rebuilding

It is not recommended to stop the server, log out or unmount the main volume while a rebuild process is running. This is especially important when the main volume is a VeraCrypt container.

graph BT
    D1(**Data Volume**
        contains content and Transform files) .->|**Rebuild**
        create index of content and run Transform files| Main(**Main Volume**
        contains file index and file attributes)
    D2(**Data Volume**
        contains additional content and Transform files) .->|**Rebuild**
        create index of content and run Transform files| Main
    User[**User**
        using the web interface] -->|Browse files| Main
    User -->|Access file| D1
    User -->|Access file| D2

Users

If you want to use the web interface to browse the files, you need to log in as a user. There are two types of users: admins and non-admins.

  • Admins are able to start a rebuild process. Usually, admins have file system access to at least one data volume and thus can control the contents of the server. As a user, you have to trust the admins of the server, since they could upload malicious content to the server or include malicious scripts in the web interface. Ideally, you host your own PFS instance so that you are the admin yourself.
  • Non-admins can only browse and view files. Usually, they have no file system access to the server and can't modify or delete files.

Users are configured in the app configuration of the PFS instance. It is not possible to register users via the web interface. Users must be registered manually by an admin.

User Password

Users require a password to access the web interface. This user password is used to authenticate the user. The password has to be stored in the app configuration as a SHA-256 hash of the UTF-8 encoded password. If you have a PFS instance already running, you can create such a hash using the web interface at https://<pfs-url>/passwordhash.

It is possible for a user to have no user password. In some cases this may be a valid choice. For example, if you run the PFS instance on your local device or if you have a global password configured.

If all configured users don't have a user password, the login page hides the User Password field.

Multiple users

In general it is a good idea to configure user passwords if multiple users should access the PFS instance. This ensures that users cannot impersonate each other. If you are the only user of your PFS instance, it may be a good choice to configure only a global password and no user password. This allows to set up encryption for the data stored in the PFS instance.

Global Password

The global password is a password that is equal for all users. Therefore, all users must know the global password. The global password can be used to decrypt the contents of the PFS instance.

Similar to the user passwords, the global password has to be configured in the app configuration of the PFS instance and has to be specified as a SHA256 hash of the UTF-8 encoded password.

If your main volume is a VeraCrypt volume, the global password has to be the password used to unlock the VeraCrypt volume. If the PFS instance doesn't configure a global password, but uses a VeraCrypt volume as the main volume, then the global password is checked by trying to unlock the main volume. In general, if the main volume can't be unlocked, the user can't log in.

All other data volumes that are VeraCrypt volumes must be encrypted with the same password as the main volume or the global password. If they can't be unlocked with the previously entered global password, the user will receive errors when trying to access files from that volume.

If all users have a user password configured and the data should not be encrypted, it is a valid choice to configure no global password. In this case, the Global Password field will be hidden from the login page.

No user and global password

It is not recommended to use neither a user nor a global password. This would make the PFS instance accessible without any authentication.

Unknown Users

It is possible to activate allow-unknown-users in the configuration. This allows guest users to freely chose a name and log in with no user password. Only user names that are registered with a user password can't be access by these guest users.

Not recommended

In general, it is not recommended to allow unknown users. If you need to allow guest users, make sure to use a strong global password.

Login tokens

In some situations you want to access the PFS instance without entering the user and global passwords. For this purpose, login tokens can be used.

A login token is a short, random one-time password that can be used to log in. To create a login token, you have to be logged in with the same user on a different device. Then you can create the token in the user menu.

On the login page you have to select Log in with token and enter the token.

The token is only valid until it has been used. If not used, the token will expire after a few minutes.