# Pithyx > Pithyx is a free, self-hosted NAS and server OS with a web desktop: Debian 13, a C# daemon, a React desktop and apps as containers. It runs 100 percent locally, without telemetry or cloud accounts. ## Pithyx documentation > Everything about Pithyx, from installing a box to writing apps for it. Source: https://pithyx.org/docs/ Markdown: https://pithyx.org/docs.md Pick an area below. Every page also exists as plain Markdown: add `.md` to its address, or use the buttons under the title. - [Getting started](https://pithyx.org/docs/getting-started/what-is-pithyx.md): What Pithyx is, the hardware it needs and the quickest way to a running box. - [Using Pithyx](https://pithyx.org/docs/user/desktop.md): The web desktop for everyday users: windows, files, apps and the own account. - [Administration](https://pithyx.org/docs/admin/storage.md): Running a box: users and groups, permissions, storage, shared folders, file services, network, apps and backups. - [Install and update](https://pithyx.org/docs/install/usb-stick.md): The USB stick, firmware and boot, the web installer, the first setup and system updates. - [Daemon](https://pithyx.org/docs/developers/daemon/architecture.md): The C# daemon: architecture, API, errors, logging and tests. - [Desktop](https://pithyx.org/docs/developers/desktop/architecture.md): The React web desktop: structure, translations, theming, window manager and budgets. - [App development](https://pithyx.org/docs/developers/apps/overview.md): Writing, building and publishing apps: pithyx dev, the manifest, backends and catalogs. - [SDK and CLI](https://pithyx.org/docs/sdk/guides/files-and-storage.md): The npm packages @pithyx/sdk, @pithyx/ui and @pithyx/cli. - [Reference](https://pithyx.org/docs/reference/cli.md): Every error code, the REST API, the manifest and Compose rules, and a glossary. - [Project](https://pithyx.org/docs/project/license.md): License, privacy, contributing, reporting security issues and the changelog. ## What is Pithyx > Pithyx in a few minutes: a NAS and server OS with a web desktop, running only on your own hardware. Source: https://pithyx.org/docs/getting-started/what-is-pithyx/ Markdown: https://pithyx.org/docs/getting-started/what-is-pithyx.md Pithyx is a free, self-hosted operating system for a NAS or home server. You install it on your own computer, and from then on you manage storage, users, file sharing and apps in a web desktop that you open in any browser. Everything runs on your box: there is no cloud account, no telemetry and no service run by the project that your box depends on. > **Caution:** > > Pithyx 1.0 is marked beta: we consider it stable, but it has not yet proven itself on real boxes in everyday use. Treat it as beta and keep a copy of data you care about on another device. ### What you get - **A web desktop.** Windows, a taskbar, desktop shortcuts and notes, in a browser on a PC, tablet or phone. See [The desktop](https://pithyx.org/docs/user/desktop/). - **Storage with ZFS.** You build pools from your disks in the Storage app and create shared folders on them. New pools use compression and are not encrypted. See [Storage](https://pithyx.org/docs/admin/storage/). - **File sharing.** Shared folders are available over SMB, SFTP, WebDAV and FTP. SMB is on by default; the others you switch on in Settings. See [Access files from other devices](https://pithyx.org/docs/user/file-access/). - **Users and groups.** Every user is a real account on the box. Rights are given to users and groups; a user gets the union of all of them. Administrators can do everything. See [Users and groups](https://pithyx.org/docs/admin/users-and-groups/). - **Apps.** Apps open in windows on the desktop. An app is a frontend with an optional backend in containers. Administrators install apps from a file or from a catalog in the Store; the official and the community catalog are on by default. See [Using apps](https://pithyx.org/docs/user/apps/). - **Backup of the configuration.** Settings, users and shared folder definitions can be saved to an encrypted file and restored after a reinstall. See [Backup and restore](https://pithyx.org/docs/admin/backup/). - **Network settings in the browser**, including bonds and VLANs, with a confirmation timer that rolls back a change that cuts you off. See [Network](https://pithyx.org/docs/admin/network/). The core apps are Files, Viewer, Storage, Settings, Resource Monitor, Log Center, About Pithyx and the Store. ### How it is built - The box runs Debian 13. The Pithyx daemon (C# on .NET 10) is the only privileged process and serves the web desktop and the API. - The desktop is a React web application. Core apps and third-party apps use the same SDK. - The system disk holds the system on btrfs, in a RAID 1 of one or two disks. Your data lives on ZFS pools on other disks. - Settings are kept in a small SQLite database on the system disk, so the system disk can be rebuilt from a configuration backup. - Pithyx is licensed under AGPL-3.0. The npm packages for app developers are MIT. For details see [Architecture](https://pithyx.org/docs/developers/daemon/architecture/). ### What Pithyx is not - It is not for data you cannot afford to lose yet (see the warning above). - It is a fresh-install system. There is no import from other NAS systems. - The installer does not restore a backup or import pools. Both happen after the first sign-in. - It does not offer NFS. Pools are not encrypted yet. - It needs a 64-bit x86 computer with UEFI and Secure Boot switched off. There is no installer for 32-bit machines, legacy BIOS or Raspberry Pi. See [Hardware requirements](https://pithyx.org/docs/getting-started/requirements/). - It supports wired networks only. Wi-Fi is not supported. - It does not announce itself on the network, so you find the box by its address. ### Where to go next - [Hardware requirements](https://pithyx.org/docs/getting-started/requirements/) - [Quick start](https://pithyx.org/docs/getting-started/quick-start/) - [The web installer](https://pithyx.org/docs/install/installer/) - [The desktop](https://pithyx.org/docs/user/desktop/) - [Frequently asked questions](https://pithyx.org/docs/faq/) ## Hardware requirements > The hardware Pithyx needs, the reference machine and what is not supported. Source: https://pithyx.org/docs/getting-started/requirements/ Markdown: https://pithyx.org/docs/getting-started/requirements.md Pithyx installs on a 64-bit x86 computer with UEFI firmware, at least 2 GB of memory and a system disk of at least 32 GB. The installer checks all of this before it lets you begin. Your data goes on additional disks, which you turn into pools after the installation. ### Supported platforms The installer checks five things on its first page and refuses to start if one fails: | Check | Requirement | | ----------- | --------------------------------------------------------------------------------------------------------------------- | | Processor | 64-bit x86 with x86-64-v2 (needs among others SSE4.2 and POPCNT) | | Firmware | Started in UEFI mode. Legacy BIOS and CSM mode do not work. | | Memory | At least 2 GB (the check allows about 400 MB of tolerance for memory the firmware reserves); 4 GB or more recommended | | Secure Boot | Switched off. The ZFS module is not signed. See [Firmware and boot](https://pithyx.org/docs/install/firmware-and-boot/). | | System disk | At least one suitable disk sold as 32 GB or more (the check allows 2 GB of tolerance) | The base system is Debian 13. There is no 32-bit version. ### Reference hardware The reference machine is an Intel N100 or N305 with 8 GB of memory. The daemon is held to below 200 MB of memory and below 1 percent of CPU when idle. These numbers are budgets for the project's own tests, not requirements. The installer only enforces the 2 GB minimum. ### Disks and pools **System disk.** The installer writes the system to one disk, or to two disks as a mirror (btrfs on an mdadm RAID 1). It never uses more than two. - The disk must be at least 32 GB. From 40 GB on, Pithyx uses 36.5 GiB of it (a 512 MiB boot partition, 32 GiB for the system and 4 GiB of swap) and leaves the rest unused. On a smaller disk the swap has 2 GiB and the system gets what remains, about 26 GiB on a 32 GB disk; that is enough for the system, its update snapshots and the logs. With two disks the smaller one decides. - With 2 to 4 GB of memory a box runs a few users and apps; the installer says so. ZFS keeps less in its cache then, and large app images or updates may use the swap. - Read-only disks, disks in use and the installer stick itself are not offered. - Built-in eMMC (common in small computers) works like any internal disk. - A USB stick, a USB disk or a memory card can hold the system, and the installer warns about it: the system writes logs and its database to the system disk all the time, and cheap flash wears out within months. If you choose one, use a USB SSD or a fast USB 3 stick of a known brand (for a card, one made for continuous use), best two of them as a mirror, and keep a [configuration backup](https://pithyx.org/docs/admin/backup/). The stick has to stay plugged in. - A hard disk is allowed, but the installer hints that an SSD is faster, quieter and uses less power. - A disk that already holds data is shown with a warning. Installing erases it. - With one disk the system is still built as a mirror with one member. Adding the second disk later is not possible in the interface yet. **Data pools.** After the installation you create pools in the Storage app, on disks other than the system disk. | Layout | Minimum disks | | ------------ | ------------------ | | Single disk | 1 | | Stripe | 2 | | Mirror | 2 | | Mirror pairs | 4 (an even number) | | RAID-Z1 | 3 | | RAID-Z2 | 4 | | RAID-Z3 | 5 | New pools are created with 4 KiB sectors (`ashift=12`), `lz4` compression and `atime=off`. A pool name starts with a lowercase letter and may contain lowercase letters, digits, hyphens and underscores, up to 32 characters. Pools are not encrypted. See [Storage](https://pithyx.org/docs/admin/storage/). ### Network - Every wired network card asks for an address by DHCP (IPv4 and IPv6) on first boot. You can set a fixed address in the installer. - The web desktop is served over HTTPS on port 7484; ports 80 and 443 redirect to it, except for domains you set up in the reverse proxy. Browsers warn about the box's own certificate until a device trusts its root. - The box has a firewall that lets in only the web interface and the file services you switch on. See [Security](https://pithyx.org/docs/admin/security/#open-ports). - Wi-Fi is not supported. - The box does not announce a name on the network. Use its IP address, which the console shows after boot. ### Community platforms There is no image for arm64 (for example the Raspberry Pi 5): the image and the installer are x86-64 only. The installer is tested in virtual machines with QEMU and KVM (UEFI firmware); other hypervisors and real hardware have not been tested systematically. ## Quick start > From the image to the first signed-in desktop in the fewest steps, with links to the details. Source: https://pithyx.org/docs/getting-started/quick-start/ Markdown: https://pithyx.org/docs/getting-started/quick-start.md The short path: write the Pithyx image to a USB stick, start the computer from it, finish the installer in a browser on another device, then sign in at `https://:7484`. This page lists the steps and links to the pages that explain each one. ### Download the image Download the image from the [releases on GitHub](https://github.com/pithyx/pithyx/releases): a file named `pithyx--amd64.iso`, with a checksum file next to it. See [Write the USB stick](https://pithyx.org/docs/install/usb-stick/). ### Write the USB stick Write the image to a USB stick with any tool that writes disk images. The whole stick is overwritten. See [Write the USB stick](https://pithyx.org/docs/install/usb-stick/). ### Install 1. Check the [hardware requirements](https://pithyx.org/docs/getting-started/requirements/). In the firmware, use UEFI mode and switch Secure Boot off. See [Firmware and boot](https://pithyx.org/docs/install/firmware-and-boot/). 2. Start the computer from the stick and choose **Install Pithyx** (it starts by itself after 5 seconds). 3. Read the address on the console, for example `http://192.168.1.50:7484`, and open it in a browser on another device. 4. Go through the steps of [the web installer](https://pithyx.org/docs/install/installer/): name and region, network, system disk, administrator account, summary. 5. Choose **Install Pithyx** and wait. Write down the recovery key that appears, then remove the stick and restart. ### First setup The installer already creates the owner account, so there is no separate setup page. Sign in with the account you chose. See [First setup](https://pithyx.org/docs/install/first-setup/). ### Next steps 1. Open **Storage** and create a pool on your data disks. 2. Open Settings > **Shared folders** and create shared folders on the pool. 3. Create users in Settings > **Users** and give them access to the shared folders. See [Users and groups](https://pithyx.org/docs/admin/users-and-groups/). 4. Switch on the file services you need in Settings > **File services** ([File services](https://pithyx.org/docs/admin/file-services/)) and connect from your devices ([Access files from other devices](https://pithyx.org/docs/user/file-access/)). 5. Make a configuration backup in Settings > **Backup and restore**. See [Backup and restore](https://pithyx.org/docs/admin/backup/). ## The desktop > Windows, the taskbar, desktop items, snapping, shortcuts and the layout each device remembers. Source: https://pithyx.org/docs/user/desktop/ Markdown: https://pithyx.org/docs/user/desktop.md The Pithyx desktop is the page you open in your browser at `https://:7484`. It works like a normal computer desktop: apps open in windows, a taskbar shows what is running, and you can put shortcuts and sticky notes on the desktop. The box remembers your windows for each device you use. ### Signing in 1. Open `https://:7484` in your browser. Port 80 forwards to it. 2. Type your **User name** and **Password** and click **Sign in**. 3. If you turned on two-factor sign-in, type the code from your authenticator app and click **Verify**. If you lost your phone, click **Use a recovery code instead**. > **Caution:** > > The first time, the browser warns about the box's own certificate; continue to the page. An administrator can make the warning go away for good with the box's root certificate ([Certificates](https://pithyx.org/docs/admin/certificates/)). You need the right **Sign in to the desktop**. If your account is deactivated or lacks the right, an administrator has to change that. After five wrong attempts for the same user name from the same address within five minutes, sign-in pauses for a short time and tells you how many seconds to wait. To sign out, open the Pithyx menu and click the **Sign out** button at the bottom, next to the power button. Forgot your password? Click **Forgot password?** on the sign-in page. Pithyx cannot reset a password by email: ask an administrator to set a new one. Administrators can use the recovery key. See [Recovery and reinstall](https://pithyx.org/docs/install/recovery/). The sign-in page has its own language selector in the footer. The first time the box is set up, the owner account is created in the installer; see [First setup](https://pithyx.org/docs/install/first-setup/). ### Windows and snapping ![The window menu of Files, opened from the app icon in the title bar, with Move, Size, Minimize, Maximize, Snap left, Snap right and Close](../../../../assets/screenshots/desktop-window-menu.webp) _The app icon in the title bar opens the window menu with the keyboard shortcuts for snapping._ Every app opens in a window. What you can do with a window depends on the width of your browser: - **1024 pixels or wider:** free windows. You can move and resize them and snap them to the screen edges. - **600 to 1023 pixels (tablets):** windows fill the screen. Snapped windows share the screen as left and right halves. - **Under 600 pixels (phones):** one app at a time, full screen. On a wide screen: - Drag the title bar to move a window. Drag any edge or corner to resize it. - Double-click the title bar to maximize the window, and again to restore it. - Drag a window to the left or right edge to fill half of the screen, or to the top edge to maximize it. On very wide screens (2400 pixels or more) the edges give thirds. - Drag a maximized or snapped window away from the edge to get its free size back. - The title bar has **Minimize**, **Maximize** (or **Restore**) and **Close** buttons. - Click the app icon at the left of the title bar for the window menu: **Restore**, **Move**, **Size**, **Minimize**, **Maximize**, **Snap left**, **Snap right** and **Close**. **Move** and **Size** let you use the arrow keys (16 pixels per press, with Shift 1 pixel), **Enter** to confirm and **Escape** to cancel. New windows open slightly offset from each other. You can have at most 50 windows open. Beyond that, opening another app does nothing. If an app does not answer for five seconds, a dialog says that the app is not responding. Click **Wait** or **Close anyway**; closing anyway loses changes the app has not saved. ### The taskbar ![The Pithyx menu in the dark theme with the account menu of Anna Weber open: Two-factor authentication, Language, Appearance, Accent color, Wallpaper, Get desktop from and Taskbar position](../../../../assets/screenshots/desktop-account-menu.webp) _The account menu opens when you click your name at the bottom of the Pithyx menu._ By default the taskbar is at the bottom of the screen. From the left it has: - the Pithyx menu button, - one button per running app, - the app switcher, with the number of open apps, - the transfers button, while files are being uploaded or downloaded, - the running tasks button, - the notifications bell, with a badge for unread notifications, - the clock. When more apps run than fit, their buttons get narrower and then scroll: turn the mouse wheel over them or swipe, and the active app always comes into view. The menu button and everything from the transfers button to the clock stay in place. Click a running app to bring it to the front. Click the active app again to minimize it. Right-click a running app (or press **Shift+F10** on it) for **Minimize** or **Restore**, **Add to desktop** and **Close**. To move the taskbar, open the Pithyx menu, click your name, choose **Taskbar position** and pick **Bottom**, **Top**, **Left** or **Right**. On phones the taskbar always stays at the bottom and the entry is missing. **The Pithyx menu** opens with the button at the left of the taskbar, or by pressing and releasing the Windows or Command key. It lists your apps and has a search field. The search field finds apps by name only; settings and files are not found there, and the list of recent files stays empty. Your account menu (click your name) has: - **Two-factor authentication** - **Language** - **Appearance**, **Accent color** and **Wallpaper** - **Get desktop from** - **Taskbar position** (not on phones) At the bottom of the Pithyx menu, next to your name, are the **Sign out** button and, for administrators and users with the right **Restart and shut down**, the **Power options** button with **Restart** and **Shut down**. Both sign every user out and stop file transfers. **Notifications.** The bell opens a panel with **Running tasks** and **Recent** notifications. Use **Dismiss**, **Mute** or **Clear all**. Press **Escape** to close the panel. ### Desktop items and notes ![The desktop with the Files and Storage windows side by side, the shortcuts Files and Settings and a sticky note at the left and the taskbar at the bottom](../../../../assets/screenshots/desktop.webp) _Two shortcuts and a sticky note next to two open windows._ The desktop holds shortcuts to apps and sticky notes. They belong to your account and appear on every device. - To add a shortcut, right-click an empty spot and choose **New shortcut**, then an app. Or right-click a running app in the taskbar and choose **Add to desktop**. - To add a note, right-click an empty spot and choose **New note**. A note holds up to 4000 characters and saves itself shortly after you stop typing. - Open a shortcut with a double-click (a single tap on a touch screen), or select it and press **Enter**. - Right-click a shortcut for **Open**, **Rename**, **Move** and **Remove from desktop**. **F2** renames, **Del** removes. - Drag icons to move them. Drag on an empty spot to select several. Hold **Ctrl** or **Shift** to add to a selection. - On a touch screen, press and hold for about half a second to open the menu. - To delete a note, click **Remove note**. A note with text asks **Delete this note?** first. The text is deleted on all your devices. The desktop holds at most 200 items. Icons snap to a grid. On small screens they flow in rows like a phone home screen. ### Keyboard shortcuts These window shortcuts work anywhere on the desktop except while you type in a text field: | Keys | Action | | ------------------------------------- | ------------------------------------------------------------- | | **Alt+Shift+Left** / **Right** | Snap the window to the left or right | | **Alt+Shift+Up** | Maximize | | **Alt+Shift+Down** | Restore a snapped or maximized window, or minimize a free one | | **Alt+Shift+Space** | Open the window menu of the active window | | **Alt+Shift+Page Up** / **Page Down** | Switch to the previous or next window | Other keys: - Tap and release the Windows or Command key: open or close the Pithyx menu. - **Escape**: close the Pithyx menu, the app switcher or the notification panel. - On the desktop: arrow keys move between icons, **Enter** opens, **F2** renames, **Del** removes, **Shift+F10** or the Menu key opens the context menu. ### Layout per device The box remembers your windows for each browser you use: which apps are open, where, how big, the taskbar position and small details such as the folder open in Files. When you open the desktop again, the windows return. A device is recognized by a small cookie, which holds no personal data. - Saved layouts expire 90 days after the last save. - A window of an app that was removed, or that you may no longer use, is skipped. A notification tells you how many. - Your desktop items, accent color and wallpaper are the same on all devices. The theme and the language belong to the device. - To copy the arrangement of another device, open your account menu, click **Get desktop from** and pick the device. If there is none, the list says **No other devices**. The desktop does not follow you between devices by itself. ### Phones and tablets There is no separate mobile app. The same page adapts to the screen. - On a phone, an app fills the screen. The app switcher shows the open apps as cards; tap a card to switch, or **Close all**. Swiping sideways along the taskbar also changes apps. - The browser's back gesture minimizes the open app and takes you to the home screen instead of leaving the desktop. - On a tablet, windows are maximized and you can snap two side by side. - Press and hold to open menus. A single tap opens a shortcut. Related pages: [Files](https://pithyx.org/docs/user/files/), [Using apps](https://pithyx.org/docs/user/apps/), [Your account](https://pithyx.org/docs/user/account/). ## Files > The Files app: browsing, uploading, copying and moving, the recycle bin, thumbnails and the viewer. Source: https://pithyx.org/docs/user/files/ Markdown: https://pithyx.org/docs/user/files.md Files is the app for working with the shared folders you may use: open folders, upload and download files, copy and move them, and restore deleted files from the recycle bin. Images, PDFs, text, audio and video open in the Viewer. You need the right to use the Files app and access to at least one shared folder. ### Browsing shared folders ![Files with the shared folders and recycle bins in the sidebar, the folder Photos/2026-summer in list view and the context menu of a photo open](../../../../assets/screenshots/files.webp) _Files in list view. Right-click an entry for its context menu._ Open **Files** from the Pithyx menu. The sidebar lists your home folder **home** first and your shared folders under it, under **Shares**; Files opens in your home. Your home is private: only you and the administrators can open it. Administrators also see **homes**, which lists every other user's home as a folder, in the same list or tiles as any folder; a double click opens one. The homes themselves cannot be renamed, moved or deleted there, and their menu only offers **Open**. Click an entry to open it. A folder that cannot be reached right now (for example because its pool is offline) shows **Not available**. If the list is empty, you have no shared folders yet and an administrator has to create them. A shared folder marked **Read only** lets you look and download, but not change anything. To move around: - Double-click a folder, or select it and press **Enter**, to open it. - Use the **Back**, **Forward** and **Up one level** buttons, or type a location in the **Path** field. - **Backspace** or **Alt+Up** goes up one level. - Click **Name**, **Size** or **Modified** at the top of the list to sort. Click again to reverse the order. - Use **Show as tiles** or **Show as list** to change the view, and **Comfortable** or **Compact** for the row height. - The search field (shown as "Search in" and the folder name) looks for names in the current folder. The status line shows how many items the folder holds, or how many you selected. Long folders load in pages as you scroll. The window remembers its folder and view for the next time. Opening a file depends on its type: pictures, PDFs, text, audio and video open in the Viewer; other files download. To choose, right-click and pick **Open with…**, then **Viewer**, **Download** or an installed app that declares it opens this file type. Names that start with `.pithyx-upload-` and the folder `.pithyx-trash` are internal and not shown. Right-click an item for its menu: **Open**, **Download**, **Open with…**, **Copy**, **Cut**, **Rename**, **Previous versions**, **Move to recycle bin** and **Delete permanently**. Right-click an empty spot for **New folder**, **Upload**, **Paste** (after you copied or cut something) and **Select all**. Actions that change something appear only when you may write to the shared folder. #### Previous versions If an administrator switched on restore points for the shared folder, the box saves a copy once a day and keeps it for 7 days. Right-click a file or folder and choose **Previous versions** to see them. Pick a day, then choose **Replace the current version**, or restore it next to the current one with the date in its name. Restoring needs write access to the folder. If no restore points exist, the list says there are no earlier versions yet. Restore points live on the same disks as the files. They do not replace a backup on another device. ### Uploading 1. Open the folder you want the files in. 2. Click **Upload** and pick files, or drag files from your computer into the window. Drop them on a folder to put them inside it. 3. Watch the progress in the transfers button on the taskbar. It shows the speed and the time left, and has a button to cancel a transfer. Things to know: - You need write access to the shared folder. - Files upload one after another. - There is no limit on file size besides the free space of the pool. - A file appears in the folder only when it has arrived completely. If the connection drops, nothing is saved and you upload the file again. There is no resume. - The uploaded file belongs to your account on the box. - If a name already exists, Files asks what to do (see below). ### Copy, move and conflicts ![The dialog Names already exist with the buttons Cancel, Skip them, Replace them and Keep both](../../../../assets/screenshots/files-conflict.webp) _The dialog when names already exist in the target folder._ - **Copy and paste:** select items, press **Ctrl+C** (or **Cmd+C**), open the target folder and press **Ctrl+V**. **Ctrl+X** cuts instead of copies. - **Drag and drop:** dragging items to another folder or to a share in the sidebar moves them. Hold **Ctrl** or **Alt** while dropping to copy. - **Rename:** press **F2** or choose **Rename**. A name must not be empty, must not contain `/` and may be at most 255 bytes long. - **New folder:** choose **New folder**, then type its name. Copying and moving run in the background with progress and a cancel button. One request handles up to 1000 selected items. Symbolic links are not copied. A folder cannot be copied or moved into itself. When the target already has items with the same names, a dialog titled **Names already exist** offers: - **Skip them**: leave the existing items alone. - **Replace them**: files are replaced, folders are merged. - **Keep both**: the new item gets a number, for example `Report (2).pdf`. - **Cancel**. To download, choose **Download** or open a file that the Viewer cannot show. ### The recycle bin ![The recycle bin of the shared folder Photos with two deleted photos, their original path and dates, and the buttons Restore, Delete for good and Empty recycle bin](../../../../assets/screenshots/files-recycle-bin.webp) _Each shared folder has its own recycle bin with the date an entry is deleted for good._ **Move to recycle bin** (the **Del** key) does not delete a file. It moves it into the recycle bin of its shared folder, or of your home. Deleting files over SMB, WebDAV or FTP does the same. To see a bin, click **Recycle bin** in the sidebar and choose the shared folder. Each entry shows where it came from and when it was deleted. With **Restore** you get it back in its original folder; missing parent folders are created. **Delete for good** removes single items. **Empty recycle bin** removes everything in the bin of that folder. Both ask first, and you need write access. Files stay in the bin for 30 days by default, then the box deletes them. The bin shows the period in use as a note at the top. Only an administrator can change this period. To skip the bin, press **Shift+Del** or choose **Delete permanently**. After the question **Delete permanently?** the items are gone for good. Deleting over SFTP does not use the recycle bin: the files are gone at once. ### Thumbnails and the viewer **Thumbnails.** Files shows small previews for JPEG, PNG, WebP and GIF images. Other types, including videos and HEIC pictures, show an icon. Previews are drawn when they come into view, and the box keeps them in a cache on the pool (up to 2 GB). Very large images are not previewed: the limits are 256 MiB per file and 50 million pixels. **The Viewer** opens in its own window. It shows: - **Images:** JPEG, PNG, WebP, GIF, AVIF, BMP, ICO and SVG. Zoom with the toolbar, or press **+**, **-** and **0** (fit to window). - **PDF files** - **Text and code files**, as plain text. Only the first megabyte is shown; download the file to see the rest. - **Audio and video** in the formats your browser can play. In the Viewer, **Left** and **Right** go to the previous and next file in the same folder. For types it does not know, the Viewer asks you to download the file. ### Keyboard shortcuts | Keys | Action | | --------------------------------------------- | ------------------------------------------------------------------- | | Arrow keys | Move the selection (Shift extends it, Ctrl moves without selecting) | | **Home**, **End**, **Page Up**, **Page Down** | Jump through the list | | **Enter** | Open | | **Space** | Select (Ctrl+Space toggles) | | **Backspace**, **Alt+Up** | Up one level | | **F2** | Rename | | **Del** | Move to recycle bin | | **Shift+Del** | Delete permanently | | **Ctrl+A** | Select all | | **Ctrl+C**, **Ctrl+X**, **Ctrl+V** | Copy, cut, paste | | **Escape** | Clear the selection | | **Shift+F10** or the Menu key | Open the context menu | See also [Access files from other devices](https://pithyx.org/docs/user/file-access/) and [Shared folders](https://pithyx.org/docs/admin/shared-folders/). ## Access files from other devices > Connecting to your shared folders from Windows, macOS, Linux and phones over SMB, SFTP, WebDAV and FTP. Source: https://pithyx.org/docs/user/file-access/ Markdown: https://pithyx.org/docs/user/file-access.md Besides the Files app, your shared folders can be opened from other computers and devices as a network drive or through a file transfer program. Pithyx offers four ways: SMB, SFTP, WebDAV and FTP. You sign in with your Pithyx user name and password. Ask an administrator which of them are switched on for you. In the steps below, `` is the name or IP address you use to open the desktop, for example `192.168.1.50`. ### Which protocol to use ![Settings, File services, with SFTP off, WebDAV on, FTP off and the addresses to connect to, such as sftp://pithyx and https://pithyx:7484/webdav/](../../../../assets/screenshots/file-services.webp) _An administrator switches the file services on in Settings > File services; each card shows the address to use._ | Protocol | Use it for | Notes | | ---------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | **SMB** | A network drive on Windows, macOS and Linux for everyday work | Needs SMB 3. Older systems cannot connect. Previous versions and the recycle bin work. | | **SFTP** | Encrypted transfers with a program such as FileZilla or WinSCP, or the `sftp` command | You see only your home and shared folders and get no shell. Password sign-in only. | | **WebDAV** | Programs and file managers that can mount a web folder | Address: `https://:7484/webdav/` | | **FTP** | Devices that know neither SFTP nor WebDAV, such as scanners | Only passive mode. Encrypted with TLS; plain FTP only if an administrator allows it. | > **Caution:** > > The desktop and WebDAV use HTTPS. Windows and macOS mount WebDAV only once the computer trusts the box's root certificate; an administrator finds it in Settings > **Certificates**. Everyone sees only the shared folders their rights allow, with the access level an administrator gave them: no access, **Read** or **Read and write**. Administrators reach every shared folder. ### Your home folder Besides the shared folders, every user has a private home folder that only they and the administrators can open. It is the share `home` over SMB (`\\\home` on Windows, `smb:///home` on macOS and Linux) and the folder `home` at the top over SFTP, WebDAV and FTP. Administrators also find every user's home in the share or folder `homes`. Files you delete in your home go to its recycle bin, except in the SMB share `homes`, where they are gone at once. See [Home folders](https://pithyx.org/docs/admin/home-folders/). Two-factor sign-in does not apply here. These services ask for your password only. ### Windows **SMB (network drive)** 1. Open File Explorer. 2. Click the address bar, type `\\\` and press **Enter**. 3. Sign in with your Pithyx user name and password when asked. Tick the option to remember the credentials if you like. 4. Your shared folders appear. To keep one as a drive letter, right-click it and choose **Map network drive**. The box does not announce itself on the network, so it does not appear under **Network** in Explorer. Always type the address. In Explorer, **Previous versions** shows the daily restore points of a shared folder. Files you delete land in the recycle bin of the shared folder, and you can restore them in the Files app. **SFTP and FTP:** install a program such as FileZilla or WinSCP and connect to ``. **WebDAV:** in File Explorer, right-click **This PC**, choose **Map network drive** and enter `https://:7484/webdav/`. Windows connects only once it trusts the box's root certificate. If it still refuses, use SMB or a WebDAV program instead. ### macOS **SMB (network drive)** 1. In Finder, choose **Go**, then **Connect to Server**. 2. Type `smb:///` and click **Connect**. 3. Sign in with your Pithyx user name and password. **SFTP:** Finder cannot browse SFTP. Use an SFTP program and connect to `sftp://`. **WebDAV:** in **Connect to Server**, enter `https://:7484/webdav/`. macOS connects once it trusts the box's root certificate. **FTP:** use a program that supports FTP with TLS, and choose "explicit FTP over TLS". ### Linux **SMB:** most file managers accept `smb:///` in the address bar. On the command line you can mount with `mount -t cifs` and `vers=3.0`. **SFTP:** use `sftp://` in your file manager, or run: ```sh sftp @ ``` SFTP accepts passwords only. Public keys are not used for SFTP users. **WebDAV:** a file manager with WebDAV support accepts `davs://:7484/webdav/`. **FTP:** use a client with explicit FTP over TLS, such as `lftp`. ### Phones There is no special app. Any app that speaks SMB 3, SFTP, WebDAV or FTP with TLS can connect with the settings above. Or use the desktop itself: it works in a phone browser, including the Files app. See [The desktop](https://pithyx.org/docs/user/desktop/#phones-and-tablets). For FTP, the box has its own certificate. Your program asks once whether to trust it. Compare the fingerprint it shows with the **Certificate fingerprint (SHA-256)** that an administrator can read in Settings, under **File services**. FTP listens on port 21 and passive data connections use ports 50000 to 50099. ### Signing in - Use your Pithyx user name (in lower case) and password. - Your account needs the right for the protocol: **SMB (network drives)**, **SFTP**, **WebDAV** or **FTP**. New users get the SMB right by default. An administrator gives you the others. - Your account must be active. - **SMB and SFTP:** if a connection with the right password is refused, sign in once on the web desktop, or ask an administrator to set a new password for you. The services learn your password that way. - After five wrong attempts for the same user name from the same address within five minutes, further attempts are paused for a short time. - Files you create belong to your account on the box. You cannot change permissions from Windows. - If a protocol is switched off, you cannot connect with it. An administrator turns services on in Settings, under **File services**. See [File services](https://pithyx.org/docs/admin/file-services/). If something does not work, the usual causes are a missing right, a deactivated account, or a protocol that is switched off. ## Using apps > Opening apps, windows of the same app, and what an app may see of your data. Source: https://pithyx.org/docs/user/apps/ Markdown: https://pithyx.org/docs/user/apps.md Apps open in windows on the desktop, like Files or Settings. Some apps come with Pithyx; administrators can install more from the Store. Each app runs in a sandbox and only sees what an administrator allowed it to see, limited by what your own account may do. ### Opening an app Open the Pithyx menu and click an app, or type part of its name into the search field. You can also open an app from a shortcut on the desktop, or put one there with **Add to desktop**. See [The desktop](https://pithyx.org/docs/user/desktop/). The apps that come with Pithyx are **Files**, **Viewer**, **Storage**, **Settings**, **Resource Monitor**, **Log Center**, **About Pithyx** and **Store**. You only see the apps you may use: - **Files** and **Viewer** are available to new users by default. - **Storage**, **Settings**, **Resource Monitor**, **Log Center** and **Store** are for administrators. - **About Pithyx** is open to everybody. - Apps an administrator installed show up for the users the administrator chose. Ask an administrator if you miss an app. If an app's data is on a pool that is offline or locked, the app cannot be opened until the pool is back. ### Single and multiple windows An app decides how many windows it may have: - **One window:** opening the app again brings its window forward instead of opening a second one. This holds per device, so another browser has its own window. Storage, Settings, Resource Monitor, Log Center, About Pithyx and the Store work this way. - **Several windows:** every click opens a new window. Files and Viewer work this way. Windows come back after you reload the page or sign in again. See [Layout per device](https://pithyx.org/docs/user/desktop/#layout-per-device). In total you can have 50 windows open. ### What an app may access An app installed from the Store runs inside a frame of its own, without access to the rest of the desktop, to your cookies or to your password. It talks to Pithyx only through a controlled channel. An administrator sees what an app asks for before installing it. The possible permissions are: | Permission | What it lets the app do | | ---------------------------- | -------------------------------------------------------------------------- | | **Read files** | Read files in the shared folders you may use | | **Change files** | Create, change and delete files in the shared folders you may write to | | **See shared folders** | See which shared folders you may use | | **Notifications** | Show notifications to that user | | **See all users and groups** | See the names of every user and group on the box | | **Internet** | Connect to servers on the internet. Without it, the app stays on this box. | Good to know: - An app acts with your rights. It never sees a shared folder you cannot use, and it cannot write where you only may read. With **Read files** and **Change files** it can use the whole file API of the box in your shared folders, not only files you picked. - An administrator can switch a permission off for an app. The change reaches open windows within a few minutes. - If an administrator removes your right to use an app, its windows close. - Apps with a backend run their own service in containers on the box. Depending on the app, the backend runs all the time, or it starts when someone opens the app and stops again after the last window closes (10 minutes later unless the app sets another time). - Apps installed from a file are not checked by the project. Administrators should only install apps from developers they trust. For administrators: [Apps and the Store](https://pithyx.org/docs/admin/apps-and-store/). ### When an app does not start - **The window closes at once or the app is gone.** An administrator may have disabled or removed it, or taken away your right to use it. Ask an administrator. - **The app is slow on its first start.** A backend that was stopped needs a moment to start. A request to it waits up to 30 seconds. If it still fails, you see "The app's backend is not running or does not answer. Try again in a moment." - **A message mentions the container service** or that the backend could not start. An administrator can read the app's log in the Log Center. - **A message says the folder for the app's storage is not ready.** The pool with the app's data is missing, offline or locked. Nobody can open the app until it is back. - **The app's access expired** ("Close the app and open it again."). Close the window and open the app again. - **The connection between the app and the desktop is closed.** Open the app again. - **The app does not answer.** After five seconds a dialog asks whether to **Wait** or **Close anyway**. Closing loses unsaved changes. - **The app needs a newer version of Pithyx.** Ask an administrator. ## Your account > Password, two-factor sign-in, how long you stay signed in, and personal settings such as language, theme and accent. Source: https://pithyx.org/docs/user/account/ Markdown: https://pithyx.org/docs/user/account.md Your account is your user name and password on the box. The same password signs you in to the desktop and to file services such as SMB and SFTP. You cannot change your own password yourself: an administrator sets a new one. You can turn on two-factor sign-in and choose language, theme, accent color and wallpaper. ### Changing the password Pithyx has no way for users to change their own password and no reset by email. Ask an administrator to set a new one. The administrator does this in Settings > **Users** with **New password**. You are then signed out everywhere and sign in with the new password. File services use the new password too. A password must have: - at least 8 characters and at most 1024, - no match on the built-in list of widely used passwords. There are no rules about capital letters or symbols. A long passphrase of several words is easier to remember than a complex password. When an administrator types a new password, the page shows a strength meter (**Weak**, **Medium**, **Strong**) and hints. The meter only advises; a weak password that is long enough is accepted. If you are an administrator and forgot your password, use the recovery key. See [Recovery and reinstall](https://pithyx.org/docs/install/recovery/). ### Two-factor sign-in ![The dialog Two-factor authentication with a QR code, the key to enter manually, the field Code and the button Turn on](../../../../assets/screenshots/account-two-factor-qr.webp) _Scan the QR code with an authenticator app, then enter the code it shows._ ![The dialog Your recovery codes with ten one-time codes and the button Copy codes](../../../../assets/screenshots/account-recovery-codes.webp) _After the first code the dialog shows ten recovery codes, once. These belong to a deleted test machine._ Two-factor sign-in asks for a code from an authenticator app on your phone in addition to your password. It is optional and applies per user. Any app for time-based codes works (6 digits, 30 seconds). To turn it on: 1. Open the Pithyx menu, click your name and choose **Two-factor authentication**. 2. Click **Set up**. 3. Scan the QR code with your authenticator app, or enter the key shown below it by hand. 4. Type the code the app shows into **Code** and click **Turn on**. 5. Store the recovery codes. Pithyx shows 10 codes once. Each works one time instead of a code from the app. Click **Copy codes** and keep them somewhere safe. When you sign in, Pithyx asks for the code after the password. Click **Use a recovery code instead** if you do not have your phone. A code can be used only once. You have five minutes to finish the second step. To turn it off, open the same dialog, type **Your password** and click **Turn off**. Setting it up again replaces the old secret and creates new recovery codes. > **Note:** > > Two-factor sign-in protects the desktop only. SMB, SFTP, WebDAV and FTP use your password alone. Keep the recovery codes safe. If you lose both your phone and the codes, ask an administrator for help. ### Sessions and devices Pithyx does not show a list of your sessions and cannot sign out your other devices from the desktop. What it does: - You stay signed in for up to 7 days without using the desktop and at most 30 days in total. An open desktop keeps the session alive until the 30-day limit. - **Sign out** ends the session of this browser only. - When an administrator sets a new password for you or deactivates your account, all your sessions end. - Each browser is recognized as a device by a cookie, which the box uses to remember your windows. To copy the arrangement of another device, open your account menu and choose **Get desktop from**. See [Layout per device](https://pithyx.org/docs/user/desktop/#layout-per-device). - An expired session shows "The session has expired. Please sign in again." ### Language, theme and accent Open the Pithyx menu, click your name and choose: - **Language**: **Automatic** (follows your browser, English or German) or a language by its own name. The choice belongs to this device. The sign-in page has its own language selector. - **Appearance**: **Like the system**, **Light** or **Dark**. This also belongs to this device. - **Accent color**: **Petrol**, **Ocean**, **Indigo**, **Plum**, **Moss** or **Graphite**. It is saved for your account and is the same on all your devices. - **Wallpaper**: **Pithyx boxes** or **Plain**, also saved for your account. Dates, times and number formats follow the region and time zone an administrator set in Settings. Your display name is set by an administrator; you cannot edit it yourself. ## 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-