OSM Documentation 0.1.0 Search

What OSM does

OSM is a complete server operating system: it installs from a USB stick onto the computer's own disks, and from then on you manage everything from a desktop in your web browser. This page lists what it does, area by area. The Administrator's guide explains how to use each part.

Installation and the system

  • Install from a USB stick. OSM Setup runs in your browser. It shows the computer's disks and hardware, sets up RAID and the first volume, creates the first Administrator, and configures the network and updates. A setup code shown on the server's own screen keeps anyone else on your network from installing first.
  • No default passwords. Until the first Administrator exists, the server's web page only sets OSM up, and it asks first for the setup code shown on the server's own screen.
  • Ethernet or Wi-Fi for the installation, chosen at the server's screen, with a list of the networks around. The installed server joins the same network.
  • The system on every disk, mirrored (RAID 1), each disk able to start the server on its own; or on one or two separate system disks; or on some of the disks only.
  • UEFI with Secure Boot, through Debian's signed boot chain, or BIOS start-up. amd64, and arm64 computers with UEFI firmware.
  • An encrypted system if you want one (LUKS2): a TPM 2.0 chip unlocks it at start-up, or a passphrase typed at the server's screen; a recovery key is shown once at the end of the installation.
  • A status screen on the server's display: its address (with a QR code on a wide enough screen), health, load, volumes, apps and updates. A reset menu there sets a new Administrator password or puts the network back to DHCP, and K chooses the keyboard layout of the screen.
  • A hardware check before anything is installed: devices without a driver and missing firmware, and a hardware report to save. The same check and report are in System Info.
  • A watchdog, once turned on in Settings > Power and Hardware, restarts a server that hangs (a hardware watchdog when the computer has one).
  • In a virtual machine: images for Proxmox VE and QEMU, VirtualBox, VMware and Hyper-V; the QEMU guest agent with one switch.

Storage

  • Volumes on RAID: Basic (one disk, ready to become a mirror), JBOD, RAID 0, 1, 5, 6 and 10, with ext4 or Btrfs.
  • Flexible RAID: disks of different sizes in one storage pool, using almost all of each. It grows when you add a disk or put a bigger one in a smaller one's place.
  • Storage pools with several volumes, which grow while in use.
  • ZFS as an option (ZFS support, installed in Storage, builds it on your server).
  • Self-healing volumes on RAID 1, 5, 6 and 10: each block's checksum is checked on every read, and a damaged block is repaired from the other disks of the RAID. Writes are about half as fast.
  • More disks for a volume: another mirror, RAID 1 to RAID 5, RAID 5 to RAID 6, bigger arrays; the volume grows by itself.
  • Hot spares that take a failed disk's place by themselves, and Repair onto a new disk, the system disks included.
  • Health: SMART on every disk with scheduled self-tests, data scrubbing once a month or quarter, the port and controller of each disk, and disks plugged in or out noticed at once.
  • Snapshots of shared folders on Btrfs and ZFS, by hand or on a schedule, kept by rules. Immutable snapshots (off unless you choose them) cannot be deleted before their time, not even by an Administrator, so ransomware cannot take the history away.
  • SSD cache for a volume: read-only, or read-write on two mirrored SSDs.
  • USB drives: mounted when plugged in, shown in Files, ejected, formatted, and copied to a shared folder when plugged in (Auto-copy).
  • iSCSI targets for Windows, VMware, Proxmox and Linux, with CHAP.
  • Network Boot: the network's computers start from the server (PXE): installers and live systems from a menu made from ISO files, or a disk of their own on the server (iSCSI), or a copy of a master made new at each start.
  • Spin-down of idle hard disks, and the Analyzer: the biggest folders and files, kinds of files, the oldest, duplicates.

Shared folders and files

  • Shared folders with Read/Write, Read only or No access for each account and group. The same rules hold in Files, over SMB and NFS, and for apps.
  • Quotas for each shared folder, and for each account on ext4 volumes.
  • A recycle bin in each shared folder, for Files and SMB, emptied by hand or after some days.
  • Encrypted shared folders, locked and unlocked with their password, or unlocked by themselves at start-up (Unlock at start-up): OSM keeps the password sealed in the computer's TPM chip, or on the system disk when there is none.
  • Copy from another server: the shared folders of your old NAS or computer (SMB or NFS) copied into shared folders here, in the background, then only what changed, until the day you switch; nothing on the old server changes.
  • Files in the browser: upload, download, copy, move, rename, zip and extract, thumbnails, a viewer for pictures, videos, music and PDFs, a text editor, favorites, permissions, and earlier versions from snapshots.
  • Share links for a file or a folder, with a password, an end date and a number of downloads if you want; file requests that let others send you files and see nothing else.
  • Search from the top bar: apps, settings, help and file names. Full-text search in the shared folders you choose, always within the reader's own permissions.
  • File protocols: SMB for Windows, macOS and Linux (Time Machine too, and the server in the Network list of Windows and macOS), Previous Versions in Windows from the snapshots, NFS with rules per shared folder, FTP and FTPS, SFTP and rsync over SSH.
  • Desktop Sync: computers keep folders in sync with the server (Syncthing), and the server keeps the earlier versions of what they change or delete.
  • Remote folders: SMB, NFS and cloud storage in an account's own folders.
  • Media streaming to TVs and players on your network (DLNA), from the shared folders you choose.
  • Home folders for each account, on the system disks or on a volume.

Accounts and sign-in

  • Accounts and groups: Administrators and Standard users, groups for shared folder permissions, import from a CSV file, rename any account, lock and unlock.
  • Password rules: length and kinds of characters, never the account's name or a common password, expiry, a new password at the next sign-in, lockout after repeated failures, and password reset by email.
  • Two-step sign-in with an authenticator app, ten recovery codes, and trusted browsers.
  • Passkeys: sign in with a phone, Windows Hello, Touch ID or a security key, without a name or a password.
  • Directory services: join an Active Directory domain, or connect to an LDAP server; domain accounts sign in and use shared folders with their groups.
  • Domain: the server as the domain controller of your home or office (Active Directory, made with Samba), in an app of its own: Windows, macOS and Linux computers join it, and their people sign in with one account everywhere, the shared folders included. Accounts (one by one or from a spreadsheet), groups, computers and units, DNS, password rules, Group Policy links, shared folders as drive letters at sign-in, checks that repair what they find, and a copy of the domain every night. Each computer's place on the network (address, what answers, wake-up), a remote desktop to the Windows PCs and a terminal to the Linux servers in the browser, Linux servers joined with one command (sudo for the domain's groups, SSH keys kept with the accounts), and rules per unit: who may sign in, Remote Desktop, the PCs' administrators.
  • Single sign-on for apps (OpenID Connect) with OSM's accounts, and App Permissions: which account or group may use which app.
  • Active sign-ins with remote sign-out, and an audit log of every change an Administrator makes.

Apps

  • The App Catalog: system apps (containers, virtual machines, VPN, antivirus, print server, Network Boot...), Debian's packages kept on the server itself so they install without the internet (file protocols, media streaming, SSH, iSCSI and ZFS install the same way, on their own page of Settings or Storage; ZFS support comes from OSM's update service), and container apps that install with one click: AdGuard Home, Pi-hole, Nextcloud, Collabora Online, ONLYOFFICE Docs, Syncthing, Immich, PhotoPrism, Jellyfin, Plex, Navidrome, Audiobookshelf, Home Assistant, Node-RED, Mosquitto, Frigate, Vaultwarden, Paperless-ngx, Stirling-PDF, Joplin Server, Trilium Notes, FreshRSS, Matrix chat, a mail server, Radicale (calendars and contacts), Gitea, VS Code (code-server), IT Tools, Grafana, Uptime Kuma, MariaDB, PostgreSQL, Adminer, qBittorrent, a remote desktop gateway, UrBackup, Nginx Proxy Manager, Tailscale, WireGuard Easy, Websites and a Minecraft server.
  • Ready at once: where an app has an administrator, OSM makes it at install, with a strong password shown on the app's page in the App Catalog; Mosquitto gets a login for your devices. Plex links to your Plex account instead, and Vaultwarden's users sign themselves up.
  • On the desktop: every app with a web page is an icon with its own logo. More than 20 of them open signed in, with their own password (which the browser never sees) or with the OSM account itself.
  • No port conflicts: each app gets free ports, or an address of its own on your network.
  • Priorities and limits: Critical, High, Normal or Low for the processor, the disks and memory; memory and CPU limits.
  • Network rules for each app: what it may reach (anywhere, the local network only, nothing) and who may reach it.
  • Updates by hand or automatically, with channels where the app has them, and back to the previous version if the new one does not start.
  • More apps: signed catalogs of other publishers, and CasaOS app stores (most apps of CasaOS's own store install from OSM: 163 of its 178 when last checked), each app checked before it can install.
  • Containers: containers, images and networks, logs, a shell inside, your own containers, and Compose projects with risky settings refused unless you agree to each one.
  • Cameras for Frigate: cameras found on your network (ONVIF), their streams set up for recording and detection.
  • Home Assistant: the server as a device in Home Assistant (MQTT), with its health, volumes, UPS and backups.

Virtual machines

  • KVM virtual machines with UEFI, Secure Boot and a TPM (Windows 11 among others), on your network (bridge) or behind the server (NAT).
  • The screen in the browser, and the actions you expect: shut down, force stop, pause, settings, delete.
  • Ready-made systems from their publishers' images, and installers from ISO files.
  • PCI and USB devices passed through to a VM, with the IOMMU groups shown.
  • Priorities and start order: Critical VMs start first.

Backup and recovery

  • Encrypted, versioned backups (restic) of shared folders, home folders, the apps' data and the server's settings and accounts: to another volume, a USB drive, another server over SFTP, a REST server or S3 storage; daily, weekly or by hand; kept by daily, weekly, monthly and yearly rules. The apps' databases are read as they stood at one moment: on Btrfs and ZFS the apps pause for about a second for a snapshot.
  • Restore single files from any version, browsed folder by folder, back where they were or into a new folder; or everything onto a new server: accounts, groups, settings, shared folders with their permissions, and the apps with their data.
  • Backups that prove themselves: every month, two hours after the task's time, a sample of each backup is restored and compared with the files on the server, and a report is sent.
  • Cloud tasks: a shared folder kept in step with cloud storage (WebDAV, S3, Backblaze B2, SFTP, Google Drive, Dropbox): upload or download, either adding and updating files or mirroring (also deleting on the other side).
  • Replication of the snapshots of shared folders on Btrfs to a second OSM server, only what changed each time.
  • Backups of your PCs to OSM with UrBackup.
  • Restore points before every update, automatic ones included.
  • A configuration backup: one file to export and import on a new installation. It brings back Desktop Access, automatic updates, the server's screen, the groups, the shared folders with their permissions, and whether the firewall is on; not the accounts and passwords, the network, the backup tasks or the apps. An import lists what it could not make.
  • A factory reset that keeps your data, from Settings or the server's screen.

Network and remote access

  • Network settings on a bridge, so virtual machines and apps sit on your network like any device: DHCP or fixed addresses, several network cards, bonding, VLANs, IPv6, static routes, Wi-Fi. A change that cuts you off is undone after 90 seconds unless you keep it.
  • VPN server (WireGuard), with a QR code for each phone; VPN client (WireGuard or OpenVPN) for the server or chosen apps, with a kill switch.
  • OSM Connect: the server at an address of its own from anywhere, through OSM's relay, with nothing opened on the router and nothing the relay can read; stricter sign-in there (two-step every time, Administrators only unless you allow more, a pause after repeated failures, a new sign-in told). Needs an OSM account with OSM Connect.
  • Remote access without opening ports (Tailscale), Dynamic DNS (DuckDNS, deSEC, No-IP, Dynu, FreeDNS, Cloudflare, any dyndns2 service), and router ports opened by UPnP.
  • Certificates: self-signed at first, your own, or Let's Encrypt (HTTP or DNS challenge, wildcards) renewed by itself.
  • An address for each app (https://photos.example.com or https://server/photos) with the server's certificate.
  • Speed limits per service and per SMB user, at chosen hours; a proxy for downloads; Wake-on-LAN; a time server for your network.

Security

  • A checked privileged core: OSM's web process (behind nginx) has no privileges and no network; every change is one of a fixed list of operations of a root service that checks each argument.
  • A firewall that opens only what you run, with allow and deny lists, and countries blocked or the only ones let in.
  • Security Check: the settings that matter most, with one-click fixes, on a schedule with an email report; the known vulnerabilities of the installed software, from Debian's security tracker.
  • Antivirus (ClamAV) for shared folders, with a quarantine.
  • Sign-in protection: addresses paused after failed sign-ins, accounts locked after repeated failures, sessions that end when idle.
  • HTTPS only, a strict Content Security Policy, and a published security contact (/.well-known/security.txt).

Updates

  • Every part from one place: one button (Install all), or none with automatic updates, updates the system, OSM and the apps' Debian packages, all from OSM's update service: Debian's packages and OSM's, tested together and signed by OSM. Never from anywhere else.
  • Your choice for each part (OSM, the kernel, system apps, extra packages, the Debian base system, the apps): it updates by itself in the maintenance window, or waits for you. Security fixes install by themselves; critical ones at once. An update history lists every update.
  • Safe updates: before every update, a restore point, and after it a watch that goes back by itself if a service fails. Nothing older ever comes back, even signed. On UEFI servers, new kernels are tried once before they become the default. A release that went wrong on the first servers waits (two days at most) before it installs by itself on yours; servers whose owners allow it send OSM a short, anonymous report after each update (off by default).
  • The next Debian release comes through OSM's update service once OSM has been tested on it.
  • A software bill of materials (SPDX) of the server as it is.

Monitoring and automation

  • Activity: the processor, memory, network, disks, processes, connections and containers, with a history of a day, a week or a month, and alerts.
  • Logs of everything, with search; notifications in the desktop, on your phone, by email, ntfy, Gotify, Telegram or signed webhooks.
  • Scheduled Tasks: scripts or built-in actions on a schedule, at start-up or shutdown, or when something happens (a failing disk, a full volume, the UPS on battery, a failed backup).
  • For your monitoring system: Prometheus and SNMP, and a syslog server for your routers and switches.
  • A diagnostic bundle with logs and settings, passwords removed, for whoever helps you.

Power and hardware

  • Power profiles (Performance, Balanced, Power saver), and the server's power draw in the Server Status widget and in Settings > Power and Hardware.
  • Power schedules: shutdowns, restarts and starts at set times.
  • UPS: by USB, or on another server; a clean shutdown before the battery is empty.
  • System Info: devices and drivers, sensors, missing firmware; server boards' BMC (IPMI).
  • Graphics cards for apps (Intel, AMD, NVIDIA), one switch per app.

Several servers and high availability

  • Servers: the health and updates of other OSM servers, watched from one desktop (each one's own desktop opens in a tab), and the ones found on your network.
  • High Availability: two servers as a cluster with one address; volumes mirrored as you write; the passive server takes over when the active one fails.

Management

  • The web desktop in English, German or French, with themes, date and number formats for each account, a search across everything, widgets and built-in help.
  • On your phone: a page made for it (how the server is, the latest notifications, Files, sending photos), on the home screen like an app, with notifications on the phone and "Share to OSM" from other apps (Android).
  • Terminal: a shell on the server in the browser, for Administrators, with sudo and their own password.
  • An API with tokens (read only or full, with an expiry), its reference generated by the server, and a command-line client; osm on the server itself for root. A token never gets a password back, and stops working when its account is locked or expires.