fez

fez is a simple script that lets you configure your mac to back up via Time Machine to an InterServer storage VPS for $3/TB per month.

details

what this is

Time Machine is Apple's integrated backup solution in macOS that can back up to a local network SMB server. Normally that server sits in your house or office, which does not help if you are traveling, your house floods, or someone walks off with the mac and the drive together.

fez puts the drive on a rented server hosted by a server provider like InterServer. You pay for the server and run one command on your mac that sets up the server, locks it down so only your mac can reach it, and hands Time Machine a backup disk.

Time Machine encrypts its backups, so your server provider or anyone else who gains access to your server cannot ever see your data.

fez is not a service. You rent the server, you own the data, and there is nothing to cancel. If this project disappears tomorrow your backups keep running. If you want to change server providers, you can do it effortlessly. fez is merely a script that configures your mac and/or server and then goes away.

how it works

Time Machine backs up to SMB shares. SMB on the open internet is a bad idea, so fez does not put it there. The share is wrapped in a mutually-authenticated TLS tunnel using pinned certificates, and your mac talks to a loopback address that behaves like a file server on the local network. This all works without installing any new software on your mac, by configuring the a sandboxed openssl process on loopback as an inetd service.

macOS
  Time Machine
      |
      |   SMB
      v
  127.0.0.2:445      launchd socket, inetd process
      |
      |   mTLS 1.2+
      v
  VPS:443            nginx stream, ssl_verify_client on
      |   SMB
      v
  timemachine:445    samba + vfs_fruit, docker network only, requires share pwd
      |
      v
     /tm             sparsebundles land here

on your mac

Two launchd jobs are added. The first job runs at boot and adds the 127.0.0.2 loopback alias. The other is an inetd-style socket listener: when something connects to 127.0.0.2:445, launchd spawns /usr/bin/openssl s_client with the socket wired to its stdin and stdout. That process carries the mTLS connection (with pinned certificates) for as long as the SMB session lasts and then exits. smbfs tends to re-use a single TCP connection, so you generally only see one openssl process.

To reiterate: no new software is ever installed on your mac; the script configures some things, then Time Machine and openssl do all the heavy lifting. See how do I remove it from my mac? for how to remove the configuration.

on the VPS

Docker Compose runs two containers. mbentley/timemachine is Samba with vfs_fruit set up as a Time Machine target, listening only on the Docker network. In front of it, nginx uses its stream module as a TCP proxy: terminate TLS on 443, check the client certificate, forward the raw bytes to Samba. 443 is the only externally-bound port.

authentication

The client certificate is generated on your mac at install-time and lives in /etc/fez with the key only readable by root. The nginx server allows only connections with the certificates of macs you've configured. Behind that, each Samba share has its own password, generated once per server, which is saved in the keychain.

Your mac checks the server the same way, against the certificate it collected over SSH during install or enroll.

encryption

There are two independent layers of encryption here. Time Machine encrypts the backup on your mac, with a password only you have. The openssl tunnel encrypts the connection separately. The hosting company sees encrypted backup data arriving over an encrypted connection.

backing up other people (--multiuser)

Multi-user mode is optional, and off unless you specify it during install. This enables an admin page and an invitation flow, to make it easier to onboard a friend or family member without giving them SSH access to the server. There is still just one port exposed: nginx reads the name out of the TLS hello with ssl_preread and routes the connection to one of two additional containers:

VPS:443
  |
  +-- fez.internal          client cert required   →  samba
  |
  +-- admin.fez.internal    admin cert required    →  admin-ui
  |
  +-- public.fez.internal   no cert required       →  enroll-queue

Both admin-ui and enroll-queue are stock node:22-alpine with a single script file from the installer mounted into each.

enroll-queue is the only thing on the server that talks to strangers, so it is built to be boring: no disk writes, no capabilities, not root, read only filesystem, no dependencies beyond the Node standard library, and one accepted request. Its own script is the only thing mounted into that container, so it cannot see the certificates, the share configuration, or the backups. It holds invitation codes in memory and notifies the admin-ui process when a valid enroll occurs.

admin-ui is the opposite; this container requires admin authentication. It writes share configuration, owns directories under /tm, and signals the other containers, so it runs as root in the host PID namespace. nginx only routes to it after checking a certificate from a separate bundle (/etc/fez/admin-certs.pem) which by defailt contains the certificate of the mac that set the server up.

what it costs

InterServer rents storage VPS servers by the slice at $3 per TB per month. You pay for raw storage, so the price does not change based on how many macs you back up or how often.

StoragePriceGood for
1 TB$3 per monthA laptop with a 256 or 512 GB drive
2 TB$6 per monthA 1 TB drive, or two macs
4 TB$12 per monthSeveral macs, or years of history

Storage servers are available in Los Angeles, Dallas, and New Jersey.

Time Machine keeps old versions of files, so it wants more space than the drive you are backing up. Two to three times the size of your mac's drive is a comfortable target, which for most laptops means the 1 TB tier is enough.

setting it up

  1. rent the server

    Sign up for an InterServer Storage VPS and pick the number of slices you want. When it asks for an operating system, I recommend choosing Debian, and choose a strong, random root password.

    I usually generate my passwords with openssl rand -hex 16. Store the password somewhere safe, or write it down.

  2. run the installer

    Open Terminal on your mac (press ⌘-Space, type Terminal, press Return) and run these lines to download the script:

    curl -o ~/Downloads/ https://fezbackup.com/install_fez.sh

    Now run the script, providing your own server IP as the last argument:

    bash ~/Downloads/install_fez.sh 1.2.3.4

    The script asks for your mac's password so it can install a launchd job, and then for the server's root password (unless you've set up an ssh keypair already). It takes a few minutes, mostly waiting on the server to install Docker.

    This is a plain shell script with no dependencies. It is idempotent, so if an install fails you can just re-run it.

    If you are going to back up other people's macs too, add --multiuser. That installs an admin interface for managing user shares and enroll codes. You can always start without it and re-run with it later.

  3. write down the backup password

    When complete, it prints the share details and suggests a backup password:

    Share password      ee0f23088a66941e70992e917e470524
    Backup password     2EE5CE33-0672-4858-B3D1-2D479AFCEA99
    

    Store the "Backup password" somewhere safe, a password manager or paper. After configuration, Time Machine encrypts your backups with it so that nobody can recover your backups without it (including you).

    The installer also prints a share password. After setup should never need to use it, since macOS keeps it in your keychain. If you lose it, you can find it on the server under /etc/fez/$SHARE/share.conf.

    You can just ignore the suggested backup password and supply your own, but you should choose something complex enough to be resistant to offline bruteforcing.

  4. point Time Machine at it

    The installer should have mounted the share when done. Next, open System Settings → General → Time Machine, click Add Backup Disk → TimeMachine, and turn on Encrypt Backup using the backup password. You will be asked for the share password again, make sure to select "Save password in keychain".

    The first backup copies your whole drive, so expect to leave it running for at least a few hours or overnight. After that Time Machine only sends what changed.

  5. disable sshd on the server (optional, recommended)

    In general, requiring a complex, random ssh password is "good enough" to survive on the internet, but your ssh server will still inevitably receive a lot of stray login attempts. As the server admin it is a good idea to keep sshd disabled when you aren't using it for setting up or restoring clients.

    click here to see how to do that To disable ssh, first ssh into the server as root and run:

    systemctl disable --now sshd

    When you want to use ssh to access your server again: log into InterServer's control panel, click VPS -> Manage, and then click the "View Desktop" button on the right, which will give you access to the out-of-band console TTY. Login as Username: root and enter your root password, and then re-enable sshd:

    systemctl enable --now sshd

    If you instead prefer to keep sshd running all the time, I recommend looking at disabling password login entirely in your sshd_config and setting up an SSH keypair.

questions

can several people share one server?

Yes. By default, a single "timemachine" share is used - if you're backing up a couple personal devices an easy method is to just have them all in one share; you just run the script as normal.

If you are trying to support different users, you can set them with their own shares so they can't see each others' backups. Each share is a separate Samba user with its own password and its own directory under /tm.

Run the install script with --multiuser to enable this, then:

1. The admin adds the share from the admin page. First, enable the admin page on your mac:

sudo launchctl enable system/com.fezbackup.admin
sudo launchctl bootstrap system /Library/LaunchDaemons/com.fezbackup.admin.plist

Or install with --admin instead of --multiuser, which registers this mac as an administrator on the server and leaves the page switched on for you. It is also how you add a second administrative mac.

Then browse to the admin page at: http://127.0.0.2:8443/:

That page lists the shares and how much disk each is using. Under add a share, type alice, optionally give her a quota, and submit. It creates the share, generates the password, and prints a banner with the install_fez.sh script link, and the command Alice needs to run:

./install.sh --server 1.2.3.4 --enroll a00ffee9fafccd7953cef4e90fee07fd

2. Alice runs the enroll command. Her mac generates its certificate, hands it over along with the enroll code, gets back her share name and password, and proceeds with the local setup process.

If Alice's mac later dies, her certificate is also gone. The admin will need to send her a new enrollment code by clicking the new invitation link on the admin page.

how do I restore from my backup?

On a new or erased mac. Run the fez installer on it the same way you did the first time, which puts the tunnel back and mounts the share.

The share is not the backup. Time machine keeps everything inside a sparsebundle disk image, and Migration Assistant will not look inside one for you, so open it first:

  1. In Finder press Command-K and connect to smb://127.0.0.2/<share>, giving the share password when it asks.
  2. Double-click <your mac>.sparsebundle in the window that opens.
  3. If you turned on Encrypt Backup, it now asks for the backup password, which is the other one.
  4. It mounts as a disk called Time Machine Backups.

Then open Migration Assistant from the Utilities folder, choose to transfer from a Time machine backup, and pick Time Machine Backups. If it shows nothing, the sparsebundle is not mounted and step 2 did not happen.

If you only want to read the backup, add --recovery:

/tmp/install_fez.sh <server address> --recovery

That does exactly the same install, but finishes by telling you how to open the sparsebundle instead of how to switch Time Machine on, so a mac you are restoring onto does not start backing itself up halfway through. Nothing needs re-running afterwards: when you do want it backing up, add the share in System Settings → General → Time Machine.

It does not work from the macOS Recovery environment. Recovery has no openssl, ruby or python, so the tunnel cannot be built there. Reinstall macOS, create a temporary account, boot into the full system, and restore from there.

If you joined with an invitation code. The certificate that let you in lived on the mac, and is now gone. Ask whoever runs the server for a new code: on the admin page that is the new invitation link on your row, and it hands back the same share password you already had. Then run one command on the new mac, or add --recovery to do it from Recovery:

/tmp/install_fez.sh --server <server address> --enroll <new code>

The old certificate keeps working until someone revokes it, so say something if the mac was stolen rather than broken: the admin can remove it under allowed clients on the admin page.

Either way you need the backup password, since the backup is encrypted. Without it the files cannot be read, by you or anyone else.

what if I lose the backup password?

The backups are gone. Time Machine encryption has no recovery option, which is what makes it safe to keep backups on someone else's computer. The backup password is not stored or sent anywhere; it is just securely generated for your convenience. You can use a different password than the generated one if you'd like. In any case, I recommend writing it down.

how do I remove it from my mac?

Run the installer with --uninstall. It asks you to type yes, then stops the launchd jobs, deletes /etc/fez, drops the loopback alias, removes the log and unmounts the share. It never touches the server or your backups.

/tmp/install_fez.sh --uninstall

Afterwards, remove the backup disk in System Settings → General → Time Machine, or it will keep trying.

how do I remove it from my server?

Bring the service down, then delete /etc/fez:

cd /etc/fez
docker compose down
rm -rf /etc/fez

That just leaves the backups, which are in /tm. Delete them when you're ready.

what versions of macOS are supported?

macOS High Sierra and up. I test each release end-to-end on the latest OS as well as a High Sierra machine.

macOS versions before High Sierra shipped with openssl 0.9.8, which you could feasibly make work in a fork by severely tuning down nginx's cipher options (see legacy-branch for my attempt at this, but I make no guarantees that it will work), but I decided the added complexity was not worth supporting in the mainline release.

will this work on other servers besides InterServer?

Yes. Any Linux server you can ssh into as root works, as long as it can run Docker and has the disk space. Nothing in the installer is specific to InterServer.

I need more help!

Open an Issue in our Github repo, and we will try our very best to diagnose the situation and assist you <3.