debian-server-tools: an engineer's Bash and Markdown notebook for Debian servers

One operator's knowledge, published and updated daily

The repository states its premise in the first line: you find all of the author's knowledge on GitHub in the form of Bash and PHP scripts and Markdown documents, updated daily as they work. That is an unusual thing for a project to claim, and it explains the shape of the repository. There is no package to install and no service to run. There are directories of scripts, documents that read like internal runbooks, and a collection of one-line answers to the questions that come up when you administer a Debian server. The licence is MIT, the primary language is Shell, and the homepage field points at a curriculum vitae document rather than a product page. The audience is a sysadmin or web developer working on Debian based servers who wants to see how an experienced operator handles a task, with the trade-offs explained rather than a tool wrapped around them.

The directory map is the feature list

The README organises the repository by directory, and the list reads like a job description for running a small hosting operation. There is a Debian setup directory with installation scripts and a script for resizing the root filesystem during boot, a backup directory for archiving, an image directory for image optimisation, an input directory for terminal related tooling, a mail directory for email account management, a monitoring directory for server monitoring, alerting and statistics emails, a MySQL directory for database management, a package directory for Debian packages and general packaging, a security directory for security and SSL certificate tooling, a tools directory for miscellaneous utilities, a virtualization directory for Docker containers, and a webserver directory for building web servers. The top level also carries install, uninstall, update and cron installation scripts, plus a Git pull helper, a document on Bash exit codes, and configuration for a link checker and a linter. It is a working setup rather than a curated library, and the directory names are how you find what you need.

Adding an SSH key for a user without switching to root

One of the more useful snippets is the one that installs a user's own SSH key without a root shell, because the awkward part of that task is that the key has to end up in the target user's home directory with the right ownership. The script runs the mkdir and the editor as that user, then works out the home directory from the account's owner and fixes the ownership afterwards:

u bash -c 'S="${HOME}/.ssh";mkdir --mode 0700 "$S";editor "${S}/authorized_keys"'
U="$(stat -c %U .)";S="$(getent passwd $U|cut -d: -f6)/.ssh";mkdir -m 0700 "$S";editor "${S}/authorized_keys";chown -R $U:$U "$S"

Two details are worth copying. The directory is created with mode 0700 rather than relying on a default umask, and the ownership is set recursively with chown afterwards, because a key file that is group readable is a problem and a key file owned by root inside a user's home directory is a problem too. The companion snippet for the root account is shorter, since it runs in root's own home, and it creates the directory, opens an editor on the authorized_keys file and then lists the fingerprints of the keys it contains so you can confirm which key was added.

Restricting what a key is allowed to do

The repository also documents the authorized_keys parameters, and the example it gives is a restricted entry that is worth reading in full. The restrict option is expanded in a comment as no port forwarding, no agent forwarding, no X11 forwarding, no pty and no user rc, and the key is then bound to a forced command that prints a message telling the user to log in as the debian user rather than root, echoes a newline and sleeps for ten seconds:

# restrict == no-port-forwarding,no-agent-forwarding,no-X11-forwarding,no-pty,no-user-rc
restrict,command="echo 'Please login as the user \"debian\" rather than the user \"root\".';echo;sleep 10" ssh-rsa AAAA...

That combination is a familiar pattern for provider access keys: the key is allowed to authenticate, and nothing else. The forced command runs regardless of what the client asks for, which is why the sleep is there, to keep the session open long enough for the message to be read. The same pattern explains why the earlier snippet advises against logging in as root over SSH at all. The repository also has a one-line recipe for recovering a public key from a private key file, which is the step you need when a client hands you the private key and expects you to derive the public half yourself:

ssh-keygen -y -f ~/.ssh/id_ecdsa

Reading the real SSH configuration from sshd

A recurring theme in these snippets is checking what the server is actually doing rather than what the configuration file appears to say. The host key listing reads the public host key files out of the SSH directory and prints a fingerprint for each one, which is how you confirm which keys a server presents:

ls /etc/ssh/ssh_host_*_key.pub | xargs -n 1 ssh-keygen -l -f

The same idea appears in the section on recording a terminal session, where the script command captures a session with timing information and the scriptreplay command plays it back with a maximum delay, which is a way to hand someone else an exact reproduction of a failure:

script --timing=NAME.time --append NAME.script
scriptreplay --maxdelay 1 NAME.time NAME.script

Cron, timezones and the day to day shell plumbing

The remaining snippets cover the working details of running things on a schedule and moving data around. There is a reference for the crontab format, drawn as a field diagram, and a form showing how to edit the crontab of a named user, since the plain crontab command only edits the current one. Timezone handling gets its own entry, and it is the kind of detail that causes silent failures: the example schedules a job well before its real execution time and uses the at command with a date expression carrying a timezone, so the job fires at the intended local time regardless of the server's own timezone. Script transfer between machines is handled with compression and base64 encoding, and the README points at magic-wormhole as the tool to use for that job, with a pack and an unpack command given as examples. There are also small utilities for moving a git working tree away from its git directory, and for rescanning the SCSI bus so that a newly attached disk appears without a reboot. And there is a note on the two ways to install Debian with UTC as the timezone: choose the expert install.

Standards, checks and the shape of the repository

The README states the conventions the scripts follow, and those conventions are a form of documentation in themselves. Shell scripts are checked with ShellCheck, code styling follows the Git project's own coding guidelines, and Bashisms are avoided with the checkbashisms tool, which exists because a script written for Bash can break when run by the dash shell that Debian uses for the system shell. The repository layout backs that up: an editor configuration, a typos configuration, a YAML lint configuration, a configuration for the link checker, a Travis configuration, and a gitmodules file, which indicates that some pieces are shared with other repositories of the same author rather than duplicated. The release history is almost empty, with a single tag from 2015 carrying the hdd-bench binaries, so the repository is not versioned in the way a released tool would be. The last push was on 2026-10-04, and the repository is not archived, which for a personal notebook is the expected state: it is meant to be read and copied from, not depended upon.

Editorial conclusion

debian-server-tools fits a Debian operator who wants a working example of the way a careful sysadmin does a task, with the caveats written next to the command, and who is prepared to read each script before running it. It does not fit automation that needs a stable interface, since the repository is explicitly updated daily as the author works. Verify first what your distribution ships for the tool each snippet needs, from sshd through psql to the mail tooling, and treat the SSH key installation snippets as templates to adapt rather than commands to paste, because they assume a particular directory layout and a particular superuser account name.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. szepeviktor/debian-server-tools on GitHub