Self-hosted open-source multi-user multi-platform secret management

TLDR: Syncthing, KeePassXC, Keepass2Android, AuthPass, and WebDAV via Apache HTTP Server allow for self-hosted open-source multi-user multi-platform secret management.

This article describes the secrets management setup used by me and my family. This is not a tutorial, but rather an overview of the possibilities and what works for us.

The setup:

• is fully open source with Open Source Initiative-approved licenses
• is multi-platform, it supports macOS, Linux, Windows, iPhone, and Android
• is multi-user, you can share secrets
• is self-hosted with low maintenance
• supports passwords, TOTP, SSH keys and any other secret
• has browser support
• does not require tech-savvy family members (one is enough)

The tools

• KeePassXC for macOS, Linux, and Windows
• Keepass2Android Offline for Android
• AuthPass for iPhone
• Syncthing for macOS, Linux, and Windows. For Android: F-Droid or Google Play
• Apache HTTP Server with WebDAV

KeePassXC, Keepass2Android Offline and AuthPass

These are three nice and complete apps that all support secret databases in the KeePass format. Although some variations exist, I have never experienced interoperability issues with these tools.

To use KeePassXC in the browser, you need a browser add-on. Many browsers are supported. Keepass2Android and AuthPass integrate well with the Android and iOS environments and don't require additional software.

On Andriod we're using the offline version of Keepass2Android since we already have Syncthing to get the keepass file.

Bonus features

Bonus feature 1: KeePassXC can also be used as an SSH-agent. This allows you to use SSH-keys as long as the KeePass database is unlocked. The SSH keys are synced along with all the other secrets. No more private key files on disk!

Bonus feature 2: if you ever lost a phone with Google Authenticator installed, you know how painful it is to set up 2FA with TOTP again. Configure TOTP in these apps instead, and that worry is gone.

Syncthing

Syncthing is an amazing program. It just continues to work with very little maintenance. It can synchronize multiple folders between multiple devices. Once a device is connected to another device, they automatically find each other over the internet.

Each person stores their main secrets database in a 'small' folder containing only the files they want to sync to their phone. This small folder is not shared between people. Then there are 'larger' folders that are optionally shared between multiple people. These larger folders are only synchronized between desktops and laptops and are a good place to store shared KeePass databases.

To ensure that all devices with Syncthing always stay in sync, it is a good idea to share all folders with a machine that is always on. Ideally the Syncthing port (22000) would be exposed directly to the internet. This reduces sync conflicts because it is more likely that all devices see the changes from the other devices.

Since you're going to create many folders, think about a naming convention. Our folders start with the name of the owner. The Syncthing folder name can be different from the directory in the file system. For example, the Syncthing folder could be named erik-documents while on my device the directory is called documents.

Even though there is a very nice Android application, Google has made it maddeningly difficult to publish to the Play store. So difficult even, that the maintainers have given up. Fortunately, you can still get a maintained fork via F-Droid or Google Play.

Bonus features and tips

Bonus feature 1: Store all your documents in a Syncthing folder so that you can access them from multiple devices.

Bonus feature 2: Configure a Syncthing instance to keep older file versions. Now you have a backup too!

Bonus feature 3: Sync the camera folder on your Android phone.

Tip 1: Using Homebrew? The most convenient way to install Syncthing is with the command brew install --cask syncthing-app.

Tip 2: When starting a new Syncthing device, remove the default folder shared from directory ~/Sync. Instead, put the folders you're sharing below the ~/Sync directory.

Tip 3: Before you create any folder in Syncthing, change the folder default configuration to have the following ignore pattern. This is especially important when you use Apple devices.

(?d)**/.DS_Store
(?d).DS_Store
#include .syncthing-patterns.txt

Tip 4: All the GUIs of the locally running Syncthing instances have the same 'localhost' URL. Since the URL is the same, you should also use the same password. Otherwise, storing the password in KeepassXC becomes difficult.

Support iPhone with Apache HTTP Server and WebDAV

Due to limitations imposed by iOS (no background threads unless you are paid by Apple), Syncthing does not run on iPhones. Fortunately, we found AuthPass which supports reading from and writing to a WebDAV folder. AuthPass does this really well; if you make changes while being offline, it automatically merges those changes into the latest version of the remote database once you go online again!

Fortunately, we already have a Linux server running Apache HTTP Server that is always on. (The websites there are also synced with Syncthing.) By configuring a WebDAV folder in Apache HTTP Server (protected by a username/password), we can share a Syncthing folder with AuthPass. Each person with an iPhone will need their own WebDAV folder.

Sharing secrets with KeeShare

KeeShare is a KeePassXC feature that allows you to synchronize a shared KeePass database with your main database. Since the main database contains a complete copy of the shared database, you only need to set up KeeShare on one device. Other devices, including your mobile phone, do not require direct access to the shared database.

Since KeeShare is only supported in KeePassXC, you must periodically open KeePassXC. Otherwise, you will miss changes in the shared databases. Shared databases won't sync if you only use the KeePass database on your mobile phone.

Tip: Sharing secrets is limited; you can only share entire databases. Therefore, plan ahead and decide how you want to organize secrets. We settled on a shared database for the whole family, and another shared database for just me and my partner.
Since each shared KeePass database is password-protected, you can store them all in the same shared Syncthing folder. However, if you are sharing other things as well, you may want to create multiple Syncthing folders.

Maintenance

Sometimes two offline devices modify the same KeePass file. Later, Syncthing detects the conflict and stores multiple files, one for each conflicting edit. You can merge all the conflict files using the database merge feature in KeePassXC. After merging them into the main database, you can delete the conflict files. Unfortunately, there is no default way to detect the presence of these conflict files. I manually check the synced folders once every few months (or when I miss a secret!). If you build a detection script, please share!

Since Syncthing runs so quietly in the background, you won't notice when things go wrong. To prevent this, check the Syncthing UI every few months.

Not explored options

KeePassXC has a command-line interface. This could be useful for Linux servers or scripts.

Conclusion

We have used this setup for over four years and have found it to be user-friendly and low-maintenance. Even my teenager kids are fervent users. Despite losing several devices, our secrets have never been lost.

Updates

Update 2025-10-12: updated the links to the syncthing android app on F-Droid and play store.

Update 2025-10-12: recommend Keepass2Android Offline instead of Keepass2Android.

Upgrading Libreoffice with Homebrew

Update 2023-06-06 brew now asks for your password so it can install everything directly. Much better!!

The text below is no longer applicable and only kepts as reference.

---

Reminder to self: this is the procedure to upgrade Libreoffice with Homebrew:

1. brew update
2. brew upgrade
3. open -a /Applications/LibreOffice.app
4. Quit the application
5. brew reinstall libreoffice-language-pack, enter your password
6. open "/usr/local/Caskroom/libreoffice-language-pack/$(cd /usr/local/Caskroom/libreoffice-language-pack; ls -1 | sort -rV | head)/LibreOffice Language Pack.app", click 'Ok', click 'Ok'

Please anyone, please make this simpler...

Update 2021-03-24

Here is a script to remove most of the manual toil:

#!/bin/bash echo "Initiating Libre Office upgrade" brew update brew upgrade libreoffice open -g -a /Applications/LibreOffice.app echo "Wait until the application completed startup (it is started in the background)" read -p "Press enter to quit LibreOffice" osascript -e 'quit app "LibreOffice"' APP=$(brew reinstall libreoffice-language-pack | tee /dev/tty | grep "LibreOffice Language Pack.app" | xargs) open -a "$APP" echo "The language pack installer has been opened."

Bash history backup

I like my bash history, and I proudly have this in my .bash_profile:

# Increase bash history size, append instead of overwrite history on exit export HISTSIZE=10000000 export HISTCONTROL=erasedups shopt -s histappend

However, after reading about Historian I realised I have no backup. Instead of installing Historian, I decided to take a simpler approach. Here it is:

#!/bin/bash set -euo pipefail IFS=$'\n\t' # # Makes a daily backup of your .bash_history, keeps the last 2 backups. # BACKUPDIR="${HOME}/.bash_history_backup" mkdir -p "${BACKUPDIR}" cp ${HOME}/.bash_history "${BACKUPDIR}/bash_history_$(date +%Y%m%d)" for h in $(ls -1r "${BACKUPDIR}"/bash_history_* | tail -n +3); do rm $h; done

Put the above contents in a file somewhere, e.g. in ~/bin/bash_history_backup.sh and activate it with:

ln -s ~/bin/bash_history_backup.sh /etc/cron.daily/

or add the following line with the more cumbersome route through crontab -e:

0 0 * * * $HOME/bin/bash_history_backup.sh

Update 2017-04-22: The script actually works now :)

Update 2017-04-23: The script actually actually works now :)

Installing gnutar on Maverick

Unfortunately Apple decided to remove /usr/bin/gnutar from Maverick (Mac OSX 10.9). This is a pain because most of the tarring I do on my mac is to transfer the file to a GNU based linux (e.g. Debian/Ubuntu). Apple's bsd-tar is not compatible with gnu-tar.

This is my solution:

brew install gnu-tar cd /usr/bin sudo ln -s /usr/local/opt/gnu-tar/libexec/gnubin/tar gnutar

Getting size of a file in shell script

This is really too silly. There seems to be no consistent way to get the size of a file (in bytes) on multiple platforms. Here is a solution that works in bash on Linux (tested under Debian and Ubuntu) and BSD (tested under OSX):

# Echo's size of a file (first argument). # Tested under Linux (Debian) and BSD (OSX). function filesize() { echo $(stat --format=%s "$1" 2>/dev/null || stat -f '%z' "$1" 2>/dev/null) } # Example usage: echo $(filesize readme.txt)

X forwarding as root

Often is useful to run jconsole on a remote (production) machine. One basically has 2 options to do so. First, you can pierce your firewall and let your application listen to the appropriate JMX and RMI ports. This however always tricky (in particular the RMI). In addition, creating the connection string that jconsole accepts is not nice at all.

The other option, is to do X forwarding. I'll describe here how to do this on MacOS X, with jconsole on any Unix server with, ssh-server, no root password and sudo installed.

1. Start X11 (you'll need to install it from the installation CDs).
2. Start iterm2.
3. Login to the target system with ssh -X remote_user@system
4. Switch to root with sudo -s.
5. Get X authorities with xauth merge ~remote_user/.Xauthority
6. Start jconsole

Making Mac's open/save dialog fast again

Out of nowhere I had to wait 20 to 40 seconds on my year old iMac before I could open or save a file. Some people reported that iDisk could be the problem, but I don't even have a mac-account! However, those reports gave me a hint.

Indeed, a ls /Volumes/ showed this:

MacintoshHD Wuala ._Ipod_van_Corine

There it is! My girlfriend's IPod was not in sight, and I dumped Wuala because it stops working after a hibernate. A simple

sudo rm /Volumes/Wuala sudo rm /Volumes/._Ipod_van_Corine

and all was well again.

Installing Maven under Mac OSX

Update 2011-09-12: Forget everything that's below here. Just install HomeBrew and type brew install maven.

Update 2008-03-28: Instead of following this article, you are probably better of with MacPorts. Thanks for the suggestion Nino!

I did not know it could be this hard to install Maven. I've installed Maven a bunch of times already but never before on a Mac. It took me about 1 hour!

Here is what you need to do:

• Download the apache-maven.tar.gz. If you follow the link on the maven download page both Firefox and Safari will get an html page but save it as a tar file. Look in the downloaded file (search for the string "apache-maven") and extract a real download link. When in doubt run md5 apache-maven-version.tar.gz on the result and compare it to the MD5 that is posted on the download page.
• Extract the tar somewhere. For example with tar xzf apache-maven-version.tar.gz. Here it gives an error (tar: A lone zero block at 3083) but so far it does not seem to affect the result.
• Ignore all the babbling about environment.plist files, and just create a ~/.bash_profile and put something like the following in it:
  export M2_HOME=/Users/erik/apps/apache-maven-2.0.8 export M2=$M2_HOME/bin export JAVA_HOME=/Library/Java/Home/ export PATH=$PATH:$M2

That's it. Good luck!

Multi user mac?

Well who would have thought? I have become a Mac user. After seeing Windows Vista at my moms computer, I decided I had enough of MS. And I love it! No noise, very useful software included, very quick to start and stop, and my girl-friend and I are simply always logged in. Switching takes 2 clicks and 2 seconds. Then an idea struck me. I still have a spare monitor and attaching a second keyboard and mouse is not so hard either: why can we not work simultaneously? Unfortunately this is not supported. But why not? My question of the month: Why is the Mac still a single user system?