OSM Documentation 0.1.0 Search

Installation guide

This guide takes you from the OSM download to the first sign-in. Allow about 20 minutes. OSM installs onto the computer's own disks, and the disks you choose are erased.

Before you start

You need:

  • The computer that becomes the server: a 64-bit PC (x86-64) with 4 GB of memory or more, or an arm64 computer with UEFI firmware. Hardware lists the requirements and the firmware settings worth making first.
  • One disk or more for OSM and your data. Back up anything on them first.
  • A wired network with DHCP (you can choose a fixed address during setup). Wi-Fi works too.
  • A USB stick of 4 GB or more. Everything on it is replaced.
  • Another computer with a web browser, on the same network.
  • For virtual machines: a processor with VT-x or AMD-V, turned on in the firmware.

1. Check the download

The OSM download holds:

  • the installer ISO, osm-<version>-amd64.iso: for a USB stick or a DVD, on PCs with BIOS or UEFI firmware;
  • the USB stick images: osm-<version>-amd64-usb.img.xz for PCs, osm-<version>-arm64-usb.img.xz for Arm computers;
  • images for virtual machines (.qcow2, .vdi, .vmdk, .vhdx);
  • the package: osm_<version>_all.deb;
  • the software lists (.spdx.json);
  • SHA256SUMS, and its signature SHA256SUMS.sig.

Checking them proves the files are the ones published, unchanged. You need OpenSSH 8.1 or later (ssh -V shows its version; current Linux distributions and macOS have it, and on Windows you may need a newer OpenSSH than the built-in one), and OSM's release key, osm-release.allowed_signers, from the download page:

ssh-keygen -Y verify -f osm-release.allowed_signers -I release@osm -n osm-release -s SHA256SUMS.sig < SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS          # on macOS: shasum -a 256 -c --ignore-missing SHA256SUMS

The first command must say Good "osm-release" signature for release@osm, and the second must say OK for every file you downloaded.

On Windows, run the first command in Command Prompt, not PowerShell (PowerShell does not accept <). Windows has no sha256sum: instead, run certutil -hashfile <file> SHA256 for each file you downloaded, and check that it prints the same value as the file's line in SHA256SUMS.

2. Write the USB stick

Two files start the same installer; use either:

  • The ISO (osm-<version>-amd64.iso): for a USB stick, or burned to a DVD.
  • The USB stick image (osm-<version>-amd64-usb.img.xz): for a USB stick only. Choose it for a server without a screen (below): a stick written from the ISO cannot be changed afterwards.

Write the file to the stick as it is, block by block (unpack the .xz first, or let the tool do it):

  • Windows: balenaEtcher, or Rufus. When Rufus asks how to write the ISO, choose Write in DD Image mode, not ISO Image mode.
  • macOS: balenaEtcher.
  • Linux: GNOME Disks (Restore Disk Image), or sudo dd if=osm-<version>-amd64.iso of=/dev/sdX bs=4M conv=fsync status=progress (the same for the .img), where /dev/sdX is the stick (check with lsblk: the wrong device loses its data).

Tools that copy files onto the stick instead of writing the image (Ventoy, UNetbootin, Rufus's ISO Image mode) are not supported: the stick may not start, or not find OSM.

A DVD: burn the ISO with the computer's own tool (on Windows: right-click the file, then Burn disc image).

3. Start the computer from the stick

Plug in the stick (or put in the DVD) and choose it in the computer's start-up menu (often F12, F11, F8 or Esc right after power-on). The stick's menu offers:

  • Install OSM: the normal choice.
  • Install OSM (safe graphics): if the screen stays black.
  • Start OSM from this computer's disks: shown, and chosen after 5 seconds, when OSM is already installed. A stick left in the computer does no harm.

Started from the ISO, the menu also offers Install OSM (copy it to memory first: the disc can come out): the installer then runs from memory (it needs 4 GB or more), and the stick or DVD can come out once the screen asks how the server reaches your network. Nothing is ever written to a stick or DVD made from the ISO.

Secure Boot can stay on: OSM starts through Debian's signed boot chain.

4. Ethernet or Wi-Fi

After about a minute, the computer's screen asks how it reaches your network. With no key pressed, it takes Ethernet after 10 seconds. Any key stops the countdown; the arrows (or 1 and 2) choose, and Enter goes on.

For Wi-Fi, it lists the networks around with their signal. Choose yours and type its password (Tab shows what you typed); hidden networks are typed by name. WPA2 and WPA3 Personal networks work, as do open ones; WPA Enterprise and WEP do not. The stick forgets the password when it restarts. The installed server joins the same network, and a network cable plugged in later is used first. If you chose Ethernet but need Wi-Fi, press W on the next screen.

The server's screen uses a US English keyboard layout until you choose yours: press K on the next screen. The installed server keeps your choice. To type a Wi-Fi password with your own layout, choose Ethernet first, press K and choose your layout, then press W for Wi-Fi.

5. Open OSM Setup

The screen then shows the address to open, a setup code and, on a wide enough screen, a QR code for phones:

Install OSM on this computer

On another computer, open:   https://192.168.1.37:5001
Setup code:   6T5D-FTG2

Open the address in a browser on another computer. The browser warns about the certificate once: the server made it itself, and keeps it after the installation. Type the setup code. It makes sure that only someone who can see the server's screen can install OSM (and erase its disks).

A server without a screen

This needs a stick written from the USB stick image (.img.xz), not from the ISO. Create an empty file named no-setup-code in the osm folder of the stick's small FAT partition, named OSMUSBEFI (the README.TXT in that folder says the same). OSM Setup then opens without a code. Find the server's address in your router's list of devices, or try https://osm-setup.local:5001. Do this only on a network you trust, and delete the file afterwards.

That partition is an EFI system partition, which Windows and macOS may not show by themselves. Mount it first:

  • macOS: find it with diskutil list, run sudo diskutil mount <its identifier>, then touch /Volumes/OSMUSBEFI/osm/no-setup-code.
  • Windows: in a Command Prompt run as administrator, give it a drive letter with diskpart (list volume, select volume <its number>, assign letter=S, exit), then run type nul > S:\osm\no-setup-code.

6. The steps of OSM Setup

  1. Welcome to OSM: the computer, its processor, memory and network, and a Hardware check: devices without a driver and missing firmware. Save a hardware report keeps a description of the computer (nothing that identifies it or you); Hardware says what it is for.
  2. Choose the disks: the disks OSM may use. The USB stick is never offered. A disk that holds something says what, and that it will be erased.
  3. Disks, RAID and volume:
    • OSM itself (the system): On every chosen disk (mirrored, so any of them can start the server), On a separate disk (one disk, or two mirrored, such as SSDs; the other disks hold only your files), or Only on some disks (they also hold part of the volume).
    • Volume 1: made now (Create volume 1 now) or later in Storage. Its disks, its RAID type (Basic, JBOD, RAID 0, 1, 5, 6 or 10) and its File system: ext4 (recommended), or Btrfs for snapshots, Previous Versions and replication. The right side shows what happens to each disk. The Storage chapter helps you choose.
    • Encryption: Encrypt the system (LUKS), off unless you choose it. With a TPM 2.0 chip, the system unlocks by itself at each start; without one, you type a passphrase at the server's screen. Either way, a recovery key is shown once at the end.
  4. Name the server and create its Administrator: the server's name (it also answers as name.local on your network), the first Administrator's account and password, and the time zone.
  5. Network: Automatic (DHCP) (the server keeps the address it has now) or a Fixed address.
  6. Updates: automatic security updates (on, recommended), all other updates, and restarting by itself when an update needs it. Every update, Debian's and OSM's, comes from OSM's update service (Updates and upgrades).
  7. Ready to install: a summary. Type ERASE and press Install.

Installing takes a few minutes; the page shows each step.

7. After the installation

  1. If you chose encryption, write down or download the recovery key now. It is shown only once, and it is the only way in if the TPM or the passphrase cannot unlock the system.
  2. Press Restart, and take the USB stick out when the computer's screen goes dark. (Or press Shut down, take the stick out, and turn the computer on again.) If the computer then says it found no bootable device, the stick came out while it was starting: turn it off and on again. A stick or DVD left in does no harm: its menu starts OSM from the disks.
  3. The same page opens the sign-in when the server is back. Sign in with the Administrator account you created.

The server's own screen now shows its status: its address, health, volumes and apps.

8. First steps

Most servers need these in the first hour. Each links to its chapter of the Administrator's guide.

  1. Shared folders and accounts: create accounts for the people who use the server, and shared folders for what they keep (Shared folders, Accounts).
  2. File sharing: in Settings > File Protocols, install SMB to reach the shared folders from Windows, macOS and Linux (Files).
  3. Apps: install them from the App Catalog (the first container app installs Containers with it), and Virtual Machines for virtual machines (Apps).
  4. Addresses for apps: in Settings > Network > Addresses for apps, give container apps a range of addresses on your network, so their ports never collide. Keep the range out of your router's DHCP range.
  5. Security: set up two-step sign-in or a passkey for your account (My Account), and run Security Check (Security). A passkey needs the server's name in the address (such as https://name.local:5001), not its IP address.
  6. Backup: back up your shared folders, and export a Configuration backup (Settings > Updates and Recovery) (Backup and recovery).

Installing in a virtual machine

The OSM download includes the USB stick image converted for virtual machines: .qcow2 (Proxmox VE, QEMU), .vdi (VirtualBox), .vmdk (VMware) and .vhdx (Hyper-V).

  1. Create a virtual machine with UEFI (or BIOS), 2 processors, 4 GB of memory, and one or two empty disks of 32 GB or more.
  2. Attach the converted image as an extra disk, and start the virtual machine from it.
  3. Install OSM onto the empty disks as above, then remove the extra disk.
  • Proxmox VE: qm importdisk <vmid> osm-<version>-amd64.qcow2 <storage>.
  • VMware: convert the .vmdk first, with vmkfstools -i (ESXi) or vmware-vdiskmanager -r (Workstation), then attach the result as an existing disk.
  • Hyper-V: a Generation 2 virtual machine; turn Secure Boot off, or choose the "Microsoft UEFI Certificate Authority" template.

When you make the virtual disks bigger later, OSM takes the room by itself at its next start (when the system is the last thing on its disks), or from Storage > Storage > System (Use the free space on the system disks...). Settings > Power and Hardware turns the QEMU guest agent on for hypervisors that use it.

Arm computers

The arm64 image starts on computers whose firmware is UEFI (EDK2, or U-Boot with UEFI), from the file the firmware looks for on the stick (EFI/BOOT/BOOTAA64.EFI, Debian's signed shim). There is no BIOS start-up on Arm: a computer that does not start by UEFI is refused before any disk is erased. Hardware lists what Debian's kernel supports on popular boards.

Installing again

Start from the stick: OSM Setup says that OSM is already installed, and installing again erases the disks you choose. To keep your data and settings instead, see Backup and recovery: a factory reset keeps your data, and a full restore puts a backup onto a fresh installation.