BUPSTASH-SERVE(1)

✨ bupstash-serve — the manual page, but make it a group chat 💅

okay so bestie, you know how bupstash is that iconic encrypted backup tool? Well this page is about the lowkey main character of the whole thing: the serve command from the General Commands Manual. It's the one doing all the actual work behind the scenes while the other commands get all the clout. Let's get into it 🫶

---

🌸 SYNOPSIS 🌸

Serve the bupstash protocol over stdin/stdout. That's it, that's the vibe.

bupstash serve [OPTIONS] REPOSITORY

---

💖 DESCRIPTION 💖

bupstash serve serves the bupstash protocol over stdin/stdout, which is a fancy way of saying it lets a client talk to a repository. Like, most bupstash commands operate via an instance of bupstash serve — it's the connector, the social butterfly, the one making introductions between your data and your repo. No cap 💀

Now here's the part where you gotta pay attention, because the serve command has flags that can be set to restrict access permissions. By default, all access is permitted — until the first --allow-* option is provided. So think of it like: everybody's invited to the party until you start handing out guest list rules, and then the rules count. These flags can be enforced through the ssh authorized_keys file, or through mechanisms such as sudo or doas configuration. Lock it down however you like, bestie 🔒

Real talk though: clients with permission to read data may still not be able to decrypt it unless they have the correct client-side decryption key. The permission to read and the ability to understand are two different things, iykyk. It's giving "you can look but you can't touch."

Heads up bestie: many errors are printed out of band via stderr, so alternative transports should consider how to also forward stderr data. Don't let your errors get lost in the void 😭

---

✨ OPTIONS ✨

Every single one, because we don't skip in this house 💅

• --allow-init — Allow the client to initialize new repositories. Fresh repo, who dis? 🌱
• --allow-put — Allow client to put more items into the repository. Shove all your stuff in there, bestie 📦
• --allow-list — Allow client to retrieve metadata and snapshot indexes for search and listing. Like window shopping, but for your backups 👀
• --allow-get — Allow client to retrieve data from the repository, implies --allow-list. Okay so note that this one implies --allow-list — because you can't grab things you can't even see, obviously 🎯
• --allow-remove — Allow client to remove repository items, implies --allow-list. Also implies --allow-list, same logic, stay consistent bestie. Bye-bye data 🗑️
• --allow-gc — Allow client to run the repository garbage collector. Taking out the trash, but make it archival ✨
• --allow-sync — Allow client to sync items into the repository, i.e. be the destination of a repository sync. You're the receiving vibe now 🎀

---

🦋 EXAMPLES 🦋

🌈 Custom ssh flags using BUPSTASH_REPOSITORY_COMMAND

When you wanna be all custom with it:

$ export BUPSTASH_REPOSITORY_COMMAND="ssh -p 2020 $SERVER bupstash serve /data/repository"
$ bupstash list

That's it. Port 2020, your server, your repo. Slay.

🌸 Setup SSH access controls

This is the good one, the whole point, the reason you're here. Let's walk it through step by step:

Create a 'backups' user on your server. Fresh account, fresh energy.

In an your sshd config file in your server add the line — yes, the original says "In an your sshd config file," and honestly? It ate, we're keeping it:

Match User backups
    ForceCommand "/bin/bupstash-put-force-command.sh"

Then create /bin/bupstash-put-force-command.sh on your server:

$ echo 'exec bupstash serve --allow-put /home/backups/bupstash-backups' > bupstash-put-force-command.sh
$ sudo cp bupstash-put-force-command.sh /bin/bupstash-put-force-command.sh
$ sudo chown root:root /bin/bupstash-put-force-command.sh
$ sudo chmod +x /bin/bupstash-put-force-command.sh

Look at those permissions being set. root:root, executable, locked in. We love to see it 👑

Now any client with ssh access to the 'backups' user will only be able to add new backups to one repository. One job, one repo, no extras:

$ export BUPSTASH_REPOSITORY="ssh://backups@$SERVER"
$ bupstash put ./data
d1659c3f56f744c7767fc57da003ee5d
$ bupstash list
server has disabled query and search for this client

See how the put slayed and gave you back that hash d1659c3f56f744c7767fc57da003ee5d, but the list got shut down? That's the --allow-put doing its thing — you can add, you can't peek. Permission check: passed, but only for the one thing 💅

Logging into the server via other means will have full access to the backups repository. So like, ssh in as yourself and the whole thing is yours. Different permissions can be configured using similar concepts alongside different ssh configurations and keys — mix and match, build your own ruleset, be the architect of your own access control 🧚

---

⭐ SEE ALSO ⭐

• bupstash(1)
• bupstash-repository(7)

---

and that's the whole page bestie — the bupstash-serve manual, May 2025 edition, from the General Commands Manual, lovingly restyled for the group chat. go forth and serve your repos responsibly 💜✨