Server Configuration
As is typical for TomatenHTTP apps, PFS is configured via a config file in the apps folder of the server.
The AppType name for PFS is pfs. Accordingly, the file pfs.toml in the apps folder contains the configuration for the PFS app.
If the server was installed with TomatenPack, a sample pfs.toml has already been created. This default configuration should be reviewed and adjusted before operation.
PFS is capable of running multiple separate instances on a single TomatenHTTP server. For this purpose, instead of pfs.toml, individual app definitions must be created for the different instances, for example, demo.pfs.toml and home.pfs.toml for two instances named "demo" and "home". Each config file must be a complete PFS app configuration.
If multiple PFS instances are used, they must be configured for different URL locations.
It is recommended to write the config in the TOML format. Optionally, a config can also be specified as equivalent JSON, for example, demo.pfs.json.
Structure
Here, the configuration options are described.
location
The site location of the PFS instance. In general, this is the base URL path where PFS should be hosted. All sites of this PFS instance will be sub-paths of this location.
| Mandatory | Type |
|---|---|
| Yes | string |
main_volume
Configures the main volume of the PFS instance. The main volume stores general information about the data volume files. See the Concepts page for more information about the main volume. See the Volume Configuration section on how to configure a volume.
| Mandatory | Type |
|---|---|
| Yes | Volume |
data_volumes
Configures the data volumes of the PFS instance. The data volumes contain the data accessible through the PFS UI. See the Concepts page for more information about the data volumes. See the Volume Configuration section on how to configure a volume.
| Mandatory | Type |
|---|---|
| At least 1 volume | List of Volumes |
Volume Configuration
The structure of the volume configuration is identical for the main volume and the data volumes. Currently, two types of volumes are supported: file and veracrypt. The different volume types have different configuration options.
File Volume
A file volume is a directory on a file system. The content of that directory represents the data of the volume.
name = "volume_name" # The unique name of the volume
type = "file" # Specifies that this is a file volume
path = "/home/pfs_data" # The path of the directory
VeraCrypt Volume
A veracrypt volume can be an encrypted VeraCrypt container or drive. PFS will mount the VeraCrypt volume when needed. Therefore, users must enter a global password during login. This password will be used by the PFS server to unlock and mount the configured VeraCrypt volumes. PFS will automatically unmount and lock all of its VeraCrypt volumes when the last user logs out. So the VeraCrypt volumes managed by PFS are only unlocked while active users are logged in.
name = "volume_name" # The unique name of the volume
type = "veracrypt" # Specifies that this is a VeraCrypt volume
# The path to the encrypted VeraCrypt container or partition
volume_path = "/home/pfs_data.hc"
# The path where PFS should mount the VeraCrypt volume
mount_path = "/mnt/pfs_data"
Optionally, some additional values can be specified. Each is read as a string and passed directly to the corresponding flag of the VeraCrypt mount command, if specified:
pim, hash_alg, keyfiles, mount_options, filesystem_mount_options.
Requires access to VeraCrypt CLI
To unlock VeraCrypt volumes, PFS requires access to the veracrypt command. This means the VeraCrypt CLI must be installed on the system. In particular, on Windows it is not sufficient to have only the VeraCrypt GUI installed.
The VeraCrypt CLI must be installed separately. VeraCrypt is not automatically installed via TomatenPack.
Additionally, the PFS server requires privileges to mount volumes with the veracrypt command. Depending on the system configuration, this may mean the server must be started with sudo on Linux.
If this is a problem, no VeraCrypt volumes can be configured and you must fall back to file volumes.
global_password
The global password is a password that is requested when logging into a PFS instance. All users of a PFS instance must know the global password.
The global password is used to unlock and mount the VeraCrypt volumes. Accordingly, all VeraCrypt volumes of a PFS instance must use the global password for encryption.
If the main volume is a VeraCrypt volume, the global password configuration can be disabled. In this case, the global password will be checked by trying to unlock the main volume.
If the main volume is not a VeraCrypt volume, the global password can also be disabled. In this case, no global password is requested during login. Without VeraCrypt volumes, it is also possible to configure multiple global passwords. Users must then enter one of these passwords during login.
global_password.enabled- Specifies whether the global password should be enabled.
global_password.passwords- A list of passwords. It is sufficient to enter any one of them as a global password during login.
Each password is configured via its UTF-8 encoded hash:
Currently,
sha256is the only implemented type.
Example:
[global_password]
enabled = true
[[global_password.passwords]]
type = "sha256"
hash = "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
users
A list of user accounts set up for this PFS instance.
Each user has a name, as well as a password. The password is configured with the SHA-256 representation of the UTF-8 encoded password.
It is possible to disable the password for a user. In this case, the user should leave the user password field empty during login. If all configured users have their password disabled, the User Password input field is hidden from the login page.
For each user, it can be configured whether they should be an admin. Admin users have some privileges. For example, admins can start rebuild processes.
For more information on users, see the Concepts page.
Example of a user configuration:
name = "admin"
admin = true
password.enabled = true
password.hash = "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918"
default_theme
Allows configuring the theme new users see when accessing the PFS instance. Users are able to change their theme in the UI settings.
Available theme names are: light, dark, lightblue, darkblue, lightgreen, darkgreen, yellow.
PFS automatically detects if the user uses dark mode. Therefore, the default theme can be set for light and dark.
Example:
login_delay
The amount of seconds to wait after a failed login attempt. During this delay, all login attempts made by the same IP address will also fail.
The login delay helps mitigate brute force attacks.
| Mandatory | Type | Default |
|---|---|---|
| No | number | 1.0 |
max_user_devices
The maximum number of devices each user can be logged in with simultaneously.
| Mandatory | Type | Default |
|---|---|---|
| No | number | 100 |
token_length
The length of login tokens.
| Mandatory | Type | Default |
|---|---|---|
| No | number | 8 |
token_expire
The amount of seconds after which a login token expires. By default, login tokens expire after 5 minutes.
| Mandatory | Type | Default |
|---|---|---|
| No | number | 300 |
file_search_limit
Limits the number of results a file search can return.
| Mandatory | Type | Default |
|---|---|---|
| No | number | 5000 |
allow_unknown_users
See the unknown users section. This allows guest users to log in without a password. It is not recommended to enable this feature.
| Mandatory | Type | Default | Recommendation |
|---|---|---|---|
| No | boolean | false | false |
secure_cookies
Marks login cookies as Secure, meaning the cookie will only be sent over HTTPS.
Only disable this setting if you run PFS on your local machine (localhost) or cannot set up TLS on the server running PFS.
| Mandatory | Type | Default |
|---|---|---|
| No | boolean | true |
login_cookie_max_age
The Max-Age of the login cookies.
This specifies how many seconds the browser will remember the cookie.
When the browser "forgets" the cookie, you will be logged out.
If less than 0, the login cookie will be a session cookie, meaning the browser will remember the cookie until it is closed.
| Mandatory | Type | Default |
|---|---|---|
| No | number | -1 |
Example
This is a complete PFS app configuration for reference.
location = "/pfs"
[main_volume]
name = "main"
type = "veracrypt"
volume_path = "/home/pfs_main_volume.hc"
mount_path = "/mnt/pfs_main"
hash_alg = "sha512"
[[data_volumes]]
name = "data"
type = "veracrypt"
volume_path = "/home/pfs_data_volume.hc"
mount_path = "/mnt/pfs_data"
hash_alg = "sha512"
[[data_volumes]]
name = "data2"
type = "file"
path = "/home/pfs_data2"
[global_password]
enabled = true
[[global_password.passwords]]
type = "sha256"
hash = "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8" # "password"
[[users]]
name = "admin"
admin = true
password.enabled = true
password.hash = "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918" # "admin"
[default_theme]
light = "light"
dark = "dark"