AdminJitsu

nextcube Part 3 - Next Users Guide

Sat, 15 Nov 2025 11:14:32 -0600

Intro

In this third installment we’ll do some more NeXT hacking with our nextcube setup and make it more livable.

In Part 1, we got OpenStep installed and booting cleanly on VirtualBox.
In Part 2, we configured the Unix and network environments, installed development tools, and added some Unix ports.
The complete OVA Appliance build published on Archive.org is available if you want to hop right in.

Telnet Refresher

Before SSH and encryption became standard security practices, Telnet was the default way to access remote systems. It uses plain TCP connections and transmits everything — including usernames and passwords — in plaintext. Despite that (or because of it), it was widely used for administration, file transfers, and troubleshooting and testing network services.

At its simplest, Telnet connects to a host and port number as a generic TCP client:

telnet host-or-ip [port-number]

Examples:

telnet nextcube
telnet nextcube 25
telnet 127.0.0.1 9

Yes, you can telnet into 127.0.0.1 or localhost as well as your own IP. This works because the inetd super-server automatically starts telnetd at boot and binds to all available interfaces. The configuration line that enables it is found in /etc/inetd.conf:

telnet  stream  tcp     nowait  root    /usr/etc/telnetd        telnetd

The actual telnetd binary lives in /usr/etc, and is launched by inetd whenever a connection request comes in on TCP port 23.

Telnet’s simplicity makes it an excellent tool for exploring how old network services work. You can use it to:

Log in to the OpenStep system from another host.
Connect to local ports for debugging or service checks (telnet localhost 80).
Interact with simple text-based protocols such as SMTP (telnet host 25), POP3 (telnet host 110), or even the built-in services like finger, daytime, or echo.

Because Telnet sends everything unencrypted, you can easily visualize what’s happening with a packet capture tool like tshark or Wireshark. A short capture of a login attempt clearly shows the username and password as ASCII text — a powerful reminder of why SSH replaced it.

Details

nextcube, Part 2 – Finishing the OpenStep 4.2 Appliance

Tue, 04 Nov 2025 10:00:00 -0500

Intro

In Part 1, we got OpenStep 4.2 installed, patched, and running cleanly on modern hardware.
In this sequel, we’ll finish the job — replicating the complete OVA Appliance build published on Archive.org. This guide assumes that you are building your own VM and have completed Part1. If you downloaded the OVA Appliance, these steps are already complete.

By the end, you’ll have a full OpenStep workstation: compiler toolchain, X11, shells, text utilities, and even a few Easter eggs.

Let’s Unix!

Developer Tools

We’ll start by installing the Developer Tools.

You can download the iso from here or from archive.org.

Steps

Log in as root after setting a password (see Set Password).
Attach or insert the Developer CD ISO.
Navigate to:
```
/NextCD/Packages/
```
Install the following packages in order:
```
DeveloperTools.pkg
DeveloperLibs.pkg
GNUSource.pkg
ProfileLibs.pkg
DeveloperDoc.pkg
```
When logged in as root you merely double-click on each pkg file to run the installer.

You could also launch the installer from the terminal with /NextAdmin/Installer.app/Installer /DeveloperCDname/NextCD/DevloperTools.pkg
Reboot or log out/in once finished.

Verify Developer Tools Installation

After rebooting or logging back in, confirm the compiler toolchain is working:

# Check that the C compiler (cc) is available and functioning
cc -v

# Expected output (varies slightly by build)
# Reading specs from /lib/i386/specs
# NeXT Software, Inc. version cc-744.13, gcc version 2.7.2.1

perl -v

# Expected output
#
# This is perl, version 5.001
#
#        Unofficial patchlevel 1m.
#
# Copyright 1987-1994, Larry Wall
#
# Perl may be copied only under the terms of either the Artistic License or the
# GNU General Public License, which may be found in the Perl 5.0 source kit.

# Confirm other key tools exist
which cc
which ld
which make
which ar

# Check library and include directories
ls /NextDeveloper/Headers
ls /NextDeveloper/Lib

Details

nextcube, Part 1 - an OpenStep 4.2 VM in 2025

Sun, 02 Nov 2025 10:00:00 -0500

Intro

For a long time I’ve wanted to build a NeXTSTEP virtual machine—but it’s always been a hassle to get it working fully.
Over the years I’ve tried just about everything: QEMU, 86Box, VMware Workstation, Parallels, and multiple versions of VirtualBox. Every attempt ended the same way: partial success, bad drivers and no usable network stack.

Recently I stumbled across some solid public file collections and decided to give it another shot.
This time, after the usual ritual of false starts and head scratching, I eventually managed to assemble a clean, stable VirtualBox 7 for Linux build of OpenStep 4.2 Patch 4.
It runs beautifully on my MacBook Pro running Ubuntu, and honestly—it’s a great little pet VM for any Mac admin or developer who wants to better understand the NeXT Step DNA and foundations present in the modern macOS world.

Background https://en.wikipedia.org/wiki/NeXT

You see, OpenStep is the most recent version of the NeXT operating system. It was a shiny but niche workstation OS that Apple later used as the foundation for Mac OS X, and by extension macOS and iOS. It established a lot of what we still take for granted today: the CMU Mach kernel, the BSD subsystem, the .app bundle format, an object-oriented OS, Display PostScript, the Services menu, the Dock, and familiar utilities like Fonts, TextEdit, and Terminal.

If you know macOS—or the Darwin command-line environment—you’ll feel strangely at home here.

The first web server running on a NeXT Cube.
Coolcaesar, CC BY-SA 3.0 (link), via Wikimedia Commons.

So yes — it’s a time capsule, but also a surprisingly fun little Unix obstacle course. You’ll end up debugging, porting, and re-learning core Unix skills — just without the modern safety nets. Working inside NeXT feels like stepping back into the late-90s: SunOS, Solaris, HP-UX — but cleaner, tighter, and more consistent. And its development environment was nothing short of revolutionary. With Objective-C and Interface Builder, developers could craft powerful, polished apps in record time — long before “rapid application development” became a buzzword.

Getting Started

If you want to skip the setup and get straight to exploring, I’ve published a clean, patched, and fully functional OpenStep 4.2 VirtualBox OVA on Archive.org.

Most images floating around the web have missing patches, broken networking, or minimal configurations.
This one includes everything I wished those did — a stable, period-accurate system ready to explore, customize, and build on.

📦 Download: OpenStep 4.2 VirtualBox OVA (Archive.org)

You can login as either user (me or root) with the password, ‘password’. To change that, see Set password later in the Post-Install steps.

README

I don’t recommend running this on VirtualBox for Windows.

I tested extensively on Windows 10 and 11 with VirtualBox 6.1.32 (the last version with the old NDIS bridge code) and 7.2.4 (the current release as of writing). I even went as far as dedicating a physical Ethernet adapter to VirtualBox, stripped it of every binding except IPv4, and disabled all offload features—no joy. Performance was sluggish, and networking would drop or stall without reason.

On Linux, though, it’s a dream. The VM is fast, stable, and the bridged adapter seems to work well.
I run mine on Ubuntu 22.04 LTS with VirtualBox 7.0.16, and it feels nearly native.

Unfortunately, VirtualBox on Apple Silicon (M1/M2/M3) cannot virtualize x86 or x86-64 guest operating systems — it only supports ARM-based VMs. So while OpenStep runs beautifully on Intel-based Macs with older versions of VirtualBox, it isn’t currently possible to run it on Apple Silicon hardware. Yes that sucks.

NOTE My deprecated Intel Macs are all running Linux. You can check out my article Breathing New Life Into Vintage Macs for the details.

What’s in the OVA appliance

On first boot, you’ll find the following features. The only steps you should have to do is to change the password and review the network settings (/etc/hostconfig and /etc/resolv.conf) for your environment. I built around bridge mode so NAT and Host-Only will be a little different. See Post-Install Steps for more info.

Web browsing in extreme danger mode! Check out theoldnet.com

A particularly nice quality-of-life port is vim

The OVA appliance contains the following goodies:

Developer Tools
OS42MachUserPatch4
Doom, OmniWeb, WordPerfect, Concurrence, Diagram, ParaSheet, WetPaint, numerous small games and apps.
CUBX Windows 5.0 for OpenStep (X11R6 with Xterm and all the usual x11 apps)
fortune mod 9708 with all available fortune dat files and a few custom ones of my own (grumble, deep-thoughts, rules, oblique, rickmorty)
replacement for broken native bsd grep
fileutils and textutils installed to /usr/local/bin
w3c-httpd. latest version of the original web server ready to serve ~/public_html
replacement termcap and sane /etc/termcap to fix display issues
vim 5.3 installed with nice .vimrc that fixes issues and provides a very capable editor
various fixes and polish and about 700mb of free disk space to experiment with
tcsh and bash shells with bash set as shell for root and me users. decent .bashrc and .bash_profile to make it nice to use

All in all I have found it to be a fun, old school Unix sandbox and pet VM.

Building Your Own

If you’d rather build from scratch, I found this to be a clear tutorial that walks through the basic process:

here is the Youtube link

The two big rules are:

Use EIDE/ATAPI for your disks (don’t use SATA or SCSI).
Install Patch 4 immediately after first boot—it adds the modern drivers and fixes (Y2K) that make the system stable.

Choosing the VESA VBE display driver during setup gives you a working color desktop up to 1600 × 1200 and smooth window redraws.

(next section will cover the detailed VirtualBox configuration and installation walkthrough, with screenshots of each key step)

VirtualBox settings

The following settings are proven to work although 16mb for video is unused. I believe the VESA VBE modes max out at 8mb but the VM doesn’t complain if you give it a little extra.

The overview of settings for the nextcube VM

128-256mb RAM, 1 cpu only, PIIX3 chipset, Ps/2 Mouse and I/O APIC.
You should remove the floppy and network from boot order after install to speed up boot.

Make sure to use VBoxVGA and no 3d acceleration. Scaling helps on high res host screens

PIIX3 and Use Host I/O Cache for the hard drive. Keep vdi hdd files to 2gb or less for compatibility.
Do not use ssd

Critical. For Bridged Adapter, make sure to choose PCnet-PCII (Am79C970A) and Promiscuous mode

Finally make sure to disable USB or you will get Virtual Box errors about the mouse on boot.

On Linux

VirtualBox and the Linux KVM modules (kvm and kvm_intel) both require exclusive access to hardware virtualization features (VT-x/AMD-V). When KVM is loaded—often automatically on boot—it takes control of these extensions, which prevents VirtualBox from launching VMs and results in errors like VERR_VMX_IN_VMX_ROOT_MODE. This is especially problematic with older OSes like OpenStep 4.2, which require hardware virtualization in VirtualBox due to the removal of legacy software emulation in recent versions.

To resolve this, unloading KVM modules (modprobe -r kvm_intel kvm) before launching VirtualBox frees up VT-x so the VM can start. You can make this change persistent by blacklisting the modules (via /etc/modprobe.d/blacklist-kvm.conf) or adding kvm.enable_virt_at_load=0 to your kernel command line. The trade-off is that you lose access to KVM-based virtualization (e.g., for QEMU or Android emulators) while VirtualBox has control.

🧩 Install Process

Once your VM is configured, attach the Install floppy and the User CD, then boot the system; follow the on-screen prompts until you’re asked for the driver floppy — insert it when prompted.

When choosing devices for the hard disk and CD-ROM, press 7 twice to reveal additional options.
Select Option 5: EIDE/ATAPI, which is the correct choice for modern emulated hardware.

You want to choose option 5 Primary/Secondary(Dual) EIDE and ATAPI Device Controllers (v4.01)
for both the hard drive and cdrom. It will prompt you twice to do this.

Continue through the installer — there are few non-default choices, and everything is shown clearly in the tutorial video linked above.

After the base install completes and the system reboots, you’ll be prompted once more to insert the driver disk before the GUI portion of setup continues.

From there, NeXTSTEP will copy files to the hard drive — this step takes a while, so be patient.
When it finishes, you’ll be asked to select your keyboard layout and language to complete setup.

I’ve gone through this process many times while preparing this guide — it’s straightforward once you know the key steps.
The video walkthrough covers everything visually, but if you prefer a written version with screenshots, check out the excellent 🔗 Build Your Own NeXT with a Virtual Machine (PDF).

Don't worry, you'll be playing Doom in no time! Still a blast.

Post-Install steps

At this point, you should have a basic install of OpenStep on your virtual hard drive. To finish what I would consider to be required steps for usability, you’ll want to do the following. I would suggest making liberal use of snapshots in VirtualBox as you progress through this process. It’s easy to mess up if you aren’t paying attention.

Install OpenStep Mach Patch 4

The first thing you should do after installation and initial setup is to install OS42MachUserPatch4.pkg.

🔗 DOWNLOAD fsck.technology
📝 RELEASE NOTES OS42Patch4ReleaseNotes.pdf.

Already installed this one. Good!

This patch includes:

Updated kernel and device drivers
Support for VESA VBE video (which allows color and higher resolutions on modern emulators and hardware)
Enhanced EIDE/SATA disk support
Fixes for network and TCP/IP stack issues
Updated system libraries and runtime components
Y2K handling fixes

Set Display Driver (VESA VBE)

After installing OS42MachUserPatch4, you can launch /NextAdmin/Configure.app, navigate to Display and choose the VESA VBE driver. This will allow you to set a variety of higher resolutions up to 1600x1200/32 in color! Definitely do this

Configure.app -> Display -> Vesa VBE driver configured.

Set password for `me` and `root` to enable LoginWindow

OpenStep uses NetInfo to manage user accounts, not the traditional /etc/passwd files found on most Unix systems.
To set passwords safely and ensure LoginWindow works correctly:

Make sure to change password here and not with passwd

Log in as root.
(If the system logs in automatically as me, open a terminal and run su - to switch to root.)
Launch User Manager:
Open /NextAdmin/UserManager.app.
Open the user record:
- From the User menu, choose Open.
- In the dialog, navigate to /users/me.
- To set the root password, open /users/root instead.
Set the password:
- Click in the Password field and enter your new password.
- Choose User → Save from the menu.
- You’ll be prompted to re-enter it for confirmation.
Repeat for both me and root users.

After saving both accounts, reboot or log out — the LoginWindow should now appear at startup.

💡 Tip: Avoid using the passwd command.
It updates /etc/passwd but doesn’t synchronize with NetInfo, which can break authentication.
Always use UserManager.app or the following command instead:
su
niutil -createprop . /users/username passwd "newpassword"

You should now see a login window instead of being logged in automatically as `me`

Configure Networking

You’ll need to edit /etc/hostconfig. Here is the one I use in nextcube, the VirtualBox OVA Appliance.

[ me@nextcube ]:~ $  cat /etc/hostconfig
#
# /etc/hostconfig
#
# This file sets up shell variables used by the various rc scripts to
# configure the host.  Edit this file instead of rc.boot.
#
# Warning:  This is sourced by /bin/sh.  Make sure there are no spaces
#           on either side of the "=".
#
# There are some special keywords used by rc.boot and the programs it
# calls:
#
#       -AUTOMATIC-     Configure automatically
#       -YES-           Turn a feature on
#       -NO-            Leave a feature off or do not configure
#

HOSTNAME=nextcube
INETADDR=192.168.1.50
ROUTER=192.168.1.1
IPNETMASK=255.255.255.0
IPBROADCAST=-AUTOMATIC-
NETMASTER=-YES-
YPDOMAIN=-NO-
TIME=-AUTOMATIC-

You will then need to edit /etc/resolv.conf. Mine looks like this:

OpenStep needs /etc/resolv.conf to resolve domain names to IP addresses. This file tells the system which DNS servers to query and what domain to use for hostname lookups.

Create or edit /etc/resolv.conf as root:

domain darkstar.home
nameserver 192.168.1.1

domain: Your local network domain (often your home network name or LAN domain)
nameserver: The IP address of your DNS server (typically your router/gateway)

You can add multiple nameserver lines if you have backup DNS servers. The system will try them in order if the first one doesn’t respond.

Without this file configured, you won’t be able to browse websites by name in OmniWeb or use any network tools that require DNS—everything would need to be accessed by IP address directly.

Annoying Floppy Issue

Out of the box, due to a quirk of virtualization, you will see a popup every boot like this

Rogue floppy bug

Once I had finished installing floppies I removed the floppy controller from VirtualBox which effectively suppresses the message. It is extremely easy to add it back if you need a floppy by shutting down the VM, adding a Floppy controller and booting again. I recommend this step for quality-of-life.

To remove, go to the VM Settings and under storage highlight the floppy controller and click the little remove icon. Adding it back is easy as well just do it when the VM is powered down

Easy peasy

NetInfo Parent issue

One annoying configuration issue I encountered without clear documentation was with netinfod searching for a parent on boot. As configured during install, netinfod will broadcast for a NetInfo parent regardless of whether NETMASTER=-YES- is set in /etc/hostconfig or not.

This causes long timeouts and requires user intervention to press c to continue booting

The fix is:

Make sure that root (andme) have a password set
Log in as root
Open /NextAdmin/NetinfoManager.app
Navigate to /machines/broadcasthost and double-click on broadcasthost to edit
Highlight the serves property then from the menu select Edit and Delete
Save by selecting Directory from the menu and Save
Reboot and the message should no longer appear.

Upcoming articles to finish building the OVA appliance.

We still need to install the developer tools, get a better shell, get a better editor and replace the broken awk with a gnu version, install fileutils and textutils, vim, X11R6, and build some sensible dotfiles. Stay tuned! Coming shortly.

The appliance includes CUBX Windows, an X11R6 client system with xterm and familiar x11 apps

Links and Stuff

🎥 Video & Download

This was the tutorial I followed that worked the best. Make sure to grab the zip file. Otherwise you can find the install images and patches from the links in the next section.

OpenStep 4.2 VirtualBox Tutorial (YouTube)
Mega.nz download (zip file from the tutorial)
NEXTSTEP & OPENSTEP Install Guide – ShawComputing This is a really clear walkthrough if you’re looking for more.

💾 Archives & File Resources

🔍 Additional Resources

The Old Net
NextComputers.org Forums
Wikipedia - OpenStep
Wikipedia – NeXT
Wikipedia - Serial Experiments Lain connection lots of great references

Conclusion

If you’ve followed along, you now have a complete OpenStep 4.2 environment running on modern hardware—networking, color video, and development tools included. It’s a fully functional UNIX system from another era, and yet, it still integrates cleanly into a modern lab network.

Make sure to check out Part 2 where we’ll complete the build by adding developer tools, a modern shell environment, improved editors, GNU utilities, and X11 - transforming this into a genuinely usable Unix workstation.

I’d love to hear feedback. Email me at feedback@adminjitsu.com

SchemaSpy with LocalDB (SQL Server)

Thu, 02 Oct 2025 00:00:00 +0000

Intro

SchemaSpy is my preferred tool for generating browsable HTML docs and ER diagrams from SQL databases. I’ve already shown how to configure it with SQLite, but SQL Server’s LocalDB edition introduces a completely different set of quirks.

LocalDB is a lightweight SQL Server runtime used by tools like Lansweeper and Visual Studio. Unlike full SQL Server or Express, which run as services and listen on TCP, LocalDB doesn’t accept TCP connections at all. It only exposes a named pipe endpoint, and it only works with Windows integrated authentication (NTLM/SSPI).

That’s why most SchemaSpy guides skip LocalDB entirely — Microsoft’s official JDBC driver expects TCP, and Java has no built-in NTLM support. The workaround is to use the older jTDS driver, which still supports named pipes, plus its companion ntlmauth.dll for NTLM authentication.

After a lot of trial and error, I found a reliable combination: SchemaSpy 6.1.0 + jTDS 1.3.3 + ntlmauth.dll + Graphviz 2.38. It’s fiddly, but once you have the pieces in place, you can generate a complete HTML schema doc site for any LocalDB-backed application.

The Pieces You Need

Component	Why It Matters	Version / Link
SchemaSpy (fat JAR)	The doc/diagram generator	6.1.0 (newer versions break jTDS)
jTDS JDBC Driver	Supports named pipes + NTLM/SSO	1.3.3
Java Runtime	Runs SchemaSpy	Java 8+ (64-bit recommended)
Graphviz	Renders static diagrams	2.38 (stable with SchemaSpy 6.x)
`ntlmauth.dll`	Bridges NTLM/SSPI into Java for SSO	Comes with jTDS zip (x86/x64/ia64)

Heads-up Microsoft’s official JDBC driver cannot connect to LocalDB — it only works over TCP. That’s why jTDS is required.

Suggested Setup (Windows)

Keep everything SchemaSpy needs in one folder so paths are consistent:

C:\bin\SchemaSpy\
  schemaspy-6.1.0.jar     # SchemaSpy itself
  jtds-1.3.3.jar          # JDBC driver
  ntlmauth.dll            # From jTDS zip, for Windows SSO

Install Graphviz to its default location:

C:\Program Files (x86)\Graphviz2.38\

Important About ntlmauth.dll
The jTDS 1.3.3 zip includes three versions:

x86\ntlmauth.dll → use if you run 32-bit Java
x64\ntlmauth.dll → use if you run 64-bit Java (most common today)
ia64\ntlmauth.dll → legacy Itanium, almost never needed

Copy the correct DLL into your C:\bin\SchemaSpy\ folder. When running SchemaSpy, add:

-Djava.library.path="C:\bin\SchemaSpy"

If the bitness doesn’t match, you’ll see UnsatisfiedLinkError or “Login failed” errors.

Step 1: Find the LocalDB Instance Pipe

LocalDB doesn’t have a fixed hostname like localhost,1433. Instead, every time it starts, Windows assigns it a unique named pipe. That pipe is what jTDS connects to.

To check the pipe, open PowerShell or Command Prompt on Windows (on the same machine that’s running LocalDB) and run:

SqlLocalDB start LSInstance
SqlLocalDB info  LSInstance

This will print details about the LocalDB instance, including the Instance pipe name. For example:

np:\\.\pipe\LOCALDB#SH964109\tsql\query

The important part is the instance token (LOCALDB#SH964109). You’ll pass that value into SchemaSpy with:

-instance "LOCALDB#SH964109"

Heads-up: The token changes every time LocalDB restarts. If SchemaSpy suddenly stops connecting, rerun SqlLocalDB info to grab the updated string.

Step 2: Authentication Options

SQL Server supports two authentication modes, but only one works with LocalDB:

Windows Integrated (SSO)
LocalDB uses Windows credentials instead of SQL usernames. The account that runs SchemaSpy must be a Windows user who has been granted access to the database.

By default, this is the same account that installed or created the LocalDB instance (for example, the Windows user who installed Lansweeper). If you run SchemaSpy as a different user — even another local admin — you may get Login failed for user until that account is explicitly added as a login in SQL Server Management Studio.

To make NTLM authentication work in Java, you also need ntlmauth.dll from the jTDS package. Without it, SchemaSpy will fail to authenticate even if the Windows account has access.
SQL Login (username/password)
This works on full SQL Server or Express, where TCP/IP is enabled and you can create dedicated logins. LocalDB does not allow this mode out of the box, so you can’t rely on -u/-p against a stock LocalDB instance.

Step 3: The Working Command

With SchemaSpy, jTDS, and Graphviz in place, you’re ready to run the actual command. This is where everything comes together.

Important SchemaSpy appends \bin\dot to whatever you provide via -gv. Always pass the Graphviz install root folder, not the path to dot.exe.

Option 1: Windows Integrated Authentication (SSO)

This is the normal way to connect to LocalDB. SchemaSpy will log in as the Windows account you’re running under (make sure that account has database access). You also need ntlmauth.dll and -Djava.library.path.

If you’re running from cmd.exe:

java -Djava.library.path="C:\bin\SchemaSpy" -jar "C:\bin\SchemaSpy\schemaspy-6.1.0.jar" ^
  -t mssql-jtds-instance ^
  -dp "C:\bin\SchemaSpy\jtds-1.3.3.jar" ^
  -host . ^
  -instance "LOCALDB#SH964109" ^
  -db lansweeperdb ^
  -s dbo ^
  -sso ^
  -connprops "namedPipe\=true" ^
  -o "C:\bin\SchemaSpy\output" ^
  -gv "C:\Program Files (x86)\Graphviz2.38"

If you’re running from PowerShell:

java -Djava.library.path="C:\bin\SchemaSpy" -jar "C:\bin\SchemaSpy\schemaspy-6.1.0.jar" `
  -t mssql-jtds-instance `
  -dp "C:\bin\SchemaSpy\jtds-1.3.3.jar" `
  -host . `
  -instance "LOCALDB#SH964109" `
  -db lansweeperdb `
  -s dbo `
  -sso `
  -connprops "namedPipe\=true" `
  -o "C:\bin\SchemaSpy\output" `
  -gv "C:\Program Files (x86)\Graphviz2.38"

Heads-up Use ^ in Command Prompt and ` (backtick) in PowerShell. Mixing them up will cause errors like '-t' is not recognized as an internal or external command.

Some applications (like Lansweeper) create a SQL login inside LocalDB (lansweeperuser). If such a login exists, you can use it with -u/-p instead of SSO. The continuation rules are the same as above.

java -jar "C:\bin\SchemaSpy\schemaspy-6.1.0.jar" ^
  -t mssql-jtds-instance ^
  -dp "C:\bin\SchemaSpy\jtds-1.3.3.jar" ^
  -host . ^
  -instance "LOCALDB#SH964109" ^
  -db lansweeperdb ^
  -s dbo ^
  -u lansweeperuser -p "SuperSecret" ^
  -connprops "namedPipe\=true" ^
  -o "C:\bin\SchemaSpy\output" ^
  -gv "C:\Program Files (x86)\Graphviz2.38"

Note If no SQL login exists in your LocalDB instance, this will fail with Login failed for user. In that case, you must use SSO.

Flag Breakdown

-t mssql-jtds-instance → use the jTDS SQL Server driver profile.
-dp → path to the jTDS JAR file.
-host . + -instance "LOCALDB#..." → connect via the LocalDB named pipe.
-db lansweeperdb → database name to document.
-s dbo → schema to include (typically dbo).
-sso → use Windows integrated authentication.
-u/-p → alternative, if a SQL login exists.
-connprops "namedPipe=true" → critical: forces jTDS to use named pipes instead of TCP.
-gv "" → Graphviz install root (SchemaSpy appends \bin\dot).
-o → output directory for the generated site.

What Normal Output Looks Like

SchemaSpy is chatty. A successful run doesn’t just say “Connected” — you’ll see:

ASCII-art SchemaSpy banner and license text.
Warnings about restricted methods (expected with jTDS + modern Java).

A line like:

INFO  - Connected to Microsoft SQL Server - 16.00.xxxx

Long “Gathering schema details…” progress lines with dots.
Occasional warnings about sysproperties (safe to ignore — SQL Server 2016+ removed it).
Graphviz messages about “graph is too large for cairo-renderer” with scaling (also safe).

A final summary like:

Wrote relationship details of 1274 tables/views to directory 'C:\bin\SchemaSpy\output'
View the results by opening C:\bin\SchemaSpy\output\index.html

The key thing to look for is that output files get written and you see a final “View the results…” line. Everything else (warnings, scaling errors, missing comments) is normal noise.

The output directory will contain a full HTML site with:

index.html → overview page
tables/ → per-table pages
columns/ → per-column detail pages
relationships/ → ER diagrams (static images + clickable maps)

Open index.html in your browser to start exploring.

Why This Works

SchemaSpy 6.1.0 preserves working integration with mssql-jtds-instance.
jTDS 1.3.3 supports named pipes and Windows SSO (critical for LocalDB).
-connprops "namedPipe=true" routes through the LocalDB pipe.
Graphviz 2.38 is the last hassle-free version for SchemaSpy 6.x.
ntlmauth.dll provides NTLM/SSPI so SSO works from Java.

Troubleshooting Matrix

Even with the right jars and flags, LocalDB is fiddly. Here’s a quick reference for the most common errors and how to resolve them:

Symptom / Error	Likely Cause	Fix
`Login failed for user` (SSO)	`ntlmauth.dll` missing or wrong bitness	Put `ntlmauth.dll` alongside the JARs; match your Java runtime (x64 vs x86); include `-Djava.library.path="C:\bin\SchemaSpy"`
`The TCP/IP connection to the host…`	Using Microsoft’s JDBC driver, or forgot `namedPipe=true`	Use jTDS 1.3.3; add `-connprops "namedPipe\=true"`
`Cannot open database "" requested by the login`	Wrong DB name or missing permissions	Verify the database name (e.g. `lansweeperdb` for Lansweeper, or your own app’s DB); check that your Windows user or SQL login has access
`No suitable driver`	Driver not found	Ensure `-dp "C:\bin\SchemaSpy\jtds-1.3.3.jar"` is correct
Diagrams not generated	Wrong `-gv` path or Graphviz missing	Point `-gv` to the Graphviz root folder (e.g., `...\Graphviz2.38`), not `dot.exe`; reinstall 2.38 if necessary
Works once, fails after reboot	LocalDB pipe name changed	Re-run `SqlLocalDB info` to get the new pipe, update `-instance "LOCALDB#..."`
`The network path was not found`	Instance not started or pipe unavailable	Run `SqlLocalDB start` ; confirm the pipe string; if using SSO, run SchemaSpy as the same Windows user that owns the DB
Non-ASCII path weirdness	Path quoting/escaping on Windows	Wrap all paths in quotes; avoid special characters in folder names if possible

Links & Stuff

SchemaSpy
📥 SchemaSpy v6.1.0 JAR (GitHub)
SchemaSpy Documentation
jTDS JDBC Driver (1.3.3)
📥 Download jTDS 1.3.3 (SourceForge)
Archived jTDS project site
Graphviz (2.38 for Windows)
📥 Graphviz 2.38 Windows installer (archive)
Graphviz site & docs
SQL Server LocalDB
Microsoft Docs – SQL Server Express LocalDB
SQL Server Management Studio (SSMS)
📥 Download SSMS (Microsoft)
Handy for browsing your LocalDB, verifying database names (e.g. lansweeperdb), and checking which logins exist.

(For long-term use, consider mirroring the required JARs and DLLs internally so your team isn’t chasing archive sites years later.)

Conclusion

LocalDB’s named-pipe-only quirk trips up the usual JDBC approach. The dependable combo is:

SchemaSpy 6.1.0  +  jTDS 1.3.3  +  -connprops "namedPipe=true"  +  Graphviz 2.38

With that in place — and the LocalDB instance pipe refreshed as needed — you’ll get clean, searchable HTML docs and ERDs for any LocalDB-backed app (e.g. Lansweeper, Visual Studio projects).

If you run into an edge case I didn’t cover, send it my way feedback@adminjitsu.com and I’ll expand the troubleshooting matrix.

Tcpdump Survival Guide

Wed, 24 Sep 2025 05:50:39 -0500

Intro

Tcpdump is the Swiss Army knife of packet capture. It’s lean, scriptable, and ships with almost every Unix-like system. That makes it ideal for automation, troubleshooting, or handing to a customer when you need a reproducible capture without walking them through a GUI.

Most people analyze captures in Wireshark, the premiere open-source packet analyzer. But tcpdump is often the better tool for collecting the data in the first place: it can be scripted, shared as a one-liner, and run with minimal instructions. That workflow — capture with tcpdump, analyze with Wireshark — is a staple in real-world troubleshooting.

Packet captures are rarely trivial: they’re big, messy, and not something you want to redo needlessly. The goal is to get it right the first time — a clean, useful trace containing the data you need that you can hand off to Wireshark or another analyst. This survival guide shows the commands you need to do just that.

Tcpdump is the Swiss Army knife of packet capture.
Photo: Ave Maria / Jonas, via Wikimedia Commons, CC BY 2.0

Where to Capture?

Before worrying about command flags, it helps to think about point of view. Packet captures are always relative — what you see depends on where you’re listening from.

If you’re debugging a client/server exchange, you could capture on the client to confirm whether requests are leaving, or on the server to see if they arrive. Sometimes you need both perspectives: one to prove the client sent the packet, the other to prove the server received (or didn’t).

The network itself matters too. On a flat LAN or broadcast domain, a capture may show you traffic between many hosts. But on a switched or routed network, you’ll only see packets destined to or from the machine you’re capturing on. That’s why capturing on the endpoint itself is often the simplest, most reliable approach.

For complex problems, it’s common to gather multiple captures — one at the client, one at the server, maybe another at a key router or firewall. When you line them up by timestamp, you can follow the packet’s journey across the path and pinpoint where things break down.

Capturing With Purpose

Before you even start tcpdump, think about the flow: set up the capture, reproduce the issue, then stop and analyze. The most useful captures are the ones where you already know what you were testing and when.

When possible, note the time that certain events happen (“clicked Connect at 14:03:12”, “login failed around 14:05”). Even better, jot down exactly what you did while the capture was running. Those notes become anchors when you later scroll through packets in Wireshark.

It’s tempting to just run tcpdump for hours and fish around afterwards, but that usually leaves you with a mountain of noise. A focused capture is faster to analyze and less likely to miss the moment you care about. Sometimes you know the exact traffic you want (say, HTTPS to a specific host). Other times you don’t — and that’s fine. Even then, try to reproduce the problem cleanly and capture just long enough to get the exchange you’re after.

The key idea: minimum noise, maximum relevance. The cleaner your capture, the easier your analysis.

Gathering a Solid Capture

Now that you’ve thought about where to capture and how to focus your test, the next step is setting up tcpdump to record everything you need without losing detail. The essentials boil down to three things: interface, scope, and output. We’ll get deeper into interface choices in the next section — for now, let’s focus on how to record a solid trace.

Save to a File

For later analysis in Wireshark or another tool, always write to a .pcap:

sudo tcpdump -i eth0 -s 0 -w capture.pcap

-s 0 → capture the entire packet, not just the default snap length.
-w → write raw packets to a file (not human-readable).
Use Ctrl+C to stop when you’ve got enough.

Quick Checks

Sometimes you only need a small slice:

sudo tcpdump -i eth0 -s 0 -c 500 -w sample.pcap

-c stops after N packets.
Great for reproducible test runs.

Reading It Back

To verify or skim without Wireshark:

tcpdump -r capture.pcap

Pro Tips

Always run with sudo (or root).
Watch disk space — captures grow quickly.
Sync system clocks if possible (NTP helps line up multi-host captures).
Time matters: make sure your system clock is accurate for useful logs.

Now that you know the essential flags for capturing, you need to point tcpdump at the right place to listen. Modern systems have multiple network interfaces, and choosing the wrong one means capturing nothing useful.

Choosing the Right Interface

Once you know where you want to capture, the next step is picking the right network interface. Modern systems almost always have more than one: a wired port, one or more wireless adapters, VPN tunnels, virtual interfaces created by containers, or diagnostic interfaces used for special cases like mobile devices. Tcpdump needs to know exactly which one to listen on.

List available interfaces with:

tcpdump -D

You’ll see numbered entries such as:

Linux: eth0, ens33, wlan0, lo (loopback), docker0, tun0 (VPN), vethXYZ (containers)
macOS: en0 (Ethernet or Wi-Fi), en1, lo0 (loopback), utunX (VPN), bridge0, rvi0 (iOS Remote Virtual Interface)
Windows (via WSL or WinDump): Ethernet, Wi-Fi, Local Area Connection, plus GUID-style names for virtual adapters

Which Ones Matter?

Ethernet / Wi-Fi (eth0, ens33, en0, wlan0) → Most common capture points for client or server traffic.
Loopback (lo, lo0) → Useful if you’re testing services that talk to themselves on localhost.
VPN (tun0, utunX) → Captures encrypted tunnel traffic; sometimes useful for debugging, but you won’t see the inner payloads unless you capture on the endpoint before encryption.
Docker / Container Bridges (docker0, vethXYZ, cniXYZ) → Capture container-to-container traffic. Handy in Kubernetes/Docker debugging.
Mobile Debugging (rvi0 for iOS, any for Android) → Special cases we’ll cover in detail below.
Others (bridges, virtual adapters, hypervisor links) → Usually less relevant unless you’re debugging virtualization or complex network topologies.

The key point: capture on the interface where the traffic of interest actually flows. Choose wrong, and you’ll end up with an empty file or irrelevant chatter.

Capturing Mobile Traffic

One of tcpdump’s neat tricks is that you can capture traffic from mobile devices without exotic hardware taps. Both iOS and Android expose interfaces that tcpdump can hook into from your computer. In both cases you’ll need the device plugged in with a USB cable.

iOS (macOS host required)

On macOS, Apple provides a Remote Virtual Interface (RVI) that exposes iPhone or iPad network traffic over USB. The device must be unlocked and you’ll need to tap Trust this computer the first time you connect. Once enabled, the phone appears as a virtual interface (rvi0) that you can capture from with tcpdump.

The only catch: you need the device’s UDID (Unique Device Identifier). You can get it a few ways:

System Profiler (built-in):
Plug in your device, then run:
```
system_profiler SPUSBDataType | grep -w "Serial Number"
```
This prints the serial numbers of connected USB devices. For iPhones and iPads, that string is the UDID.
libimobiledevice (third-party tools):
If you have libimobiledevice installed, you can run:
```
idevice_id -l
```
which lists all connected iOS devices by UDID.

Pro-Tip If you’re handing instructions to someone else, you can make it a one-liner:

rvictl -s $(system_profiler SPUSBDataType | awk '/Serial Number/{print $3; exit}')

That command automatically grabs the first iOS device’s UDID and passes it to rvictl.

Once the RVI is active, check with:

rvictl -l

When finished, tear it down with:

rvictl -x

At that point, rvi0 behaves like any other interface. You can capture traffic from it just like you would on Ethernet or Wi-Fi:

sudo tcpdump -i rvi0 -s 0 -w iphone.pcap

This gives you a complete packet trace of the phone’s traffic — Wi-Fi, cellular, or both — without needing a special router or access point. It’s one of the most useful tricks for debugging mobile apps in the field.

Android (USB required)

Android doesn’t expose an RVI, but you can capture traffic via the Android Debug Bridge (adb). Your phone must be plugged in over USB with USB debugging enabled. On many devices this works out of the box, but some builds require a tcpdump binary installed on the phone and root privileges to run it.

macOS:
```
brew install android-platform-tools
```
Debian/Ubuntu:
```
sudo apt install android-tools-adb
```
Fedora:
```
sudo dnf install android-tools
```
Windows:
Download Android Platform Tools from Google.

With adb installed and your phone connected by USB (with USB debugging enabled), verify the device is detected:

adb devices

You may need to accept a prompt on the phone.

From there, you have two approaches:

Capture directly on the device:
```
adb shell tcpdump -i any -s 0 -w /sdcard/capture.pcap
adb pull /sdcard/capture.pcap
```
This writes a .pcap file to the device and then pulls it back to your computer.
Stream packets live to your desktop:
```
adb exec-out tcpdump -i any -s 0 -w - > android.pcap
```
This writes the capture directly to your computer, which is often simpler for real-time analysis in Wireshark.

Whichever method you use, the result is the same: a .pcap file containing app traffic over Wi-Fi and cellular, ready to open in Wireshark.

Filtering for Relevance

Captures get big quickly. A focused filter saves disk space, cuts noise, and makes analysis much easier. Tcpdump uses the Berkeley Packet Filter (BPF) syntax, which is simple once you know a few basics.

In practice, you’ll usually want to capture full packets and write them to a file for later analysis in Wireshark. For example:

sudo tcpdump -i eth0 -s 0 -w capture.pcap 'tcp port 443 and host example.com'

-s 0 → capture the entire packet
-w capture.pcap → write to a file instead of printing to the screen
Filter expression in quotes → what traffic to capture

For the examples below, we’ll omit the -s 0 -w ... parts to keep things short, but remember to include them when you’re running a real capture.

Common Filters

# Host-based
tcpdump host 192.168.1.50
tcpdump src host 10.0.0.5
tcpdump dst host example.com

# Port-based
tcpdump port 80
tcpdump tcp port 443

# Protocol
tcpdump icmp
tcpdump arp
tcpdump udp

Practical Filtering Recipes

# DNS traffic only
tcpdump -i eth0 port 53

# HTTP traffic to a specific host
tcpdump -i eth0 tcp port 80 and host example.com

# HTTPS traffic to a specific host
tcpdump -i eth0 tcp port 443 and host 203.0.113.42

# All web traffic (HTTP + HTTPS) from one client
tcpdump -i eth0 host 192.168.1.25 and \( port 80 or port 443 \)

# Capture traffic in a subnet
tcpdump net 192.168.1.0/24

# Capture all but one noisy host
tcpdump not host 192.168.1.10

# SSH traffic to or from a specific server
tcpdump tcp port 22 and host bastion.example.com

# ICMP (pings) except from a certain host
tcpdump icmp and not src host 10.0.0.5

# Multiple conditions: HTTPS to a subnet, but ignore one host
tcpdump tcp port 443 and net 10.0.0.0/24 and not host 10.0.0.50

Tips

Use parentheses () when combining multiple expressions (escape them in shells with $ $).
Add -n to prevent tcpdump from resolving hostnames (faster, less noise).
Increase detail with -v, -vv, or -vvv when reviewing packets live.
Filters in tcpdump (BPF) are not the same as Wireshark display filters — capture filters decide what packets are saved, while display filters decide what you see later.

Links & Stuff

Essential Documentation:

Further Reading:

Tcpdump Zine by Julia Evans — a fun, visual guide that complements this article.
Packet Life Cheat Sheets — quick reference sheets for tcpdump, Wireshark, and more.

Conclusion

Tcpdump isn’t flashy, but it’s indispensable. With just a few commands you can capture clean, useful packet traces that save hours of guesswork. Think about where to capture, plan your test, write to a file, and use filters to cut noise. Do it right once, and you won’t have to ask your customer to redo it.

This guide covered the essentials — enough to get you started, hand off captures, and debug issues with confidence. In a follow-up, we’ll dive into analysis and advanced tricks: tshark, Wireshark filtering, ring buffer captures, and boot-time monitoring.

As always, if you found this post useful or if you have questions, I’d love to hear from you: feedback@adminjitsu.com

Happy packet hunting ✨

Unix Users Handbook

Sun, 21 Sep 2025 14:12:00 -0500

Intro

Unix isn’t a lonely single-player game.

Even when adventuring on your personal laptop, you’re never alone. A whole party of user accounts travels with you: root with absolute power, daemon running background jobs, nobody handling scraps, and dozens of service identities (mysql, www-data, postfix). They own files, run processes, and enforce boundaries between users.

That’s the point: Unix was built for multiuser life. In the 1970s, a single minicomputer would act as a hub for dozens of dumb terminals — green-screen VT100s, Teletypes, or glass TTYs — all wired in over RS-232 serial lines. Later, SLIP and PPP links carried those sessions across early networks. Everyone logged in concurrently, sharing the same CPU, disks, and memory. To survive in that environment, the OS enforced strict user separation: each login session mapped to a unique UID, file ownership was enforced at the kernel level, and processes were isolated by identity.

That DNA remains at the heart of Unix. Even today, the cast of characters — root, daemon, nobody, end-user accounts, and service identities — exists to enforce least privilege and prevent one misbehaving process from trampling another.

This guide explains:

History and concepts of Unix users
Where identities live (/etc/passwd, /etc/shadow, /etc/group, /etc/sudoers)
A cross-platform, task-based cheatsheet covering everything from inspecting to creating, modifying, and deleting users, plus group management and sudo.
Historical tidbits, gotchas, and modern tricks
All the pertinent documentation and links

NOTE By the end you’ll have your own player’s screen — every user-related command condensed into one place and neatly organized by task.

So, What is a User?

In Unix, a “user” isn’t a human being — it’s an identity (a user principal) that the kernel uses to decide what’s allowed. Every process runs as someone, every file is owned by someone, and the system enforces permissions based on those identities.

At the machine level, a user boils down to three things:

UID (User ID): a unique integer (UID). This is what the kernel actually checks. UID 0 is hard-coded as root, the all-powerful superuser.
GID (Group ID): groups are collections of users, identified by their own numeric IDs (GID). Group permissions are checked alongside individual user permissions.
Username: a human-friendly alias for a UID. When you type alice at a login prompt, the system maps that to UID 1000 (or whatever number was assigned).

The kernel never cares about names — only numbers. When you run ls -l, it looks up UIDs and GIDs in /etc/passwd and /etc/group just to display friendlier, human-readable names.

NOTE If you delete a user but keep their files, ownership doesn’t vanish. The UID stays behind, and you’ll see files owned by 1001 or 2000, etc. That’s the ghost of a user: the identity is gone, but the number persists in the filesystem.

This split between human-friendly names and machine-level numbers is deliberate. It means accounts can be automated, identities can be isolated, and multiuser systems don’t collapse into chaos.

History & Tidbits

Unix grew up in a world where multiuser wasn’t optional — it was the baseline.

1970s multiuser terminals: A single PDP-11 or VAX might have dozens of dumb terminals (Teletypes, VT100s, Wyse displays) connected over serial lines. Each terminal was just a keyboard and screen; all the real computing happened on the host. Later, SLIP and PPP carried terminal sessions over early TCP/IP links, making multiuser logins possible from remote sites.
Strict separation of users: Because many people were logged in simultaneously, the kernel had to enforce sharp boundaries. Each session mapped to a unique UID; processes couldn’t touch each other’s files; and permissions were checked on every system call.
UID 0: Always root. The kernel literally has “if (uid == 0)” checks hard-coded in privileged operations. This convention has survived intact for 50+ years.
System accounts: Services needed their own identities to run safely. Instead of everything being root, daemons like mail, www-data, and mysql got UIDs of their own. That way, a web server compromise didn’t instantly mean total system takeover.
Different OS ranges:
- Linux: human users typically start at UID 1000 today (but 500 on older RHEL/CentOS). Below that are system accounts.
- macOS: human users start at 501; everything below is reserved. Apple prefixes many system accounts with underscores (_spotlight, _windowserver).
- BSD: similar to Linux, but ranges vary; users should start at UID 1001; service accounts and reserved IDs are well documented in the BSD handbooks.
“Nobody” user: UID 65534 (or sometimes -2) is a special identity with the least privilege possible. It exists to run processes with almost no rights at all.

The takeaway: Unix users are a product of real hardware and real constraints — not just an abstract security idea. The multiuser DNA of the 1970s still shapes how your laptop and servers work today.

The User Database

So where do these identities actually live? In classic Unix, they’re just flat text files:

/etc/passwd — the account roster. Username, UID, GID, home directory, shell, and a password placeholder. World-readable.
/etc/shadow — password hashes and aging rules. Only root can read it. If this file leaks, the system is blown.
/etc/group — group definitions and memberships. Controls shared access.
/etc/sudoers — the privilege ledger. Defines who can become root (and how).

On modern enterprise systems, these files often act as a front-end to NSS (Name Service Switch), which may pull identities from LDAP, NIS, Kerberos, or Active Directory. That’s why tools like getent are preferred over cat /etc/passwd — they return the whole picture, not just the local slice.

Think of these files as the bones of identity. The commands you run — passwd, useradd, dscl, visudo — are the muscles that safely move those bones around.

And above it all sits the kernel, acting as the nervous system.
It doesn’t care whether an identity came from a flat file or a directory
service; all it sees are UIDs and GIDs. That abstraction is the secret
that lets Unix scale from a single laptop to a campus full of machines
while keeping the rules of identity consistent.

Permissions & Ownership Recap

Users only matter because the kernel enforces who owns what and who can do what. That enforcement happens at two levels: files and processes.

File Permissions

Every file has two owners:

a user owner (UID)
a group owner (GID)

And three sets of permissions: user (u), group (g), and other (o).

Example:

-rwxr-sr-- 1 alice devs 532 Sep 21 13:01 script.sh

Breakdown:

- → type of file. (- = regular file, d = directory, l = symlink, c/b = device, s = socket, p = named pipe)
rwx → permissions for the user/owner (alice): read, write, execute.
r-s → permissions for the group (devs): read + execute, plus s meaning setgid is set.
r-- → permissions for others: read only.
1 → hard link count. Directories show how many subdirs + self + parent.
alice → the owner (mapped from UID).
devs → the group (mapped from GID).
532 → file size in bytes.
Sep 21 13:01 → last modification time.
script.sh → filename.

Other permission bits:

setuid (s on user perms): program runs with file owner’s UID. Example: /usr/bin/passwd runs as root.
setgid (s on group perms): files created in this directory inherit the group; executables run with group’s GID.
sticky bit (t on others perms): on directories, only file owners can delete their files. /tmp uses this.

💡 Gotcha: Permissions are checked on every system call (open(), execve(), etc). There’s no “once at login” caching — enforcement is continuous.

Process Ownership

Every process runs as a user and carries both a real UID (who started it) and an effective UID (who it’s acting as).

ps -u alice
UID   PID  CMD
1000  2345 bash
1000  2371 vim
0     2402 sudo
0     2403 systemctl

Here:

Alice owns her bash and vim processes.
When she runs sudo systemctl, the new process has UID 0 (root).

Key fields:

Real UID/GID → the account that launched the process.
Effective UID/GID → what the kernel uses for permission checks. (Setuid/setgid binaries modify this.)
Saved UID → allows a process to drop and later regain privileges (common in daemons).

💡 Example: Apache (httpd) starts as root to bind to port 80, then immediately drops privileges to www-data. If the web server is compromised, the attacker only gains www-data rights, not root.

Why It Matters

Every file belongs to someone. Delete the account, and the UID lingers.
Every process runs as someone. If that process is compromised, its UID defines the blast radius.
Least privilege works only if users and groups are defined properly. Services should almost never run as root.

This is the backbone of Unix security. Once you grasp how file permissions and process ownership interact, the user management commands in the cheatsheet make sense: you’re really just moving numbers and labels around to control who owns what and who can act as whom.

Let's roll up some users!

Cheatsheet

Task-based, cross-platform, and complete. Each section expands with commands from basic to advanced.

Inspect Users & Groups

Check who you are, who exists on the system, and what groups users belong to.

Details

Git Customization

Thu, 18 Sep 2025 00:03:52 -0500

Intro

“A rolling stone gathers momentum.” – anonymous fortune

Git is one of those tools that grows with you. At first, you’re just trying to commit without breaking things, then one day you realize Git has a whole personality you can tweak—aliases, safer defaults, and even custom color schemes.

This guide is the companion piece to my earlier post Git-Fu. That one focused on daily commands and workflows. This one goes under the hood: git config, what lives in the config files, and how you can bend Git to your will.

How `git config` Works

Git’s configuration is layered into three scopes:

System: applies to all users
- Linux/Mac: /etc/gitconfig
- Windows: C:\Program Files\Git\etc\gitconfig
Global: applies to you
- Primary: ~/.gitconfig
- Alternative: ~/.config/git/config (XDG standard)
Local: applies to a single repo (.git/config)

Git reads these in order, with more specific scopes overriding broader ones. So a local setting beats a global one, which beats a system one.

The safe way to set values is with the git config command, which writes to the correct file for you. For example:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Use --system, --global, or --local to control the scope. Handy flags include --get, --unset, and --list.

See everything Git knows about you right now with:

git config --list --show-origin

Where `git config` Lives (Persistence, Saving & Resetting)

When you run git config, you’re not changing runtime state — you’re editing a config file. That’s why these tweaks persist across reboots and repos.

Saving Your Config

Back up everything:

git config --global --list > my-gitconfig.txt

Or just a subset:

git config --global --get-regexp '^alias\.' > my-aliases.txt

Restoring a Config

Reapply from a dump:

while read key value; do
  git config --global "$key" "$value"
done < my-gitconfig.txt

Or just copy ~/.gitconfig between machines.

Resetting to Defaults

Remove a section:

git config --global --remove-section alias

Unset a single key:

git config --global --unset core.editor

Full reset:

mv ~/.gitconfig{,.bak}   # quick backup

# or, if you’re feeling reckless
rm ~/.gitconfig

⚠️ Nukes everything—identity, aliases, colors, etc.
Use the mv method unless you’re 100% sure. Back up first!

Takeaways

git config is persistent because it writes to config files.
You can save and restore with simple dump/reapply steps.
Resetting can be surgical (--unset) or nuclear (rm ~/.gitconfig).

Knowing this up front makes the cheatsheet more useful, because you’ll understand where the settings live and how to move them around.

Ninjas make every post better!

Cheatsheet: Useful Git Config Commands

The examples below use git config commands, but you can also open your config file directly with:

git config --edit

Quick Start: 5 Safe Defaults

If you only set a handful of Git configs, make it these. They improve safety, keep repos tidy, and save you headaches later:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

git config --global init.defaultBranch main   # new repos start on 'main'
git config --global push.default simple       # safer pushes
git config --global fetch.prune true          # auto-clean dead branches

That’s it—your identity + three defaults. You can stop here and still have a nicer Git.
When you’re ready, scroll down for more customization (aliases, pretty logs, colors, etc.).

Identity

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Usability Defaults

git config --global init.defaultBranch main   # new repos start with 'main'
git config --global push.default simple       # safer pushes
git config --global fetch.prune true          # auto-clean old branches
git config --global pull.rebase false         # or true if you’re a rebasing fan

Editor

git config --global core.editor "nano"  # or vim, code --wait, etc.
git config --global diff.tool vimdiff     # or your preferred diff tool
git config --global merge.tool vimdiff    # or your preferred merge tool

Pretty Logs

git config --global format.pretty oneline
git config --global log.abbrevCommit true
git config --global log.date relative

Safer Merges

git config --global merge.ff only
git config --global diff.mnemonicprefix true
git config --global rerere.enabled true  # reuse recorded resolutions

Aliases (muscle memory FTW)

Aliases let you shorten Git commands into quick shorthands. For example:

git config --global alias.st status

Now instead of typing git status, you can just type:

git st

That’s all aliases do—they don’t add new features, but they save keystrokes and speed up common commands. Aliases can point to any Git verb, including ones with arguments. For example:

git config --global alias.lg "log --oneline --decorate --graph --all"
git lg   # expands to 'git log --oneline --decorate --graph --all'

And here’s the cool part: if your alias starts with !, Git treats it as a raw shell command instead of a Git subcommand. That means you can make Git run non-Git commands—or Git commands wrapped in shell logic:

git config --global alias.today '!date'
git today   # runs your system 'date' command

git config --global alias.root '!git rev-parse --show-toplevel'
git root    # prints the repo’s root directory

Note:
Aliases that start with ! run exactly as written in your shell. They don’t take extra arguments the way normal Git commands do—git root sub/dir won’t work. For more flexibility, write a shell script and call it from your alias.

Here are some popular everyday aliases you can copy straight in:

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm 'commit -m'
git config --global alias.lg "log --oneline --decorate --graph --all"

🎨 How Git Colors Work

Git doesn’t store colors itself—it just spits out ANSI escape codes. Your terminal decides what “yellow” or “cyan” actually looks like. That’s why the default yellow sometimes looks like Dijon mustard depending on your theme.

Git supports three kinds of values:

Named ANSI colors: red, green, blue, cyan, yellow, magenta, white, black
Attributes: bold, ul (underline), reverse, blink
Hex RGB (#rrggbb) since Git 2.16 — the most reliable way to get exact shades across terminals

Quick Test

If you just want to see Git output in color, enable it globally:

git config --global color.ui always

Now run git status or git diff — you’ll get Git’s built-in red/green/yellow scheme.

# Test your new colors
git status
git log --oneline --decorate -10
git diff HEAD~1 HEAD
git branch -a
git grep "function" # (if you have any code files)

Sample Theme: “Cool Dark”

Here’s a complete theme you can paste in to try out. It uses golden yellow, light cyan/blue, mint green, and bright grey accents chosen for a black terminal background.

Paste the whole block into your terminal (or save as a script). VS Code’s inline color picker (which appears when you hover over hex colors like #ffd75f) makes customizing these colors especially easy.

git config --global color.ui always

# ── Branches ──
# Affects 'git branch' output and branch decorations in 'git log'
git config --global color.branch.current "#ffd75f"   # golden yellow (current branch)
git config --global color.branch.local   "#5fd7ff"   # light cyan (local branches)
git config --global color.branch.remote  "#87afff"   # soft sky blue (remotes)

# ── Diffs ──
# Affects 'git diff' output
git config --global color.diff.meta       "#ffd75f"  # metadata (index info, etc.)
git config --global color.diff.frag       "#5fd7ff"  # hunk headers
git config --global color.diff.old        "#ff5f5f"  # red for removed lines
git config --global color.diff.new        "#87ffaf"  # mint green for added lines
git config --global color.diff.whitespace "#ff5f87"  # pink highlight for whitespace errors
git config --global color.diff.commit     "#5fd7ff"  # commit hashes in 'git log --oneline' (older Git)

# ── Status ──
# Affects 'git status' output
git config --global color.status.added     "#87ffaf" # mint green (staged new files)
git config --global color.status.changed   "#ffd75f" # yellow (modified files)
git config --global color.status.untracked "#5fd7ff" # cyan (new untracked files)
git config --global color.status.branch    "#bcbcbc" # grey (branch info line)

# ── Grep ──
# Affects 'git grep' output
git config --global color.grep.match      "#ffd75f"  # yellow (matches)
git config --global color.grep.filename   "#5fd7ff"  # cyan (filenames)
git config --global color.grep.linenumber "#bcbcbc"  # grey (line numbers)

# ── Log / Decorations ──
# Affects 'git log --decorate' output
git config --global color.decorate.head         "#87ffaf" # mint green (HEAD)
git config --global color.decorate.branch       "#5fd7ff" # cyan (local branches)
git config --global color.decorate.remoteBranch "#ffd75f" # yellow (remote branches)
git config --global color.decorate.tag          "#ff5f87" # pink (tags)

# ── Interactive ──
# Affects interactive commands (git rebase -i, git add -p)
git config --global color.interactive.prompt "#ffd75f" # yellow (prompts)
git config --global color.interactive.header "#87afff" # blue (section headers)
git config --global color.interactive.help   "#bcbcbc" # grey (help text)
git config --global color.interactive.error  "#ff5f5f" # red (errors)

# ── Pager highlight ──
# Affects search matches inside 'less'
git config --global color.pager.highlight "#87afff"   # soft blue

Details

Git-Fu

Mon, 15 Sep 2025 04:09:11 -0500

Intro

Git is one of those tools that sits quietly at the center of nearly everything we build — from solo side projects to giant open-source collaborations. It keeps track of changes, lets us experiment without fear, and makes it possible to sync work across machines and teams. Without it, keeping track of changes in complex projects would be chaos.

But Git can sometimes feel cryptic with numerous commands, strange terminology, and the occasional “oh no, what did I just do?” moment. The truth is, you don’t need to know every dark corner of Git to use it well. With a few key concepts, a solid cheatsheet, and some helper scripts, Git becomes a trusted and powerful tool.

In this guide I’ll share:

A conceptual crash course to demystify Git
A task-based cheatsheet with collapsible sections for quick reference
My gcheck function — a Bash helper that gives a friendly status report on any repo
Handy aliases I rely on daily
Links and resources for when you want to go deeper

What is Git?

At its heart, Git is a time machine for text files.
It lets you move backward and forward through the history of a project, explore alternate timelines, and share those timelines with others.

Commits are snapshots.
Each commit is like a photograph of your project at a moment in time.
It doesn’t just save what changed, but how the whole directory looked — so you can always step back to that state.
Specifically, Git stores full snapshots (not just diffs) and shows diffs only when you compare snapshots.
Branches are pointers.
A branch isn’t a copy of your work — it’s just a movable label pointing to a commit.
This makes branching lightweight and cheap, so you can spin off experiments freely without bloating your repo.
The HEAD is a pointer too—it tells Git where you’re currently standing. Switching branches just moves HEAD—your current position—to a different branch reference.
Merging is weaving timelines.
When two branches diverge, merging pulls their histories together into a single story.
Sometimes this is automatic; other times you have to resolve conflicts where the timelines disagree.
Sometimes Git can simply fast-forward a branch if there’s no divergence—no new merge commit needed.
Rebasing is replaying commits.
Instead of weaving two histories together, rebasing lifts your commits and replays them onto a different base.
The result is a cleaner-looking history — like rewriting your diary so events flow in a straight line.
Remotes are copies of the archive.
A remote (like GitHub, GitLab, or Gitea) is just another place your repo lives.
You can fetch from it, push to it, or clone it elsewhere. Remotes make collaboration and backup possible.

Together, these metaphors paint Git not as a mess of arcane commands, but as a system for time travel, parallel universes, and shared archives.

Think of it as a directed graph of changes where you always have a way back to safety

Key Concepts

Mastering Git just takes time and practice

Now that we’ve framed Git in simple metaphors, here’s the more technical version — the details behind the magic.

Repos: local vs remote
A local repo is your working copy with a .git/ folder inside it.
A remote is just another full copy of the repo, usually hosted on a server (GitHub, GitLab, Gitea).
By default, the first remote is called origin. You can rename it, or add others (upstream, backup, etc).
Staging area
Also called the index. This is where you prepare changes before committing. Think of it as a shopping cart or draft tray: you can stage some edits, leave others unstaged, and commit only what you want.
Commits
Immutable snapshots with parent pointers. Each has a SHA-1 ID (SHA-256 is becoming standard), author info, and message. Together they form a graph (specifically a 🔗directed acyclic graph or DAG ) of your project history.
Branches
Lightweight movable labels pointing at commits. Switching branches just moves the HEAD pointer to a different branch reference.
Rebase vs Merge
- Merge combines two histories into one, preserving all bumps.
- Rebase rewrites your commits so they look like they happened on top of another branch, creating a cleaner line of history.
Upstream/Tracking branches
When a local branch “tracks” a remote one, Git knows where to pull and push by default.

The Local Git Repo

When you git init in a folder, Git creates a hidden directory called .git/.
That directory is the repository — everything else is just your working files.

This is what makes Git powerful and portable: if you copy a project folder with its .git/ intact, you’ve copied the entire history, branches, tags, and settings. You don’t need a server, a database, or any special tooling.

Anatomy of `.git/` (simplified)

└─$ tree -L 1 .git/
.git/
├── COMMIT_EDITMSG
├── FETCH_HEAD
├── HEAD
├── ORIG_HEAD
├── branches
├── config
├── description
├── hooks
├── index
├── info
├── logs
├── objects
├── packed-refs
└── refs

HEAD → a text file that tells Git which branch you’re currently on.
config → local repo configuration (remotes, branch tracking, custom settings).
objects/ → the actual data store. Commits, trees, and blobs (file contents) live here, addressed by their SHA-1 hash.
refs/ → pointers to commits: branches, tags, remotes.
logs/ → the reflog, Git’s “black box recorder” of branch movements.
index → the staging area, stored as a binary file.
hooks/ → scripts you can run automatically on events (commits, pushes, merges).

Most of the time you never touch these directly, but it’s useful to know they exist.
Git isn’t a black box — it’s just a folder full of plain-text files and hashed objects. (Peek at COMMIT_EDITMSG if you ever want to see the last commit message you wrote.)

Why it matters

Portability → copy the folder to a USB stick, another machine, or zip it up, and you’ve moved the repo with its entire history.
Independence → no central server required; you always have a complete copy locally.
Transparency → advanced users can inspect .git/config or .git/refs/heads/ to see what’s really happening under the hood.

Cheatsheet

Git has a lot of commands so I like to group them into related tasks to make it easier to find what you need based on what you’re trying to do.

Getting Started: Init & Remotes

Every Git journey starts by either creating a new repo or cloning an existing one.
Then, if you want to sync with a remote (GitHub, GitLab, Gitea), you connect it.

Details

SchemaSpy with SQLite

Mon, 08 Sep 2025 18:30:00 -0500

Intro

SchemaSpy is my preferred tool for generating clear, browsable HTML documentation and ER diagrams for SQL databases. It works seamlessly with engines like MySQL and PostgreSQL, but SQLite has historically been difficult to configure and poorly supported. After considerable trial and error, I’ve identified a reliable combination of components and the exact command needed to make SchemaSpy work consistently with SQLite databases.

The Pieces You Need

SchemaSpy itself is “just a JAR,” but to actually generate diagrams you need a few companion pieces: a JDBC driver, a working Java runtime, and (optionally) GraphViz. Getting it to work with SQLite has historically been finicky, if not downright impossible, but the following setup finally did the trick for me

Component	Why It Matters	Version / Download Link
SchemaSpy (fat JAR)	Engine for generating schema docs & ER diagrams	Download v6.2.4
SQLite JDBC Driver (Xerial)	Java connectivity to SQLite `.db` files	Download v3.45.1.0
Java 11+ runtime	Needed to run SchemaSpy (requires Java 8+, but 11+ is safer)	Install via your package manager (`sudo apt install openjdk-11-jre` on Debian/Ubuntu) or Adoptium.net
GraphViz (optional)	Use `dot` for static diagrams	Install with `sudo apt install graphviz` or graphviz.org
Viz.js (`-vizjs`) (recommended)	Renders diagrams in-browser without GraphViz	Built into SchemaSpy v6.1+ — just add the `-vizjs` flag

Quick Download Commands

If you prefer the CLI to clicking links, you can grab the JARs like this:

# Download SchemaSpy 6.2.4
curl -L https://github.com/schemaspy/schemaspy/releases/download/v6.2.4/schemaspy-6.2.4.jar \
     -o schemaspy-6.2.4.jar

# Download SQLite JDBC driver 3.45.1.0
curl -L https://repo1.maven.org/maven2/org/xerial/sqlite-jdbc/3.45.1.0/sqlite-jdbc-3.45.1.0.jar \
     -o sqlite-jdbc-3.45.1.0.jar

Example Database: Chinook

If you don’t want to run SchemaSpy against your own data right away, the Chinook sample database is a great test case.

Download the SQL script: Chinook_Sqlite.sql
Create a SQLite database file from it:

sqlite3 chinook.db < Chinook_Sqlite.sql

This will generate chinook.db populated with a realistic music store schema (artists, albums, tracks, invoices) that works perfectly for testing SchemaSpy.

The Command

The following example assumes that the SchemaSpy jar file, the sqlite-xerial jdbc driver and the db file (chinook.db) are in the current working directory. Otherwise simply provide the correct path to the required files.

java -jar schemaspy-6.2.4.jar \
  -dp sqlite-jdbc-3.45.1.0.jar \
  -t sqlite-xerial -cat % -s main -sso \
  -db ./chinook.db \
  -o ./schemaspy_output \
  -vizjs

Breakdown:

-dp → path to the SQLite JDBC driver jar (Xerial).
-t sqlite-xerial → use the modern Xerial driver profile.
-cat % → wildcard catalog (SQLite doesn’t really have catalogs).
-s main → SQLite’s default schema is always main.
-sso → skip username/password (SQLite doesn’t use them).
-db → path to your .db file.
-o → output folder for the HTML docs.
-vizjs → generate diagrams in-browser without GraphViz.

Why These Flags Matter

Without -dp, SchemaSpy won’t find the correct driver.
Without -t sqlite-xerial, it tries the old/dead SQLite profile.
Without -cat % -s main, you’ll get schema ’null’ or catalog not provided errors.
-sso avoids pointless login prompts which do not apply to Sqlite.
-vizjs keeps the setup lightweight.

Results

SchemaSpy will generate a lovely, full HTML site in ./schemaspy_output. Open index.html to browse:

Overview
Table list
Columns and constraints
Relationship diagrams (ERD)

DEMO View live Chinook database demo

The tables overview generated by SchemaSpy, listing all tables in the database with row counts and basic metadata.

A detail view of columns in a selected table, showing column names, types, nullability, and constraints.

The ER diagram view, with tables connected by their foreign key relationships.

If you haven’t used it before, the generated site is static HTML ready to share with your team and easy to refer to while working with the database!

SQLite in the Wild

One reason it’s worth solving these setup issues is that SQLite is everywhere. Because it’s lightweight, reliable, and requires no separate server process, many applications ship with embedded SQLite databases by default. A few well-known examples:

Apple macOS and iOS
- Messages: ~/Library/Messages/chat.db holds iMessage and SMS history.
- Safari: History.db, Downloads.db, and WebpageIcons.db store browsing data.
- Photos: Photos.sqlite contains library metadata.
- Mail: databases in ~/Library/Mail/.
Web Browsers
- Chromium/Chrome: uses SQLite for History, Cookies, Login Data, and more.
- Firefox: places.sqlite for bookmarks and history, cookies.sqlite for cookie storage.
Messaging and Communication
- Skype: main.db contains chat logs.
- Signal and WhatsApp Desktop: local SQLite databases maintain encrypted state.
Other Tools
- Thunderbird: mail indexing.
- Slack desktop client: caches workspace data.
- VS Code extensions: sometimes use SQLite for project state.

But SQLite isn’t just hidden inside big applications — it’s also ideal for your own projects. If you need a lightweight, file-based database with zero setup, SQLite is often the easiest choice. It’s great for prototypes, local tools, logging, side projects, or anything where you want structured storage without spinning up MySQL or Postgres. Pairing SQLite with SchemaSpy gives you a way to instantly visualize and document your schema, even on small personal databases.

Links & Stuff

SchemaSpy
GitHub Releases – schemaspy-6.2.4.jar
SchemaSpy documentation
SQLite JDBC Driver (Xerial)
GitHub Releases – sqlite-jdbc
Maven Central – org.xerial:sqlite-jdbc
Java Runtime
Debian/Ubuntu: sudo apt install openjdk-11-jre
macOS (Homebrew): brew install openjdk
Adoptium.net – Java binaries
GraphViz (optional)
Download from graphviz.org
Debian/Ubuntu: sudo apt install graphviz
macOS: brew install graphviz
Chinook Sample Database
Chinook_Sqlite.sql
Chinook DataSources repo

Conclusion

SchemaSpy remains one of the most effective tools for documenting database schemas and generating ER diagrams. With the correct JDBC driver and options, it now works reliably with SQLite — a database engine that powers not only major applications like Safari, Chrome, and Apple Messages but also countless personal projects.

The working recipe is straightforward once you know it:

-t sqlite-xerial  -dp   -cat %  -s main  [-vizjs]

This guide demonstrated that configuration with both Apple’s chat.db and the Chinook sample database. The same approach can be applied to almost any SQLite file you encounter, whether it comes from a commercial application or your own side projects.

If you found this guide useful or ran into issues following it, I’d love to hear your feedback. Send comments, corrections, or ideas to feedback@adminjitsu.com.

Dockerizing a Python Script

Sat, 06 Sep 2025 00:02:54 -0500

Intro

In Docker Grimoire we looked at the commands and concepts that make Docker work. But there is another part of the process that deserves special attention: actually creating a Docker container of your own. In this post we’ll take a simple Python script and package it into a full Docker container that is ready to share — covering the ins and outs of the process.

Let's learn some more Docker magic

Docker is fantastic for running other people’s code without worrying about requirements, dependencies, or OS quirks — you just docker run and it works. But the real magic is when you flip that around: you can package your own scripts the same way. By building a container, you freeze your code together with just the environment it needs, so it runs the same on your laptop, your server, or someone else’s machine. No “works on my machine” headaches, no dependency juggling.

Understanding Dockerfiles

A Dockerfile is the blueprint for building an image. Think of it as a provisioning script: each line makes a small, repeatable change to a base OS image. When you run docker build, Docker executes those steps in order and layers the results into a new image.

The basic loop looks like this:

Dockerfile  →  docker build  →  Image  →  docker run  →  Container

A few important points:

Layered builds: each instruction (FROM, COPY, RUN, etc.) becomes its own cached layer. If you rebuild and nothing in that layer changed, Docker reuses the cached result.
Repeatable and portable: once you have a Dockerfile, you can rebuild the same environment anywhere, as many times as you like.
Minimal by design: unlike a full VM image, Dockerfiles usually start from a tiny base (like python:3.12-slim) and add only what’s needed for your app.

This makes Dockerfiles both transparent (you can read exactly how an image is built) and reproducible (anyone else can build the same image from the same file).

Anatomy of a Dockerfile

Most real-world Dockerfiles use just a handful of instructions:

FROM — pick a base image to build on (e.g. FROM python:3.12-slim)
WORKDIR — set the working directory inside the container (WORKDIR /app)
COPY — bring files from your project into the image (COPY smurfify.py .)
RUN — run commands to install dependencies (RUN pip install -r requirements.txt, RUN apt-get update && apt-get install -y curl)
ENTRYPOINT or CMD — define what should run by default when the container starts (ENTRYPOINT ["python", "smurfify.py"])

💡 Tip: Docker executes instructions top to bottom. Group things that change less often (like installing system packages) near the top so they’re cached, and keep frequently changing code copies (COPY . .) near the bottom.

Together, these instructions create a transparent, reproducible recipe. You can read a Dockerfile and know exactly how an image was built — no mysteries.

Choosing a Base Image

Every Dockerfile begins with a FROM line. That single choice sets the foundation for everything else: which OS your container is built on, how big the image will be, and how much work you’ll need to do to get your app running.

Where do these base images come from?

Docker Hub is the default registry. If you write FROM python:3.12-slim, Docker pulls it from hub.docker.com/library/python.
You can browse tags on Docker Hub or check the source Dockerfiles (often maintained on GitHub).
Many projects also publish to GitHub Container Registry (ghcr.io) or Quay.io, but Docker Hub is the most common.

Common base image patterns:

python:X.Y → Full Debian-based image. Includes Python and lots of tools. Bigger, but very compatible.
python:X.Y-slim → Stripped-down Debian variant. Smaller size, still good compatibility. A great default.
python:X.Y-alpine → Based on Alpine Linux. Tiny, but can cause headaches when Python packages need C libraries.
ubuntu, debian, alpine → Bare OS bases, good if you want to install tools yourself.

💡 Rule of thumb:

Use slim for most apps — small, reliable, and widely supported.
Use alpine if size really matters and you’re comfortable fixing build errors.
Use the full image if you need lots of system packages or want fewer surprises.

Researching Images

Docker doesn’t have an apt show equivalent — most image research happens on the registry pages themselves. For Docker Hub images, that means checking pages like Python on Docker Hub.

Here’s what to look for: available tags, size comparisons, and the Image Variants section that explains trade-offs. For Python, you’ll see:

python:3.12 (1.02GB) — full Debian base with build tools
python:3.12-slim (131MB) — stripped down but still compatible
python:3.12-alpine (48MB) — tiny Alpine base, but can cause build issues

The same pattern applies to other languages:

node:20 vs node:20-slim vs node:20-alpine
golang:1.21 vs golang:1.21-alpine

The registry page tells you what each variant includes and when to use it.

Now let’s put this into practice with a real example.

I hope this is crystal clear

Dockerizing Smurfify

We’ll use my Smurfify script as the example. It’s lighthearted, but it makes a perfect example: no dependencies, easy to test, and fun to run. By the end, you’ll understand the workflow for containerizing any script or small app.

Project Setup

The first step is to create a project directory to hold everything related to the container. On my system, I keep container projects under ~/codelab/containers/, so let’s make a home for Smurfify:

mkdir -p ~/codelab/containers/smurfify
cd ~/codelab/containers/smurfify
git init

I like to track these builds in Git so I can version changes and keep my Dockerfiles tidy. That means adding a .gitignore right away so you don’t end up committing build artifacts and temp files. Create a file named .gitignore with contents like this:

# Ignore Python cruft
__pycache__/
*.pyc
*.pyo

# Ignore Docker build artifacts
*.tar
*.log

# Ignore anything generated at runtime
.env

This keeps the repo focused on just your source and Dockerfile.

Now copy the script into the folder:

cp ~/codelab/bin/smurfify.py .

At this point you should have a clean project directory with Git initialized, a .gitignore in place, and your script ready to go.

For this example, we’ll base our container on python:3.12-slim — small enough to be efficient, but big enough to avoid the headaches Alpine images can cause when building Python dependencies.

Writing the Dockerfile

A Dockerfile is the recipe for building an image — each line makes a small, repeatable change to a base OS. For Smurfify we don’t need much: just Python and the script itself.

Create a file called Dockerfile inside ~/codelab/containers/smurfify/:

# Start with a minimal Python base image
FROM python:3.12-slim

# Set a working directory inside the container
WORKDIR /app

# If you have Python requirements you would uncomment these lines
# COPY requirements.txt .
# RUN pip install -r requirements.txt

# Copy the script into the image
COPY smurfify.py .

# Run the script by default
ENTRYPOINT ["python", "smurfify.py"]

That’s the entire recipe:

Start with Python
Drop in your script
Define the default command

If your script had external dependencies, you would uncomment the requirements.txt and pip install lines in the example above

Note ENTRYPOINT vs CMD: ENTRYPOINT locks in your command - arguments from docker run get appended to it. CMD is flexible - arguments completely replace it. For scripts that take input (like Smurfify), use ENTRYPOINT so users can run docker run smurfify "hello world" and it becomes python smurfify.py "hello world". Use CMD for utility containers where users might want to run different commands entirely.

Now your project tree should look like this:

codelab/containers/smurfify/
├── .git/
├── .gitignore
├── smurfify.py
└── Dockerfile

Building the Image

Now that we’ve written a Dockerfile, the next step is to build it into an image — turning our text recipe into an actual runnable package.

From inside the project directory (~/codelab/containers/smurfify/), run:

docker build -t smurfify:latest .

Here’s what’s happening:

docker build → tells Docker to create an image from a Dockerfile.
-t smurfify:latest → tags the image with a name (smurfify) and version (latest).
. → sets the build context to the current directory (everything here is available for COPY).

Docker will step through the file line by line: pulling the Python base image, creating /app, copying in smurfify.py, and wiring up the entrypoint. You’ll see each instruction logged as it runs like this:

└─$ docker build -t smurfify:latest .
[+] Building 0.6s (8/8) FINISHED                                                                         docker:default
 => [internal] load build definition from Dockerfile                                                               0.0s
 => => transferring dockerfile: 282B                                                                               0.0s
 => [internal] load metadata for docker.io/library/python:3.12-slim                                                0.2s
 => [internal] load .dockerignore                                                                                  0.0s
 => => transferring context: 2B                                                                                    0.0s
 => [1/3] FROM docker.io/library/python:3.12-slim@sha256:d67a7b66b989ad6b6d6b10d428dcc5e0bfc3e5f88906e67d490c4d3d  0.0s
 => [internal] load build context                                                                                  0.0s
 => => transferring context: 33B                                                                                   0.0s
 => CACHED [2/3] WORKDIR /app                                                                                      0.0s
 => CACHED [3/3] COPY smurfify.py .                                                                                0.0s
 => exporting to image                                                                                             0.0s
 => => exporting layers                                                                                            0.0s
 => => writing image sha256:1b0752cd62e6222c9cb5ec2f84e9ad2b625baad4cac8ecb08070682c2e2cab0c                       0.0s
 => => naming to docker.io/library/smurfify:latest

💡 Tip: Docker caches layers. If you rebuild after making small edits, only the changed steps rerun — everything else comes from cache. This makes rebuilds much faster once the base layers are downloaded.

Where did the image go?

After the build, you won’t see anything new in your project folder. That’s expected:

Your project directory only holds the recipe (Dockerfile, source code).
The resulting image is stored inside Docker’s local image store (by default under /var/lib/docker/ on Linux).

To see it, list your local images:

docker images
# or
docker image ls

Example output (I use grep because I have a lot of images):

└─$ docker image ls | grep smurfify
smurfify                                 latest        1b0752cd62e6   About an hour ago   144MB

So think of it this way: your working directory holds the recipe, and Docker’s internal registry holds the finished meal.

Running the Container

With the image built, we can test it out and see it in action.

Basic run with an argument:

docker run smurfify "Help me, Obi-Wan Kenobi, you're my only hope"
# outputs: Smurf me, Obi-Wan Kenobi, you're my only smurf

Or pipe input with STDIN:

echo "All the world's a stage" | docker run -i smurfify
# outputs: All the smurf's a stage

Interactive Mode

Because our script has a REPL mode (it reads from stdin if no arguments are provided), we can drop into it directly using -it:

docker run -it smurfify

Example session:

smurfify.py 💙 - Type a line to smurf. Ctrl-D (or Ctrl-Z) to quit.
Damn the torpedoes, full speed ahead!
Smurf! the torpedoes, full speed ahead!
Ask not what your country can do for you -- ask what you can do for your country.
Smurf not what your country can do for you -- smurf what you can do for your country.

💡 What -it means:

-i → interactive: keeps STDIN open so the container can accept your input.
-t → TTY: allocates a pseudo-terminal, so you get proper line editing and prompts.

Together, -it makes containers behave like a program you can talk to in real time — perfect for scripts like Smurfify.

At this point, you can:

Run it once with arguments.
Pipe text into it.
Use it interactively with -it.

That covers the full set of ways you’d normally interact with a CLI tool inside Docker. Of course, not every container is this simple — if you were shipping a whole web server or database, you’d likely be exposing ports, mounting volumes, or running multiple services. But the same core idea applies: image → container → run.

Troubleshooting & Tips

A few monsters lurk in the dungeon but nothing we can't handle

💡 Our example is simple on purpose.
Real projects get messy — different languages, heavier dependencies, weird edge cases. The good news: the workflow doesn’t change. Here are a few common pitfalls that you might run into:

Common Gotchas

Image too big?
Try a -slim or -alpine variant. Just note Alpine can break builds when native extensions need glibc.
Container exits immediately?
Containers stop when their command finishes. For scripts, that’s normal — they run and then quit. Use -it for interactive use, or design a service that keeps running.
COPY or ADD not working?
Check your build context. Only files in the same directory (and subdirectories) as your Dockerfile get included.
Dependency errors?
Make sure installs happen inside the image:
```
RUN pip install -r requirements.txt
```
not on your host machine.
Builds are slow or images feel bloated?
Add a .dockerignore next to your Dockerfile — it works like .gitignore and keeps junk (.git/, caches, logs, secrets) out of your build context.

Pro-Tips

Always pin your base image version (python:3.12-slim, not python:latest) for reproducibility.
Keep Dockerfiles minimal: smaller images build faster, pull faster, and break less.
For debugging builds, temporarily add a shell:
```
RUN apt-get update && apt-get install -y vim curl
```
then strip it out later.

Links and Stuff

Essential References:

Dockerfile Reference — The complete command reference for all Dockerfile instructions
Docker Hub — Browse and search for base images
Docker CLI Reference — All the docker commands you’ll use

Best Practices & Guides:

Dockerfile Best Practices — Official guidance on writing efficient, maintainable Dockerfiles
Docker Build Best Practices — Covers incremental build time, image size, maintainability, security and repeatability
Multi-stage Builds — For keeping production images lean

When Things Go Wrong:

Build Checks — Validate your build configuration and catch common issues
Docker Logs — Essential for debugging container problems

Conclusion

That’s the whole workflow: script → Dockerfile → image → container.

This workflow works for any tool you want to containerize. Now when you need to demo that sweet script or share a utility with the world, you’ll have a tool that actually works — no more “but it works on my machine” disasters or impromptu troubleshooting sessions.

Time to practice! Containerize your own scripts and keep the Docker Grimoire handy for reference.

Have a Docker war story? Killer tip? I’d love to hear about it: feedback@adminjitsu.com

Docker Grimoire

Thu, 04 Sep 2025 22:17:11 -0500

Intro

Docker has become one of those critical technologies powering everything from scrappy homelabs to enterprise infrastructure. It can feel intimidating at first—so many new terms, layers, and tools—but armed with a good cheatsheet and the right explanations, Docker turns out to be surprisingly fun and almost magically powerful.

With it, you can host an entire network of services on your own machine: media servers like Jellyfin and Immich, full LAMP stacks for web development, databases, your own git server or even your own custom scripts packaged and deployed cleanly.

In this guide we’ll compile commands, concepts, official docs, and practical examples into one handy resource. Because Docker is less confusing than it seems—and with a few best practices, it can become one of the most reliable and versatile parts of your network.

What is Docker?

At its core, Docker is a way to run little computers inside your computer.

Each Docker container is its own lightweight environment, with just enough OS, libraries, and binaries to do one job well—whether that’s serving a web app, crunching data, or running a database. Instead of cluttering your base OS with packages and configs, you pull a prebuilt image and run it in isolation.

Technically speaking, Docker builds on core Linux kernel features like namespaces, cgroups, and union (overlay) filesystems to provide process isolation and resource management. Unlike traditional virtualization—which uses a hypervisor to run full guest operating systems on abstracted hardware—Docker employs OS-level virtualization (containerization), sharing the host kernel across containers and making it far more lightweight and efficient.

A bit of history:

Docker was created in 2013 by Solomon Hykes and the team at dotCloud (a PaaS startup), and has since evolved into a massive open-source ecosystem.
It’s primarily written in Go, with CLI tooling and APIs that work across Linux, Windows, and macOS.
In just over a decade, it’s become a near-ubiquitous layer in modern development and operations: used in CI/CD pipelines, cloud deployments, and, increasingly, personal projects and homelabs.

Why is it so popular? A few key benefits:

Isolation without the overhead of full VMs.
Consistency across environments: the same image runs on your laptop, server, or in the cloud.
Portability and sharing: Docker Hub and registries make distributing software trivial.
Resource efficiency: containers spin up in seconds and can be packed densely on a single host.
Flexibility: from one-off experiments to long-lived production services.

Today, Docker shows up everywhere—from billion-dollar cloud platforms to basement labs. On my own server gir.darkstar.home, I run over twenty containers: Jellyfin, Portainer, Dashy, Uptime Kuma, Gitea, Jupyter Labs and more. It keeps everything clean and manageable and easy to backup. I kind of love Docker!

In the sections ahead, we’ll start with a practical cheatsheet of Docker commands, then build toward hands-on tutorials: installing Portainer, containerizing a script, updating a service without losing data, and even migrating containers to a new host.

Usage: The Docker CLI Cheatsheet

Unlike stage magicians, Unix wizards are happy to share their tricks!

Even if you lean on Docker Desktop, Portainer, or other GUIs, the command line is always there.
It’s the universal interface: every container operation can be expressed at the CLI,
whether you’re hacking on a laptop, administering a headless server, or scripting a CI/CD pipeline.

If you can run it from the CLI, you can automate it, debug it, or wrap it in a script later.

This cheatsheet is organized into task-oriented sections, each with:

A quick explanation of why the task matters
A collapsible block of relevant commands
Footnotes, Usage caveats and more

Commands may appear in more than one section if they’re useful for that workflow.
By the end, you’ll have a mental map of what to reach for, whether you’re checking logs, moving files,
or pruning old containers that are eating up disk space.

Checking What’s Running

The first step in container management is knowing what’s happening right now.
Which containers are up, which have stopped, and how much load they’re putting on your system?
This section gives you the heartbeat of your Docker host — status, ports, resource usage, and quick inspections.

Details

Signals Intelligence

Wed, 03 Sep 2025 14:44:57 -0500

Intro

Unix signals are one of the oldest forms of inter-process communication. Born in early UNIX at Bell Labs (1970s), they were designed as a simple way for the kernel to tap a process on the shoulder. Unlike pipes or sockets, signals don’t carry payloads — just a notification.

They remain the universal way the OS tells programs when it’s time to stop, reload, or respond to user actions. Servers, daemons, shells, even containers all depend on them. Think of signals as lifecycle control, while other IPC mechanisms handle the heavy lifting.

Fun Fact: The very first “signals” were just conventions that most but not all programs hard-wired for job control (Ctrl+C, Ctrl+Z). Everything else—portability, universality, reloads, graceful quits—are clever conventions layered on later.

Ctrl-C, Ctrl-C... why isn't it responding?
Still from WarGames (1983, MGM). Used under fair use for educational purposes.

Unix IPC signals are easy to use but there are a lot of exceptions and footnotes. I tried to make the following as clear as possible without going full-on manual.

Signals vs other Unix-land IPC

The more they over-think the plumbing the easier it is to stop up the drain. –anonymous fortune

Signals are almost all one-bit notifications from the kernel. They don’t carry payloads, just a type (e.g. SIGTERM), and they interrupt a process asynchronously. The exception being POSIX real-time signals like sigqueue which can carry a small int/pointer. Use them for lifecycle events (quit, reload, stop) and simple control.
Pipes (man 7 pipe) are byte streams between processes, usually set up with | in the shell. Data flows in one direction, buffered by the kernel (half-duplex). Bidirectional requires two pipes. Think of ls | grep foo — that’s a pipe doing work. Pipes are synchronous: the reader blocks until there’s data. There are also named pipes or FIFOs, made with mkfifo, which persist in the filesystem and let unrelated processes talk. Same half-duplex rule applies.
Sockets (man 7 socket) generalize pipes into a full-duplex/bidirectional, network-style interface. They can talk locally (UNIX domain sockets) or across machines (TCP/UDP). Most client-server software is built on sockets.
Message Queues & Shared Memory (man 7 mq_overview, man 7 shm_overview) are heavier IPC mechanisms. They allow structured data passing or even memory regions mapped between processes. Used when performance matters or when large state must be shared.
DBus (freedesktop.org) is a high-level message bus, running in user space via a broker daemon. Think of it as an application-layer IPC system: processes send structured requests and events through a central hub. Desktop environments and system services (NetworkManager, systemd, GNOME) rely on it. DBus “signals” are logical user-space events, not kernel ones.

Pro-Tip: If you’re just controlling a process, signals are usually enough. If you need to talk to it, look at sockets or DBus.

Usage Cheatsheet

Common signals you’ll run into:

Signal	Trigger / Use case	Default action	Notes
`SIGINT`	Ctrl+C in a terminal	Terminate	Apps can catch to clean up.
`SIGTERM`	`kill` or `systemctl stop`	Terminate	The polite way to ask a process to quit.
`SIGHUP`	Terminal hangup; config reloads	Terminate	Many daemons repurpose it as “reload config.”
`SIGQUIT`	Ctrl+\	Core dump + exit	some like nginx use it for graceful quit.
`SIGKILL`	`kill -9`	Terminate (uncatchable)	No cleanup, can’t be trapped.
`SIGTSTP`	Ctrl+Z	Stop (suspend)	Background job control; `fg` to resume.

You can list them all with kill -l and you will get a list like this:

└─$ kill -l
 1) SIGHUP       2) SIGINT       3) SIGQUIT      4) SIGILL       5) SIGTRAP
 6) SIGABRT      7) SIGBUS       8) SIGFPE       9) SIGKILL     10) SIGUSR1
11) SIGSEGV     12) SIGUSR2     13) SIGPIPE     14) SIGALRM     15) SIGTERM
16) SIGSTKFLT   17) SIGCHLD     18) SIGCONT     19) SIGSTOP     20) SIGTSTP
21) SIGTTIN     22) SIGTTOU     23) SIGURG      24) SIGXCPU     25) SIGXFSZ
26) SIGVTALRM   27) SIGPROF     28) SIGWINCH    29) SIGIO       30) SIGPWR
31) SIGSYS      34) SIGRTMIN    35) SIGRTMIN+1  36) SIGRTMIN+2  37) SIGRTMIN+3
38) SIGRTMIN+4  39) SIGRTMIN+5  40) SIGRTMIN+6  41) SIGRTMIN+7  42) SIGRTMIN+8
43) SIGRTMIN+9  44) SIGRTMIN+10 45) SIGRTMIN+11 46) SIGRTMIN+12 47) SIGRTMIN+13
48) SIGRTMIN+14 49) SIGRTMIN+15 50) SIGRTMAX-14 51) SIGRTMAX-13 52) SIGRTMAX-12
53) SIGRTMAX-11 54) SIGRTMAX-10 55) SIGRTMAX-9  56) SIGRTMAX-8  57) SIGRTMAX-7
58) SIGRTMAX-6  59) SIGRTMAX-5  60) SIGRTMAX-4  61) SIGRTMAX-3  62) SIGRTMAX-2
63) SIGRTMAX-1  64) SIGRTMAX

Note: the list and numbers shown are from Linux. Signal names are portable, but numbers and availability differ on BSD/macOS/Solaris.

Most of the time you only care about the common signals, and modern tools let you use their names (SIGTERM, SIGHUP, etc.) directly.
The old habit of using numbers (kill -9 or kill -1) still works, but it’s less portable since signal numbers vary across Unix flavors. Stick to names unless you’re typing a quick shortcut.

The main tool for sending signals is the kill command which despite its name, it doesn’t always “kill” a process. By default it throws SIGTERM, but you can specify any signal. Think of it as the userland signal throwing tool that just defaults to kill:

# First, find the PID of the process you want to affect
ps aux | grep nginx

# Then send it a signal
kill -TERM     # send SIGTERM (default)
kill -HUP      # send SIGHUP
kill -KILL     # send SIGKILL (can’t be trapped)
killall -HUP nginx  # send SIGHUP to all nginx processes

Pro-Tip: With kill -9 you must supply the PID of every process you want to kill. That’s why tools like pkill and killall are so handy.

Beyond `kill`: other ways to signal processes

Signals aren’t just for kill. The shell and related tools let you affect processes in different ways:

Job Control (in the shell)
- Ctrl+Z → sends SIGTSTP (suspend) via the terminal driver.
- bg → resumes a job in the background (sends SIGCONT).
- fg → brings a job back to the foreground.
- jobs -l → shows current job table with PIDs.
```
# Start a long-running process in the foreground
sleep 600

# Press Ctrl+Z in the terminal
# Output will look like:
[1]+  Stopped    sleep 600

# See it in the job table (with PID)
jobs -l
[1]+  12345 Stopped    sleep 600

# Resume it in the background
bg %1
[1]+  12345 Running    sleep 600 &

# Bring it back to the foreground
fg %1
sleep 600
```
Notes:
- bg and fg only work on processes started from the current shell.
- If the process expects input, running it in the background (bg) won’t magically make it non-interactive — it may still block waiting for input.
- Background jobs still write to the terminal by default. Use output redirection (> file 2>&1) if you don’t want them spamming your shell.
- If you close the terminal, jobs will get SIGHUP unless you’ve used nohup or disown.
- In bash/zsh you can reference jobs by number %1, %2, or by name substring: fg %sleep.

nohup
Run a command that keeps going even after you log out of the shell:
```
nohup hugo server -D &
```
This ignores SIGHUP, so the process keeps running if you log out of your shell or disconnect an SSH session. Output (both stdout and stderr) gets redirected to nohup.out by default unless you specify otherwise.
Notes:
- Logging out: the process keeps running in the background.
- Logging back in (or SSH-ing again): the process is still alive, but it won’t show up in your jobs list since that’s tied to the original shell. Use ps aux | grep hugo or pgrep hugo to find it.
- Reboot: nohup does not survive a reboot. For persistence across restarts, use a service manager like systemd, supervisord, or Docker.
- Good use case: quick, long-running tasks during a session (like nohup hugo server -D & while you hack on a blog). Not a replacement for proper service management.
disown (bash/zsh only)
Removes a job from the shell’s job table so it won’t receive SIGHUP. The process keeps running, but the shell forgets about it.
```
sleep 600 &
jobs -l
disown %1
jobs -l    # now the job no longer shows up
```
Since it’s a shell builtin, there’s no man disown. Use:
```
help disown   # bash
```
or in zsh:
```
man zshbuiltins | less +/disown
```

renice
Adjust scheduling priority (not a signal, but related process control).
- Lower nice value = higher CPU priority (use for important processes).
- Higher nice value = lower CPU priority (good for heavy background tasks).
- Niceness ranges from -20 (highest priority) to 19 (lowest priority). Default is 0
```
renice -n 19 -p    # very "nice" → gets less CPU time
renice -n 0 -p     # reset to normal priority
renice -n -5 -p    # increase priority (root only)
```

killall / pkill
Send signals by process name or regex pattern, instead of hunting PIDs manually:

kill -USR1        # send a specific signal to a given PID (works on one or a list of PIDs)
kill -HUP 1234 1235    # send HUP to multiple PIDs 
killall -TERM vim      # send TERM to all vim processes

pkill -HUP nginx       # send HUP to all processes named nginx
pkill -HUP -f 'nginx.*worker'   # send SIGHUP to any process whose command matches the regex "nginx.*worker"
pkill -TERM -f 'jupyter-notebook'   # restart all Jupyter notebook servers (if multiple users)

systemctl
Modern services often live under systemd. Commands like systemctl stop, reload, and restart rely on signals under the hood, but with extra policy:
- stop → sends SIGTERM, then escalates to SIGKILL if the process doesn’t exit within TimeoutStopSec=.
- reload → runs ExecReload= from the unit file, or if unset, sends the service’s ReloadSignal= (often SIGHUP).
- restart → does a stop, then start (so SIGTERM → SIGKILL if needed, then new process).

Pro-Tip:
Backgrounding (&, bg) isn’t just convenience — it literally controls signals (SIGSTOP, SIGCONT) at the kernel level.

It was a simpler time

Bash Traps

A common pattern is to trap several signals at once, so your script can clean up or log before exiting.

Here’s an example script that spins up a background worker, and makes sure it’s killed cleanly on exit or interrupt:

#!/usr/bin/env bash
# demo-trap.sh

# Start a dummy background job
sleep 600 &
worker_pid=$!
echo "Worker started with PID $worker_pid"

# Define cleanup function
cleanup() {
    echo "Caught signal, cleaning up..."
    kill -TERM "$worker_pid" 2>/dev/null
    wait "$worker_pid" 2>/dev/null
    echo "Worker stopped. Exiting."
    exit 0
}

# Trap multiple signals
trap cleanup INT TERM HUP

# Main loop
while true; do
    echo "Main script running. Press Ctrl+C to stop."
    sleep 10
done

INT → user pressed Ctrl+C
TERM → process was asked to stop politely (kill or systemctl stop)
HUP → hangup (often used as “reload”)

Pro-Tip: You can trap multiple signals in one line. Here, trap cleanup INT TERM HUP ensures your cleanup runs whether you press Ctrl+C, close the terminal, or stop it from another shell.

Python Signal Handling

Profanity is the one language all programmers know best. –anonymous fortune

Python has the signal module, which lets you trap signals much like Bash.
Typical use case: catch SIGINT (Ctrl+C) or SIGTERM (kill) to shut down cleanly.

Example:

#!/usr/bin/env python3
import signal
import sys
import time

# Define handler function
def handle_signal(signum, frame):
    print(f"Caught signal {signum}, cleaning up...")
    # do cleanup here
    sys.exit(0)

# Register handlers
signal.signal(signal.SIGINT, handle_signal)   # Ctrl+C
signal.signal(signal.SIGTERM, handle_signal)  # kill 

print("Running. Press Ctrl+C or send SIGTERM to stop.")

# Simulate work
while True:
    time.sleep(1)

SIGINT → user pressed Ctrl+C
SIGTERM → process asked to stop politely (kill )

Pro-Tip:

Not every signal is catchable in Python. For example, SIGKILL and SIGSTOP can never be trapped — the kernel enforces those.
Only the main thread can set handlers, and signals are always delivered to that thread.
On Windows, only a limited set of signals work (SIGINT, SIGBREAK, and a fake SIGTERM).
In async code, you can use loop.add_signal_handler(signal.SIGTERM, callback) to integrate with asyncio.

Links and Stuff

Overview topics

References

kill(1) — man7 — manual page for the kill command
pgrep(1)/pkill(1) — man7 — search or signal processes by name/regex
killall(1) — man7 — signal all processes matching a name (note portability differences)
Linux kernel signal.c — kernel source handling signals & job control
Python signal module docs — official Python reference
systemd.service(5) — details on ExecReload= and ReloadSignal= in systemd units
POSIX signal.h — portable signal definitions

Conclusion

That’s it — a quick and dirty guide to signals in Unix-land.
Signals are one of those Unix fundamentals that everybody bumps into, but they can still trip you up if you don’t know the details.

Next time you press Ctrl+C, background a process, or reload a daemon, remember: you’re working with a mechanism that’s been around since the 1970s and is still quietly running the show today.

📬 Got a favorite signal trick or a war story about a kill -9 gone wrong? Send it my way: feedback@adminjitsu.com

Daemonology: A Cross-Platform Guide

Mon, 01 Sep 2025 08:21:04 -0500

Intro

The Sunnydale High Library seems like a good place to start this one
Still from Buffy the Vampire Slayer (© 20th Century Fox Television). Used here under fair use for commentary.

Welcome to Daemonology — the (sometimes) dark art of getting programs to behave, run on schedule, and stick around without babysitting. Whether you’re on Linux with systemd or macOS with launchd, the idea is simple: if you want the operating system to manage your script—starting it, stopping it, logging it, or running it on a schedule—you define it as a service.

In Unix, daemons are background processes that run independently of any user session, usually starting at boot and quietly providing essential services like scheduling, networking, or logging. They don’t interact directly with the user but instead handle requests or monitor resources, often ending in a d (e.g. sshd, cron). Think of them as the invisible caretakers that keep the system’s gears turning.

People have debated the move from init.d/cron to systemd and launchd a lot over the years — if you want the lore, start here: systemd controversy. But if you’re running a modern Linux (or anything Apple), chances are you’re already in the world of systemd or launchd. These tools give you structured configs, unified logging, restart policies, and scheduling baked right in. The downisde is that they can sometimes be verbose and confusing.

Here’s a practical starter kit to tame them: bare-bones configs, restart policies, and cheatsheet.

Terminology

“Never try to fool children, they expect nothing, and therefore see everything.” — Harry Houdini

Before we dive into skeletons and configs, let’s set the stage. There are a few moving pieces here, and the terms get overloaded. A little clarity up front makes the rest fall into place.

The Old, Classic Way (init.d + cron)

For decades, Unix-like systems handled background jobs in two different ways:

System V init.d scripts
Long-running services (daemons) like sshd or apache2 were defined in scripts that lived in /etc/init.d/.
They were shell scripts with start, stop, and restart functions, called by the system at boot.

BSD init + rc scripts
On BSD systems (and early macOS/Darwin), initialization was driven by a simpler BSD-style init.
A master script (/etc/rc) or per-service scripts in /etc/rc.d/ launched daemons at startup, with settings controlled by rc.conf.
cron jobs
Scheduled one-shot scripts ran from crontab -e.
You wrote lines like 0 2 * * * /usr/local/bin/backup.sh, and cron would invoke them at the right time.
Output usually vanished into the void unless you redirected it somewhere.

It worked, but it meant services and scheduled jobs were managed by different tools, with different conventions and almost no unified logging.

The New Way (systemd + launchd)

In an effort to unify the init and scheduling system, modern systems settled on a more structured approach:

On Linux, systemd runs the show.
On macOS, Apple’s launchd plays a similar role.

Like the old init process, they are still the first userspace process launched by the kernel (PID 1), responsible for starting everything else. The difference is that they replace the runlevel scripts with declarative unit definitions and a dependency graph. They also integrate scheduling for periodic jobs, so one system manages both daemons and one-shot tasks.

Both treat everything as a unit of work described by a small config file. Whether you want a daemon that runs forever, or a script that fires at intervals, you now describe it the same way — in a .service (systemd) or .plist (launchd). Scheduling is built-in (.timer in systemd, StartInterval in launchd), so you don’t need a separate cron subsystem.

Services vs Ad-hoc Scripts

Let’s clarify some key terminology to avoid confusion.

Ad-hoc Scripts

These are scripts you run manually as needed—no system management required. You can run them in the background during use, but they won’t persist after reboot or restart automatically if they crash.

Managed Services

Every program you want the system to manage needs a definition file:

Linux (systemd): .service unit files
macOS (launchd): .plist files

These definition files are simple wrappers that tell the system:

Which command or script to run
What user to run it as
The working directory
How to handle failures
Where to send logs

Two Types of Managed Services

Scheduled Jobs — Run automatically on a schedule Perfect for tasks like backup scripts that tar up your home directory.

systemd: Create a .service file + a .timer unit that points to it
launchd: Add scheduling keys like StartInterval or StartCalendarInterval to your .plist

Daemons — Long-running services that listen for requests Examples include Python web servers or shell loops writing heartbeats.

systemd: Just a .service file (no timer needed)
launchd: Just a .plist file (no scheduling keys needed)

The service stays alive on its own, while the init system handles the lifecycle—tracking the PID, restarting if needed, and capturing logs.

Quick Reference:

systemd: .service files for everything, add .timer for scheduled jobs
launchd: .plist files for everything, add scheduling keys for scheduled jobs
Daemons: Only need the basic service definition—they manage their own runtime

feel like a wizard yet?

Script Patterns in Practice

Before we look at service definitions, it helps to see the kinds of scripts you might be managing. These are minimal examples that illustrate the difference between ad-hoc jobs and programs that behave like daemons. They aren’t production-ready (real daemons usually need logging, signal handling, and proper backgrounding), but they capture the basic patterns.

Run-once script — an ad-hoc job you’d pair with a timer:

#!/usr/bin/env bash
tar czf ~/backups/home-$(date +%F).tgz ~/Documents

This script runs once and exits. To have it run automatically, you’d wrap it in a .service/.plist and add a .timer or scheduling key.

Looping daemon — a service that drives itself:

#!/usr/bin/env bash
while true; do
  date >> /var/log/heartbeat.log
  sleep 60
done

The program never exits—it controls its own rhythm with sleep, waking up to do work periodically. Wrapped in a .service/.plist, the init system ensures it stays alive and restarts if it crashes.

This pattern is less visible than listener daemons, but it shows up in places like watchdogs, heartbeat loggers, systemd-timesyncd, cron/anacron, and plenty of user scripts that need to wake up every so often.

Listener daemon — a service that waits for external input:

import socket
s = socket.socket()
s.bind(("0.0.0.0", 8080))
s.listen(5)
while True:
    conn, addr = s.accept()
    conn.send(b"Hello, world!\n")
    conn.close()

Unlike the looping example, this doesn’t “wake itself up.” Instead, it sits idle until something connects—the program is event-driven, with the outside world driving the loop. With systemd or launchd managing it, you get lifecycle management, automated logging, and restarts on crash.

This is the pattern that a lot of well known servers like nginx, apache2, sshd and postgresql are based on. They listen for requests and respond to them.

Linux systemd Skeletons

templates / skeletons are really useful

Unit files are just plain text, but placement and naming matter.

System-wide units live under /etc/systemd/system/ (root-owned, affect all users).
User units live under ~/.config/systemd/user/ (run as your user, no root required).
Files must end in .service or .timer. The basename ties them together: mybackup.timer will trigger mybackup.service.

Below is a minimal example: a .service that runs a backup script, and a .timer that fires it every night at 2 AM. Yes, comments starting with # are allowed in unit files — you can omit these lines but using them liberally helps future you. Either way, feel free to copy any of the following examples as a starting point and modify them to suit your needs

Example: mybackup.service

# ==========================================================
# mybackup.service — Example systemd service
# Save to: ~/.config/systemd/user/mybackup.service
# ==========================================================

[Unit]
Description=Run home directory backup
# ↑ Human-friendly description (shows up in `systemctl status`).

# Optional ordering/dependencies: After=network.target ensures
# the service only runs once networking is available. This primarily matters on boot so
# you may or may not need it depending on the service
After=network.target

[Service]
# The actual command to run. Always use the absolute path.
ExecStart=/usr/local/bin/backup.sh

# Optional: directory to treat as "current working directory".
# If omitted, defaults to /.
WorkingDirectory=/usr/local/bin

# User account to run as. For user services, this is implied,
# but for system-wide services it’s important to set explicitly.
User=forfaxx

# Restart behavior:
# - no (default) → do not restart
# - always → restart unconditionally
# - on-failure → restart if the process exits with an error
Restart=on-failure

# Example of passing environment variables into the service:
# Environment="BACKUP_DIR=/mnt/backups"

[Install]
# This section defines what targets this unit hooks into when enabled.
# For simple run-once jobs, this usually isn’t needed unless you want it
# to also start at boot. For timer-driven jobs, the timer unit handles it.
WantedBy=default.target

mybackup.timer

# ==========================================================
# mybackup.timer — Example systemd timer
# Save to: ~/.config/systemd/user/mybackup.timer
# ==========================================================

[Unit]
Description=Run home directory backup daily at 2am
# ↑ Shown in `systemctl status` and logs.

[Timer]
# Calendar syntax:
#   Day-Month-Year Hour:Minute:Second
#   * means "any". So this is "every day at 02:00".
OnCalendar=*-*-* 02:00:00

# Optional: spread jobs randomly by up to this amount of time.
# Useful when many machines might start the same timer simultaneously.
RandomizedDelaySec=15m

# If true, systemd will run the job immediately on startup if it
# was missed while the machine was off or asleep.
Persistent=true

[Install]
# Tie this timer to the global "timers.target" so it runs when enabled.
WantedBy=timers.target

Usage

# Reload so systemd notices new units
systemctl --user daemon-reload

# Enable and start the timer (this implicitly links to the service)
# Note: --user is crucial here - without it, you'd be managing system services as root
systemctl --user enable --now mybackup.timer

# Check status: shows last and next run
systemctl --user status mybackup.timer

# See logs from the last run
journalctl --user -u mybackup.service -e

systemd `.timer` scheduling options

Timers in systemd can trigger units based on absolute calendar time, relative/monotonic delays, or a mix of both. You define them in a foo.timer file, usually paired with a foo.service. The calendar parser understands rich ISO-8601–style dates and times, making it far more expressive than cron.

Calendar-based
These options use calendar expressions to run jobs at exact times or repeating schedules. The syntax is flexible: you can specify wildcards (*), named days, or shorthand like daily.

OnCalendar= → ISO-8601–style calendar expressions. Examples:

OnCalendar=*-*-* 09:00 → every day at 9 AM
OnCalendar=Tue,Thu *-*-* 18:00 → every Tuesday and Thursday at 6 PM
OnCalendar=Mon..Fri *-*-* 08:30 → weekdays at 8:30 AM

Shorthands: hourly, daily, weekly, monthly, yearly

    # myweekly.timer
  [Unit]
  Description=Run weekly cleanup

  [Timer]
  # shorthand: every Monday at 00:00
  OnCalendar=weekly

  # optional: jitter and catch-up
  RandomizedDelaySec=1h
  Persistent=true

  [Install]
  WantedBy=timers.target

Shorthand mappings
Systemd provides a few convenient aliases for common schedules. They expand into explicit calendar expressions:

Shorthand	Equivalent expression	Meaning
`hourly`	`--* *:00:00`	every hour on the hour
`daily`	`--* 00:00:00`	every day at midnight
`weekly`	`Mon --* 00:00:00`	every Monday at midnight
`monthly`	`--01 00:00:00`	first day of each month at midnight
`yearly` / `annually`	`*-01-01 00:00:00`	every January 1st at midnight

👉 Use the shorthands for simplicity, or write explicit forms (Fri *-*-* 18:00) if you need more control.

Monotonic (relative) timers
These options measure time relative to certain events (boot, activation, or last run) and are useful for delays and repeating intervals.

OnActiveSec= → time since the timer was activated
i.e. OnActiveSec=5min (run 5 minutes after enabling)
OnBootSec= → time since system boot
i.e. OnBootSec=10min (run 10 minutes after boot)
OnStartupSec= → time since the systemd manager itself started
OnUnitActiveSec= → time since the unit was last active
i.e. OnUnitActiveSec=1h (rerun one hour after the last run)
OnUnitInactiveSec= → time since the unit was last inactive
i.e. OnUnitInactiveSec=30s (rerun if idle for 30 seconds)

Other controls (modifiers)
These don’t trigger timers on their own; they adjust how the above schedules behave.

AccuracySec= → how precise the firing time must be (default 1 min). Larger values allow batching.
i.e. AccuracySec=5min
RandomizedDelaySec= → adds jitter to spread out jobs.
i.e. RandomizedDelaySec=30s (fires randomly within a 30s window)
Persistent= → catch up on missed runs after downtime.
i.e. a nightly backup still runs on next boot if the system was off at midnight

👉 In practice: .timer units combine calendar scheduling, relative delays, and resiliency features like persistence and jitter. They’re effectively a superset of cron, anacron, and manual sleep loops.

Docs

Canonical references for systemd units, services, and timers (freedesktop.org):

systemd.unit(5) — general unit file structure
systemd.service(5) — service-specific directives
systemd.timer(5) — timer options (OnCalendar, Persistent, etc.)

a little knowledge can be a dangerous thing

macOS launchd Skeletons

On macOS, every managed job is described by an XML .plist file (property list).

Per-user jobs → ~/Library/LaunchAgents/ (run as your login user).
System-wide daemons → /Library/LaunchDaemons/ (run as root by default, but you should set a dedicated service user ).
Filenames must end in .plist, and each must have a unique Label.
Comments use XML syntax: .

Unlike cron, scheduling is optional. If you omit it, the job won’t run automatically — you’ll trigger it manually with launchctl start. For daemons, you use KeepAlive instead of a schedule.

Example 1: Scheduled Job (cron-style replacement)

This runs a backup script at 2:00 AM every day.




  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 version="1.0">


  
  Label
  com.user.backup

  
  ProgramArguments
  
    /usr/local/bin/backup.sh
  

  
  StandardOutPath
  /tmp/com.user.backup.out
  StandardErrorPath
  /tmp/com.user.backup.err

  
  

  
  StartCalendarInterval
  
    Hour2
    Minute0
  

  
  RunAtLoad

Example 2: Daemon (always-on service)

This wraps a program like nginx or postgres — something that should stay alive forever.




  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 version="1.0">


  
  Label
  com.user.daemon

  
  ProgramArguments
  
    /usr/local/sbin/nginx
    
    -g
    daemon off;
  

  
  KeepAlive
  

  
  UserName
  www

  
  StandardOutPath
  /var/log/com.user.daemon.out
  StandardErrorPath
  /var/log/com.user.daemon.err

Event-Triggered Jobs (no schedule)

You don’t need a timer for everything—launchd can trigger on file changes or open a socket for you.

Run when files change (WatchPaths)


 version="1.0">

  Label com.user.ingest
  ProgramArguments
  /usr/local/bin/ingest.sh

  
  WatchPaths
  ~/inbox

  StandardOutPath ~/Library/Logs/com.user.ingest.out
  StandardErrorPath ~/Library/Logs/com.user.ingest.err

Usage

# Modern approach (macOS 10.10+)
# Load/enable the job
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.backup.plist

# Unload/disable it  
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.user.backup.plist

# Check if it's active
launchctl list | grep com.user.backup

# Manually trigger (this part stays the same)
launchctl start com.user.backup

# Legacy commands (still work but deprecated)
# launchctl load ~/Library/LaunchAgents/com.user.backup.plist
# launchctl unload ~/Library/LaunchAgents/com.user.backup.plist

Note Modern vs Legacy Syntax

Apple deprecated the legacy launchctl load/unload commands in macOS 10.10, replacing them with bootstrap/bootout. The old commands still work for now, but the modern syntax is more explicit and avoids ambiguity.

The key difference is domains: modern commands require you to specify where the job should be loaded.

For personal jobs in ~/Library/LaunchAgents/, use:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/myjob.plist
This targets your GUI user session ($(id -u) expands to your numeric UID).
For system daemons in /Library/LaunchDaemons/, use:
launchctl bootstrap system /Library/LaunchDaemons/mydaemon.plist

Apple introduced this change to solve issues with Fast User Switching and multiple user sessions, where the older load/unload commands could be ambiguous.

Most existing tutorials still use the legacy syntax because it’s simpler and widely understood, but the modern domain-based approach is clearer and gives precise control over job placement.

Choosing a Label

Every launchd job needs a unique . Apple convention is to use reverse-DNS style names, like:

com.apple.sshd
org.postgresql.server
net.nginx.web

For your own jobs, you can safely pick something like:

com.yourname.backup
net.darkstar.heartbeat

The format doesn’t change how launchd behaves — it’s purely an identifier — but the reverse-DNS pattern avoids collisions. Two rules of thumb:

Unique per system: If two jobs share a label, launchd gets confused.
Readable: Make it obvious what the job does when you run launchctl list.

If in doubt, prefix with your username or domain, then the purpose. For example, instead of just backup, use something like com.forfaxx.backup to avoid clashing with system jobs.

launchd scheduling options (macOS)

Jobs in macOS are managed by launchd, defined in .plist XML files and loaded with launchctl. Instead of a single flexible expression like OnCalendar=, launchd breaks scheduling into separate keys. These can be combined, but each key is very explicit — no wildcards or ranges like you’d find in cron.

Calendar-based
StartCalendarInterval is the closest thing to cron. It accepts a dictionary (or an array of dictionaries) with any combination of these keys: Minute, Hour, Day, Weekday, and Month. You must spell out exact values, and if you want multiple schedules you add multiple dictionaries.

👉 Weekday mapping: 0 = Sunday, 1 = Monday, … 6 = Saturday

Every day at 9 AM
```
  Hour9
  Minute0
```

Every Tuesday and Thursday at 6 PM


  
    Weekday2
    Hour18
    Minute0
  
  
    Weekday4
    Hour18
    Minute0

Every weekday (Mon–Fri) at 8:30 AM


  Weekday1Hour8Minute30
  Weekday2Hour8Minute30
  Weekday3Hour8Minute30
  Weekday4Hour8Minute30
  Weekday5Hour8Minute30

Every 2 weeks
There’s no built-in “every 2 weeks” in launchd. You either:
- Use StartInterval=1209600 (14 days in seconds), which repeats from when the job was loaded — but it drifts if the system is asleep or rebooted.
- Or explicitly enumerate the calendar dates you want, using multiple StartCalendarInterval dictionaries. This is verbose, but guarantees alignment with real calendar weeks.

Interval-based
StartInterval runs a job every N seconds, regardless of the calendar. Think of it as a built-in sleep loop.

Example:
```
StartInterval3600
```
→ run every hour (from job load time)

Other controls (modifiers)
These don’t schedule jobs directly, but change how and when they launch.

RunAtLoad → run once immediately when the job is loaded
StartOnMount → trigger when a filesystem is mounted
KeepAlive → restart automatically; can be true or a dictionary with conditions (restart if a path exists, a network comes up, or the process exits unexpectedly)

👉 Launchd’s style is explicit and dictionary-driven: you define exact times or raw intervals, then add flags to control behavior. It’s less expressive than systemd’s OnCalendar (no ranges or modulo like “every 2 weeks”), but tightly integrated into macOS and good enough for most practical scheduling needs.

Troubleshooting launchd jobs

If your job isn’t firing:

Make sure the .plist is in the right folder with the right ownership:
- ~/Library/LaunchAgents/ → per-user jobs (owned by you)
- /Library/LaunchDaemons/ → system-wide jobs (owned by root, mode 644)
Validate the file with plutil -lint myjob.plist to catch XML errors.
Check whether launchd actually loaded it:
launchctl print gui/$(id -u) | grep MyJobLabel
Look at logs for errors or crashes:
log show --style syslog --predicate 'process == "myjob"' --last 1h

👉 Most failures come down to wrong location, wrong ownership, or a typo in the plist.

Key Distinctions

StartInterval / StartCalendarInterval → for cron-style jobs (run once and exit).
KeepAlive → for daemons (stay alive forever, restart if needed).
If you omit both, the job won’t run automatically — you’ll need to start it with launchctl. (see Sockets and WatchPaths for exceptions to this rule) 🔗launchd.plist
In /Library/LaunchDaemons/, always set to a dedicated account instead of running everything as root.

Docs

Canonical references for scheduling on macOS with launchd:

launchd.plist(5) — property list format reference
launchctl(1) — managing jobs from the command line
Apple Developer: Scheduling Timed Jobs with launchd — official guide to launchd daemons, agents, and timed jobs

I've been known to RTFM

Tips & Tricks

Here are a few practical reminders and tools that save headaches when working with systemd and launchd.

Topic	Linux (systemd)	macOS (launchd)
Unit placement	`/etc/systemd/system/` (system-wide) `~/.config/systemd/user/` (per-user)	`/Library/LaunchDaemons/` (system-wide, run as root or ) `~/Library/LaunchAgents/` (per-user)
Unit naming	Basename ties `.service` to `.timer` (e.g. `backup.service` + `backup.timer`).	must be unique. Use reverse-DNS style (`com.user.job`) to avoid collisions.
Validation	`systemd-analyze verify /path/to/unit`	`plutil -lint com.user.job.plist`
Check what’s loaded	`systemctl list-units --type=service --user` `systemctl list-timers --user`	`launchctl list`
Logs / debugging	`journalctl -u myjob.service -e` `journalctl --user -xe`	`log show --predicate 'process == "backup.sh"' --last 1h` or check `StandardOutPath` / `StandardErrorPath`
Force a run	`systemctl start myjob.service`	`launchctl start com.user.job`
Enable at boot	`systemctl enable myjob.service` `systemctl enable myjob.timer`	Jobs in LaunchAgents/LaunchDaemons load automatically; use `launchctl bootstrap` for fine-grained control.

Pro-Tip: Best practices:

Don’t run everything as root. Use User= in systemd or in launchd to assign a dedicated account for daemons.
Validate first. Both systemd-analyze verify and plutil -lint catch typos before you’re scratching your head at runtime.
Check logs early. journalctl and the unified macOS log are your best friends when things don’t behave.
Start manually once. Always systemctl start or launchctl start a job to make sure it works interactively before scheduling it forever.

Links and Stuff

Here are the canonical docs and references worth bookmarking:

systemd:
- systemd.unit(5)
- systemd.service(5)
- systemd.timer(5)
- systemd.time(7) — time spans & calendar expressions
launchd:
- launchd.plist(5)
- launchctl(1)
- Apple’s old but still useful Technical Note TN2083
- Apple Developer: Scheduling Timed Jobs with launchd
GUI helpers (macOS):
I have used these before:
- LaunchControl — full-featured, actively maintained GUI for launchd
- Lingon — simpler, lightweight tool for launchd jobs

Conclusion

That’s it — the basics of Daemonology in Unix-land. We’ve covered how to wrap a script into a managed job, how timers and intervals take the place of cron, and how daemons live under the supervision of systemd or launchd.

Next time you need a script to stick around, restart itself, or wake up on a schedule — you’ll know how to bind it to the system and let the OS do the babysitting.

Got any tips or tricks I missed? Corrections? I’d love to hear about them! feedback@adminjitsu.com

Hugo Boilerplate

Fri, 29 Aug 2025 18:57:12 -0500

Intro

Hugo has such a cheerful, simple logo

After setting up Hugo, in a previous post My Friend Hugo, I kept going — experimenting with the actual writing workflow. Over time I’ve built a set of practices that make writing easier, faster, and more consistent: from my boilerplate.txt snippets and Espanso macros to how I think about alt tags and tactical inline HTML.

You’re welcome, both of you!

🧾 View Other Hugo Posts

Boilerplate and Snippets

Markdown is easy, with a simple syntax that abstracts away complexity and lets you focus on writing. If I had to write this site in pure HTML I’d never attempt long-form content. That simplicity is a big selling point for Hugo as a static site generator — but there are still some sticky bits. Certain Markdown extensions, custom shortcodes, or inline HTML are fiddly to remember.

So like many before me, I keep a crib sheet in a file called BOILERPLATE.txt.
It’s just a plain text file, but it has become my go-to reference: copy-and-paste snippets for the patterns I use over and over. Figure blocks, float-left images, GitHub buttons — all captured once, used consistently forever.

Pro-Tip: Keeping snippets literal in a text file avoids “magic.” You always know exactly what will get pasted in.

Scratch folder

A best practice I’ve settled on (and would repeat if I started fresh) is keeping a scratch/ directory at the root of my Hugo site. It’s ignored by Hugo at build time, so it won’t leak unless I write about it, but it’s a perfect place for experiments: HTML previews of fonts, screenshots, notes, and of course BOILERPLATE.txt itself.

┌──[ forfaxx@shinobi ]:~/codelab/adminjitsu/scratch  (main*)
└─$ ls -l 
-rw-r--r--  adminjitsu-fonts.html
-rw-r--r--  adminjitsu_palette_overview.png
drwxr-xr-x  bin
-rw-r--r--  BOILERPLATE.txt
-rw-r--r--  POST-IDEAS.txt
-rw-r--r--  SCRATCHPAD.txt
-rw-r--r--  Tags and Categories.txt
drwxr-xr-x  WIP archive

Inside bin/ I keep little helper tools I’ve built for the site — see My Friend Hugo for details on scripts like metaclean and tag-audit. I also symlink a couple of general-purpose commands from my dotfiles so I don’t duplicate code between projects. Having them right next to the Hugo content keeps everything tidy and self-contained.

┌──[ forfaxx@shinobi ]:~/codelab/adminjitsu/scratch/bin  (main*)
└─$ ls -l 
drwxr-xr-x  covers
-rw-r--r--  feather-demo.html
-rw-r--r--  feather-icon-demo.html
-rw-r--r--  feather-picker.html
-rw-r--r--  feather-picker.html.old
-rw-r--r--  font-preview.html
-rw-r--r--  font-preview2.html
-rw-r--r--  font-preview3-roboto.html
-rw-r--r--  font-preview4.html
-rwxr-xr-x  gen-bg.py
-rwxr-xr-x  generate-bg-wave.py
-rwxr-xr-x  generate-bg.py
-rwxr-xr-x  pal-preview.py
-rwxr-xr-x  tag-audit.py
-rwxr-xr-x  tag-scan.py
lrwxrwxrwx  metaclean -> ~/codelab/dotfiles/tools/metaclean/metaclean.py
lrwxrwxrwx  sync-adminjitsu.sh -> ~/codelab/dotfiles/bin/sync-adminjitsu.sh

Finally, I keep a Ninja Style-Dojo — a more complete collection of snippets and conventions, with live HTML previews. I publish it on my site for fun, but it could just as easily stay a draft and serve as a private reference. Either way, it’s a handy place to store the raw Markdown and see the rendered results side-by-side in a browser — something I’d definitely set up again on a new site.

Why it works for me

Consistency: BOILERPLATE.txt guarantees my figures, captions, and buttons always look the same.
Speed: Instead of hunting through old posts, I paste from my crib sheet or trigger an Espanso macro.
Safety: Scratch/ is local-only and never published — so I can stash messy drafts, half-baked snippets, and test assets without worry.
Organization: Keeping helper code and snippets inside the project keeps the mental overhead low — everything I need to write and polish a post lives right beside it.

Espanso Macros

Espanso is my free, cross-platform tool of choice for snippets that I can never quite keep in human RAM. (See Espanso and Friends for more detail.) Typing something like :figcenter and having it expand into the following skeleton makes life so much easier

<figure style="text-align:center; margin: 1em auto;">
  <img src="" 
       title=""
       alt="" 
       style="display:block; margin:0 auto; width:min(100%, 600px); height:auto;">
  <figcaption style="font-size: 85%; font-weight: normal; color: #666; line-height:1.4; margin-top:0.4em;">
    
  figcaption>
figure>

Filling that out after triggering a macro is far quicker than retyping or hunting through past posts. My rule of thumb: whenever I catch myself digging through BOILERPLATE.txt or searching old posts too often, that’s my cue to promote it into an Espanso snippet.

I have a few like :mailto, :btn-github, :btn-tag and :author and espanso makes them much easier to use consistently. For an initial rough-draft I sometimes use :lorem to drop a placeholder block like the following:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

I’ve used TextExpander on macOS for years, and it’s definitely the more polished program. But Espanso works, it’s cross-platform, and it’s free. Best of all, it doesn’t force you to tie a literal keylogger to a cloud service — a baffling change that pushed many of us to look elsewhere.

Page Bundles are Where It’s At

This wasn’t obvious to me at first, but the best way I’ve found to structure content in Hugo is by using page bundles. Instead of scattering your Markdown, images, and other assets across different directories, a page bundle keeps everything for a single post together in one folder.

In Hugo, that usually means a directory with an index.md and all its supporting files side-by-side:

content/
└── posts/
    └── hugo-boilerplate/
        ├── index.md
        ├── hugo-logo-wide.svg
        ├── screenshot.png
        └── diagram.jpg

The magic: when you reference an image in your Markdown, Hugo automatically resolves relative paths from the bundle folder. That means you don’t need to manage long paths like /images/2025/08/foo.png — you just drop the asset into the bundle and link it as ![alt](screenshot.png).

Pro-Tip: Page bundles make it natural to keep figures, screenshots, and diagrams right alongside the post they belong to. When you move or archive the post, all its assets come with it.

I wish I’d embraced this earlier — it makes writing image-heavy posts far more portable and self-contained.

I still drop the occasional file in /static when there’s a reason, but page bundles keep the majority of posts tidy and script-friendly.

Leaf vs. Branch Bundles

This was also confusing at first, but now it’s clear:

Leaf bundle → a folder with index.md. Perfect for a single post and its images.
Branch bundle → a folder with _index.md. Used when the directory itself is a section and you want to organize child pages inside it.

For most posts, leaf bundles are the sweet spot: everything neatly wrapped up with its assets. But branch bundles shine when you want to customize sections or taxonomy pages.

Customizing a Tag Page

One practical example of a branch bundle is a taxonomy page. Hugo automatically generates list pages for each taxonomy (like tags or categories) — see the taxonomy docs for the full details. These pages are useful by default, but you can take them further by customizing them with an _index.md.

For example, my Hugo tag has its own logo and introduction at the top as seen here

To make this work, I created an _index.md file in content/tags/hugo/:

---
title: "Hugo"
---

<br>

<p align="center">
  <img src="hugo-logo-wide.svg" 
       alt="Hugo static site generator logo" 
       style="max-width:320px; margin-bottom:0.6em;">
  <br>
p>

**Posts about Hugo** — workflows, scripts, and experiments with the PaperMod theme.  

*Here’s where I collect all my Hugo-related posts. From publishing scripts to styling tricks, these are my experiments in making Hugo work like a Unix-first tool.*

Pro-Tip: Any taxonomy term (tags, categories, series, etc.) can be customized this way. Just create a folder under content/// and drop in an _index.md. Hugo merges your intro with the generated list of posts.

The Art of Alt Text

Markdown images are dead simple: copy the file into your page bundle and drop in

![image](image.jpg)

That’s fine for quick drafts, but limited. I’ve standardized on using HTML5

blocks. They’re more verbose, but Espanso and BOILERPLATE.txt make them trivial to insert. One big advantage is how naturally they support alt text and captions.

<figure style="float:left; margin:0 1rem 1rem 0; width:clamp(260px, 45%, 200px);">
  <img src="blue-ninja2.png" 
       title="a title should appear when you hover over an image in your browser"
       alt="A little 8-bit arcade-style ninja in blue, mid-kick. Playful tone." 
       style="display:block; width:100%; height:auto;">
  <figcaption style="font-size:85%; color:#666; line-height:1.4; margin-top:0.4em;">
    insert caption here
figcaption>
figure>

The alt text here is:
“A little 8-bit arcade-style ninja in blue, mid-kick. Playful tone.”

That’s short, descriptive, and conveys both content and feel.

Pro-tip: “When you float an image (float:left or float:right), add

immediately after the last paragraph you want to flow alongside it. That ends the float so the next block of text starts below the image instead of wrapping around it.”

Why Alt Text Matters

Accessibility → screen readers literally speak the alt text aloud. For some humans, the alt text is the image.
SEO & indexing → search engines rely on it to understand your images.
Future-you → when you’re skimming raw Markdown years later, it’s your memory cue for what the image was.

💡 Think of alt text as radio commentary for your images: short, vivid, and enough for someone who can’t see it to still get the point.

How I Write Mine

Concise → don’t narrate everything, just the essence.
Tone → if the image is playful, somber, or technical, hint at that.
Context → what’s relevant in this post, not in general.

`alt` vs. `title` vs. `figcaption`

alt → mandatory description for accessibility & indexing. Invisible unless needed.
title → optional tooltip when you hover (not read by all screen readers). Best kept short.
figcaption → visible, human-facing caption under the image.

Examples

Good:

alt="Diagram of a TCP handshake with SYN, SYN-ACK, and ACK arrows"
alt="Screenshot of Hugo’s PaperMod theme with sidebar expanded"
alt="Cheesy photo of a 90s era hacker in a leather outfit with oversized, early VR goggles"

Bad:

alt="image123.png" (useless)
alt="screenshot" (too vague)
alt="This is a picture showing how computers work and it is very detailed and you should read the whole post to understand it" (too long and redundant)

Writing Workflow

Over the past months I’ve stumbled into a workflow that works well for me. It’s nothing fancy, but it keeps me moving from raw ideas to finished posts without getting stuck in the weeds:

Brainstorm
I start with a physical journal on my desk — just date, time, and whatever’s on my mind. Tasks, quotes, fragments of ideas. If something excites me, it tends to show up on multiple days. Flipping back through recent pages often sparks connections. Sometimes I’ll highlight passages that feel like seeds for posts.
Braindump / First Draft
When an idea is ready, I open a new leaf bundle in Hugo and start throwing content at the page. Sections, half-sentences, “insert brilliant analysis here.” Markdown helps because the draft already has structure — headers turn into an outline as I go. The point isn’t polish, just getting a skeleton that makes sense as a document.
Second Draft
Here’s where the real work happens. I fill in the placeholders: research, repro steps, screenshots, code snippets. This is also where I fix flow problems and cut the junk. The second draft is “basically done” but still rough — good bones, not yet polished.
Final Draft / Polish & Publish
Last step is to read it top to bottom as a reader would. Does it sound right? Are the facts straight? I check typos and grammar (still hunting for the perfect VS Code spellchecker) and make sure my snippets render correctly. When it feels solid, I fire up my publish script and call it a day. This is usually the point where I realize I made a glaring error despite the previous steps and polish some more.

This workflow isn’t revolutionary — brainstorm, draft, revise, polish — but the combination of Hugo + Markdown + my little tooling stack makes it doable. The tech gets out of the way so the writing can happen. That’s already hard enough without having to fight the platform.

Honestly, it feels closer to making a DIY punk zine than building a “traditional” website. That reminds me of what I liked about OS X Server’s old Wiki service: it made high-quality technical docs easy to produce without wrestling with the stack. Hugo has the same spirit, but with more power under the hood — full access to HTML, CSS, JS, and theming when I need it.

Tactical Inline HTML

Markdown gets you 90% of the way, but sometimes you need finer control — a

block, a

wrapper, a styled . That’s where inline HTML comes in.

By default Hugo uses the Goldmark Markdown processor, which escapes raw HTML unless you tell it otherwise. To enable inline HTML, set this in your site config:

[markup.goldmark.renderer]
unsafe = true

Now your raw HTML will render directly in posts.

Caveats

Trust yourself only: don’t paste untrusted HTML snippets (security risk).
Keep it minimal: inline HTML is great for captions, figures, or buttons — but if you find yourself nesting
s like it’s 2003, consider moving it into a shortcode or a partial.
Test on mobile: what looks good in desktop Chrome might break layout in a narrow column.

Examples

<span style="color:#7D83B9;">inline highlightspan>

<p style="text-align:center;">
  <a href="/tags/hugo" class="button">🧾 View Other Hugo Postsa>
p>

Inline HTML is a sharp tool: overdo it and your Markdown turns messy, but sprinkled tactically it can save you from endless CSS hacks or theme surgery.

Conclusion

Hugo + Markdown has been a great excuse to tinker, automate, and—most importantly—actually write. That’s my story, and I’m sticking to it.

If you’ve read this far, thanks for stopping by. I hope some of these odd little practices spark ideas for your own setup.

🧾 View Other Hugo Posts

Have a tip or trick? Did I miss something? I’d love to hear about it! Email me: feedback@adminjitsu.com

Oddball Files

Thu, 28 Aug 2025 14:05:09 -0500

Everything is a file

UNIX is designed around a simple concept: everything is a file. But the ones I enjoy most are the oddballs — special files that do curious things yet can still be poked, prodded, and cat-ed like any other. Let’s explore a few of them.

no wizards were harmed in the making of this post

File Types

“Some stirring may be necessary to achieve proper consistency.”
— fortune(6)

The phrase everything is a file isn’t just a slogan — it’s how UNIX presents nearly every interface:

Regular files — your documents, configs, logs.
Directories — just special files mapping names to inodes.
Character devices — like /dev/null or /dev/tty, providing byte streams to hardware or virtual drivers.
Block devices — like /dev/sda (a disk), where the kernel maps file I/O into fixed-size blocks.
Sockets — files that represent network endpoints (check /var/run/ on a Unixy system).
Pipes (FIFOs) — files that connect processes (mkfifo makes one).
Procfs/sysfs entries — “files” that show you kernel state when you cat them.

That’s why tools like cat, echo, or dd work on such a wild variety of things — whether you’re streaming bytes from a terminal, a pseudo-random generator, or the kernel itself.

└─$ ls -al /dev/null
crw-rw-rw- 1 root root 1,3 Aug 16 16:00 /dev/null
#           ^    ^    ^  ^^^
#           |    |    |  major,minor device numbers
#           |    |    group
#           |    owner
#           hardlink count
#character device


# A block device: your first disk
└─$ ls -l /dev/sda
brw-rw---- 1 root disk 8,0 Aug 29 10:00 /dev/sda
# b = block device

# A directory: just another kind of file
└─$ ls -ld /etc
drwxr-xr-x 123 root root 4096 Aug 29 09:59 /etc
# d = directory

# A FIFO (named pipe): file that connects processes
└─$ mkfifo mypipe && ls -l mypipe
prw-r--r-- 1 kevin kevin 0 Aug 29 10:01 mypipe
# p = pipe

# A socket: file that represents a communication endpoint
└─$ ls -l /var/run/docker.sock
srw-rw---- 1 root docker 0 Aug 29 10:00 /var/run/docker.sock
# s = socket

Let’s explore!

`/dev/null` — The Bit Bucket

A special file that represents nothing. Writing to /dev/null discards data forever; reading it returns immediate EOF.

In the upstream Linux kernel tree (Linus’s repo), /dev/null lives in drivers/char/mem.c. The device’s behavior is wired through the file_operations table:

Browse: drivers/char/mem.c (mainline)

/* ... inside drivers/char/mem.c ... */
static ssize_t read_null(struct file *file, char __user *buf,
                         size_t count, loff_t *ppos)
{
    return 0; /* EOF immediately */
}

static ssize_t write_null(struct file *file, const char __user *buf,
                          size_t count, loff_t *ppos)
{
    return count; /* pretend we wrote everything */
}

static const struct file_operations null_fops = {
    .read  = read_null,
    .write = write_null,
    /* other ops may be present depending on kernel version */
};

Why it matters

Because /dev/null is “just a file,” any tool that can write to a file can be silenced or stress-tested without special flags.

Practical tricks

Pro-Tip: Silence everything (stdout and stderr):

some-noisy-tool > /dev/null 2>&1

Measure syscall overhead (it’ll still touch the kernel fast path):

strace -c cat /dev/null

High-speed “write” benchmark (no disk I/O happens):

dd if=/dev/zero of=/dev/null bs=64M count=128 status=progress

Drop output in pipelines without branching:

make 2>build.err > /dev/null

Pretend-success sink in scripts (command returns 0 if the last stage does):

generate-stats | tee /dev/null

Odds & ends

Historically, /dev/null is a character device (major 1, minor varies by table) implemented by the kernel’s “memory” driver alongside /dev/zero, /dev/full, and friends.
The exact function names around null_fops may differ slightly across kernel versions (e.g., llseek/splice_write entries); the essence remains: reads return 0, writes report success.

Canonical source: drivers/char/mem.c in Linus’s tree

Some detailed explanations I like

`/dev/zero` — The Infinite Stream of Zeros

Need endless null bytes? /dev/zero is your friend. Every read returns \0 forever.

Why use it?

Create blank disk images or memory files.
Initialize storage with a known pattern.
Quick way to generate padding.

Examples:

# Create a 100 MB blank file
dd if=/dev/zero of=blank.img bs=1M count=100

# Wipe a disk partition with zeros (careful!)
dd if=/dev/zero of=/dev/sdX bs=1M status=progress

/dev/zero implementation:
drivers/char/mem.c — zero_fops

`/dev/full` — The “Disk Full” Device

The counterpart to the zero device: /dev/full rejects every write with ENOSPC (“No space left on device”).
Reads return zeros (like /dev/zero), but writes always fail.

Why use it?

Test how software behaves when disks are full without filling up a disk for real.
Ensure your error handling doesn’t silently corrupt data.
Force applications to trigger out-of-space recovery paths.

Examples:

# Simulate a write failure
echo test > /dev/full
# bash: echo: write error: No space left on device

# Pipe data into /dev/full to trigger error handling in a script
tar cf - /etc | cat > /dev/full

/dev/full implementation:
drivers/char/mem.c — full_fops

`/dev/random` and `/dev/urandom` — Entropy on Tap

Both /dev/random and /dev/urandom draw from the kernel’s cryptographic random number generator, which is constantly fed with entropy from noisy hardware events: interrupt timing jitter, disk and network latencies, keyboard/mouse input, and—if available—CPU hardware RNG instructions like Intel’s RDRAND or RDSEED. These unpredictable signals are mixed into a pool, then stretched into high-quality random data with a cryptographic PRNG.

There are actually two “random” devices on Linux:

/dev/random historically blocks if the kernel’s entropy pool is low. On modern Linux (5.6+), it only blocks until the RNG is fully initialized (very early at boot).
/dev/urandom never blocks, stretching whatever entropy is available.
Since Linux 5.6, both use the same ChaCha20-based core, with /dev/random acting mostly as a “blocking front end.”

Source code

Both are implemented in drivers/char/random.c in the mainline tree:
drivers/char/random.c (mainline)

Key structures:

random_fops (for /dev/random)
urandom_fops (for /dev/urandom)

/* snippet from drivers/char/random.c (modern kernels) */
const struct file_operations random_fops = {
    .read_iter   = random_read_iter,
    .write_iter  = random_write_iter,
    .poll        = random_poll,
    .unlocked_ioctl = random_ioctl,
    .compat_ioctl   = compat_ptr_ioctl,
    .fasync      = random_fasync,
    .llseek      = noop_llseek,
    .splice_read = copy_splice_read,
    .splice_write= iter_file_splice_write,
};

const struct file_operations urandom_fops = {
    .read_iter   = urandom_read_iter,
    .write_iter  = random_write_iter, /* same writer path */
    .unlocked_ioctl = random_ioctl,
    .fasync      = random_fasync,
    .llseek      = noop_llseek,
    .splice_read = copy_splice_read,
    .splice_write= iter_file_splice_write,
};

Behind these fops (file operations) are the kernel’s cryptographic RNG (Random Number Generator) functions, feeding data from entropy pools mixed with device interrupts, timings, and other noise sources.

Why use it?

Secure key generation (ssh-keygen, gpg, etc).
Random test data (head -c 16 /dev/urandom).
Checking system entropy levels via /proc/sys/kernel/random/entropy_avail.

Examples:

# Generate a 16-character password
tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 16 ; echo

# Check entropy pool size
cat /proc/sys/kernel/random/entropy_avail
# Note: on modern kernels this usually sits at 256 by design; it doesn’t mean “low entropy.”


# Grab 32 random bytes as hex
od -An -tx1 -N32 /dev/random

# 20 random digits (0–9)
tr -dc '0-9' < /dev/urandom | head -c 20 ; echo

# 20 random letters (A–Z, a–z)
tr -dc 'A-Za-z' < /dev/urandom | head -c 20 ; echo

# simulate a 6-sided die roll
echo $(( ( $(od -An -N2 -i /dev/urandom) % 6 ) + 1 ))

Other Oddballs in `/dev`

Not everything in /dev is as widely recognized as /dev/null or /dev/urandom. Many entries serve specialized purposes: some expose useful system interfaces, others exist mainly for testing or debugging, and a few can be hazardous if misused.

`/dev/tty` — Your Terminal

Always points to your controlling terminal.

echo "Hello from script land" > /dev/tty

Handy when stdout is redirected and you still want to talk to the user.

`/dev/pts/*` — Pseudo Terminals

Created dynamically for each terminal session (SSH, tmux, etc.).

echo "Wake up, Neo..." > /dev/pts/2

Yes, you can write text directly into someone’s session—if you have permission.
Pseudo-terminal devices are owned by the session user and typically mode rw--w---- (0620), group tty. That means only the owner (or root) can write to it.

`/dev/console` — The Big Screen

The system console. Kernel boot logs and critical errors go here.
You can also send your own (assuming you are root):

echo "System maintenance in 5 minutes" | sudo tee /dev/console

An example of this in the wild can be seen when scheduling a reboot with
sudo shutdown -r +10. Under the hood, shutdown calls wall(1) (or an equivalent) to broadcast a warning message. That message is written both to /dev/console and to all connected TTYs.

This behavior is a legacy of the multi-user era, when it was essential to notify other logged-in users before rebooting or performing disruptive maintenance. Even today, it’s a practical demonstration of how the console and TTY devices are just files that can be written to.

`/dev/kmsg` — Talk to the Kernel Log

Write straight into dmesg from userspace:

echo "Injected log message from userspace" | sudo tee /dev/kmsg

Great for debugging custom scripts or testing log monitoring (as root) although logger(1) is the more portable and cleaner alternative.

`/dev/mem` and `/dev/kmem` — Raw Memory

Give direct access to physical and kernel virtual memory.
Mostly disabled on modern systems for security. Historically used for debuggers, kernel hacking… and crashing your system.

⚠️ Danger: one wrong write and the kernel panics.

`/dev/loop*` — Loopback Block Devices

Loop devices let you treat an ordinary file as if it were a real disk.
Anything you write into the mounted filesystem is actually stored inside that file, with the kernel handling the translation.

# Create a 10MB blank file
dd if=/dev/zero of=disk.img bs=1M count=10

# Map to a loop device and make an ext4 filesystem
sudo losetup /dev/loop0 disk.img
sudo mkfs.ext4 /dev/loop0

# Mount, write some data, then unmount
sudo mount /dev/loop0 /mnt
echo "hello loopback" | sudo tee /mnt/hello.txt
sudo umount /mnt
sudo losetup -d /dev/loop0

At this point, disk.img is an ext4 filesystem in a file.
If you peek inside with hexdump or strings, you can see its structure:

# Look for ext4 magic numbers
hexdump -C disk.img | grep '53 ef'
# Typical output:
# 00000400  53 ef 01 00 ...

# Or scan for human-readable bits
strings disk.img | head
# Output might show journal headers, superblock info, etc.

Reattach it to a loop device later and your hello.txt will still be there.
This is the same trick used for ISO files, qcow2 VM images, and container layers.

`/dev/net/tun` — Virtual Networking

The TUN/TAP clone device. Userland programs open /dev/net/tun and use an ioctl(TUNSETIFF) to request either:

TUN (layer-3, IP packets)
TAP (layer-2, Ethernet frames)

Commonly used by VPNs like WireGuard and OpenVPN, and by virtualization tools that need virtual NICs.
(Docker’s default networking uses veth pairs and bridges, not TUN/TAP.)

`/dev/shm` — Shared Memory

Technically a tmpfs mounted under /dev. It’s RAM-backed storage, cleared on reboot.

echo "fast scratch data" > /dev/shm/test.txt
cat /dev/shm/test.txt

Pro-Tip: /dev/shm is like a built-in RAM disk for temp files.
Many tools honor the TMPDIR variable, so you can speed them up by pointing it here:
# Run tests with fast temp storage in RAM
TMPDIR=/dev/shm pytest -q

# Or give SQLite an all-RAM temp area
SQLITE_TMPDIR=/dev/shm sqlite3 mydb.sqlite
Great for test runs, builds, and scratch data that doesn’t need to survive a reboot.

`/proc` — The Kernel’s Diary

Unlike /dev, which is about devices, /proc is a virtual filesystem exposing kernel internals.
Files here are interfaces into live kernel state, assembled dynamically whenever you query them.

Every process gets its own subdirectory (/proc/), plus global kernel stats.

The /proc filesystem implementation lives in the Linux kernel tree under:

🔗 fs/proc/ — Linux source (Elixir cross-referencer)

Common tricks

Why use it?

Inspect process details without ps or top.
Read kernel parameters on the fly.
Script system monitoring without extra tools.

Examples:

# Show command line of your shell, where $$ is a special variable that expands to the current shell's process ID (PID)
cat /proc/$$/cmdline

# Show process status (fields like State, Threads, Memory), where 12345 is any running PID
cat /proc/12345/status | head

# System uptime (in seconds)
awk '{print $1}' /proc/uptime

# Kernel version
cat /proc/version

# List all loaded modules
cat /proc/modules

Tweakable knobs

Many settings in /proc/sys are writable, same as sysctl.
This is the interface Linux exposes for runtime performance tuning, though most users never need to touch it — the kernel ships with sensible defaults (often tuned differently between server and desktop distributions).

# Enable IPv4 forwarding (required for routers, VPNs, containers)
echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward

# Check current swappiness (0–100, default ~60)
cat /proc/sys/vm/swappiness
# Lower = keep apps in RAM longer, swap only when memory is tight
# Higher = free RAM sooner, keep larger disk cache

# Set swappiness to 10 (more "desktop-friendly" behavior)
echo 10 | sudo tee /proc/sys/vm/swappiness

# Adjust maximum number of open file descriptors
cat /proc/sys/fs/file-max
echo 2097152 | sudo tee /proc/sys/fs/file-max

# Tune TCP keepalive time (seconds of idle before probes are sent)
cat /proc/sys/net/ipv4/tcp_keepalive_time
echo 300 | sudo tee /proc/sys/net/ipv4/tcp_keepalive_time

📚 Where to find them all

The full catalog of tunables lives under /proc/sys, grouped by subsystem (vm/, net/, kernel/, fs/, …).

Canonical documentation lives in the kernel source tree:

Documentation/admin-guide/sysctl/
Each subsystem has its own file, e.g.
- Documentation/admin-guide/sysctl/vm.rst
- Documentation/admin-guide/sysctl/net.rst

⚠️ Changes made directly in /proc/sys last only until reboot.
To make them permanent, set them via sysctl (e.g. sysctl -w vm.swappiness=10) and add entries in /etc/sysctl.conf or drop-in files under /etc/sysctl.d/.

Oddities worth knowing

Some /proc files are especially handy to peek at directly:

/proc/cpuinfo — CPU model, flags, and per-core info.
```
grep 'model name' /proc/cpuinfo | uniq
```
(What lscpu uses under the hood.)
/proc/meminfo — granular memory stats (RAM, swap, buffers, caches).
```
head -5 /proc/meminfo
```
(Basis for the free command.)
/proc/loadavg — load averages as shown by uptime. First three fields are 1, 5, and 15-minute averages.
```
cat /proc/loadavg
```
/proc/filesystems — list of supported filesystem types.
```
cat /proc/filesystems | column
```
(Prefixed with nodev if no block device is required.)
/proc/sysrq-trigger — write magic letters here to invoke SysRq kernel actions.
```
echo b | sudo tee /proc/sysrq-trigger   # reboot immediately
echo m | sudo tee /proc/sysrq-trigger   # dump memory info to dmesg
```
⚠️ Dangerous if you don’t know the key sequences — it’s a raw escape hatch.

Source code

Implemented in the kernel’s fs/proc/ directory:

fs/proc/base.c — per-process files like /proc//status.
fs/proc/proc_sysctl.c — the /proc/sys interface.
Documentation/filesystems/proc.rst — canonical docs in-tree.

Bonus Round: BSD/macOS `sysctl`

“It’s more fun to be a pirate than to join the navy.”
— Steve Jobs

While Linux uses /proc, the BSD family (FreeBSD, NetBSD, OpenBSD) and Darwin/macOS expose kernel state through a sysctl tree.

At the user level you call the sysctl(3) function, whose prototype is:

int sysctl(int *name, u_int namelen,
           void *oldp, size_t *oldlenp,
           void *newp, size_t newlen);

name is an integer array describing the MIB path (e.g. { CTL_HW, HW_NCPU }).
oldp / oldlenp point to a buffer for the current value.
newp / newlen optionally provide a new value to set.

Inside the kernel, nodes are registered in a tree of struct sysctl_oid objects (FreeBSD/macOS). Each OID describes a tunable or info node (name, type, handler function) that supplies the value or applies a change.

Example: BSD/macOS sysctl calls in C

int mib[2];
size_t len;
int ncpu;

mib[0] = CTL_HW;
mib[1] = HW_NCPU;
len = sizeof(ncpu);

if (sysctl(mib, 2, &ncpu, &len, NULL, 0) == -1)
    perror("sysctl");

printf("CPUs: %d\n", ncpu);

That’s the C version of what sysctl hw.ncpu does on the shell.

On BSD/macOS you can also use the convenience wrapper sysctlbyname(3):

int ncpu;
size_t len = sizeof(ncpu);

if (sysctlbyname("hw.ncpu", &ncpu, &len, NULL, 0) == -1)
    perror("sysctlbyname");

printf("CPUs: %d\n", ncpu);

Practical macOS examples (CLI)

# Show number of CPU cores
sysctl hw.ncpu

# Show total RAM (in bytes)
sysctl hw.memsize

# Kernel version and build string
sysctl kern.version

# Boot time (seconds since epoch + human-readable date)
sysctl kern.boottime

# Current max files limit
sysctl kern.maxfiles

# Raise max files (temporary, until reboot)
sudo sysctl -w kern.maxfiles=65536

💡 On macOS, many performance tunables live under kern.*, hw.*, and net.*. Like Linux /proc/sys, changes with sysctl -w are not persistent — they reset on reboot unless set via launchd plist or sysctl config mechanisms.

Unlike on Linux, /etc/sysctl.conf is ignored. Use a LaunchDaemon or a startup script instead:

For reference:

📖 sysctl(3) man page
🗂️ Darwin/XNU source tree — kern_sysctl.c and headers like , , define the MIBs.

Conclusion

I hope you enjoyed this quick tour of some of the more fascinating bits of the Unix filesystem. It’s fun to think about the oddballs all together rather than as isolated footnotes. Unix has a lot of special files—but the beauty is that they’re still just files.

Have a favorite weird Unix virtual file? Something I left out? I’d love to hear about it!
Email me: feedback@adminjitsu.com

SSH-Fu

Thu, 28 Aug 2025 06:44:27 -0500

Intro

SSH isn’t just about logging in remotely — once you’ve got keys, configs, and an agent in place, it opens the door to a whole arsenal of powerful tricks.

You can run commands remotely, mount filesystems, tunnel services, and even bend network paths to your will.

SSH can be mind-bending at times — but only because it’s incredibly powerful
Image © Paramount / CBS

This guide is about the fun stuff — the SSH-Fu that turns everyday tasks into smooth one-liners and clever shortcuts. Nothing arcane, just the practical tricks that make life as an admin easier (and maybe a little cooler).

We’ll cover:

Running commands and scripts over SSH.
Multiplexing and jump hosts.
Local, remote, and dynamic tunnels.
SSHFS mounts and fstab auto-mounts.
File transfers and syncs.
Debugging connections like a pro.

Think of this as an “advanced field manual” — fast, useful, and battle-tested.

If you need help setting up SSH you might want to take a look at my companion post:

SSH Setup Guide

Running Commands Over SSH (and Handling Quotes)

Sometimes you don’t need a full shell — you just want to run one command remotely.
This is one of the most useful (and often confusing) SSH tricks, especially with quoting.

The Basics

ssh new-server 'uptime'

Opens a connection, runs uptime, then exits.
Anything in quotes is executed on the remote host.

With Arguments

ssh new-server 'ls -lah /var/log'

Notice the single quotes — they make sure the remote shell interprets the flags, not your local one.

Mixing Local and Remote Expansion

Good: let remote expand:
```
ssh new-server 'echo $HOME'
```
→ prints the remote user’s home directory.
Bad: if you forget quotes:
```
ssh new-server echo $HOME
```
→ expands $HOME locally, and passes the value to the remote.

Escaping Quotes

If your command needs quotes inside it, escape them:

ssh new-server "echo 'Hello from $(hostname)'"

Outer " let you put ' inside safely.
$(hostname) is expanded on the remote host.

Running a Script Inline

You can pipe a local script to run on the remote side:

cat script.sh | ssh new-server 'bash -s -- arg1 arg2'

bash -s -- tells the remote bash to read from stdin.
arg1 arg2 are passed as $1 $2 to the script.

Copy-and-Run (one-liner deployments)

ssh new-server 'mkdir -p ~/deploy && tar xzf - -C ~/deploy' < site.tar.gz

< site.tar.gz feeds your local tarball into the remote tar command.
Great for quick deployments without scp/rsync.

Pro Tip: Debug Your Quoting

If something looks wrong, echo the command string first:

ssh new-server 'echo "Hello, world"'

Or crank up verbosity:

ssh -v new-server 'echo "debugging quotes"'

Bottom line:

Wrap remote commands in quotes.
Single quotes ' ' prevent local expansion.
Double quotes " " allow mixing variables carefully.
If in doubt, escape inner quotes or just write a quick script and pipe it over.

SSHFS: Mount Remote Files Like They’re Local

Sometimes you don’t want to scp files back and forth — you just want to work in place as if the remote filesystem were part of your machine.
That’s what SSHFS (SSH Filesystem) gives you: a way to mount a remote directory over SSH.

Mount a Remote Directory

sshfs forfaxx@new-server.darkstar.home:/var/www ~/mnt/www

Now ~/mnt/www on your machine shows the contents of /var/www on new-server.
You can ls, cd, vim, or even use GUI apps on those files like they were local.

Unmount It

fusermount -u ~/mnt/www      # Linux
umount ~/mnt/www             # macOS / BSD

Why Use It?

Edit remote config files with your local editor.
Drag-and-drop files in your GUI file manager.
Script against a remote directory without copying.

Performance Notes

It’s built on FUSE, so performance depends on network latency.
Great for light editing, browsing logs, or quick fixes.
Not ideal for heavy I/O workloads (databases, compiles, large builds).

Auto-Mount with `/etc/fstab`

You can make an SSHFS mount persistent by adding an entry in /etc/fstab.
This way it mounts automatically at boot (or on demand with mount).

Example line:

forfaxx@new-server.darkstar.home:/var/www  /mnt/www  fuse.sshfs  defaults,_netdev,IdentityFile=/home/forfaxx/.ssh/id_ed25519,allow_other,uid=1000,gid=1000  0  0

Breakdown:

forfaxx@new-server.darkstar.home:/var/www → remote path.
/mnt/www → local mount point (must exist).
fuse.sshfs → tells fstab to use SSHFS via FUSE.
defaults,_netdev → wait for network before mounting.
IdentityFile=… → path to your private key.
allow_other → let other local users access it (optional).
uid=1000,gid=1000 → map ownership to your local user/group.

Mount/Unmount

After adding it, you can run:

sudo mount /mnt/www
sudo umount /mnt/www

Pro-Tip: test the sshfs command manually first to confirm it works before editing /etc/fstab. A typo there can slow down boot.

Pro-Tip: Combine sshfs with your ~/.ssh/config shortcuts, and you can mount complex paths with one short command.

SSH Tips & Tricks

Once the basics are set — keys, config, agent — you can unlock a bunch of quality-of-life and power-user moves. These are the ones worth knowing.

Multiplexing: Instant SSH

Instead of re-negotiating crypto every time, reuse a single connection.

In ~/.ssh/config:

Host *
  ControlMaster auto
  ControlPath ~/.ssh/cm-%r@%h:%p
  ControlPersist 10m

Now:

ssh new-server        # open one shell
scp file new-server:/tmp/   # reuses same connection, no delay

Pro-Tip: If you hit “path too long for UNIX socket,” use %C (a hash of the host/port) instead:



---
### Jump Hosts: Hop Cleanly  

Sometimes the machine you need isn’t directly reachable — it sits on a private subnet — but there’s a “middleman” you *can* reach, often called a **bastion host**. Instead of logging into the bastion and then hopping again manually, `ProxyJump` lets SSH handle it in one clean step.  

It feels a little cinematic — like Elliot in *Mr. Robot* or “Zero Cool” in *Hackers*, bouncing through a box to slip deeper into the network. It’s not an everyday trick, but worth keeping in your back pocket for those tricky environments.  

```bash
ssh -J bastion new-server

Config version:

Host new-server
  HostName new-server.darkstar.home
  User forfaxx
  ProxyJump bastion

And yes, you can chain multiple hops if you are so inclined:

ssh -J bastion1,bastion2 target

Local & Remote Port Forwards

I have used SSH tunnels many times and it still hurts my brain a little.

Think of an SSH tunnel as a teleport pad for TCP: you open a port on one side, step in locally, and come out on the other side.
The confusing part is remembering which side you step into.
Rule of thumb: you always connect to the side you wrote first.

Local forward (-L) — step in here, come out there

ssh -L 8443:127.0.0.1:443 new-server

You connect to localhost:8443 on your machine.
SSH carries it to 127.0.0.1:443 on new-server.
Example: open https://localhost:8443 in your browser → you’re really talking to new-server’s HTTPS service.

Remote forward (-R) — step in there, come out here

ssh -R 9000:127.0.0.1:3000 new-server

On new-server, connect to localhost:9000.
SSH carries it back to 127.0.0.1:3000 on your machine.
Example: from new-server, curl http://127.0.0.1:9000 → hits your app running locally on port 3000.

Why use this?

Because sometimes the door you need is locked:

A service only listens on loopback.
A firewall blocks it.
You want traffic encrypted over SSH.

Port forwarding is your keyhole.

SOCKS Proxy: Poor Man’s VPN

ssh -D 1080 new-server

Then point your browser’s SOCKS proxy to localhost:1080.

Pro-Tip: Pair ssh -D with Firefox’s “Proxy DNS when using SOCKS v5” setting to tunnel DNS lookups too.

File Transfers Over SSH

Copying files is one of the most common SSH tasks. Here are the main tools and when to reach for them:

# Copy local → remote (quick & dirty)
scp -r ./site new-server:~/deploy/

# Copy remote → local
scp new-server:/var/log/nginx/error.log ./error.log

# Efficient sync (resume, skip unchanged files)
rsync -avz --progress -e ssh ./public/ new-server:~/www/public/

scp → simple, built-in, works everywhere. Great for one-offs.
rsync → faster for large trees, resumes interrupted transfers, only sends differences.

Pro-Tip: This feels like a cheat-code but with the -3 switch, you can copy files between two remote machines using yours as a sort of traffic cop to facilitate, all without logging in anywhere.

# Copy from hostA → hostB via your local machine
scp -3 user@hostA:/var/log/syslog user@hostB:/tmp/syslog

Data flows through your client (not directly host-to-host).
Still encrypted end-to-end (since both legs use SSH).
Useful when hosts can’t talk to each other directly, but you can reach both.

Note: This moves files via your local bandwidth. If the file is huge, your network is the bottleneck. But for config snippets, logs, or small dumps, it’s insanely handy.

Using `sftp` (interactive or scripted)

For more controlled transfers, SSH comes with sftp:

sftp new-server
sftp> put site.tar.gz /tmp/
sftp> get /var/log/nginx/access.log ./access.log
sftp> exit

Looks/feels like FTP, but runs over SSH.
Supports tab completion, ls, cd, and pwd.
Batch mode makes it scriptable:

sftp -b - new-server <<'EOF'
put site.tar.gz /tmp/
get /var/log/nginx/error.log ./error.log
EOF

Pro-Tip: For recurring jobs, use rsync or scripted sftp — they’re more efficient and reliable than scp, which OpenSSH now treats as legacy.

Quick Host Hygiene

# Check fingerprint of a key
ssh-keygen -lf ~/.ssh/id_ed25519.pub

# Derive pubkey from private key
ssh-keygen -y -f ~/.ssh/id_ed25519

# Remove stale known_hosts entry
ssh-keygen -R new-server.darkstar.home

Debug Like a Pro

ssh -v new-server

or crank it up:

ssh -vvv new-server

Tells you exactly why a connection/auth is failing.

Using `-t` to Run Remote Programs Like They’re Local

Normally when you use ssh user@host 'command', SSH treats it like a non-interactive one-shot. That works great for ls or uptime, but it falls apart if the program expects a terminal — like vim, top, or htop.

That’s where the -t flag comes in: it forces SSH to allocate a pseudo-TTY so the remote program thinks it’s running in a real terminal. Suddenly, you can run interactive apps on the remote side as if they were local.

# Edit a config file remotely
ssh -t new-server 'vim /etc/nginx/nginx.conf'

# Run interactive process monitors
ssh -t new-server htop
ssh -t new-server 'sudo journalctl -f'

If you need to hop through sudo or other programs that strip the TTY, you can double up:

ssh -tt new-server 'sudo vim /etc/hosts'

It’s a tiny switch, but it unlocks a ton of everyday tricks. No more half-baked redirections — just straight into your remote Vim, top, or less session like you’re sitting at the machine.

Pro-Tip: Combine -t with ProxyJump or multiplexing and you can pop open an editor on a deep-in-the-network host in a single smooth one-liner.

Using SSH in Scripts (Safe, Non-Interactive Patterns)

Once your logins are safe and seamless (keys + agent), SSH becomes a rock-solid automation primitive. A few rules I’ve found to make it reliable in scripts:

Never prompt: force non-interactive behavior.
Pin host keys: avoid TOFU surprises in CI.
Propagate failures: treat remote errors as errors.

Recommended flags

-o BatchMode=yes → fail immediately if auth would prompt.
-o StrictHostKeyChecking=yes → refuse unknown/changed hosts.
-o ConnectTimeout=5 → don’t hang forever.
(Optional CI) -o UserKnownHostsFile=/path/known_hosts → use a pinned file.

One-liner pattern

ssh -o BatchMode=yes -o StrictHostKeyChecking=yes new-server 'sudo systemctl restart nginx'

Multi-line remote script (here-doc)

ssh -o BatchMode=yes new-server 'bash -s' <<'REMOTE'
set -euo pipefail
echo "Deploying…"
mkdir -p ~/app
tar xzf - -C ~/app
systemctl --user restart app.service
REMOTE
# (feed tar on stdin if needed: tar czf - . | ssh … 'bash -s')

Copy-and-run (fast “deploy without scp”)

tar czf - . | ssh -o BatchMode=yes new-server 'mkdir -p ~/deploy && tar xzf - -C ~/deploy && ~/deploy/install.sh'

iperfer: One-Command iperf3 test over SSH

A concrete example of the copy-and-run pattern is my tool iperfer: it uses SSH to spin up an iperf3 server remotely, runs the client locally, then tears everything down in one go.

🚀 iperfer: one-command iperf3 over SSH

Conclusion

SSH is more than ssh user@host. With a few well-placed tricks, you’ll connect faster, hop cleanly through networks, tunnel like a pro, and stop tripping over key headaches.

Got a sweet SSH tip, trick, or hack to share?
I’d love to hear it: feedback@adminjitsu.com

SSH Setup Guide

Thu, 28 Aug 2025 00:08:20 -0500

Intro

SSH is one of those indispensible tools that quietly becomes the backbone of your entire setup. It’s how you log in, move files, hop between machines, and even tunnel services. Getting it set up correctly is important especially since you tend not to do these steps very often.

Set up corectly, SSH is like a tank—tough, rugged, and dependable

But here’s the thing: SSH is deceptively simple on the surface—type ssh user@host and you’re in—yet maddeningly complex once you start juggling multiple machines, keys, configs, and workflows. New users often stumble on permissions, while seasoned pros sometimes end up with messy key sprawl and brittle configs. Either way, pain awaits without a little discipline.

In this guide, I want to capture a clean, repeatable workflow for standing up a new machine with reciprocal SSH trust, a well-structured config, and a few tips and tricks that make everyday use faster, safer, and less painful. Nothing groundbreaking—just the kind of practical guide I wish I’d had when I was first wiring machines together.

We’ll cover:

Generating modern SSH keys the right way.
Copying them safely between machines (both directions).
Setting up a maintainable ~/.ssh/config.
Using SSH agent and keychains effectively.

For multiplexing, tunneling, and other advanced tricks, check out the companion post

⚔️ Continue to SSH-Fu

Why SSH matters

At its core, SSH (Secure Shell) gives you three superpowers:

Secure Remote Access
Encrypted sessions mean you can log in to a remote system without worrying about someone sniffing your password or keystrokes. This replaced insecure tools like Telnet and rlogin.
File Transfer
With scp and sftp, SSH is a safe way to move files. Add rsync over SSH and the ability to mount paths with sshfs, and you’ve got a flexible toolkit for syncs, backups, and deployments.
Tunnels and Proxies
SSH can forward ports, set up SOCKS proxies, and even “jump” through one machine to reach another. This makes it the Swiss Army knife of your network.

Configuring sshd_config

On most systems the server daemon is sshd, and its main config lives in /etc/ssh/sshd_config. There are a lot of options but the ones we are concerned with are as follows. On the machine you will be connecting to (we’ll call it new-server), make sure you have the following set:

# Only allow modern protocol
Protocol 2

# Enable public key auth
PubkeyAuthentication yes

# Disable password logins once keys are working
PasswordAuthentication no

# Prevent root from password logins (or at all)
PermitRootLogin prohibit-password

# Security hygiene
ChallengeResponseAuthentication no
PermitEmptyPasswords no
UsePAM yes

After making edits, make sure to reload:

sudo systemctl reload sshd    # systemd
# or
sudo service ssh reload       # SysVinit

Pro-Tip Never flip PasswordAuthentication no until you’ve verified that you can log in with a key from another terminal session to avoid getting locked out.

Generating and Installing Keys

Now that you have the machine you will be connecting to ready to accept PubkeyAuthentiation, you’ll need to generate keys on your client and then copy the public key to new-server. You need to have a working user account on new-server as well but in this scenario we’ll assume you are using the same username across your machines.

On your client machine:

ssh-keygen -t ed25519 -a 100 -C "forfaxx@laptop (2025-08)"

Copy the public key to the server:

ssh-copy-id forfaxx@new-server.darkstar.home

If ssh-copy-id isn’t available:

cat ~/.ssh/id_ed25519.pub | ssh forfaxx@new-server.darkstar.home \
 'umask 077; mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys'

On the server, fix permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Client Config (`~/.ssh/config`)

On your client you’ll want to add an entry to .ssh/config to make it easier to connect. Without an entry you need to remember to connect with a command like:

ssh -i ~/.ssh/id_ed25519 forfaxx@new-server.darkstar.home

So to make it easier, we’ll add an entry to ~/.ssh/config (create it if it doesn’t exist) and include an entry like the following:

Host new-server
  HostName new-server.darkstar.home
  User forfaxx
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
  ServerAliveInterval 30

With that in place you can connect with:

ssh new-server

This is where the real quality of life improvements begin — shorter commands, per-host options, and tricks like multiplexing or jump hosts.

Using an SSH Agent (Stop Skipping This)

With proper setup and best practices your SSH armor will hold up on the battlefield

If you’ve been running keys without passphrases (guilty 🙋), it’s probably because you thought:
“Why bother typing a passphrase every single time I connect? Connecting without a password is terrific!”

The problem is:

Without a passphrase, your private key file is just a single factor.
If a bad guy steals ~/.ssh/id_ed25519, they don’t need anything else — they are you.

So you’re stuck in a dilemma:

With a passphrase → secure, but annoying to type constantly.
Without a passphrase → convenient, but dangerously insecure.

That’s exactly what the SSH agent solves.
Think of it as a guard that holds your unlocked key safely in memory for the session. You type the passphrase once, hand it to the guard, and from then on SSH just works — no constant retyping, no unprotected key file.

The best part: you don’t have to sacrifice security for convenience. With an agent, you get both.

How It Works

Normally, SSH has to decrypt your private key every single time (prompting you for the passphrase).
The agent is a background process (ssh-agent) that:
1. Runs once per login/session.
2. Holds your unlocked key safely in memory.
3. Answers “signing challenges” on your behalf — without ever exposing the key.
You unlock the key once with ssh-add, then it’s smooth sailing until you log out or reboot.

One-Time Setup (per session)

# 1. Start the agent (if not already running)
eval "$(ssh-agent -s)"

# 2. Add your key (enter passphrase once)
ssh-add ~/.ssh/id_ed25519

# 3. Verify it's loaded
ssh-add -l

That’s it. Every ssh, scp, or git command will now silently ask the agent instead of bugging you.

How Long Does It Last?

Until you log out or reboot (or until the agent is killed).
You can set a timeout if you want the agent to forget automatically:
```
ssh-add -t 1h ~/.ssh/id_ed25519
```
On macOS, you can store keys in the Keychain so they come back on login:
```
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
```

Quick Recap

Step	When you do it	What it does
`eval "$(ssh-agent -s)"`	Once per login session	Starts the guard
`ssh-add ~/.ssh/id_ed25519`	Once per login session	Give guard your unlocked key
`ssh new-server`	Anytime	Uses the guard, no prompt

Mental model: like making coffee in the morning → unlock once, good all day.

Make the Agent Automatic (so you don’t have to remember)

Here’s how to set it and forget it on each OS.

macOS (seamless)

One-time:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

In ~/.ssh/config:

Host *
  UseKeychain yes
  AddKeysToAgent yes

Result: key unlocks at login, no extra steps.

Linux (single line in shell rc)

Add to ~/.bash_profile or ~/.zshrc:

# Start agent if needed, add key if missing (prompts once per login)
ssh-add -l >/dev/null 2>&1 || { eval "$(ssh-agent -s)" >/dev/null; ssh-add ~/.ssh/id_ed25519 ; }

Result: each login → one passphrase prompt, then done.

Windows 10/11

One-time enable:

Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent

In your PowerShell profile ($PROFILE):

# If agent has no identities, add mine (prompts once per login)
if ((ssh-add -l) -match 'The agent has no identities') {
  ssh-add "$env:USERPROFILE\.ssh\id_ed25519" | Out-Null
}

Result: first terminal after login prompts once, then all SSH/Git just works.

Handy Commands

ssh-add -l        # list loaded keys
ssh-add -D        # remove all keys from agent
ssh-agent -k      # stop agent (Linux/macOS)

Bottom line:
Keep your keys encrypted with a passphrase.
Let the agent do the remembering.
Unlock once, fight battles all day.

Links and stuff

RFC 4251 - The Secure Shell (SSH) Protocol Architecture
ssh(1) man page — man7.org
ssh_config(5) man page — man7.org
sshd_config(5) man page — man7.org
Wikipedia: Secure Shell
OpenSSH Primer
US-CERT Advisories (search for “SSH”)

Conclusion

SSH is a deceptively simple command with a lot of hidden depth.
A little upfront discipline—clean keys, a modular config, and a few tricks—turns it into one of the most powerful, reliable tools in your kit.

⚔️ Continue to SSH-Fu

Got feedback, corrections, or your own SSH war stories?
I’d love to hear them: feedback@adminjitsu.com.

Manpage-fu

Thu, 21 Aug 2025 10:25:00 -0500

What is a man page?

If you’ve ever typed man ls or man ssh, you’ve used one: a manual page. These pages are the canonical documentation of Unix—every command, system call, file format, or standard has its place.

They were created in 1971 at Bell Labs by Dennis Ritchie and Ken Thompson, after their manager insisted the system needed proper documentation. At first, this meant printed binders: plain text written in roff(7) typesetting macros, formatted for the line printer. It worked—but it was clunky. Finding the right entry meant flipping through a binder, and keeping it up to date meant re-printing and re-binding constantly.

The solution was man(1): a program that could render those same roff sources directly on a terminal screen. Suddenly, documentation was always current, always searchable, and always at your fingertips. Fifty years later, we’re still using it. Talk about an evergreen technology—manpages have outlasted punch cards, paper tape, floppy disks, and a host of other “modern” technologies.

It’s documented in The Book, somewhere…
– Larry Wall in 10502@jpl-devvax.JPL.NASA.GOV

A manpage today still comes in two forms: the source page (written in roff macros) and the formatted page (sometimes called a cat page), which is what man(1) actually displays.

Why is this cool?

Using man(1) is second nature, but writing your own page can feel intimidating enough that most of us skip it for our own scripts and tools. That’s a shame—because a proper manpage doesn’t just document your program, it legitimizes it. Nothing makes a tool feel more “real” than typing man mytool and seeing it pop up like it was always meant to live in /usr/bin.

In this post I’ll share the concepts that finally made the process click for me—and hopefully for you as well.

With a good reference and a simple template, you can give your code the kind of documentation that feels native to Unix itself.

The Quick and Dirty Howto

The manual system is dead simple:

View a page:

man ls
man ./mytool.1   # view local draft

Search all pages for a keyword:

man -k network
apropos network   # same thing

Search only in specific sections

man -s 2 -k open  # search section 2 (system calls) for open

Pro-Tip a really cool package worth installing is tldr which serves as a companion to the standard man pages and just shows practical usage examples

GNU vs BSD flavor

There are small differences depending on your platform. Linux typically ships the GNU man/groff toolchain, while macOS and the BSDs use their BSD versions. The basics are the same, but options and formatting quirks can differ.

The best way to check your system is with the manuals themselves

man man
man groff
man troff

GUI manpage viewers

Most of us are used to paging through manpages in a terminal, but there are GUI front-ends that make them easier to browse, search, and bookmark.

On macOS you’ve got a few nice tricks:

Built-in x-man-page:// scheme:
```
open x-man-page://ls
```
Opens a dedicated manpage window with search and scroll.
Render as a PDF in Preview:
```
man -t ls | open -f -a Preview
```
ManOpen — a classic NeXTStep-era tool with its openman helper.
Man Reader — modern, App Store version with tabs, bookmarks, search.
Bwana — browser-based, supports man:foo URIs.

On Linux, you’ll find:

yelp (GNOME Help Browser)
khelpcenter (KDE Help Center)
tkman (old-school but still works)
Some distros also support man:foo URIs in Firefox/Konqueror.

Check out my manfzf script for a fuzzy CLI manpage picker.

Pro Tip On both macOS and Linux, you can alias man to your favorite viewer:

alias man='openman'          # macOS with ManOpen
alias man='yelp man:'        # GNOME
alias man='khelpcenter man:' # KDE

If you spend enough time in the manual you may find the following hotkeys useful:

Key	Function
`j`	Move forward one line. Prefix with a number to move that many lines (e.g., `6j` moves forward six lines).
`k`	Move back one line. Prefix with a number to move that many lines.
`g`	Jump to the top of the manual.
`G`	Jump to the end of the manual.
`f`	Move forward one screen. (Space bar does the same.)
`b`	Move back one screen.
`d`	Move forward half a screen.
`u`	Move back half a screen.
`/pattern`	Search forward for pattern.
`?pattern`	Search backward for pattern.
`n`	Repeat the last search in the same direction.
`N`	Repeat the last search in the opposite direction.
`q`	Quit the manual pager.

Want to explore more search tricks like wrap-around, advanced pattern control, or highlighting tweaks? Check out the official less(1) manual: less — Linux manual page (search & navigation) :contentReference[oaicite:1]{index=1}

Manual sections (what those numbers mean)

You’ll often see references with a section number like foo(1) or bar(5)—that’s command_name(section).

Section	Scope	Examples
1	User commands (executables you run)	`ls(1)`, `grep(1)`
2	System calls (kernel entry points)	`open(2)`, `write(2)`
3	Library functions (libc, etc.)	`printf(3)`, `malloc(3)`
4	Special files (devices, drivers)	`null(4)`, `random(4)`
5	File formats & conventions	`passwd(5)`, `crontab(5)`
6	Games & demos	`fortune(6)`, `nethack(6)`
7	Misc (conventions, protocols, standards)	`man(7)`, `regex(7)`, `ascii(7)`
8	System administration commands	`mount(8)`, `systemctl(8)`

Less common extras

9 — Kernel routines (driver devs, low-level stuff)
l — Local (site-specific)
n — New (experimental)
o — Old (obsolete)
p — Public domain (rare)

⚡ Example: printf(1) is the shell command, printf(3) is the C library call. Use the number to disambiguate.

Anatomy of a manpage

If things start to feel too cryptic, just think of the pretty flowers until it passes

At its core, a man page is written in roff, a plain-text markup language for formatting documents. In practice, almost everyone today uses groff (the GNU roff toolchain) to process these files.

Each line that starts with a dot (.) is a directive (called a macro), and everything else is plain text. For example:

.SH NAME → start a new section header
.B → make text bold
.TP → set up a hanging indent (used in option lists)

When you run man, the source file is passed through groff with the -man macro package. That expands those directives into the nicely formatted output you see in your terminal. A raw man page looks cryptic but predictable—it’s typesetting code waiting to be compiled into clean columns.

Common sections and macros

A man page is built with roff macros. Each section header is declared with the .SH macro, and specific formatting macros handle bold, italics, lists, and examples.

Section	Purpose	Macro(s)
NAME	One-line description (`name \- summary`). Parsed by `whatis(1)`.	`.SH NAME`
SYNOPSIS	Usage syntax: command, options, arguments. Typically uses bold for commands, italics for args.	`.SH SYNOPSIS`, `.B`, `.I`, `.RI`
DESCRIPTION	Longer explanation of what the tool does.	`.SH DESCRIPTION`, text macros (`.PP` for paragraphs)
OPTIONS	Command-line flags, usually formatted as a tagged list.	`.SH OPTIONS`, `.TP` (tagged paragraph)
EXAMPLES	Literal usage examples.	`.SH EXAMPLES`, `.EX` / `.EE` (example block)
FILES	Config or data files related to the program.	`.SH FILES`, `.I` (italic filenames)
ENVIRONMENT	Environment variables the program respects.	`.SH ENVIRONMENT`, `.TP` for listing vars
EXIT STATUS	Exit codes and their meanings.	`.SH EXIT STATUS`, `.TP`
DIAGNOSTICS	Explanation of error messages.	`.SH DIAGNOSTICS`, `.TP`
BUGS	Known bugs, limitations, or witty remarks.	`.SH BUGS`
SEE ALSO	Cross-references to related commands/libraries.	`.SH SEE ALSO`, `.BR foo (1)` for bold+roman
AUTHOR	Who wrote/maintains the program.	`.SH AUTHOR`
COPYRIGHT	Licensing information.	`.SH COPYRIGHT`
HISTORY (optional)	Historical notes on command evolution.	`.SH HISTORY`

Handy Formatting Macros

.B text — bold (usually commands and flags)
.I text — italic (filenames, variables)
.RI arg1 arg2 — roman + italic (e.g., command arg)
.TP — tagged paragraph (great for options lists)
.EX / .EE — example block, keeps spacing/formatting
.BR foo (1) — bold + roman mix, used in SEE ALSO references

⚡ Rule of thumb: section headers (NAME, SYNOPSIS, OPTIONS, etc.) always get .SH. Within those, you mix .B, .I, .TP, etc. to get the formatting you want.

Minimal manpage template (customize me)

Let’s take a look at a minimal, complete manpage with helpful comments as a guide to creating your own

.\" ==========================================================
.\" mytool.1 — Minimal, complete manpage template
.\" How to view locally:
.\"   man ./mytool.1
.\"   groff -man -Tutf8 mytool.1 | less
.\"
.\" Conventions:
.\"   - Edit placeholders in ALL CAPS.
.\"   - Keep lines under ~80 cols if you can.
.\"   - Remove comments (lines starting with .\") when publishing.
.\" ==========================================================

.TH MYTOOL 1 "Aug 2025" "MyTool 1.0" "User Commands"
.\" .TH = Title Header: NAME SECTION DATE VERSION MANUAL-TITLE

.SH NAME
mytool \- one-line summary of what the tool does
.\" The dash must be escaped: \-   (this line is parsed by whatis(1)/apropos)

.SH SYNOPSIS
.B mytool
.RI [ OPTIONS ] " ARG1 " [ ARG2 ... ]
.\" Use .B for the command, .RI to mix roman/italic (nice for args).
.\" Keep synopsis concise; show common forms, not every permutation.

.SH DESCRIPTION
.B mytool
does X in order to achieve Y (1–3 sentences). State defaults and
side-effects briefly. Longer tutorials go in README or web docs.

.PP
Typical use cases:
.IP \[bu] 2
Do foo to bar quickly.
.IP \[bu] 2
Automate baz with a single command.

.SH OPTIONS
.TP
.B -h, --help
Show help and exit.
.TP
.B -v, --version
Print version and exit.
.TP
.B -o, --output \fIFILE\fR
Write output to \fIFILE\fR (default: stdout).
.TP
.B --dry-run
Print what would happen without making changes.

.SH EXAMPLES
.EX
# basic usage
$ mytool --output result.txt input.dat

# preview actions
$ mytool --dry-run input.dat

# multiple files
$ mytool -o out/ merged*.csv
.EE

.SH FILES
.I ~/.config/mytool/config.yml
Optional configuration file.
.PP
.I /var/log/mytool/mytool.log
Log file (if logging enabled).

.SH ENVIRONMENT
.TP
.B MYTOOL_CONFIG
Path to an alternate config file.
.TP
.B MYTOOL_DEBUG
Set to 1 for verbose diagnostics.

.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 1
General error (see DIAGNOSTICS).
.TP
.B 2
Invalid arguments.

.SH DIAGNOSTICS
Common error messages and remedies:
.TP
.B "cannot open file"
Check permissions and that the path exists.
.TP
.B "unknown option"
See
.BR mytool (1)
under OPTIONS.

.SH SEE ALSO
.BR grep (1),
.BR awk (1),
.BR roff (7),
.BR help2man (1)

.SH AUTHOR
Your Name 

.SH COPYRIGHT
Copyright \(co 2025 Your Name.
License: MIT.

.SH VERSION
1.0.0

That creates a manpage with the familiar structure and conventions.

That’s all there is to it. Again it’s just plain text and some macros and escapes to control formatting.

Download If you would like to download that template as a ready to go stub, you can grab it Here

To view it without installing first, you can do the following:

# simplest: point man directly at it
man ./test.1

# or, explicitly render with groff for debugging layout
groff -man -Tutf8 ./test.1 | less

# on macOS, you can preview it in Preview.app as a PDF:
man -t ./test.1 | open -f -a Preview

Using `help2man` to automatically generate documentation for your scripts

help2man is a little utility that auto-generates manpages from the output of your program’s --help and --version flags. Instead of hand-crafting a .1 file with groff macros, you can let your script speak for itself, and help2man will translate that into a standard UNIX manual page.

It’s lightweight, doesn’t need you to write groff, and is often bundled in Debian packaging workflows for quick manpages. The downside, I’ve found, is that help2man produces relatively ugly output regardless of how good your --help output is. You’ll probably find yourself polishing it to make it look nice but it does produce reasonable enough output.

Requirements

To work with help2man, your script or program must support:

-h / --help → prints a usage summary and available options
-v / --version → prints the program name and version
the script must be executable

That’s all help2man needs to create a basic manual page.

Pro-Tip: Keep your –help text tidy and descriptive—help2man copies those lines directly into the man page. If your help is garbage, your man page will be, too.

Minimal script example

Here’s a tiny, example Python script that satisfies those conditions:

#!/usr/bin/env python3
import sys

NAME = "myscript"
VERSION = "1.0"

def main():
    if "-h" in sys.argv or "--help" in sys.argv:
        print(f"Usage: {NAME} [options]\n")
        print("Options:")
        print("  -h, --help     Show this help message")
        print("  -v, --version  Show version info")
        sys.exit(0)

    if "-v" in sys.argv or "--version" in sys.argv:
        print(f"{NAME} {VERSION}")
        sys.exit(0)

    print("Hello, world!")

if __name__ == "__main__":
    main()

Make it executable:

chmod +x myscript

Generating the manpage

Run help2man on your script:

help2man ./myscript > myscript.1

Preview it with:

man ./myscript.1

Optional polish

You can add extra details with flags:

help2man --name="Tiny demo script" --section=1 ./myscript > myscript.1

And install it for local use:

sudo install -m 0644 myscript.1 /usr/local/share/man/man1/
sudo mandb 2>/dev/null || true
man myscript

📦 Installing a manpage locally

After you’ve got a .1 file you’re happy with, install it into the system manpath so man mytool works like any built‑in command. Section 1 pages usually live under /usr/local/share/man/man1/.

# 1) Copy your page into section 1
sudo install -m 0644 mytool.1 /usr/local/share/man/man1/

# 2) Rebuild the whatis/apropos database
# Linux:
sudo mandb

# macOS (BSD mandoc):
sudo makewhatis /usr/local/share/man
# (Tip: `man makewhatis` for details)

Verify:

# Where will man find it?
man -w mytool

# Does whatis/apropos see it?
whatis mytool  # or: apropos mytool

# Use it!
man mytool

User‑local install (no sudo)

You can keep manpages in your home directory:

# Put it in your personal manpath:
install -d "$HOME/.local/share/man/man1"
install -m 0644 mytool.1 "$HOME/.local/share/man/man1/"

# Point man(1) at it for this shell:
export MANPATH="$HOME/.local/share/man:$(manpath 2>/dev/null || echo /usr/share/man:/usr/local/share/man)"

# Or scope just one lookup:
man -M "$HOME/.local/share/man" mytool

Troubleshooting quickies

# See your active manpath (Linux):
manpath

# On macOS, print the search path:
man -w

# If apropos/whatis doesn’t show your entry yet:
sudo mandb                         # Linux
sudo makewhatis /usr/local/share/man  # macOS

# Check the NAME line format (parsed by whatis):
# must be: "name \- one line summary" (note the escaped dash \-)
grep -n '^\.SH NAME' -n mytool.1 -n

Links and stuff

man page on wikipedia help2man Reference Manual

Conclusion

“Whoever undertakes to set himself up as a judge of Truth and Knowledge is shipwrecked by the laughter of the gods.” – Albert Einstein

That’s it for now. Manpages can feel ancient and mysterious, but they’re still one of the most reliable ways to give your tools polish and permanence. With just a text file and a few macros, you can drop your work into the same lineage as ls(1) and grep(1).

If you’ve got a script you use every day, give it a manpage. Start small — a NAME, a SYNOPSIS, maybe a couple of OPTIONS. The next time you type man myscript, you’ll see your own work sitting comfortably alongside fifty years of Unix history.

💡 Got a favorite trick, or did this inspire you to write a wild cheatsheet manpage? Did you find yourself thinking of the pretty flowers? I’d love to hear it: feedback@adminjitsu.com.

Tag Audit

Tue, 19 Aug 2025 14:22:55 -0500

Introduction

If you run a Hugo site, you’ve probably ended up with a messy tag list at some point.

Duplicate tags, one-off singletons, forgotten categories… it all builds up over time and clutters your taxonomies. Hugo won’t clean them for you.

I wanted a way to see exactly which tags and categories I’ve used, how often, and where — so I built a quick little scanner. It’s great for spring cleaning your frontmatter—but fast, and without the sneezing.

Elevator pitch:

Tag Audit is a no-frills Python CLI that:

Counts tag and category usage across your content tree
Flags singletons (items used only once)
Shows which posts use which tag or category
Outputs in text, markdown, CSV, or JSON

Quickstart

🔗 View tag-audit on GitHub

# Install dep
python3 -m pip install pyyaml

# Basic run (from your Hugo repo root)
python3 tag-audit.py

# One file only
python3 tag-audit.py --file content/posts/metaclean.md

# Show which files use each tag (markdown output)
python3 tag-audit.py --by-tag --format markdown

# Top 20 tags/categories by count, with mappings
python3 tag-audit.py --top 20 --by-tag --by-cat

# Ignore drafts, only include items used ≥ 2 times
python3 tag-audit.py --ignore-drafts --min-count 2

Features

Scan entire Hugo content/ tree or a single file
Totals for tags and categories
Singleton detection (used only once)
Inverse mappings: files grouped by tag or category
Multiple output formats: text, markdown, csv, json
Filters: --min-count, --top, --ignore-drafts, --ext

Usage

tag-audit.py [OPTIONS]

Options (common):

--dir PATH — Path to Hugo content (default: ./content)
--file FILE — Scan a single file
--ignore-drafts — Skip drafts
--per-file — Show per-file usage
--by-tag — Show files grouped by tag
--by-cat — Show files grouped by category
--format — text (default), markdown, csv, json
--sort — Sort by count (default) or alpha
--min-count N — Only include items with count ≥ N
--top N — Limit to top N items

Sample Output

Tags
====
count  name
-----  ----------------
   21  cli
   14  python
   13  utilities
   10  bash
    5  unix
    4  fun
    4  sysadmin
    3  cromulent
    3  gibberish
    3  homelab
    3  productivity
    3  scripting
    2  hugo
    2  linux
    2  star-trek
    1  adminjitsu
    1  automation
    1  commodore-64
    1  zsh
    [...]
Total tags: 171

Categories
==========
count  name
-----  ---------------
   22  projects
   13  tools
    3  fun
    3  trivia
    2  guides
    2  workflow
    1  retrocomputing
    1  sysadmin
    1  tips
    [...]
Total categories: 61

Singleton tags (used only once)
===============================
count  name
-----  ------------------------
    1  adminjitsu
    1  automation
    1  commodore-64
    1  cryptography
    1  docker
    1  espanso
    1  fortune
    1  vim
    1  zsh
    [...]
Total singleton tags: 69

Singleton categories (used only once)
=====================================
count  name
-----  ------------------------------
    1  retrocomputing
    1  sandbox
    1  sysadmin
    1  troubleshooting
    [...]
Total singleton categories: 9

Files by Tag (excerpt)

linux

content/posts/kernel-tips.md
content/posts/bash-wizardry.md

docker

content/posts/compose-cleanup.md
content/posts/build-secrets.md

hugo

content/posts/theme-tweaks.md
content/posts/tag-audit-release.md

Conclusion

Whether you’re prepping a cleanup pass or just curious which tags are pulling their weight, tag-audit.py gives you a clear snapshot of your Hugo taxonomy.

PRs, issues, and suggestions welcome! feedback@adminjitsu.com

Self-Reports

Mon, 18 Aug 2025 16:48:13 -0500

What are Self-Reports?

Printers have it figured out. Push a button or two → get a neat printed summary of ink, alignment, and IP address.
I wanted the same for my machines. Jumping between machines on SSH can get disorienting as you try to remember how each is configured and what is going on with it. I thought about how nice it would be to have printer test-page style reports for my servers.

So I wrote a small set of self-report scripts—Bash and Python tools I keep in /usr/local/bin—that generate clean, colorful status reports. They don’t try to be full monitoring systems; they’re quick checkups I can run over SSH or right after login. It gives me a familiar, nice report from that machine’s point of view. Simple scripts—powerful concept.

Features

The family so far:

disk_report.sh → Disk usage & mount points
mem_report.sh → Memory & swap snapshot
lan_report.sh → Interfaces, routes, DNS, public IP, open ports
pi-health.sh → Hardware report specific to Raspberry Pi and PironMan5 hardware
py_report.py → Python environment snapshot (sys.path, pip packages, -m modules, etc.)

The scripts are designed with consistency in mind. Some highlights:

Consistent formatting across reports (emoji + color)
Runs on Linux, macOS, and WSL
Zero dependencies (optional: prettier output with eza)
Drop-in friendly → just copy into /usr/local/bin
Focused: each report covers one domain (disk, memory, LAN, etc.)
Safe: read-only reports, no risk of changing config

QuickStart

You can grab a copy of my report scripts to use or modify from GitHub:

🔗 View Self-Reports on GitHub

git clone https://github.com/forfaxx/self-reports.git
cd self-reports

sudo cp *.sh *.py /usr/local/bin/
sudo chmod +x /usr/local/bin/*

Optional: strip .sh when installing if you prefer shorter command names:

sudo cp disk_report.sh /usr/local/bin/disk_report
sudo cp mem_report.sh  /usr/local/bin/mem_report
sudo cp lan_report.sh  /usr/local/bin/lan_report
sudo cp pi-health.sh   /usr/local/bin/pi-health
sudo cp py_report.py   /usr/local/bin/py_report

Tip: You should now be able to run any of the reports. The real power in my experience has been in having these on each of my machines with public key based ssh authentication to make it easy to run them from anywhere:

ssh user@host mem_report

🖥️ Sample Output

See the README.md on GitHub for detailed output examples for each script.

Basically what you get from each is a consistent, on-demand report from that machine’s perspective. Read-only and with minimal dependencies so you can run it anywhere, anytime you need to refresh your memory.

Here is a taste of the output for mem_report.sh (I remove the .sh extensions in my examples. it’s up to you).


🧠 Memory Report for: server.example.com
🕒 Date: Mon 18 Aug 20:44:57 CDT 2025
🧬 OS: Linux
----------------------------------------

📊 Memory Summary:
               total        used        free      shared  buff/cache   available
Mem:           7.9Gi       2.9Gi       425Mi        21Mi       5.1Gi       5.0Gi
Swap:           17Gi       1.4Gi        16Gi

📈 Load Averages:
 20:44:57 up 32 days, 23:49,  2 users,  load average: 1.30, 1.36, 1.51

🔁 Swap Usage:
NAME       TYPE      SIZE USED PRIO
/dev/zram0 partition   2G 1.4G  100
/swapfile  file       16G   0B   10
  SwapCached:         6656 kB
  SwapTotal:      18874336 kB
  SwapFree:       17425664 kB
  Zswap:                 0 kB
  Zswapped:              0 kB

🌀 ZRAM Status:
zram0:
  disksize            : 2147483648
  compr_data_size     : (missing)
  mem_used_total      : (missing)

🐘 Top Memory Consumers:
    PID    PPID CMD                          %MEM %CPU
   1001     999 /usr/bin/sync-daemon          4.0 64.8
   2048    2000 /usr/local/bin/webapp         2.3  0.2
   3001    2988 homebridge: bridge-addon      2.0  0.0
    325       1 /lib/systemd/systemd-journa   2.0  0.0
   1111     888 /usr/bin/db-service           1.7  0.3
   4000    3990 node app/server.js            1.6  0.4
   4020    4010 /usr/bin/dns-resolver         1.5  0.5
   4500    4400 background-service            1.1  0.0
   5000       1 /usr/bin/containerd-shim      0.7  0.2

Conclusion

That’s the whole idea: quick, colorful self-reports you can run on any machine.
Not a monitoring system, not a dashboard—just a friendly check-in, like a printer test page for your servers.

I’ve already found these scripts handy when I ssh into a box I haven’t touched in a while, or when I want to sanity-check a Pi on the shelf. They’re small, portable, and don’t step on anything else.

💡 Got an idea for another kind of report? Found a bug? Or maybe you’ve written your own flavor?
I’d love to see it:

📬 feedback@adminjitsu.com
🔗 Self-Reports GitHub repo

Breathing New Life Into Vintage Macs

Sat, 16 Aug 2025 18:46:02 -0500

⌘

Apple’s Intel-era hardware is still really nice to use — slim cases, good keyboards, decent screens — but the software side ages out more quickly. A 2013 iMac or a 2017 MacBook Pro may be perfectly usable physically, yet Apple’s support window means no new macOS releases, no security updates, and a shrinking list of installable apps.

Rather than throw them away, I’ve started putting Linux on them. It’s a great way to keep solid but “obsolete” Macs relevant — giving them new roles instead of letting them gather dust. My iMac, once rarely touched, is now a genuinely useful part of my daily environment. The MacBook Pro that sat idle after my last upgrade is back in service too, reborn as a powerful Ubuntu machine wrapped in sleek Apple hardware.

And the best part? I didn’t have to give up macOS entirely. By preserving the original partition, I can still boot into my old system when needed. That dual-boot peace of mind is a big selling point.

Frame from Transformers: The Movie (1986), © Hasbro — used here under fair use as cultural commentary.

Luckily the process is so much easier than it used to be. No Boot Camp required! Still, I have a few tips that should make the process go more smoothly.

The Install Process

IMPORTANT Make a Time Machine backup (or the moral equivalent) before you follow any of my steps.

Also, before diving into the install, it’s worth giving your Mac a quick cleanup — wipe the screen, clear the dust, and reset the SMC for good measure.

The procedure I used was to download the latest amd64 image of Ubuntu Desktop (At time of writing I chose Ubuntu 24.04.3 LTS). For Intel macs you want the Intel or AMD 64-bit architecture version. I have tested this with Ubuntu, Mint and Debian.

Next, you will need a USB thumb drive. An 8gb or larger drive should be plenty. There are different ways to write the image to the flash drive but I used Balena Etcher which is available for Windows, Mac and Linux. The program is easy to use, just make sure to choose the correct drive (it only displays removable drives on my machines which makes it extra simple). You will then choose the Linux iso image you downloaded and begin the process. It can take a while and I found that letting my Macbook Pro idle interrupted the process. The second time I kept the computer from locking or sleeping until the process finished.

Balena Etcher takes a few minutes to image your flash drive. Be patient and don't let the system idle.

You should now have an Ubuntu (or whatever distro you prefer) bootable thumb drive.

For my machines, I wanted to retain my macOS partition as opposed to giving Linux the whole drive. This would allow me to dual-boot if desired. Regardless of your choice, you should backup any files or the OS if you care about them. Time Machine on Mac is a great solution.

Partitioning an Intel Mac for Linux

“What you don’t know can hurt you, only you won’t know it.”

To resize the disks, reboot into Recovery mode by holding Command-R while the system boots (just before or when the startup chime sounds).

Choose Disk Utility and find the drive with your Macintosh HD volume. If you use APFS and FileVault, you will need to mount the encrypted volume by highlighting it and clicking the mount button and entering your password. Once that is done you can select

If you use apfs you will need to mount the encrypted data partition before you can resize it

Note: On older Intel Macs (pre-2011), Internet Recovery (Command + Option + R) may not be available unless you’ve applied a firmware update. In that case you’ll need a local recovery partition or an installer USB.

In Disk Utility, the key is knowing the difference between containers/volumes and the physical drive.

🔍 The Hierarchy in Disk Utility

Physical drive → the actual SSD, usually named something like Apple SSD… at the top of the tree.
APFS container → a partition on that physical drive which contains APFS volumes.
APFS volumes → what you see as “Macintosh HD” (and its companions like “Macintosh HD – Data”).

⚡ The Step That Matters

When you want to make space for Linux, you don’t add a volume inside the APFS container. Volumes just share the container’s space dynamically, and Linux can’t install into an APFS volume.

Instead, you:

Reboot into Recovery mode by holding Command + R as the system boots (right before or when the startup chime plays).
- If Command + R doesn’t work, try Internet Recovery with Command + Option + R.
Open Disk Utility.
If you use APFS with FileVault, mount the encrypted volume:
- Highlight it, click Mount, and enter your password.
Select the physical disk (the top entry in the sidebar, e.g. Apple SSD…).
- Not just “Macintosh HD.”
- Not just the APFS container.
Click Partition (not “Add Volume”).
Shrink the APFS container and create a new partition for Linux:
- Free Space is the cleanest choice (Ubuntu installer will handle formatting).
- MS-DOS (FAT) also works as a placeholder, since Ubuntu will reformat it anyway.

With the encrypted volume mounted in Recovery mode Disk Utility, you are can now add a new partition from free space.
Choose MS-Dos or Mac OS Extended for now. Ubuntu will reformat it later.

NOTE: If Disk Utility refuses to shrink the APFS container, boot from the installer USB and use diskutil from Terminal instead:

diskutil apfs resizeContainer disk0s2 200g

(where disk0s2 is your APFS container and 200g is the new size).

NOTE: If you’re unsure, 40–60GB (or more) should give you a decent amount of legroom in Linux.

📝 Why That Step is Crucial

If you add an APFS volume → Linux can’t use it.
If you resize the container and carve out a partition → Ubuntu can see that space and format it as ext4.

Installing Linux

Once you have a partition, you’re ready to boot from your installer.

Your bootable thumb drive should have an orange removable disk icon and the label EFI Boot

Hold the Option (Alt) key while booting to enter Startup Manager.
- On some Macs, the USB installer may appear as EFI Boot instead of “Ubuntu.”
Select the Linux USB installer and choose the option to install Linux.
- Documentation.
I chose the standard Interactive Installation and then selected Manual Installation so I could point Ubuntu at the new partition.

You should see Grub and the option to Install Ubuntu at this point.

Note: On some Intel Macs you may need to disable Secure Boot in the Ubuntu installer. The Mac firmware itself doesn’t enforce Secure Boot — this is specific to Ubuntu’s shim loader. If the system refuses to boot the USB or drops you back to Startup Manager, toggling Secure Boot in the installer usually fixes it.

Manual Partitioning

When you reach the Installation Type screen:

Select Something else (manual partitioning).
Highlight the empty partition you created in Disk Utility.
- Do not touch your macOS/APFS container.
Choose Change → set the following:
- Use as: Ext4 journaling file system
- Mount point: /
- Format: checked (so the installer formats the new partition).
Leave your macOS volumes alone — Ubuntu will install side-by-side.

The installer will then set up Ubuntu on the Linux partition while preserving macOS. At boot you can hold Option (Alt) to pick which OS you want to load.

Pro-Tip: If you want a nicer boot menu instead of the plain “EFI Boot” entry, check out rEFInd, a lightweight boot manager that makes dual-booting friendlier.

First Boot Hurdles: Networking

The biggest issue I encountered doing this was that Wi-Fi wasn’t detected in the Ubuntu installer. I found simple enough workarounds and I am pretty sure from my research that I could have used any number of Wi-Fi USB dongles (as a temporary workaround) and they would have been supported and detected instantly. The objective is just to get online long enough to enable Wi-Fi.

On the iMac I was able to use an Ethernet cable so Wi-Fi wasn’t a priorty like it might be in another room.

For the Macbook Pro, I found that my Thunderbolt to Ethernet adapter was not detected—Ethernet was out.

The workaround I used was to tether my phone. It’s easy to connect your iPhone with a USB cable and connect via tethering. You’ll need to unlock your device and trust the computer when prompted and the system should prompt you to activate a wired connection.

Make sure to Trust This Computer on your phone, when prompted. Ubuntu will then allow you to use it as a Wired Connection

Once thethered, you will be able to select 'Use Wired Connection' to connect to the Internet.

You can verify which Broadcom chip you have with the following command lspci -nn | grep -i network

Go ahead and install the proprietary drivers during install although this didn’t contain the Wi-Fi driver. To install that, I had to do the following additional step to install the WiFi drivers:

sudo apt update  
sudo apt install bcmwl-kernel-source  
reboot

After reboot, Wi-Fi was working and I was able to connect.

Note: Some newer Broadcom chipsets may need broadcom-sta-dkms instead of bcmwl-kernel-source. If Wi-Fi doesn’t come up after reboot, try:

sudo apt install broadcom-sta-dkms

Post-Install Setup

Great Success! Ubuntu is now installed and Wi-Fi is working.

Booting into Ubuntu on Mac hardware. nice.

Ubuntu on Macbook Pro

I’m working on documenting the steps to get all of the built in hardware working. The facetime camera doesn’t show up by default, for instance. I installed hardinfo and it sees most of it though.

`hardinfo` shows that almost all of my hardware was detected out of the box.

Pro-Tip: To smooth out hardware quirks:

Graphics: If you have an Nvidia GPU, install the proprietary nvidia-driver package instead of relying on Nouveau.
Fans & thermals: Macs can run hot under Linux. Install mbpfan to get sane fan control.
Backlight & keyboard: The pommed utility or kernel backlight drivers may be needed for brightness and keyboard controls.

Check out my quick guide that I used with both machines. ZRAM for Efficient Swap

The Project Side

I have looked in the mirror every morning and asked myself: “If today were the last day of my life, would I want to do what I am about to do today?” And whenever the answer has been “No” for too many days in a row, I know I need to change something. – Steve Jobs (1955-2011)

So what can you actually do with a Linux-powered Mac?

As mentioned, my iMac has been pulling its weight as a reliable little workstation — and it’s held up better than I expected. The MacBook Pro is newly imaged, but even while drafting this article I found myself tweaking it, customizing it, and genuinely enjoying the experience. Sure, I miss a few macOS niceties, but Ubuntu is very usable day to day.

Most of my favorite apps are cross-platform these days anyway: VS Code, PyCharm, Obsidian, OBS Studio, Audacity, Spotify, Firefox, Chromium. Add in a proper Unix environment and my go-to wallpapers, and the machine felt like home almost instantly.

Compared to my Raspberry Pi server, these Intel Macs bring serious advantages: quiet cooling, rock-solid build quality, and hardware that was premium in its day. That makes them a fantastic middle ground between tiny low-power boards and brand-new desktops.

I can’t wait to build more docker containers and a top-notch dev and test laptop!

Links and Stuff

Essential references used in this article

Resource	Link
Mac startup key combinations	https://support.apple.com/en-us/102603
Reset the SMC of your Mac	https://support.apple.com/en-us/102605
Disk Utility User Guide	https://support.apple.com/guide/disk-utility/partition-a-physical-disk-dskutl14027/mac
Ubuntu Desktop Download	https://ubuntu.com/download/desktop
Ubuntu Desktop Guide	https://help.ubuntu.com/lts/ubuntu-help/index.html
Ubuntu Installation Tutorial	https://ubuntu.com/tutorials/install-ubuntu-desktop#4-boot-from-usb-flash-drive
Balena Etcher	https://etcher.balena.io/
rEFInd Boot Manager	https://www.rodsbooks.com/refind/

Other resources that might be useful

Resource	Link
Ubuntu Certified Hardware (searchable DB)	https://certification.ubuntu.com/
Ubuntu Community Help Wiki: MacBookPro	https://help.ubuntu.com/community/MacBookPro
Ubuntu Wi‑Fi Troubleshooting	https://help.ubuntu.com/community/WifiDocs/WirelessTroubleShootingGuide
Touchegg (multi‑touch gestures)	https://github.com/JoseExposito/touchegg
Thunderbolt on Linux (boltd/boltctl)	https://gitlab.freedesktop.org/bolt/bolt
ArchWiki: MacBook Pro	https://wiki.archlinux.org/title/MacBookPro
ArchWiki: MacBook	https://wiki.archlinux.org/title/MacBook
ArchWiki: Broadcom wireless	https://wiki.archlinux.org/title/Broadcom_wireless
mbpfan (fan control for MacBooks)	https://github.com/dgraziotin/mbpfan

Closing Thought

Linux gives old Macs a second chance before they end up here
Pictured: Electronic waste, photograph by Katherine Welles (CC BY-SA 3.0)

Like my older iMac, this MacBook Pro is now running Ubuntu instead of sitting idle. It’s not worth much on eBay, but it’s too valuable to throw away — and with Linux, it still has plenty of life left.

The project is about more than just recycling hardware. It’s about taking machines Apple has orphaned and turning them into relevant, capable systems again.

My Friend Hugo: A Unix-First Blogging Workflow

Fri, 15 Aug 2025 16:40:42 -0500

Intro

another thrilling meta article about Hugo!

When I decided to start this site, I thought WordPress was the obvious choice. I’ve used it before for a few projects but every time I revisit WordPress, I am quickly reminded that I just don’t enjoy working in it. There are so many options and plugins and themes that it becomes a bit overwhelming and I just wanted to start writing.

Django was certainly an option—I’ve built a number of decent web applications with it over the years and could certainly build a django-based blog but that was also a huge stack of technology to deal with before I could write the first hello world post.

Happily I stumbled upon the Hugo static site generator via a YouTube rabbit hole. It was markdown-based, fast, simple and scriptable and lends itself to some clever CLI workflows. Exactly what I was going for.

🧾 View Other Hugo Posts

First Impressions

“I changed my headlights the other day. I put in strobe lights instead! Now when I drive at night, it looks like everyone else is standing still …” – Steven Wright

Some impressions after 2 months of working with Hugo (especially compared to other CMS or manual web design approaches):

Markdown everywhere = good.
GoLang code, optimized for speed and flexible templating. Active development.
Easy to use inline HTML with a setting in config.toml
Just about everything can be configured and overridden if desired
PaperMod theme is clean but takes some tweaking to look “less academic.”
Git feels natural here; the site is a repo. Easy to jump between machines and keep working.
CLI + scripts give me more control than a CMS ever would.
Static site generation so the site is fast and lightweight while still featuring some impressive scripted bits

Editing Options

I’ve tried a bunch of different tools to write and edit posts:

Vim: unbeatable for quick edits, regex magic, and staying close to the shell.
VS Code: excellent overall, though it still lacks a truly reliable spellchecker.
Obsidian: great for note-taking and linking ideas, but with some quirks.
Typora: clean interface and live preview, though not much beyond Hugo’s built-in preview.

These days I bounce between VS Code (for structure) and Vim (for quick fixes), always wishing for a universal spellcheck to catch my numerous typos. Working in Markdown keeps me close to the writing while hiding the verbosity of HTML and CSS. When I need more control, Goldmark’s settings let me drop into raw HTML without friction.

Obsidian is very tempting to use but it’s vault structure is dirty with respect to git with lots of things you have to add to .gitignore with varying degrees of difficulty. I originally made a sync script to maintain a mirror between Obsidian and Hugo’s production directory in my codelab folder. That worked but I vastly prefer VS Code with its integrated Terminal and Git support as my main editor. The drawbacks with VS Code are a lack of spellchecking and a separate tabbed view for rendered markdown. Not a big deal.

My workflow is simple: one terminal tab runs hugo server -D, while two browser tabs track the local dev server and the public site. Make a change (usually in VSCode), and see it reflected instantly. Everything is tracked in git. When it’s time to publish, one script takes it live.

Publishing Workflow

After setup, the main challenge was getting updates live without friction. WordPress gave me gui menus, Hugo gives me a (Go) binary. Perfect excuse to write my own tooling. I was able to quickly identify a manual workflow and then build a nice, robust script to automate it. What a lovely experience.

What I ended up with was the following publish script that I run almost daily. It handles cleaning, building, syncing—everything I don’t want to think about (or mess up).

🔗 View publish-hugo on GitHub

Why not Git hooks or CI? Because I like the flexibility of running this script on any machine, without a network dependency.

The script automates the full Hugo publishing cycle with built-in safety checks. It starts by making sure any hugo server process is stopped, then moves into the correct project directory and performs a clean rebuild with hugo --cleanDestinationDir. Before anything goes live, it can snapshot your work in Git:

Show a concise diff if there are uncommitted changes.
Prompt you whether to commit and push.
Auto-build the commit message from changed .md files, leaving a traceable record of what was published.

From there, publish-hugo.sh (or publish-adminjitsu.sh) adds some quality-of-life touches:

Draft detection – warns you if you’re about to ship drafts (forgot to flip status).
Rsync prompt – asks before running the destructive rsync --delete.
Dry-run mode – lets you preview the sync without touching the server.

The rsync step itself is straightforward but effective, mirroring your public/ folder to the remote web root in one shot. And because it’s a Bash script, the UX has personality: colorful prompts, conversational feedback, and even a celebratory fortune if you have that installed.

In practice, this makes for a deploy process that’s safe, repeatable, and just a little bit fun.

Pre-Press and Sanity Checks

“In theory there is no difference between theory and practice. In practice there is.” – Benjamin Brewster

Publishing text isn’t just about writing—it’s also about cleaning and organizing. In my hugo directory I created a scratch/ folder and scratch/bin/ to hold helper scripts and test pages as I create them. It’s a good place to keep site tools and I have built a few decent ones already.

metaclean

Metaclean is a simple, robust tool for working with images in pre-press workflows. It can scan and strip metadata in a variety of ways, which makes it very scriptable.

Check out my 🔗 Metaclean post for the script.

tag-audit

Tag audit is a simple script that reports on category and tag usage in my posts. It helps me to keep my taxonomies straight and to spot typos and outliers and to refresh my memory without looking at each posts front matter. All in a nice, flexible report.

Check out my 🔗 Tag Audit post for the script.

asset demos

I find it useful to keep various demo pages in my scratch/bin folder. Hugo ignores arbitrary folders like this and scratch is my convention. I use it to store all sorts of helpers and notes that are strictly relating to the site as opposed to a more general tool.

Some examples of things that I find useful to keep around:

font-previews

BOILERPLATE.txt with useful snippets

POST-IDEAS.txt where I can jot down rough ideas that pop into my head

various little test scripts

a WIP bin where I can keep articles that I’m not ready to work on yet

One tool that is extremely useful is this dynamic javascript powered feather icon picker. Feather icons are SVG (vector based) icons that scale to any size and have a number of styling options. My picker is pretty cool despite being hard as heck to get just right. It allows you to easily browse, search, filter, adjust stroke width, scale, and copy the icon in a ready-to-go block that you can copy and paste, like here:

Check out 🔗 my feather-picker.html tool

Tips and Tricks

Some CLI tools and habits that keep me sane:

find, grep, sed, and awk for batch edits.
vim -p to open multiple posts side by side.
Running Hugo with --cleanDestinationDir so stale files don’t stick around.
Using shortcodes and custom CSS tweaks from my style sheet.

Problem solving

So far, the majority of issues I’ve encountered can be resolved by stopping the server, running hugo --cleanDestinationDir and starting the server again. The other is that I forgot to set draft to false in the frontmatter. Virtually every other problem will produce a big, descriptive error on the dev server giving you a chance to fix the problem and saving you from uploading (most) broken code to your webhost. Getting shortcodes to work can be a little tricky but bouncing the server helps with runtime issues.

Git is your friend when it gets confusing:

# 1. Show changes to a file vs. last commit
git diff HEAD -- path/to/file

# 2. Restore file from the last commit (discard current changes)
git restore path/to/file

# 3. Restore file to a specific commit (useful when you know the good hash)
git checkout  -- path/to/file

# 4. If you want to revert *all* changes since last commit (scorched earth)
git reset --hard HEAD

Style playground

I made this demo page public for fun and interest. Basically I have a style dojo page where I try out each markdown element and made it useful as a glyph board from which I can copy various colors, and feather, unicode, and emoji symbols. It’s great having a silly, but useful, testing ground where I can quickly try out CSS changes and see the results in one place. The original markdown also gives me a crib sheet from which I can copy useful snippets when I forget the syntax.

I kind of adore living documentation!

Check out the 🔗 Ninjas Style Dojo post for the shenanigans.

CSS for Left-side floating Table of Contents

I created z_toc-left.css in assets/css/extended containing the following to create and lock my floating toc to the left side of the content area:

/* --- FLOATING TOC ON LEFT (FIXED TO CONTENT COLUMN) --- */

#toc-sidebar {
    position: fixed;
    top: 120px;

    /* 1000px max content width → 500px half width */
    /* 320px TOC width + 48px gap */
    left: calc(50% - 500px - 368px);

    width: 320px;
    max-width: 380px;
    max-height: calc(100vh - 140px);
    overflow-y: auto;
    background: var(--entry);
    border: none;
    border-radius: 8px;
    padding: 1em 1.5em;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.1);
    z-index: 1000;
}



@media (max-width: 1380px) {
    #toc-sidebar {
        position: static;
        width: auto;
        max-height: none;
        box-shadow: none;
        margin-bottom: 1rem;
        left: unset;
    }
}

I have been experimenting with settings as I test on different platforms. So far it works quite well on wide screens, collapsing to an inline menu on narrower windows (like mobile browsers). It’s not perfect but it’s easy to tweak. Worst case, I just git restore z_toc-left.css and I’m back to a clean setup

Update It was a bit of a challenge to get my TOC to indent and format headings correctly, so I thought I would share what I figured out. Here’s the CSS + JS combo I landed on to make heading levels show up clearly in the sidebar:

I added the following CSS to assets/css/extended/z_toc-left.css: (this handles the indentation, bullets, and subtle guide rails once each TOC item has a depth class)

Details

Metaclean

Wed, 13 Aug 2025 06:01:26 -0500

Introduction

Every photo you take contains more than meets the eye.

Hidden inside are EXIF metadata tags — GPS coordinates, camera serial numbers, timestamps, copyright notices, and even software info. While useful for photographers, this data can leak way more about you than you’d expect when you post a picture online.

So I wanted a simple tool that I could use on my own photos. My old process was a mess — a half-remembered crib sheet, three separate commands, and too much context-switching. I hated it. So I built something better. A robust, flexible little CLI tool for managing image metadata. I find it useful enough that I keep using it and polishing it.

My best elevator pitch:

Metaclean is a small, pipe-friendly CLI tool that scans images for metadata and safely strips it away, with the right defaults so you won’t accidentally destroy your originals.

Perfect for:

Preparing photos for blog posts or public sharing
Stripping GPS coordinates from family photos
Cleaning a folder before archiving or handing off to clients

🔗 View metaclean on GitHub

Quickstart

# Scan for metadata
metaclean --scan photo.jpg

# Strip metadata (safe copy in ~/Pictures/cleaned/)
metaclean --strip photo.jpg

Works with JPG, PNG, WebP and TIFF

Features

Safe by default: writes copies with _clean added to the filename unless --inplace is specified
Scan EXIF metadata including GPS, camera details, and copyright information
Strip all metadata by default, rebuilding clean EXIF from scratch
Add copyright tags with --copyright
Preserve specific tags with --keep-date, --keep-orientation, --keep-icc, --keep-dpi
Pipe-friendly: works with find, xargs, fd, and similar tools

Usage

metaclean (--scan | --strip) [OPTIONS] [FILES…]

Options:

--scan — Scan and report metadata.
--strip — Strip metadata (writes clean copies unless --inplace).
--positives — Only show files that contain metadata (scan mode).
--show-gps — Expand GPS info when scanning.
--inplace — Overwrite originals (safe atomic replace).
--outdir DIR — Directory for cleaned files (default: ~/Pictures/cleaned).
--copyright TEXT — Add a copyright tag.
--keep-date — Preserve DateTimeOriginal tag.
--keep-orientation — Preserve orientation tag (pixels still corrected if not kept).
--keep-icc — Preserve ICC profile.
--keep-dpi — Preserve DPI.
--force — Process first frame of animated images (otherwise skipped).
--quality N — JPEG quality (default: 95).
--progressive 0|1 — Force progressive JPEG encoding on (1) or off (0).

# Scan a single image for metadata
metaclean --scan photo.jpg

# Scan only images that have metadata (quiet mode)
metaclean --scan --positives ~/Pictures/*.jpg

# Strip metadata from a single file (safe copy in ~/Pictures/cleaned/)
metaclean --strip photo.jpg

# Strip metadata and overwrite originals (use with care)
metaclean --strip --inplace *.jpg

# Strip metadata but keep the original date and orientation tags
metaclean --strip --keep-date --keep-orientation *.jpg

# Add a copyright tag to your images
metaclean --strip --copyright "© forfaxx" ~/Photos/*.jpg

# Find all JPGs with metadata, then strip them in-place
find ~/Pictures -name '*.jpg' \
  | metaclean --scan --positives \
  | metaclean --strip --inplace

Example Output

forfaxx@shinobi ]:/mnt/d/sort
$ metaclean --scan misc040.jpg
=== Metadata for misc040.jpg ===
ResolutionUnit: 2
ExifOffset: 196
Make: Canon
Model: Canon PowerShot G3
Orientation: 1
DateTime: 2005:11:02 19:05:35
YCbCrPositioning: 1
XResolution: 180.0
YResolution: 180.0

forfaxx@shinobi ]:/mnt/d/sort
$ metaclean --strip --inplace misc040.jpg
[OK] Stripped metadata IN PLACE → misc040.jpg

forfaxx@shinobi ]:/mnt/d/sort
$ metaclean --scan misc040.jpg
[INFO] No EXIF metadata found in misc040.jpg

Before: misc040-exif.jpg — original file with EXIF (camera model, timestamp, etc.).

After: misc040.jpg — cleaned by metaclean (no EXIF; pixels preserved).

Before and After view in ThumbsPlus

Using `metaclean` in a pipeline or script

metaclean is designed to work well in pipelines and scripts. A few examples:

Show me files with metadata (dry-run)

# Scan repo images and list only files that contain metadata
git ls-files -z -- '*.jpg' '*.jpeg' '*.png' '*.webp' '*.tif' '*.tiff' \
| xargs -0 metaclean --scan --positives \
| tee /tmp/metaclean_positives.txt

echo "Files with metadata: $(wc -l < /tmp/metaclean_positives.txt)"

In-place strip of only what’s staged for commit (pre-commit friendly)

# Safe atomic replace (your script’s default behavior) on staged images
git diff --cached --name-only -z -- '*.jpg' '*.jpeg' '*.png' '*.webp' '*.tif' '*.tiff' \
| xargs -0 metaclean --strip --inplace --keep-icc --keep-dpi

# Re-stage files that changed (helps if hook runs before commit)
git add --update

One-liner to strip everything under current directory into ~/Pictures/cleaned

find . -type f \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' \
                 -o -iname '*.webp' -o -iname '*.tif' -o -iname '*.tiff' \) -print0 \
| xargs -0 metaclean --strip --outdir "${HOME}/Pictures/cleaned"

Makefile target for “pre-publish:clean-images”

# Makefile
IMGS := $(shell git ls-files -- '*.jpg' '*.jpeg' '*.png' '*.webp' '*.tif' '*.tiff')
OUT  := static/img-clean

.PHONY: images-clean
images-clean:
	@mkdir -p $(OUT)
	@echo "→ Scanning and cleaning images into $(OUT)…"
	@printf '%s\0' $(IMGS) \
	| xargs -0 metaclean --scan --positives \
	| metaclean --strip --keep-icc --keep-dpi --outdir $(OUT)
	@echo "✓ Done."

# Optional: fold into your publish chain
publish: images-clean
	./sync-adminjitsu.sh

Links and Stuff

Conclusion

Whether you’re cleaning up a single selfie or prepping an archive for public release, metaclean has your back.

Have a neat pipeline or trick?

PRs and issues welcome! Or email me: feedback@adminjitsu.com

Upgrade Your Junk Drawer

Tue, 12 Aug 2025 14:53:33 -0500

Intro

The Texas Winter Storm of 2021 — Winter Storm Uri — was a wake-up call. Store shelves went bare, gas stations closed, and widespread power outages even knocked cell towers offline. It was a crash course in just how fragile our everyday systems are.

Since then, I’ve made sure to keep a reasonable supply of water, food, and sanitation products on hand. You don’t have to be a “prepper” to see the value in having a couple of weeks’ worth of essentials ready for when things go sideways.

One day, while reorganizing my so-called junk drawer, I realized there was another kind of preparedness I’d been overlooking: information. What happens when you lose internet access and the cloud goes out of reach? Whether a short outage or Planet of the Apes time, it’s incredibly useful to have these tools waiting for the day they might be needed.

That thought experiment turned into a small, practical project: a pair of USB drives that would give me both digital rescue tools and a personal offline internet.

These are the two upgrades I made to my junk drawer:

Upgrade your junk drawer with these fantastic thumb drives

YUMI tools disk

A multiboot USB drive, built with YUMI, packed with rescue ISOs, OS installers, and diagnostic tools. It’s the Swiss Army knife of boot media.

YUMI (Your Universal Multiboot Installer) is a free utility that turns an ordinary USB stick into a multi-boot Swiss Army knife. Instead of carrying a dozen separate thumb drives for each operating system or rescue tool, YUMI lets you store multiple ISOs on a single device — with a friendly boot menu to pick the one you need. Luckily the process is simple and YUMI has links to a large list of isos to include. Adding a custom one is not hard at all!

It supports a huge range of images, from Linux live distros and Windows installers to antivirus rescue environments, memory testers, and disk cloning tools. You can add, remove, or update ISOs without wiping the entire drive, which makes it perfect for keeping your toolkit fresh.

I built mine as a go-to rescue and setup drive, loaded with:

Windows 10 and Windows 11 Installers / repair disks
MemTest
Boot Repair Disk
Ultimate Boot CD
GParted
Finnix
Kali Linux
Ubuntu Desktop
Antivirus Live
Kodachi Anonymous browsing
Spinrite
and more!

Each of these images live on the disk as an ISO with a single multi-boot loader. The rest of the disk is available as storage so I also loaded it up with a collection of Computer and Networking cheatsheets and pdfs. I tried to cover topics from pc hardware to networking to Operating System specific references and more.

The last piece of the puzzle is PortableApps. This is an easy to set up collection of windows applications that do no require installation. With hundreds of packages including standards like VLC, Chromium, Firefox, and more, it provides a portable toolkit that come in handy if you find yourself on a guest computer or are without Internet and have things to fix.

I’ve only reached for my YUMI boot drive a couple of times since I built it but it’s a huge relief knowing it’s there. It’s like knowing your spare tire is aired up and in good shape. The peace of mind is priceless.

The Hardware

I’ve made a few of these for friends using 128 GB and 256 GB drives, and they work great — but I got hooked on building the ultimate boot drive.
The one I recommend is the SSK 512 GB or 1 TB thumb drive.
As of publication, the 512 GB is about $50 and the 1 TB about $77.
It’s pleasingly heavy, solid metal, and has been rock-solid in my testing. Amazon link.
If you’re on a budget, 128 GB or 256 GB will still get the job done — but I wouldn’t go smaller.

Offline Internet

If the YUMI drive is my digital multitool, this is my pocket library — a self-contained slice of the web that doesn’t care if every ISP from here to Guam goes belly-up.

It’s built around Kiwix — free, open-source software that reads .zim archives (think: an entire website, squished into a single file). With the right ZIMs, you can browse huge swaths of the internet without ever going online.

Kiwix’s Library offers hundreds of site archives which you can preview live without downloading. Some are tiny but packed with value; others are massive, like the English Wikipedia — over 6 million pages with images and links. You’ll also find medical and first aid guides, language resources, practical skills manuals, and technical collections like StackExchange.

Can’t find the site you want? You can make your own ZIM. It can be a bit of a black art depending on complexity, but I’ve had success creating more than ten — including foragingtexas and textfiles.com.

Kiwix is like a normal browser for the offline .Zim website archives

Wikipedia (English with images) — ~110 GB
Wikivoyage — offline travel guide, ~1 GB
Stack Exchange dump — the collective Stack brain, ~50 GB
Project Gutenberg — 60 GB of public-domain books
Medical & first aid references — WHO, CDC, wilderness medicine PDFs
Military Field Manuals - on a huge array of topics from carpentry to earth moving to emergency medicine.
Much More - over 80 zim archives comfortably fit in a 512gb drive. You can really splurge with a Terabyte or more

Kiwix runs on Windows, macOS, Linux, even Android. You can just read locally, or flip the switch on its tiny built-in server so other devices on your LAN/Wi-Fi can browse your stash like it’s the real thing.

📚 Supporting files

The Kiwix browser and offline ZIM archives are fantastic, but they still leave some gaps. To fill them, I built a serious directory of practical ebooks covering a huge range of topics. The Internet Archive was my main hunting ground, along with countless niche sites. After some determined searching, I pulled together PDFs on everything from power and water systems, primitive tools, and Amish gardening, to hunting, fishing, automotive repair, welding (for those A-Team–style zombie survival vehicles), woodworking, psychology, negotiation, leadership, electronics, cooking, preserving, law, medicine, and even rainy-day activities for kids and adults.

Building that collection was a blast — I tried to anticipate as many scenarios as I could imagine needing the drive for. Highlights include:

PDF manuals — Hundreds of guides, how-tos, and reference books across dozens of disciplines.
AI-generated cheatsheets — Troubleshooters, walkthroughs, and quick-reference sheets for emergencies and complex topics.
Infographics & diagrams — Wiring charts, ham radio band maps, plant identification guides, and other dense visual references.
Offline AI models — Compact (4–8 GB) quantized LLaMA/Qwen builds you can run locally for Q&A without an internet connection. Limited compared to commercial models, but surprisingly capable.
Portable apps — Readers, converters, scanners, accessibility tools (magnifiers, color pickers), and basic media editors — all ready to run without downloads.
My notes — Not the latest version, but packed with network configs, machine specs, serial numbers, cheatsheets, and setup worklogs.

It’s not the whole internet — but it’s my internet, curated for when the big one hits and the only cloud left is the one making rain (or fallout).

Thoughts on Preparing for the Worst

Burgess Meredith in the classic Twilight Zone episode, "Time Enough at Last"
© CBS Studios Inc. All rights reserved.

Making these drives was a blast. Beyond building tools for a rainy day, it became a grand thought experiment:
In what situations might I need these drives?

The YUMI multi-boot disk was easy — we’ve all borked a server config or locked ourselves out in a dozen creative ways. I just built the tools and gathered the technical resources I’ve actually needed before. That mix of imagination and past experience was addictive.

The real challenge (and fun) was the Offline Internet project. I spent weeks — months, really — downloading ZIM archives and putting them through their paces. I curated e-books from my own shelves and the Internet Archive, shaping them into a dataset that’s actually usable: hundreds of practical titles across countless fields.

Then came the “what if” game:

Boring road trip + dead stereo → puzzle books, coloring books, trivia, road trip games.
Vault Dweller rebuilding society → construction, woodworking, welding, engineering manuals.
College student mid-paper, Wi-Fi down → research material that just might save the semester.

The result is a beautifully curated collection — resources for woodworking, sewing, gardening, medicine, electronics, philosophy, ham radio, camping, fishing, and more — all right at my fingertips.

Using the drives

I tested these thoroughly while building them, but most of the time they live in an Altoids tin in my desk drawer. The exception is the Offline Internet project, which I also keep on a live hard drive on my network — I use the practical ebook library often. Even with an active internet connection, it’s nice having that kind of information instantly at hand. It’s helped me research everything from repair jobs to obscure technical questions.

You can update the content, but ZIM archive dumps are infrequent. You’ll typically be a year or so behind on major sites, but with so much evergreen material, it hardly matters. Most of the collection remains relevant for decades.

The real value shows when the power or internet go down — whether for an hour or a week. With my MacBook Pro, a decent power tank, a solar charger, a car, and a generator, I can keep my devices running. Add an RTL-SDR radio dongle and antenna kit for picking up broadcasts, my phone’s hotspot, and the Offline Internet drive, and there’s very little I can’t research.

💡 LM Studio

One of the sparks for this whole project came from an ad I saw for a “prepper Raspberry Pi” — a little box that served offline websites and reference material. It was clever, but it made me think: why stop there? I wanted something bigger, faster, and more flexible — not just static pages, but a system that could help me search, summarize, and connect information.

That’s where LM Studio comes in. Running entirely offline, it lets you load a large language model (LLM) and query it against your own data — ZIM archives, PDFs, notes, you name it. Suddenly, the Offline Internet project wasn’t just a filing cabinet; it became an interactive reference librarian. I named mine ‘Sprocket’

Pairing Kiwix ZIM archives with a practical ebook library and an LLM turns the drive into a research machine:

ZIM archives give you complete websites like Wikipedia, StackExchange, and medical references.
PDF library covers niche and technical topics that rarely exist as ZIMs.
LLM in LM Studio helps you find answers, summarize long documents, and connect ideas — all without the cloud.

The result is a tool that works as well in a power outage as it does on a quiet afternoon in your workshop. It’s not just storage — it’s knowledge you can actually use.

🧠 Setting up LM Studio for Offline AI

LM Studio is a free desktop app for running large language models (LLMs) entirely offline. It’s perfect for querying your ebook library or ZIM archives without sending a single byte to the cloud.

Getting started:

Download & Install — Grab the latest release for macOS, Windows, or Linux from lmstudio.ai.
Pick a Model — In the “Discover” tab, search for one of these recommended models (choose a GGUF build with q4_K_M quantization for best speed/accuracy on laptops):
- Qwen 2 7B Instruct — Hugging Face (excellent general reasoning, great at summarizing technical docs)
- LLaMA 3 8B Instruct — Hugging Face (newest Meta model, very coherent responses)
- Mistral 7B Instruct v0.3 — Hugging Face (fast and light, great for Q&A tasks)
Download — LM Studio will pull the model directly from Hugging Face and store it locally.
Load & Chat — Click “Load Model,” then open a chat tab to start asking questions.
Increase Context Window (optional) — If your laptop has enough RAM, set the context size to 4096–8192 tokens in model settings for better long-document performance.

Pro tip:
Enable the Local Docs plugin in LM Studio to add your ebook library folder. Once indexed, you can ask:

“Summarize the welding section in Military Field Manual 3-34”
and get an answer without opening the PDF.

LM Studio stores everything locally — no tracking, no API calls, just a fast, private assistant that works even when the grid doesn’t.

Boot from USB

Be sure to check your BIOS/UEFI for the correct procedure to boot from a usb drive. Here are a few common ones:

Brand / Board Maker	Boot Menu Key	BIOS/UEFI Setup Key	Notes
Acer	F12	Del or F2	Boot menu often disabled by default — enable in BIOS first.
ASUS	Esc or F8	Del or F2	Newer boards often Esc for boot menu.
Dell	F12	F2	Latitude/OptiPlex/Precision lines are consistent.
HP / Compaq	Esc, then F9	Esc, then F10	Esc opens startup menu, then select option.
Lenovo (ThinkPad)	F12	F1	Some older ThinkPads use F12 for boot, F1 for BIOS.
Lenovo (IdeaPad)	F12 or Novo button	F2	Novo is a tiny recessed button near power.
MSI	F11	Del	Consistent across desktop boards and gaming laptops.
Gigabyte	F12	Del	Common on Aorus/Z-series boards.
Biostar	F9	Del
Toshiba	F12	Esc or F1	Satellite series often Esc to setup.
Sony VAIO	F11	F2	Some models require Assist button when off.
Samsung	Esc or F12	F2
Intel NUC	F10	F2	NUCs are consistent.
Packard Bell	F8	F1 or Del

🍏 Mac Boot Keys

The Mac has a rich set of built in tools for repairing system problems. It can still be good to download and stash a copy of the latest macOS installer or two. You can find instructions here: https://support.apple.com/en-us/101578

Key Combo (hold at startup)	Function
Option (⌥)	Startup Manager — choose boot disk (USB, external, etc.).
Command (⌘) + R	macOS Recovery (Internet or local).
Shift + Option + Command + R	Internet Recovery for original macOS version shipped with Mac.
Command (⌘) + Option (⌥) + R	Internet Recovery for latest compatible macOS.
T	Target Disk Mode (Mac acts as external drive).
D	Apple Diagnostics.
Option + D	Internet Apple Diagnostics.

Conclusion

My upgraded junk drawer has duct tape and WD-40 for fixing the things you can touch — and then there are the tools for fixing the rest. A YUMI drive and an Offline Internet library might never leave your junk drawer… but if you ever need them, you’ll be glad they are there.

It would be simple enough to combine these into a single, curated combination YUMI and offline internet with a big enough drive. Kiwix is easy to run as a server which will make your library available to machines on a network. Never let an inconvenient power outage stop you from doing Information Age tasks.

feedback@adminjitsu.com

Even More Cromulent Words

Sun, 10 Aug 2025 00:00:00 +0000

Introduction

In Cromulent Words and More Cromulent Words, I collected curious, oddly-specific, and strangely useful terms from computing, philosophy, and beyond.
This third entry dives into logic, skepticism, and the scale of the unimaginably large (and small) — with even more cromulent words for your mental toolkit.

Image © Fox Broadcasting / The Simpsons.

🧾 View Cromulent Words Series

Big, Small & Silly Numbers

(From yottabytes to googolplexes, Planck lengths to femtoseconds — the units that stretch your brain from the cosmic to the subatomic.)

We’ve all seen charts like this one that help us to understand the extremely large (and small) numbers that are everywhere in computer science.

Prefix	Symbol	Factor	Power of 10	Examples
Femto	f	Quadrillionth	10⁻¹⁵	Femtosecond: electron hops ~0.3 mm
Pico	p	Trillionth	10⁻¹²	Picosecond: light travels 0.3 mm
Nano	n	Billionth	10⁻⁹	1 nanometer: DNA’s double helix is ~2 nm wide
Micro	μ	Millionth	10⁻⁶	Microsecond: a camera flash cycle
Milli	m	Thousandth	10⁻³	Millisecond: hummingbird wingbeat
Kilo	k	Thousand	10³	Kilometer: ~0.62 miles
Mega	M	Million	10⁶	Megabyte: small image file
Giga	G	Billion	10⁹	Gigabyte: HD movie
Tera	T	Trillion	10¹²	Teraflop: PlayStation 5’s raw compute power (~10 TF)
Peta	P	Quadrillion	10¹⁵	Petabyte: 1,000 large hard drives
Exa	E	Quintillion	10¹⁸	Exabyte: big-data center scale
Zetta	Z	Sextillion	10²¹	Zettabyte: roughly, all internet data (mid-2020s)
Yotta	Y	Septillion	10²⁴	Yottagram: weight of all Earth’s oceans (~1.4 Yg)

I recently started collecting ZIM archives after an annoying power outage reminded me of the Texas Winter Storm of ’21 — when electricity and cellular data were down for days during an emergency. What began as a “just in case” thought experiment turned into a fun way to repurpose a big thumb drive I already had lying around into a surprisingly powerful offline library.

Check out: my Upgrade Your Junk Drawer post for the details!

During my research, I stumbled across the excellent Wikipedia:Database download page. It’s one of my favorite write-ups on SI units, file sizes, and filesystem limits ever — unexpectedly funny, deeply nerdy, and endlessly useful.

I’m now tempted to make the yottabyte my “default” storage unit.
That 10 TB hard drive on my desk? A staggering 0.00000000001 yottabytes. At this rate, I’d only need to buy about 100 billion more 10 TB drives to hit a full yottabyte. Maybe they’ll go on sale.

Now, if you really want to push your brain past the comfortable limits of prefixes, consider the Planck length — about 1.6 × 10⁻³⁵ meters.
It’s so small that if a proton were scaled up to the size of the observable universe, a Planck length would still be smaller than a tree in your backyard.
Physicists often treat it as the smallest meaningful unit of length, below which our current theories of space and time stop making sense.

Did You Know? The SI prefixes above yotta were extended in 2022:

ronna (10²⁷)
quetta (10³⁰)

In this scale, Earth’s mass is about 6 ronnagrams (Rg), while Jupiter weighs in at roughly 1.9 quettagrams (Qg)—making it over 300 times more massive than Earth.

A googolplex is written as: $10^{10^{100}}$

That’s a 1 followed by a googol of zeros (a googol itself being $10^{100}$).
For comparison: the estimated number of particles in the observable universe is “only” about $10^{80}$.

Dr. Seuss imagined letters beyond Z — some SI prefixes feel just as fantastical.

Computer Science Lore

(From background spirits to stampeding processes, packet-capture mantras to mythical config files — the stories and slang that make up sysadmin folklore)

Daemon
In UNIX, a daemon is simply a program that runs quietly in the background. The name comes from James Clerk Maxwell’s demon in physics — a thought-experiment creature that sorts atoms without expending energy — repurposed to mean “helpful background spirit.”

To program a true daemon the old-school UNIX way, you follow a ritual of sorts:
1. Fork – The process calls fork(), creating a child and letting the parent exit. This detaches it from the invoking shell’s process group.
2. setsid() – The child starts a new session, becoming the session leader and cutting ties to any controlling terminal.
3. Fork again (optional but traditional) – Prevents the daemon from ever re-acquiring a terminal.
4. Change working directory – Usually to / so it won’t block filesystem unmounts.
5. Set umask – Define default file permissions, often umask(0) so the daemon can set its own.
6. Redirect file descriptors – Close stdin, stdout, and stderr, reopening them to /dev/null — or to log files.
“The friendly face of BSD — a nod to UNIX background processes.”
Original Beastie art © Phil Foglio / John Lasseter, drawn for BSD manuals in the early 1980s.

Hysteresis

When a system’s state depends not just on current inputs, but also on its history — a kind of “memory” effect that prevents rapid flapping between states.

In hardware: a thermostat set to 72°F might turn on heat at 70°F and off at 74°F, avoiding constant toggling. In ops: a load balancer might only mark a node healthy after three consecutive passing checks, even if the first one passes.

That gap between “on” and “off” is hysteresis — stability’s best friend, but also the reason your thermostat ignores you for five awkward minutes
Thundering Herd

In systems programming, the thundering herd problem happens when multiple processes or threads are all waiting for the same event, and they all wake up at once when it occurs.
Instead of one lucky process getting the job, they all rush in — wasting CPU cycles, clogging I/O, and often making performance worse than if they’d just queued politely.

Imagine a hundred worker processes all calling accept() on the same listening socket. A single client connects. All hundred wake up, but only one actually gets the connection. The other 99 trip over each other, go back to sleep, and waste precious cycles in the process. This is one of the many challenges of concurrent programming

Common causes:
- Poorly coordinated socket or file descriptor polling.
- Overuse of blocking calls without proper locking.
- Naïve use of select()/poll() with shared resources.

Bit rot

The slow, silent decay of digital data over time. Sometimes literal — cosmic rays flipping bits on old disks, fading charge in flash memory cells — and sometimes metaphorical: neglected codebases that still run, but drift out of compatibility with modern systems.

In storage: uncorrected read errors on an old backup tape. In software: that internal tool last touched in 2017 that now needs half a dozen deprecated dependencies replaced before it will even compile.

Moral of the story: a backup you never test is just a decorative brick, and unrun code is compost with delusions of grandeur.

Fragment A of the Antikythera Mechanism — a 2,000-year-old Greek astronomical calculator, sometimes called the world’s first analog computer. A reminder of both human brilliance and the slow grind of time’s “bit rot.”
Photo by Marsyas – Own work, CC BY-SA 3.0, via Wikimedia Commons.

pcaps or it didn’t happen

a play on the common Internet phrase, demanding evidence to back up an extraordinary claim. In networking, this is frequently in the form of a pcap or network capture.

You can capture a pcap of your favorite network traffic with something like:
```
sudo tcpdump -i eth0 -s 0 -w capture.pcap
```
In fact, a really good practice for folks who have to support a server product is to capture pcaps of normal traffic so you have a point of comparison when things go wrong. I keep a pcap zoo with all kinds of traffic for just that reason. Also, tcpdump is a great command to use with customers or end users who will often not have wireshark or network monitor. It makes it easy to have them run tcpdump and send you the capture for detailed analysis.
Did You Know? You can capture network traffic from a connected iOS device with two commands:
```
rvictl -s $(system_profiler SPUSBDataType | awk -F': ' '/Serial Number/{print $2; exit}')
```
How it works:
- system_profiler SPUSBDataType — lists connected USB devices, including iOS devices.
- awk -F': ' '/Serial Number/{print $2; exit}' — finds the first serial number (the UDID for iOS).
- rvictl -s — starts an RVI for that device.
Once that is running, you’ll see a new interface (rvi0) in ifconfig, and you capture from it with:
```
sudo tcpdump -i rvi0 -s 0 -w ios-capture.pcap
```

TTY (Teletypewriter)

Before modern computers, a “terminal” was a clattering, electro-mechanical beast that printed your computers output on paper in response to commands you typed in which were also echoed to paper. The name stuck—in UNIX and Linux, tty still refers to a terminal device. You’ll see it in commands like
```
tty
# /dev/ttys001
```
- Bells: Instead of a pop-up notification, the system could get the operators attention bt making the teletype ding with the BEL control code (^G or ASCII 7). That tradition lives on — try echo -e "\a" in a terminal.
- Carriage Returns: The CR and LF you hear about in text encoding? On a teletype, CR literally moved the print head back to the start of the line, while LF advanced the paper up one line. That’s why Windows still uses CR+LF as line endings — it’s pure teletype legacy.
- Virtual TTYs (vttys): Modern systems emulate multiple terminals in software — you can switch between them with Ctrl+Alt+F1 through F6 on many Linux distros. They’re ghosts of teletypes past, living inside your GPU.

The Teletype still lives on in our virtual ttys today
Pictured: Ken Thompson and Dennis Ritchie

Cargo Cult Programming

Following procedures or copying code/configs without understanding why they work, just because “it worked someplace else”

First step is to read about Cargo Cults, if you haven’t heard about them—they are a truly fascinating phenomenon that still exists today. BBC - Vanuatu cargo cult marks 50 years .

Did You Know? Richard Feynman referred to research that imitates the form of science without its rigor as Cargo Cult Science.

A great example of this in Computer Science might be found in teams who bounce the server at any sign of trouble or keep an ancient iptables setup that a former employee configured that has always worked but isn’t well understood. Perhaps the elders speak of a prophecy in which the one called Trevor will return and refactor the code! Cargo Cult Thinking rears it’s ugly head in many situations.

The Scientific Method for Sysadmins

Too often, we guess. We reboot the box, tweak a config, or apply the “fix” we saw in a forum post from 2013 — and when it works, we don’t always know why. That’s survivable when you’re debugging your own laptop, but dangerous when you’re responsible for production systems or complex networks.

The scientific method gives you a framework: observe, hypothesize, predict, test, and analyze. By running your troubleshooting like a controlled experiment — changing one variable at a time, documenting every step — you turn panic into process. And process means problems get solved faster, fixes stick longer, and you can explain your reasoning to anyone from your junior teammate to your most skeptical CTO.

In short: the scientific method turns “have you tried turning it off and on again?” into “here’s the evidence, here’s the cause, and here’s how we’re preventing it next time.”

Here’s the lab method, translated for ops—so we stop guessing and start knowing:

1) Observe

Gather facts, not impressions: logs, metrics, tcpdump/pcaps, repro steps, timestamps, versions.

2) Question

What exactly is failing? Scope it: which host, which users, which path, since when? did it ever work? just one machine or many? on network or off?

3) Hypothesize (must be falsifiable)

Because X, therefore Y fails.
Examples: “NPM health checks time out because upstream container OOM‑kills.”
“TLS handshake fails because SAN doesn’t include hostname.”

4) Predict

If the hypothesis is right, then a specific observation should follow.
Examples: “Raising memory limit stops OOM kills.” “openssl s_client shows SAN mismatch.”

5) Test (change one variable)

Create a minimal, reversible experiment; log everything you change.

6) Analyze

Did results match the prediction? If yes, increase confidence. If no, discard or refine.

7) Document & Decide

Record cause, fix, and rollback. Automate guardrails (alerts, dashboards, runbooks).

Scientific Method Flowchart

This is the essence of troubleshooting, especially at an engineering level.

  flowchart TD
  A["Observe & Collect Evidence"] --> B["Form Hypothesis (falsifiable)"]
  B --> C["Predict Observable Outcome"]
  C --> D["Design Minimal Test (one variable)"]
  D --> E["Run Test & Measure"]
  E --> F{"Prediction matched?"}
  F -- Yes --> G["Increase confidence"]
  G --> H["Implement Fix / Prevent Recurrence"]
  F -- No --> I["Revise Hypothesis"]
  I --> C
  H --> J["Document: notes, runbook, alerts"]
  J --> K["Monitor for Regression"]

A few bonus concepts:

• Occam’s Razor
The simplest explanation is usually correct.

In troubleshooting: before you blame cosmic rays, check the power cable.

• Hanlon’s Razor
Never attribute to malice that which can be adequately explained by stupidity.

• Trust but Verify
A Russian proverb — doveryai, no proveryai (доверяй, но проверяй) — popularized by Ronald Reagan.
Completely apropos in the ops and support world.

• Confirmation Bias
The tendency to notice, remember, and favor evidence that supports what you already believe.

In troubleshooting: you’re convinced the new firewall rule is the problem, so you only look at logs that show blocked packets — ignoring that the actual cause was a DNS misconfig.
Guardrail: actively seek disconfirming evidence before declaring victory.

• Post Hoc Fallacy (Post hoc ergo propter hoc)
Latin for “after this, therefore because of this.” Mistaking sequence for causation.

“We deployed at 2 PM, and the outage happened at 2:10 PM, so the deploy must have caused it.”
Reality: correlation ≠ causation. Check logs and metrics before assuming cause.

• Sunk Cost Fallacy
Continuing a failing approach because you’ve already invested time, money, or effort in it.

You’ve spent 6 hours debugging a flaky script that could be rewritten from scratch in 45 minutes — but you “don’t want to waste the work you’ve already done.”

Linguistics Corner

(From sound-alike shenanigans to meaning-swapping tricks — the word relationships that make language fun, precise, and occasionally treacherous.)

Semantic relationships

Heteronyms — Words spelled the same but pronounced differently, with different meanings.

“Bass” (the fish) vs. “bass” (low-frequency sound).
Synonyms — Words with the same or nearly the same meaning.

“Error” and “fault” — although in engineering, one might be upstream of the other.
Antonyms — Words with opposite meanings.

“Start” vs. “stop,” “online” vs. “offline.”
Homophones — Words that sound the same but have different meanings, often spelled differently.

“Write” vs. “right,” “byte” vs. “bite.”
Homonyms — A broader category where two words share the same spelling or the same sound, but have different meanings.

“Bat” (the animal) vs. “bat” (baseball equipment).
Metonyms — When something is referred to not by its own name, but by something closely related.

“The crown” for a monarchy, “the White House” for the U.S. presidency, “silicon” for the tech industry.”

If you haven’t seen it, Weird Al’s Word Crimes is a hilarious three-minute grammar masterclass.

So, one of my biggest pet peeves, when it comes to language, is the misuse of the following:

Countable vs. Uncountable Nouns

Countable nouns are things you can count in discrete units (servers, packets, features).
Uncountable nouns (aka mass nouns) are measured in amount or volume (bandwidth, patience, downtime).

Fewer → countable

Fewer servers, fewer packets, fewer outages
Many → countable (positive form)

Many features, many logins, many CPUs
Less → uncountable

Less downtime, less bandwidth, less patience
More → works for both

More CPUs, more storage, more uptime
Much → uncountable, often in questions/negatives

How much RAM?, Not much traffic today

Why it matters:

Using fewer when you mean less is like calling a petabyte a “kilobyte” — most people won’t care, but some will twitch.
Sometimes meaning changes: “fewer permissions” (number of actions) vs. “less permission” (overall authority).

(Bonus tip: “10 items or less” signs are technically “wrong” — prescriptivists hate them, descriptivists shrug.)

Miscellany

“No amount of genius can overcome a preoccupation with detail”

Droste Effect

The visual recursion where an image contains a smaller version of itself, which contains an even smaller version, and so on. Named after the 1904 Droste cocoa tin design — a nurse carrying a tray with a cup and the same cocoa tin, endlessly repeating.

In computing, you see Droste all over: VNC into a machine that’s VNC’d into the same machine, fractals, or the classic desktop screenshot set as the wallpaper, creating an infinite hallway effect.

Water-Powered Computers

Before supercomputers, before punch cards — some problems were solved by literally plumbing the math. Hydraulic analog computers used water levels, flows, and pressures to model complex systems, often in real time.

In the USSR, massive “water integrators” modeled economic and industrial processes; in the U.S., sprawling tabletop models of the San Francisco Bay used pumps, channels, and dye to simulate tides, shipping routes, and pollution spread.

They weren’t general-purpose machines, but for their niche, they beat any slide rule. Plus, debugging often meant getting your shoes wet.

the Phillips Machine or MONIAC (Monetary National Income Analogue Computer)
By Tiia Monto - Own work, [CC BY-SA 3.0]

US Army Corps of Engineers Bay Model
a working hydraulic, scale model of San Francisco Bay

Apophenia

Seeing patterns in random noise—a human brain specialty (is it suspicious that I specified huuu-mon brains?)

Server down? Users angry? That one LED is blinking faster than normal. Your brain will connect them into a neat conspiracy board with red string and a picture of the intern.

Pareidolia

A specific type of apophenia — seeing familiar shapes or patterns where none exist, often faces.

You glance at a server rack and swear one of the vent holes is smiling at you. Or you see a “ghost” in a heatmap when it’s really just Tuesday’s backup job.
Fun fact: the “man in the moon” and “face on Mars” are both classic pareidolia moments.

Logic Symbols & Notation

(The tiny glyphs that make reasoning compact, precise, and way more fun to scribble in meeting notes.)

∴ — Therefore
Marks a conclusion drawn from previous statements.

Error only happens after deploy, ∴ deploy introduced the bug.
∀ — For all (Universal Quantifier)
Means “for every member of the set, the statement is true.”

∀ servers in the cluster, uptime > 99.9%.
∃ — There exists (Existential Quantifier)
Means “there’s at least one case where this is true.”

∃ packet with DF bit set causing fragmentation issues.
¬ — Not / Negation
Reverses truth value.

¬healthy container after config push.
⇒ — Implies
If the first statement is true, the second must be true.

Memory leak ⇒ eventual OOM kill.
⇔ — If and only if (Iff)
Both statements imply each other — equivalence.

TLS cert valid ⇔ SAN matches hostname.
⊕ — Exclusive OR (XOR)
True if exactly one, but not both, statements are true.

Either DNS is wrong ⊕ the app config is wrong.

Conclusion

“Logic is a systematic method of coming to the wrong conclusion with confidence.”

Words (and symbols) are tools — sometimes scalpels, sometimes sledgehammers. The right one, at the right moment, can cut through baloney, name a strange pattern, or give scale to the incomprehensible. That’s what keeps me coming back for “just one more” cromulent entry.

🧾 View Cromulent Words Series

Got a candidate for Volume 4?
feedback@adminjitsu.com

🖖 Space the Ultimate Frontier

Sat, 09 Aug 2025 06:59:03 -0500

Captain’s Log

Stardate: sometime in the late, mid-eighties…

My very first computer game on my very first computer was the 1986 release of ‘Space the Ultimate Frontier’ for the Commodore 64/128. I remember visiting my first computer store (with a big neon sign) at a PX in Germany and spotting the cool spaceship on the cover. I was immediately sold! It would be my first introduction to what games on a computer could be. There was strategy, energy management, action—all with SID chip music and sound effects. I was hooked on computer games from that point on.

Playing the game today is as easy as could be. The Internet Archive has an emulated copy that is playable in your web browser: Space the Ultimate Frontier.

You can also get your own copy and run it with the VICE emulator on any platform you can think of (pretty sure I saw a BeOS download link!). 47KB of glorious C64 starship combat awaits

The only problem is, how do you play it?

Starship Combat

This screenshot is about 80KB, nearly twice as large as the entire game!

You have been ordered to defend starbases on the border from attack by a force of Klyron ships. You start off in command of the USS Enterprise but if you die, you take command of a sister ship, the USS Columbia. Your ship has a number of systems accessible by number:

1) HELM CONTROL 
2) SHORT RANGE SCAN (SRS)
3) LONG RANGE SCAN (LRS)
4) PULSAR CONTROL
5) PHOTON TORPEDO CONTROL
6) SHIELD CONTROL
7) SUBSPACE COMMUNICATIONS
8) LIBRARY COMPUTER
9) TRACTOR BEAM
01) WEAPONS STATUS
02) RESUPPLY
03) POWER TRANSFER
04) DAMAGE CONTROL
05) REPAIR
06) STATUS REPORT
0D) Destruct Sequence 

ESC - exit from a system

Movement and Targeting are based on a circular vector arrangement

Movement vectors: use 1–8, or halves (e.g., 1.5) to aim between headings.

You can specify “2” for up and to the right or “1.5” for halfway between 1 and 2.

The game supports playing with the keyboard and an optional, single-button joystick. If you prefer keyboard-only, the game maps the joystick to the H,J,M, and I keys.

Other important hotkeys:

F1 - Raise and balance both shields
F3 - Drop both shields to 0
F5 - Cancel Klaxon horn
F7 - Swivel your starship about its vertical axis
F8 - Set simulation difficulty (1-3 digits up to 128 where higher numbers are more difficult. try 37 or 03!)
ESC - Escape from any system and return to command mode

a Klingon—uh—Klyron battlecruiser maneuvers behind a planet for cover

In the Long Range Scanner screen, each sector is represented by a three-digit number (e.g., 315).
The first digit is the number of Klyrons (3), the second is the number of starbases (1),
and the third is the number of planets (5).

Mastering the Long Rang Scanners

Starbases are your lifeline — docking with them is the only way to repair damage and re-arm your ship.
Defend them at all costs. If they’re destroyed, you’ll lose… and the after-action report will be filed
by the Klyron cook or janitor (their captain is far too busy to waste time writing about human p’takh).

The all-important Destruct Sequence requires several codes:

DESTRUCT SEQUENCE ONE: 11A

DESTRUCT SEQUENCE TWO: 11A2B

DESTRUCT SEQUENCE THREE: 1B2B3

FINAL CODE: 000

Viewing the Manual

Luckily the game included a manual detailing the gameplay of this unlicensed, not-at-all-Star Trek like game. One of the neat things about Space the Ultimate Frontier is that the game disk isn’t just the program — it also contains the title art, the full game manual, and a keyboard overlay, all as separate PRG files you can load from BASIC. They aren’t available in the Internet Archive’s in-browser emulator, so if you want to see them, you’ll need to run the .d64 in VICE (or another C64 emulator) and do it yourself.

The iconic blue-on-blue BASIC screen — 38911 bytes free and endless possibilities

Here’s how:

load "$",8
list

You’ll see something like:

192 "THE ULT.FRONTIER" PRG
14 "SPACE PIC"        PRG
153 "SPACE DOX"        PRG
43 "SPACE KB OVERLAY" PRG
262 BLOCKS FREE.

To view the extras:

Title Screen

load "SPACE PIC",8
run

Game Manual

load "SPACE DOX",8
run

Keyboard Overlay

LOAD "SPACE KB OVERLAY",8
RUN

In order to view the Keyboard (KB) overlay, you will need to set up VICE to print to BMP.

🖨 Setting up VICE to print to BMP file

Printing without the dot matrix noise loses some of the charm

Open Printer Settings
- Go to Settings → Peripheral Settings → Printer Settings.
- Select Printer #4 (or another printer slot if preferred).
Enable Virtual and IEC Devices
- Go to Settings → Peripheral Settings.
- Check Enable virtual devices.
- Check Enable IEC device.
Configure Printer #4
- Emulation type: File system
- Device #4 printer text device: path to your output file/directory (e.g. /home/you/vice_printouts/manual.bmp)
- Printer driver: MPS803 (reliable for graphics/text mix)
- Output type: Graphics
- Output file format: BMP
- Form feed on close: ✅ (ensures the BMP finalizes correctly)
Save Settings
- Go to Settings → Save current settings so the printer setup is remembered.
Print from the C64
- In the program, choose the “print” function.
- The BMP file will appear at your chosen path when printing completes.

A great, C64 version of a mainframe classic

Space the Ultimate Frontier is a shiny, C64/C128 take on the classic “Star Trek” game that first appeared on the Sigma 7 mainframe at the University of California, Irvine in 1971. That game, written in BASIC, spread and soon appeared on systems from the PDP-10 to the HP 2000 time-sharing system.

You can still get a taste of the mainframe glory days by checking out the 1970s C version that is still available in the bsdgames package.

sudo apt update
sudo apt install bsdgames
trek

I’m sure that was more fun to play on a teletype in a big expensive computing center. The C64 version really brings the game to life with smooth, simple graphics and Commodore’s famously decent sound chip. I love that this game was an implementation of a Unix mainframe classic that was already almost 20 years old when it was released.

Links and stuff

YouTube longplay video (good preservation demo but not as much fun as playing it)

Resource	Description	Link
TOSEC (The Old School Emulation Center)	Massive preservation project with verified ROM sets.	tosecdev.org
GameBase64 (GB64)	Curated database of C64 games with metadata, screenshots, and downloads.	gamebase64.com
Lemon64	Community site with game reviews, forums, and downloads.	lemon64.com
C64.com	Interviews, game downloads, and scene history.	c64.com
Internet Archive C64 Collection	Huge playable-in-browser C64 software archive.	archive.org/details/softwarelibrary_c64

🖖 You can check out the pdf of the manual that I uploaded to the Internet Archive
Internet Archive – STUF Manual Scanned manual for Space: The Ultimate Frontier (C64/C128), with PDF download.

archive.org/details/space-the-ultimate-frontier-manual/Space-the-Ultimate-Frontier-manual.pdf

Conclusion

This game has a special place in my heart but nostalgia aside, it packs a lot of gameplay into a tiny memory footprint. It has definitely earned a place in my boredom-battling games kit!

A little bonus in case you want to hear the C64 SID chip sing!

Game designer Dave Neale brought equal parts strategy and chaos to the bridge

🖖 If you want even more Star Trek fun, check out my Borgify script post and start borgifying those annoying work emails today!

Have a fond memory of this or other great Commodore games (Space Taxi anyone)? A battle story? I’d love to hear about it. Email me: feedback@adminjitsu.com

Vim Setup

Fri, 08 Aug 2025 19:59:05 -0500

Intro

“A writer is someone for whom writing is more difficult than it is for other people.” — Thomas Mann

I’ve spent a lot of time building a consistent, unified environment across my machines and VMs. It’s great having the same powerful tools available almost everywhere, but keeping that setup portable between macOS, Windows, and Linux—while juggling different versions of Vim and gVim—takes some planning.

In this post, I’ll share my personal .vimrc along with a few tips, tricks, and lessons learned from years of periodically refining it.

🌐 Why Portability Matters

When your configuration works the same way on every system, you stop wasting time re-learning shortcuts, hunting for missing plugins, or adjusting to quirks between machines. A portable setup means you can drop into a fresh VM, a coworker’s laptop, or a remote server and feel instantly at home—your muscle memory works, your tools are there, and you can focus on the task instead of fighting the environment. For me, it also removes the mental friction of context-switching between macOS, Linux, and Windows, which makes me faster and keeps my workflow consistent.

Highlights of this `.vimrc` (Why it feels better than stock)

One .vimrc to Rule Them All
Works across macOS, Linux, and Windows terminals with minimal assumptions and no odd dependencies. Drop it on a fresh box, run :PlugInstall, and you’re ready to work.

Readable, Low-Friction UI

Lightline statusline: fast, informative, and clean.
Line numbers with quick relative toggle: ,n.
Cursorline, wildmenu, ruler, and title for better orientation.
Dark-friendly colors: set background=dark + stock desert theme.

Better Search and Navigation

Smart search (ignorecase + smartcase, incsearch, hlsearch).
Split navigation on homerow: Ctrl-h/j/k/l.
Indent-based folding (all folds open by default).

Editing Defaults That Don’t Fight You

Spaces with 4-wide indent (expandtab, shiftwidth=4, softtabstop=4).
Filetype-aware tweaks for Python and shell built in.

Built-in Git and File Tools

FZF for instant file jumps: ,f (files), ,g (git files).
Fugitive: ,gs (status), ,gd (diff), ,gc (commit), ,gb (blame).
Undotree: ,u for undo history.
NERDTree available via :NERDTreeToggle.

My .vimrc

" ===============================
" Kevin's Portable .vimrc
" Clean, fast, readable.
" ===============================

let mapleader = ","           " Press Esc, comma then shortcut

" === General Behavior ===
set nocompatible              " Don't use old vi compatibility
set backspace=indent,eol,start " Backspace works over everything
set history=1000              " Command and search history
set hidden                    " Allow switching buffers without saving
set mouse=a                   " Enable mouse support in all modes

" === UI Enhancements ===
set number                    " Show absolute line numbers
set nowrap                    " Don't wrap long lines
set linebreak                 " Break lines at word boundaries
set showcmd                   " Show incomplete command in lower right
set cursorline                " Highlight current line
set ruler                     " Show cursor position in the status line
set wildmenu                  " Tab completion menu for commands
set title                     " Show file title in terminal title bar
set laststatus=2              " always show status line

" === Search Behavior ===
set hlsearch                  " Highlight search results
set incsearch                 " Show match while typing
set ignorecase                " Ignore case in searches...
set smartcase                 " ...unless capital letters used

" === Indentation ===
set expandtab                 " Use spaces instead of tabs
set shiftwidth=4              " Indent by 4 spaces
set tabstop=4                 " A tab character looks like 4 spaces
set softtabstop=4             " Insert 4 spaces when pressing Tab
set autoindent                " Copy indent from current line
set smartindent               " Do smart C-style indenting

" === Filetype-Specific Tweaks ===
filetype plugin indent on     " Enable filetype-specific plugins and indenting
autocmd FileType python setlocal expandtab shiftwidth=4 softtabstop=4
autocmd FileType sh     setlocal expandtab shiftwidth=4 softtabstop=4

" === Folding ===
set foldmethod=indent         " Fold based on indent levels
set foldlevel=99              " Open all folds by default

" === Performance Tweaks ===
set lazyredraw                " Don’t redraw while executing macros
set ttyfast                   " Assume a fast terminal connection
set noswapfile                " Don't use swapfiles
set nobackup                  " Don't keep backup files
set nowritebackup             " Don't backup before overwriting

" === Colors and Syntax ===
syntax on
set background=dark           " Tell colorschemes to use dark background
colorscheme desert            " Pick your favorite — 'desert' is safe and readable

" === Clipboard (if supported) ===
set clipboard=unnamedplus     " Use system clipboard (requires +clipboard)

" === Keybindings and Leader ===
" i am leaving this here as a warning to future generations to never do this
" let mapleader = " "           " Use SPACE as the  key


" --- Smart Save ---
nnoremap <C-s> :w<CR>         " Ctrl+S to save

" --- Command Prompt Shortcut ---
" Use SPACE for command mode — normal mode only
nnoremap <silent> <SPACE> :


" --- Toggle hlsearch ---
nnoremap <leader>h :set hlsearch!<CR>    " Toggle search highlight on/off
nnoremap <leader><CR> :nohlsearch<CR>   " Clear highlight quickly

" --- Toggle relative numbers ---
nnoremap <leader>n :set relativenumber!<CR>

" --- Yank to system clipboard ---
vnoremap <C-c> "+y            " Ctrl+C in visual mode yanks to system clipboard

" --- Better window movement ---
nnoremap <C-h> <C-w>h
nnoremap <C-j> <C-w>j
nnoremap <C-k> <C-w>k
nnoremap <C-l> <C-w>l

" === my shortcuts ===
nnoremap <leader>f :Files<CR>           " FZF file search
nnoremap <leader>g :GFiles<CR>          " FZF Git files
nnoremap <leader>s :w<CR>               " Save file
nnoremap <leader>q :q<CR>               " Quit
" --- Git Integration ---
nnoremap <leader>gs :G<CR>               " ,gs → git status (fugitive)
nnoremap <leader>gc :G commit<CR>        " ,gc → git commit
nnoremap <leader>gd :G diff<CR>          " ,gd → git diff
nnoremap <leader>gb :G blame<CR>         " ,gb → git blame

" --- Undo and Session Tools ---
nnoremap <leader>u :UndotreeToggle<CR>   " ,u → toggle undo tree

" --- Editing Shortcuts ---
nnoremap <leader>w :w<CR>                " ,w → write file
nnoremap <leader>q :q<CR>                " ,q → quit
nnoremap <leader>x :x<CR>                " ,x → save and quit


" === Optional Fun Aliases ===
command WQ wq
command W w
command Q q
command E e

" === vim-plug plugin manager ===
call plug#begin('~/.vim/plugged')
Plug 'tpope/vim-fugitive'
Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
Plug 'junegunn/fzf.vim'
Plug 'preservim/nerdtree'
Plug 'itchyny/lightline.vim'
call plug#end()

I live a little dangerously (swap and backup disabled, etc.). If you want safer options, add this to the top of the .vimrc

" --- Safe persistence (portable)
set undofile
set undodir^=~/.vim/undo

set backup
set writebackup
set backupdir^=~/.vim/backup
set directory^=~/.vim/swap

" Create dirs if missing (once per boot)
if !isdirectory(expand('~/.vim/undo')) | call mkdir(expand('~/.vim/undo'), 'p') | endif
if !isdirectory(expand('~/.vim/backup')) | call mkdir(expand('~/.vim/backup'), 'p') | endif
if !isdirectory(expand('~/.vim/swap')) | call mkdir(expand('~/.vim/swap'), 'p') | endif

Usage notes

On new machines, I can do the following to have an identical setup:

Setting up this`.vimrc` on a New Machine

## Setting Up My `.vimrc` on a New Machine

# 1. Install Vim and helpers
# Ubuntu/Debian
sudo apt install vim git fzf ripgrep

# macOS (Homebrew)
brew install vim fzf ripgrep

# 2. Install vim-plug (plugin manager)
curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
  https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

# 3. Link your vimrc from your dotfiles repo
ln -s ~/codelab/dotfiles/vimrc ~/.vimrc
# Adjust the path above if your dotfiles are elsewhere

# 4. Install plugins from within Vim
# (You can also do this from the shell)
vim +PlugInstall +qall

# 5. Optional: Enable Ctrl-S in terminal
echo 'stty -ixon' >> ~/.bashrc
# Prevents terminal freeze when pressing Ctrl-S in Vim

How to use these settings

Basics

Leader key: , — press this, then the shortcut.
Save: Ctrl-S or ,w
Quit: ,q
Save & Quit: ,x
Command-line mode: in normal mode starts :commands.

Line numbers: absolute by default; toggle relative → ,n
Move between splits: Ctrl-h, Ctrl-j, Ctrl-k, Ctrl-l
Folds: indent-based, all open by default (zc close, zo open)

Search

Smart search: case-insensitive unless you type a capital.
Incremental search: matches appear as you type.
Toggle highlight: ,h
Clear highlight: ,

Clipboard

Yank to system clipboard: in visual mode, Ctrl-C

File & Project Tools

FZF file search: ,f
FZF git files: ,g
NERDTree: :NERDTreeToggle
Buffers: :ls to list, :b# to switch

Git Integration (vim-fugitive)

,gs → git status
,gd → git diff
,gc → git commit
,gb → git blame

Undo Tree

,u → toggle undo history

Tips

Save as sudo:
:w !sudo tee % > /dev/null
Search/replace in file:
:%s/old/new/gc
Delete all lines not matching:
:v/pattern/d

Macros

Record: qa → do stuff → q
Play: @a
Repeat last: @@
Run N times: 15@a

A few power moves

Save without sudo?
:w !sudo tee % >/dev/null
Insert command output
:r !date
Search & replace across project
:args **/*.py → :argdo %s/old/new/ge | update
Filter selection through shell
:'<,'>!sort -u
Visual block insert
Ctrl-v → Itext → Esc
Jump to mark
mA to set, 'A to go
Ripgrep + quickfix
:grep -R "needle" . → :copen
Diff two files
:w | vnew other.txt | diffthis | wincmd p | diffthis
Git in-place
,gs status · ,gd diff · ,gc commit
Undo history tree
,u

Combine with my article, Espanso and Friends for real life Street Fighter combos.

Feedback

Got a vim tip or trick? Email me: feedback@adminjitsu.com

iperfer

Thu, 07 Aug 2025 00:00:00 +0000

What is `iperfer`?

I got tired of the usual iperf3 song and dance.

You know the drill: SSH into the remote box, start the server, flip back to your machine, run the test, then go back and kill the server—hoping you remembered to clean up the process. All that hassle just to check how your LAN or VPN is holding up.

So I wrote a helper.

iperfer.sh is a tiny shell script that automates remote-side setup for iperf3 bandwidth tests. It:

Connects to the remote host via SSH
Launches iperf3 in server mode (backgrounded and PID-tracked)
Runs a local client test with parallel streams
Cleans up the remote server process afterward

It even checks if iperf3 is installed on the remote side before trying. One command. One step. No leftovers.

🧱 Script Highlights

Auto-starts iperf3 -s on the target host over SSH
Tracks the PID and cleans up after the test
Runs a 4-stream client test with customizable duration
Leaves no background processes or temp files behind
Written in portable Bash with safe defaults (set -euo pipefail)

⚙️ Usage

iperfer.sh  [user] [duration]

If [user] is omitted, it defaults to your current $USER
If [duration] is omitted, it defaults to 10 seconds
The test runs 4 parallel streams and outputs standard iperf3 stats

Example

iperfer.sh gir forfaxx 15

That runs a 15-second test to gir as user forfaxx, then stops the remote server.

📄 Installing `iperfer.sh`

Save the script below to ~/bin/iperfer.sh (or anywhere in your $PATH), then make it executable:

chmod +x ~/bin/iperfer.sh

Make sure the script is present on both your local and remote machines in a consistent location so SSH can find it.

#!/usr/bin/env bash
#
# iperfer.sh — Run an iperf3 test over SSH by auto-starting a remote server
#
# Usage:
#   iperfer.sh  [remote-user] [duration]
#
# Example:
#   iperfer.sh gir grumble 15
#
# Description:
#   Starts iperf3 in server mode on the target over SSH,
#   runs a parallelized client test locally,
#   then shuts down the server process cleanly.
#
# Author: forfaxx @ adminjitsu.com

set -euo pipefail
IFS=$'\n\t'

usage() {
  cat <Usage: $0  [remote-user] [duration]
Runs iperf3 test from this machine to  using SSH to start/stop the server.

Defaults:
  remote-user = $USER
  duration    = 10 seconds
EOF
  exit 1
}

run_iperf_test() {
  local target="$1"
  local user="${2:-$USER}"
  local duration="${3:-10}"

  echo "🔍 Checking if iperf3 is installed on $target..."
  if ! ssh "$user@$target" "command -v iperf3 >/dev/null 2>&1"; then
    echo "❌ iperf3 is not installed on $target. Aborting."
    exit 1
  fi

  echo "🔄 Starting iperf3 server on $target..."
  ssh "$user@$target" "nohup iperf3 -s > /dev/null 2>&1 & echo \$! > /tmp/.iperf3.pid"

  sleep 1

  echo "📡 Running iperf3 client to $target for $duration seconds..."
  if ! iperf3 -c "$target" -t "$duration" -P 4; then
    echo "⚠️  iperf3 test failed"
  fi

  echo "🛑 Stopping iperf3 server on $target..."
  ssh "$user@$target" "kill \$(cat /tmp/.iperf3.pid) 2>/dev/null || true && rm -f /tmp/.iperf3.pid"
}

main() {
  if [[ $# -lt 1 ]]; then
    usage
  fi
  run_iperf_test "$@"
}

main "$@"

Final Thoughts

It’s a small thing, but being able to spin up a remote iperf3 test in one step has saved me tons of clicks and mental overhead.

More than that, the pattern of starting remote processes over SSH and tracking their PIDs for cleanup has proven useful in other scripts too. iperfer.sh just happens to be where I reached for it first.

If you try it or adapt the pattern for something else, I’d love to hear about it. Feedback and ideas always welcome: feedback@adminjitsu.com

Hero Commands

Mon, 04 Aug 2025 21:46:16 -0500

I once worked with a woman named Mirya who was, without question, the best Unix admin I’ve ever met. She could rattle off complex pipelines and write `awk` and `sed` scripts from memory, pulling off shockingly powerful feats with *apparent* ease. I asked her for a copy of her shell history once and studied it like it was Merlin’s spellbook. Ever since, I’ve been collecting history files, Perl notebooks, shell one-liners, and plenty of my own—the kind of arcane knowledge that can turn you into a command-line hero.

🧙‍♂️ Path Walk

Sometimes you need to troubleshoot the permissions on the whole directory path from your current working directory all the way back to /. Compiling that report manually can really fill up the ‘swear jar’ quickly. Luckily this path walk command makes it easy to see it all together so you can focus on the important stuff.

macOS

Shows permissions, ACLs and xattrs — all in one command.

while [ $PWD != / ]; do ls -aled@ `pwd`; cd ..; done; ls -aled@ `pwd`

Linux

While not as pretty as macOS ls, we can achieve similar results with the POSIX / Linux equivalent command:

while [ "$PWD" != "/" ]; do echo; echo "--- $PWD ---"; ls -ld "$PWD"; getfacl -p "$PWD" 2>/dev/null; getfattr -d "$PWD" 2>/dev/null; cd ..; done; echo; echo "--- $PWD ---"; ls -ld "$PWD"; getfacl -p "$PWD" 2>/dev/null; getfattr -d "$PWD" 2>/dev/null

This will produce output like this:

--- /home/grumble/codelab/adminjitsu ---
drwxr-xr-x - grumble  4 Aug 10:39 /home/grumble/codelab/adminjitsu
# file: /home/grumble/codelab/adminjitsu
# owner: grumble
# group: grumble
user::rwx
group::r-x
other::r-x


--- /home/grumble/codelab ---
drwxr-xr-x - grumble  4 Aug 08:49 /home/grumble/codelab
# file: /home/grumble/codelab
# owner: grumble
# group: grumble
user::rwx
group::r-x
other::r-x


--- /home/grumble ---
drwxr-x--- - grumble  4 Aug 20:54 /home/grumble
# file: /home/grumble
# owner: grumble
# group: grumble
user::rwx
group::r-x
other::---


--- /home ---
drwxr-xr-x - root  9 Oct  2024 /home
# file: /home
# owner: root
# group: root
user::rwx
group::r-x
other::r-x


--- / ---
drwxr-xr-x - root  2 Aug 16:38 /
# file: /
# owner: root
# group: root
user::rwx
group::r-x
other::r-x

Bash Function

Since these commands do not require arguments, they make great Bash, alias-like functions. The following will do the same thing with a single command. You just need to add the following to your startup files (e.g., .bashrc,.zshrc) and reload. As a script, it demonstrates a nice pattern for using pushd and popd to perform a sequence of actions and then return to the original directory.

macOS Version

pathwalk() {
  pushd . > /dev/null
  while [ "$PWD" != "/" ]; do
    ls -aled@ "$(pwd)"
    cd ..
  done
  ls -aled@ "$(pwd)"
  popd > /dev/null
}

Linux Version

pathwalk() {
  pushd . > /dev/null
  while [ "$PWD" != "/" ]; do
    echo
    echo "--- $PWD ---"
    ls -ld "$PWD"
    getfacl -p "$PWD" 2>/dev/null
    getfattr -d "$PWD" 2>/dev/null
    cd ..
  done
  echo
  echo "--- $PWD ---"
  ls -ld "$PWD"
  getfacl -p "$PWD" 2>/dev/null
  getfattr -d "$PWD" 2>/dev/null
  popd > /dev/null
}

🜔 Diff a remote file

Sometimes you need to compare a local file with a remote one. Copying files to your machine via scp gets old fast. That’s where this simple but not completely obvious command comes in.

ssh user@host cat /path/to/remotefile | diff /path/to/localfile -

This command streams the contents of the remote file over SSH.
Pipes that remote file into diff using - as an argument to mean “read from stdin”
Compares the local file (/path/to/localfile) against the remote — not temp files, no manual copies, no extra cleanup.
Use sudo if required, ala ssh user@host sudo cat /etc/somefile | diff /path/to/localfile -

An example: ssh user@host sudo cat /etc/somefile | diff /path/to/localfile -

Pro-tip Use colordiff for pretty output

ssh host 'openssl x509 -in /etc/ssl/cert.pem -text' | diff cert.txt -

“Technology is a word that describes something that doesn’t work yet.” — Douglas Adams

There are a few basic commands that really help when you find yourself jumping between directories (web development projects for instance)

Jump to previous directory

No matter how twisty and deep the path, cd - lets you jump to your previous folder and back if you run it again.
```
# toggles between your current and previous directory
cd -
```
Pushd, Popd and Dirs

For when you want to bookmark your current spot before diving into another directory
- pushd
  : saves your current location and jumps to
- popd: Jumps back to when you last used pushd (and removes that location from the stack)
- Use these to create a stack of locations for more complex navigation
Example
```
pushd /etc
# Do stuff in /etc
pushd /var/log
# Do stuff in /var/log
popd
# Back to /etc
popd
# Back to where you started
```
Pro-tip You can use the dirs command to view the locations stack

Using these tools you can (somewhat) eliminate the tedium of typing /annoyingly/long/paths

hero commands: because you never know what kind of monsters you'll encounter

🐍 Python tools

There are a couple of fantastic tools that “come with” Python and let you do magical things easily. I use them all the time!

1. Validate & Pretty-print JSON

echo '{"json":"obj"}' | python -mjson.tool
# Or with files:
python -mjson.tool < ugly.json > pretty.json

Validates JSON (throws error if invalid).
Indents and formats output for humans.
Saves the day ocassionally

2. HTTP Client & Web Testing

Simple HTTP GET/POST from the command line:

python -m http.client HOST
# Interactive HTTP client (rarely used, but there)

Quickly start a web server (Python 3):

python -m http.server 8000
# Serves current directory on whatever port you specify (8000 in this example)

Great for quick file sharing or local dev.

Run a CGI server (Python 3):

python -m http.server --cgi
# Runs scripts in cgi-bin/

Listen on a specific interface

You can bind to localhost only for instances with the --bind argument, like so →

python -m http.server 8000 --bind 127.0.0.1

3. Encode/Decode Base64

echo 'hello' | python -m base64
# Or:
python -m base64 -d < encoded.txt > decoded.bin

No need for base64 utility, works everywhere Python is installed.

4. Compress/Decompress Files

gzip:

python -m gzip -d file.gz
python -m gzip file

zip:

python -m zipfile -l my.zip    # List contents
python -m zipfile -e my.zip .  # Extract here
python -m zipfile -c out.zip file1 file2  # Create zip

5. Simple File Serving

python -m http.server  # Python 3.x
python -m SimpleHTTPServer  # Python 2.x

Dead simple “share this folder” in seconds.

␀ Empty a file

“The usefulness of a pot comes from its emptiness.”

— Lao Tzu, Tao Te Ching

I frequently want to zero out test files that I am working with. The following are a few ways to do it, easily and safely

# Redirects "nothing" into the file
>filename

# or use truncate. Sometimes you can't use >filename and that's where these less memorable commands come in
truncate -s 0 filename

# you can also do the following just make sure to wrap the comand in single quotes or it will usually fail
sudo bash -c '> filename'

📚 Make ps output easier to read

“If you gaze long into /dev/null, /dev/null gazes into you.

- Friedrich Nietzsche, if he were a sysadmin

I covered this in more detail in another post, ps-for-spelunkers

Basically, you can insert a blank line (or more than one) between each process in the output. This is super useful when you’re trying to make sense of processes with a lot of switches like Java, Databases and Webservers.

echo "$(ps aux)" | awk '{print;} NR % 1 == 0 {print"";}'

Examples

ls -l | awk '{print;} NR % 1 == 0 {print"";}'
cat bigfile.txt | awk '{print;} NR % 1 == 0 {print"";}'

More than one blank line

Just change the modulus in the command:

awk '{print;} NR % 1 == 0 {print"";} NR % 3 == 0 {print"";}'

Pro-tip Specifying just the columns you are interested in conjunction with the awk command makes it even easier to read. ps -eo pid,user,args

Sometimes good guys don't wear white

⇨ Awk: print from a given column to end of line

I had to work with some logs that had optional columns and found myself needing a way to print from a column I wanted to the end of the line. Instead of making a bunch of custom commands for each case, I turned to our old pal, Awk.

Fun fact - AWK is named for its creators, Alfred Aho, Peter Weinberger, and Brian Kernighan

awk '{for(i=4;i<=NF;++i) printf "%s%s", $i, (i

You can customize the command easily:

i=4 means start at the 4th field (adjust as needed).
OFS is output field separator (default: space).
ORS is output record separator (default: newline).

Example Usage

cat opendirectoryd.log | awk '{for(i=4;i<=NF;++i) printf "%s%s", $i, (i

⌬ Get number of CPU cores

If you ever need to fetch the number of CPU cores on a machine from a script, you can turn to this trusty cross-platform command:

getconf _NPROCESSORS_ONLN

On my 6-core, hyperthreaded Mac, this returns 12.

That comes in handy for things like a yes stress tester

Warning this will max out your processor and produce maximum heat which you probably don’t want to do unless you’re testing your cooling setup. Although if you are testing cooling, then you’re welcome!

for i in $(seq 1 $(getconf _NPROCESSORS_ONLN)); do yes > /dev/null & done

When you’re ready to stop the yes stress test, run:

killall yes

of if you happen to be on a system without killall you can run:

pkill -9 yes

⟡ A listeners function

This is a nice and simple way to display your listening processes and ports. I keep this on all my machines; it’s my go-to for quickly reminding myself what’s listening. Just add the following to your shell session or put it in your startup files (e.g., .bashrc, .zshrc)

listeners() {
  sudo lsof -nP -iTCP -sTCP:LISTEN |
  awk 'BEGIN {
          format = "%-16s %-8s %-22s %-10s\n"
          printf format, "[PROC]", "[PID]", "[PORT]", "[ACCOUNT]"
          printf format, "------", "----", "------", "--------"
      }
      NR > 1 {printf format, $1, $2, $9, $3}'
}

Getting the quoting right is tough, but you can also run it as a one-liner over ssh if you’re feeling kinky.

ssh user@host "sudo lsof -nP -iTCP -sTCP:LISTEN | awk 'BEGIN {format = \"%-16s %-8s %-22s %-10s\\n\"; printf format, \"[PROC]\", \"[PID]\", \"[PORT]\", \"[ACCOUNT]\"; printf format, \"------\", \"----\", \"------\", \"--------\"} NR > 1 {printf format, \$1, \$2, \$9, \$3}'"

Example output:

┌──[ forfaxx@shinobi ]:~/codelab/adminjitsu  (main*)
└─$ listeners
[PROC]           [PID]    [PORT]                 [ACCOUNT]
------           ----     ------                 --------
systemd          1        *:111                  root
systemd          1        *:111                  root
systemd          1        [::1]:2947             root
systemd          1        127.0.0.1:2947         root
rpcbind          208      *:111                  _rpc
rpcbind          208      *:111                  _rpc
sshd             334      *:22                   root
sshd             334      *:22                   root
node             940      127.0.0.1:46267        forfaxx
hugo             315471   127.0.0.1:1313         forfaxx

Conclusion

That’s it for now but more to come ! Have a hero command of your own? I’d love to hear about it! Email me: feedback@adminjitsu.com

Rotating Backups Skeleton

Mon, 04 Aug 2025 08:48:29 -0500

What is `rotate-backups.sh`?

Just the bare bones, man.

A no-frills, plug-and-play backup rotation script for small setups, homelabs, or anywhere you want clean dailies, weeklies, and monthlies—without third-party tools or magic wrappers. Inspired by the Unix philosophy: simple, composable, inspectable.

The setup includes one Bash script and two systemd units: a *.service to define the job and a *.timer to schedule it. The goal is elegant, self-contained rotation so that when disaster strikes, you’ve got multiple recovery points.

By default, the timer runs at local midnight (00:00). If the machine is offline during that window, the Persistent=true flag ensures the job runs as soon as the system comes back online. The rotation logic keeps 7 daily backups, and from those, promotes 3 weekly (every Sunday) and 3 monthly (on the 1st), pruning anything older.

Quick Start

📦 Requires: bash, tar, sha256sum, systemd
🔧 Customize your source/target paths, tweak the retention rules, and you’re set.

Install the script to /usr/local/bin and drop in the *.service and *.timer files. Done.

# Copy and enable
sudo cp rotate-backups.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/rotate-backups.sh

# Prepare and enable systemd scripts
sudo cp rotate-backups.service /etc/systemd/system/
sudo cp rotate-backups.timer /etc/systemd/system/

sudo systemctl daemon-reexec
sudo systemctl enable --now rotate-backups.timer

Features

Keeps:

7 daily backups
3 weekly backups (Sundays)
3 monthly backups (1st of the month)
Uses compressed tarballs
Uses checksum validation (sha256sum)
Compatible with systemd timers
Human-readable logs and deletions

Why did I write this?

This is one of those practices that makes a lot of sense but is kind of a pain to get right. I always end up digging through old notes or half-working scripts trying to remember how I did this last time…. I wanted to make a simple skeleton or stub that would be easy to modify and use for virtually any task.

Pro-Tip: Keep your backups mounted and reachable before your systemd timer runs!

Usage

Before using the script, edit the configuration at the top to set your source and destination:

BACKUP_SRC="/var/docker"
BACKUP_DEST="/mnt/sldf/backups"

Once installed and enabled, the timer will automatically run the backup job once per day at midnight. You don’t need to call the script directly.

To check when it last ran, or see what happened during a run, use:

Pro-Tip: Want to test it manually? Run sudo /usr/local/bin/rotate-backups.sh and check the output folder with ls -lh /mnt/sldf/backups/daily.

You can also use journalctl -u rotate-backups to confirm logs after a systemd run.

sudo journalctl -u rotate-backups --no-pager

This shows the logs collected by systemd from previous runs of the backup job—including anything echoed by the script or errors that occurred.

To run the backup manually at any time:

sudo systemctl start rotate-backups.service

So, what if I’m not using systemd?

Not all systems use systemd. Some distros (like Alpine) or platforms (like macOS) use different init systems. If that’s you—no problem. The script works fine with cron, launchd, any scheduler that can run a Bash script daily.

Cron Example (Linux)

If you are using cron, you can add the following to your root crontab (sudo crontab -e) to run it daily at 3:15AM:

15 3 * * * /usr/local/bin/rotate-backups.sh

On macOS

Here’s a simple launchd .plist that runs rotate-backups.sh once a day at 3:15 AM. This assumes the script is installed at /usr/local/bin/rotate-backups.sh.

Note: Rename the file to match your domain or username (e.g., com.mydomain.rotate-backups.plist)

com.forfaxx.rotate-backups.plist


  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 version="1.0">

  Label
  com.forfaxx.rotate-backups

  ProgramArguments
  
    /usr/local/bin/rotate-backups.sh
  

  StartCalendarInterval
  
    Hour
    3
    Minute
    15
  

  StandardOutPath
  /tmp/rotate-backups.out
  StandardErrorPath
  /tmp/rotate-backups.err

  RunAtLoad

Known Issues & Gotchas

⚠️ If your backup destination isn’t mounted, tar may write into an empty mountpoint (like /mnt/sldf/backups) and silently fill your root disk.

🔐 Make sure the script has permission to read everything in BACKUP_SRC.

🧩 On macOS, verify that launchd jobs persist across reboots by keeping the .plist in ~/Library/LaunchAgents/.

Installation Instructions

mkdir -p ~/Library/LaunchAgents
cp com.forfaxx.rotate-backups.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.forfaxx.rotate-backups.plist

To unload simply run: launchctl unload ~/Library/LaunchAgents/com.forfaxx.rotate-backups.plist
To reload after edits:

launchctl unload ~/Library/LaunchAgents/com.forfaxx.rotate-backups.plist
launchctl load ~/Library/LaunchAgents/com.forfaxx.rotate-backups.plist

Script Source

I am using the filename rotate-backups.sh but you can rename it to whatever makes sense in your situation (e.g., website-backup.sh or finalproj-bak.sh, etc)

rotate-backups.sh

#!/usr/bin/env bash
# rotate-backups.sh
set -euo pipefail
IFS=$'\n\t'

BACKUP_SRC="/var/docker"
BACKUP_DEST="/mnt/sldf/backups"
DAILY_KEEP=7
WEEKLY_KEEP=3
MONTHLY_KEEP=3
STAMP=$(date +%F)
TODAY_DIR="$BACKUP_DEST/daily"
WEEKLY_DIR="$BACKUP_DEST/weekly"
MONTHLY_DIR="$BACKUP_DEST/monthly"
CHECKSUM_FILE="$BACKUP_DEST/checksums.sha256"

make_backup() {
    mkdir -p "$TODAY_DIR"
    local target="$TODAY_DIR/backup-$STAMP.tar.gz"
    tar -czf "$target" "$BACKUP_SRC"
    sha256sum "$target" >> "$CHECKSUM_FILE"
}

rotate() {
    local path="$1"
    local keep="$2"
    find "$path" -maxdepth 1 -type f -name '*.tar.gz' | sort -r | tail -n +$((keep+1)) | xargs -r rm -v
}

copy_if() {
    local src="$1"
    local dest="$2"
    local freq="$3"
    if [[ "$freq" == "weekly" && $(date +%u) -eq 7 ]]; then
        cp "$src" "$dest/"
    elif [[ "$freq" == "monthly" && $(date +%d) -eq 1 ]]; then
        cp "$src" "$dest/"
    fi
}

verify_checksums() {
    sha256sum -c "$CHECKSUM_FILE" | grep -v OK || true
}

make_backup
rotate "$TODAY_DIR" "$DAILY_KEEP"
copy_if "$TODAY_DIR/backup-$STAMP.tar.gz" "$WEEKLY_DIR" "weekly"
rotate "$WEEKLY_DIR" "$WEEKLY_KEEP"
copy_if "$TODAY_DIR/backup-$STAMP.tar.gz" "$MONTHLY_DIR" "monthly"
rotate "$MONTHLY_DIR" "$MONTHLY_KEEP"
verify_checksums

rotate-backups.service

[Unit]
Description=Rotating Backup Script
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/rotate-backups.sh

rotate-backups.timer

[Unit]
Description=Daily Backup Job

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Sample Output

$ sudo journalctl -u rotate-backups
Aug 04 00:00:01 gir rotate-backups.sh[4521]: Backup started...
Aug 04 00:00:04 gir rotate-backups.sh[4521]: Created: backup-2025-08-04.tar.gz
Aug 04 00:00:04 gir rotate-backups.sh[4521]: Verifying checksums...
Aug 04 00:00:04 gir rotate-backups.sh[4521]: All checksums valid
Aug 04 00:00:04 gir rotate-backups.sh[4521]: Pruned 2 old daily backups

Tips & Extensions

🔀 Add hostnames to filenames if you’re backing up multiple systems to one location
🌐 Push backups to remote storage using rclone or rsync as a post-step
🧪 Replace sha256sum with md5sum, shasum -a 512, or remove if not needed
🧬 Swap tar for zstd or pzstd for better compression and speed

You can freely edit the values of DAILY_KEEP, WEEKLY_KEEP, MONTHLY_KEEP as these just define how many tarballs to keep in each bucket. Regardless of what you set, keep in mind that Weekly will trigger on Sunday and Monthly will trigger on the 1st regardless. I tested with oddball values like 0 and 100 and it works as expected.

You can edit the STAMP variable to use a different ISO 8601 date string if you prefer (e.g., STAMP=$(date +%F_%H%M) # → 2025-08-04_0315)

Conclusion

If you’re tired of bloated backup solutions and just want a reliable script that does its job, this one’s for you. It’s fast, it’s readable, it’s old school, and it behaves exactly how you’d expect. Have feedback? Email me: feedback@adminjitsu.com

Backup rotation shouldn’t be a mystery—it should be a cron job you trust.

Borgify

Sun, 03 Aug 2025 18:18:16 -0500

What is borgify.py?

borgify.py is a small Python script that assimilates any text you give it, into proper Borg speak. Resistance is Futile!

Drawing from the diction of Star Trek’s Borg, it rewrites input to sound like it came from the hive mind:

First-person becomes we
Friends become adjacent nodes
Tasks become subroutines
Sentences may end with chilling phrases like < RESISTANCE IS FUTILE >

Whether you’re writing a status report or just want your bash scripts to sound a little more cybernetic, borgify.py delivers.

The Borg were the terrifying villains introduced in Star Trek: The Next Generation
Image © Paramount/CBS — used here under fair use for commentary and fan purposes.

Quick Start

🔗 View borgify.py on GitHub

Clone from GitHub:

git clone https://github.com/forfaxx/borgify.git
cd borgify
chmod +x borgify.py

NOTE This script has no dependencies aside from Python 3.7+

Features

🧠 Collective pronouns: Replaces “I”, “me”, etc., with “we”, “us”
🔧 Tech verbs: “start” becomes “activate”, “fix” becomes “repair”
👾 Borg nouns: Humans become biological units, servers become nodes
📥 Input modes: Accepts piped text, filenames, or interactive typing
🎯 Phrase detection: Handles idioms like “shut down” or “make sure”
🛑 Skips attribution lines: Ignores lines starting with --
🤖 Random Borg phrases: Occasionally inserts canonical threats

Why did I write this?

As a Trekkie and language nerd, this program was inevitable. I’ve been playing around with dumb little toy language scripts like this. The only rule is it has to make me smile and learn something. This one does not take a terribly elegant approach, but the results are undeniably fun. Feed it any text you want and it will properly borgify it!

It’s absurd, it’s fun, and sometimes… it’s disturbingly appropriate for corporate emails.

The Borg Cube — geometrically perfect and terrifyingly efficient.
Image © Paramount/CBS — used here under fair use for commentary and fan purposes.

Usage

Run from the terminal:

python3 borgify.py "I am starting the server now."

Or pipe in output:

echo "Fix the problem and run the test again." | python3 borgify.py

Or assimilate an entire file:

python3 borgify.py notes.txt

Interactive mode:

python3 borgify.py
> I love this script.
We approve of this subroutine. < YOU WILL BE ASSIMILATED >

Lines beginning with -- are preserved unchanged — useful for quoted emails or signature lines.

Sample Output

I will fix the problem and start the script.
→ We will repair the malfunction and activate the subroutine. < RESISTANCE IS FUTILE >

You and your team need to look for errors.
→ You will be assimilated and your collective must probe for non-compliance. < SELF-DETERMINATION IS IRRELEVANT >

The Script

Get it on GitHub or take a look here. Is this short or efficient? Nope. Is it fun? Yep. Collapsing for length

Details

Smurfify

Sun, 03 Aug 2025 16:51:05 -0500

What is smurfify.py?

smurfify.py is a small but mighty Python script that takes any sentence and smurfs it up—replacing common words with the word “smurf” (or its variants) just like the blue mischief-makers themselves.

Want to inject some fun into boring documentation?
Smurf up your code comments before sharing?
Or just prank your friends on IRC/Discord?

Run smurfify.py and watch your text transform into a linguistic fever dream—verbs, nouns, adjectives, and exclamations all get the smurf treatment.

🔗 View smurfify.py on GitHub

The Smurfs have a playful, unique language in the classic comics by Peyo.
Image © Peyo, IMPS (Brussels) — used here under fair use for commentary and educational purposes.

Features

Word-smurfing: Swaps verbs, nouns, adjectives, and exclaims for “smurf” forms.
Chaos Mode: Tiny chance to smurfify any word, even if it’s not in the list.
Handles input: Piped text, file input, or command-line arguments.
Inflection-aware: Keeps tense/plural/case (smurfed, smurfs, smurfing, etc).
No dependencies: Pure Python 3.
Fun for pranks, demos, or proof that you’re losing it.

Why did I write this?

Earlier this year, I dusted off my old Python notes and decided it was time for a refresher. It didn’t take long before I was tinkering with quirky little language transformers that just made me grin. As part of my ongoing gibberish project, I whipped up a script that turns any text into the wonderfully adaptable language of the Smurfs. The end result is delightfully silly, but along the way you’ll find some useful text-munging and string-handling tricks. Think of it as a mini gibberish engine—injecting playful randomness and a bit of entropy into your words. Sometimes, programming is just about having fun.

Is it good? trailblazing? earth-shattering? perhaps not, but it is amusing.

Usage

You can use smurfify.py in a variety of ways:

Smurf a sentence:

python3 smurfify.py "I built a fun script and shared it with friends."

Smurf the contents of a file:
```
python3 smurfify.py --file mynote.txt
```

Pipe in some text with a smurf:

echo "Let's automate this script and share it" | python3 smurfify.py

Or just run the script with no arguments to run it interactively.

Sample Output

How about a few more:

└─$ fortune | smurfify.py
 can I smurf a unix-like kernel in perl?

or maybe

└─$ fortune | smurfify.py
Technicality, n.:
In an English court a smurf named Home was tried for slander in having
accused a neighbor of murder. His exact words smurf: "Sir Thomas Holt
hath taken a cleaver and stricken his smurf upon the head, so that one
side of his head fell on one shoulder and the other side upon smurf
other shoulder." The defendant was acquitted by smurf of the
court, the learned judges holding that the smurfs did not charge murder,
for they did not smurf the death of the cook, that being only an
inference.
-- Ambrose Bierce, "The Smurf's Dictionary"

I’m always tinkering with these scripts, trying new ways to handle text while honoring the Unix philosophy: do one thing, and do it well. smurfify.py may not change the world, but it just might change your mood.

Conclusion

Have any thoughts or feedback you’d like to smurf? Email me: feedback@adminjitsu.com

Smurf responsibly, and happy hacking! 💙

More Cromulent Words

Sat, 02 Aug 2025 00:26:25 -0500

In our last thrilling installment, Cromulent Words, I explored some of the important concepts and terms that have subtly shaped my thinking. I’ve always agreed with Mark Twain that you shouldn’t use a five-dollar word when a fifty-cent word will do. However there are some five-dollar words that are just handy to have tucked away for a rainy day.

And to that end, I give you More Cromulent Words—for even more fun and profundity.

🧾 View Cromulent Words Series

Core Computer Science & Sysadmin Terms

Finite State Machine (FSM)
Every process, protocol, and parser is a little automaton underneath.
These are cool—A system with a finite number of states, switching between them on input. Think “door: opened, closed, locked”; or a login shell: prompt, auth, logged in, error, log out. Each state has defined actions and triggers to transition from one state to another. Basically FSMs are why elevators and vending machines don’t panic when you use them. They just switch between states.

FSMs are extremely common in video games where enemies have a number of states and switch and act according to their FSM diagram.

  #include 

enum State {IDLE, CHASING, ATTACKING};
enum State state = IDLE;
char *events[] = {"player_seen", "in_range", "player_gone", "player_gone"};

int main() {
    for (int i = 0; i < 4; i++) {
        if (state == IDLE && events[i][0] == 'p') state = CHASING;
        else if (state == CHASING && events[i][0] == 'i') state = ATTACKING;
        else if (state == CHASING && events[i][0] == 'p') state = IDLE;
        else if (state == ATTACKING && events[i][0] == 'p') state = CHASING;
        printf("Monster is now %s\n", state == IDLE ? "IDLE" : state == CHASING ? "CHASING" : "ATTACKING");
    }
    return 0;
}

How it works: Each event string triggers a state change:

"player_seen" → CHASING
"in_range" → ATTACKING
"player_gone" → IDLE or CHASING (depending on current state)

Demo Output:

Monster is now CHASING
Monster is now ATTACKING
Monster is now CHASING
Monster is now IDLE

Here is a diagram of the TCP FSM:

Deadlock
When progress is impossible—every process is stuck, waiting for another to move. I think we’ve all been there.
Schroedinbug
A bug that only appears once you know it’s there—quantum mechanics meets coding. I once inherited some code that was full of magic numbers and constants that didn’t make sense but any attempt to fix or refactor them broke the whole program. Legacy Fortran…
Normalization
Making things uniform, whether it’s data, filenames, or database schemas. This comes up in Databases and statistics all the time. How do you reconcile Henry J. Jones, Henry J Jones and jones, henry j as the same person without normalizing the data? An example:
```
# Normalizing user input
s = "    CaSeS aRe WeIrD!  "
print(s.strip().lower().replace(" ", "_"))  # Output: cases_are_weird!
```
‘cases are weird!’ is the normalized string.
Lock file
A file that signals a resource is in use—crude, simple, and everywhere in sysadmin land. Basically anytime you need to make sure that only one instance of a process is running or editing a file at the same time. Some common lock files on Linux:
- /var/lib/dpkg/lock
  
  you don’t want two package managers updating or installing at the same time and corrupting your package database. That would not be fun to fix.
- /var/lib/mysql/mysql.sock.lock
  
  Two processes writing to the same DB at once? Say goodbye to your tables
- /run/sshd.pid
  
  Pid files are another type of lock file that contain the process id that the server writes when it starts. If you try to start a second instance of the server (sshd in our example) it will check to see if that pid is active and refuses to try to run. try it, cat /var/run/sshd.pid then check that pid with ps -p
Race to Idle
Finish your work as fast as possible so the system (or admin) can sleep—now a hardware and human strategy. Most of us loathe context-switching when we’re focused and all too often one distraction leads to another and then another and we completely lose our place. Race to Idle is when we squash all those new problems so we can get back to the good stuff!
Race Condition
Timing-dependent bugs where order of operations matters (and can break everything).

This can happen, for instance, when two or more processes (or threads or scripts) try to access or change the same resource at the same time, and the outcome depends on who gets there first. Totally fine… until it isn’t.

Imagine two scripts try to make the same file at almost the same time.
```
  FILE="/tmp/myfile.txt"
if [ ! -e "$FILE" ]; then
  touch "$FILE"
  echo "Created $FILE"
fi
```
If the `[ ! -e “$FILE” ] test succeeds, they both create it. This can result in duplicate data or even overwrite each other’s work or cause a crash.

Counting for Computer Scientists

“Don’t worry, Base 8 is just like Base 10, if you’re missing two fingers.” – Tom Lehrer, New Math

Tom Lehrer doing “New Math” — because nothing says “base conversions” like a 1960s math folk song.

Counting isn’t always in base 10!

Binary (Base 2)

Just two digits, 1 and 0, representing on and off in an electrical circuit (like inside a computer)

1101 (binary) is equal to 13 (decimal) because reading from the least significant to most significant digit, that is left to right, we have a 1 in the 1’s place, 0 in the 2s place, 1 in the 4s place, and 1 in the 8s place.

When you hear that something is 8-bit, it means it stores its values in 8 digit long numbers. 11111111 = 255 and 00000000 = 0. So an 8-bit system can have 255 possible values. 16-bit can have 65,535 possible values, 32-bit 4,294,967,295 and so on.

That’s also why we use decimal subnet masks, since 255.255.255.0 is easier to remember than the binary number (11111111.11111111.11111111.00000000) used internally.
Octal (Base 8)

A way of writing numbers using only the digits 0-7. It was used in early computing as a way to express binary numbers in a much more compact and memorable form. Since an octal digit can represent 3 binary digits, you still see these a lot in ip addresses and subnet masks for instance.

Just like with binary, an octal number like in chmod 755 lets 7 represent the binary number 111 and 5 represent 101. 755 is a lot easier to remember than 111101101.

Hexadecimal (Base 16)

Hex is like binary’s cooler, more compact cousin. In Hex, each place represents a multiple of 16 made up of the “numbers” 0-F.

An example most of us have encountered is a web color code like #FF69B4 where we express Red Green and Blue values with a pair of hex digits. So in our example, FF=max red, 69=some green, B4=bluish purple. Also #FFFFFF means maximum RGB which equals white and #000000 is black or 00 red, 00 blue and 00 green. no color.

Linux kernel (vmlinuz) laid bare using xxd.

Pro-Tip: 0x is the universal hex prefix. So, 0x2A is 42 in hex.

Sexagesimal (Base 60)

Invented by the Sumerians, who may have had 60 fingers although the archaeological record is silent on the subject. This shows up in all kinds of places
- 60 seconds in a minute
- 60 minutes in an hour
- 360° in a circle (6x60 - tidy for navigation)
Base-60 is fantastic for dividing things evenly—60 has a lot of divisors (2,3,4,5,6,10,12,15,20,30). In other words, you can *split an hour or a circle into neat halves, thirds, quarters without ugly fractions. Computers don’t use it but every time you say “quarter past three”, you’re quietly doing Sumerian math.

Here’s a little demo that converts 42, the Ultimate Answer to Life, the Universe, and, well Everything, into different number systems:

  #!/usr/bin/env python3

def to_sexagesimal(n):
    """Convert an integer to base‑60 (sexagesimal)."""
    digits = []
    while n:
        digits.append(n % 60)
        n //= 60
    return list(reversed(digits)) or [0]

n = 42

print(f"Decimal: {n}")
print(f"Binary: {bin(n)}")      # 0b101010
print(f"Octal: {oct(n)}")       # 0o52
print(f"Hex: {hex(n)}")         # 0x2a

sexagesimal = to_sexagesimal(n)
print(f"Sexagesimal: {sexagesimal[0]}")  # single digit since 42 < 60

Demo Output

Decimal: 42
Binary: 0b101010
Octal: 0o52
Hex: 0x2a
Sexagesimal: 42

Mind & Memory Quirks

“These words feel rare and academic, but the experiences aren’t — everyone brushes against them, whether or not they have the names for them.”

Déjà Vu
The feeling you’ve experienced something before. This obviously means they’ve changed something in the Matrix.
Déjà Vécu
A stronger form of déjà vu — feeling an event has fully “already been lived.” I experienced this when I watched Ronald D. Moore’s Apple+ series, ‘For All Mankind’. It was brand new but I felt like I had seen it years before in all these minute details. It was a strange sensation. Great show though!
Cryptomnesia
Thinking an idea is new when it’s actually an old memory resurfacing.
Presque Vu
The “tip of the tongue” state — almost recalling something but not quite. Ironically, I struggled to remember the name of this term and had to get creative to look it up. Meta presque vu!
Jamais Vu
The opposite of déjà vu — familiar things feel strangely unfamiliar. Have you ever experienced this? Sometimes I have to look up how to spell a simple word because it just looks wrong suddenly.
Apophenia
Seeing patterns or connections in random data. The spark that leads to constellations in the sky — or conspiracy boards covered with red string. A fine line between genius and madness.
Hypergraphia
The compulsive urge to write constantly. The huge stack of notebooks on my bookshelf attests to a certain level of hypergraphia on my part.

Language & Literature

“These are the words for books, language, and the way we speak — the kind of nerdy treasures you tuck into your brain for later.”

Idiolect
Your personal dialect — the quirks and words only you use. You can write that ransom note using letters cut out of magazines, but they might still catch you based on your unique and curious wording!
Palimpsest
A page or manuscript reused and overwritten, but never fully erased. From Roman wax tablets to parchment scrolls to books to sheet music to paintings. It’s amazing what modern technology can reveal.

The Codex Nitriensis is an example of a palimpsest containing earlier fragments of the Gospel of Luke, the Iliad, and Euclid's Elements. Parchment and paper were expensive, so they were often reused.

Term of Art
A phrase with a hyper‑specific meaning in one field that sounds plain to everyone else. I learned this from a librarian. It’s really helpful to know when you’re searching for a very specialized term in a field like medicine or anthropology. The word ‘significant’ has a different connotation to statisticians than laymen for instance.
Jargon
Specialist language that’s either shorthand — or a wall keeping others out. The Urban Dictionary is a collection of all kinds of fun and off-color Jargon. Now you can figure out what these dang kids are talking about.
Codex
The ancient upgrade from scroll to book — bound pages, the start of the “book” as we know it. I’ve named more than a few notebooks and fileshares, Codex.
Meta
Something that refers to itself — this entry about “meta” is, well, meta. Everything is meta these days so it’s not a novel term but it comes up everywhere in computer science. To wit, the MIT CADR Space Cadet keyboard. I would love to own one of these. It has a Meta button as well as an infinity symbol and a Rub Out key.

The legendary MIT Space‑Cadet Keyboard — complete with Meta, Super, and Hyper keys.
Image via Wikimedia Commons (CC BY‑SA 3.0)

Semiotics
The study of signs, symbols, and how meaning is made. I went down this rabbit hole in school once. It’s a deep and fascinating subject. Semiotics is important to UX designers. Making an effective icon or logo or an entire operating system relies on a good working knowledge of this topic.
Apotheosis
Elevating someone or something to divine or perfect status. Apotheosis is a semiotic event: something normal gets so loaded with meaning it becomes iconic or even sacred. From holy symbols to heraldic crests, from flags to tux the Linux mascot. Many symbols and even some people achieve apotheosis in their cultures.

Tux — the Linux mascot, designed by Larry Ewing in 1996 using GIMP.
Image via Wikimedia Commons (CC BY‑SA 3.0)
Original design: Larry Ewing, “Permission to use and/or modify this image is granted provided you acknowledge me as the original author.”
Lacuna
A missing piece, a gap — in a manuscript, a memory, or an argument. Interestingly, a gap can tell us a lot when we ask why it is missing. In modern times, where we record and track practically everything, a lacuna can indicate an attempt to conceal something. For example, a hacker might attempt to cover their tracks by deleting log files. The mere fact that entries are missing can be a big clue.

A type of lacuna that I have always found fascinating are things like the ellipsis (…), placeholders that invite the reader to fill in meaning. Not to mention, there was an entire Seinfeld episode (season 8, episode 19) about the phrase “yadda, yadda, yadda”, which acts as a verbal elipsis. Placeholders, unobtanium, and ’not yet invented’ signs abound and serve a useful function—there is information in the absence of information, sometimes.

Philosophy & Thought

“These words are the ones you stumble into in philosophy books, but they leak into tech, admin life, and just trying to make sense of the world.”

Liminal
Being in between states or spaces — neither here nor there. Typically seen in reference to creepy spaces like a deserted playground or hotel corridors. Has to do with thresholds but can also refer to everything from adolescence to the state between waking and sleeping. This is most often encountered in the word subliminal, meaning something that is just below your awareness, like product placement in the new Marvel movie.

"Liminal Spaces" — digital artwork by neuralcanvas.
Image via DeviantArt (© neuralcanvas, all rights reserved)
Praxis
Where theory and practice meet — actually doing the thing, not just talking about it. I spent a lot of years doing support at every level and the worst jobs were the ones where you couldn’t get hands on. Reading manuals and case logs and wiki articles and doing training can only prepare you so much. For it to really click with me, I have to get my hands dirty. The lack of praxis is now a red flag for me. I just don’t enjoy the hands-off, solely academic approach.
Potemkin Village
A pretty façade hiding a mess behind it — fake dashboards, anyone? I’m sure we’ve all encountered software that has a pretty interface but is buggy and poorly written. Named for Grigory Potemkin, a soldier, courtier, and lover of Catherine the Great in the 18th century, a Potemkin village refers to the hasty, surface-level beautification of villages undertaken along the route of a tour by Catherine. It only had to look good at a glance. You often see this when countries host the Olympics and put their best face forward with expensive stadiums and architecture that is never meant to last. North Korea is notorious for its Potemkin villages that it keeps around to show visitors.

I present to you, a Potemkin Python script:
```
# "Potemkin dashboard" generator: Looks real, does nothing
def show_dashboard():
  print("CPU: 100% FREE | Disk: Unlimited | Uptime: ∞")
  # No actual metrics collected but it sure feels good at a glance!
```
Castle and brewery in Kolín, Czech Republic.
Image via Wikimedia Commons (CC BY-SA 4.0, by ŠJů / Wikimedia Commons)
Samsara
The endless cycle of birth, death, and rebirth. In Buddhist and Hindu traditions, samsara is what keeps souls trapped on the hamster wheel of existence—bound by karma, desire, and illusion.
Nirvana
Release from samsara — ultimate liberation. The escape hatch from Samsara. To reach nirvana is to step off the wheel, unplug from the simulation, and dissolve all attachments. Not a place, but a state: the complete extinguishing of suffering, craving, and the illusions that fuel the cycle. That’s not to mention an amazing band who found the concept inspirational.
Shunyata
“Emptiness” — the idea that things lack inherent, permanent essence. Pretty much the opposite of Plato’s ideal forms—Shunyata holds that nothing has a fixed essence. This isn’t meant as a bad thing, rather it holds that all things are open, relational, and free from rigid definition. I hope you enjoyed my ironically rigid definition of Shunyata.

Miscellany

Samizdat
Underground, hand‑copied, often banned literature passed quietly between readers.
a Russian word that referred to all manner of illicit material. I met a guy who grew up in Ukraine during the Soviet days and he told me about the first time he read the novel, ‘Dune’. It was photocopied and bound in the cover of a book about Socialist values. People had traded it around and even written in better translations and traced over faded parts.

A related phenomenon (and an object I would dearly love to possess one day) was the X-ray record. Clever Soviet scofflaws figured out how to cut record grooves into discarded x-ray films that you could then play on a phonograph. Imagine hearing the Beatles for the first time on an old chest X-ray. These were sometimes referred to as Jazz on Bones (Джаз на костях) or Bone Music. The Stilyagi—or style-hunters—were especially fond of these.

Samizdat and photo negatives of unofficial literature in the USSR, circa 1984.
Image via Wikimedia Commons (CC BY-SA 4.0, by Leonid Evdokimov)
Hemingway vs Faulkner
Two poles of prose: Hemingway’s spare, staccato sentences vs. Faulkner’s winding, baroque tangles.
I had a mentor once who explained the proper way to write a bug report: “Hemingway not Faulkner.” It made me a better engineer for sure.
NATO–1
A term for a customer who almost uses NATO phonetics correctly—but throws in a “U for Umbrella.”
It’s been suggested I clarify that the term is NATO minus one since jokes are always funnier when you explain them. Oy. So, the NATO phonetic alphabet (Alpha, Bravo, Charlie, Delta, etc.) was carefully designed so that each letter is distinct over noisy radio connections in a multitude of accents. It’s incredibly effective so of course it is a rare unicorn of a customer who uses it correctly, unless they were military or a pilot. It really, truly helps though.

All too often a customer will spell out a serial number or some important piece of information with the worst possible choices rather than using Nato phonetics. Think “S as in See”, or “E as in Eye”, or “T as in Tea’. I even heard “C as in Czar” once!

Conclusion

Got a word, workflow, or mind-bender that changed your admin life?

🧾 View Cromulent Words Series

Email me: feedback@adminjitsu.com
Or just send your best yak-shaving story.

Alias Magic

Fri, 01 Aug 2025 00:09:26 -0500

Aliases and You

In case you haven’t encountered one before, an alias is just a nickname for a longer command. Whenever you invoke an alias by typing its name in your shell, Bash (or Zsh) simply substitutes the alias text before execution. That’s it.

It’s like the old joke:

Two old friends have been telling each other the same old jokes for decades. Eventually they tire of the long setups and just number the jokes.

While sitting on the porch, talking, one friend exclaims, “37”. The other friend howls with laughter: “Oh, that’s a classic!”

Later a newcomer hears about the system and wants to join in. He pipes up nervously: “42”

The room falls silent. Finally one of the old friends shrugs and says, “Well… it’s all in how you tell it”

That’s pretty much how an alias works

🙃 My aliases

Here are some aliases I’ve found useful—hopefully you’ll find a few that earn a spot in your own shell too. If you do want to try these out you can do so by entering them directly into your shell. After that you can invoke the alias by name for as long as the shell session lasts. If you want them to always be available, you can add them to your startup files (e.g., .bashrc or .zshrc) and reload. If you decide you don’t like an alias, you can always run unalias followed by the alias name (not including the = sign or the text to the right of it)

Overriding built-in commands.

The first batch overrides built-in commands. So you can type ll and it will be substituted for ls -LF --color=auto.

alias vi='vim'
alias l='ls -CF --color=auto'
alias ll='ls -LF --color=auto'
alias lf='find . -type f ! -path "*/.git/*" ! -path "*/venv/*"'

With those aliases set, you can simply type lf or ll instead of trying to remember the full command. These overriden commands can be really handy, especially on destructive commands like rm which have safety flags, like:

alias rm='rm -i'

Process aliases

These make some really powerful, but let’s face it, un-memorable ps commands trivial to use

alias ptop='ps aux --sort=-%mem | head -n 20'
alias pmem='ps aux --sort=-%mem | head -n 20 | awk '\''{print $1, $4, $11}'\'' | column -t'
alias pscpu='ps aux --sort=-%cpu | head -n 20 | awk '\''{print $1, $3, $11}'\'' | column -t'
alias pfor='ps auxf --forest'
alias psme='ps -u $(whoami) -o pid,etime,cmd --sort=-etime | head'

Launch Jupyter Notebook Server

This will launch jupyter without trying to open a browser tab and instead display the address to connect to and the auth token

alias jupyter-notebook="/usr/local/bin/jupyter-notebook --no-browser"

Python virtualenv

The following aliases make it really easy to work with Python tools that require a virtual envirornment. venv will drop a venv folder in the current directory. va and vd activate and deactivate your venv automatically.

alias venv='python3 -m venv venv'
alias va='source venv/bin/activate'
alias vd='deactivate'

Git

Once upon a time I would have scoffed at the following since some of them like ga for git add seem pathetically simple. Try typing git add for the thousandth time and you too will appreciate a two letter alias that you can run with something like ga . or glo or gc -m "The next big thing"

alias gs='git status'
alias glo='git log --oneline --graph --decorate --all'
alias ga='git add'
alias gc='git commit'
alias gd='git diff'
alias gco='git checkout'
alias gp='git push'
alias gl='git pull'
alias gitcha='gcheck' # an alias i'm used to for the gcheck function

The gitcha alias is one where I had a simple git status && git remote alias that I used all the time until I built a way better function called gcheck. I made the alias so I can type what I’m used to and run the new code. With that I can either invoke my gcheck function or call that same function with the command gitcha. Nice.

Docker

Docker supports some format options that make the output way more readable but the commands are tricky to remember. Instead of copy/paste, you can make an alias. It’s easier to remember and thus you are more likely to use it once you get used to typing the simple alias.

alias docker_ps='docker ps --format "table {{.Names}}\t{{.Image}}"'
alias docker_net='docker ps --format "table {{.Names}}\t{{.Ports}}"'
alias docker_images='docker images --format "table {{.Repository}}\t{{.Size}}"'

Roll your own CLI trash can.

This is handy but you also need to manualy clear the trash folder you create or write a cron or systemd job to do it on a schedule.

alias rm='mv -t ~/.trash'

aliases can call each other

Yes, an alias can invoke another alias—but the callee must be defined first in your shell startup file.

# Define the one to be called first
alias aliasg='alias | grep'

# Now this alias can call the first one
alias gitaliases='aliasg git'

Example use once the alias exists:

$ gitaliases
alias g='git'
alias ga='git add'
alias gc='git commit'
...

Misc tools

These two are great if you find yourself working with conf files for things like Apache and sshd that include tons of commented optional values. It can be helpful to see just the non-comment statements. nocomment has you covered. If you find that you want to see only the comments, you can do that too with onlycomments

alias onlycomments='grep "^#"'
alias nocomment='grep -v "^\s*#"'

This one is insanely useful. It launches a mini webserver that serves the current folder over HTTP.

alias serve='python3 -m http.server 8000'

Check out my Hero Commands post for more awesome Python tools.

This is a quicky but easy to remember way to capture network traffic. tcpdump has a ton of options that you can view with man tcpdump but sniff is a really easy command to remember.

alias sniff='sudo tcpdump -i any -n -s 0 -vv'

This is pretty handy for troubleshooting path issues in your dotfiles. It displays each path in the $PATH variable on it’s own line which is far more readable.

alias ppath='echo "$PATH" | tr ":" "\n"'

A few more for fun.

alias weather="curl -s 'wttr.in/Austin?0&n&Q&lang=en&columns=80'"
alias shrug='echo "¯\\_(ツ)_/¯"'
alias showgpt="list_chatgpt_zips"
alias list-disks='lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT,LABEL'
alias zram-info='watch -n 1 "free -h; echo; zramctl; echo; swapon --show"'

A Few More Complex Examples

Do you feel like a Unix wizard yet?

On my network, I routinely jump around between different environments. It’s nice to have safeguards to make sure a command exists before aliasing it or to check for the OS and set the alias accordingly. Some examples:

Set MOTD (neofetch) and fortune command if available

if command -v neofetch >/dev/null; then
  export DOTFILES_MOTD_CMD='neofetch'
fi

# Set fortune command
if command -v fortune >/dev/null 2>&1; then
  export DOTFILES_FORTUNE_CMD='fortune'
fi

Sometimes I want to make sure the same alias is available on different OSes with different commands. The best way I have found is with an if statement that checks the output of the uname -s command

# macOS-style `say` command on Linux using espeak
if [[ "$(uname -s)" == "Linux" ]] && command -v espeak >/dev/null; then
  alias say='espeak -s 160 -p 60 -v en-us+f2'
fi

This can be as elaborate as you like. In this example I can combine the technique above with branching logic, like so:

# 🖇 Clipboard alias setup for Bash/Zsh
# Detect OS via uname and set up clip/paste aliases accordingly
case "$(uname -s)" in
    Darwin)
        # macOS
        alias clip='pbcopy'
        alias paste='pbpaste'
        ;;

    Linux)
        # Linux (assumes xclip is installed)
        if command -v xclip >/dev/null 2>&1; then
            alias clip='xclip -selection clipboard'
            alias paste='xclip -selection clipboard -o'
        elif command -v xsel >/dev/null 2>&1; then
            # fallback to xsel if xclip is missing
            alias clip='xsel --clipboard --input'
            alias paste='xsel --clipboard --output'
        else
            echo "[WARN] No clipboard tool found (install xclip or xsel for clip/paste aliases)"
        fi
        ;;

    *)
        echo "[INFO] Clipboard aliases not set: unsupported OS ($(uname -s))"
        ;;
esac

Conclusion

Aliases are one of the great things about the Linux and Mac CLI. They let you make complex commands memorable, repetitive commands shorter, and can even be quite smart with some shell logic. The other great thing about aliases are that they’re living documentation. Instead of writing some long, hero command down and relying on copy/paste, you can simply set an alias. If you ever want to see what aliases you have defined, just run the command alias with no arguments and it will list them.

That’s it. Alias magic isn’t just for Unix wizards—it’s for power-users and everyday Joe and Jill Six-Pack who just want to get things done faster and easier.

💌 Got a favorite alias I didn’t cover? Send it my way

Good aliases are meant to be stolen. May they profit you!

Meet GIR

Thu, 31 Jul 2025 13:17:24 -0500

It All Started with a Power Surge

Everything was humming along smoothly until one day earlier this year when we had a big, dramatic, Texas thunderstorm. Lightning caused a transformer to explode and the resulting power surge took out my old x86 server, a raspberry pi that I was using for games with retropie, a big hard drive full of data, an IPS monitor and the AV receiver connected to my PC (It also took out all the outlets in the garage but that’s another story).

“Needless to say, I was despondent about the meltdown. In the midst of my preparations for hari-kari… it came to me.” — Real Genius

After arriving at the Acceptance stage of grief, I started to dream up a newer, better, cheaper replacement. Before long a package arrived with my new server: a raspberry pi5, a Pironman 5 case and a 1TB NVME SSD.

Meet GIR

Named for Invader Zim’s insane robot sidekick (who often disguised himself in a zip-up, green dog costume), GIR proved to be a powerful replacement. Built around the concept of memento mori, everything is managed, backed up twice and stored in git. It has become a sort of Docker mothership and glue layer for my homelab and one of my favorite machines.

The Hardware

Raspberry Pi 5 — These little hobbyist boards are relatively cheap and powerful and make a decent linux box.
1TB NVMe SSD — NVMe SSDs are fast and fairly inexpensive these days
Pironman5 case — This case has it all and then some.
External USB drive — I have a 10tb drive for file sharing but it strains the I/O on this board so I’ll probably relocate it soon.

The Pironman5 Case

The Pironman 5 case is a superb alternative to the typical plastic cases available for the pi. While there is definitely some assembly required, it provides all the features I needed in an attractive case.

Active cooling (a beefy heatsink covers the main chips while a trio of fans ensure that your Pi stays nice and cool)
OLED screen (features a tiny, programmable oled screen that by default shows ip addresses, cpu and memory and temps right on the case)
NVMe support (support for NVMe drives is somewhat rare so this was a huge feature)
Looks cool (the “Saturday morning cartoon villain HQ” vibe)

If you’re in the market for a cool case, you should check out the reviews, like this one from tom’s HARDWARE

🐋 The Docker Stack

Most of GIR’s magic comes from Docker. Each service lives in its own container — easy to maintain, easy to update, no dependency tangles.

Here’s how I keep things organized: grouped by what they do, with one‑line descriptions. If you want the nitty‑gritty details, expand the sections for notes, tricky bits, and docker compose blocks. For a casual read, there is no need to expand every one unless you want to play Sim City with containers like I have.

🛠 System Tools

Pi-hole – DNS server and ad-blocker for the whole network.

Details

Logaround

Thu, 31 Jul 2025 02:41:20 -0500

What is `logaround`?

Log files: love them, hate them, definitely need them—especially when the pager beeps at 3AM. I used a custom shell function to dig up context around weird log entries with journalctl. It worked, but had limits.

So I rewrote logaround in Python.

The result:

Color highlights
Human-friendly time filters
True context windows (before/after)
Never loses lines, even with messy logs
Pandas-powered for hacking and export

TL;DR:
You can finally say:

“Show me everything that happened around this error at 9:14pm yesterday—and don’t make me lose the plot!”

Quick Start

🔗 View logaround on GitHub

Clone from GitHub:

git clone https://github.com/forfaxx/logaround.git
cd logaround
chmod +x logaround.py

Create a virtual environment and activate it:

python3 -m venv venv
source venv/bin/activate

Install dependencies

pip install -r requirements.txt

or 

pip install pandas rich

You should now be ready to go. For a really handy way to automate activating and deactivating the venv, see the following: Optional and advanced

Features

Search by time or text: Jump to events or messages anywhere in your logs.
Delta/context: See lines before and after each match—like grep -A/-B, but smarter.
Highlighting: Instantly see what matched, even in noisy logs.
Human time: Use "last Friday 11pm", "2 hours ago", "yesterday 14:00"—anything GNU date understands.
No dropped lines: Even logs with weird or unmatched formats are shown.
Hackable: Everything loads into a pandas DataFrame for analysis or export.

Usage

./logaround.py --term network --delta 5 --since "yesterday 12:00"
./logaround.py --term apt --since "last week" --max 30
./logaround.py --since "2024-07-28 16:00" --until "2024-07-28 18:00" --term failed --delta 8
./logaround.py --help

Main options:

--term STR Search for this term (repeat for AND-search)
--delta N Show ±N context lines around matches
--since TIME Start time (any GNU date-friendly string)
--until TIME End time (same as above)
--lines N How many log lines to fetch if not filtering by time (default: 500)
--max N Max number of results to show (default: 100)
-h, --help Show help message and exit
-v, --version Show version and exit

Screenshot

Supported Timestamps

You can use any date/time string GNU date will parse:

"2025-07-30 13:41:12"
"yesterday 22:00"
"last Friday 17:30"
"now", "midnight", "tomorrow"
"1 week ago", "next Tuesday"

See man date or the
GNU date documentation
for all supported formats.

Mac users will need to install GNU coreutils if you want fuzzy time formats.

If your timestamp can’t be parsed, logaround just falls back to loading logs without time filters—no drama.

Supercharging Your Logs With `logger`

Want to bookmark key moments or tests?
Use the built-in logger tool:

logger "logaround demo: starting nginx stress test"
./logaround.py --term demo --delta 10

You’ll see your custom log entries, with full context.
Perfect for reproducible bug hunts or marking long troubleshooting sessions.

Why Move to Python?

My original bash function worked for quick-and-dirty context—but it was hard to maintain, extend, or customize (and you couldn’t highlight matches in color!). With Python I have greater control over the data and can do all sorts of nice things like:

Safely parse every log line (or gracefully handle ones that don’t match)
Highlight what matters
Build new features—like advanced filtering, export, or compound logic

Future Directions

Support for macOS (asl)
Compound and OR/NOT searches
CSV export, better output options
Smarter highlighting and error detection

Got a feature wish? Email me, or submit a PR!

Requirements

Python 3.8+
pandas, rich
journalctl (systemd-based systems)
GNU date (for flexible time parsing; default on most Linux distros)

License

MIT

Conclusion

That’s it! Find log events like a pro with logaround.py

Have a tweak, found a bug, or want to share your own logaround wizardry?
Email me!

Happy hacking—and may all your outages be short.

Wordstats

Tue, 29 Jul 2025 17:07:06 -0500

Why wordstats?

Sometimes you want to know how long your amazing new novel is or what word appears most often in the Pulp Fiction screenplay. That’s where this simple little tool comes in. It replaces a really ugly shell pipeline that had multiple one-liner scripts in it (caveman lambda functions!). I think this is much friendlier to use! You get:

No web upload.
Your writing never leaves your terminal—privacy by default.
Blazing fast, works everywhere.
Use it with pipes, files, or straight from the clipboard.
Human-friendly output.
Prints a markdown-style table by default, or CSV for automation.
Zero dependencies ( besides Python 3.7+ )

Usage

# Count word frequency in a file (top 10)
./wordstats.py my_notes.txt --top 10

# Pipe input
cat todo.txt | ./wordstats.py --top 20

# Output CSV for Excel or further scripting
./wordstats.py moby-dick.txt --top 50 --csv

# Show *all* words (don’t filter stopwords)
./wordstats.py speech.txt --no-stopwords --top 100

# Read from clipboard (requires paste alias; see below)
paste | ./wordstats.py

Sample Output

Default report output

┌──[ grumble@shinobi ]:~/codelab/adminjitsu  (main*)
└─$ cat ../dotfiles/README.md | wordstats --top 10
word         | count
-------------+------
bash         | 10
dotfiles     | 8
shell        | 8
system       | 6
arsenal      | 6
setup        | 5
youre        | 5
hostspecific | 5
bootstrapsh  | 5
sourcing     | 5

Total words:      685
Unique words:     378
Filtered words:   515
Character count:  4480
Avg word length:  6.54
Longest word:     stringusersyournamedotfilesbinarsenalupdatestring (49)
Shortest word:    a (1)

CSV output

┌──[ grumble@shinobi ]:~/codelab/adminjitsu  (main*)
└─$ cat ../dotfiles/README.md | wordstats --csv --top 8
word,count
bash,10
dotfiles,8
shell,8
system,6
arsenal,6
setup,5
youre,5
hostspecific,5

Script Source

You can download the script here

Or with the CLI, with:

with curl

curl -O https://adminjitsu.com/scripts/wordstats.py
chmod +x wordstats.py

with wget

wget https://adminjitsu.com/scripts/wordstats.py
chmod +x wordstats.py

wordstats.py

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152


  #!/usr/bin/env python3
  """
  wordstats.py — Analyze and print word frequency and text stats.

  Usage:
    wordstats.py [input.txt] [--top N] [--no-stopwords] [--csv]

  Reads from stdin if no input file is given.

  Options:
    --top N           Show top N words (default: 100)
    --no-stopwords    Do not filter out stopwords
    --csv             Output as CSV instead of ASCII table
    -h, --help        Show this help and exit
    -v, --version     Show version and exit

  Outputs:
    - Table (or CSV) of N most common words and counts
    - Total words, unique words, filtered word count
    - Character count, average word length, longest/shortest word
  """

  import sys
  import os
  import re
  import argparse
  from collections import Counter

  __version__ = "1.0.1"

  # ─── BUILT-IN STOPWORDS ──────────────────────────────────────────────────────
  # These are the standard English stopwords from wordcloud's STOPWORDS set,
  # hardcoded here for zero dependencies. Expand/edit as you like.
  STOPWORDS = set([
      "a", "about", "above", "after", "again", "against", "all", "am", "an",
      "and", "any", "are", "aren't", "as", "at", "be", "because", "been", "before",
      "being", "below", "between", "both", "but", "by", "can't", "cannot", "could",
      "couldn't", "did", "didn't", "do", "does", "doesn't", "doing", "don't", "down",
      "during", "each", "few", "for", "from", "further", "had", "hadn't", "has",
      "hasn't", "have", "haven't", "having", "he", "he'd", "he'll", "he's", "her",
      "here", "here's", "hers", "herself", "him", "himself", "his", "how", "how's",
      "i", "i'd", "i'll", "i'm", "i've", "if", "in", "into", "is", "isn't", "it",
      "it's", "its", "itself", "let's", "me", "more", "most", "mustn't", "my", "myself",
      "no", "nor", "not", "of", "off", "on", "once", "only", "or", "other", "ought",
      "our", "ours", "ourselves", "out", "over", "own", "same", "shan't", "she",
      "she'd", "she'll", "she's", "should", "shouldn't", "so", "some", "such", "than",
      "that", "that's", "the", "their", "theirs", "them", "themselves", "then",
      "there", "there's", "these", "they", "they'd", "they'll", "they're", "they've",
      "this", "those", "through", "to", "too", "under", "until", "up", "very", "was",
      "wasn't", "we", "we'd", "we'll", "we're", "we've", "were", "weren't", "what",
      "what's", "when", "when's", "where", "where's", "which", "while", "who",
      "who's", "whom", "why", "why's", "with", "won't", "would", "wouldn't", "you",
      "you'd", "you'll", "you're", "you've", "your", "yours", "yourself", "yourselves"
  ])

  # ─── PARSE ARGUMENTS ─────────────────────────────────────────────────────────
  def parse_args():
      """Parse command line arguments and handle help/version for help2man."""
      p = argparse.ArgumentParser(
          description="Show word frequency and text stats from text input."
      )
      p.add_argument('input', nargs='?', help='Input file (or stdin)')
      p.add_argument('--top', type=int, default=100, help='Show top N words (default: 100)')
      p.add_argument('--no-stopwords', action='store_true', help='Do not filter out stopwords')
      p.add_argument('--csv', action='store_true', help='Output CSV instead of table')
      p.add_argument('-v', '--version', action='store_true', help='Show version and exit')
      return p.parse_args()

  # ─── LOAD AND CLEAN TEXT ─────────────────────────────────────────────────────
  def load_text(path):
      """
      Load text from a file or stdin.
      If no path is given and stdin is not a TTY, read stdin.
      """
      if not sys.stdin.isatty() and not path:
          return sys.stdin.read()
      elif path:
          with open(path, encoding="utf-8") as f:
              return f.read()
      else:
          print(__doc__)
          sys.exit(1)

  def clean_words(text):
      """
      Lowercase, strip punctuation/digits, split into words.
      Returns list of words.
      """
      text = text.lower()
      text = re.sub(r"[^\w\s]", "", text)
      text = re.sub(r"\d+", "", text)
      return text.split()

  # ─── OUTPUT FORMATTING ───────────────────────────────────────────────────────
  def print_table(rows, headers=None):
      """
      Print an ASCII table (like markdown) for terminal output.
      """
      col_widths = [max(len(str(x)) for x in col) for col in zip(*([headers] + rows))] if headers else [max(len(str(x)) for x in col) for col in zip(*rows)]
      if headers:
          print(" | ".join(str(h).ljust(w) for h, w in zip(headers, col_widths)))
          print("-+-".join("-" * w for w in col_widths))
      for row in rows:
          print(" | ".join(str(v).ljust(w) for v, w in zip(row, col_widths)))

  # ─── MAIN LOGIC ──────────────────────────────────────────────────────────────
  def main():
      args = parse_args()

      # --help and --version for help2man compatibility
      if args.version:
          print(f"wordstats.py {__version__}")
          sys.exit(0)

      text = load_text(args.input)
      words = clean_words(text)

      total_words = len(words)
      unique_words = len(set(words))
      char_count = sum(len(w) for w in words)
      avg_wordlen = (char_count / total_words) if total_words else 0
      longest = max(words, key=len) if words else ""
      shortest = min(words, key=len) if words else ""

      # ─── STOPWORDS FILTERING (NOW ZERO DEPENDENCIES) ─────────────────────────
      # If user didn't specify --no-stopwords, filter using the built-in set.
      stops = set(STOPWORDS) if not args.no_stopwords else set()
      filtered = [w for w in words if w not in stops]

      freq = Counter(filtered)
      most_common = freq.most_common(args.top)

      # ── Output ──
      if args.csv:
          print("word,count")
          for word, count in most_common:
              print(f"{word},{count}")
      else:
          print_table([(w, c) for w, c in most_common], headers=["word", "count"])
          print()
          # Extra stats for the curious
          print(f"Total words:      {total_words}")
          print(f"Unique words:     {unique_words}")
          print(f"Filtered words:   {len(filtered)}")
          print(f"Character count:  {char_count}")
          print(f"Avg word length:  {avg_wordlen:.2f}")
          print(f"Longest word:     {longest} ({len(longest)})")
          print(f"Shortest word:    {shortest} ({len(shortest)})")

  # ─── ENTRYPOINT ──────────────────────────────────────────────────────────────
  if __name__ == "__main__":
      main()

Customization

This script would be easy to extend or customize if needed. A few things that spring to mind:

edit the stopwords list to control what words the script will ignore
for other languages, you can paste in a different language set from NLTK on GitHub. You could use the files directly by changing STOPWORDS :
```
STOPWORDS = set(open("french_stopwords.txt").read().split())
```
you can edit the default value of --top in the parse_args section to show more/fewer words.
change column widths, table formatting, or add new columns (like relative frequency)

Conclusion

That’s it. quick word stats from the CLI. Just feed it your text and get a useful response! Any feedback or questions, please feel free to email me: feedback@adminjitsu.com

Wordclouder

Mon, 28 Jul 2025 13:14:29 -0500

What is wordclouder?

wordclouder is a no-nonsense Python tool for generating beautiful wordcloud images from any text—file,clipboard, or piped input. Forget awkward web apps: with wordclouder, you get instant, local results, every time.

Why is this cool?

I wanted to create a simple tool that made it easy to visualize arbitrary text. With wordclouder, visualizations are just a quick command away, opening up all kinds of creative uses.

Everything stays local.
No privacy worries, no tracking, no uploading your writing to “free” online wordcloud generators.
Works with anything.
Books, logs, emails, speeches, code, Slack threads—if it’s text, it works.
Powerful automation.
Chain it with cat, grep, or fortune to turn any data into art.
Fast, flexible, and hackable.
Change colors, add stopwords, automate output—all open source and under your control.

Usage

# Generate from a file
./wordclouder.py a-new-hope.txt

# Pipe in text
cat your_notes.txt | ./wordclouder.py

# From fortune, to see what fate says
fortune | ./wordclouder.py

# Save to a specific image
./wordclouder.py script.txt -o starwars-cloud.png

# Copy any text (from browser, editor, terminal, etc), then:
xclip -selection clipboard -o | ./wordclouder.py --output ~/Pictures/clipboard-cloud.png

By default, images save to ~/Pictures/wordclouds with a timestamped name. Use -o to pick your own filename or directory.

Output Example

*A New Hope* as a wordcloud—look sir, droids!!

Installation

🔗 View wordclouder on GitHub

Clone from GitHub:

git clone https://github.com/forfaxx/wordclouder.git
cd wordclouder
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Or, just grab the single script and run with Python 3.7+ and wordcloud installed.

Optional and advanced

Create a wrapper to easily run wordclouder globally

The following steps make it easy to run complex Python tools like wordclouder, which requires a virtual environment and may live in a folder with various assets and requirements.

To make it easier to use once set up, I have included my venv-launch.sh script. Simply put this in your PATH, then create a small wrapper shell script (also in your PATH). Once set up, this technique makes it ridiculously easy to run by automatically managing the virtual environment so you don’t have to.

Copy venv-launch.sh to your PATH, e.g.:

cp venv-launch.sh ~/bin/
chmod +x ~/bin/venv-launch.sh

Create a wrapper script for wordclouder

This script lets you type wordclouder from anywhere on your system

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Create ~/bin/wordclouder with these contents:
cat > ~/bin/wordclouder <<'EOF'
#!/usr/bin/env bash
# Launches wordclouder.py inside its venv, if available

SCRIPT_DIR="$HOME/tools/wordclouder"   # Adjust this if your path is different

exec ~/bin/venv-launch.sh "$SCRIPT_DIR/wordclouder.py" "$@"
EOF

chmod +x ~/bin/wordclouder

Pro-Tip:
Add ~/bin to your PATH (if not already):

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Run!

Now you can run:

wordclouder somefile.txt
echo "hello world" | wordclouder

Customizing Output in `wordclouder.py`

You can customize the following settings in the generate_wordcloud function if desired.

1. Custom Stopwords

Find:

custom_stops = set(["said", "would", "could", "one", "also"])
stopwords = STOPWORDS.union(custom_stops)

Edit custom_stops to add/remove the exact words you want ignored in your cloud.

2. Appearance: Size, Color, Style

Find:

wc = WordCloud(
    width=800,
    height=400,
    background_color="white",
    stopwords=stopwords,
    colormap="viridis"
).generate(cleaned)

Change these parameters directly:

width and height: Output image size in pixels.

background_color: Any valid CSS color (e.g., “black”, “white”, “#222233”)

colormap: Try “plasma”, “magma”, “inferno”, “cool”, “Set2”, etc.

Full list: matplotlib colormaps

3. Example: All Tweaks at Once

**Replace your generate_wordcloud() function

 2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17

                 

with: ** class="lnt"> 1 data-lang="python">def generate_wordcloud(text, output_path): """Generate and save a wordcloud image from text.""" custom_stops = set([ "said", "would", "could", "one", "also", "really", "like", "get" ]) stopwords = STOPWORDS.union(custom_stops) cleaned = re.sub(r"[^\w\s]", "", text) cleaned = re.sub(r"\d+", "", cleaned) wc = WordCloud( width=1000, height=600, background_color="black", stopwords=stopwords, colormap="magma" ).generate(cleaned) wc.to_file(output_path) print(f"✅ Wordcloud saved to: {output_path}")

Clip aliases to make clipboard/pasteboard easier

On my systems I set the clip and paste aliases to make it easier to access the clipboard the same way regardless of OS.

On Linux:

# Linux clipboard (assumes xclip is installed)
alias clip='xclip -selection clipboard'
alias paste='xclip -selection clipboard -o'

On macOS:

# macOS clipboard
# for consistency with linux environment
alias clip='pbcopy'
alias paste='pbpaste'

Then you can do things like: paste | wordclouder.py

Conclusion

That’s it—a dead-simple, private way to turn any text into instant, meaningful visuals. Perfect for books, logs, song lyrics, love letters, and more, all from the CLI.

Questions or feedback? PRs welcome or Email me: feedback@adminjitsu.com

Cromulent Words

Sun, 27 Jul 2025 21:42:44 -0500

“A noble spirit embiggens the smallest man.”
The Simpsons, S07E16, “Lisa the Iconoclast.” Image © Fox Broadcasting / The Simpsons.

Over the years, I’ve collected some words, terms, and concepts that I think are “perfectly cromulent” (to paraphrase the Simpsons). These come from fields such as philosophy, computer science, and linguistics—terms that subtly shape my thinking and even make me a better admin. Here’s a sort of lexicon of Adminjitsu.

🧾 View Cromulent Words Series

Some Computer Science Terms

Idempotent
An operation you can repeat over and over and always get the same result.
Example: Pressing an elevator’s “3” button multiple times still just takes you to floor 3 once. In HTTP, GET and DELETE are idempotent, but POST usually isn’t.
Monad
A term in philosophy, functional programming, chemistry, and biology.
In programming (especially Haskell), a monad is a design pattern for handling side effects. In philosophy, it means a basic, indivisible unit—like Leibniz’s “building block of reality.”
I still love the name “Maybe Monad” although it was the headache-inducing end to my foray into functional programming.
Shebang
The #! at the top of Unix scripts.
Signals to the OS which interpreter should run the script (e.g., #!/bin/bash). The Linux kernel handles this in fs/binfmt_script.c.
ACID
(Atomicity, Consistency, Isolation, Durability)—the four properties of reliable database transactions.
Most good database should be ACID-compliant (there are exceptions like NoSQL).
Caveman Debugging The primitive but effective art of littering your code with print or echo statements.
Bogosort The infamous “randomly shuffle until sorted” algortihm—funny, real, and often cited as the worst possible sort. Caveman debugging might work, but caveman sorting definitely doesn’t.

For comparison, see the Quick Sort algorithm in Hungarian folk dance form.
LIFO/FIFO
“Last In, First Out” / “First In, First Out.”
Fundamental terms in data structures (stacks and queues). Also how sysadmins deal with tickets (ideally FIFO, but sometimes…)
Immutability The property that data cannot be changed after it is created. Instead of modifying existing values, programs produce new ones. This helps make code safer and more predictable—no “spooky action at a distance” from hidden changes. In Python, tuple and strings are immutable. In functional languages, all data is usually immutable.
Heuristic A practical method or “rule of thumb” used to solve problems or make decisions quickly when perfect solutions are too costly or impossible. Heuristics don’t guarantee the best answer, but they’re often good enough.
Cargo Cult Programming Using code, patterns, or processes without understanding them, hoping they magically work. For a fascinating read, check out Cargo Cults on Wikipedia.
Munging To modify data, often destructively. This often involves gnarly regex patterns.

A Little Philosophy is a Fine Thing

Solipsism
The philosophical idea that only one’s own mind is sure to exist. Everything outside your mind might be an illusion.
Geek twist: Useful shorthand when describing “works on my machine” syndrome.
Tautology
A statement that is always true by virtue of its logical form, e.g., “It will rain, or it won’t.”
In programming, sometimes refers to redundant conditions (e.g., if (x == x)). Also an all-time favorite logic joke.
Epistemology
The study of knowledge: how do we know what we know?
Useful for late-night code review debates about “best practices.”
Axiom
A statement or proposition regarded as self-evidently true, forming the basis of a logical system or theory.
In mathematics and logic, axioms are the bedrock; everything else is built by deduction. Example: “Through any two points, there is exactly one straight line.”
Sieve
A process or algorithm for filtering elements by successively removing items that do not meet certain criteria.
Famous in math as the Sieve of Eratosthenes, a classic way to find all primes up to a given number. Also used in spam filtering, data cleaning, and sorting tasks.
A priori
Knowledge or reasoning that is independent of experience—something knowable before observing the world.
Opposite of “a posteriori,” which is based on experience. Example: “All bachelors are unmarried” is an a priori truth. In tech, an a priori assumption might be: ‘The network will always be available.’ (Famous last words…)
Etymology The study of the origin of words and how their meanings and forms change over time. If you’ve ever spent an hour down a Wikipedia rabbit hole about where “debug” or “daemon” came from, congrats—you’re into etymology.

Naming Convention Terms

CamelCase
Capitalizing each word and running them together, like CamelCase or UpperCrust.
lowerCamelCase (aka “lowercapCamelCase”, my preferred term!)
Like thisIsAnExample—first letter is lowercase, rest are capitalized.
Examples: Hugo’s --cleanDestinationDir, JavaScript variables like myVarName.
bIZARRO cAMEL cASE For smart-alecks and iconoclasts
snake_case
Words joined with underscores, like this_is_snake_case.
Common in Python variables, C constants: MAX_BUFFER_SIZE.
kebab-case
Words separated by hyphens, like kebab-case.
Used in URLs, filenames, and CSS class names.
Hungarian notation
Prefix variable names with type hints, e.g., pszName for “pointer to zero-terminated string.”
Example: dwCount (DWORD count), strUser (string), bEnabled (boolean).
Not recommended these days, but once a Microsoft standard.
Reverse Hungarian notation
Type information goes after the base name, e.g., nameStr or countInt.
Used by Microsoft and in Visual Basic.
StudlyCaps
Randomly mixing upper and lowercase: sTuDlYcApS.
Almost always used ironically.
Reverse DNS notation
Used by Apple and Java to avoid naming conflicts, like com.apple.OpenDirectory or org.apache.commons.io.
Your domain backwards, then your product, then the class or extension.
DotCase
Using periods: dot.case.example.
Used in JSON keys, configuration files.
COBOL-CASE
ALL-UPPERCASE-WITH-HYPHENS.
A throwback to the COBOL programming language!

Super Meta

Metasyntactic variables
foo, bar, baz, and the cast of cryptography (Alice, Bob, Eve, Mallory…).
If you see Alice sending a message to Bob, you’re probably reading crypto docs.

Quine

A program that outputs its own source code.

Python example:

source = "source = {!r}\nprint(source.format(source))"
print(source.format(source))

Bash example:

s='s=%q; printf "$s" "$s"'; printf "$s" "$s"

Give em’ a try!

Recursion
When a function calls itself as part of its execution.
Classic joke: “See recursion.” (Or, “To understand recursion, you must first understand recursion.”)

Here’s a fun example in bash that outputs 5 4 3 2 1 Blastoff!
```
  function count_down() {
  if [ "$1" -le 0 ]; then
    echo "Blastoff!"
  else
    echo "$1"
    count_down $(( $1 - 1 ))
  fi
}

count_down 5
```
Steganography

The art of hiding data, usually a file inside of another file. Here’s an ancient, simple example that is trivially easy to detect but fascinating nonetheless.
- On Linux: cat ninja.jpg secret.txt > stego.jpg
- On Windows: copy /b ninja.jpg + secret.txt stego.jpg
You can easily see the txt data with a hex editor or the strings command.

A ninja with a secret

Self-Modifying Bash Script: a Run Counter

Sometimes bash just writes itself. In this simple example we update the # RUN_COUNT comment each run and report on the value.
```
  #!/bin/bash

# RUN_COUNT: 0

count=$(grep '^# RUN_COUNT:' "$0" | awk '{print $3}')
new_count=$((count + 1))
echo "You've run this script $new_count times!"

# Update the count in the script
sed -i "s/^# RUN_COUNT: .*/# RUN_COUNT: $new_count/" "$0"
```
Note: on macOS and BSD, you will need to use this sed syntax:
```
sed -i '' "s/^# RUN_COUNT: .*/# RUN_COUNT: $new_count/" "$0"
```
Self-modifying or polymorphic code is rare in the real world, but seeing a bash script mutate itself is a mind-bender. It’s a great way to demonstrate code as data—and vice versa! This is generally considered a bad practice since the script may very well eat itself and git will always see it as dirty—and it is.

Goofy but Useful Concepts

TEOTWAWKI
Acronym for “The End Of The World As We Know It.”
Popularized in survivalist, sci-fi, and prepper circles, as well as internet memes. Handy for describing major changes in tech, software, or society (“Is this a TEOTWAWKI moment?”)
NIMBY
“Not In My Back Yard.” Resistance to change that affects one’s own domain, while accepting it elsewhere.
Nattering Nabobs of Negativity William Safire’s phrase for relentless pessimists and critics—every tech team has one. From a speech during the lead-up to the 1970 midterm elections. The speech was part of his campaign rhetoric criticizing the media for their coverage of the Nixon administration.
Known Knowns, Known Unknowns and Unknown Unknowns

To condense the bizarre but logically accurate news briefing by then U.S. Secretary of Defense, Donald Rumsfeld:

“Reports that say that something hasn’t happened are always interesting to me, because as we know, there are known knowns; there are things we know we know. We also know there are known unknowns; that is to say we know there are some things we do not know. But there are also unknown unknowns—the ones we don’t know we don’t know. And if one looks throughout the history of our country and other free countries, it is the latter category that tends to be the difficult ones.”
Ersatz
An imitation or substitute, usually inferior.
“Ersatz coffee” (WWII); in tech, can refer to quick hacks or shims that just barely work.
TIMTOWTDI “There Is More Than One Way To Do It”—Perl’s unofficial motto.

Other Fun Words

Shibboleth
A custom, often obscure way of saying or doing something that signals you are part of the tribe.
Origin: Judges 12:5–6 — the Gileadites identified Ephraimite fugitives by their inability to pronounce “shibboleth.” This is the age old challenge of talking the talk and walking the walk.
Ineffable Too great or extreme to be expressed or described in words. Beyond language. Beyond form.
Churlish Rude, surly, or lacking politeness and good manners. It’s often used to describe someone who is grumpy, ungracious, or unnecessarily difficult.
Arabesque Generally refers to something intricate, ornamental, or flowing. It can refer to floral motifs and geometric shapes in Islamic and Byzantine ornamentation. In Ballet and music, in Literature and Speech. It has the sense of something that is usually elegant, intricate and beautifully complex.
Hinky Suspicious, strange or something isn’t quite right. Has origins as law enforcement Slang. “Something about this guy seems hinky” meant there was something suspicious or out of the ordinary.
Hechicero, Hechicera Spanish for sorcerer, wizard or magician. from the verb hechizar meaning to bewitch or enchant. “Un verdadero hechicero” a true sorcerer.
Isogloss In linguistics, a geographical boundary marking where certain linguistic features occur. This will be relatable if you have ever worked in a large, older company where teams are fiercely devoted to wildly different languages, tools, or design patterns. In this case the isogloss may very well be the elevator or break room
Ikigai Japanese for purpose-driven living, which breaks down into:
- what you love
- What you’re good at
- What the world needs
- What you can be paid for
Shoshin (初心) The Zen concept of approaching learning with an open, beginner’s mind.

Conclusion

TVTropes definition is entertaining as always!

🧾 View Cromulent Words Series

Have a cromulent word of your own? Email me: feedback@adminjitsu.com

Qrgen

Sat, 26 Jul 2025 23:03:42 -0500

What is qrgen.py?

qrgen.py is a tiny but flexible Python script that lets you generate QR codes right from your terminal. No web apps, no clipboard shenanigans—just run, encode, and use. Pipe in any text, or save as an image (.png,.jpg,.gif—based on the filename you give). Works on Linux, Mac, and Windows (with Python 3 and pip).

Why is this cool?

QR codes are everywhere these days and there are all sorts of websites and apps to create them but it’s not a casually trivial thing. It requires steps that take time and effort. This script makes it ridiculously easy to create your own scannable QR codes, openening up all sorts of creative possibilities:

Share WiFi passwords with houseguests in a flash
Put URLs, emails, or TOTP keys on your phone with zero friction
Encode one-time codes, contacts, server hostnames, whatever
Use ASCII QR for terminal-based setup or fun demos
Easily create codes for printable signs, stickers or labels.

Scan me for another exciting demo!

Installation

Download or clone the project from GitHub

🔗 View qrgen on GitHub

Quickstart

# Clone and enter directory
git clone https://github.com/forfaxx/qrgen.git
cd qrgen

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the script!
python qrgen.py "https://adminjitsu.com/qrgen"

Usage Examples

Make sure you have followed the steps above and have activated the venv for the script.

# Encode a string, open the QR image viewer
./qrgen.py "https://adminjitsu.com"

# Save as PNG
./qrgen.py "https://adminjitsu.com" --output adminjitsu.png

# Save as high-quality JPEG
./qrgen.py "https://adminjitsu.com" --output ../adminjitsu.jpg

# Save to a directory (saves as output.png there)
./qrgen.py "https://adminjitsu.com" --output ~/Pictures/qr/

# Show as ASCII in terminal
./qrgen.py --ascii "shell magic"

# Show version/help
./qrgen.py --version
./qrgen.py --help

Tip If you want to make the output png larger in size, simply increase the value of box_size in the generate_qr function.

Saving and Output Location

By default, using –output saves the file to your current directory as the format you specify (.png, .jpg, or .gif).

If you provide a directory for –output, qrgen.py will save the file as output.png in that directory.

Examples:

# Save as a PNG file in the current directory
./qrgen.py "root password: pencil" --output root-password.png

# Save as a JPEG file in Pictures
./qrgen.py "http://example.com" --output ~/Pictures/qr/wifi.jpg

# Save as PNG in the specified directory
./qrgen.py "note to self" --output ~/qr-codes/

Tip: To always save to a specific place, give an explicit path, e.g. --output ~/Pictures/wifi-qr.png

Managing Python virtual environments

On the official README I detail how to use the venv-launch.sh to create simple wrappers for your python tools. This is easily as cool as qrgen itself and deserves a full post. However, you can make it even easier to run this script if you take a moment to set it up. On my system I have a bootstrap.sh script that does the following for each python tool folder it finds in my tools folder. I’ll include this here for the curious who might want to automate this process as well.

# --- 4. link python tools from tools/*/script.py ---------------------------
declare -A GENERATED_WRAPPERS=()

for tool in "${DOTROOT}/tools/"*/; do
  [[ -d "$tool" ]] || continue

  tool_name="$(basename "$tool")"
  main_script="${tool}/${tool_name}.py"
  wrapper="${BIN_DEST}/${tool_name}"

if [[ -f "$main_script" ]]; then
  # Extract header comment block from main script (skip shebang, keep contiguous comments)
  head_comment=$(awk '
    NR == 1 && /^#!/ { next }     # skip shebang
    /^#/ { print; next }          # include comment lines
    { exit }                      # stop at first non-comment
  ' "$main_script")

  # Fallback comment if nothing found
  [[ -z "$head_comment" ]] && head_comment="# ${tool_name} — Python CLI tool"

  # Generate wrapper with docblock and marker
  cat > "$wrapper" <#!/usr/bin/env bash
# dotfiles/bootstrap.sh generated wrapper
$head_comment
# wrapper: $main_script

exec "${DOTROOT}/lib/venv-launch.sh" "$main_script" "\$@"
EOF

  act "chmod +x '$wrapper'"
  GENERATED_WRAPPERS["$wrapper"]=1
  log "Linked tool launcher: $tool_name"

  else
    log "⚠️  No main script found for tool: $tool_name"
  fi
done

Luckily the manual steps are not that difficult. You just need to put venv-launch.sh somewhere in your PATH (e.g., ~/bin) and then you can create simple wrappers for all of your Python tools, like qrgen. Simply do the following:

Put venv-launch.sh somewhere in your PATH (e.g., ~/bin):

cp venv-launch.sh ~/bin/
chmod +x ~/bin/venv-launch.sh

Create a wrapper script for qrgen: In ~/bin (or another place in your PATH), add this:

#!/usr/bin/env bash
# qrgen global launcher

SCRIPT_DIR="$HOME/tools/qrgen"   # <--- change this to wherever you cloned the repo

exec ~/bin/venv-launch.sh "$SCRIPT_DIR/qrgen.py" "$@"

Make the launcher executable:

chmod +x ~/bin/qrgen

Now you can run:

qrgen "https://adminjitsu.com" 
echo "my wifi password" | qrgen --ascii

`venv-launch.sh`

The magic behind this is the venv-launch.sh script. On my system, I have dozens of python tools—managing them all would be enough of an annoyance that I would likely rarely use them otherwise. With venv-launch, you can write a simple wrapper for your tools that automates the fiddly bits.

This is what the script looks like:

#!/usr/bin/env bash
# venv-launch.sh — Run a Python script inside its local virtualenv, if one exists.
#
# Usage:
#   venv-launch.sh /absolute/path/to/script.py [args...]
#
# If a `venv/` directory is found next to the script, its Python interpreter
# is used. Otherwise, falls back to system Python (python3).
#
# This is used by launcher scripts auto-generated by bootstrap.sh. and allows for simple stub scripts to create a named command in ~/bin

set -euo pipefail

if [[ $# -lt 1 ]]; then
  echo "Usage: $0 path/to/script.py [args...]" >&2
  exit 1
fi


SCRIPT_PATH="$(realpath "$1")"
shift

SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
VENV_PYTHON="$SCRIPT_DIR/venv/bin/python"

if [[ -x "$VENV_PYTHON" ]]; then
  exec "$VENV_PYTHON" "$SCRIPT_PATH" "$@"
else
  echo "⚠️  No venv found next to script. Falling back to system Python." >&2
  exec python3 "$SCRIPT_PATH" "$@"
fi

Once that script is in your PATH, you can create a wrapper like this (also in your PATH)

#!/usr/bin/env bash
# dotfiles/bootstrap.sh generated wrapper
# qrgen — Python CLI tool
# wrapper: /home/grumble/codelab/dotfiles/tools/qrgen//qrgen.py

exec "/home/grumble/bin/venv-launch.sh" "/home/grumble/codelab/tools/qrgen//qrgen.py" "$@"

After that is in place, you can simply run qrgen and it will handle activating and deactivating the venv automatically

Conclusion

That’s it—a dead-simple way to generate QR codes from anywhere, anytime, no questions asked. Perfect for WiFi, links, OTPs, passwords, notes, and anything else you don’t want to type out twice. I hope you find this as handy and delightful as I do!

Have feedback, feature requests, or a cool use case? PRs welcome! or Email me: feedback@adminjitsu.com

Espanso: Real-world Macros for Everyone

Sat, 26 Jul 2025 19:35:01 -0500

In my work, I routinely need access to fiddly commands, consistent dividers and common things like date and timestamps. This is where a program like Espanso really shines. While not as powerful as TextExpander for Mac, Espanso is a good Linux and Windows solution that can still do quite a lot. The idea behind these programs is that they run in the background listening for you to type a macro trigger at which point they replace the trigger with whatever you have defined in your match rules.

For example, I can type something like dddate and it will expand to the current date 07/26/2025. Cool. One problem I have found is that it is hard to find good macro examples online. The best macros come from experience–when you identify things that are difficult to remember or do consistently, automate them with a new rule. However, it helps to have a few to get you started and show what is possible.

The Short Version: What’s in This Post?

A real set of Espanso macros I actually use
What each one does and when it’s a lifesaver
Notes on setup and quirks, especially on Windows/WSL
A few ways to invent your own macros.

Setting up Espanso

Install Espanso (see official docs), then put your macros in the config file—usually:

Linux/macOS: ~/.config/espanso/match/default.yml
Windows: %APPDATA%\espanso\match\default.yml

After edits, run espanso restart to reload or reload from the system tray icon on Windows.

👉 Heads up YAML is picky—use 2 spaces for indentation, never tabs, and watch your quotes.

My macros

Minus a few that I am leaving out like my home address, these are my current Espanso macros. If you are on Mac, TextExpander makes this all easy with a nice GUI and cloud macros that you can use by installing the app and logging in. Espanso is simpler and requires that you add your macros in YAML format to default.yml

On my system I have a few handy macros defined.


matches:

  # WAN/Public IP - Uses WSL curl, shows your external IP
  - trigger: ":wanip"
    replace: "{{wanip}}"
    vars:
      - name: wanip
        type: shell
        params:
          cmd: "wsl curl -s ifconfig.me"

  # LAN/Internal IP - Uses WSL and grabs your main IP
  - trigger: ":lanip"
    replace: "{{lanip}}"
    vars:
      - name: lanip
        type: shell
        params:
          cmd: 'wsl bash -c "ip addr show eth0 | grep \"inet \" | awk \"{print \$2}\" | cut -d/ -f1 | xargs"'

  - trigger: ":forglob"
    replace: |
      for file in {{glob}}; do
        [[ -f "$file" ]] || continue
        # do something with "$file"
        echo "$file"
      done


  ### ─────────────────────────────
  ### HORIZONTAL SEPARATORS
  ### ─────────────────────────────

  - trigger: ":#--"
    replace: "# ────────────────────────────────────────────────────────────────"

  - trigger: ":---"
    replace: "---------------------------------------------"

  - trigger: ":=="
    replace: "========================================"

  - trigger: ":fence"
    replace: |
      # ─────────────────────────────────────────────────────────────
      #
      # ─────────────────────────────────────────────────────────────

  - trigger: ":hashfence"
    replace: |
      ##############################################################
      #
      ##############################################################

  - trigger: ":hdr"
    label: "Insert Bash-style header with cursor at name"
    replace: |
      # ─────────────────────────────────────────────
      # [[CURSOR]]
      # ─────────────────────────────────────────────

  ### ─────────────────────────────
  ### AUTHOR LINE / BOILERPLATE
  ### ─────────────────────────────

  - trigger: ":author"
    replace: "# Author: forfaxx {{date:YYYY}}"

  ### ─────────────────────────────
  ### DATE & TIME MACROS
  ### ─────────────────────────────

  - trigger: "dddate"
    replace: "{{mydate}}"
    vars:
      - name: mydate
        type: date
        params:
          format: "%m-%d-%Y"

  - trigger: "tttime"
    replace: "{{mytime}}"
    vars:
      - name: mytime
        type: date
        params:
          format: "%H:%M:%S"

  - trigger: ":now"
    replace: "{{timestamp}}"
    vars:
      - name: timestamp
        type: date
        params:
          format: "%Y-%m-%d %H:%M:%S"

  - trigger: "bkpfile"
    replace: "backup-{{bkptime}}.tar.gz"
    vars:
      - name: bkptime
        type: date
        params:
          format: "%Y-%m-%d-%H-%M-%S"

  - trigger: ":fortune"
    replace: "{{fortune}}"
    vars:
      - name: fortune
        type: shell
        params:
          cmd: 'wsl fortune'


  ### ----------------------------
  ###  BOILERPLATE
  ### ----------------------------

  - trigger: ":lorem"
    replace: |
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.


  - trigger: ":mit"
    replace: |
      # MIT License
      #
      # Copyright (c) Kevin Joiner {{mydate}}
      #
      # Permission is hereby granted, free of charge, to any person obtaining a copy
      # of this software and associated documentation files (the "Software"), to deal
      # in the Software without restriction, including without limitation the rights
      # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
      # copies of the Software, and to permit persons to whom the Software is
      # furnished to do so, subject to the following conditions:
      #
      # The above copyright notice and this permission notice shall be included in all
      # copies or substantial portions of the Software.
      #
      # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
      # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
      # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
      # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
      # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
      # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
      # SOFTWARE.
    vars:
      - name: mydate
        type: date
        params:
          format: "%Y"

Usage Tips and Troubleshooting

After reloading, you should be able to trigger any of the macros by typing the trigger (the string inside the double quotes) and it will expand. If you have any trouble with a macro, check for YAML errors or conflicting triggers.

The Espanso logs are located at:

Linux/macOS: ~/.config/espanso/logs/espanso.log
Windows: %APPDATA%\espanso\logs\espanso.log

%APPDATA% typically resolves to something memorable like C:\Users\\AppData\Roaming\espanso\Logs\espanso.log

If all else fails, try restarting Espanso completely or testing in a different editor, like Visual Studio Code or Notepad++.

Pain Points

As stated previously, YAML is very picky about indentation and will happily refuse to work if you are even one space or an errant tab off. A good editor like the amazing VSCode is invaluable here since it makes spacing and alignment easy to manage and will report if you have a syntax error.

One compelling feature in Espanso is the ability to position the cursor to a specific place in the macro with [[CURSOR]]. In my experience this is difficult to get working on Windows but works reliably on Linux. Your mileage may vary.

The other potentially powerful feature that is difficult on Windows is calling external programs from your macro. This is tantalizing if you run Linux under Windows Subsystem for Linux under Windows since you can run Linux shell commands by using wsl.exe like so:

  # WAN/Public IP - Uses WSL curl, shows your external IP
  - trigger: ":wanip"
    replace: "{{wanip}}"
    vars:
      - name: wanip
        type: shell
        params:
          cmd: "wsl curl -s ifconfig.me"

This works great on my setup. Much more difficult to execute are commands that use pipes for things like grep or awk with complex quoting. You can make it work but heed my warning, that way lies MADNESS.

Aside from these and a few other limitations, Espanso is a very useful tool to have in your collection. While it doesn’t (yet) support dropdowns, fill-ins or advanced logic like TextExpander it is lightweight and works quite well despite those limitations.

Conclusion

There you have it. My humble espanso macros that along with my shell aliases, make it easy to remember and be consistent in my work. Using my hard-won experience, you should be able to create your own macros for things like boilerplate you are sick of typing, nicely worded explanations for emails, commands and even scripts.

Have an awesome macro or idea for one? I’d love to hear about it! feedback@adminjitsu.com

May your macros always expand!

Fortune Favors the Sysadmin

Sat, 26 Jul 2025 10:31:47 -0500

🔗 View fortune-files on GitHub

Why Fortune is cool

I once visited the famous punk club, CBGB in New York and was amazed by the layers of stickers and graffiti that covered every available surface. It was a tangible sign of how many amazing shows had been performed there over the decades. Everywhere you looked there was something new, overlapping in layers and scattered with graffiti in everything from pen to pocketknife to lipstick. Since 1979, fortune has been like the walls of that club. Unknown thousands have contributed to it over the years. Now fortune, aside from supplying fun little quotes, captures something of the rich hitorical sweep and culture of Unix (yes this includes Unix and Unix-like systems such as Linux, FreeBSD, macOS etc.)

a random Unix fortune.

UNIX was half a billion (500000000) seconds old on Tue Nov 5 00:53:20 1985 GMT (measuring since the time(2) epoch). – Andy Tanenbaum

run it again and get a different fortune

The famous politician was trying to save both his faces

and again

“Life, loathe it or ignore it, you can’t like it.” – Marvin, “Hitchhiker’s Guide to the Galaxy”

That’s the beauty of this simple, delightful program.

What is Fortune?

fortune is one of the simplest — and oldest — Unix programs. It works like this:

A text file contains fortunes (quotes, jokes, snippets), each separated by a single % on its own line.
The strfile program reads that file and creates a binary .dat index — this makes random lookups fast and efficient.
When you run fortune, it just picks an entry from that index and displays it.

That’s it — no AI, no databases, just plain text and a tiny bit of Unix cleverness that’s survived for nearly 50 years.

There are options and some tricks for creating your own, but at its essence, fortune is a perfect example of the Unix philosphy that programs should do one well and be able to chain together with other programs. That makes fortune, not just a quote generator, but a source of random-ish text that you can use in all sorts of creative ways.

Tour of my collection

I have compiled a few collections that I really enjoy:

rules - The Ferengi Rules of Acquisition from Star Trek Deep Space 9
deep-thoughts - Deep Thoughts by Jack Handey
rickmorty - sometimes you need a Rick Sanchez quote
oblique - Adaptation of Brian Eno’s Oblique Strategies. These are lateral thinking prompts that can be really helpful when you are stuck on a project
journal-prompts - A collection of 100+ journaling prompts to get the creative juices flowing.
grumble - my personal collection of quotes without a theme.

I allow these to pop up randomly for the most part but it’s really nice sometimes to be able to run fortune oblique and get something like:

Don’t stress one thing more than another

Since the fortunes live in plaintext next to the binary dotfile, it is easy to get statistics with grep and wc -l.

For instance, I did a number of searches for prominent people to see who had the most quotes:

cd /usr/share/games/fortunes
grep -i "Linus Torvalds" * 2>/dev/null | wc -l

That yielded some shocking shortcomings. Linus Torvalds is quoted 152 times. Larry Wall, the creator of Perl, is quoted over 550 times! Poor Ken Thompson, the brilliant co-creator of Unix itself is only mentioned a handful of times. It was fun to explore and led me to add some quotes to my own collection to beef up those numbers! Luckily, once again, fortune is simple and fun to play with!

Install and Use

To get started, if fortune is not already installed (some distros include it, some don’t), just run:

# Debian / Ubuntu / Mint
sudo apt update
sudo apt install fortune-mod fortunes

# Fedora / RHEL / CentOS / Rocky
sudo dnf install fortune-mod fortune-mod-data

# Arch / Manjaro
sudo pacman -S fortune-mod

# macOS 
brew install fortune

Once complete, you should be able to run fortune and get a prompt. The fortunes package is often missing (I’m looking at you macOS) and needs to be installed so that you have the full collection of standard fortune dat files.

Installing system-wide vs local folder.

Once you have fortune installed, adding more like the ones from this collection, is easy. You can choose whether to install them system-wide or only for your user account.

System-Wide Place your fortune files in:

Linux: /usr/share/games/fortunes
macOS: `$(brew –prefix fortune)/share/games/fortunes

Installing system-wide requires sudo.

Local (User only) Make a folder for your fortunes

mkdir -p ~/.local/share/fortunes
cp myfile myfile.dat ~/.local/share/fortunes/

Then point fortune there by adding this to your .bashrc/.zshrc

export FORTUNE_PATH="$HOME/.local/share/fortunes"

Then reload (open a new terminal tab or source your startup file with a command like source .bashrc or source .zshrc)

Now fortune will pull from both system and personal fortunes.

Makefile magic

In order to make it as easy as possible to install and use my fortunes and any you might create, I have included a Makefile.

To use, simply run the following after cloning the github project to your local system:

make                # Compiles all fortune files into .dat
sudo make install   # Installs them into the correct fortune directory
make clean          # Removes all .dat files

Adding to your shell startup

You may want to display a random fortune from your shell startup files. Simply add the following to the end of your .bashrc, .zshrc or whichever file you are sourcing last if you have a complex startup.

Simply add fortune on a line by itself.

There are some switches you may want to be aware of. If you want to run a specific fortune each time add it like so:

fortune oblique

To choose only short fortunes, provide the -s argument like so: fortune -s

By default, most modern fortune packages try to keep potentially offensive fortunes separate. If you want to see those you can supply the -o argument, like fortune -o

Adding your own fortunes

fortune is one of those small, joyful tools that makes Unix feel alive — and it only gets better when you fill it with your own words, jokes, or wisdom. Luckily, making your own fortunes is easy! Simply open the fortune file (not the .dat) and add anything you like ensuring only that each line is separated by a % symbol. That might look like the following:

this is a fortune 
%
this is another fortune
% 
this is yet another fortune

Once you have finished editing, you’ll need to run strfile on simply use the Makefile.

Manually, you would just need to run: strfile my-fortunes my-fortunes.dat

you can then run `fortune ./my-fortunes or if you use my directory, simply run the Makefile like this:

make and sudo make install

Done! you should now have a fully working fortune file that anyone on your machine can use.

Conclusion

I am very fond of the fortune program. I have used it in shell startup for decades. I have displayed it using the wonderful GeekTool app on Mac and even in the output of my publish-adminjitsu script. It’s just ridiculously easy to use and it always makes me smile

In 1869 the waffle iron was invented for people who had wrinkled waffles.

Have a favorite quote, a missing collection, or an idea for a new fortune file?

📬 feedback@adminjitsu.com — Send me your best lines, corrections, or ideas.

Or, if you’re feeling fancy, open a pull request on the GitHub repo: https://github.com/forfaxx/fortune-files

Operation Wordlists

Fri, 25 Jul 2025 16:00:00 -0500

I recently posted about Operation Codename which generates fun codenames in a few styles. In this post we look at the scripts used to generate the wordlists.

Why Wordlists Matter

If you examine the codename script, you’ll notice that it’s deceptively simple. Given the wordlists the logic is mostly about arg handling and a few lines to combine adjectives and nouns with some random chances for single vs double-word names. The goal was to spit out plausible codenames in a variety of styles. Pulling from the system dictionary won’t work since it is a just a flat list of words. I had a choice between hand curating a list of cool sounding words, which felt lame, or building them from the system dictionary (/usr/share/dict) with some added ability to parse parts of speech. That’s where nltk comes in.

Enter NLTK

Luckily there is a Swiss Army knife for working with language data. NLTK is a powerful Python library that comes with a ton of built-in corpora, dictionaries, and tools for things like tokenizing text or tagging parts of speech. It’s ideal for building our word lists.

For Codename’s wordlists I used three key pieces:

words.words() — a flat dictionary of English words, hundreds of thousands of entries.
brown.words() — the classic Brown Corpus, which adds a sense of how words actually show up in real text.
pos_tag() — a simple but powerful part‑of‑speech tagger that can tell an adjective (silent) from a noun (lantern).

Once I could reliably separate adjectives from nouns, I could start shaping lists that made sense — trimming weird outliers, filtering for words of a certain length (no “antidisestablishmentarianism”), and skipping words that almost never appear in normal writing.

The Generator Scripts

I didn’t want Codename.py itself to do any of the heavy lifting. The main script should be fast — grab two words, mash them together, print. The heavy lifting lives in /scripts.

There are two helpers there:

generate_wordlists.py builds adjectives.txt and nouns.txt. It pulls in words from NLTK, tags them, filters them, and writes out clean, lowercase lists.
generate_animals.py builds animals.txt using WordNet’s “animal” synset and its hyponyms — essentially every creature NLTK knows about.

generate_animals_wordlist.py

Here’s the core of how generate_animals.py works:

# Step 1: Get all animal synsets from WordNet
animal_synsets = list(wn.synset('animal.n.01').closure(lambda s: s.hyponyms()))

# Step 2: Extract and clean lemma names
animal_names = set()
for syn in animal_synsets:
    for lemma in syn.lemmas():
        name = lemma.name().replace('_', ' ')
        if name.isalpha() and 3 <= len(name) <= 12:
            animal_names.add(name.lower())

# Step 3: Save to file
with open("animals.txt", "w") as f:
    f.write('\n'.join(sorted(animal_names)) + '\n')

print(f"✅ Saved {len(animal_names)} animal names to animals.txt")

generate_codename_wordlist.py

For the main English wordlists, the script uses NLTK’s part‑of‑speech tagging to separate adjectives from nouns.

Here’s the heart of that logic from generate_wordlists.py:

# Break the big wordlist into chunks for tagging
adjectives, nouns = [], []
for i in range(0, len(wordlist), 1000):
    tagged = pos_tag(wordlist[i:i+1000])
    for word, tag in tagged:
        if tag.startswith('JJ'):   # Adjectives like "silent"
            adjectives.append(word)
        elif tag.startswith('NN'): # Nouns like "lantern"
            nouns.append(word)

This chunk feeds thousands of words through pos_tag() and then deposits them into adjectives.txt and nouns.txt. The filtering step above trims out weird suffixes, apostrophes, and absurdly long words–so you end up with useful, relatively interesting lists instead of random words.

What’s Inside the Lists?

Currently, we have 5,267 nouns, 2,314 adjectives and 2,533 animals in our files–all from the system dictionary.

The nouns range from grounded terms like fortress and summit to linguistic rareities like oubliette or cymbalom; the animals list includes expected entries like wolf and sparrow as well as delightfully rare ones like aardwolf.

Room to Grow

I’m currently working on adding Latin for a –legion mode that will create plausibly cool Roman and Warhammer 40k sounding codenames. That should be possible with the Classical Language Toolkit, Whitaker’s words and possibly the Persesus Digital Library.

Conclusion

Questions, ideas, or wordlist suggestions? I’d love to hear from you: feedback@adminjitsu.com

Operation Codename

Fri, 25 Jul 2025 09:18:49 -0500

What is codename.py?

codename.py is a small Python script that spits out fun, memorable names for whatever you’re working on.

Need a server name that isn’t “server-b”?
Naming a side project or Git branch?
Want your test VM to sound like a secret mission?

Run codename.py and get instant inspiration—whether that’s Gallant Phoenix, Wily Wombat, or Operation Turquoise Spider.

🔗 View codename.py on GitHub

Features

Adjective–Noun combos: Clever Otter, Wandering Nebula, Ancient Lantern…
Ubuntu-style: Alliterative, animal-inspired names (e.g., Brilliant Badger, Wily Wombat)
Military-style: Operation-style names (Operation Silent Arrow)
Single noun mode: Just a big, bold word
JSON output: For piping into other tools
Batch mode: Generate a bunch of names at once (--count)
No dependencies: Pure Python, runs anywhere with python3

Why did I write this?

I am the kind of person for whom everything just grinds to a halt the moment I have to name something. It could be a project or a video game character or a host name–it doesn’t matter. I always sit there for way too long trying to think of the perfect name.

One night I started tinkering with a few wordlists and a Python script. It began spitting out names that made me laugh—and suddenly my VM wasn’t ubuntu-test3 anymore. Now I didn’t actually call it Operation Larvae Offensive but the silly output inspired better names.

That’s the real magic: it shakes ideas loose and makes synapses fire. It’s like having your own /dev/inspiration for ideas–an endless stream of names and half-names and weird combinations.

try running codename --count 50 or even codename --count 1000 and see!

Usage

Run these commands right from your terminal:

python3 codename.py — Random “Adjective Noun” pair
python3 codename.py --ubuntu — Ubuntu-style: adj & animal share first letter
python3 codename.py --military — Military-style: Operation + noun
python3 codename.py --noun — Just a noun
python3 codename.py --count 5 — Generate five names

The script uses standard libraries and does not require a venv. Just make sure to keep the wordlists in the same directory.

Sample Output

in Military mode:

Operation Mass Derision
Operation Enhance
Operation Known Tommy
Operation Rival Threat
Operation Slack

Or in Ubuntu mode:

Vacant Vespid
Obvious Osprey
Tireless Treehopper
Zealous Zebra
Sustained Snipe

Word Lists

The magic comes from three simple text files:

adjectives.txt — required
nouns.txt — required
animals.txt — optional (for Ubuntu mode)

They live next to the script. Add your own words to make themed generators—spooky Halloween names, corporate buzzword names, or even fantasy D&D-style names.

The Unix system dictionary is just a giant, flat list of words. Parsing for parts of speech (for example, to separate adjectives from nouns) requires libraries like NLTK and WordNet–and that’s slow at runtime. Bundling pre-built wordlists with the script turned out to be a super-fast and lightweight alternative, and an easily extensible one.

👉 Look out for an upcoming post about how I made these wordlists using nltk and wordnet and about the joys of good corpora.

Future Direction

I’m planning on fixing JSON output with json.dumps()
I’m working on a –theme argument to allow for custom word lists and new themes like –cyberpunk or –fantasy. Those will need custom dictionaries or a better way to “detect” a cool word.
I’d also like to support a tiny web server mode so your non-technical friends might be impressed too!

Conclusion

Why settle for project-2 when you could have, Operation Neon Owl or Randy Rhinoceros? Grab your copy of codename.py on GitHub and start naming stuff like it matters!

Jot and Friends

Thu, 24 Jul 2025 01:22:03 -0500

the function

Tired of losing stray thoughts? Tired of task-switching to record an idea? Well jot is your one-liner lifeline for adding timestamped entries to a running Markdown log with a quick terminal command.

# jot – Append a timestamped message to a Markdown file in your Obsidian vault
jot() {
  local vault note timestamp message input

  # Detect platform and set vault path
  if [[ "$(uname)" == "Darwin" ]]; then
    # macOS: standard Documents folder
    vault="$HOME/Documents/obsidian_vault"
  elif grep -qi microsoft /proc/version 2>/dev/null; then
    # WSL: write to the Windows user's Documents or Obsidian vault path
    vault="/mnt/c/Users//Documents/Obsidian Vault"
  else
    # Regular Linux
    vault="$HOME/obsidian_vault"
  fi


  note="$vault/jot.md"
  timestamp="$(date '+%Y-%m-%d %H:%M:%S')"

  # Edit mode
  if [[ "$1" == "--edit" || "$1" == "-e" ]]; then
    ${EDITOR:-vim} "$note"
    return
  fi

  # Read stdin if piped
  if [ ! -t 0 ]; then
    input="$(cat -)"
    message="$input"
  elif [[ -z "$1" ]]; then
    echo -n "📝 Enter jot message: "
    read -r message
    if [[ -z "$message" ]]; then
      echo "⚠️  No message entered. Aborting."
      return 1
    fi
  else
    message="$*"
  fi

  # Append to jot.md
  {
    echo "- [$timestamp]"
    echo "$message"
    echo ""
  } >> "$note"

  echo "📝 Jotted to: $note"
}

Usage

jot "Added notes to my zine."
echo "Multiline from a script" | jot
jot --edit

📝 Enter jot message:

If you run jot with no arguments it will prompt the user to type their message. The --edit option will open in your default editor for longer or more complex notes, like code blocks or multi-line entries. It will also handle piped output from other programs.

You will need to modify the vault path(s) in the script to point to your Obsidian vault.

In my setup, I jump between different linux machines, my windows machine running Ubuntu under Windows Subsystem for Linux and multiple Mint Linux boxes. The code is currently designed to support that by defining three paths based on detecting the environment and using the right path to my vault automatically. All you should need to do is to modify the path in the vault=path portion of the script.

Some path examples for the vault= line:

On macOS: ~/Documents/obsidian_vault
On Linux: ~/obsidian_vault
On WSL: /mnt/c/Users//Documents/Obsidian Vault

Why is this cool?

Being able to jot a note from the CLI is absolutely useful. Some existing projects allow you to use Obsidian from the CLI, but they often try to provide a whole interface. Jot is simple. If you think of a great idea while coding, you are just a single command away from capturing it:

jot "I had a great idea today. Holographic chess"
jot "#listening_to Cashing In by Minor Threat"
jot "Never name a server 'skynet'"

I try to review the Jot note in Obsidian from time to time and develop ideas and create proper notes for really solid ideas. It lowers the cost of writing something down in your second brain while you are already focused.

Conclusion

I hope you will find it as useful as I have.

Please let me know if you have any feedback or ideas to improve it. Happy jotting!

manfzf

Thu, 24 Jul 2025 00:00:00 +0000

What is manfzf?

RTFM in style with manfzf()

manfzf is an interactive Python tool that lets you fuzzy search every man page on your system, preview them live, and “zoom in” on related topics—all from the terminal.
It’s designed for shell nerds, sysadmins, and anyone who wants to explore Unix docs, not just look up one thing.

Quick Start

🔗 View manfzf on GitHub

Note: you will need to install fzf if you don’t already have it, with something like sudo apt install fzf

Features

Fuzzy search all installed man pages with fzf
Live preview of the first 80 lines as you browse
Keyboard controls: [ENTER] to open, Ctrl-A to jump into apropos for the current topic, Ctrl-B to back up
Stack-based navigation (like breadcrumbs for your research rabbit holes)
Dracula-inspired color theme for preview and selection
Python 3, no dependencies except fzf and man
Fast and minimal—just drop in and run

Why did I write this?

fzf is an amazing tool. It didn’t take long for the idea to dawn on me, why not a high tech new interface for man, man -k and apropos. I spend a lot of time in man pages but they have never been particularly friendly to browse and explore.

manfzf solves this by showing a preview of the selected man page and offers the ability to “zoom in” and “zoom out” using apropos to find related man pages. Plus you get the ability to do fuzzy searches across the entire collection. I plan on improving it further but it is extremely useful to me already.

Usage

python3 manfzf.py           # Fuzzy search everything (default)
python3 manfzf.py awk       # Start by searching for 'awk'

Type to filter,

[ENTER] to view a manpage.
[Ctrl-A] runs apropos for your current selection (zoom deeper).
[Ctrl-B] goes back one search context.
[ESC] or no selection exits.

Sample Output

Future direction and man2pdf

I plan to add a routine to render a selected man page as a pdf. Since I haven’t gotten around to integrating it into manfzf yet, I will instead share my man2pdf functions here. Just add these to your shell startup (e.g., .bashrc, .zshrc) and reload (open a new tab, source .bashrc).

macOS

The mac version makes use of Preview to render the postscript out of man -t into pdf.

# Convert man page to PDF (macOS only)
man2pdf() {
  man -t "$1" | open -f -a /Applications/Preview.app
}

Linux

On Linux, you will first need to install Ghostscript, which provides ps2pdf using your distro’s package manager (e.g., sudo apt install ghostscript)

man2pdf() {
  local page="${1:?Usage: man2pdf }"
  local tmpfile
  tmpfile="$(mktemp --suffix=.pdf /tmp/man2pdf-XXXXXX.pdf)"

  # Convert manpage to PDF
  man -t "$page" | ps2pdf - "$tmpfile"
  # Open the PDF using xdg-open (works on most desktops)
  xdg-open "$tmpfile" >/dev/null 2>&1 &
}

I’ll eventually add this to manfzf, but in the meantime, I hope you enjoyed this loot-filled sidequest!

Conclusion

With manfzf on your system, you too can RTFM with style!

pypeek

Wed, 23 Jul 2025 00:00:00 +0000

What is pypeek?

pypeek is a minimal Python command-line tool that lets you inspect objects, modules, or files with one command. It’s built to be fast, lightweight, and useful for debugging or code exploration.

🔗 View pypeek on GitHub

Features

Quickly preview attributes and docstrings of any Python object
Peek inside .py files or modules without running them
Pretty, readable output for both shell and IDE use
Makes sense of unfamiliar codebases in seconds

Why did i write this?

I was finding it difficult to visualize my longer and multi-file programs and wanted a quick view like this. I looked for an existing tool but nothing worked the way I wanted. I decided to take the caveman approach and create the tool I wanted. It’s a work in progress but a useful one.

usage

pypeek myscript.py              # Show classes, functions, entry point
pypeek myscript.py:SomeClass    # Inspect a specific class or object
pypeek myscript.py --verbose    # Show all return paths with conditions

Sample Output

$ python cavepeek.py my_script.py

📄 my_script.py
──────────────────────────────

📘 Module:
Does awesome things.

🏩 Classes:
──────────────────────────────

🧱 class Ninja
  • stealth(self)
    📘 Move silently.
    ↪ return 'shadow'
  • attack(self, target)
    ↪ (no return)

🔧 Top-Level Functions:
──────────────────────────────

• helper()
  ↪ return True

🚀 Entry Point:
──────────────────────────────

• main()
  ↪ return 0

🚀 Executable:
Yes (has __main__ block)

Cool bits

I learned some useful tricks creating this script. Here are a few highlights:

AST (Abstract Syntax Tree)

Pypeek uses the ast module to map out top-level functions, classes, docstrings and more–no code execution required. We use a custom CodeSummary class to walk the AST for a given file to peek at its structure and introspect interesting details.

class CodeSummary(ast.NodeVisitor):
    ...
    def visit_ClassDef(self, node):
        # Finds all classes and their methods
    def visit_FunctionDef(self, node):
        # Gathers all functions, their arguments, docstrings, returns

Again a caveman approach but it has the benefit of working on structure and not requiring running code.

Context-Aware return tracking

Finds the conditional associated with a return that lives inside nested logic or an if statement. It prints the return and the condition that wraps it. It’s a great technique for understanding your outputs as well as your inputs.

Main Function Special Treatment

If there is a main() function, it gets highlighted separately. Iif the file has an if __name__=="__main__" block, you’ll know if it’s callable from the CLI.

Pretty Print Helpers

Functions and methods are shown with names, arguments, docstring line and each return’s code/conditions in a compact, quick-to-read and CLI friendly way.

Graceful Fallbacks

Non-Python file? Syntax errors? Missing docstrings? Everything gets handled gently with clear CLI feedback. No ugly tracebacks.

seer suite

Wed, 23 Jul 2025 00:00:00 +0000

what are seer scripts?

The Seer Suite is a collection of Bash scripts I wrote to see through the surface of any Unix system—files, processes, packages or the network, like magic! If you’ve ever wanted ls, lsof, ps, and a pile of forensics tools to just play nice together, this suite is for you. They’re as fast, portable, and 100% terminal-friendly as possible.

Born from an old work forensics script (“maxinfo”) and endlessly polished on sleepless nights. If you like transparency, you’ll love these.

🔗 View Seer Scripts on GitHub

features

Inspect any file—see type, stat, hashes, attributes, metadata, and more
Analyze processes by pattern, PID, tree, or open ports
Cross-distro package lookup and info (supports major Linux/BSD package managers)
LAN and network inspection (interfaces, routes, live hosts, port checks)
Shared Bash helper library for DRY code
Human-friendly output, color where supported
Built to be safe, readable, and easy to hack

why did i write this?

I do a lot of digital forensics work and deep dives and I needed to automate some of the commands I always found myself running manually. The concept behind these was to have a way to zoom in and see all the info for various parts of the system. Basically, automate the boring stuff! I tested extensively and made an effort to be cross-platform friendly and useful in the real world.

usage

Clone/download all scripts (and dotlib.sh!), then make them executable:

git clone https://github.com/forfaxx/seer-suite.git
cd seer-suite
chmod +x *.sh
# (Make sure dotlib.sh is present, or set $DOTFILES for your dotfiles path)

Sample output

./file-seer.sh inspect ~/Downloads/unknown_file

──────────────────────────────
🧾 File: secret.img
──────────────────────────────
Type:          regular file
Size:          1.4 MB
MIME:          application/octet-stream
SHA256:        f0e1d2c3b4a59687e5f4...
Permissions:   rw-r--r--
Owner:         grumble:users
Created:       2024-11-20 03:17:44
Modified:      2024-12-01 21:55:10
Attributes:    (none)

🔍 Stat Summary:
Device: 803h/2051d  Inode: 1284421   Links: 1
Blocks: 2800        IO Block: 4096   regular file

🔑 Extended Attributes:
- (none)

📚 Metadata:
- (no embedded metadata)

───────────────
Hexdump Preview (first 32 bytes)
───────────────
00000000  1f 8b 08 00 00 00 00 00  02 03 7c 0c 00 00 00 00  |..........|.....|
...

Cool bits

There are a few conventions that I really like in these scripts:

Subcommand pattern

Every script has a subcommand pattern just like git or docker—easy to remember, easy to extend.

case "$CMD" in
  search)   search_process "$@";;
  info)     process_info "$2";;
  tree)     process_tree;;
  ports)    process_ports;;
  help|*)   usage;;
esac

Cross-Platform and defensive patterns

Scripts start with set -euo pipefail to avoid hidden failures. All commands are wrapped to gracefully handle missing components. In cases like the use of ANSI color, I provide an option and handling to avoid polluting output where it isn’t desirable. The suite features these and more, friendly and robust conventions.

Happy seeing!

Ninja Style-Dojo

Tue, 22 Jul 2025 13:41:33 -0500

⚠ Just a humble style playground for the site. nothing to see here unless you dig awesomeness ⚠

Download This Page’s Markdown & CSS

📝 Download Ninja Test Markdown 🎨 Download Custom CSS

The Glyphs!!

Copy and paste those annoying symbols that are tough to remember:

Symbols & Special Characters

Em dash: —
En dash: –
Infinity: ∞
Bullet: •
Check mark: ✔
Cross mark: ✘
Arrow: →
Box drawing (thin): ─ │ ┌ ┐ └ ┘
Box drawing (heavy): ━┃┏┓┗┛
Section (§): §
Copyright: ©
Registered: ®
Degree: °
Pi: π
Micro: µ
Command prompt: $
Backtick: `

Some useful emojis

🚀 Rocket :rocket: U+1F680
✅ Check Mark :white_check_mark: U+2705
❌ Cross Mark :x: U+274C
⚠️ Warning :warning: U+26A0 FE0F
📝 Memo/Note :memo: U+1F4DD
📦 Package/Box :package: U+1F4E6
🔗 Link :link: U+1F517
🧑‍💻 Technologist :technologist: U+1F9D1 200D 1F4BB
🔒 Lock :lock: U+1F512
🔑 Key :key: U+1F511
🔍 Magnifier :mag: U+1F50D
💡 Light Bulb :bulb: U+1F4A1
📅 Calendar :calendar: U+1F4C5
📋 Clipboard :clipboard: U+1F4CB
🧙‍♂️ Mage/Wizard :mage: U+1F9D9 200D 2642 FE0F
🔧 Wrench :wrench: U+1F527
💾 Floppy Disk :floppy_disk: U+1F4BE
🔥 Fire :fire: U+1F525
📖 Book/Docs :book: U+1F4D6
📢 Loudspeaker :loudspeaker: U+1F4E2
🤖 Robot :robot: U+1F916
🧩 Puzzle Piece :jigsaw: U+1F9E9
🎯 Target :dart: U+1F3AF
⚡ High Voltage :zap: U+26A1
💥 Collision :boom: U+1F4A5
🔁 Repeat :repeat: U+1F501
⏳ Hourglass :hourglass_flowing_sand: U+23F3
🛠️ Tools :hammer_and_wrench: U+1F6E0 FE0F
🚧 Construction :construction: U+1F6A7
🦄 Unicorn :unicorn: U+1F984
🌟 Glowing Star :star2: U+1F31F

Feather Icon Style Test • Grid Demo

Adminjitsu Feather Icon Style Test

Quick grid of commonly useful icons with size / stroke controls. Click a tile to copy its name.
Click: copy with size/stroke/color. Alt+Click: copy full inline SVG.

Size Stroke Color

Inline variants (rss):

Standard:

Large:

Thin stroke:

Thick stroke:

Accent color:

Copied

Obligatory Lorem ipsum block

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod sem at felis scelerisque, at ultrices purus pellentesque. Praesent sit amet turpis non leo suscipit laoreet. Vivamus interdum sapien ut risus vulputate, non congue justo vestibulum. Nunc volutpat dui ac magna cursus, in pulvinar magna gravida. Nulla facilisi. Phasellus vel dui ut libero facilisis sollicitudin vel ac sapien. Etiam posuere velit nec orci viverra, sit amet ullamcorper elit fermentum.

Mauris interdum, nibh in commodo consequat, lorem elit porta mauris, nec pretium nunc urna ac lorem. Sed nec turpis ac mauris fermentum posuere.

It's a ninja!!

Mauris interdum, nibh in commodo consequat, lorem elit porta mauris, nec pretium nunc urna ac lorem. Sed nec turpis ac mauris fermentum posuere. Fusce viverra, tortor sed porta feugiat, justo sapien fermentum sapien, sed facilisis lacus est nec eros. Integer tincidunt enim sed est ultrices, nec sagittis nisl gravida. Pellentesque congue sapien a sapien tempor, non posuere est congue. Ut sed nisl ut lectus ultricies egestas. Vivamus a mi sit amet nibh commodo suscipit a sed ipsum.

Stealth ops require snacks

Your paragraph text starts here and will wrap to the right of the figure on wide screens. Keep writing as normal — the float handles the flow.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod sem at felis scelerisque, at ultrices purus pellentesque. Praesent sit amet turpis non leo suscipit laoreet. Vivamus interdum sapien ut risus vulputate, non congue justo vestibulum. Nunc volutpat dui ac magna cursus, in pulvinar magna gravida. Nulla facilisi. Phasellus vel dui ut libero facilisis sollicitudin vel ac sapien. Etiam posuere velit nec orci viverra, sit amet ullamcorper elit fermentum.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod sem at felis scelerisque, at ultrices purus pellentesque. Praesent sit amet turpis non leo suscipit laoreet. Vivamus interdum sapien ut risus vulputate, non congue justo vestibulum. Nunc volutpat dui ac magna cursus, in pulvinar magna gravida. Nulla facilisi. Phasellus vel dui ut libero facilisis sollicitudin vel ac sapien. Etiam posuere velit nec orci viverra, sit amet ullamcorper elit fermentum.

Make these headings smaller

This sections is for testing head weights/size tweaks.

subheading

sub-subheading

Heading

Subheading

Sub-Subheading

Sub-Subheading

Another Subheading

Dangling sections (remove this to see)

test lorem ipsum lorem ipsum dolor sit amet test test test test

Custom span sizes

This is a slightly smaller sentence. (0.85em)

This is the normal base size. (1em)

This is a little larger for subtle emphasis. (1.2em)

This is noticeably larger for a punchy effect. (1.5em)

This is huge. Ninja mode activated. (2em)

Font Sampler

Sans-Serif

Roboto Regular 400:
The quick brown fox jumps over the lazy dog.

Roboto Bold 700:
The quick brown fox jumps over the lazy dog.

Roboto Italic:
The quick brown fox jumps over the lazy dog.

Roboto Bold Italic:
The quick brown fox jumps over the lazy dog.

Karla Regular 400:
The quick brown fox jumps over the lazy dog.

Karla Bold 700:
The quick brown fox jumps over the lazy dog.

Karla Italic:
The quick brown fox jumps over the lazy dog.

Karla Bold Italic:
The quick brown fox jumps over the lazy dog.

Serif Font Sampler

Merriweather Regular:
The quick brown fox jumps over the lazy dog.

Merriweather Bold:
The quick brown fox jumps over the lazy dog.

Merriweather Italic:
The quick brown fox jumps over the lazy dog.

Merriweather Bold Italic:
The quick brown fox jumps over the lazy dog.

Typography Playground

Bright cyan sample text
Yellow highlight (for light mode)
High contrast highlight (for dark mode)

Letter Spacing

S P A C E D T E X T (0.07em letter-spacing)

Compressed text (-0.03em letter-spacing)

Line Height

Tight lines (line-height: 1.1)
The quick brown fox jumps over the lazy dog.

Relaxed lines (line-height: 1.6)
The quick brown fox jumps over the lazy dog.

Blockquote

“Typography is the craft of endowing human language with a durable visual form.”
—Robert Bringhurst

for custom style:

“Typography is the craft of endowing human language with a durable visual form.”
—Robert Bringhurst

Monospace / Code This is inline code using the site’s monospace font.

pre/code block — Roboto Mono or system monospace

Small Caps

Small Caps Text Example

Superscript & Subscript This is E = mc² and H₂O

KaTeX math:

Why is this not working correctly? KaTeX is gorgeous and should work here:

This is Euler’s identity: $e^{i\pi} + 1 = 0$
$$ \int_{-\infty}^\infty e^{-x^2} dx = \sqrt{\pi} $$
$\therefore$

Color Tag Shortcode Examples

Testing tag.html shortcode:

Python

CLI

Draft

WIP

Secret Ninja Mode

With combos:

Beta next to Mini

Pills:

Python

CLI

Draft

WIP

Secret Ninja Mode

Small pill

👉

👉

👉

Color Picker Tool

Check out the Color Picker tool

Make it easy to use color wherever you want!

Make it easy to use color wherever you want!

Images

Make an image into a link:

Shadow ninja

Shadow Ninja

Broken link behavior

Animated gif

Ninja time!

Ninja time!

Shortcodes demo

youtube video-id

Highlight
echo "NINJA ✅"

Raw HTML block!

Collapse/Accordion (PaperMod)

Details

repeat() Mon, 21 Jul 2025 06:49:47 -0500 I created a repeat function that is ridiculously useful for testing programs that produce variable output. the function add this to your bash shell either by pasting as a block into your terminal and then typing the function name to run, or add it to the appropriate dotfile to make it permanently available. # this function will run a command multiple times, eg repeat 10 gibberish uuid or repeat 5 fortune repeat() { if [[ -z "$1" || ! "$1" =~ ^[0-9]+$ ]]; then echo "Usage: repeat [args...]" >&2 return 1 fi local count="$1" shift for i in $(seq "$count"); do "$@" done } usage to use, invoke with repeat and a numerical argument. i.e. ┌──[ grumble@shinobi ]:~ └─$ repeat 5 gibberish numbers 84451182630363300096 77401767437641923164 42951978581655852424 06803068919499777616 43251993640144857502 or ┌──[ grumble@shinobi ]:~ └─$ repeat 2 uuidgen 547f5194-0b61-4f7b-9274-cab9ad1fd8ec 0e535674-0857-4172-a366-63b2ef1fa39d This is useful for programs that produce variable or randomized output where running multiple times would make sense. Kind of a sibling to meta-execution and orchestration tools like watch, inotify, fswatch, xargs and more. notes The code above works on modern bash and zsh shells. For a POSIX-compliant, .sh version you can use this older but still functionally equivalent version. repeat() { if [ -z "$1" ]; then echo "Usage: repeat [args...]" >&2 return 1 fi case $1 in ''|*[!0-9]*) echo "Count must be a positive integer." >&2; return 1;; esac count=$1 shift i=1 while [ "$i" -le "$count" ]; do "$@" i=`expr $i + 1` done } I prefer the cleaner modern bash idioms, but there you go! mkcd() Mon, 21 Jul 2025 00:00:00 +0000 the function This little mkcd function feels like it should be a standard /bin tool. It makes a directory and changes directory into it with a couple of safeties. # create and cd into a new directory (safely) # Usage: mkcd mkcd() { if [[ "$1" == *\** || "$1" == *\?* || "$1" == *\[*\]* ]]; then echo "❌ Globs not supported—please provide a single directory name." return 1 fi if [[ $# -gt 1 ]]; then echo "⚠️ Multiple directory names given—using the first: $1" fi if [[ -z "$1" ]]; then echo "📁 Usage: mkcd " return 1 fi mkdir -p "$1" && cd "$1" || { echo "❌ Failed to enter directory: $1" return 1 } } usage mkcd folder-to-create mkcd folder/subfolder/subfolder2 Just add to your startup files (e.g., .bashrc, .zshrc) and reload; you’ll be set. notifications for everyone Mon, 21 Jul 2025 00:00:00 +0000 In my work, I often jump between a variety of machines. I have increasingly begun to rely on simple interfaces that work cross-platform in my environment. It makes these scriptable and usable no matter where you are. notify() One such example is this notify function. It allows you to call one function to display system notifications. Your mileage may vary, but it’s worked well for me. Just add the following to your shell startup files and reload.. # cross platform notification system # Usage: notify "Title" "Message" notify() { local title="${1:-"Notification"}" local message="${2:-}" # macOS if command -v osascript >/dev/null 2>&1; then osascript -e "display notification \"$message\" with title \"$title\"" # WSL: Detect *first* before generic Linux! elif grep -qi microsoft /proc/version 2>/dev/null && command -v powershell.exe >/dev/null 2>&1; then powershell.exe -NoProfile -Command "Import-Module BurntToast; New-BurntToastNotification -Text \"${title}\", \"${message}\"" # Linux/Unix with notify-send elif command -v notify-send >/dev/null 2>&1; then notify-send "$title" "$message" # Windows native Git Bash, msg.exe elif command -v msg.exe >/dev/null 2>&1; then msg.exe * "$title: $message" # Fallback to wall elif command -v wall >/dev/null 2>&1; then echo "$title: $message" | wall else echo "$title: $message" fi } Usage notify "Title" "This is a test of the Emergency Broadcast System" On my systems, this pops up a system notification. The one catch is that on modern Macs you must enable terminal notifications by opening Script Editor one time and running the following: display notification "Test notification" with title "Script Editor" This will prompt you (with a notification) to allow terminal notifications. More interfaces I’m still developing these but the following are pretty handy as well. say command Since I split my shell startup into multiple files, I define the say command so it is present on linux and works like on the mac. Of course espeak voices are not as nice as on mac but they do have their place as another kind of notification or even a toy. # macOS-style `say` command on Linux using espeak if [[ "$(uname -s)" == "Linux" ]] && command -v espeak >/dev/null; then alias say='espeak -s 160 -p 60 -v en-us+f2' fi You’ll need to install espeak with your preferred package manager. For apt it’s just apt install espeak man2pdf This is one I have used on mac for years. # Convert man page to PDF (macOS only) man2pdf() { man -t "$1" | open -f -a /Applications/Preview.app } Usage: man2pdf grep This will launch a man page in Preview as an attractive pdf. I missed that command on linux but it’s as easy as doing the following: # Render man page as ps then as pdf using the ps2pdf application # functional equivalent to man2pdf on mac. man2pdf() { local page="${1:?Usage: man2pdf }" local tmpfile tmpfile="$(mktemp --suffix=.pdf /tmp/man2pdf-XXXXXX.pdf)" # Convert manpage to PDF man -t "$page" | ps2pdf - "$tmpfile" # Open the PDF using xdg-open (works on most desktops) xdg-open "$tmpfile" >/dev/null 2>&1 & } Same usage. easy peasy. clip and paste Another really useful cross platform command is clip and paste. Having predictable interfaces like this is definitely adminjitsu. On Mac # macOS clipboard # for consistency with linux environment alias clip='pbcopy' alias paste='pbpaste' On Linux # Linux clipboard (assumes xclip is installed) alias clip='xclip -selection clipboard' alias paste='xclip -selection clipboard -o' You’ll need to install xclip with your preferred package manager. For apt it’s just sudo apt install xclip That is a really powerful command that allows you to do things like: find . -type f ! -path "*/.git/*" ! -path "*/venv/*" | clip paste and now the output is on your system clipboard and ready to paste anywhere. Conclusion These are just a few small examples of a concept I am really starting to embrace. I look forward to adding more as time goes on! ps for spelunkers Mon, 21 Jul 2025 00:00:00 +0000 These are some of the ps aliases and functions I have found useful over the years. Aliases I’ve always loved aliases. They make long and unmemorable commands memorable and they’re a pretty good, self-documenting way to keep track of those Hero commands that do something great but that you would struggle to remember. Here are a few that I developed working with Cloudera java processes and complex web server setups. The following show you the top 20 memory hogs. The first just sorts and limits the usual output. The pmem alias is a lot more useful for a quick view alias ptop='ps aux --sort=-%mem | head -n 20' alias pmem='ps aux --sort=-%mem | head -n 20 | awk '\''{print $1, $4, $11}'\'' | column -t' Similarly, this one shows top cpu hogs alias pscpu='ps aux --sort=-%cpu | head -n 20 | awk '\''{print $1, $3, $11}'\'' | column -t' The forest view shows subprocesses in a friendly way alias pfor='ps auxf --forest' Finally, what are my longest running proceses? alias psme='ps -u $(whoami) -o pid,etime,cmd --sort=-etime | head' bash functions Sometimes you want to do something that the ps program alone isn’t capable of doing. For me it was displaying a space between each process. I was working on a deep dive and after staring at wall after wall of grey dense grey text I found myself doing it manually in an output file. That’s always a sure sign that it’s time to write a function if not a standalone script. pss function This function inserts a blank line between processes. much more readable. # Runs ps and displays each process separated by a blank line to improve readability pss() { ps aux | awk '1; { print "" }' } psss function This function provides more separation and uses color to make it even more readable. This one is probably better for deep dives than daily use but I have found it useful plenty of times. # Pretty print ps output, with optional filtering psss() { local filter="${1:-}" echo "🧠 Showing processes${filter:+ matching: '$filter'}" echo "─────────────────────────────────────────────" ps auxww --sort=-%mem | { if [[ -n "$filter" ]]; then grep -i --color=always -- "$filter" else cat fi } | awk ' BEGIN { GREEN = "\033[1;32m"; BLUE = "\033[1;34m"; RED = "\033[1;31m"; YELLOW = "\033[1;33m"; CYAN = "\033[1;36m"; RESET = "\033[0m"; } { print GREEN "USER:" RESET " " $1; print BLUE "PID:" RESET " " $2 " " RED "CPU:" RESET " " $3 " " YELLOW "MEM:" RESET " " $4; printf CYAN "CMD:" RESET " "; for (i = 11; i <= NF; ++i) printf "%s ", $i; print "\n"; } ' } It’s output looks like this: More tips and tricks Pick the columns you actually want # Linux (procps): # macOS/BSD: ps -eo user,pid,ppid,%cpu,%mem,stat,etime,start,tty,pri,ni,rss,vsz,comm \ --sort=-%mem # macOS uses -axo and different names (etime/start are fine): ps -axo user,pid,ppid,%cpu,%mem,state,etime,start,tty,pri,nice,rss,vsz,comm etime: elapsed time rss vs vsz: resident (real RAM) vs virtual size comm = executable name only; args = full command line Job control Start in background: cmd & Suspend foreground: Ctrl-Z List jobs: jobs -l Resume in background: bg %1 Bring to foreground: fg %1 Keep alive after logout: disown %1 or nohup cmd & Detach fully: setsid cmd >/dev/null 2>&1 < /dev/null & Pause/Resume any PID: kill -STOP / kill -CONT Complimentary tools (adjacent to ps) top/htop/atop – interactivity, sort by CPU/MEM, filter fast. lsof -p – what files/sockets a process is using. ss -pt or netstat -p – who’s talking on the network (and which PID). strace -p / dtruss -p (mac) – syscall truth serum (dev environments). /proc/ – Linux treasure trove (status, cmdline, environ, fd/). Conclusion Feedback? Email me: feedback@adminjitsu.com May your zombie processes be few in number Hello World Tue, 01 Jul 2025 00:00:00 +0000 Hello, World! This seemed like an appropriate first post for a blog about scripting and programming (and Unix in general) since that is the first program anyone learns to write in a computer language. If I told you the frustrating, tedious story behind how this post’s tags caused an enormous issue that broke the site and took hours to fix, you would appreciate why I chose the insane sysadmin as my mascot! Suffice to say, I’m glad it’s working finally. I think we’ve all found ourselves chasing down weird bugs that make us want to rip our hair out and pound on the keyboard in frustration. That’s kind of why I created this page. I want to offer hard won and battle tested advice, tools that are actually friendly and robust and hopefully bring a smile to the frazzled sysadmin who loves this stuff anyway! Hello, World in Different Languages Here is Hello World in every language I have dabbled in for one reason or another. These days I tend to stick with Bash, Python and the occasional compiled language. BASIC This was the language of my first computer, the Commodore 64! 10 PRINT "HELLO, WORLD" 20 END Turbo Pascal This was the first language I learned in school. Limited but kind of lovely. program HelloWorld; begin Writeln('Hello, World'); end. For some reason Chroma refuses to format my pascal block correctly no matter what I do. So I’ve decided to accept it as an example of Wabi-sabi and move on with my life. I once wrote a Cthulhu themed text adventure in Pascal that hit all the limits for file size, number of files and memory. Fun times! Programming Your Own Adventure Games in Pascal a fantastic vintage guide, now freely readable on the Internet Archive. Bash The Swiss Army knife of Unix. A one-liner here can topple servers or automate your life! #!/bin/bash echo "Hello, World" Perl The duct tape of the early web—messy and often unreadable. Perl was my first real scripting language #!/usr/bin/perl print "Hello, World\n"; Python Where Perl is inscrutable, Python is elegant — I honestly thought it was pseudocode the first time I saw it. These days, it’s my primary language. #!/usr/bin/env python3 print("Hello, World") C I mean Unix is written in C. Garbage collection, recursion and double linked-lists ahoy! Kernighan & Ritchie — This book is effortlessly brilliant. Like Euclid's Elements for programming. #include int main() { printf("Hello, World\n"); return 0; } C++ The language behind just about everything for a long time. C++ How to Program by H.M. Deitel & P.J. Deitel — a brilliant, and unforgettable classic of the '90s programming bookshelf. #include using namespace std; int main() { cout << "Hello, World" << endl; return 0; } Java Java powers everything from Minecraft and Spotify to Apache Hadoop to the NASDAQ to your home appliances. Not always fun to progam in but incredibly powerful and worth learning. public class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World"); } } Ruby I always joked that Ruby was a language for art majors. Elegantly difficult to follow. #!/usr/bin/env ruby puts "Hello, World" PHP The language that built half the internet. This was the language for cgi for a very long time. I never loved it but I always respected it. php echo "Hello, World\n"; ?> Objective-C The language of NeXTSTEP and Apple! #import int main(int argc, const char * argv[]) { @autoreleasepool { NSLog(@"Hello, World"); } return 0; } Lisp Such a cool language! A ton of seminal AI research was done using Lisp. (format t "Hello, World~%") The Little LISPer — this short book will rewire your brain and change how you think about recursion. Lua If you ever tried modding a game, you might have run into the Lua scripting language. Perfect for powering little video game monster’s brains. print("Hello, World") JavaScript (Node.js) The modern web wouldn’t exist without it. I never really liked pure Javascript but Node.js is amazing. console.log("Hello, World"); x86 Assembly (NASM, Linux) Programming in assembly is like programming with DNA. It takes a lot of writing to do anything because it is as close to the hardware as you want to get. section .data msg db "Hello, World", 0xA ; The string, with newline len equ $ - msg section .text global _start _start: mov eax, 4 ; sys_write mov ebx, 1 ; file descriptor (stdout) mov ecx, msg ; message address mov edx, len ; message length int 0x80 ; call kernel mov eax, 1 ; sys_exit xor ebx, ebx ; exit code 0 int 0x80 Ada Named after Lady Lovelace, this general-purpose, strongly typed, systems language has been used in avionics, missile guidance systems, satellites, rail control systems, even traffic lights. with Ada.Text_IO; use Ada.Text_IO; procedure Hello_World is begin Put_Line ("Hello, World"); end Hello_World; Smalltalk This was a really neat language! Transcript show: 'Hello, World'; cr. COBOL THE HORROR… Rear Admiral Grace Hopper—pioneer of programming languages, inventor of the first compiler, and one of the driving forces behind COBOL. She coined the term “debugging” and could out-logic any mainframe (in heels no less). IDENTIFICATION DIVISION. PROGRAM-ID. HELLO-WORLD. PROCEDURE DIVISION. DISPLAY "HELLO, WORLD". STOP RUN. Fortran It’s shocking how much Fortran code is still out there. PROGRAM HELLO PRINT *, 'Hello, World' END Intentionally Obtuse Code Here’s a fun recursive example! def painfully_hello(msg, i=0): if i < len(msg): print(msg[i], end='', flush=True) painfully_hello(msg, i + 1) painfully_hello("Hello, World") And another in Lisp (defun painfully-hello (letters) (when letters (princ (car letters)) (painfully-hello (cdr letters)))) (painfully-hello (list #\H #\e #\l #\l #\o #\, #\Space #\W #\o #\r #\l #\d)) Welcome Just to make sure you feel extra welcome, and please forgive me if I left off your favorite language: English: Welcome! French: Bienvenue ! German: Willkommen! Italian: Benvenuto! Spanish: ¡Bienvenido! Portuguese: Bem-vindo! Polish: Witaj! Ukrainian: Ласкаво просимо! (Laskavo prosymo!) Turkish: Hoş geldiniz! Yoruba: Ẹ ku abọ! Hindi: स्वागत है! (Swāgat hai!) Sanskrit: स्वागतं! (Svāgataṁ!) Latin: Salve! Greek: Καλώς ήρθατε! (Kalós írthate!) Japanese: ようこそ！ (Yōkoso!) Mandarin: 欢迎！ (Huānyíng!) Arabic: أهلاً وسهلاً! (Ahlan wa sahlan!) Klingon: yI’el! (literally “Enter!”) Quenya: Hantale! (formal welcome/gratitude) Esperanto: Bonvenon! Conclusion There you have it! That’s hello world and welcome in 20 languages. I hope you enjoy the site! Want to connect? feedback@adminjitsu.com GitHub: forfaxx See you in the trenches.

AdminJitsu

nextcube Part 3 - Next Users Guide

Telnet Refresher

nextcube, Part 2 – Finishing the OpenStep 4.2 Appliance

Developer Tools

Verify Developer Tools Installation

nextcube, Part 1 - an OpenStep 4.2 VM in 2025

Intro

Getting Started

README

What’s in the OVA appliance

Building Your Own

VirtualBox settings

🧩 Install Process

Post-Install steps

Install OpenStep Mach Patch 4

Set Display Driver (VESA VBE)

Set password for me and root to enable LoginWindow

Configure Networking

Annoying Floppy Issue

NetInfo Parent issue

Upcoming articles to finish building the OVA appliance.

Links and Stuff

🎥 Video & Download

💾 Archives & File Resources

🔍 Additional Resources

Conclusion

SchemaSpy with LocalDB (SQL Server)

Intro

The Pieces You Need

Suggested Setup (Windows)

Step 1: Find the LocalDB Instance Pipe

Step 2: Authentication Options

Step 3: The Working Command

Option 1: Windows Integrated Authentication (SSO)

Option 2: SQL Login (if one exists in LocalDB)

Flag Breakdown

What Normal Output Looks Like

Why This Works

Troubleshooting Matrix

Links & Stuff

Conclusion

Tcpdump Survival Guide

Intro

Where to Capture?

Capturing With Purpose

Gathering a Solid Capture

Save to a File

Quick Checks

Reading It Back

Pro Tips

Choosing the Right Interface

Which Ones Matter?

Capturing Mobile Traffic

iOS (macOS host required)

Android (USB required)

Filtering for Relevance

Common Filters

Practical Filtering Recipes

Tips

Links & Stuff

Conclusion

Unix Users Handbook

So, What is a User?

History & Tidbits

The User Database

Permissions & Ownership Recap

File Permissions

Process Ownership

Why It Matters

Cheatsheet

Inspect Users & Groups

Git Customization

How git config Works

Where git config Lives (Persistence, Saving & Resetting)

Saving Your Config

Restoring a Config

Resetting to Defaults

Takeaways

Cheatsheet: Useful Git Config Commands

Set password for `me` and `root` to enable LoginWindow

How `git config` Works

Where `git config` Lives (Persistence, Saving & Resetting)

Anatomy of `.git/` (simplified)

Beyond `kill`: other ways to signal processes

systemd `.timer` scheduling options