WITHLOCK(1)

📦 version 0.5, in fedora 43, fedora 44

💖 WITHLOCK — locking wrapper script 💖

okay bestie, gather round, because withlock(1) is about to become your new fave little sysadmin sidekick and I am so excited to tell you about her. she's a wrapper script, she's polite, she's tidy, and she will absolutely hold the door so your cron jobs stop piling up on each other like it's a Black Friday sale. 🎀

✨ NAME ✨

withlock — locking wrapper script. that's it, that's the whole vibe. 💅

🦋 SYNOPSIS 🦋

withlock lockfile command [args...]
withlock [-w <seconds>|--wait=seconds] [-q|--quiet] [-v|--verbose]
lockfile command [args...]
withlock [-h|--help]
withlock [--version]

like. look at her. so simple. so clean. iconic. ✨

🌸 DESCRIPTION 🌸

so withlock(1) is a wrapper script whose whole entire job is making sure some program isn't run more than once. she is literally the ideal girlie to stop those periodic jobs spawned by cron(8) from stacking up on top of each other. no more seventeen copies of the same backup script fighting in the group chat. 🙈

the way she does it is so clever: the locks she uses are only valid while the wrapper is running. which means she will never require extra cleanup — not even after a system crash, not even after a reboot. zero crumbs left behind. this is what makes her safe and easy to use, and honestly better than implementing some half-hearted locking situation inside your own scripts. no cap. 💯

and because sometimes you're not in a rush? the script can wait a defined time for a lock to become "free". patient queen. 👑

🔥 SECURITY 🔥

okay this part is important, bestie, listen up. 🚨

lockfiles, generally, MUST NOT be placed in a publicly writable directory. why? because that would open the door to a symlink attack. and for that exact reason, withlock(1) simply disallows lockfiles in such locations. she said no thank you, we're not doing that. periodt. 💀

not me being dramatic about it, it's literally just true. publicly writable dir = no. she won't even let you. 🫶

💅 OPTIONS 💅

  • -v, --verbose — print debug messages to stderr. she'll narrate her whole little journey for you. gossipy in the best way. 👀
  • -q, --quiet — if the lock can't be acquired immediately, silently quit without error. she just. leaves. no drama, no error, no nothing. ghosting, but politely and on purpose. 🧚
  • --version — show the program's version number and exit. her little birth certificate. 🎀
  • -h, --help — show command synopsis and exit. the cheat sheet. 🦋
  • -w seconds, --wait=seconds — wait for a maximum of seconds for the lock to be acquired. she'll hang out by the door for as long as you tell her to, and not one second more. ⏳

⭐ EXAMPLES ⭐

instead of running your command like this:

<command> [<args>...]

you simply use:

withlock <lockfile> <command> [<args>...]

and honestly? that's the whole trick. slay. ✨

cron(8) jobs — especially the long-running ones — are frequently run under withlock(1). here's an example:

-*/10 * * * *   root     withlock LOCK-serverstatus /usr/bin/log_server_status2
43 5,17 * * *   mirror   withlock LOCK-rsync-edu-isos rsync -rlptoH --no-motd rsync.opensuse-education.org::download/ISOs/ /srv/mirrors/opensuse-education/ISOs -hi

see how tidy?? one lockfile, one job, no stacking. she ate and left no crumbs. 🔥

💜 HISTORY 💜

so the tea is: this wrapper got implemented because no comparable solution was found — even after looking around for a long time. and after suffering through problems caused by missing or insufficient locking for years. years, bestie. 😭

the only thing that came close was with-lock-ex.c, a C implementation written by Ian Jackson and placed in the public domain by him. with-lock-ex.c is traditionally available on Debian in a package named chiark-utils-bin. parts of withlock's locking strategy and parts of the usage semantics were inspired by that program. 🫶

this implementation was chosen to be done in Python because it's universally available, easy to adapt, and doesn't require being compiled. no build step, no toolchain, just vibes and a working interpreter. ✨

then — plot twist — somebody pointed out that there's flock(1), a small tool written in C that does the same thing. and yes, the author had apparently managed to completely miss that tool during a decade's worth of Linux hacking (you discover something new every day, don't you?). the functionality is mainly the same indeed. 💀

however, withlock(1) has some advantages:

  • withlock(1) is a little easier and more logical to use than flock(1). the semantics are more suited for sysadmins. 👑
  • withlock(1) always cleans up its lock files. flock(1) always lets them lie around. and honestly? the author admits they like that with withlock(1) you can always tell by the presence of the lock files which jobs are running. little status indicators. we love a visible paper trail. 🎀
  • flock(1) doesn't prevent using unsafe directories. 🚫
  • withlock(1) is easily extensible. 🌱
  • it could be used as a Python module (not implemented so far). 👀
  • flock(1) doesn't exist on Solaris and OSX. 💀

🙈 BUGS 🙈

withlock(1) has been tested on many platforms, including Debian, Ubuntu, openSUSE, CentOS, Fedora, FreeBSD, OSX, and OpenCSW Solaris — and she's been in production use since 2009. 💖

there don't seem to be race conditions (the author tried very hard to break it) — but there are no guarantees. so like, she's tough, she's been through a lot, but don't @ her if the universe decides to be weird. 😭

🌈 AUTHOR 🌈

this program was written by Peter Pöml peter@poeml.de in 2009. a legend, fr fr. 👑

🫶 SEE ALSO 🫶

and that's the whole page, bestie!! 🎀 this was the withlock(1) manual, dated June 2015, and if you made it all the way down here you are officially a certified unix girlie. go lock something. responsibly. mwah. 💖✨🦋🌸💅

📦 where this page comes from