# Pithyx: Administration > Running a box: users and groups, permissions, storage, shared folders, file services, network, apps and backups. ## Storage and pools > Disks, ZFS pools, datasets, importing and growing a pool, and why some disks are refused. Source: https://pithyx.org/docs/admin/storage/ Markdown: https://pithyx.org/docs/admin/storage.md The Storage app (administrators only) creates and manages the ZFS pools that hold all data on the box. Pithyx never uses the system disk for a pool, shows for every disk whether it may be used, and asks you to type the disk's serial number before it wipes a disk that holds data. Changes run in the background, and **Show commands** lists the exact commands before anything runs. ### Disk verdicts ![Storage, Disks, with the column For a new pool: two system disks Not available, four empty disks Available and one disk with partitions Needs confirmation](../../../../assets/screenshots/storage-disks.webp) _The Disks tab says for every disk whether a new pool may use it._ The column **For a new pool** shows one of three verdicts per disk: **Available**, **Needs confirmation** or **Not available**. Pithyx re-checks the verdict right before each command of a plan, so a disk that changed after you looked is caught. A disk is **Not available** when: - it holds the system (`/`, `/boot`, `/boot/efi` or `/var/lib/pithyx`, also through partitions, LVM, md or another pool): "Holds the system. Never used for pools." - it is read-only, or a file system on it is in use; - it is already part of a pool; - another disk reports the same serial number, so the two cannot be told apart; - it holds data but has no serial number to confirm with. A disk **Needs confirmation** when it has partitions, file systems or other signatures, or has not been checked yet. For a disk with contents Pithyx says "Holds data" and lists the partitions, file systems and signatures it found. Type its serial number exactly as shown to use it. Empty disks are **Available**. A replacement disk (see below) always needs its serial, even when it is empty. > **Everything on a confirmed disk is lost:** > > Confirming with the serial number clears the disk: Pithyx runs `zpool labelclear -f` on pool members, then `wipefs --all` on the partitions and the disk. There is no undo. Check the serial against the label on the disk. If a disk changed after the plan was shown, nothing is changed and you get [`storage.plan.stale`](https://pithyx.org/docs/reference/errors/#storage.plan.stale). A plan expires after 10 minutes ([`storage.plan.expired`](https://pithyx.org/docs/reference/errors/#storage.plan.expired)); show it again. ### Creating a pool ![The Create a pool wizard at step 2, Layout, for four disks with RAID-Z1 recommended and the cards Mirror, Mirror pairs, RAID-Z1, RAID-Z2 and Stripe](../../../../assets/screenshots/storage-layout.webp) _Step 2 of the wizard compares the layouts for the chosen disks and marks the recommended one._ Open Storage and choose **Create pool…**. The wizard has four steps: **Disks**, **Layout**, **Encryption** and **Name and check**. Disks are addressed by their `/dev/disk/by-id` names, so a pool survives a changed port or cable. | Layout | Minimum disks | Notes | | --------------------------- | ------------- | -------------------------------- | | Single disk (no redundancy) | 1 | exactly one disk | | Stripe | 2 | one failed disk loses everything | | Mirror | 2 | | | Mirror pairs | 4 | an even number of disks | | RAID-Z1 / RAID-Z2 / RAID-Z3 | 3 / 4 / 5 | one / two / three disks may fail | The wizard recommends a layout: one disk single, two disks mirror, three to five disks RAID-Z1, six or more RAID-Z2. With disks of different sizes every disk counts as large as the smallest, and the wizard tells you how much stays unused. The pool name starts with a lowercase letter, then lowercase letters, digits, `-` or `_`, at most 32 characters. The names `mirror`, `raidz`, `raidz1` to `raidz3`, `draid`, `spare`, `log`, `cache`, `special`, `dedup` and `pithyx`, and names that start with `c0`, are reserved. Every new pool gets the same options: `ashift=12`, `compression=lz4`, `xattr=sa`, `acltype=posixacl`, `atime=off`, `normalization=formD`. Pithyx then creates its dataset layout below `/pithyx`: `shares`, `homes`, `apps`, `system` and `cache` (quota 2.5 GiB, no compression, no automatic snapshots). A pool that Pithyx did not create has no `pithyx` dataset, and Pithyx creates nothing on it ([`storage.pool.not_prepared`](https://pithyx.org/docs/reference/errors/#storage.pool.not_prepared)). Other pool actions: **Replace…** (always asks for the serial), **Add hot spare…**, **Remove spare**, **Take offline**, **Bring online** and **Destroy pool…**. > **Destroying a pool:** > > **Destroy pool…** lists every dataset that goes with the pool and asks you to type the pool name ([`storage.pool.name_mismatch`](https://pithyx.org/docs/reference/errors/#storage.pool.name_mismatch) if it differs). Destroying or exporting is refused while disks are missing ([`storage.pool.disks_missing`](https://pithyx.org/docs/reference/errors/#storage.pool.disks_missing)) or the pool is suspended. A pool shows one of these states: Healthy, Degraded, Faulted, Offline, Unavailable, Removed, Suspended, Unknown or "Not connected". On a degraded pool a disk that comes back is rebuilt on its own (resilver). The daemon brings a returning disk back with `zpool online` and then `zpool clear`, each with a 30 second timeout. ### Datasets and restore points Under **Advanced**, **Datasets** > **Show datasets** lists datasets with Name, Used, Free, Limit, Compression and the folder or size. Dataset names use letters, digits, `.`, `-` and `_`, start with a letter or digit and are at most 64 characters. - **Rename…** moves the folder; shared folders follow. - **Limits…** sets Quota, Reservation, Compression and Record size. An empty quota or reservation means no limit. Compression: off, lz4, zle, zstd (levels 1 to 19) or gzip (1 to 9). Record size: a power of two from 4 KiB to 1 MiB, default 128 KiB. - **Delete…** asks for the full dataset name and lists child datasets and snapshots. Datasets of homes, apps and the system cannot be renamed or deleted ([`storage.dataset.managed`](https://pithyx.org/docs/reference/errors/#storage.dataset.managed)), and a dataset used by a shared folder must lose that shared folder first. Pithyx creates no volumes (block devices) yet: nothing in this version uses one, since iSCSI and virtual machines are not built. Volumes that exist on a pool show in the table and under Advanced, where you can delete them. The Storage app has no snapshot section. Snapshots reach the interface as restore points: one switch per shared folder in Settings > **Shared folders**, which takes a snapshot of the folder's dataset once a day and keeps the newest 7, and **Previous versions** in Files to get older versions back. See [Shared folders](https://pithyx.org/docs/admin/shared-folders/). Manual snapshots, holds, rolling back a dataset and other schedules are not in the interface. ### Importing and exporting **Import a pool…** scans the labels of every disk when you press **Scan disks**; the scan may wake sleeping disks and never runs by itself. A pool is first imported read-only as a preview (shown as "Read-only (preview)"): nothing is mounted and nothing changes. Then choose **Import for use…**, which imports it again and mounts the datasets that are safe to mount, or **Export** to end the preview ([`storage.import.preview_required`](https://pithyx.org/docs/reference/errors/#storage.import.preview_required) if you skip the preview). Datasets that cannot be mounted safely stay unmounted (`canmount=noauto`) with a reason: they would cover a system folder, hide something that is mounted there, share a folder with another dataset, or are encrypted and locked. Shared folders and apps on them stop. A pool last used by another system shows "Used by another system". It needs **Import it anyway (force)** and the pool name typed ([`storage.import.force_required`](https://pithyx.org/docs/reference/errors/#storage.import.force_required)). If the name is taken, choose **New name for the pool**. **Export…** unmounts the datasets and lists what becomes unavailable; the data stays on the disks and the pool can move to another system. ### Growing a pool **Add disks…** adds a new group of disks (a vdev) to the pool: single, mirror (2 disks), RAID-Z1 (3), RAID-Z2 (4) or RAID-Z3 (5). The dialog warns when the new group lowers redundancy, when its layout differs from the existing ones (this needs the pool name typed), and that the disks can never be removed from the pool again. **Expand with a disk…** widens a RAID-Z group by one disk. The pool stays usable, the step is irreversible and asks for the pool name, one expansion runs at a time ([`storage.pool.expanding`](https://pithyx.org/docs/reference/errors/#storage.pool.expanding)), and data already on the pool keeps its old ratio of data to parity until it is written again. > **Note:** > > The Storage app has no button to turn a single disk into a mirror later. ### Encryption Pool encryption is not available in this version. The wizard asks "Should the pool be encrypted?" and the answer is mandatory; **No encryption** works and **Encrypt with a key** is refused with [`storage.encryption.unavailable`](https://pithyx.org/docs/reference/errors/#storage.encryption.unavailable). A pool cannot be encrypted afterwards. ### Health and warnings Administrators get a desktop notification when a storage alert appears or worsens, and a second one that starts with "Resolved:" and names the problem when it clears. Alerts cover: pool suspended, degraded, faulted or offline, a missing disk, data errors, scrub errors, a pool 80 percent full (warning) or 90 percent full (critical), and failing or worrying SMART values. You can mute an alert for yourself. - **Scrub now**, pause, resume and stop. A schedule per pool: Off, Weekly or Monthly (default Monthly). - SMART is read with `smartctl -n standby` (30 second timeout), so sleeping disks stay asleep. States: Healthy, Warning, Failing, No SMART, Unknown. Short self-tests run weekly and long ones monthly by default; a sleeping disk is skipped and retried later, never woken. ## Shared folders > Create, edit and delete shared folders, set who may use them, and how the recycle bin and restore points protect their files. Source: https://pithyx.org/docs/admin/shared-folders/ Markdown: https://pithyx.org/docs/admin/shared-folders.md A shared folder is a ZFS dataset of its own on a pool, with its own space, rights and snapshots. Administrators create them in Settings > **Shared folders**; users see only the folders they have a right to. Deleted files go to a recycle bin (30 days by default) and daily restore points keep seven days of older versions. ### Creating a shared folder 1. Open Settings > **Shared folders** and choose **Create shared folder…**. 2. Enter a **Name**, pick the **Pool** and, if you like, a **Description (optional)**. 3. Check **Show commands** if you want to see what runs, then choose **Create shared folder**. If no pool exists, the dialog says "No pool is ready for shared folders yet. Create a pool in Storage first." The name has 1 to 64 characters: letters, digits, spaces, dots, dashes and underscores, not starting with a dot, unique without regard to case ([`fs.share.invalid`](https://pithyx.org/docs/reference/errors/#fs.share.invalid), [`fs.share.exists`](https://pithyx.org/docs/reference/errors/#fs.share.exists)). The description has at most 200 characters on one line. The names `global`, `home`, `homes`, `printers`, `print$` and `ipc$` are reserved ([`fs.share.name_reserved`](https://pithyx.org/docs/reference/errors/#fs.share.name_reserved)); `home` and `homes` are the [home folders](https://pithyx.org/docs/admin/home-folders/). The dataset gets a name derived from the folder name (lowercase, accents folded, other characters turned into `-`) at `/pithyx/shares/`, mounted at `//`. New folders start with restore points on. To limit the size of a shared folder, set a quota on its dataset in Storage (**Limits…**); the dialog has no size field. > **Note:** > > Registering an existing folder as a shared folder works only on development machines ([`fs.share.folder_dev_only`](https://pithyx.org/docs/reference/errors/#fs.share.folder_dev_only)). On a normal box every shared folder is a new dataset. ### Rules for folders ![The dialog Edit Photos with the network access switches and the rights: the group family with Read and write, the users with the access they end up with](../../../../assets/screenshots/shared-folders-edit.webp) _The edit dialog of a shared folder: network access per protocol and rights per group and user._ The edit dialog has three parts. - **Name and description.** Renaming changes only the name users see; the dataset keeps its name. - **Rights.** Per user and per group: no access, read, or read and write. A user gets the most that it or one of its groups is given, and administrators can always read and change everything. Every user is in the group users, shown as "every user". Changes apply right away. See [Permissions](https://pithyx.org/docs/admin/permissions/). - **Network access.** Switches **Offer over SMB**, **Show over SFTP**, **Offer over WebDAV** and **Offer over FTP**, all on by default, and **Require encryption over SMB** (off by default; older clients without SMB encryption cannot connect then). A user needs both the protocol right and the folder switch. See [File services](https://pithyx.org/docs/admin/file-services/). The overview table shows Name, Pool, Used, Description, Rights and Restore points. A user without any right does not see the folder at all ([`fs.share.not_found`](https://pithyx.org/docs/reference/errors/#fs.share.not_found)). If its pool is not connected, stopped or not mounted, the folder is unavailable ([`fs.share.unavailable`](https://pithyx.org/docs/reference/errors/#fs.share.unavailable)). > **Deleting a shared folder:** > > Deleting asks you to type the folder name and to choose: **Keep the data** (the dataset and files stay and remain visible in Storage) or **Delete the data for good** (dataset, files and every snapshot, no undo). ### Recycle bin and retention Every shared folder has a hidden folder `.pithyx-trash` at its root. Deleting in Files moves items there, and so do deletes over SMB, WebDAV and FTP. Deleting over SFTP removes files for good. The bin lists where each item came from, when it was deleted and when it goes for good, and offers **Restore**, **Delete for good** and **Empty recycle bin**. How users work with it is in [Files](https://pithyx.org/docs/user/files/#the-recycle-bin). The retention is per folder: 30 days by default, 0 keeps items until the bin is emptied, at most 3650 days. A cleanup runs hourly. Only administrators can change the retention, and the desktop has no setting for it today; it can only be set through the API (`PUT /api/shares/{shareId}/trash`, [`fs.trash.retention_invalid`](https://pithyx.org/docs/reference/errors/#fs.trash.retention_invalid) for a bad value). The bin shows "Deleted items are kept for {days} days." ### Restore points Restore points are daily snapshots; the newest 7 are kept (a box that was off for a while keeps its last points instead of losing them). They only use space for files that changed or were deleted, and a deleted file frees its space after the last point holding it expires. Each folder has a switch in the column **Restore points** ("Daily, kept 7 days" or "Off"); **What are restore points?** explains them to the user. Users restore older versions with **Previous versions** in Files, and Windows shows them as "Previous versions". They help against accidental deletion and ransomware but are no replacement for a backup on another device, because they live on the same disks. Restore points are not available for a shared folder registered from an existing folder (development machines only), because it has no dataset of its own. ### Encryption over SMB The per-folder switch **Require encryption over SMB** sets `server smb encrypt = required` for that folder; otherwise a connection is encrypted when the client asks for it. The server always requires SMB 3 and signing. This is separate from pool encryption, which is not available (see [Storage](https://pithyx.org/docs/admin/storage/#encryption)). ## Home folders > Every user gets a private home folder on the home pool; administrators pick the pool, set quotas and decide what happens to the home of a deleted user. Source: https://pithyx.org/docs/admin/home-folders/ Markdown: https://pithyx.org/docs/admin/home-folders.md Status: draft Every user gets a home folder of their own: a private place for files that only that user and the administrators can open. Users see it as **home** in Files and over every file service; administrators also see every other home below **homes**. Settings > **Home folders** shows on which pool the homes are, their space and quotas, and the homes of deleted users. ### Where users find it | Where | The user's own home | Every home (administrators only) | | -------------- | ------------------------------ | ------------------------------------------------------------ | | Files | **home**, first in the sidebar | **homes** in the sidebar, which lists every home as a folder | | SMB | `\\\home` | `\\\homes` | | SFTP | The folder `home` | The folder `homes`, one folder per user | | WebDAV and FTP | The folder `home` at the top | The folder `homes`, one folder per user | A home is used like a shared folder: it has its own [recycle bin](https://pithyx.org/docs/user/files/#the-recycle-bin), files created there belong to the user, and the user needs the right for a protocol to reach it over that protocol (see [File services](https://pithyx.org/docs/admin/file-services/)). Nobody else can be given access to a home, and it never appears in Settings > **Shared folders**. Apps that may read the user's shared folders see the user's own home as well, never anybody else's. > **Caution:** > > Files deleted in the SMB share `homes` do not go to a recycle bin; they are gone. Each home is a dataset of its own, and Samba cannot move a file across them. Over `home`, in Files, SFTP, WebDAV and FTP the recycle bin works as usual. ### The home pool Each home is a dataset `/pithyx/homes/`, mounted at `//homes/`. When the first pool with the Pithyx layout exists, it becomes the home pool, and every user without a home gets one there; a user created before that gets the home as soon as the pool is there. Users created later get theirs at once. The **Users** page shows each home's path, or "No pool yet". To move every home to another pool, choose the pool under **Move to** and **Move home folders**. A pool is offered only while it is online, writable, has the Pithyx layout and is unlocked; it also needs room for all homes ([`homes.pool.no_space`](https://pithyx.org/docs/reference/errors/#homes.pool.no_space)). The move runs as a job, one home after the other: 1. The home turns read-only, so it can be read but not changed while it is copied. 2. A snapshot of it is copied to the new pool with its files, owners, rights and recycle bin. 3. The home is used from the new pool, and the old copy is deleted with its snapshots. If one home cannot be moved, it stays where it was and can be changed again; the homes moved before stay moved, and the home pool stays the old one until every home has arrived. Start the move again once the cause is fixed. Only one move runs at a time ([`homes.move.running`](https://pithyx.org/docs/reference/errors/#homes.move.running)). A home on a pool that is gone (destroyed, or exported and not imported again) cannot be moved; the move leaves it where it is. If the pool will not come back, **Delete** the home on this page: the user gets a new, empty home on the home pool. ### Quotas **Default quota** applies to every home without its own quota; leave it empty for no limit. **Quota** on a home sets the user's own: **Use the default quota**, **No limit** or **Own quota**. A quota is at least 1 MiB ([`homes.quota.invalid`](https://pithyx.org/docs/reference/errors/#homes.quota.invalid)) and counts the files and the snapshots of the home. When a home is full, writing to it fails until files are deleted and the recycle bin is emptied. ### When a user is deleted Deleting a user in Settings > **Users** asks what happens to the home folder: - **Keep it** (the default): the home stays, renamed to `.deleted-`, so the name is free for a new user. Administrators see it below **homes**. - **Move its files into a shared folder**: a new folder named after the user in the shared folder you choose gets every file, then the home is deleted with its recycle bin. This runs as a job. - **Delete it with every file**: the home goes with its files, recycle bin and snapshots, after you typed the user name. A kept home appears on the **Home folders** page with "user deleted". **Move into shared folder** and **Delete** do the same as above later; **Delete** asks you to type the folder name. A new user with the same name never gets an old home: a home that belongs to another user id is renamed out of the way first. ### Limits - Homes have no `Desktop` folder for the desktop items yet. - A home is never shared with other users; use a shared folder for that. ## Users and groups > Create users and groups, give them rights, deactivate or delete accounts, and what happens to their home folders. Source: https://pithyx.org/docs/admin/users-and-groups/ Markdown: https://pithyx.org/docs/admin/users-and-groups.md Administrators manage accounts in Settings > **Users** and Settings > **Groups**. Every Pithyx user is also a Linux account with an own user id, so files they create belong to them. Passwords have at least 8 characters, and only an administrator can set a new password for another user. ### Creating a user Choose **Create user** and fill in: - **User name**: lowercase letters, digits, hyphens and underscores, starting with a letter or underscore, at most 32 characters. System names such as `root`, `daemon`, `sshd`, `pithyx`, `docker` and `users`, and names starting with `systemd-`, are refused ([`auth.username.reserved`](https://pithyx.org/docs/reference/errors/#auth.username.reserved)). A name a system account may already use is refused with [`users.account.refused`](https://pithyx.org/docs/reference/errors/#users.account.refused). - **Display name (optional)**: at most 64 characters. - **Password**: 8 to 1024 characters. Well-known passwords are refused ([`auth.password.too_common`](https://pithyx.org/docs/reference/errors/#auth.password.too_common)); there are no other composition rules. - **Groups**. Every user is also in the group users. User ids come from 20000 to 29999 and are never given out again. Group ids come from 30000 to 39999. The shell is `/usr/sbin/nologin` unless the user has the SSH login right and SSH logins are switched on. A new user can sign in to the desktop, use SMB, and use the apps Files and Viewer; you can change this in the rights dialog. The password is also set for the Linux and Samba accounts. A user who does not have one yet is marked "Not ready for SMB and SFTP yet: the user signs in once on the web, or you set a new password." Badges in the list: Administrator, Two-factor, Deactivated. ### Groups Choose **Create group** in Settings > **Groups**. A group has a name (same rules as user names, and it may not start with `pithyx-`), a **Description (optional)** of up to 200 characters, and members. Rights given to a group apply to all its members. Deleting a group keeps its members; files keep the group id, and it is never given to another group. The built-in group users contains every user and cannot be renamed, deleted or given members by hand ([`users.group.builtin`](https://pithyx.org/docs/reference/errors/#users.group.builtin)). ### Special rights The rights dialog of a user or group has four special rights: "Administrator (may change everything)", "Sign in to the desktop", "Sign in over SSH with a shell" and "Restart and shut down". Further sections cover file services, apps and shared folders. How rights combine is on [Permissions](https://pithyx.org/docs/admin/permissions/). Without "Sign in to the desktop" a user cannot sign in to the web desktop; a user who loses it is signed out with the next request. ### Deactivating and deleting **Deactivate** gives the user no rights at all and signs them out; **Activate** gives the rights back. You cannot deactivate yourself ([`users.user.self`](https://pithyx.org/docs/reference/errors/#users.user.self)), and the last administrator can neither be deactivated, deleted nor lose the right ([`users.user.last_admin`](https://pithyx.org/docs/reference/errors/#users.user.last_admin)). **Delete** asks you to type the user name and what happens to the user's home folder: **Keep it** (the default), **Move its files into a shared folder** or **Delete it with every file**, see [Home folders](https://pithyx.org/docs/admin/home-folders/#when-a-user-is-deleted). The account goes, files the user created in shared folders stay, and the user id is never given to anyone else. Grants, group memberships and the user's jobs and notifications are removed. To reset a password, use **New password** on the user: the user is signed out everywhere, and SMB and SFTP use the new password as well. Pithyx has no reset by email. If the only administrator forgot the password, the recovery key from first setup is the only way, see [Security](https://pithyx.org/docs/admin/security/#the-recovery-key). ### Home folders Each user gets a private home folder, a dataset `/pithyx/homes/` at `//homes/`, owned by the user. The list shows its path, or "No pool yet" until a pool with the Pithyx layout exists. Its pool, quotas and the homes of deleted users are on [Home folders](https://pithyx.org/docs/admin/home-folders/). ## Permissions > How rights are given to users and groups, how shared folder, protocol and app access combine, and when a change takes effect. Source: https://pithyx.org/docs/admin/permissions/ Markdown: https://pithyx.org/docs/admin/permissions.md Pithyx gives rights to users and to groups. A user's effective rights are the union of the user's own rights and those of all its groups, including the built-in group users. There are no deny rules, and administrators have every right. A deactivated user has none. ### The model A right is one of: - a special right: administrator, sign in to the desktop, sign in over SSH with a shell, restart and shut down; - a protocol: SMB, SFTP, WebDAV or FTP; - access to a shared folder: no access, read, or read and write (the highest wins); - access to an app. The rights dialog of a user or group says it plainly: the user has these rights and everything its groups give it; there are no rules that take a right away. A group never overrules a user, and you cannot deny what a group grants. ### Shared folder access Set the levels **No access**, **Read** and **Read and write** per user or group in the rights dialog, or per folder in the folder's edit dialog, which also shows what a user "ends up with". Administrators always read and write every folder. Pithyx makes the file system agree: it creates Linux groups per folder and sets POSIX ACLs, so SMB, SFTP, WebDAV, FTP and the Files app see the same rights. ACL changes made from an SMB client are ignored. A folder without access is hidden, not refused ([`fs.share.not_found`](https://pithyx.org/docs/reference/errors/#fs.share.not_found)); writing with read access gives [`fs.share.read_only`](https://pithyx.org/docs/reference/errors/#fs.share.read_only). ### Protocol access A user reaches a folder over a protocol only when both allow it: the user (or a group) has the protocol right, and the folder has the matching **Offer over ...** switch. A new user has SMB only. The server-side switches are on [File services](https://pithyx.org/docs/admin/file-services/). SSH with a shell is a right, not a protocol: it needs the right and the **SSH logins** switch. Protocol sign-ins use the password only; two-factor sign-in applies to the web desktop. ### App access Files and Viewer are given by right (new users get both), About is open to everybody, and Storage, Settings, Resource Monitor, Log Center and Store are for administrators only. For apps from the Store, **Who may use the app** is **Everybody**, **Administrators only** or **Selected groups and users**; administrators may use every app. Per app, administrators can turn permissions off to take them from the app. More on [apps and the Store](https://pithyx.org/docs/admin/apps-and-store/). ### When a change applies Changes apply at once. Open sessions are re-authorized over the WebSocket, and a user who loses desktop sign-in is disconnected. For WebDAV and FTP the right is checked on every request. A correct protocol password is remembered for 5 minutes, and a new password ends that at once. Open windows of an app get a permission change within a few minutes. Web sessions end after 7 days without use or 30 days in total; deactivating, deleting or resetting the password ends them immediately. ## File services > Switch SMB, SFTP, WebDAV and FTP on or off, with their ports, defaults and limits. Source: https://pithyx.org/docs/admin/file-services/ Markdown: https://pithyx.org/docs/admin/file-services.md File services let other computers open shared folders over the network. Settings > **File services** has one switch per service: SMB, SFTP, WebDAV and FTP. Users sign in with their Pithyx user name and password. Pithyx has no NFS and no guest access. In a fresh installation SMB is on and the other services are off. Which user may use which service is set per user or group (see [Permissions](https://pithyx.org/docs/admin/permissions/)); which folders a service offers is set per folder ([Shared folders](https://pithyx.org/docs/admin/shared-folders/)). A user whose password Pithyx does not know yet for SMB and SFTP has to sign in once on the web, or an administrator sets a new password. ### SMB Switch **Offer shared folders over SMB**; the default workgroup is `WORKGROUP` (1 to 15 characters: letters, digits, dot, dash, underscore, starting with a letter or digit; stored in upper case). SMB serves network drives to Windows, macOS and Linux on port 445. Only signed connections of current systems (SMB 3) are accepted, encrypted when the client asks for it, and always encrypted for shared folders with **Require encryption over SMB** on (see [Shared folders](https://pithyx.org/docs/admin/shared-folders/#encryption-over-smb)); guests are refused and NetBIOS is off. Pithyx writes `/etc/samba/smb.conf` itself on every change; put your own Samba settings into `/etc/samba/pithyx.local.conf`, which Pithyx includes and never writes. The file is checked with `testparm` before Samba reloads. Connect from Windows File Explorer with `\\
\`, from macOS or Linux with `smb://
`. The box does not announce itself on the network (no WS-Discovery, no mDNS), so clients connect by address. Deletes go to the recycle bin, and the daily restore points show as "Previous versions" in Windows. When a user's access changes (a right on a shared folder, a group membership), Pithyx ends that user's open SMB connections. The computer reconnects by itself within seconds and gets the new rights at once; files the user had open over SMB are closed, as after a short network outage. ### SFTP Switch **Offer shared folders over SFTP**. It is encrypted file transfer over SSH, for example with FileZilla, WinSCP or the `sftp` command: `sftp://
`. Users see only their shared folders and get no shell. It uses the system's `sshd` through a drop-in file, with password sign-in only. Switching SFTP off only stops letting Pithyx users in; it does not stop SSH for other accounts. Turning it on runs `systemctl enable --now ssh.service`. The sshd configuration is checked with `sshd -t` and reverted if refused. SSH with a shell is a separate switch, see [Security](https://pithyx.org/docs/admin/security/#ssh). ### WebDAV Served by the daemon itself at `/webdav/` on the box's web address (`https://:7484/webdav/`), with Basic authentication using the Pithyx name and password. The root lists the shared folders the user may use; deletes go to the recycle bin. A user needs the WebDAV right and the folder switch **Offer over WebDAV**. > **No encryption yet:** > > WebDAV runs over the box's HTTPS. Clients that check certificates (Windows, macOS) connect once the device trusts the box's root; see [Certificates](https://pithyx.org/docs/admin/certificates/). ### FTP For devices and programs that know neither SFTP nor WebDAV, such as scanners. **Offer shared folders over FTP with TLS** uses explicit FTPS (`AUTH TLS`); it presents the box's certificate (see [Certificates](https://pithyx.org/docs/admin/certificates/)) and the page shows its SHA-256 fingerprint. **Also allow plain FTP without encryption** is off by default and carries a warning; switching it off again ends plain sessions. - Control port 21, passive data ports 50000 to 50099. Only passive mode works (`PORT` and `EPRT` are answered with "502 Only passive mode"). - Idle timeout 10 minutes, data timeout 30 seconds. - Failed sign-ins are limited to 5 per user and 30 per address in 5 minutes. ### Limits - SMB 3 only; older clients cannot connect. - SFTP accepts passwords only. - Rights cannot be changed from a client (SMB ACL edits are ignored). - Protocol sign-ins do not use two-factor sign-in. - The box is not announced on the network (no WS-Discovery, no mDNS). ## Network > Network cards, static addresses, bonds, VLANs, DNS and the 60 second confirmation that protects you from locking yourself out. Source: https://pithyx.org/docs/admin/network/ Markdown: https://pithyx.org/docs/admin/network.md Settings > **Network** (administrators only) shows the box's network cards and changes their addresses, bonds, VLANs, host name, name servers and default route. Every change waits 60 seconds for your confirmation and goes back on its own without it, so a wrong address cannot lock you out. If you do lock yourself out, the console menu on the box itself resets the network. ### Cards and addresses The page lists network cards, bonds and VLANs with their state (Connected, No cable, Off), IPv4 method (Automatic (DHCP), Static, Off, Set outside Pithyx), addresses, gateway, name servers, hardware address, MTU, speed and duplex. A card without settings uses DHCP. Per interface you can switch it on or off, choose IPv4 DHCP, static or off, and IPv6 automatic (router and DHCPv6), static or off. A static address is written with its prefix length, for example `192.168.1.10/24` or `2001:db8::10/64`; the gateway is optional and must be inside the network. The MTU is 1280 to 9000 (576 to 9000 with IPv6 off); empty means 1500. **Back to DHCP** removes a card's own settings. Changes are collected as a draft ("Changes not applied yet") and applied together with **Apply…**, or dropped with **Discard changes**. Pithyx refuses a change that would leave the box without any interface that has an address ([`network.config.unreachable`](https://pithyx.org/docs/reference/errors/#network.config.unreachable)). Pithyx writes systemd-networkd and systemd-resolved files for this; there is no Wi-Fi or bridge setting. The firewall is set with the file services (see [Security](https://pithyx.org/docs/admin/security/#open-ports)). ### Bonds **Add bond** combines at least one card (cards with their own settings must go back to DHCP first) in a mode: - **Active-backup**: one card carries the traffic, another takes over when its cable fails. Works with every switch; you can pick a primary card. - **LACP (802.3ad)**: all cards together; the switch ports must form an LACP group. The LACP rate is Slow (every 30 seconds) or Fast (every second). - **Adaptive load balancing**: all cards send and receive without help from the switch. Names of bonds and VLANs have up to 15 lowercase letters, digits, dots, hyphens or underscores, start with a letter, and must not start with a prefix that Docker, the apps' networks, containers or VPNs use: `px-`, `veth`, `docker`, `br-`, `ve-`, `vb-`, `vz-`, `vt-`, `virbr`, `tun`, `tap` or `wg`. ### VLANs **Add VLAN** takes a parent (a card or a bond) and a VLAN ID from 1 to 4094, as the switch port tags it (802.1Q). ### DNS, search domains and the default route The card "Host name and name servers" holds: - **Host name**: letters, digits and hyphens, 1 to 63 characters, no leading or trailing hyphen. Windows networks see its first 15 characters. - **Name servers**: up to 4. Empty uses the ones DHCP announces; set ones replace them. - **Search domains**: up to 6. - **Default route via**: Automatic, or a chosen interface that is enabled and has settings and a gateway. ### The confirmation timer ![Settings, Network, with the banner 55 seconds left to keep the new network settings and the buttons Keep and Undo now](../../../../assets/screenshots/network-confirm.webp) _After Apply the page counts down. Without Keep the box goes back to the previous settings._ After **Apply…** a banner shows "{seconds} left to keep the new network settings" with **Keep** and **Undo now**. Without confirmation within 60 seconds, after **Undo now**, after a failed apply ([`network.apply.failed`](https://pithyx.org/docs/reference/errors/#network.apply.failed)) or after a daemon restart, the previous settings come back. Only one change can wait at a time. If the page stops answering because the address changed, open the box at its new address and keep the change there; the dialog lists the addresses. > **Note:** > > Backups do not contain network settings (see [Backup and restore](https://pithyx.org/docs/admin/backup/)), because cards are named differently on other hardware. ### Locked out: the console menu On the box's own screen, the console shows the addresses and a menu that needs no password, because physical access is the proof: - `[s]` Set a static address: card number, address with prefix length, gateway (empty for none) and name servers (empty keeps them). The same 60 second timer applies. - `[r]` Reset the network to DHCP: after "Reset every network card to DHCP and remove bonds, VLANs and name servers? [y/N]", every card goes back to DHCP. The host name stays. No timer. - While a change waits: `[k]` keep it, `[u]` undo it. Only IPv4 static addresses can be set from the console. ## Security > Transport, open ports, physical access, SSH, two-factor sign-in, the recovery key and what leaves the box. Source: https://pithyx.org/docs/admin/security/ Markdown: https://pithyx.org/docs/admin/security.md Pithyx keeps everything on the box: no telemetry, no cloud account, no phone-home. The web desktop speaks HTTPS with a certificate from the box's own certificate authority. This page covers transport, open ports, physical access, SSH, two-factor sign-in, the recovery key and the few connections the box makes on its own. ### HTTPS and certificates The box serves the desktop and WebDAV on `https://:7484`, over TLS 1.2 or 1.3 with HTTP/2. Ports 80 and 443 redirect there, except for the domains of the [reverse proxy](https://pithyx.org/docs/admin/reverse-proxy/), and a request with plain `http://` on 7484 is redirected to `https://` on the same port. The box is its own certificate authority, so a browser warns about its certificate until the device trusts the box's root: download it in Settings > **Certificates** and install it once per device (see [Certificates](https://pithyx.org/docs/admin/certificates/)). FTP over TLS presents the same certificate. The authority may sign only local names and private addresses unless an administrator creates one without that limit, so a device that trusts it never accepts a certificate from the box for a public website. The box sends no HSTS header: browsers do not let anyone pass a certificate warning on an HSTS host, and the box's certificate is untrusted until a device trusts its root. The session cookie is `HttpOnly`, `SameSite=Strict` and `Secure`. State-changing requests need the header `X-Pithyx-Request`. SMB 3 and SFTP encrypt their own traffic. The live system of the installer is the one exception: it speaks plain HTTP, because it has no certificate yet and asks for no password. ### Open ports Pithyx has a firewall that lets in only the web interface and the file services that are switched on, over IPv4 and IPv6: the web desktop and WebDAV on 7484, 80 and 443 for the redirect and the reverse proxy, the ports of enabled reverse proxy streams, SMB on 445 (on from the first start), SFTP and SSH on 22, FTP on 21 with the passive ports 50000 to 50099. Switching a service off in Settings > **File services** also closes its port. Everything else is dropped, except answers to the box's own connections, DHCP replies and the usual ICMP messages (ping among them) and those IPv6 needs. App backends publish no ports at all. With **Only private networks may use the file services** (section **Firewall** on the same page, off by default), SMB, SFTP, SSH and FTP answer only computers in private networks (10.x, 172.16 to 31.x, 192.168.x, link-local and IPv6 ULA); the web interface stays reachable either way. Leave it off if you reach the box through a router from another network or over a VPN with public addresses. If the rules cannot be applied, the setting is still saved and the error is [`network.firewall.failed`](https://pithyx.org/docs/reference/errors/#network.firewall.failed). Pithyx offers no remote access of its own; keep the box behind a router and reach it from outside over a VPN rather than forwarding these ports. ### Physical access Whoever can use the box's console, in person or through remote management (BMC, IPMI), can get root: the boot menu has no password, and the system disk is not encrypted. A password at the console would therefore protect nothing, so the console menu and the [recovery menu](https://pithyx.org/docs/install/updates/#the-recovery-menu) ask for none and only ask you to confirm what you do. The box has no login at the console at all: tty1 shows only the console menu, the other consoles are switched off, and root stays locked. Put the box where strangers cannot reach it, and secure its remote management. Each box writes its own ZFS host id during the installation, so two boxes installed from the same stick never claim to be the same system. A pool from before a reinstall therefore counts as used by another system and needs the forced import (see [Recovery](https://pithyx.org/docs/install/recovery/#importing-the-pools-again)). Pool encryption is not available in this version; the storage wizard says it comes with the key vault. A key kept in a vault on the system disk protects only against stolen disks, not against someone who has the whole box or its console. ### SSH SSH is off by default. Two separate switches on the **File services** page: - **Offer shared folders over SFTP**: file transfer only, no shell. - **SSH logins** with the switch **Let users with the SSH login right sign in with a shell**. Users with the right "Sign in over SSH with a shell" get a shell with their own rights, with password or public key, without forwarding, tunnels or X11. A shell reaches the whole system with the user's rights, so give the right only to people who need it. Switching either off never stops SSH for the system's own accounts; Pithyx never stops `sshd`. A shell sign-in greets with the Pithyx logo, the version and a warning that changes made by hand in the shell can break the box or be undone by Pithyx or an update (in English for now). The host keys are made on the first boot and are part of the configuration backup. The administrator you created in the installer is in the group `sudo` and gets root with `sudo` and its own password (it needs to have signed in to the web interface once since the installation, so the system knows the password). Other administrators get no `sudo`. Root itself stays locked; what you do with it is up to you. `sudo`, `nano`, `htop`, `curl`, `wget` and `git` are installed. ### Two-factor sign-in Every user can turn on two-factor sign-in (TOTP) in the account menu under **Two-factor authentication**: scan the QR code or enter the key, enter a code, choose **Turn on**, and keep the 10 recovery codes shown once; each works once. The codes use SHA-1, 6 digits and 30 seconds. At sign-in, enter the code or choose "Use a recovery code instead"; the challenge is valid for 5 minutes. Turning it off needs the password. After 5 failed attempts for one user from one address, or 30 from one address, in 5 minutes, further attempts are refused for a while. Sessions end after 7 days without use or 30 days in total. SMB, SFTP, WebDAV and FTP use the password only. ### The recovery key First setup shows the recovery key once (`PTHX-` followed by 26 characters). It is the only way to reset the administrator password. To use it, choose "Forgot password?" on the sign-in page, then enter the key, the user name of an administrator and a new password. This signs that user out everywhere, turns off two-factor sign-in for that user and issues a new recovery key; the old one stops working. There is one key for the whole box and it is part of the configuration backup. Without the key and the password, the system has to be reinstalled. Other users ask an administrator for a new password. ### What leaves the box The box sends no data to the Pithyx project. These are the outbound connections Pithyx itself makes: - **System updates**: once a day at a random time chosen by each box (switch it off with **Check for updates daily** in Settings > **Updates**), and on **Check now**, the box reads the channel file of its update source (by default the project's releases on GitHub) and Debian's package lists from `deb.debian.org`. An update you install downloads its file from the same source. See [System updates](https://pithyx.org/docs/install/updates/). - **App catalogs**: git over HTTPS or SSH to each enabled catalog repository (the official and the community catalog are on and fetched from GitHub by default), once a day at the set time with a random delay of up to an hour, when you add a catalog, and on **Check now**. Switch a catalog off to stop it. - **Container images** of catalog apps from the registry the catalog names, unless the package carries them. - **Time**: with **Time servers** in Settings > **Regional settings** empty, the box uses the Debian defaults through systemd-timesyncd, which contacts public time servers. - **Apps** that you allow the permission "Internet" get a second network with outbound access to the internet; other apps have none. Devices in your local network are reachable only for apps with the permission "Local network". Logs stay on the box under `/var/log/pithyx/`. Secrets are masked in logs. Passwords are stored as Argon2id hashes. ## Apps and the Store > Install apps from catalogs or a file, choose the app pool, set update rules, and how backends run in Docker. Source: https://pithyx.org/docs/admin/apps-and-store/ Markdown: https://pithyx.org/docs/admin/apps-and-store.md Only administrators install apps, in the Store app. An app is a frontend that the daemon serves plus, optionally, a backend of containers. Apps come from catalogs (git repositories with a signed index) or from a package file (`.pithyxapp`). All app data lives on one pool you choose at the first install, never on the system disk. ### The Store The Store has the tab **Installed**, **Updates** while updates wait (with their number), **Official** and **Community** while that catalog is on, and **Own** while you added a catalog of your own, and a gear for **Store settings**. Official apps are reviewed, built and signed by the Pithyx project; community apps are from developers outside the project and reviewed by it before they are published; **Own** shows apps of catalogs you added, which the project does not verify. Badges read "Pithyx", "Community" and "Unverified" (also for apps installed from a file). Search covers name, description and developer. Users open installed apps from the Pithyx menu; see [Apps](https://pithyx.org/docs/user/apps/). ### Installing from a file Choose **Install from file** on the **Installed** tab (or **Update from file** in an app's detail) and select a package. The dialog lists the permissions the app asks for, the folders it needs, whether it brings a backend, a warning if a container runs as root, special rights, **Who may use it**, and **Pool for app data**. For a package from a file it warns "This package comes from a file and is not verified." Limits of an upload: the file at most 256 MB, unpacked at most 512 MB and 10 000 entries, the manifest at most 64 KB ([`app.package.too_large`](https://pithyx.org/docs/reference/errors/#app.package.too_large)). A checked package waits 15 minutes for you to confirm. The ids `org.pithyx.*` are refused from files. A version can be installed, updated, reinstalled (replaces its files) or downgraded; a downgrade may be refused ([`app.package.downgrade_unsupported`](https://pithyx.org/docs/reference/errors/#app.package.downgrade_unsupported)), then use **Back to the previous version**. **Uninstall** asks you to **Keep the data** (installing again finds it, with the app's user id; the install dialog then says so) or **Delete the data** (databases, settings, files and snapshots; irreversible). Shared folders mapped into the app stay either way. Disabling an app ("Users can open the app" off) keeps its data and access. An app asks for storage; you map each requested folder to a folder in a shared folder, read only or read and write: choose the shared folder, open the folder you want (or **New folder** to create it there) and save; the shared folder itself works too. Required ones must be mapped or the backend does not start. The install dialog offers the mapping as its last step and shows **Open app** once every required folder has one; until then the app's window says that it waits for a folder. The switch "Send debug messages to the Log Center" turns on debug logging for one app. ### The app pool At the first install you pick **Pool for app data**: "Every app keeps its data on this pool. It cannot change while an app is installed." Without a pool the Store says to create one in Storage first. The pool must be imported, online (or degraded), writable, unlocked and set up by Pithyx. Each app gets a dataset `/pithyx/apps/`, mounted at `//.pithyx/apps/`. Docker's data root is `//.pithyx/docker`. If the pool is missing or locked, apps on it show "Pool not available" and nobody can open them until it is back. App containers run with user ids from 40000 to 49999. ### Updates and rollback ![Store settings with the update policy Tell administrators, the daily check time 03:00, the channel Stable and the catalog list](../../../../assets/screenshots/store-update-settings.webp) _The Store settings: what happens with new versions, when the box checks and which channel it follows._ Open the gear, then **Updates**. The policy "When a catalog has a newer version" is **Install it**, **Tell administrators** (default) or **Do nothing** (the update is only listed in the **Updates** tab). An update that asks for new permissions or special rights never installs on its own. The daily check time defaults to 03:00 (box time zone) plus a fixed random delay of 0 to 3600 seconds per box; **Check now** runs it at once. An app can follow its own policy in its detail. Administrators get the notifications "App updates" and "Catalog not fetched". Before an update Pithyx takes a snapshot of the app's dataset. If the new version does not start, the old one comes back. **Back to** and the version number (for example **Back to 1.2.0**) returns to the previous version, with the app's data as it was before the update; changes and snapshots made since are lost. Only the one previous version is kept. The channel is **Stable** (versions the catalogs' owners released, default) or **Beta** (every new version as soon as a catalog publishes it, before its release). ### Catalogs and trust The official and the community catalog are both on by default; the tab **Community** says that its apps come from developers outside the project, reviewed by the project but not vouched for like its own. Switch the community catalog off in the Store settings if you want only official apps; switching it on again asks "Use the community catalog?". Neither can be removed ([`store.catalog.built_in`](https://pithyx.org/docs/reference/errors/#store.catalog.built_in)). To add your own, enter a **Repository URL**: `https://...` for a public catalog or `git@host:owner/repository.git` for a private one (no credentials in the URL, at most 500 characters; [`store.catalog.url_invalid`](https://pithyx.org/docs/reference/errors/#store.catalog.url_invalid)). For a private catalog over SSH the box generates an ed25519 deploy key and shows its public line; add it to the repository as a read-only deploy key and choose **Fetch now**. The server's host key is pinned at the first connection. A fetch times out after 3 minutes. A fetch state is Off, Not fetched yet, Up to date, Fetch failed or Fetching; a failed fetch keeps the last verified copy. Indexes of the official and community catalogs carry an Ed25519 signature checked against keys built into the daemon, and every file's hash is checked. Custom catalogs are unsigned: "Apps of your own catalogs are not checked by the Pithyx project. Add only catalogs you trust." The ids `org.pithyx.*` come only from the official catalog. ### Backends and Docker A backend is a Compose subset with images pinned by digest, checked against a fixed allowlist. The box runs it in Docker (Debian's `docker.io`), which the daemon starts only while a backend app is installed and its pool is available. Containers run in a user namespace, on an own internal network without internet unless the app has the permission "Internet", and cannot reach host services. Other devices in your network (router, printer, other servers) are reachable only with the permission "Local network"; "Internet" alone does not include them. Containers that do not run as root have no Linux capabilities. Pithyx 1.0.0 refuses the Docker socket and host-wide rights ([`app.elevated.unsupported`](https://pithyx.org/docs/reference/errors/#app.elevated.unsupported)). A container as root is only allowed when the app declares it, and the install dialog warns. A backend with lifecycle `always` runs whenever it can; `onDemand` starts when a user opens the app (a request waits up to 30 seconds) and stops 10 minutes after the last window closed. A failed start is retried after 1 minute. Container output goes to the Log Center as source `app/`. ## Certificates > HTTPS on 7484, the box as its own certificate authority, trusting it on your devices, certificates for other devices and a certificate of your own. Source: https://pithyx.org/docs/admin/certificates/ Markdown: https://pithyx.org/docs/admin/certificates.md The box speaks HTTPS on port 7484 with a certificate from its own certificate authority; ports 80 and 443 redirect there, except for the domains of the [reverse proxy](https://pithyx.org/docs/admin/reverse-proxy/), which present certificates of their own. Install the authority's root once on each device and the browser trusts the box, its reloads come from the cache and FTPS clients accept it. Everything on this page is in Settings > **Certificates** (administrators only). ### Why the browser warns The first time you open `https://:7484`, the browser warns that the connection is not private: it does not know who signed the box's certificate. That is expected. Continue to the page, sign in and trust the box as described below; the warning is gone on that device afterwards. Until then, Chromium-based browsers keep nothing from the box in their cache: every reload loads the desktop again, and every app window loads its app again. ### Trusting the box on a device In **Trust this box**, choose **Download root certificate** (the file `pithyx-root-ca.crt`; anyone may download it, also before signing in, from `/api/system/tls/root-ca.crt`). Before you trust it, compare its SHA-256 fingerprint with the one the page shows. Then: - **Windows**: open the file, choose **Install Certificate**, **Local Machine**, then the store **Trusted Root Certification Authorities**. - **macOS**: open the file in Keychain Access (keychain **System**), open the certificate and set **Trust** to **Always Trust**. - **iPhone and iPad**: open the file in Safari, install the profile under Settings, General, VPN and Device Management, then switch it on under Settings, General, About, Certificate Trust Settings. - **Android**: Settings, Security, Encryption and credentials, Install a certificate, CA certificate, then pick the file. - **Linux**: copy the file to `/usr/local/share/ca-certificates/` and run `sudo update-ca-certificates`. - **Firefox** keeps its own store: Settings, Privacy and Security, Certificates, View Certificates, Authorities, Import, and trust it to identify websites. ### The certificate authority The authority has two parts: a root (ECDSA P-384, 20 years) that devices trust, and an intermediate (ECDSA P-256, 5 years) that signs every certificate. The intermediate renews itself a year before it ends; devices notice nothing, because they trust the root. The first authority is limited by Name Constraints to local names and private addresses: the suffixes `local`, `lan`, `home.arpa`, `internal` and `localhost`, the box's host name, the network's search domains, and the address ranges 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 169.254.0.0/16, 127.0.0.0/8, fc00::/7, fe80::/10 and ::1. A device that trusts the root accepts nothing else from it, so even someone who took over the box could not forge a certificate for a public website. Both the root and the intermediate carry the limit. **Create new authority…** replaces root and intermediate. With **Only local names and private addresses** (the default) you can add domains of your own, such as `home.example.org`; each covers every name below it. Without the limit the authority may sign any name, and a device that trusts it would accept a forged certificate for any website if the box were compromised. After a new authority every device has to trust the new root again; certificates issued for other devices stay valid only where the old root is still trusted, and the list marks them **Earlier authority**. Renaming the box also needs a new authority if you reach it by its bare host name, because the old host name is part of the limit. ### The box's own certificate The box's certificate covers its host name, `.local`, the host name in each search domain, `localhost`, every address of its network cards (not those of app containers) and the loopback addresses, as far as the authority may sign them. It lives 397 days, renews itself 30 days before it ends and is issued again at once when an address or the host name changes. **Names of the box's certificate** shows what it covers; **More names** adds names such as a domain that points at the box, which must lie inside the authority's limit ([`tls.name.not_permitted`](https://pithyx.org/docs/reference/errors/#tls.name.not_permitted) otherwise). ### Certificates for other devices **Issue certificate…** makes a server certificate for a printer, router or another server in your network: names and addresses (a leading `*.` for a wildcard), 1 to 825 days, and an ECDSA key or, for devices that need it, RSA with 2048 bits. The browser downloads the certificate with the intermediate (`.crt`) and the private key (`.key`). The box does not keep the key. The list lets you download the certificate again, without the key, and remove an entry; the box keeps no revocation list, so a removed certificate stays valid until it ends. ### A certificate of your own **Your own certificate** takes a certificate you got elsewhere, for example for your own domain: the certificate with its intermediates and the private key, both in PEM and the key without a password. The box presents it on 7484, 443 and for FTPS while it is valid, and its own certificate again once it has ended or after **Remove own certificate**. The upload is refused with [`tls.custom.invalid`](https://pithyx.org/docs/reference/errors/#tls.custom.invalid), [`tls.custom.key_mismatch`](https://pithyx.org/docs/reference/errors/#tls.custom.key_mismatch) or [`tls.custom.expired`](https://pithyx.org/docs/reference/errors/#tls.custom.expired). Let's Encrypt is not built in yet. ### Behind a reverse proxy To put other services behind the box, use its own [reverse proxy](https://pithyx.org/docs/admin/reverse-proxy/). A reverse proxy elsewhere in front of the box connects to `https://:7484`. Let it trust the box's root (or, less strictly, skip the check for this one backend), pass WebSocket upgrades through for `/ws` and app sockets, and send its own requests with the host name the browser used. The box sees the proxy's address as the client, so the limit of failed sign-ins per address applies to everyone behind the proxy together. ### Backup The root, the intermediate, the box's certificate, an uploaded certificate, the extra names and the list of issued certificates are part of the configuration backup (part **Certificates**). Restoring them on a new system brings the same authority back, so devices keep trusting it; the box issues its own certificate again for the new system's names. ## Reverse proxy > Proxy hosts and redirect hosts on ports 443 and 80 by domain, with certificates, access rules and the Pithyx sign-in, and TCP and UDP streams. Source: https://pithyx.org/docs/admin/reverse-proxy/ Markdown: https://pithyx.org/docs/admin/reverse-proxy.md The built-in reverse proxy makes other services reachable under their own domains on ports 443 and 80: a request for `media.home.arpa` goes to the service behind it, with a certificate for that name. The box itself stays on port 7484; every name you did not set up goes there as before (or gets 404, if you choose so). Streams forward a TCP or UDP port of the box to another host. Everything is in Settings > **Reverse proxy** (administrators only), applies to the next request without a restart and is part of the configuration backup. ### Before you start Point each domain at the box in your DNS server or router (an A or AAAA record with the box's address, or a wildcard record for `*.apps.home.arpa`). The proxy only answers names that reach it. Without HTTPS on the box (development or simulation) it answers plain HTTP only, and a development daemon listens on the proxy ports only when `PITHYX_DEV_PROXY_PORTS` names them. ### Proxy hosts **Add proxy host** opens the settings of a host: - **Domains**: up to 50 names, separated by commas or spaces. A leading `*.` covers any one label in front (`*.apps.home.arpa` answers `photos.apps.home.arpa`, not `a.b.apps.home.arpa`); an exact name wins over a wildcard. A name belongs to one host only ([`proxy.domain.taken`](https://pithyx.org/docs/reference/errors/#proxy.domain.taken)). A switched-off host answers nothing; its names count as unknown. - **Target**: protocol, host and port of the service. For `https` choose how its certificate is checked: against the trusted authorities of the system, against the box's own authority (devices with a certificate from Settings > **Certificates**), or not at all for a self-signed certificate. - **The target is a service on this box itself**: needed for a target such as `localhost`, the box's name or one of its addresses ([`proxy.target.on_box`](https://pithyx.org/docs/reference/errors/#proxy.target.on_box)), for example to reach the web interface on 7484 under a domain. Ports 80 and 443 of the box are always refused, because the request would come back to the proxy ([`proxy.target.loop`](https://pithyx.org/docs/reference/errors/#proxy.target.loop)). - **Pass WebSockets on**: on by default; switched off, upgrades get 403 ([`proxy.websockets.disabled`](https://pithyx.org/docs/reference/errors/#proxy.websockets.disabled)). Answers stream through without buffering, so server-sent events and large downloads reach the browser as they come. Targets are spoken to with HTTP/1.1. #### HTTPS - **Certificate**: **From the box's certificate authority** makes a certificate for the host's domains in memory (397 days, renewed 30 days before its end and whenever the authority changes). Every domain must lie inside the authority's scope ([`tls.name.not_permitted`](https://pithyx.org/docs/reference/errors/#tls.name.not_permitted)); add your own domain to the scope with a new authority in Settings > **Certificates**. **Upload my own** takes a certificate with its chain and unencrypted key in PEM that covers every domain ([`proxy.certificate.name_mismatch`](https://pithyx.org/docs/reference/errors/#proxy.certificate.name_mismatch)), for example one for a public domain. An expired or broken upload is replaced by the box's own certificate, and the host shows **No certificate** when it has none of its own. - The box picks the certificate by the name the browser asks for in the TLS handshake, on 443 and on 7484; a name without a host gets the box's own certificate. - **Redirect HTTP to HTTPS** (on by default) answers plain HTTP on 80 with a redirect to 443 (301 for GET and HEAD, 308 otherwise). Switched off, the host also answers on 80. - **Offer HTTP/2** (on by default) lets browsers use HTTP/2 on 443. - **Send HSTS** adds `Strict-Transport-Security: max-age=31536000` to HTTPS answers. > **HSTS:** > > With HSTS a browser refuses plain HTTP and every certificate warning for the name for a year, even after you switch it off again. Use it only with a certificate every device trusts. #### Access The proxy checks, in this order: the allowed and denied addresses, Basic Auth, then the Pithyx sign-in. - **Allowed addresses** and **Denied addresses**: IP addresses or ranges such as `192.168.1.0/24`. A denied address never gets in; with allowed addresses, only those do ([`proxy.address.denied`](https://pithyx.org/docs/reference/errors/#proxy.address.denied)). The box sees the address the connection comes from. - **Basic Auth**: users with a password the browser asks for before anything else. Passwords are stored as Argon2id hashes and never shown; leave the field empty to keep a stored password. Failed attempts count towards the same limits as failed sign-ins. The target does not get the `Authorization` header. - **Require Pithyx sign-in**: a page of the host sends a visitor without access to the box's sign-in, by default on the requested name and port 7484 (or the **Sign-in address** of the page). After signing in there, the browser comes back with a one-time ticket (30 seconds) to `/.pithyx/auth` on the host, which sets a cookie of the host and continues to the page. Requests that are no page load get 401 ([`proxy.auth.required`](https://pithyx.org/docs/reference/errors/#proxy.auth.required)). The cookie belongs to the box session: signing out of the box, revoking the session, losing the right to sign in to the desktop or being removed from the host's users and groups ends the access at the next request. **Users** and **Groups** limit who gets in ([`proxy.access.denied`](https://pithyx.org/docs/reference/errors/#proxy.access.denied)); with neither, everybody who may sign in does, and administrators always do. The target gets the user in `X-Pithyx-User`, `X-Pithyx-User-Id`, `X-Pithyx-Groups` and `X-Pithyx-Admin`. The path `/.pithyx/auth` of such a host belongs to the proxy. Users and groups are stored by name: after renaming a group, update the host. > **Note:** > > The sign-in happens on the box's web interface. If you reach a host from outside through 443 only, set **Sign-in address** to a host that leads to the box's web interface, such as a proxy host for `nas.example.org` with the target `https://localhost:7484`. #### Headers - The target never gets incoming `X-Pithyx-*`, `X-Forwarded-*`, `Forwarded` or trace headers, nor the box's own cookies (`pithyx_*`); an answer cannot set those cookies either. - **Send X-Forwarded-For, -Proto and -Host** (on by default) tells the target the client's address, the protocol and the requested name. - **Send the requested name as Host** passes the browser's `Host` on; otherwise the target gets its own host and port. **Host header** sets a `Host` of your own instead. - **Request headers** and **Response headers**: one per line as `Name: value`; `Name:` alone removes the header. Headers the proxy controls itself (`Host`, `Connection`, `X-Forwarded-*`, `X-Pithyx-*`, `Strict-Transport-Security` and others) are refused ([`proxy.header.invalid`](https://pithyx.org/docs/reference/errors/#proxy.header.invalid)). #### Limits and logging - **Largest upload in MB**: empty for no limit. - **Connect timeout** (1 to 300 seconds, default 10) and **Answer timeout** (1 to 86400 seconds, default 100: how long the target may stay silent). An idle WebSocket stays open for up to a day. A target that cannot be reached gets 502 ([`proxy.target.unavailable`](https://pithyx.org/docs/reference/errors/#proxy.target.unavailable)), one that is too slow 504 ([`proxy.target.timeout`](https://pithyx.org/docs/reference/errors/#proxy.target.timeout)). - **Write an access log** (on by default): every request in the Log Center under the source `proxy/`, with method, name, path (without the query, which may hold secrets), status, duration, client address and, behind a sign-in, the user. The list shows for each host whether its target answered when the page opened; **Check target** looks again. ### Redirect hosts A redirect host sends browsers from its domains to another address with 301, 302, 307 or 308. With **Keep path and query** a request for `/a?b=1` goes to the target address followed by `/a?b=1`. It presents a certificate on 443 like a proxy host. ### Names without a host **Names without a host** decides what 443 and 80 do with a name no enabled host has: **Redirect to the web interface on port 7484** (the default, as without a reverse proxy) or **Answer “not found” (404)** ([`proxy.host.unknown`](https://pithyx.org/docs/reference/errors/#proxy.host.unknown)). The installer's check `/api/install-id` on port 80 always answers. ### Streams A stream forwards a port of the box, TCP, UDP or both, byte for byte to a host and port, for services that do not speak HTTP. The firewall opens the port while the stream is on. The box's own ports are refused (21, 22, 80, 443, 445, 7484 and FTP's passive ports 50000 to 50099, [`proxy.stream.port_reserved`](https://pithyx.org/docs/reference/errors/#proxy.stream.port_reserved)), so are ports another program holds ([`proxy.stream.port_in_use`](https://pithyx.org/docs/reference/errors/#proxy.stream.port_in_use)) and ports below 1024 unless you confirm them. A UDP client keeps its own connection to the target until it is silent for a minute; a stream takes up to 512 TCP connections and 1024 UDP clients at a time. ### Security The proxy runs inside the daemon, which runs as root, and only administrators may set targets. Requests the proxy itself sent are recognized and refused with 508 ([`proxy.loop.detected`](https://pithyx.org/docs/reference/errors/#proxy.loop.detected)). The settings are in the configuration backup as the part **Reverse proxy**; uploaded certificates come with the part **Certificates** (files `proxy-host-.pem` and `.key` next to the box's own). ### Not built yet Load balancing with health checks, rules per path, rate limits and Let's Encrypt come later. ## Backup and restore > Save the configuration of the box in an encrypted file and restore it, and what the backup does not cover. Source: https://pithyx.org/docs/admin/backup/ Markdown: https://pithyx.org/docs/admin/backup.md Settings > **Backup and restore** saves the configuration of the box (users, shared folders, file services, schedules and more) into one password-protected file and restores it later. It does not back up the files on your pools. Backups are manual: there is no schedule. ### Creating a backup 1. Open Settings > **Backup and restore** and choose "Create a backup". 2. Enter a backup password and repeat it. It must meet the normal password rules (at least 8 characters, not a well-known password). 3. Choose **Create and download**. The file is named `pithyx-config--.pithyxbackup`. > **The password cannot be recovered:** > > Without the backup password the backup cannot be restored. Pithyx does not keep it and nobody can recover it. Keep it, and the file, somewhere other than this box. The file is encrypted with AES-256-GCM under a key derived from the password with Argon2id (64 MiB, 3 passes). The archive may be up to 16 MB and 256 MB unpacked ([`system.backup.too_large`](https://pithyx.org/docs/reference/errors/#system.backup.too_large)). It holds password hashes and keys, so protect it like a secret. ### What it holds Categories you can choose when restoring: - **Users and groups**: accounts, groups, passwords (also for SMB and SFTP), two-factor sign-in, the recovery key, personal settings and desktop layouts. - **Shared folders and file services**: shared folders with their rights and the SMB, SFTP, WebDAV and FTP settings. - **Storage settings**: snapshot schedules (restore points), scrub and self-test schedules. - **System settings**: language, formats, time zone, time servers and log retention. - **Certificates and keys**: the box's certificate authority and certificates, uploaded certificates of reverse proxy hosts, and the SSH host keys, when present. - **Reverse proxy**: proxy hosts (with Basic Auth users as hashes), redirect hosts, streams, what unknown names get and the sign-in address. - **Apps**: the app registry, permissions, folder mappings, catalogs and the app pool. The apps' files and data stay on the pool. Not included: files on pools, app data, logs, Docker data, sessions, jobs, notifications, the recycle bin index, and the network settings (cards are named differently on other hardware). ### Restoring ![Settings, Backup and restore, after Check backup: when and where the backup was made, its contents and the parts to restore, with the button Restore](../../../../assets/screenshots/backup-checked.webp) _Check backup shows what the file holds; nothing changes until you choose Restore._ 1. Choose the file, enter its password and choose **Check backup**. Nothing changes yet. 2. The page shows "This backup holds": when it was created, from which host, the Pithyx version and counts of users, groups and shared folders. 3. Under "What to restore", tick the parts, then choose **Restore…** and **Restore now**. A checked backup waits 15 minutes ([`system.backup.restore_expired`](https://pithyx.org/docs/reference/errors/#system.backup.restore_expired)). Each part you choose replaces the current one completely; files on your pools stay untouched; Pithyx restarts afterwards. Restoring users signs everybody out, including you; sign in with an account and password from the backup. Before the restore the database is copied to `pithyx.db.pre-restore-