Blog by Jade Michael Thornton

Why is Dodd Road Discontiguous?

2025-06-04T09:00:00-06:00

The path of Dodd Road (and Dodd Boulevard) through the southern Twin Cities metro. The portion in orange is signed as Dodd Road but does not follow the original path.

I first noticed Dodd Road when I saw sections in Eagan, MN sitting near each other yet not connecting. Then, a seemingly useless 50-meter break between the otherwise-aligned Dodd Road and Dodd Boulevard on the eastern edge of Lebanon Hills Park looked so peculiar that I suspected a historical reason. An easy way to begin is to explore the road's namesake.

Captain William Bigelow Dodd was a ferry operator turned land speculator and militia captain. An energetic entrepreneur, Dodd staked roughly 500 acres on both banks of the Minnesota River at his road-head, laid out the village of Rock Bend (renamed St. Peter in 1854), and even ran "Dodd's Ferry" to carry traffic across the river. He later fell defending New Ulm in the Dakota War of 1862 (for more on that conflict and its broader impact, see my post on Walden and Bdote) and is buried behind St. Peter's Episcopal Church beneath a stone simply reading 'Builder of the Dodd Road.'

Dodd Road began in 1853 as a private subscription road cut by Captain Dodd and eleven men to link Mendota (Bdote) to Rock Bend. This model of road-building meant the colonists pooled money up front and then recouped costs via tolls or land-value gains. The subscription model let Dodd move faster than federal road acts could. Backers in St. Paul signed up to finance clearing trees, grubbing stumps, and building primitive bridges so the road would be usable by wagons. Building it as an all-season path was crucial because steamboats on the Minnesota River ran only when water levels and lack of ice allowed.

In April 1853, Dodd's crew set out from Mendota with two wagons and basic tools. For 109 days they hacked nearly 70 miles of trail through dense forest, following ridges to skirt marshy ground, bridging small streams, and marking trees. By July they reached Lake Emily just outside Rock Bend, having transformed a hunters' path into a wagon-passable highway.

Meanwhile, the U.S. Army's Topographical Engineers had funds to survey a 260-mile military road from Mendota toward the Big Sioux River. In September 1853, Captain Jesse L. Reno's party mapped across Minnesota and "stumbled" onto Dodd's freshly cut trail near Traverse des Sioux. Reno praised its quality and recommended reimbursing Dodd $3,270 (about $136,000 in 2025). The territorial assembly petitioned Congress, and Dodd received payment before the year's end. Reno noted those private improvements saved his survey weeks of bushwhacking.

Almost immediately, Dodd Road spurred settlement. Lakeville and Eureka sprang up in 1853, Millersburg in 1855, Shieldsville and Cordova in 1856, Cleveland in 1857, and Rosemount and Kilkenny by 1859. But when the Minnesota Central Railroad built a St. Paul–Faribault line in 1864, it pulled traffic off the old wagon road. Only one new town, Eidswold, was founded along Dodd Road after the railroad's arrival, a sign that trains had superseded overland wagons, especially for commercial transport.

Today, Dodd's path survives in fragments in Dakota County, but the segments north of MN 55 are not on Dodd's 1853 alignment. In Saint Paul, West Saint Paul, Mendota Heights and the first few miles in Eagan, the road was built in 1921 as part of the Jefferson Highway rather than the original pioneer trace. South of MN 55, however, the road more closely follows Captain Dodd's route. Dropping south, there's a short jump west at Wescott Road, and continues paved down past Lebanon Hills, then follows the gravel-surfaced Dodd Boulevard into Rosemount, through Apple Valley and Lakeville, where the old right-of-way has never been entirely straightened, and then off out of Dakota County. The remains of this twisting path are full of gaps and jumps that trace where modern highways cut across curves, subdivisions severed right-of-way, and county priorities straightened farm-road segments. One of those gaps is the one I found along the eastern edge of Lebanon Hills: a deliberate break planted to prevent through-traffic on this now-residential road.

In 2003, three gravel portions earned National Register status: a 6.8-mile stretch in Rice County (Circle Lake Trail through Falls Trail, Garfield Avenue, Groveland Trail, Halstad Avenue) and two in Le Sueur County (County 136 west of Kilkenny and County 148 near Cleveland). None of the heavily-altered Dakota County segments made the grade. Dodd Road today feels like a time-scarred artifact you can still drive in fits and starts. Next time you hit that gravel stretch or a sudden dead end, imagine Captain Dodd's crew hacking through the Big Woods in 1853 and know every curve once linked frontier farms to a growing territory.

References

"A History of Minnesota's Highways Part One." Streets.Mn, 9 Feb. 2018. https://streets.mn/2018/02/09/a-history-of-minnesotas-highways-part-one/.
Brown, Curt. "Light the Candles and Pull Out the Party Hats: Dodd Road, the Mother of All Minnesotal Highway Construction Projects, Turns 150 Years Old This Summer." Star Tribune, 11 June 2003.
"Dodd Road Discontiguous District." Wikipedia, 24 Feb. 2024. https://en.wikipedia.org/w/index.php?title=Dodd_Road_Discontiguous_District.
"Lost Highway: Dodd Road, Dakota County." Dead Pioneer. https://deadpioneer.com/articles/dakota/doddroad/doddroad.htm.
National Park Service. Dodd Road Discontiguous District: National Register of Historic Places Registration Form. Washington, DC: U.S. Department of the Interior, National Park Service, June 13 2003. https://npgallery.nps.gov/NRHP/GetAsset/NRHP/03000520_text.
Wolston, Bill. "On the 150th Anniversary of the Elusive Dodd Road." Over the Years: Journal of the Dakota County Historical Society, October 2003.

Automatically add Jira issue to commit message from branch name

2020-08-15T09:00:00-06:00

At FlightAware, we use Jira to track work and git for version control. To reference each other, git branch names start with the relevant issue number, taking the form

${project}_${ticketNumber}_${shortDescription}

Additionally, commit messages end with the same issue number in the form

${project}-${ticketNumber}

These conventions allow for easy referencing of issues to look for details and business decisions. Specifically, the issue number in the commit message is used by Zeitgit to attribute commit statistics to issues. It's also used by Jenkins to create useful links between tickets and pull requests.

It is, however, a little annoying to type the issue number in to every commit, especially when I know git already has this information in the branch name—git just doesn't know it. To automate this little task, I use a git hook to prepare the commit message with the issue number before it goes to $EDITOR (e.g. vim) for editing.

Git hooks

Git hooks are scripts—typically written in bash, zsh or another shell—which live in the .git/hooks/ directory of a project. These scripts provide a means of performing actions certain stages of git's behavior. By default, the hooks directory comes pre-populated with sample hooks, each ending with .sample. That file ending keeps them from running until the suffix is removed. Take note of their names though, git will look for these specific names (without the .sample ending) when looking for hooks to run.

The prepare-commit-msg hook

What we need to do is edit the commit message before it goes to your $EDITOR for regular editing; the one we want is called prepare-commit-msg. This hook is called by git commit and is given the name of the file which has the commit message, followed by the description of the commit message's source (discussed later), and the commit's SHA-1 hash.

For the script itself, we need to get the issue number from the branch name, format it according to FlightAware conventions, then prepend it onto the commit message file, preserving git's default message if it exists (the summary of changes in the commit). My script is in Zsh, but could be in any language available on the system; Bash, Python, plain old Bourne shell, etc. would be fine. I use Zsh as my login shell, so that's what I default to.

Hook script in full

#!/usr/bin/env zsh
COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2
SHA1=$3

if [[ -z "$COMMIT_SOURCE" ]]
then
  branch=$(git symbolic-ref --short HEAD)
  if [[ "$branch" =~ ^([a-zA-Z]+)[_-]([0-9]+).* ]]
  then
    ticket="${match[1]:u}-${match[2]}"
    gitMsg=$(cat "$COMMIT_MSG_FILE")
    printf "\n\n%s\n" $ticket > "$COMMIT_MSG_FILE"
    printf "$gitMsg" >> "$COMMIT_MSG_FILE"
  fi
fi

This will handily extract issue names from branch names ranging from "web_14800_some_feature" to "NXT-1701". The first few letter are project codes, of which FlightAware has dozens like PREDICT, ADSB, OPS, NXT, WEB, etc., so we want to support as many as possible.

Now I'm a strong believer of not just executing code without understanding what's happening, so let's break it down.

Capturing commit information

COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2
SHA1=$3

To keep track of the information passed to the hook script, we store the arguments in variables. Here's what we get:

The first argument is the name of the temporary commit message file, where git physically keeps the message until the commit is complete.
The second argument is the commit source. We'll check this a couple lines below.
The third argument is the commit's SHA-1 hash. This script won't use it, but it could be useful to capture if you extend this hook in the future.

Checking the commit source

if [[ -z "$COMMIT_SOURCE" ]]

Before doing any work, the script ensures there's no special commit source by ensuring it's empty with the -z test. This source gives us some info on why this commit is happening. It could be "merge" or "squash" or a number of other sources. In a "normal" commit, the source is just empty. We don't want to mess with any special commits (by FlightAware convention), so we can just check that it's empty.

Getting the branch name

  branch=$(git symbolic-ref --short HEAD)

We also need the branch name, which (may) contain an issue number. Git's symbolic-ref command lets us get info about a symbolic reference, in this case HEAD. The --short option shortens the symbolic ref's path to just its name. For example, this would shorten the full path refs/heads/main to just the name main.

Extracting the issue number

  if [[ "$branch" =~ ^([a-zA-Z]+)[_-]([0-9]+).* ]]

The next if condition performs two actions. First, it only resolves as true if there is an issue number in the branch name—at least of the form we use at FlightAware. Second, the () capture groups take the project code and ticket number and implicitly store them in the $match array. Any description text after the issue number is ignored.

Formatting the issue number

    ticket="${match[1]:u}-${match[2]}"

if we find an issue number, we'll need to format it. This is necessary only because of FlightAware conventions; branch names are snake_case, while Jira issue numbers are properly TRAIN-CASE. We simply create a new variable, ticket, built from the capture groups stored in $match. We upcase the project code portion with the :u expansion modifier to complete the transformation. There are other ways to upcase text, but this is the cleanest in my opinion.

Building the commit message

    gitMsg=$(cat "$COMMIT_MSG_FILE")

At this point, git has already created a message file and populated it with information including a diff summary. We capture all this pre-existing text into a variable, gitMsg. We'll need to add this back to the end of the file after overwriting the file to simulate prepending. There are other methods of prepending to a file, most interestingly by using a here-string, but this is the most straight-forward method.

    printf "\n\n%s\n" $ticket > "$COMMIT_MSG_FILE"
    printf "$gitMsg" >> "$COMMIT_MSG_FILE"

Now to build up our new message, we overwrite the existing message with a formatted string including the ticket number. This string starts with two newlines, providing space to put the substantive commit message, and ends with a newline to distance the ticket number from the git-supplied information. Finally, we append that git-supplied info to the message.

After this hook is complete, git will continue on it's merry way and (probably) open the user's $EDITOR as usual.

Usage

All we need to do to use this hook is to save it as .git/hooks/prepare-commit-msg and make it executable (chmod +x), git will handle the rest!

For security reasons, git doesn't allow committing hooks to a repository (nor anything inside .git/), so this script will have to be added to each project individually. If you'd like to add it to all projects, you can store it in a known directory and have git always look there for hooks:

git config --global core.hooksPath /path/to/your/hooks

However, this will stop git from looking at the local hooks directory. Unfortunately you can't have it both ways, at least as of git version 2.18.

Combine multiple Excel workbooks into sheets in a single workbook

2023-06-27T09:00:00-06:00

It may be useful to have multiple source workbooks which can be individually updated and replaced, then combine them into a single combined workbook for actual use. In my case, the combined workbook is used as a data source in Tableau, with each sheet acting as a table.

Below is a VBA subroutine which can be run in Excel (in the workbook which will be the combined file). The subroutine assumes that all the new, updated files are in a source/ directory which is in the combined file's directory.

Importantly, this subroutine only copies visible sheets (ignoring hidden and very hidden sheets).

Caution: For this script to work, the sheet name in the source files _must_ match the corresponding sheet name in the combined file.

Sub UpdateSheetsFromSourceFiles()

'Disable alerts to delete silently
Application.DisplayAlerts=FALSE

'We assume source files are in the source\ directory
path = ActiveWorkbook.Path & "\source\"
filename = Dir(path & "*.xlsx")
  Do While filename <> ""
    Workbooks.Open Filename:=path & filename, ReadOnly:=True
    For Each Sheet In ActiveWorkbook.Sheets
      If Sheet.Visible = -1 Then 'Only if sheet is visible
        'Remove old version of sheet to update, then pull in the updated version
        ThisWorkbook.Sheets(Sheet.Name).Delete
        Sheet.Copy After:=ThisWorkbook.Sheets(ThisWorkbook.Worksheets.Count)
      End If
    Next Sheet
    Workbooks(filename).Close
    filename = Dir()
  Loop

'Re-enable alerts
Application.DisplayAlerts=TRUE

End Sub

How it works

First, we disable alerts. This allows us to delete files without asking for confimation from the user, making it nice and silent.
The path is determined from the ActiveWorkbook, which in this case is the combined file where the subroutine is running. Using the Dir function, we get the first xlsx file in the source\ directory.
Looping through each sheet in the workbook, we first check to see if the sheet is visible (Visible = -1). If it is, we get to the real workhorse of the function:
- In the combined file (ThisWorkbook), the matching sheet is deleted, then:
- The sheet from the source file is copied in. It's placed at the end of the list of sheets. Since we're looping through the directory, this has the side-effect of alphabetizing the worksheets.
Once all the sheets in a workbook have been looped through, we close it and move on to the next file which matches the string we gave at the start (calling Dir with no arguments returns the next matching file).

ClearNight Retro

2018-05-08T09:00:00-06:00

After a bit of work, I'm proud to introduce ClearNight Retro, a new dark, relaxed retro theme for Atom! The set is a UI theme with matching syntax theme, but both can work separately with other dark themes like Atom's own One Dark.

The core of the theme is forked from Clear Night, and makes use of a relaxed, almost faded color scheme inspired by Gruvbox. The theme set will continue to be maintained by me and the ClearNight organization. I'm no longer using Atom much, I've been leaning more into my configuration of Emacs recently, but the ClearNight themese will continue to receive full support for at least a few years.

Take a look

Try it out

ClearNight Retro is fully released and ready to make your code look good!

Overriding project.el project root in Emacs

2023-03-07T09:00:00-06:00

I've recently been experimenting with replacing Projectile with the built-in project.el, and so far it has impressed me. Not only are all of Projectile's useful features available, but for me project.el runs significantly faster in large repositories. If you're not familiar, both of these packages provide functions to search and operate on files and directories in the same project. If you're using Git, a "project" is probably synonymous with a repository.

Unfortunately, project detection is not always as easy as looking for a .git/ nearby, and sometimes Emacs gets it wrong. Projectile solves this by also looking for a .projectile file, which overrides detection and says "this is the project root". This happens to be one of the features missing in project.el.

Update

Since the writing of this post, Emacs 29 has been released and introduces a variable which may solve this same issue in a cleaner way! Unfortunately it doesn't appear to work for me, but some folks on Reddit commented that it seems to function as expected. So, it may be worth a shot for you: set project-vc-extra-root-markers to a list of file names or glob patterns which mark a project's root in addition to the default ".git", ".hg" and other common markers.

So, the cleaner equivalent to the rest of the post, if it works, is a simple

(setq project-vc-extra-root-markers '(".project.el" ".projectile" ))

If, however, you're like me and can't seem to get this to do anything, the original post still works:

Original post

Luckily, we can provide our own function to project.el which looks for a file like this in the current and parent directories. Even better, the excellent Emacs community has already jumped on this, and a splendid solution was provided by Michael Stapelberg.

Alas, Michael couldn't have forseen that Emacs would change the project root data format in Emacs 29, so the provided function only works in earlier versions. However, adding in forward compatibility isn't much trouble. And while we're at it, we can also provide support for anyone else moving from Projectile like I am, by allowing .projectile to serve as a project root marker alongside Michael's .project.el.

(defun project-root-override (dir)
  "Find DIR's project root by searching for a '.project.el' file.

If this file exists, it marks the project root. For convenient compatibility
with Projectile, '.projectile' is also considered a project root marker.

https://jmthornton.net/blog/p/emacs-project-override"
  (let ((root (or (locate-dominating-file dir ".project.el")
                  (locate-dominating-file dir ".projectile")))
        (backend (ignore-errors (vc-responsible-backend dir))))
    (when root (if (version<= emacs-version "28")
                    (cons 'vc root)
                  (list 'vc backend root)))))

;; Note that we cannot use :hook here because `project-find-functions' doesn't
;; end in "-hook", and we can't use this in :init because it won't be defined
;; yet.
(use-package project
  :config
  (add-hook 'project-find-functions #'project-root-override))

Now we can use touch .project.el in any directory, and project.el with recognize it as the project root!

By the way, the snippet above makes use of use-package which provides fantastic package configuration and loading ability. John Wiegley is currently working on adding it into Emacs itself, so it shouldn't be long before this code snippet is fully native!

One note, in an ideal world, I'd prefer the root marker to be just .project instead of .project.el, but this is already widely used by other tools like Eclipse and I'd rather not cause conflicts. If you'd like to use this in your own Emacs, obviously you can change the function to check for anything you want.

Pro tip: If you'd like to use a project root marker like this, but you don't want other developers to have to worry about it (i.e. you don't want to commit it nor add it to the .gitignore), you can always add locally-ignored files to .git/info/exclude.

Remove (deinit) a Git submodule

2020-11-01T09:00:00-06:00

Every once in a while, I need to deinit a Git submodule, but I just cannot get my brain to remember how, so here's my reminder:

git submodule deinit -f path/to/submodule
rm -rf .git/modules/path/to/submodule
git rm -f path/to/submodule

After those three commands, you're free to commit the deinit. Note that this will not actually remove the submodule locally, you'll need to rm -r to take care of that.

To make things just a bit easier, we can stick those three lines into a script and call it with a Git alias.

Protonmail - Why I switched and you should too

2016-10-26T09:00:00-06:00

Email privacy has historically been less friendly than one might hope, with the most widespread technology being PGP (Pretty Good Privacy). While PGP is actually relatively easy to use, it remains solidly outside the comfort zone of the average user. This is true even with increasing awareness and concern about government snooping and corporate tracking. Privacy is fundamental to the human experience, yet it continues escapes the purview of most people.

Enter ProtonMail, a secure email service designed to be free, easy to use and mobile friendly. Developed by scientists at the European Organization for Nuclear Research (CERN)—the place where all the Higgs Boson hype came from—ProtonMail seeks to give encryption to everyone, protecting them from mass surveillance by governments and corporations. It uses very strong open source cryptography to encrypt your data before it even leaves your computer (or phone or tablet). It stays encrypted _even if you're sending it to someone who doesn't use ProtonMail_. The ProtonMail servers don't have the key to your encrypted emails, which means they can't see what your email holds even if they wanted to, so your email couldn't be shared even if a government ordered it. Plus, the servers themselves protected with Switzerland's very strong privacy laws.

Other features include the ability to set an expiration time on your emails, easy to use filters and tags for organization. While there are paid versions which add extra functionality (like extra storage, custom aliases, priority support, etc.), most users have and only need the standard version, which will be free forever with no ads. How do they keep running a free service without ads?

Besides their record-breaking crowdfunding campaign on Indiegogo, they receive donations from their many users. This is combined with heavier users like myself who use the paid services to gain access to functionality like using custom domain names (ProtonMail secures my public-facing email). In addition to all their features, they don't track or log any identifiable information—unlike Google or Yahoo.

ProtonMail offers a beautiful, Lovie design award nominated web-based client, as well as highly rated easy-to-use apps for Android and iOS. For the more-than-average security minded, a standalone APK is in the works also. Plus–a necessity with personal data–ProtonMail offers two-factor authentication.

Of course, nothing can be perfect. ProtonMail is fully released, but doesn't yet offer the full functionality of a service like GMail. Don't get me wrong, email is their focus and that part is fantastic. However, the service does not yet offer a calendar or even calendar integration. Nor is there an instant messaging capability, nor a desktop client. The spam filter isn't perfect (though none are), and I would prefer more storage space. However, with many of these features on their way as development continues, I am more than very pleased with the state of ProtonMail.

Privacy is an important part of life and secure email is a huge step in the direction of this basic freedom. Going against the grain of less user friendly—though still very secure—methods of encryption like PGP, ProtonMail brings email privacy back to the people while still maintaining a fantastic user experience characteristic of a first-class email service. This is why I've switched all my mail to ProtonMail, and why I encourage without hesitation that you do the same. And for the record, no I have not been paid or asked to write about this, I really do love ProtonMail that much.

Snyk Language Server in Emacs

2023-11-07T09:00:00-06:00

At DroneDeploy, we've been experimenting with more and more AI tools like GitHub Copilot, but we're concerned about the security implications of incorporating complex generated code snippets into our production projects. To help out, we're experimenting with the Snyk language server, which provides security insights and vulnerability scanning for code and dependencies. However, there's no official package for using the Snyk language server in Emacs. So, I dove into making Snyk and Emacs get along nicely, a feat which returns exactly zero search results as of the writing of this post. I finally got it working, and I hope this helps anyone else looking for a solution to the same issue.

Update

Since the writing of this post, we've concluded our experiment and found that Snyk was not worth the cost for us, and we find more value in investing in better peer review practices instead. However, the process of setting up a language server configuration was still interesting.

Before we start, you should already:

Be somewhat familiar with Emacs Lisp since these steps don't explain a whole lot and you should always be wary of copying code off the Internet.
Be using LSP Mode—as of right now, the built-in Eglot (in v29+) can't run add-on servers in parallel, so LSP Mode is the only option.

Snyk Language Server Setup

Since no one seems to have written about this before, this may not be a perfect approach, but this is the workflow I've found to be effective. The official IDE integration documentation is a bit outdated, so the following steps reference the current server documentation.

First, install the server using the bash installer script provided by Snyk: snyk/snyk-ls/main/getLanguageServer.sh. This is basically a fancy wrapper around a curl call, but don't blindly run scripts from the Internet. Please do take a look at what this script is doing before you run it on your own system.
Install the Snyk CLI (brew tap snyk/tap && brew install snyk). This step lets you get your authentication token. Since the Snyk language server supports automatic authentication, this shouldn't actually be necessary, but I had issues with excessively repeated re-authentication, so the token provides a workaround.
Run snyk config get api to actually get your token after authenticating in your browser. Especially if your config is version-controlled, do not commit the token; load it from an external source (my init.el loads a git-ignored init.local.el if it exists, that's one place to put such a token).
Finally, register the LSP client with LSP Mode:

(lsp-register-client
 (make-lsp-client
  :server-id 'snyk-ls

  ;; The "-o" option specifies the issue format, I prefer markdown over HTML
  :new-connection (lsp-stdio-connection '("snyk-ls" "-o" "md"))

  ;; Change this to the modes you want this in; you may want to include the
  ;; treesitter versions if you're using them
  :major-modes '(python-mode typescript-mode)

  ;; Allow running in parallel with other servers. This is why Eglot isn't an
  ;; option right now
  :add-on? t

  :initialization-options
  \`(:integrationName "Emacs"
    :integrationVersion ,emacs-version

    ;; GET THIS FROM SOMEWHERE ELSE, don't hardcode it
    :token ,snyk-ls-token

    ;; Enable these features only if available for your organization.
    ;; Note: these are strings, not booleans; that's what the server
    ;; expects for whatever reason
    :activateSnykCodeSecurity "true"
    :activateSnykCodeQuality "true"

    ;; List trusted folders here to avoid repeated permission requests
    :trustedFolders [])))

Using Snyk in Emacs

After setting everything up, simply open a file using one of the major modes you configured above. If it's not in one of the :trustedFolders, Snyk will ask you if you'd like to trust the one you're in. Keep in mind that Snyk takes a few seconds to start once you open the first file in a project. So, if you don't see it right away, just be patient.

And there you have it! You can now use the Snyk language server in Emacs.

Duplicate IDs in HTML: What would happen?

2017-09-27T09:00:00-06:00

The id attribute is an often-used and useful HTML attribute. However, they're always meant to be unique. The HTML5 specification explicitly says:

The value must be unique amongst all the IDs in the element's home subtree

The HTML 4.01 specification says basically the same thing, that an id "must be unique in a document".

That's pretty clear, and is usually followed. When you want to use the same identifier for multiple elements, you should and probably usually do use a class attribute instead. But what if you do reuse the same id, intentionally or not? Take this example:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Duplicated IDs</title>
    <style>
      #sec1, #sec2 {
        color: blue;
      }

      #sec3 {
        color: red;
      }
    </style>
  </head>
  <body>
    <nav>
      <a href="#sec1">Goto 1</a>
      <a href="#sec2">Goto 2</a>
      <a href="#sec3">Goto 3</a>
      <a href="#sec3">Goto 4</a>
    </nav>

    <div id="sec1">
      <p>Section 1</p>
    </div>

    <div id="sec2">
      <p>Section 2</p>
    </div>

    <div id="sec3">
      <p>Section 3</p>
    </div>

    <div id="sec3">
      <p>Section 4</p>
    </div>

    <script>
      document.getElementById('sec3').innerHtml('Sup!');
    </script>
  </body>
</html>

Notice that both 'Section 3' and 'Section 4' have the same id="sec3". Oh no! The HTML police are already knocking on my door! So what actually happens when a browser comes across duplicated id's? How does styling work? Document fragments? Javascript accessing the DOM?

Surprisingly, behavior is quite consistent across modern browsers as of this writing. Modern browsers—including Chrome, Firefox, Opera, etc.—are quite forgiving when it comes to some invalid HTML like duplicate id's. The HTML5 specification lays out three main uses for unique identifiers, basically comprising of fragment identifiers, DOM targeting for scripting and CSS styling. The behaviors of duplication on each of these uses is different, but related.

Document fragments: The browser will navigate to the first instance of the specified id. In the example above, clicking on the nav links "Goto 3" and "Goto 4" will both go to "Section 3" since they both use href="#sec3".
Javascript targeting: Javascript will select the first instance of the id. In the example, the script will only change the HTML inside the "Section 3" div.
Styling: All instances of the id are styled. In the example above, both "Section 3" and "Section 4" are styled with color: red;.

In all, document fragments and Javascript choose the first element, while CSS styles them all.

Why do all the browsers act the same, even though the specification doesn't say what to do and forbids duplicated identifiers in the first place? The specific reasons are varied, but in general browsers trend towards being developer-friendly. This means rendering bad markup by doing their best to interpret what the author means, and fail gracefully and often silently when necessary. But does this mean it's okay to duplicate id's? No.

Since the HTML5 specification, as well as HTML5.1 and HTML5.2 don't dictate what browsers should do with duplicate id's, nor is there any other standard which does. Therefore, behavior is not guaranteed and could change at any time.

The point of this article is that while browsers are forgiving of duplicated id's, this behavior is not guaranteed or predictable, and should always be avoided. Duplicated identifiers are bad style, create confusing code, are invalid HTML and most importantly, they make me cry. Surely you don't want me to cry.

More often than the world should allow (which is not at all), I have come across invalid HTML like this in the professional environments. Fixing it is time consuming and typically frustrating, and it drives me to drink (coffee). The world of development is filled with invalid and unreadable code, and this is why I cry.

What's new in http-server v0.12?

2019-11-23T09:00:00-06:00

http-server has gone a while without a substantial release, despite issues and PR's coming in at full force. Unfortunately, the core team is small, only three devs, and we all have busy lives and full-time careers. But, we've been able to pull together a major release, with some interesting improvements.

Ecstatic v4

One of the largest set of changes is improvements to the underlying project, ecstatic, which recently reached version 4.0.0, and has had a few patch releases since. For http-server, the most important improvements include:

Ability to override MIME types with a .types file
Improved charset detection
Improved accuracy when checking if gzip responses are allowed
Elimination of a file descriptor leak
Elimination of a DOS vulnerability

Brotli encoding

In addition to gzip compression, http-server can now serve Brotli encoded content. This provides better compression ratios than gzip for many types of content, especially text-based assets like HTML, CSS, and JavaScript.

.httpserverrc settings file

This improvement has been a long time coming, with the original PR opened at the start of 2015! We know passing switches can become cumbersome when automating starting up a server, so now it's a bit easier.

By using a .httpserverrc file in the directory to be served. The file is simple JSON and uses the same switch arguments as the CLI. This is one of my personal favorite improvements!

Here's an example .httpserverrc file:

{
  "port": 8080,
  "cache": 3600,
  "cors": true,
  "log-ip": true
}

--find-port

If the port given with the -p switch is not available, this new switch will allow the server to automatically find a free port to bind to. No more "port already in use" errors when you just want to get a server running quickly!

Support for HTTP basic access authentication

http-server now supports basic authentication by passing --username and --password switches, which the client must authenticate with. This is useful for protecting development servers or staging environments.

Client IP logging

By passing the --log-ip option, the client's IP is logged to stdout. This can be helpful for debugging or monitoring which clients are accessing your server.

Improved handling of proxy errors

Previously, proxy errors had the potential to crash the server with an unhelpful error message. Now, the server logs the error (and status code) and continues without a crash. Much more robust for production use.

Other improvements

Aggressive no-cache when the cache option is set to -1
A clever hack for a catch-all redirect (useful for single page apps) was added to the Readme page
Fixed some issues with the -o [path] switch
Better test messaging on some types of errors
Cleaner handling of setting options behind the scenes

We're excited to get this release out to the community. The combination of these improvements should make http-server more robust, feature-rich, and easier to use. Keep an eye on the GitHub repository for the official release announcement!

Remove an element from an Array in Javascript

2017-10-25T09:00:00-06:00

From time to time, one comes to the issue of removing elements from an Array. While there are certainly ways to do this with built-in functions like splice(), they just don't quite do everything I want. So, as usual, I made my own.

The first iteration I created was designed to be able to polymorphically take either a single argument (the index of the element to remove), or two arguments defining a range. It then basically concatenates the part of the array before the removed element(s) with the part of the array after the removed element(s). Here's how that took shape:

const removeElement = (arr, from, to) => {
  const rest = arr.slice(to || from);
  arr.length = from;
  return [...rest];
}

This works out pretty well, and I even started using it in a project. However, I soon came across the case where I wanted to remove the last element in an array. Sure, that's just as easy as removeElement(arr, arr.length - 1), right? Well, sure, but I'm too lazy for all that typing. Ideally what I really want is negative indexing like Python allows, where arr[-1] === arr[arr.length - 1].

I did a little researching around to see how others might have solved the same issue, and came across this blog post by none other than John Resig, the creator of jQuery itself and the author of one of my favorite books on Javascript.

In the post, John outlined five goals for his Array.remove:

It had to add an extra method to an array object that would allow me to remove an item by index (e.g. array.remove(1) to remove the second item).

It had to be able to remove items by negative index (e.g. array.remove(-1) to remove the last item in the array).

It had to be able to remove a group of items by index, and negative index (e.g. array.remove(0,2) to remove the first three items and array.remove(-2,-1) to remove the last two items).

It had to be destructive (modifying the original array).

It had to behave like other destructive array methods (returning the new array length - like how push and unshift work).

Those sound like pretty good goals to me. It covers the base cases my function already solves and adds in the negative indexing I'd like, plus it raises the issue of making the function destructive. Even better, John implemented his function as an addition to the Array object itself, which fits object oriented-ness quite well.

So I combined my function and ideas with John's function, and came up with something I'm quite happy with. This function is already being used in several projects and is ready to be utilized elsewhere:

The complete function

Array.prototype.removeElement

// Array#removeElement - By Jade M Thornton (ISC Licensed)
Array.prototype.removeElement = function(from, to) {
  const rest = this.slice((to || from) + 1 || this.length);
  this.length = from < 0 ? this.length + from : from;
  this.push(...rest);
  return this;
}

Example usage

let a = [1, 2, 3, 4, 5, 6, 7, 8, 9];

// remove the element at index 1 (second element)
a.removeElement(1);
// a --> [1, 3, 4, 5, 6, 7, 8, 9]

// remove the last element (a.length - 1)
a.removeElement(-1);
// a --> [1, 3, 4, 5, 6, 7, 8]

// remove elements 2-4 (INCLUSIVE)
a.removeElement(2, 4);
// a --> [1, 3, 7, 8];

// remove elements (-1)-(-2) (INCLUSIVE)
a.removeElement(-1, -2);
// a --> [1, 3]

Explanation

What's that you ask? What in David Hilbert's beard are those six lines of code doing? Let's take a look at it again, along with some helpful line numbers.

Array.prototype.removeElement = function(from, to) {
  const rest = this.slice((to || from) + 1 || this.length);
  this.length = from < 0 ? this.length + from : from;
  this.push(...rest);
  return this;
}

Each line is doing something important, so let's break them up and talk through what's going down.

In line 1 is the assignment of our new anonymous function to Array.prototype.removeElement. Unlike my first implementation above, this allows us to use the function as a method on an instance of an Array itself. In a more heavily object-oriented language like Java, this would be similar to adding our function to the Array object, which we would later instantiate.

Line 2, in a nutshell, grabs the part of the Array starting immediately after the last element we want to remove. For example, if the function call is arr.removeElement(2); then rest will be the elements of the Array starting at index 3 and continuing to the end of the Array. However, there's some trickiness in there for handling different cases. Let's break this line down further.

What we're assigning to rest is a slice of this, which is referring to the Array we're working on.
The argument (yes, singular argument) takes advantage of falsy values. The first part, (to || from), evaluates to the value of to if it's assigned to a value. If to is undefined, which is falsy, the statement short-circuits to the value of from.
We then add 1 to the value of (to || from), which gets us the element immediately after the removal section.
In the case that (to || from) is -1, meaning we want to remove the last element, then adding 1 brings it to 0. we don't want to roll over to the first element like that, so we take advantage of 0 being falsy. (to || from) + 1 || this.length lets us translate -1 into the last element.

Line 3 handles the front part of the Array, the part before the removal area. We use a conditional operator to handle negative indexing. If from is negative, this.length gets from added to itself (which is the same as subtracting the negative). Otherwise, we just use from directly. Because Javascript is (rightfully) zero-indexed, this results in this Array being shortened correctly.

In line 4, we reassemble the section before the removed element(s), stored in this, with the section after the removed element(s), stored in rest. We do this by pushing rest onto this Array—utilizing the spread operator—which achieves the goal of destroying the old Array in favor of the new, altered one.

The last (meaningful) line, line 5, the new Array is returned so the function can be used in an assignment. Technically there's a fifth line, but it's a closing brace. I'm going to let you guess what that does.

All code created by me, Jade Michael Thornton, is licensed under the terms of the ISC License, just like the rest of this site.

A list of the best bug write-ups I've read

2023-11-11T09:00:00-06:00

A modest list of interesting blog posts I've come across containing tech mystery stories exploring how a bug or mistake or other problem came about, how it was discovered, how it was fixed, and maybe some lessons to learn.

The case of the 500-mile email, by Trey Harris
A three part series by James Haydon on the August 2023 UK NATS (ATC) meltdown:
A Very Subtle Bug, by Nelson Elhage. This bug was caused by unusual behavior in Python's handling of SIGPIPE which was fixed in Python 2.7.
My Hardest Bug Ever, by Dave Baggett. Unlike almost every bug you'll ever come across, Dave was eventually forced to blame the hardware.
I Accidentally Saved Half A Million Dollars, by "Ludicity", although this reads as a junior engineer's perspective
The hardest bug I ever debugged, by Jacob Voytko

Fixing cmdline for Non-Terminal Usage

2019-01-20T09:00:00-06:00

Working with TCL at FlightAware, I've run into more than a few frustrating bugs in the standard library packages. One that was particularly annoying was in the cmdline package, which is used for parsing command-line arguments. So I made a fork.

The problem was that the original relies on the global argv0 variable to determine the application name for error messages. This works fine when TCL is running as a standalone script from the command line, but fails completely when TCL is embedded in other applications or used in non-terminal contexts where argv0 doesn't exist. That's exactly what we do at FlightAware, where TCL runs in a server context.

Rather than go through the painful process of contributing back to the original project (which uses Fossil for version control, a tool I'd rather avoid), I created a fork that fixes this specific issue. The fix was simple but effective: remove the dependency on argv0 entirely and strip out the getArgv0 function that was causing the problem.

The result is a drop-in replacement for the standard cmdline package that works in all contexts, not just terminal applications. You can find it at github.com/thornjad/cmdline.

This is exactly the kind of bug that makes working with TCL packages frustrating. The ecosystem has been stagnant for years, and we're stuck with these kinds of limitations until the language gets off of Fossil and into the modern world..

Business Is Not War

2026-02-25T09:00:00-06:00

I read Frank Slootman's Amp It Up recently, and it clarified my thinking about management philosophy, even though I landed somewhere different from where the book wanted to take me. Slootman's thesis is something like: increase the urgency and demand more from everyone. Cal Newport's Slow Productivity argues the opposite: do fewer things and obsess over quality. I think one of these approaches is more honest about how good work actually happens, and it is not the one with war metaphors.

Slootman says, without apparent irony, "It's no exaggeration to say that business is war." This is literally an exaggeration. And it's a useful focal point for everything I find problematic with the book. The war metaphor treats employees as soldiers, competitors as enemies, and market share as territory. It frames business as a zero-sum game when most of it is not. Economics has understood this since at least Adam Smith, that most market transactions grow the pie rather than divide it. Slootman's war framing assumes that every gain requires someone else's loss, and that is just not how most business works.

Slootman's core framework has five parts: raise standards, align people, sharpen focus, pick up the pace, transform strategy. All of these ideas are genuinely useful. The section on focus is particularly solid. "Priority" should be a singular word; when you have many priorities you have none. Ask "what are we not going to do?" and "if you can only do one thing for the rest of the year, what would it be?" These are good questions. Most leaders would benefit from asking them more often.

And the emphasis on high standards is something I appreciate and agree with fully. This is where the two philosophies actually converge. Newport's "obsess over quality" and Slootman's "raise your standards" are pointing at the same thing. Holding people to a high bar and being willing to have difficult conversations about performance are all part of good management. I have held those kinds of conversations and they mattered. Where the two approaches diverge is on how you get there. Slootman's answer is urgency. When someone says they'll get back to you in a week, ask them why not tomorrow. This sounds productive in a book, but in practice, it creates an environment where people are always behind, always feeling the heat, never able to think at the depth that good engineering requires. Higher urgency leads to burnout.

Newport makes the opposite case and I find it far more convincing. Slow Productivity rests on three principles: do fewer things, work at a natural pace, and obsess over quality. The argument is that the most meaningful work in history was not produced under artificial urgency. It was produced by people who had the space to think deeply about fewer problems. The claim is not that we should all move slowly for the sake of it, but that sustained focus on fewer things at higher quality produces better results than spreading attention thin and racing to meet arbitrary deadlines.

As an engineering manager, this matches what I see in practice. The best work my team produces comes from periods of focus, not pushes of intensity. When people have the space to think carefully about a problem, they build things that hold up. When they are rushed, they ship something that passes review but needs to be revisited in three months. The urgency model optimizes for visible activity. The slow productivity model optimizes for outcomes.

I also find myself uncomfortable with the worldview underneath Slootman's framework. The book assumes that work is the central project of your life. I do not share that assumption. I care about leading my team well and I care about creating real value in what we build. But work is one part of a life, and a management philosophy that only functions for people who have made it their whole thing has a limited audience. The "quiet quitting" discourse during the pandemic revealed how many workers already felt this way but had no language for it. The phrase was misleading because most of them were not quitting anything. They were just drawing a boundary that Slootman's philosophy does not allow for.

Where these two philosophies genuinely diverge is on what they ask of people. Slootman's model asks people to run hotter. Newport's asks them to run deeper. One treats intensity as a virtue. The other treats it as a cost, one that compounds over time and eventually degrades the quality of the work it was supposed to improve. I know which approach I want to bring to the teams I lead.

What's new in ECMAScript 2017

2017-09-29T09:00:00-06:00

Two years ago, ES6 (retconned to ECMAScript 2015) provided a massive update to the existing and already powerful ECMAScript standard. Incredibly useful features like const, let, arrow functions and destructuring syntax were unleashed upon the world. Another big change was the new yearly release schedule based on proposals are ready to ship as of the TC39 meeting. The next annual release, ECMAScript 2016, wasn't much to gawk at in comparison, adding only two new features—Array.protoype.includes and the exponentiation operator—and a handful of changes to the existing standard.

The newly released ECMAScript 2017 is somewhere in between, not being a massive update, but adding a sizeable number of features and changes. Let's take a look at all the new additions in this year's release.

Object.values and Object.entries

The first addition to ECMAScript 2017 liberates us from jQuery dependence when it comes to enumerating pairs of entries or values from objects. This adds two new methods to the Object prototype, complementing pre-existing methods like keys(). values() returns an array of all values, without the keys, while entries() returns a two dimensional array of keys and values. Let's see an example use:

const jmthornton = {
  name: 'Jade Michael',
  writes: 'code'
};

Object.entries(jmthornton);
// [['name', 'Jade Michael'], ['writes', 'code']]

const jmthornton = {
  name: 'Jade Michael',
  writes: 'code'
};

Objects.values(jmthornton);
// ['Jade Michael', 'code']

Documentation:

String padding

This new feature is relatively small, but comes to the rescue of npm and Node itself. If you don't remember, March 2016 saw a bit of a crisis where a widely used package (even by Node and Babel) called left-pad was unpublished from npm and crippled developers everywhere. This new ECMAScript feature makes the package unneeded. You can use it to easily format string output so the string reaches the given length:

'foobaring foo'.padStart(20);       // "       foobaring foo"
'foobaring foo'.padStart(20, '#');  // "#######foobaring foo"

'foobaring foo'.padEnd(20);         // "foobaring foo       "
'foobaring foo'.padEnd(20, '#');    // "foobaring foo#######"

Documentation:

Object.getOwnPropertyDescriptors

Copying objects manually is never fun, and comes with a lot of uncertainty, and with the rising awareness and use of functional programming, immutability is very important. The new method on the Object prototype solves this issue once and for all. Object.getOwnPropertyDescriptors takes in an Object and returns the descriptors describing the attributes of a property (like value, if it's writable, etc.) Here's an example of how it's used:

const source = {
  name: 'Jackie Smith',
  id: 555
};

const sourceClone = Object.create(
  Object.getPrototypeOf(source),
  Object.getOwnPropertyDescriptors(source)
);

const stateClone = Object.create(
  Object.getPrototypeOf(this.state),
  Object.getOwnPropertyDescriptors(this.state)
);

// make changes to stateClone

this.setState(stateClone);

Documentation:

MDN: Object.getOwnPropertyDescriptor()

##Trailing commas in function parameter lists and calls

This new update is purely aesthetic, allowing trailing commas in function parameter lists and calls. For a long time, we've been able to put trailing commas in objects and arrays, so it's only fitting that parameter lists join the ranks. There's no performance or big underlying changes here, but I think it's a good addition. Example for clarity:

function foo(
    paramA,
    paramB,
    paramC,
  ) {
  console.log('No more complaints from the compiler!');
}

Documentation:

MDN: Trailing commas

Async functions

A solution to chained callbacks, that all-too-common pattern especially prevalent with APIs, async functions are a bit of syntatic sugar, but they let you write promise-based code in a way that looks synchronous. As Jake Archibald puts it, it makes "your asynchronous code less 'clever' and more readable". Check out this excellent in-depth walk-through by Nicolás Bevacqua. Here's the gist of the syntax:

async function doTheThing(data) {
  try {
    const valA = await anAsyncFunction(data);
    const valB = await aDifferentAsyncFunction(valA);
    console.log(`valB: ${valB}`);
  } catch (err) {
    console.error(`Oh noes! ${err}`);
  }
}

And to use it with an arrow function:

const doTheThing = async (data) => {
  try {
    const valA = await anAsyncFunction(data);
    const valB = await aDifferentAsyncFunction(valA);
    console.log(`valB: ${valB}`);
  } catch (err) {
    console.error(`Oh noes! ${err}`);
  }
}

Documentation:

MDN: async function

Shared memory and atomics

This new addition is a little more technical than others, but definitely one of the coolest. It adds a new SharedArrayBuffer, and allows the already-existing TypedArray and DataView types to be used to allocate shared memory. The associated Atomics object allows operations to be carried out on that shared memory. The proposal states these cases for justification:

Support for threaded code in programs written in other languages that are translated to asm.js or plain JS or a combination of the two, notably C and C++ but also other, safe, languages.

Support for hand-written JS or JS+asm.js that makes use of multiprocessing facilities for select tasks, such as image processing, asset management, or game AI.

The author of the proposal, Lars T Hansen, provides a tutorial for use of shared memory, and Dr Axel Rauschmayer dives in to explain it all in depth in a long form article.

Documentation:

That's it for ECMAScript 2017! Lots of new changes, and all welcome additions to the specification. Many of these features are already supported in major browsers, and the rest are soon to follow. By now, ECMAScript 2018 is in the works and I'm excited to see what proposals make it in!

Org-roam: Automatically Set Node Created and Modified Dates

2024-03-18T09:00:00-06:00

Org-roam is an Emacs package for non-hierarchical note-taking, and it does a brilliant job at organizing these thoughts but does not include automatic timestamping. By default, Org-roam does include the creation timestamp in the file name, but that's not easily read by a human.

To add this generally useful information, I automatically add a :created: property when visiting a node if it doesn't already exist, and a :modified: property when saving a node. This way, I can see when a note was created and when it was last modified.

Note that the :created: property parses the timestamp from the filename and relies on Org-roam's default naming scheme. If you use a different naming scheme, you'll need to modify the org-roam-extract-timestamp-from-filepath function to match your scheme.

Automating Creation Dates

(defun org-roam-insert-created-property ()
  "Insert :created: property for an Org-roam node.

Does not override the property if it already exists.

Calculation of the creation date is based on the filename of the note,
and assumes the default Org-roam naming scheme."
  (interactive)
  (when (org-roam-file-p)
    ;; Don't update if the created property already exists
    (unless (org-entry-get (point-min) "created" t)
      (let ((creation-time (org-roam-extract-timestamp-from-filepath
                            (buffer-file-name))))
        ;; Don't error if the filename doesn't contain a timestamp
        (when creation-time
          (save-excursion
            ;; Ensure point is at the beginning of the buffer
            (goto-char (point-min))
            (org-set-property "created" creation-time)))))))

Extracting Timestamps from Filenames

(defun org-roam-extract-timestamp-from-filepath (filepath)
  "Extract timestamp from the Org-roam FILEPATH assuming it follows the default naming scheme."
  (let ((filename (file-name-nondirectory filepath)))
    (when (string-match "\\([0-9]\\{8\\}\\)\\([0-9]\\{4\\}\\)" filename)
      (let ((year (substring filename (match-beginning 1) (+ (match-beginning 1) 4)))
            (month (substring filename (+ (match-beginning 1) 4) (+ (match-beginning 1) 6)))
            (day (substring filename (+ (match-beginning 1) 6) (+ (match-beginning 1) 8)))
            (hour (substring filename (match-beginning 2) (+ (match-beginning 2) 2)))
            (minute (substring filename (+ (match-beginning 2) 2) (+ (match-beginning 2) 4))))
        (format "[%s-%s-%s %s:%s]" year month day hour minute)))))

Keeping Modification Dates Current

(defun org-roam-insert-modified-property ()
  "Update the :modified: property for an Org-roam node upon saving."
  (when (org-roam-file-p)
    (save-excursion
      ;; Ensure property is applied to the whole file
      (goto-char (point-min))
      (org-set-property
       "modified" (format-time-string "[%Y-%m-%d %a %H:%M]")))))

The integration of these functions into your Emacs and Org-roam config ensures that every note's origins and edits are easily accessible and readable. To make these actually run, I set them up to run on before-save. There may be better hooks for this, but Org-roam's own hooks make it kind of difficult in my own setup, so I take the more brute force approach and it works fine for me:

(add-hook 'before-save-hook #'aero/org-roam-insert-created-property)
(add-hook 'before-save-hook #'org-roam-insert-modified-property)

Weather Station Forwarder on Cloudflare Workers

2026-03-29T09:00:00-06:00

I have a Tempest weather station and I quite love it. The app is excellent and I love checking the readings more often than a sane person might. Tempest already shares the weather data to some sources when the public share data setting is active, which also allows it to appear publicly on the Tempest weather site. But I really believe in contributing weather data to the public meteorological record, so I want to send to more weather aggregation sites. Philosophically, I hold the belief that surface weather is theoretically deterministic given sufficient observational density, and probabilistic forecasting is better today only because we lack enough weather data. Weather models are getting remarkably good, but fundamentally we're working around a data problem. My one station is a tiny push in a better direction, and I want those readings going to as many networks as I can, starting with NOAA's Citizen Weather Observer Program (CWOP).

One starting point is WeeWX, which I planned to run on a Raspberry Pi Zero (because I happened to have one lying around). WeeWX is mature, well-documented, and well-loved by weather hobbyists. I got about halfway through the setup documentation and even got a simulated weather station running before remembering that I genuinely do not enjoy DevOps or running servers. Nothing against WeeWX, I just don't want to run it, even though its pretty hands-off. The Pi Zero went back into its drawer.

Then I found WundergroundStationForwarder by Leo Herzog, a Google Apps Script project that pulls from the Tempest API and forwards the readings to reporting services on a timer. It's simple, serverless, no hardware needed. I would have run it immediately, except that I remembered that I spent a significant chunk of my time when I worked at the University of Minnesota writing Google Apps Script, and I did not enjoy it much better than configuring servers. The development environment is cramped and under-featured, and debugging is painful, and quota limits have a way of surprising you at unexpected times.

Luckily, I deal with Cloudflare Workers in my work at DroneDeploy. The runtime is quite sane, wrangler is a real CLI, and cron triggers are a first class feature. Plus the free tier could probably handle ten thousand times the load of this functionality without blinking. So porting Leo's project to Workers was the obvious path for me.

I also decided to treat this as an experiment in end-to-end agent-driven development. I use Claude Code regularly for small, well-scoped work, but as a manager, I don't often have the opportunity to define and implement complex projects anymore. So I read through the GAS source, mapped out the destination integrations, defined the overall architecture, and wrote up a plan that included comprehensive testing. After less than an hour of refinement, I handed it off to a Claude Code agent team and let it run. After about 10 minutes (on coffee shop WiFi, so a lot of waiting for tokens to stream), I had a full feature, with only one bug to fix.

The result is CloudflareTempestStationForwarder (creative name, I know, thanks), and it came out better than the source in a few ways, if I may be so bold. The Workers module system allowed pushing the code toward cleaner separation than the GAS original. For example, unit conversion math is in its own module and each destination has its own module. The GAS original had no test suite (GAS testing is no joy), but the port runs real tests in the workers runtime via vitest.

Having planned for WeeWX, I had applied for my CWOP station ID a week prior, since CWOP approval is manual and takes a while (much love to the unsung heroes of NOAA and NWS who run this program as well as others like Skywarn). So by the end of just one afternoon, my station was reporting to CWOP, Weather Underground, PWSWeather, OpenWeatherMap, WeatherCloud and Windy on a five-minute interval (with more destinations to be built later).

Between this project and my professional work, what I keep learning time and time again is nothing new. Garbage in, garbage out, and its corollary: quality in and quality out. Spending my brain power on a well-specified architecture document rather than the actual code produced a coherent result that I can review with confidence and rely on tests that I trust. Without AI, I'm confident I could have produced a fairly literal GAS to JavaScript transliteration filled with hacky code and misleading comments. And given how much I have always despised the process of writing tests, I'm sure that my result would have zero tests.

The project is available on GitHub under Creative Commons BY-SA 4.0, the same as Leo's original project from which the vast majority of my code derives directly. If you have a Tempest station and want your readings in public networks without maintaining a Raspberry Pi on a shelf or a GAS project in your account, it should be straightforward to get running. But please open an issue if it's not.

A Few Lesser-Known Emacs Packages

2023-06-25T09:00:00-06:00

When it comes to Emacs packages, there are a few "must-have" selections that always appear on popular lists, from Magit to Helm and/or Ivy, and the necessity of the sane person: Evil. But for the more experienced Emacs user, finding lesser-known packages can add powerful new functionality and streamline day-to-day working methods. Here are several of my favorite Emacs packages that don't always make the most popular lists, in no particular order.

Virtual Comment

An unusual yet surprisingly helpful package. It allows you to create a "virtual" comment on a line of code, without altering the original code on disk at all. The comment is then displayed above the line instead of cluttering the main Emacs buffer. This is incredibly useful for exploring complex new code, reviewing changes and even quick prototyping.

Writegood Mode

A tool that combats common writing pitfalls in everything from documentation to code comments. With helpful (if sometimes annoying) features such as highlighting weasel words, passive voice or repeated phrases, it helps users tighten their writing style and produce more concise, high-quality documents. Truly a must-have for anyone who deals with documentation or coding comments on a regular basis.

Counsel-Spotify

If you're a fan of Counsel and Ivy, and you use Spotify, then maybe a package putting them together deserves some attention. This utility allows you to control Spotify playback without leaving Emacs, effectively turning Emacs into a somewhat-awkward-but-functional Spotify remote. While it doesn't provide access to all of Spotify's catalog functions, it's a great tool for quickly pausing, skipping or adjusting volume settings during a work session. It can even browse songs, albums and artists, though I haven't found this particularly useful myself.

Unmodified Buffer

This one is a small yet compelling package. It resets the "modified" flag on a buffer automatically if the new buffer content matches the content of the file on disk. This means that you won't accidentally overwrite a previously saved copy of a file with identical buffer content, saving you time and headaches in the long run. Honestly this should be the default behavior in core Emacs.

ToDo Light

Okay, this one is a bit of a personal plug, but it's made a noticeable impact in streamlining my Emacs workflow. It highlights keywords such as TODO, FIXME and TEMP, helping users quickly locate areas in a project that need attention. It's easy to customize, so you can add as many keywords or phrases as you would like.

StormScope: Giving Real-Time Weather Data to Your AI

2026-04-07T09:00:00-06:00

I built an MCP server that gives AI assistants access to real-time US weather data. It pulls from seven different sources, aggregates them into structured JSON, and exposes nine tools that any MCP-pluggable client can call. The project is called StormScope, and it's open source under an ISC license.

What I actually wanted was for the AI I already use every day to understand weather the way I want to. I've been a weather enthusiast for practically all my life, the kind of person who reads SPC outlooks more often than a sane person might, especially once the upper Midwest starts thawing out and things get interesting. I wanted to be able to ask my AI about severe weather risk, or current conditions, or what the 500mb pattern looks like, and get answers grounded in real observations rather than over-eager hallucinations. LLMs know a surprising amount about meteorology in the abstract, but they have no idea what the weather is doing right now. StormScope fills that niche gap.

The data problem

Weather data in the US is remarkably good and remarkably free. The National Weather Service API returns current observations, forecasts, gridpoint data, and active alerts. NOAA's Storm Prediction Center publishes severe weather outlooks as GeoJSON. The Iowa Environmental Mesonet (our neighbors at Iowa State) archives NEXRAD radar imagery and WPC surface bulletins. Open-Meteo provides global model data including pressure-level fields. All of these are public, well maintained, and free to use (much love to the unsung heroes at NOAA and NWS, and everywhere else, who keep these systems running).

One problem is that no single source gives you the full picture. NWS gives you surface observations and forecasts but nothing about upper-air patterns. SPC gives you severe weather risk but only as polygons on a map. Radar data exists as imagery, which an AI cannot interpret without help. And if you want to know whether you're in the warm sector ahead of a cold front, you need surface analysis data that lives in a completely different format, an encoded bulletin called CODSUS that uses decades-old 7-digit coordinate notation. All of it is freely available and machine-readable, so StormScope aggregates all of it rather than leaving it scattered across half a dozen APIs when an AI could be using it at once.

How it works

The server is built with FastMCP, a Python framework for building MCP servers. Each tool is an async function that accepts optional latitude and longitude (falling back to a configured primary location) and returns structured JSON. The AI calls whichever tool matches the user's question. Conditions, forecasts, alerts, briefings, the straightforward stuff works the way you'd expect.

The interesting problems start when a question requires data that doesn't come back as a simple JSON response. "Am I at risk for severe weather this afternoon?" sounds like one question, but answering it well means pulling the SPC's categorical and probabilistic outlooks (get_spc_outlook), checking surface analysis for whether you're in the warm sector ahead of a cold front (get_surface_analysis), and looking at the 500mb pattern for shortwave energy that might trigger development (get_upper_air). Each of those is a separate tool call against a different data source, and some of those sources require some computation before the data is useful to an AI.

The SPC publishes outlooks as GeoJSON polygons, which is great for mapping but useless for a text-based AI conversation. So get_national_outlook converts those polygons into human-readable region descriptions, "central Oklahoma" or "northern Texas" instead of a coordinate array. The surface analysis lives in a CODSUS bulletin (more on that later), and get_surface_analysis parses it into front positions and pressure centers with distances and bearings from your location. Radar is imagery, which an AI can't look at, so get_radar provides NEXRAD station metadata alongside a textual precipitation summary.

The vorticity computation was a fun side problem. Vorticity is essentially how much the atmosphere is spinning at a given point, and meteorologists use it to identify where storm development is favored. To compute it you need wind observations from five grid points arranged in a cross pattern around your location, one center point and four cardinal neighbors. Weather reports give you wind as a speed and a direction ("southwest at 30 knots"), but the math needs those broken into east-west and north-south components (the u and v you might see in meteorological data). The center point gives you the observation at your location, but the actual computation uses the four cardinal points to measure how the wind field changes across the grid. That rate of change is the relative vorticity. Add Earth's own rotational contribution (the Coriolis parameter) and you get absolute vorticity, which is what forecasters actually look at on a 500mb chart.

I was pleasantly surprised by how little code the core computation needs.

dx, dy = grid_spacing(lat)

u_n, v_n = wind_components(*north_wind)
u_s, v_s = wind_components(*south_wind)
u_e, v_e = wind_components(*east_wind)
u_w, v_w = wind_components(*west_wind)

# centered finite differences: dv/dx - du/dy
dvdx = (v_e - v_w) / (2.0 * dx)
dudy = (u_n - u_s) / (2.0 * dy)

relative = dvdx - dudy
absolute = relative + coriolis_parameter(lat)

The wind_components() helper decomposes speed and direction into u/v, and grid_spacing() adjusts for latitude (a degree of longitude is shorter near the poles). The whole module is under 75 lines with no external dependencies, but getting it to produce meteorologically sensible values took some fun comparison against professional analyses, and one frustrated rewrite. It's still not perfect, always trust your friendly neighborhood meteorologist more, but it hasn't been flat wrong in a while.

Personal weather station integration

NWS observations come from airports and official stations, which can be miles from where you actually are. This part is optional, but it's the feature I use most. If you have a WeatherFlow Tempest weather station (because of course you happened to have one on your roof), you can configure StormScope to enrich NWS data with hyper-local sensor readings. Solar radiation, UV index, lightning strike counts, air density, wet bulb temperature, data and more data galore. The Tempest station becomes the primary source for temperature, wind, and pressure, with the NWS values retained as sidecars for comparison. There's a 5-mile distance gate on the station for precision, though, so if you ask about weather in a city 200 miles away, StormScope uses NWS data alone.

When the Tempest and NWS temperatures diverge by more than 5 degrees Fahrenheit, it flags the discrepancy so the AI knows something might be off with the sensor or the NWS observation station is farther away than you'd like.

What this enables

Here's what using it actually feels like. I asked "what's the weather?" a few minutes ago and got back a summary that pulled from my Tempest station (40°F with gusts to 30, not too bad for April up here), blended in the NWS forecast (mostly cloudy tonight, chance of rain tomorrow), noted no active alerts, and mentioned that the SPC had a general thunderstorm risk over eastern Colorado. The whole thing took a couple of seconds and the answer was grounded in data from four different sources, none of which the AI made up. That's a simple case, and it's what I use most often. I run StormScope as an MCP server connected to Claude Code, so asking about the weather is as natural as asking about code.

Ask about severe weather risk and the AI will pull the probabilistic tornado, wind, and hail outlooks, cross-reference with the surface analysis to see if you're in the warm sector, check the 500mb pattern for shortwave energy, and synthesize all of that into a plain-English assessment of what the afternoon looks like. Four tool calls and a synthesis step, done in a few seconds, tech is magic.

Ask for a weather briefing before a road trip and the AI can check conditions and forecasts for both endpoints, look at alerts along the route, and flag anything worth knowing about the sky. Ask whether it's warm enough to finally open the windows and it can check temperature, humidity, and wind, then give you a straight answer instead of a disclaimer about not having real-time data.

One design decision that hasn't worked as well as I hoped was suggesting behavioral patterns to the AI. MCP servers can ship with an instruction block that the AI reads at connection time, and mine asks it to check for alerts at the start of a conversation and proactively fetch probabilistic outlooks when the SPC risk level is elevated. In practice the AI never follows through unprompted (MCP instructions are suggestions, not commands), but when it does check, it has some basis for prioritization, which is better than nothing.

The underlying bet with this project is that LLMs are already good at meteorological reasoning, they just lack current observations to reason over. StormScope is the plumbing that makes that possible.

Things that bit me

The NWS API has a two-step coordinate lookup that tripped me up early on. You can't just ask for the forecast at a lat/lon pair. First you call {`/points/{lat},{lon}`} to get the grid office, grid coordinates, and a URL for the nearest observation stations. Then you use those to fetch the actual forecast and observations. Not hard once you know, but I was surprised that I couldn't just pass coordinates and get an answer. Luckily the point metadata is stable enough to cache for 24 hours, so the extra round trip only hurts on the first request for a given location, which includes the server making multiple calls and the AI making subsequent tool calls, even if you only ask one weather question.

Before you can even call the NWS API, you need to know where the user is. The simplest approach is to require the AI to pass coordinates, but AI assistants don't usually know where you are unless you tell them. So StormScope has a fallback chain. First it checks for a configured primary location (environment variables). Then it can optionally pull coordinates from a connected Tempest station. After that, IP geolocation, which sounds reasonable until you try it. My IP address resolves to a location roughly 25 miles from where I actually am, and for mesoscale weather that's a huge difference. My solution here, though it only works on macOS, was to compile a tiny Swift app that calls CoreLocation directly. The server builds it automatically on first run, stashes it in ~/Library/Application Support/, and calls it as a subprocess. It requires location authorization (a macOS popup, but only the first time) and returns coordinates accurate to about a hundred meters. Because it needs compilation and touches system permissions, it's opt-in via an environment variable. But when it works, it's the most satisfying kind of hack, solving a problem by compiling a tool on the fly that has no business being inside a weather server.

I already mentioned vorticity, and I spent a while looking for a public API that returns it directly, but came up empty. Open-Meteo gives you 500mb wind speed and direction at individual grid points, which is the raw material you need, but the vorticity itself requires computing finite differences across a grid. I'd never written that kind of computation before, so I pulled out some faithful old meteorology tomes (jk, I used Wikipedia and a NOAA training module) and worked through it. But that's the kind of thing that makes a side project really fun.

The CODSUS surface bulletin parser was a different kind of fun. The bulletin is plaintext with encoded 7-digit coordinates, front type keywords, and pressure values, all strung together with minimal delimiters. The coordinate encoding is, well... different:

def _decode_coord(token: str) -> tuple[float, float]:
    lat = int(token[:3]) / 10.0
    lon = -(int(token[3:]) / 10.0)
    return lat, lon

First three digits are latitude times ten, last four are longitude times ten, always negated because the bulletin only covers North America. The Iowa Environmental Mesonet archives these bulletins, but their product ID metadata is unreliable. ASUS01 and ASUS02 labels get swapped frequently, so StormScope checks the actual WMO header text instead of trusting the label. Long front segments and pressure center lists wrap across continuation lines that need to be rejoined before parsing. The first version worked on most bulletins but produced phantom front segments between disconnected line segments in certain edge cases. Getting the parser robust enough to handle the full range of real-world bulletins took a few iterations, and I'm not convinced all the bugs are gone.

What it can't do

StormScope is focused on general-purpose weather for the contiguous US, and, frankly, focused on the upper Midwest, since that's where I call home. It doesn't cover marine forecasts, fire weather, aviation TAFs and METARs (beyond the raw METAR that shows up in full-detail conditions), or tropical cyclone advisories. It doesn't do historical data or climate norms. The SPC outlooks cover days 1 through 3 but nothing beyond that.

I'd like to add some historical data access, since the Tempest API provides it (and I log my data to a local DB too), plus maybe tropical cyclone support eventually, and aviation METARs/TAFs wouldn't be a huge lift. If any of those gaps bother you enough to contribute, the client architecture is modular and welcoming PRs is part of what I love about open source software.

Feed your AI fresh weather data

If you want to give your AI a dose of the sky, the GitHub repo has everything you need to get started, and leave a star while you're there. StormScope is open source under an ISC license. Fair warning, most of the tools are US-only because they depend on the NWS API (though the Tempest integration should work anywhere). Thanks for letting me take up a little of your brain power today!

Connecting consult-line with isearch history

2024-01-17T09:00:00-06:00

I've recently jumped on the not-so-new hotness of Consult, with its friends Vertico and Orderless, replacing the still strong but slightly slower Counsel, Ivy, Swiper and Flx. There's been a few bumps along the way to adapt these new packages to my own whims, but its all working out so far.

One such issue is that after using consult-line to search in a buffer, I'd often like to continue my search, preferring the evil-mode keys n and N (evil-search-next and evil-search-previous, respectively). Unfortunately, once consult-line is closed, it can't be resumed without starting it again anew, unlike the swiper behavior I've come to rely on.

Now I did come across a 2021 GitHub thread about this issue, but the chosen solution only works for evil-search as the search module. This is not the default and, though I'm sure many love it, I prefer the isearch way of highlighting. So, taking inspiration from that thread, I've made my own advice for consult-line which instead works by connecting consult's consult--line-history with the regexp-search-ring that isearch uses.

(defun consult-line-isearch-history (&rest _)
    "Add latest `consult-line' search pattern to the isearch history.

This allows n and N to continue the search after `consult-line' exits."
    (when (and (bound-and-true-p evil-mode)
               (eq evil-search-module 'isearch)
               consult--line-history)
      (let* ((pattern (car consult--line-history))
             (regexp (if (string-prefix-p "\\_" pattern)
                         (substring pattern 2)
                       pattern)))
        (add-to-history 'regexp-search-ring regexp)
        (setq evil-ex-search-pattern (evil-ex-pattern regexp t nil nil))
        (setq evil-ex-search-direction 'forward))))

;; Now tell consult-line to run the function after a search
(advice-add #'consult-line :after #'consult-line-isearch-history)

Fix Steam 'Corrupt Update Files'

2020-10-12T09:00:00-06:00

Occasionally, though I don't know or understand the cause, Steam fails to install and/or update some games and reports the error "Corrupt update files". No matter how many times you try to reinstall, the same error occurs. There are scant resources I've found searching for this problem, but it happens to me just often enough I'd like this post as a reminder for myself.

Steps to fix

Uninstall the affected game
Clear the Download Cache (In Steam settings > Downloads). Skipping this step may let the game claim to have downloaded successfully, but when the files are verified, it will likely find corrupt files again.
Remove lingering game files: Clear any previous files from the game; look for the game title under steamapps/common (in Linux this can be found in ~/.steam/steam/steamapps/common)
Change download region: Change the download region to something else, probably still something nearby to keep speeds as high as possible. For example, my default is "US - New York", so I usually change it to something like "US - Philadelphia" or anywhere else nearby
Restart Steam when prompted
Reinstall the game
- If you do, go back to step 1 and use a different region. If it still doesn't work a second time, these steps may not be valid for your problem, or this guide is now outdated.
Verify game files integrity (In the game's 'Properties' > 'Local Files')

Your AI Is Not Your Co-Author

2026-02-19T09:00:00-06:00

Some AI coding agents have started adding themselves as Co-Authored-By on git commits by default. They sign commits as though they were a contributing developer. I think this gets something fundamentally wrong about what commit authorship means. As someone who has started leaning on AI tools heavily in my own work, I find it matters to me that the line of accountability stays clear.

The question of who is responsible for AI's output is not actually new or complicated. AI is a tool. It is a technically impressive tool, different in important ways from a calculator or a linter, but it is still a tool. It does not comprehend what it produces. It has no free will and no moral capacity to answer for its actions. When a financial analysis tool causes a bad trade, we might want to blame the software, but we hold the person who used it accountable, and to some extent the people who built it. The same structure applies to AI. Ethical responsibility for what a tool produces belongs to the human who chose to use it and the humans who made it.

Commit authorship in git carries that same weight. It's your signature as an engineer. When your name is on a commit, you're the person accountable when it breaks production, the person who decided this change was correct and necessary. So when an AI agent adds itself as co-author, it is claiming a moral responsibility it cannot hold. The human who prompted the AI, reviewed its output, and chose to commit it is the one who exercised that judgment. The AI was a tool in that process, the same way a compiler or a linter or Stack Overflow is a tool. We don't add Co-Authored-By: GCC to commits that required tricky compiler flags (and we don't credit the IDE's autocomplete either). The relevant question is not "who typed these characters" but "who is responsible for them."

This is an argument about the AI systems we have today, which are software tools without moral agency. If that changes someday, the ethics change with it. But the current generation of language models does not understand, intend, or accept consequences. Until one can, authorship belongs to the humans.

There is a reasonable counterargument about transparency. Maybe tracking AI involvement helps teams understand how code was produced. But Co-Authored-By is the wrong mechanism for it. If your team wants to track AI usage, build that into your process explicitly. A commit message note, a PR label, whatever fits (we use PR labels at DroneDeploy). An authorship field with professional meaning isn't the right place for it. The more interesting question for code review is not "did AI help write this" but "did a human verify this is correct." The answer to that should always be yes, regardless of how the code was literally produced.

If you use Claude Code, you can disable the default co-author behavior by adding "includeCoAuthoredBy": false to your Claude settings.

Halfway on Main: Thoughts on Clean Architecture

2021-04-18T09:00:00-06:00

Chapter 26 is a short section of Uncle Bob Martin's classic, Clean Architecture. It discusses the necessary evil of creating a Main component which handles the dirty work and initializes the rest of the program. This component necessarily breaks rules to get the show running and provide an interface with the non-clean world which is our reality. The Main component takes care of setting up globals and may enter the program into an infinite loop to keep it running forever.

Uncle Bob gives a lengthy yet incomplete example of a Main class component for a hypothetical game of "Hunt the Wumpus". The game is a text-based somewhat-roguelite dungeon-crawler in which you seek out the Wumpus and avoid traps. A simple game concept, well within the wheelhouse of a first-year computer science student, and Uncle Bob's code looks the part. For an otherwise insightful book about how to separate concerns, Martin seems to give up when it comes to this component, relegating it to be "the dirtiest of all the dirty components" without any effort to find a better way. The example class he presents is needlessly brittle and repetitive.

Here is that entire Main class, as presented in the book. Note that the book contains the comment at the end (much code removed...), it wasn't added here.

public class Main implements HtwMessageReceiver {
  private static HuntTheWumpus game;
  private static int hitPoints = 10;
  private static final List<String> caverns = new ArrayList<>();
  private static final String[] environments = new String[]{
    "bright",
    "humid",
    "dry",
    "creepy",
    "ugly",
    "foggy",
    "hot",
    "cold",
    "drafty",
    "dreadful"
  };

  private static final String[] shapes = new String[] {
    "round",
    "square",
    "oval",
    "irregular",
    "long",
    "craggy",
    "rough",
    "tall",
    "narrow"
  };

  private static final String[] cavernTypes = new String[] {
    "cavern",
    "room",
    "chamber",
    "catacomb",
    "crevasse",
    "cell",
    "tunnel",
    "passageway",
    "hall",
    "expanse"
  };

  private static final String[] adornments = new String[] {
    "smelling of sulfur",
    "with engravings on the walls",
    "with a bumpy floor",
    "",
    "littered with garbage",
    "spattered with guano",
    "with piles of Wumpus droppings",
    "with bones scattered around",
    "with a corpse on the floor",
    "that seems to vibrate",
    "that feels stuffy",
    "that fills you with dread"
  };

  public static void main(String[] args) throws IOException {
    game = HtwFactory.makeGame("htw.game.HuntTheWumpusFacade", new Main());
    createMap();
    BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
    game.makeRestCommand().execute();
    while (true) {
      System.out.println(game.getPlayerCavern());
      System.out.println("Health: " + hitPoints + " arrows: " + game.getQuiver());
      HuntTheWumpus.Command c = game.makeRestCommand();
      System.out.println(">");
      String command = br.readLine();
      if (command.equalsIgnoreCase("e"))
        c = game.makeMoveCommand(EAST);
      else if (command.equalsIgnoreCase("w"))
        c = game.makeMoveCommand(WEST);
      else if (command.equalsIgnoreCase("n"))
        c = game.makeMoveCommand(NORTH);
      else if (command.equalsIgnoreCase("s"))
        c = game.makeMoveCommand(SOUTH);
      else if (command.equalsIgnoreCase("r"))
        c = game.makeRestCommand();
      else if (command.equalsIgnoreCase("sw"))
        c = game.makeShootCommand(WEST);
      else if (command.equalsIgnoreCase("se"))
        c = game.makeShootCommand(EAST);
      else if (command.equalsIgnoreCase("sn"))
        c = game.makeShootCommand(NORTH);
      else if (command.equalsIgnoreCase("ss"))
        c = game.makeShootCommand(SOUTH);
      else if (command.equalsIgnoreCase("q"))
        return;
      c.execute();
    }
  }

  private static void createMap() {
    int nCaverns = (int) (Math.random() * 30.0 + 10.0);
    while (nCaverns-- > 0)
      caverns.add(makeName());

    for (String cavern : caverns) {
      maybeConnectCavern(cavern, NORTH);
      maybeConnectCavern(cavern, SOUTH);
      maybeConnectCavern(cavern, EAST);
      maybeConnectCavern(cavern, WEST);
    }

    String playerCavern = anyCavern();
    game.setPlayerCavern(playerCavern);
    game.setWumpusCavern(anyOther(playerCavern));
    game.addBatCavern(anyOther(playerCavern));
    game.addBatCavern(anyOther(playerCavern));
    game.addBatCavern(anyOther(playerCavern));
    game.addPitCavern(anyOther(playerCavern));
    game.addPitCavern(anyOther(playerCavern));
    game.addPitCavern(anyOther(playerCavern));
    game.setQuiver(5);
  }

  // much code removed...
}

User command parsing

Let's start with the low-hanging fruit: repetitive statements. The main method contains the primary game loop, which runs forever until the user enters "q". Most of this is fine, but the long block of else if's are not only difficult to read, they're needlessly inefficient. We must test input against every statement in sequence until one turns up true or there are no statements left to test. Further, if the user enters a command which matches none of the conditions (necessitating a complete run-through of them all), the game executes a "rest" command, declared outside the set of conditions, which could easily come back to bite an unsuspecting developer in the future.

Whenever there is a set of three or more distinct conditions to test, it's almost always a better bet to use a switch, case or best of all (if the language supports it), pattern matching. The game loop cleans up a bit if we use this advice. We can also take advantage of the fact that when comparing strings, the switch statement acts as if we're calling the String.equals method, so as long as we convert the command to lower case, it'll act identically to calling String.equalsIgnoreCase repeatedly.

while (true) {
  System.out.println(game.getPlayerCavern());
  System.out.println("Health: " + hitPoints + " arrows: " + game.getQuiver());
  System.out.println(">");

  String command = br.readLine();
  HuntTheWumpus.Command c;
  switch (command.toLowerCase()) {
    case "e": c = game.makeMoveCommand(EAST);
      break;
    case "w": c = game.makeMoveCommand(WEST);
      break;
    case "n": c = game.makeMoveCommand(NORTH);
      break;
    case "s": c = game.makeMoveCommand(SOUTH);
      break;
    case "se": c = game.makeShootCommand(EAST);
      break;
    case "sw": c = game.makeShootCommand(WEST);
      break;
    case "sn": c = game.makeShootCommand(NORTH);
      break;
    case "ss": c = game.makeShootCommand(SOUTH);
      break;
    case "q": return;
    default: c = game.makeRestCommand();
  }
  c.execute();
}

These conditions are now, in my opinion, more readable, and operate in O(1) time. Additionally, the command parsing is visually separated from the user output (which is a sort of UI).

Rather than making the command matches here, the architecture would benefit even more from taking Martin's advice from his own book, and moving the UI elements to their own component. If we wish to implement a more complex UI in the future, even a GUI, only the dedicated component will need to change considerably. In the shorter-term, perhaps we'll want to add an explicit "i" command which prints this out. It would be nice to separate this concern from the "dirty" Main component.

The main game loop could still live in a clean main method, but we should restrict it to only getting the command and executing it. This leaves the looping action at this, the lowest "dirtiest" level, while abstracting away the complications of interpreting user input. Here's how well we clean it up by separating the concerns via abstraction:

while (true) {
  GameUI.displayUserStatus();
  HuntTheWumpus.Command c = GameUI.getUserCommand();
  c.execute();
}

Map generation

The createMap method may indeed be at home in the Main class, but surely we can clean it up. Uncle Bob leaves needless repetition in the same method where he used a loop to avoid it.

First, let's look at the cavern connection block, which uses some not-printed method to dynamically generate connections between caverns. This isn't so bad, but a nested loop could abstract it a little better, especially if we wanted to change the cavern geometry in the future (I'm thinking hexagons, which are the bestagons). We'll make the further improvement of moving our directions into an enum, which we'll simply call Direction.

for (String cavern : caverns) {
  for (Direction direction : Direction.values()) {
    maybeConnectCavern(cavern, direction);
  }
}

Next, we have a block which spawns the characters, some bats and some pits into presumably random unique caverns. Placing the player and the Wumpus are single statements and probably always will be, but we don't need to repeat ourselves thrice for bats and pits each. Let's also rename the anyOther method to anyOtherCavern to reduce ambiguity.

Along with populating caverns, our map generation block gives the player a quiver of arrows? This has nothing to do with creating the map! Let's move that to a method called createPlayer, which we'll relegate to the "much code removed..." section.

String playerCavern = anyCavern();
game.setPlayerCavern(playerCavern);
game.setWumpusCavern(anyOther(playerCavern));
IntStream.range(0, 3).forEach(() -> game.addBatCavern(anyOtherCavern(playerCavern)));
IntStream.range(0, 3).forEach(() -> game.addPitCavern(anyOtherCavern(playerCavern)));

Using IntStream.range is about the closest we can get to a proper range loop like Python's for x in range(i, j), and I much prefer it to for loops.

Why did I leave the bat and pit cavern population loops separated? Because they're not inherently linked, and we may reasonably wish to change the frequency of one without changing the other.

Hard-coded values

When an application hard-codes values as severely as this example, it's hard to avoid cringing at the looming technical debt. The severity we see here would be perfectly acceptable in an early computer science course, but a real-world system would struggle to keep up with changing requirements. A simple typo in a string, an additional witty cavern description or the substitution of localized languages should not require code changes.

Similarly, values such as the initial player HP, the number of arrows in the player's quiver, the seed for the randomly generated number of caverns, and the number of bat and pit caverns, all should be configurable with ease. Perhaps we wish to introduce difficulty levels which change the balance of these values. Perhaps we find we've given the player too much HP for a fair fight. We'll undoubtedly need to balance these values, and so we'll be better off storing them in an configurable but immutable data structure.

As detailed in previous chapters of Clean Architecture, the data structure to house these values shouldn't matter to our Main component. They could reside in a key-value store, a database of any kind, a CSV or TSV, or even a well formatted plain text file. As far as this component knows, they're all just an interface. For our purposes we'll call the interface GameConfiguration, which is responsible for loading and providing the configured values.

Putting all our changes together with the interface-provided configuration, we arrive at a much cleaner architecture than Uncle Bob presents.

public class Main implements HtwMessageReceiver {
  private static HuntTheWumpus game;
  private static final List<String> caverns = new ArrayList<>();

  private static int hitPoints;
  private static int quiver;
  private static String[] environments, shapes, cavernTypes, adornments;

  public static void main(String[] args) throws IOException {
    environments = GameConfiguration.get("environments");
    shapes = GameConfiguration.get("shapes");
    cavernTypes = GameConfiguration.get("cavernTypes");
    adornments = GameConfiguration.get("adornments");
    hitPoints = GameConfiguration.get("hitPoints");
    quiver = GameConfiguration.get("quiver");

    game = HtwFactory.makeGame("htw.game.HuntTheWumpusFacade", new Main());
    createMap();
    createPlayer();
    BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
    game.makeRestCommand().execute();

    while (true) {
      GameUI.displayUserStatus();
      HuntTheWumpus.Command c = GameUI.getUserCommand();
      c.execute();
    }
  }

  private static void createMap() {
    int nCaverns = (int) (Math.random()
                          * GameConfiguration.get("cavernSeed")
                          + GameConfiguration.get("cavernMinimum"));
    while (nCaverns-- > 0)
      caverns.add(makeName());

    for (String cavern : caverns) {
      for (Direction direction : Direction.values()) {
        maybeConnectCavern(cavern, direction);
      }
    }

    String playerCavern = anyCavern();
    game.setPlayerCavern(playerCavern);
    game.setWumpusCavern(anyOther(playerCavern));
    IntStream.range(0, GameConfiguration.get("batCaverns"))
      .forEach(() -> game.addBatCavern(anyOtherCavern(playerCavern)));
    IntStream.range(0, GameConfiguration.get("pitCaverns"))
      .forEach(() -> game.addPitCavern(anyOtherCavern(playerCavern)));
  }

  // much code removed...
}

The resulting code is more terse, hardy and generally cleaner. Is some of this overkill for a small pet or student project? It probably is, but Uncle Bob presents this as a contrived but real-world example in a printed book about code design, and should have taken the time to apply his own principles to his examples.

Coding a website from scratch - a timelapse

2016-12-14T09:00:00-06:00

Jade creates a simple website from scratch using the Bootstrap framework

Switch Caps Lock and Escape (Linux)

2016-03-28T09:00:00-06:00

The standard QWERTY keyboard is great in a lot of ways and for a lot of uses. My current keyboard has been with me for years and I know it well, but if I could change the locations of a couple keys, I would. And naturally, that's what I did.

The most useful change I've made is switching the Caps Lock and Escape keys. This is much easier (after the initial muscle-memory retraining) because of how often I use Escape while programming. Instead of a reach up to the edge of the keyboard, it's only one key to the left of my pinky finger on home row. So how do you do it? It's pleasantly simple:

First, add the folowing code to your ~/.Xmodmap (note the capital X):

clear Lock
keysym Caps_Lock = Escape
keysym Escape = Caps_Lock
add Lock = Caps_Lock

Next, add the following line to your ~/.zshrc (or ~/.profile if you're using bash):

xmodmap ~/.Xmodmap

There you go! source ~/.zshrc (or logout and login again for bash) and they should switch!

A Known SSH Socket for Tmux

2020-05-03T09:00:00-06:00

Artisanal SSH socket remapping

At FlightAware, my work is spread over multiple packages on multiple remote servers, all accessed by SSH. I'll often chain SSH connections together, sometimes more than four connections deep. Plus I often push and pull git-controlled code to yet more remote servers.

To keep track of everything, I do 100% of my work within tmux. To let me chain my SSH connections, nearly every connection uses ForwardAgent. Unfortunately, this doesn't work for long. When I reconnect to a server and reattach my tmux session, I am suddenly unable to chain my connections!

The problem here is that my SSH Agent has created a new socket for my new connection. This works fine by itself, but when I reattach the already existing tmux session, I no longer have any reference to the new socket. Inside of tmux, SSH will try to use the socket in use at the time the session was created, which probably no longer exists.

So what to do? The obvious solution is to simply close my tmux session when I disconnect and create a new one with every new connection. But this has problems.

First, what if I accidentally disconnect? Maybe I've lost my network connection, or somehow accidentally hit ~.. I want to get back into my session as quickly and easily as possible.
Second, what if I want to save my panes when I disconnect? Maybe there's some long-running process I want to keep. Or maybe I simply don't want to have to recreate my session every time I connect (though some of this can be solved by a project like tmuxinator).

Obviously, a better solution would be to just fix the problem and get tmux to always use the current socket. Additionally, I want to be sure to support using tmux within SSH within tmux, chained arbitrarily. The answer is to always put the socket in a known location and hook everything up to use it.

Rather than try to devise some solution to signal to tmux what the current socket file is, it will be much easier to use a symbolic link. Whenever we create a new socket, we'll simply override the existing link with a link to the new socket.

We need a name for this symbolic socket, so how about /tmp/ssh-agent-$USER-screen. We're putting it in /tmp/ since it doesn't matter too much if this is overwritten or cleaned up. We're also using the USER environment variable to keep sockets separate for different users. At the end, I'm putting -screen since this is sort-of more general than -tmux, but it can really be whatever, or even removed.

Now, creating a symbolic link is all fine and good, but what do we actually link to? Unfortunately there's no great built-in way to grab the current socket all the time. But there's no need to re-invent the wheel, we can use the proven ssh-find-agent tool. So let's put that in a useful location:

git clone git@github.com:wwalker/ssh-find-agent.git ~/lib/ssh-find-agent

We'll use the "automatic" -a option, which will find the active SSH agent and store it in SSH_AUTH_SOCK for us. But, if there is no active SSH session, nothing useful will happen, so we'll want to get the SSH agent started.

# Source the script first
. ~/lib/ssh-find-agent/ssh-find-agent.sh
ssh_find_agent -a

# If nothing happened, we need to start up the ssh-agent
if [ -z "$SSH_AUTH_SOCK" ]
then
  eval $(ssh-agent) > /dev/null
  ssh-add -l >/dev/null || alias ssh='ssh-add -l >/dev/null || ssh-add && unalias ssh; ssh'
fi

Now that we have the socket, we just need to make (or override) that symbolic link so it can be found later.

SOCK="/tmp/ssh-agent-$USER-screen"
if test $SSH_AUTH_SOCK && [ $SSH_AUTH_SOCK != $SOCK ]
then
  rm -f /tmp/ssh-agent-$USER-screen
  ln -sf $SSH_AUTH_SOCK $SOCK
  export SSH_AUTH_SOCK=$SOCK
fi

Putting it all together, we'll find the active socket or create it, then make a known symblic link. Now we just have to do this everywhere the socket is needed. This is the most annoying part, though it can be relieved with a tool like sshrc. The full process will need to be added to the ~/.bashrc or ~/.zshrc on your host system, as well as every system you want to chain tmux and SSH sessions from.

To be clear about where this needs to happen, if your chain looks like this:

host → tmux → (remote 1) → tmux → (remote 2) → tmux → (remote 3)
            ⤓
              (remote 4) → tmux → (remote 5)

Then you would need to have this set-up on host, (remote 1), (remote 2) and (remote 4), but not the last two remotes. If you think of these chain connections as a tree, the socket mapping is not needed on the leaves. Technically it's also not needed on any nodes on which you're not using tmux, provided you use ForwardAgent.

So there we have it, the SSH socket symbolically linked to a known location. After cloning ssh-find-agent, here's the complete script to add to your shell login script as required:

# Known SSH Socket for tmux
# https://jmthornton.net/blog/p/tmux-known-socket

. ~/lib/ssh-find-agent/ssh-find-agent.sh
ssh_find_agent -a
if [ -z "$SSH_AUTH_SOCK" ]
then
  eval $(ssh-agent) > /dev/null
  ssh-add -l >/dev/null || alias ssh='ssh-add -l >/dev/null || ssh-add && unalias ssh; ssh'
fi

# Predictable SSH authentication socket location so tmux can find it
SOCK="/tmp/ssh-agent-$USER-screen"
if test $SSH_AUTH_SOCK && [ $SSH_AUTH_SOCK != $SOCK ]
then
  rm -f /tmp/ssh-agent-$USER-screen
  ln -sf $SSH_AUTH_SOCK $SOCK
  export SSH_AUTH_SOCK=$SOCK
fi

Vero: A Simple Zsh Theme

2017-02-09T09:00:00-06:00

I'm excited to announce the release of Vero, a simple and informative theme for Zsh. After using various themes over the years, I decided to create one that focuses on providing essential information without clutter.

Features

Vero includes all the information I need in my daily terminal work:

Current versions for nvm and pyenv
Git branch and status
Timestamp
SSH indication
Current user
Current working directory

Preview

As you can see, Vero provides a clean, informative prompt that shows everything you need to know about your current environment. The theme is designed to be fast and lightweight while remaining highly functional.

Installation

Vero is available on GitHub and can be installed using ZPico:

zpico add thornjad/vero source:gitlab

The theme is released under a permissive license, so feel free to use, modify, and distribute it as needed. I hope you find it as useful as I do!

Data Paradigms in TCL: Associative Arrays vs Dictionaries

2020-08-10T09:00:00-06:00

Working with TCL for a while, you have to come to terms with the fact that arrays and dicts aren't just different APIs. They're fundamentally different beasts under the hood.

The Implementation Reality

Associative arrays are TCL's original key-value store, implemented as hash tables directly in the interpreter. When you write set arr(key) value, you're actually creating a variable with a compound name. The interpreter maintains a separate hash table for each array variable, and accessing $arr(key) triggers a hash lookup on that specific table.

Dictionaries came later (TCL 8.5 in 2007) as first-class values. Unlike arrays, a dict is just a string with a specific internal representation: a list of alternating keys and values that gets cached as a hash table when you perform dict operations on it. The key insight is that dicts are values that can be passed around, while arrays are variables that live in specific scopes.

Why This Matters in Practice

Arrays tie you to variable scopes. You can't return an array from a procedure without using upvar or global to work around the limitation. Arrays also can't be nested without ugly naming tricks like set arr(outer,inner) value.

# Arrays: scope-bound and flat
proc make_config {} {
    # Can't return this directly
    set config(host) "localhost"
    set config(port) 8080
}

# Dicts: values you can actually use
proc make_config {} {
    return [dict create host localhost port 8080]
}

Dicts shine for structured data and functional-style programming. Need nested data? dict set config database host localhost just works. Want to pass complex data between procedures? Dicts are your friend.

Performance Quirks

Here's the counterintuitive part: arrays can be faster for simple key-value operations because there's no string parsing overhead (everything is a string, except when it's not). But dicts win for complex operations because they can optimize their internal representation and handle nesting efficiently.

Arrays also support pattern matching with array names pattern, which dicts can't match without iteration.

When to Use What

Use arrays for:

Simple key-value stores that stay in one scope
When you need pattern matching on keys
Legacy code that expects array semantics

Use dicts for:

Structured, nested data
Passing data between procedures
Modern TCL code that values composability

The real lesson? TCL's "everything is a string" philosophy is surface-level, and it means these data structures evolved different internal optimizations while maintaining the same string-based interface. At FlightAware, we've learned this the hard way. Legacy code is full of arrays that should have been dicts, and newer code sometimes uses dicts where arrays would be simpler. Understanding the implementation helps you pick the right tool and avoid performance traps.

Walden and Bdote: Land, Protest, and the Forgotten Cost of American Freedom

2025-05-11T09:00:00-06:00

In June of 1861, a steamboat³ carrying Minnesota's governor, political dignitaries and a group of white observers drew up at the Redwood Agency for what would become the last peaceful treaty payment to the Dakota people⁴ before betrayal, starvation, and violence made such ceremonies impossible.^{5 7 8} Among those present was Henry David Thoreau, the New England naturalist, whose brief visit made him an accidental witness to rising Dakota desperation. Listening amid a crowd more interested in official rituals than in Dakota grievances, Thoreau noted quietly in a letter, "The most prominent chief was named Little Crow. They were quite dissatisfied with the white man's treatment of them & probably have reason to be so."^{5 7 9} That mundane remark anticipated the eruption of war and exile that would engulf Little Crow's world only a year later. Their paths crossed by chance at a fulcrum of Minnesotan and American history, each emblematic in vastly different ways, of resistance to injustice and the meaning of relationship to land.¹⁰

The coincidence of Thoreau's brief encounter with the Dakota underscores the depth of the divide between their worlds. For Thoreau, Walden Pond represented a sanctuary for moral renewal and principled dissent; he became both model and myth, celebrated as America's first great interpreter of nature and a paragon of individual conscience.^{11 13} However, the legend of solitary resistance often masks how Thoreau's insight was limited by mid-19th-century New England's assumptions about property and the hierarchy between settlers and Native peoples. Beneath his critique of progress, Thoreau operated within a society deeply invested in land as commodity and shaped by settler colonial beliefs, which constrained the possibilities of his vision even as he resisted its mainstream currents. For the Dakota, by contrast, land was neither backdrop nor resource, but a living relative, the foundation of kinship and language.^{10 14} Their center was Bdote,¹⁵ the confluence of rivers where, as creation stories recount, the Dakota people emerged from earth and water and began a relationship of mutual care and obligation.¹⁴ The United States did not see land this way. As expansion accelerated, the nation demanded cessions, negotiated and broke treaties, and enforced a language of ownership foreign to Dakota understanding, until patience gave way to the desperate calculus of survival.

America's story has depended on the systematic elimination of Native presence, physically and symbolically, a process by which the dominant settler society secures itself through the construction of the "other" who can be dispossessed.^{17 18} Dakota presence and removal functions as the setting of American origins—a setting that must not speak for itself but serves as the shadow on which national self-creation rests. Thoreau's dissent is canonized as a noble conscience, while the Dakota resistance is written out of national memory. A close study of Thoreau's tradition and that of the Dakota reveals sharply different relationships to land, contrasting forms of protest, and profoundly unequal consequences for resistance. Dakota resistance to unjust government in 1862 should be recognized as legitimate resistance, standing alongside Thoreau's celebrated acts of civil disobedience. The ongoing exclusion of the Dakota from the national canon reveals a contradiction at the heart of the United States: a nation born in rebellion, it upholds ideals of liberty for some by displacing and silencing others. Reckoning with Dakota resistance and its consequences is essential to confront how the American promise of liberty has depended on the denial of justice to those it casts outside its boundaries.

Land and Meaning

The Dakota, who gave Mni Sota Makoċe its name—"land where the waters reflect the skies"—live in a world where land, origin, kinship, and spirit are inseparable.^{14 19} Their understanding of land begins at Bdote, the confluence of the Minnesota and Mississippi rivers,²⁰ from which traditions say the Dakota people first arrived, formed from the clay at Maka Ċokaya Kiŋ, the Center of the Earth.^{14 16 19} Here, stories and obligations to the land are passed through language, ceremony, and place-names that mark ancient belonging and ongoing return, even in exile. Identity is rooted in caring for land as a living relation; the Dakota word for "mother" and "earth" are the same, "Ina."¹⁹ This equivalence is no metaphor, Dakota identity is rooted in caring for land and returning—even after exile.^{14 19 21}

1844 Watercolor of Fort Snelling above Bdote, by John Caspar Wild (Wikimedia Commons)

For the Dakota, land is not a commodity but a relative—an ongoing being, woven into story, subsistence, and belonging. The attempt by the United States to extract "cessions," to convert place into property sold to the exclusion of all but the owner, was both a legal strategy and a form of cultural violence. Treaties deliberately reframed the relationship to land using the language of ownership and exclusive title in order to justify dispossession. This was facilitated by translation choices: missionary Stephen Riggs, responsible for the Dakota-language versions of two pivotal 1851 treaties, selected words that purposely obscured the American legal meanings of "to cede," "to sell," or "to relinquish."²² His Dakota translations substituted words meaning "to give up" or "to throw away," concepts which do not make sense when applied to Ina Maka, Mother Earth, making it impossible for Dakota signers to grasp the full legal consequences.¹⁹ Cheyfitz observes, "In traditional Native American cultures there are persons, but no 'individuals.'… there, traditionally, is no notion of property. For the idea of property depends on the possibility of an individual relation to the land."¹⁸ This fundamental difference gave the U.S. legal system the advantage, using mutually unintelligible language and intention to unravel Dakota kinship, history, and hope, and making dispossession not just a matter of force but of deliberate misunderstanding written into law.

Thoreau's relationship with land emerges out of a different heritage, though it is marked by its own deep yearning and critique of his culture's trajectory. Troubled by a society in which "men have become the tools of their tools," he sought refuge at Walden to discover a truer, more vital existence.¹ His famous retreat was not an escape into wilderness but an effort to "live deliberately, to front only the essential facts of life," and to let the land teach him what civilization obscures.^{1 13} Walden Pond, for Thoreau, was "earth's eye, looking into which the beholder measures the depth of his own nature."¹ In passages that border on reverence, Thoreau imagines the pond as a living interlocutor, a mirror for self-examination, and a source of moral renewal and insight.

View of Thoreau's Walden Pond, 2018, photo by Ashok Boghani (CC BY-NC 2.0)

Thoreau's experiment rested on daily acts of tending and listening to the land. The chapters "The Ponds" and "Solitude" unfold as meditations on how land shapes mood, vision, even ethical possibilities. Seasons, dirt, and water do not merely support life—they instruct and humble their visitor. Buell observes that Thoreau's project becomes "one of fitful, irregular, experimental, although increasingly purposeful, self-education in reading landscape and pondering the significance of what he found there."¹¹ The land's power is further acknowledged in Thoreau's restless awareness of loss: he mourns clear-cut forests and industrial progress as an abstract evil, and a specific diminishment of nature's capacity to nurture the spirit.

If Thoreau's retreat is a protest against his nation's increasing alienation from land, it is also a meditation on the contradictions of his role as a white settler. He pursues kinship with place through experiment and labor, but his belonging remains partial and chosen, a project one may freely attempt or put aside. Unlike the Dakota, for whom loss of land is a wound at the root of being, Thoreau's losses are encountered and mourned, but never cut to the core of the sense of self or community. His vision of harmony with land is shaped by his 19th-century New England assumptions about property and autonomy, even as he seeks to outgrow them. Sayre observes that while Thoreau "sometimes claims kinship with the land, his writing is an ongoing quest to approach land on its own terms," marked by aspiration and limitation.²³

The Dakota and Thoreauvian ways of being with land thus reveal two radically different ontologies—the first grounded in continuity, kinship, and mutual obligation; the second experimental, reflective, and forever reaching for a belonging it can envision but cannot fully enact. Their fleeting meeting at the Redwood Agency and the divergence of their fates a year later expose the cost when those with the power to define property limit who is allowed to belong and whose losses are remembered.

Desperate State of Mind

Dakota resistance followed years of deprivation and forced endurance. Patience was deep-rooted; for generations, Dakota moved with the seasons, caring for land and kin. Treaties and reservations ended this, confining families to reserved land, and dependence grew as a result. The 1851 treaties of Mendota²⁴ and Traverse des Sioux tied survival to annuity payments, which were often late or siphoned by traders. Big Eagle later recounted, "The Indians bought goods of [the traders] on credit, and when the government payments came the traders were on hand with their books, which showed that the Indians owed so much and so much, and as the Indians kept no books, they could not deny their accounts, but had to pay them, and sometimes the traders got all their money."²

By the summer of 1862, Dakota patience was stretched thin. A failed harvest, an unusually harsh winter, and the absence of meaningful government support left many weakened by hunger. Still, following the rhythms imposed by outsiders, the bands gathered in hope around the agency each year. When rumors that the payment, already weeks late,²⁵ might not arrive at all, traders closed their doors while families had nothing to eat. Sarah Wakefield, a white witness at the Upper Sioux Agency, saw that "these poor creatures subsisted on a tall grass which they find in the marshes, chewing the roots, and eating the wild turnip... I know that many died from starvation or disease... It made my heart ache."²⁶ Good Fifth Son would later recall, "a starving condition and desperate state of mind."²

Debate turned bitter in councils and the soldiers' lodge, historically a group of hunters, increasingly called for violent action. Years of delegations, attempted adaptation, and patience had only resulted in humiliation and hunger. The 1862 crisis was the result of broken promises. "Every one of the treaty negotiations... between Dakota people and the United States government were immoral and fraught with corruption," Waziyatawin writes, "but in the end, even the ridiculous terms of the treaties were moot because the government violated every one."¹⁴

Forms of Resistance

Recognition shapes protest. Thoreau's testimony and refusal were legible to the nation; the Dakota protest, however lawful, was ignored. Effective resistance required a form that the dominant society would recognize. Thoreau's 'Civil Disobedience' offered a refusal easily identified as moral. Thoreau, questioning state complicity in slavery and war, writes, "We should be men first, and subjects afterward... The only obligation which I have a right to assume is to do at any time what I think right."¹ Later dissenters, including Gandhi and King, read from Thoreau's script to transform the public conscience.^{27 28 29} Their protests worked precisely because the nation (however reluctantly) could reflect and, sometimes, revise itself.

The Dakota protested first through diplomacy and speeches,^{2 14 19} but these recognizable forms could not be "heard" as legally meaningful. As Cheyfitz notes, this was by design: "There was also a great oral tradition among many tribes concerning the provisions of the treaties and their meaning. … Courts had declared that this oral tradition could not be used by Indians in cases that involved treaties, and that only the writings and minutes taken by the government secretaries and officers would qualify, since they were considered 'disinterested parties.'"¹⁸ The boundary between celebrated and suppressed protest in American memory is marked by the nation's willingness to label certain acts as "civil" and thus worthy of recognition. As Erickson and others have shown, this distinction is not neutral: "civil disobedience" is often defined to exclude actions by marginalized groups whose grievances exceed what the dominant society is prepared to see or address.²⁸ The concept of "civility," then, functions as a gatekeeping tool, policing the forms of protest granted legitimacy and relegating all others to silence or infamy. This selective embrace of dissent reveals not universal principles, but a defensive logic protecting the status quo of property and order; it ensures that only those challenges compatible with national self-image are ultimately remembered as American.

Some among the Dakota pressed forward in an attempt to survive, adopting farming, building houses, and cultivating land. But this "sensible course," as Big Eagle called it, only earned them the resentment of other bands and the derision of government officers.^{2 19} "The whites were always trying to make the Indians give up their life and live like white men—go to farming, work hard and do as they did—and the Indians did not know how to do that, and did not want to anyway," Big Eagle explained.²

Denial of recognition shaped the war's tragic ignition. In August 1862, following years of deprivation, an argument among four young Dakota men about stealing eggs escalated to the murder of five settlers in Acton, Minnesota.^{2 8 30} Though this act was indefensible, those responsible knew it would doom their people: state violence would make no distinction between guilty individuals and the fate of an entire people. Big Eagle recalled, "It began to be whispered about that now would be a good time to go to war with the whites and get back the lands. It was believed that the men who had enlisted [for the Civil War] had all left the state, and that before help could be sent the Indians could clean out the country, and that the Winnebagoes, and even the Chippewas, would assist the Sioux."² Anticipating collective punishment, Dakota leaders called a council to debate whether any future remained in patience or restraint.

Portrait photo of Little Crow (Taoyateduta) in Washington, D.C. 1858 (Wikimedia Commons)

At Little Crow's house—just hours after the Acton murders—the council did not celebrate revolt. Instead, it was a reckoning with years of repression and the glimmer of hope for recovering their taken land. Elders like Traveling Hail urged caution; others pressed for violence, seeing it as inevitable. The people turned to Little Crow (Taoyateduta), not as a willing commander but as a last, reluctant leader. His response carried grief, not glory:

Braves, you are like little children; you know not what you are doing... We are only little herds of buffalo left scattered; the great herds that once covered the prairies are no more. See!–the white men are like the locusts when they fly so thick that the whole sky is a snowstorm... Kill one–two–ten, and ten times ten will come to kill you. Count your fingers all day long and white men with guns in their hands will come faster than you can count… Yes; they fight among themselves, but if you strike at them they will all turn on you and devour you and your women and little children…^{2 32}

He warned of ruin, but in the end agreed to share his people's fate:

Taoyateduta is not a coward; he will die with you.^{2 31 32}

By dawn, war became a reality. Dakota warriors attacked agency posts and settlements along the Minnesota River. The uprising that followed was swift, brutal, and impossible to contain; it was the collective response of a people who, for all their prior appeals to justice, had been driven to the end of endurance.³³ The eruption of war on August 18 was not a heroic rebellion but the consequence of a willfully ignored protest.^{8 10 19} Where Thoreau's disobedience could eventually be read as testing the republic's conscience, the Dakota's became proof of American innocence. The dominant order legitimates only forms of resistance it is willing to see; the rest are lost to law and memory.^{27 28 34 35} Dakota protest at the limits of endurance revealed the costs of American justice: costs written in the lives and land of the unseen. What followed made clear that the winners drew the boundary between legitimate protest and criminality through violence, law, and forgetting.

Contradiction at the Heart of America

The American project of self-creation, defining and redefining national identity, has always depended on principles of liberty and retroactively drawing boundaries around which voices and memories are permitted to matter. Thoreau's solitary act of resistance, refusing to pay taxes to a state complicit in slavery and war, became enshrined as an emblem of the nation's highest values: individual conscience, principled dissent, and the celebration of questioning authority. His place in memory was secured because his protest could be absorbed into the mythology of American freedom. It was held up as proof that the nation welcomes and ultimately honors those who resist injustice, so long as their protest fits within familiar forms.

As Kaplan observes, "American exceptionalism [is] defined as inherently anti-imperialist, in opposition to… empire-building," even as conquest of Native land—and the disavowal of that history—remains a recurring requirement of national identity.³⁶ Those who cannot be so recuperated, like the Dakota, remain consigned to absence, their protest rendered unintelligible by the shape of American memory.

For the Dakota, resistance was not a matter of experiment or choice. It was compelled by a foreign nation's encroachment and broken promises, as years of negotiation and legal petitions were met with indifference or betrayal.² When hope was finally exhausted, the Dakota's acts were punished as crimes by military tribunals, in stark contrast to how American dissenters like Thoreau were ultimately canonized.⁸

The doctrine of "domestic dependent nations" relegated tribal sovereignty to a status always subject to Congressional authority, enabling the United States to unilaterally break treaties and redefine or dissolve Native rights whenever expedient.³⁴ The Dakota case is emblematic of how this legal structure, repeatedly upheld by American courts, applied to all Native societies whose continued presence challenged the national project of settler self-creation.

Cheyfitz characterizes this dynamic as a "self-serving logic" built into American law and the story it tells: "This 'history of America' is, of course, generated by the same 'principles' that it 'proves': the principles of Western law, which are, precisely, those of property with its foundation in the notion of title. This history, then, is based on a totally self-reflexive, or self-serving, logic, the limits of which are the term property."¹⁸ The American ideal of liberty has always relied on the exile or silencing of those whose relationships to land defied its boundaries. Manifest Destiny demanded the erasure of people whose kinship with place troubled the nation's chosen script.

Tragedy and Exile

The aftermath of the Dakota resistance brought neither justice nor peace. Minnesota Governor Alexander Ramsey proclaimed to the legislature, "The Sioux Indians of Minnesota must be exterminated or driven forever beyond the borders of the State."¹⁹ Words became policy: the state organized bounties for Dakota scalps and encouraged vigilantes to hunt any survivors. Federal authorities, facing pressure from settlers clamoring for revenge, organized mass military trials that sentenced 307 Dakota men to death, offering little pretense of due process (some trials were heard in as little as five minutes) and recognizing neither the context nor the legitimacy of their resistance.^{8 32 37}

In Washington, President Lincoln confronted a settler populace demanding vengeance. He reviewed the court records to commute as many sentences as possible.

The president ordered a stay of all executions until he personally reviewed the trial transcripts. Sick at heart by the ongoing slaughter in the South, Lincoln had no appetite for mass hangings. He agreed with Commissioner of Indian Affairs William Dole that such actions would be "a stain on the national character." The president was also troubled by a recent meeting with [missionary] Bishop Whipple, who had eloquently laid out the history of abuses that finally culminated in violence. Lincoln was so moved that he pledged, "If we get through this war, and I live, this Indian system shall be reformed!"¹⁰

Print of a drawing depicting the 1862 execution of 38 Dakota men at Mankato, Minnesota, by John C. Wise (public domain)

After the gallows, the punishment did not end. More than 1,700 Dakota men, women, and children were forced to a concentration camp below Fort Snelling, where hundreds died of disease and exposure through the winter. The next year, the state ordered the complete removal of the survivors, even those who had opposed the war. On their way out, they were subjected to humiliation and assault as townspeople lined the route in fury. Congress unilaterally annulled all Dakota treaties.^{38 39} Courts affirmed that Congress, within America's own legal inventions, had the right to break its word if it saw fit, anchoring the Dakota expulsion in law.

American triumph was built on the disappearance of peoples and stories. The aftermath of the Dakota resistance made clear that the victors drew the boundary between legitimate protest and criminality through violence, law, and selective forgetting. Memories of liberty were secured for some at the price of another's removal, and the nation's own ideals were entwined with exclusion and exile. Though the narrative of the Dakota has often been suppressed or disregarded, their voices persist, enduring in acts of protest, remembrance, and the ongoing struggle to be heard in their own homeland. The contradiction remains: a nation that celebrates dissent and justice, but only within the limits it chooses to recognize. To remember Dakota resistance as it truly was—not as a crime, but as a final, desperate reckoning with betrayal—is to expose the unresolved cost of American self-creation, a cost that neither Thoreau's searching conscience nor Little Crow's doomed warning could ultimately redeem or erase. Only in facing the stories that have been written out, yet still refuse to fade away, can the depths of the long-favored promise and the wounds beneath it come fully into view.

Glossary and People

Alexander Ramsey: (1815-1903) Governor of Minnesota during the Dakota War, who called for the removal or extermination of the Dakota following the conflict.
bde: lake (noun), going (verb).
Bdewákhaŋthuŋwaŋ or Mdewakanton: one of the tribes of the Isáŋyathi (Santee) Dakota (Sioux), of which Little Crow was a leader. Literally "people of the mystic lake" (Lake Mille Lacs).
Bdote: literally "confluence of rivers," also known as Maka Ċokaya Kiŋ, the center of the earth.
Big Eagle (Wamditanka): (1827-1906) A respected Dakota leader and orator, whose account of the causes of the 1862 war is frequently cited. He participated in the conflict and later dictated his experience. He was among those pardoned by President Lincoln.
Ȟaȟa Wakpa: literally "River of the Falls", Mississippi River.
Henry David Thoreau: (1817-1862) American naturalist, essayist and philosopher. He championed individual conscience, simplicity and resistance to unjust government. Thoreau visited Minnesota in 1861 in an attempt to treat his terminal tuberculosis.
Isáŋyathi, Isanti, Santee: The Eastern Dakota, "dwells at the place of knife flint."
Little Crow (Taoyateduta, His Red Nation): (c. 1810-1863) A prominent Bdewákhaŋthuŋwaŋ leader during the Dakota War. He became the reluctant leader of Dakota resistance following pressure from his people.
Lower Sioux Agency, or Redwood Agency: the federal administrative center for Dakota living on the lower (downriver) part of the Minnesota River.
Maka Ina: Mother Earth.
mni: water.
Mni Sota Makoċe: Minnesota, literally "land where water reflects the sky."
Očéti Šakówiŋ: Seven Council Fires, also called the Sioux.
Sarah Wakefield: (1829-1899) A white prisoner and survivor of the Dakota War, she provided a first-hand account of conditions in Dakota caps and the events surrounding the war.
Sioux, or Nadouessioux: The Sioux people, from the Ojibwe term Nadowessi meaning "little snakes."
Sisíthuŋwaŋ: one of the tribes of the Isáŋyathi (Santee) Dakota (Sioux). Literally "lake village people."
Stephen Riggs: (1812-1883) Presbyterian missionary and linguist who translated treaties for the U.S. government, often in ways that obscured critical legal meanings for Dakota signers.
tipi: lodge (noun), they live (verb).
Traveling Hail (Wasuihiyayedan): An elder within the Dakota community, elected speaker in 1862, noted for counseling caution and restraint after the Acton murders.
Upper Sioux Agency, or Yellow Medicine Agency: the federal administrative center for Dakota living on the upper (upriver) part of the Minnesota River.
Wabasha: (c. 1816–1876) Principal chief of his Bdewákhaŋthuŋwaŋ band in 1862. Advocated for negotiation and adaptation with the U.S. government, striving for land security. After the war, he helped rebuild lives at the Santee Reservation in Nebraska.
Waȟpékhute: one of the tribes of the Isáŋyathi (Santee) Dakota (Sioux). Literally "leaf archers."
wakaŋ: holy, mysterious, sacred.
Wakaŋ Tipi: Dakota sacred site near present-day St. Paul, Minnesota.
wakpa: river, stream.
Wakpa Mni Sota: Minnesota River.
Wanaġi Taċaŋku: road of the spirits, the Milky Way.
William Whipple (Bishop Whipple): (1822-1901) Episcopal Bishop of Minnesota and advocate for reform of the federal Indian system, he pleaded for clemency and justice for the Dakota with President Lincoln.

Brief Timeline

1805: Treaty of St. Peters, also called Pike's Purchase, the Dakota cede small tracts at Bdote for the construction of Fort Snelling, and eagerly await this new trading opportunity.
1825: Treaty of Prairie du Chien, establishing tribal boundaries and "spheres of influence."
1837: [Second] Treaty of St. Peters, also called the White Pine Treaty, the Dakota ceded land east of the Mississippi.
1851: Treaties of Mendota and Traverse des Sioux, the Dakota cede nearly all of their land and move to a reservation system in exchange for annuity payments.
July 1845–September 1847: Thoreau lives at Walden Pond.
May 1849: Thoreau's "Resistance to Civil Government" is first published in Aesthetic Papers.
August 9, 1854: Walden is published.
1858: "Land Allotment" Treaties, reducing Dakota land to a small reservation along the Minnesota River (10 miles wide, 140 miles long), opening the rest of the land to white settlement.
May 11–July 9, 1861: Thoreau visits Minnesota in an attempt to relieve his tuberculosis.
May 6, 1862: Thoreau dies from tuberculosis.
August 17, 1862: Murder of five settlers at Acton, Minnesota.
August 18, 1862: Attacks on the Upper and Lower Sioux Agencies, and Redwood Ferry.
August 22, 1862: Main attack on Fort Ridgely.
September 26, 1862: Surrender of captives at Camp Release.
December 26, 1862: 38 Dakota executed at Mankato, Minnesota.
February 16, 1863: Congress passes an act that "all treaties heretofore made and entered into by the Sisseton, Wahpaton, Medawakanton, and Wahpakoota bands of Sioux or Dakota Indians, or any of them, with the United States, are hereby declared to be abrogated and annulled."
July 3, 1863: Little Crow is killed by a settler near Hutchinson while gathering raspberries.

Notes and References

Thoreau, Henry David. Walden and Civil Disobedience. New York: Union Square & Co, 2023.
Anderson, Gary Clayton, and Alan R. (Alan Roland) Woolworth. Through Dakota Eyes: Narrative Accounts of the Minnesota Indian War of 1862. St. Paul: Minnesota Historical Society Press, 1988.
The steamboat that carried Thoreau to the Redwood Agency in 1861 was named the Frank Steele after a man whose "flashing axe in the wilderness" symbolized the spirit of settler progress. Thoreau observed with wry detachment how the boat repeatedly rammed riverbanks and destroyed trees to navigate the winding waterway, offering a literal and comic description of American expansion crashing up against the land's contours.²³
The terminology used for Native peoples in North America varies considerably and is shaped by context, community preference, and scholarly convention. "Native American," "American Indian," "Indigenous," and "Native" are all in current use, and it is widely accepted best practice to name peoples in terms of their specific tribal or national identity whenever possible—for example, Dakota, Ojibwe, or Lakota.^{5 14 19} While the most linguistically precise representation may be "Dakȟóta" or "Dakhóta" (with diacriticals reflecting the Dakota alphabet), the plain form "Dakota" appears most consistently in both academic scholarship and within English-language writings by Dakota scholars themselves (see Waziyatawin, Westerman & White). The anglicized spelling is thus retained here for coherence with established scholarly usage and accessibility to a general audience, while always privileging Dakota perspectives and language where appropriate.
National Museum of the American Indian. "Teaching & Learning about Native Americans," n.d. https://americanindian.si.edu/nk360/faq/did-you-know.
Harding, Walter. "Thoreau and Mann on the Minnesota River, June, 1861." Minnesota History 37, no. 6 (1961): 225–28. http://www.jstor.org/stable/20176368.
Flanagan, John T. "Thoreau in Minnesota." Minnesota History 16, no. 1 (1935): 35–46. http://www.jstor.org/stable/20161165.
Carley, Kenneth. The Dakota War of 1862. 2nd ed. St. Paul, Minnesota: Minnesota Historical Society Press, 2001.
In Thoreau's Minnesota notes, he records a "Dream Dance" put on at the request of Governor Ramsey at the 1861 agency gathering, but there is no documented evidence of this as a specific Dakota ceremony at that time. The "Dream" or "Drum Dance" later became part of new religious movements responding to dispossession and trauma, but Thoreau (like many observers) likely misunderstood the ritual, applying a misnomer from missionary or ethnographer sources to a Dakota ceremony whose meaning he did not grasp.^{23 19}
Wingerd, Mary Lethert. North Country: The Making of Minnesota. Minneapolis: University of Minnesota Press, 2010.
Buell, Lawrence. "Thoreau and the Natural Environment." In The Cambridge Companion to Henry David Thoreau, 171–93. Cambridge: Cambridge University Press, 1995. doi:10.1017/CCOL0521440378.013.
Buell, Lawrence. "American Literary Emergence as a Postcolonial Phenomenon." American Literary History 4, no. 3 (1992): 411–42. http://www.jstor.org/stable/489858.
Schneider, Richard J. "Walden." In The Cambridge Companion to Henry David Thoreau, 92–106. Cambridge: Cambridge University Press, 1995. doi:10.1017/CCOL0521440378.008.
Waziyatawin. "Maka Cokaya Kin (The Center of the Earth): From the Clay We Rise." Paper presented at University of Hawaii Manoa International Symposium 'Folktales and Fairy Tales: Translation, Colonialism, and Cinema', Honolulu, Sept 23-26, 2008. http://scholarspace.manoa.hawaii.edu/handle/10125/16456.
The Dakota word Bdote (or Mdote) means "confluence" and refers specifically to the area around the meeting of the Minnesota and Mississippi Rivers. The difference in spelling (B- vs. M-) arises from dialect variation and changing conventions for transcribing Dakota—contemporary usage increasingly prefers "Bdote."^{14 16}
White, Bruce. "Bdote/ Mdote Minisota: A Public EIS Continues." MinnesotaHistory.Net (blog), February 26, 2009. https://www.minnesotahistory.net/staging/?p=169.
Wolfe, Patrick. 2006. "Settler Colonialism and the Elimination of the Native." Journal of Genocide Research 8 (4): 387–409. doi:10.1080/14623520601056240.
Cheyfitz, Eric. "Savage Law: The Plot Against American Indians in Johnson and Graham's Lessee v. M'Intosh and The Pioneers." Cultures of United States Imperialism (1993): 109-128.
Westerman, Gwen, and Bruce M. White. Mni Sota Makoċe: The Land of the Dakota. St. Paul: Minnesota Historical Society Press, 2012.
The Dakota name for the Mississippi is Wakpá Taŋka (Great River) or Ȟaȟa Wakpá (River of the Falls). The name Mississippi comes from the Anishinaabe (Ojibwe) name Misi-ziibi, also meaning Great River.
Gould, Roxanne, and Jim Rock. "Wakaŋ Tipi and Indian Mounds Park: Reclaiming an Indigenous Feminine Sacred Site." AlterNative: An International Journal of Indigenous Peoples 12, no. 3 (September 2016): 224–35. https://doi.org/10.20507/AlterNative.2016.12.3.2.
Missionary Stephen R. Riggs, the main translator for the Dakota-language text of the treaty of Traverse des Sioux (1851), intentionally substituted neutral or ambiguous Dakota verbs in place of critical American legal concepts. For example, the English treaty states the Dakota "agree to cede, sell, and relinquish all their lands." Riggs translated "cede" as "erpeyapi" (to give up, throw away, lose), a term without the legal finality of English property law, a word he also used for describing money that would be set aside for farming equipment. Meanwhile, "sell" and "relinquish" were treated similarly, with Riggs using everyday Dakota phrasing that did not carry the sense of permanent transfer. The Dakota had no concept of exclusive title to land, and this linguistic mismatch ensured they could not grasp what they were supposedly agreeing to.¹⁹
Sayre, Robert F. Thoreau and the American Indians. Princeton, N.J: Princeton University Press, 1987.
The historical agreement commonly called the "Treaty of Mendota" is referred to by this official name because that is its title in United States government records and legal references. While "Mendota" is an anglicized rendering of the Dakota word Bdote, using the legal designation also distinguishes this specific 1851 treaty from other agreements and references to the place itself.^{16 19}
The 1862 annuity for the Dakota was delayed in part by a debate in Washington over whether it should be sent in gold or the new "greenbacks" (paper money), a monetary drama that further illustrates how distant policies could devastate local life. In a tragic irony, the $71,000 in gold finally arrived at Saint Paul the day before the murders at Acton, and would arrive to Fort Ridgely (the military camp protecting the agencies) several days later—too late to prevent the ongoing war.⁸
Wakefield, Sarah F, and June Namias. Six Weeks in the Sioux Tepees : A Narrative of Indian Captivity. Norman: University of Oklahoma Press, 1997.
Reddy, Saahith. "Thoreau's Civil Disobedience from Concord, Massachusetts: Global Impact." Frontiers in Political Science 6 (October 2, 2024). https://doi.org/10.3389/fpos.2024.1458098.
Erickson, Evie. "Investigating the Meaning and Application of Civil Disobedience Through Thoreau, Gandhi and Martin Luther King Jr." The Nonviolence Project. University of Wisconsin-Madison, March 16, 2024. https://thenonviolenceproject.wisc.edu/2024/03/16/investigating-the-meaning-and-application-of-civil-disobedience-through-thoreau-gandhi-and-martin-luther-king-jr/.
Hendrick, George. "The Influence of Thoreau's 'Civil Disobedience' on Gandhi's Satyagraha." The New England Quarterly 29, no. 4 (1956): 462–71. https://doi.org/10.2307/362139.
While the murder of five settlers at Acton on August 17, 1862, is often cited as the direct cause of war, underlying conditions made violence an ever-present risk. Dakota survivors and many settlers alike understood this event not as the origin, but as the moment when unbearable injustices boiled over—though the leaders who chose violence did so reluctantly and with awareness of likely catastrophe.^{2 8}
Despite being widely depicted in frontier myth as a bloodthirsty war chief, Little Crow (Taoyateduta) was, in fact, a complex and often conflicted leader. He succeeded his father as chief only after a violent dispute left him with both wrists shattered by gunfire; for years, he advocated for adaptation and peaceful coexistence, attending church services, negotiating in Washington, and even taking up farming. His oratory was legendary, and his warning to the war council in August 1862 was later remembered word-for-word by his son, Wowinape, and corroborated by other Dakota witnesses. In an unusual twist of fate, after the war forced him into exile, Little Crow was killed while picking raspberries with his son near Hutchinson, Minnesota. His scalp and remains were displayed for decades as war trophies in Minnesota museums, before finally being returned to his descendants for proper burial in the 1970s—a potent symbol of the long afterlife of memory and erasure in the story of Dakota resistance.^{2 10}
Michno, Gregory, ed. Dakota Dawn: The Decisive First Week of the Sioux Uprising, August 17-24, 1862. New York: Savas Beatie LLC, 2011.
Fort Ridgely was among the obvious targets, and would be attacked twice in the coming weeks. Coincidentally, Fort Ridgely was named after two U.S. Army officers who died in the Mexican-American War: Major Jefferson F. Ridgely and Lieutenant Thomas L. Ridgely. The Mexican-American War itself was among the government injustices that prompted Thoreau's "Civil Disobedience," as he refused to pay taxes to a government waging what he considered an immoral conflict. Built in 1853 on the Minnesota River, Fort Ridgely became a crucial defensive post during the U.S.-Dakota War of 1862, serving as the main refuge for white settlers and a central target during the conflict's early battles; its survival prevented a wider collapse of settler control in the region. Notably, contemporary accounts suggest that if the Dakota had attacked the fort immediately following their early victories—before reinforcements arrived—they could have overrun it and altered the course of the war.^{1 8}
Duthu, N. Bruce. American Indians and the Law. The Penguin Library of American Indian History. London: Penguin Books, 2009.
Byrd, Jodi A. The Transit of Empire: Indigenous Critiques of Colonialism. First Peoples: New Directions in Indigenous Studies. Minneapolis: University of Minnesota Press, 2011.
Kaplan, Amy. "Left Alone With America: The Absence of Empire in the Study of American Culture." In Cultures of United States Imperialism. New Americanists. Durham: Duke University Press, 1993.
Many of the military trials that followed the Dakota War of 1862 were shockingly brief, sometimes lasting just minutes. One reason for this haste was that Dakota defendants, unfamiliar with American criminal proceedings, often freely admitted participation in battles, believing they were answering honestly about what they considered legitimate acts of war against soldiers. Unaware that they were being tried as if these actions were cold-blooded murder rather than recognized acts of war, they did not see the need to conceal their involvement.^{8 10}
Vogel, Howard. "Rethinking the Effect of the Abrogation of the Dakota Treaties and the Authority for the Removal of the Dakota People from Their Homeland." William Mitchell Law Review 39, no. 2 (January 1, 2013). https://open.mitchellhamline.edu/wmlr/vol39/iss2/5.
In the wake of the Dakota War, Congress passed legislation in February of 1863 unilaterally abrogating all treaties with the Dakota. "Abrogation" refers to the formal repeal or annulment of a law or agreement; in this case, Congress declared that all obligations to the Dakota under previous treaties were void and redirected remaining payments to compensate white settlers for damage caused by the war. According to U.S. legal doctrine, Congress reserves the power to unilaterally end treaties with Native nations—essentially disregarding the original nation-to-nation status and legal promises—by simple legislative act, even without the consent of the affected Native party. The Supreme Court has repeatedly upheld this authority, holding that "plenary power" over Indian affairs resides with Congress, regardless of prior agreements. The Act of February 16, 1863 not only declared the treaties abrogated but also seized Dakota lands within the State of Minnesota. The Dakota, for their part, had no legal recourse to prevent this breach; the federal government's power to break its own word was built into the legal system governing U.S.-Native relations.^{38 40}
U.S. Congress, An Act for the Relief of Persons for Damages sustained by Reason of Depredations and Injuries by certain Bands of Sioux Indians, 37th Cong., Act, February 16, 1863.
Dakota Online Dictionary, https://dictionary.swodli.com/index.html.
Scott County Historical Society. "Thoreau's Journey along the Minnesota River," May 22, 2019. https://www.scottcountyhistory.org/blog/thoreaus-journey-along-the-minnesota-river.
Dunbar-Ortiz, Roxanne. An Indigenous Peoples' History of the United States. ReVisioning American History. Boston: Beacon Press, 2014.

Set DuckDuckGo as default search in Thunderbird

2017-09-23T09:00:00-06:00

For several dwindling reasons, DuckDuckGo can still be tricky to add to some services despite being the default search engine for several browsers. A couple years ago, Mozilla made the decision to open searches from Thunderbird in your default browser, instead of using a tab in Thunderbird itself, which broke the previous method of adding DuckDuckGo to the settings. They neglected to update their tutorials for adding more than the default search engines, and as of this writing neither has DuckDuckGo (though I will be contributing this tutorial to them).

Download and install the Google Search for Thunderbird add-on. You can easily do this within Thunderbird by going to Tools > Add-ons > Get Add-ons
Navigate to your profile library. One way to get there is Help > Troubleshooting information > Application basics > Profile Directory > Open Directory
Navigate to the directory extensions/gsearch@standard8.plus.com/searchplugins
Save the following file into that directory: https://duckduckgo.com/opensearch.xml
Rename the file as anything you want as long as you keep the .xml suffix
Make sure to leave the existing Google.xml file as is
Restart Thunderbird
Finally, go to Edit > Preferences > General > Default Search Engine and choose DuckDuckGo! Now you're set!

You can also put any other OpenSearch XML files into that same directory if you want to add any other search engines.

The Internet worm of 1988: A Tour of the Worm

2017-10-31T09:00:00-06:00

A Tour of the Worm

Donn Seeley
Department of Computer Science
University of Utah

ABSTRACT

On the evening of November 2, 1988, a self-replicating program was released upon the Internet (1) This program (a worm) invaded VAX and Sun-3 computers running versions of Berkeley UNIX, and used their resources to attack still more computers (2). Within the space of hours this program had spread across the U.S., infecting hundreds or thousands of computers and making many of them unusable due to the burden of its activity. This paper provides a chronology for the outbreak and presents a detailed description of the internals of the worm, based on a C version produced by decompiling.

Table of contents:

1. Introduction
2. Chronology
3. Overview
4. Internals
5. Opinions
6. Conclusion
Acknowledgments

1. Introduction

There is a fine line between helping administrators protect their systems and providing a cookbook for bad guys.

November 3, 1988 is already coming to be known as Black Thursday. System administrators around the country came to work on that day and discovered that their networks of computers were laboring under a huge load. If they were able to log in and generate a system status listing, they saw what appeared to be dozens or hundreds of "shell" (command interpreter) processes. If they tried to kill the processes, they found that new processes appeared faster than they could kill them. Rebooting the computer seemed to have no effect within minutes after starting up again, the machine was overloaded by these mysterious processes.

These systems had been invaded by a worm. A worm is a program that propagates itself across a network, using resources on one machine to attack other machines. (A worm is not quite the same as a virus, which is a program fragment that inserts itself into other programs.) The worm had taken advantage of lapses in security on systems that were running 4.2 or 4.3 BSD UNIX or derivatives like SunOS. These lapses allowed it to connect to machines across a network, bypass their login authentication, copy itself and then proceed to attack still more machines. The massive system load was generated by multitudes of worms trying to propagate the epidemic.

The Internet had never been attacked in this way before, although there had been plenty of speculation that an attack was in store. Most system administrators were unfamiliar with the concept of worms (as opposed to viruses, which are a major affliction of the PC world) and it took some time before they were able to establish what was going on and how to deal with it. This paper is intended to let people know exactly what happened and how it came about, so that they will be better prepared when it happens the next time. The behavior of the worm will be examined in detail, both to show exactly what it did and didn't do, and to show the dangers of future worms. The epigraph above is now ironic, for the author of the worm used information in that paper to attack systems. Since the information is now well known, by virtue of the fact that thousands of computers now have copies of the worm, it seems unlikely that this paper can do similar damage, but it is definitely a troubling thought. Opinions on this and other matters will be offered below.

2. Chronology

Remember, when you connect with another computer, you're connecting to every computer that computer has connected to.

Here is the gist of a message I got: I'm sorry.

Many details of the chronology of the attack are not yet available. The following list represents dates and times that we are currently aware of. Times have all been rendered in Pacific Standard Time for convenience.

11/2:1800 (approx.): This date and time were seen on worm files found on prep.ai.mit.edu, a VAX 11/750 at the MIT Artificial Intelligence Laboratory. The files were removed later, and the precise time was lost. System logging on prep had been broken for two weeks. The system doesn't run accounting and the disks aren't backed up to tape: a perfect target. A number of "tourist" users (individuals using public accounts) were reported to be active that evening. These users would have appeared in the session logging, but see below.
11/2:1824: First known West Coast infection: rand.org at Rand Corp. in Santa Monica.
11/2:1904: csgw.berkeley.edu is infected. This machine is a major network gateway at UC Berkeley. Mike Karels and Phil Lapsley discover the infection shortly afterward.
11/2:1954: mimsy.umd.edu is attacked through its finger server. This machine is at the University of Maryland College Park Computer Science Department.
11/2: 2000 (approx.): Suns at the MIT AI Lab are attacked.
11/2: 2028: First sendmail attack on mimsy.
11/2: 2040: Berkeley staff figure out the sendmail and rsh attacks, notice telnet and finger peculiarities, and start shutting these services off.
11/2: 2049: cs.utah.edu is infected. This VAX 8600 is the central Computer Science Department machine at the University of Utah. The next several entries follow documented events at Utah and are representative of other infections around the country.
11/2: 2109: First sendmail attack at cs.utah.edu.
11/2: 2121: The load average on cs.utah.edu reaches 5. The "load average" is a system-generated value that represents the average number of jobs in the run queue over the last minute; a load of 5 on a VAX 8600 noticeably degrades response times, while a load over 20 is a drastic degradation. At 9 PM, the load is typically between 0.5 and 2.
11/2: 2141: The load average on cs.utah.edu reaches 7.
11/2: 2201: The load average on cs.utah.edu reaches 16.
11/2: 2206: The maximum number of distinct runnable processes (100) is reached on cs.utah.edu; the system is unusable.
11/2: 2220: Jeff Forys at Utah kills off worms on cs.utah.edu. Utah Sun clusters are infected. 11/2: 2241 Re-infestation causes the load average to reach 27 on cs.utah.edu.
11/2: 2249: Forys shuts down cs.utah.edu.
11/3: 2321: Re-infestation causes the load average to reach 37 on cs.utah.edu, despite continuous efforts by Forys to kill worms.
11/2: 2328: Peter Yee at NASA Ames Research Center posts a warning to the TCP-IP mailing list: "We are currently under attack from an Internet VIRUS. It has hit UC Berkeley, UC San Diego, Lawrence Livermore, Stanford, and NASA Ames." He suggests turning off telnet, ftp, finger, rsh and SMTP services. He does not mention rexec. Yee is actually at Berkeley working with Keith Bostic, Mike Karels and Phil Lapsley.
11/3: 0034: At another's prompting, Andy Sudduth of Harvard anonymously posts a warning to the TCP-IP list: "There may be a virus loose on the internet." This is the first message that (briefly) describes how the finger attack works, describes how to defeat the SMTP attack by rebuilding sendmail, and explicitly mentions the rexec attack. Unfortunately Sudduth's message is blocked at relay.cs.net while that gateway is shut down to combat the worm, and it does not get delivered for almost two days. Sudduth acknowledges authorship of the message in a subsequent message to TCP-IP on Nov. 5.
11/3: 0254: Keith Bostic sends a fix for sendmail to the newsgroup comp.bugs.4bsd.ucb-fixes and to the TCP-IP mailing list. These fixes (and later ones) are also mailed directly to important system administrators around the country.
11/3: early morning: The wtmp session log is mysteriously removed on prep.ai.mit.edu.
11/3: 0507: Edward Wang at Berkeley figures out and reports the finger attack, but his message doesn't come to Mike Karels' attention for 12 hours.
11/3: 0900: The annual Berkeley Unix Workshop commences at UC Berkeley. 40 or so important system administrators and backers are in town to attend, while disaster erupts at home. Several people who had planned to fly in on Thursday morning are trapped by the crisis. Keith Bostic spends much of the day on the phone at the Computer Systems Research Group offices answering calls from panicked system administrators from around the country.
11/3 :1500 (approx.): The team at MIT Athena calls Berkeley with an example of how the finger server bug works.
11/3:1626: Dave Pare arrives at Berkeley CSRG offices; disassembly and decompiling start shortly afterward using Pare's special tools.
11/3:1800 (approx.): The Berkeley group sends out for calzones. People arrive and leave; the offices are crowded, there's plenty of excitement. Parallel work is in progress at MIT Athena; the two groups swap code.
11/3:1918: Keith Bostic posts a fix for the finger server.
11/4: 0600: Members of the Berkeley team, with the worm almost completely disassembled and largely decompiled, finally take off for a couple hours' sleep before returning to the workshop.
11/4: 1236: Theodore Ts'o of Project Athena at MIT publicly announces that MIT and Berkeley have completely disassembled the worm.
11/4:1700 (approx.): A short presentation on the worm is made at the end of the Berkeley UNIX Workshop.
11/8:: National Computer Security Center meeting to discuss the worm. There are about 50 attendees.
11/11: 0038: Fully decompiled and commented worm source is installed at Berkeley.

3. Overview

What exactly did the worm do that led it to cause an epidemic? The worm consists of a 99-line bootstrap program written in the C language, plus a large relocatable object file that comes in VAX and Sun-3 flavors. Internal evidence showed that the object file was generated from C sources, so it was natural to decompile the binary machine language into C; we now have over 3200 lines of commented C code which recompiles and is mostly complete. We shall start the tour of the worm with a quick overview of the basic goals of the worm, followed by discussion in depth of the worm's various behaviors as revealed by decompilation.

The activities of the worm break down into the categories of attack and defense. Attack consists of locating hosts (and accounts) to penetrate, then exploiting security holes on remote systems to pass across a copy of the worm and run it. The worm obtains host addresses by examining the system tables /etc/hosts.equiv and /.rhosts, user files like .forward and. rhosts, dynamic routing information produced by the netstat program, and finally randomly generated host addresses on local networks. It ranks these by order of preference, trying a file like /etc/hosts.equiv first because it contains names of local machines that are likely to permit unauthenticated connections. Penetration of a remote system can be accomplished in any of three ways. The worm can take advantage of a bug in the finger server that allows it to download code in place of a finger request and trick the server into executing it. The worm can use a "trap door" in the sendmail SMTP mail service, exercising a bug in the debugging code that allows it to execute a command interpreter and download code across a mail connection. If the worm can penetrate a local account by guessing its password, it can use the rexec and rsh remote command interpreter services to attack hosts that share that account. In each case the worm arranges to get a remote command interpreter which it can use to copy over, compile and execute the 99-line bootstrap. The bootstrap sets up its own network connection with the local worm and copies over the other files it needs, and using these pieces a remote worm is built and the infection procedure starts over again. Defense tactics fall into three categories: preventing the detection of intrusion, inhibiting the analysis of the program, and authenticating other worms. The worm's simplest means of hiding itself is to change its name. When it starts up, it clears its argument list and sets its zeroth argument to sh, allowing it to masquerade as an innocuous command interpreter. It uses fork() to change its process I.D., never staying too long at one I.D. These two tactics are intended to disguise the worm's presence on system status listings. The worm tries to leave as little trash lying around as it can, so at start-up it reads all its support files into memory and deletes the tell-tale filesystem copies. It turns off the generation of core files, so if the worm makes a mistake, it doesn't leave evidence behind in the form of core dumps. The latter tactic is also designed to block analysis of the program-it prevents an administrator from sending a software signal to the worm to force it to dump a core file. There are other ways to get a core file, however, so the worm carefully alters character data in memory to prevent it from being extracted easily. Copies of disk files are encoded by repeatedly exclusive-or'ing a ten-byte code sequence; static strings are encoded byte-by-byte by exclusive-or'ing with the hexadecimal value 81, except for a private word list which is encoded with hexadecimal 80 instead. If the worm's files are somehow captured before the worm can delete them, the object files have been loaded in such a way as to remove most non-essential symbol table entries, making it harder to guess at the purposes of worm routines from their names. The worm also makes a trivial effort to stop other programs from taking advantage of its communications; in theory a well-prepared site could prevent infection by sending messages to ports that the worm was listening on, so the worm is careful to test connections using a short exchange of random "magic numbers".

When studying a tricky program like this, it's just as important to establish what the program does not do as what it does do. The worm does not delete a system's files: it only removes files that it created in the process of bootstrapping. The program does not attempt to incapacitate a system by deleting important files, or indeed any files. It does not remove log files or otherwise interfere with normal operation other than by consuming system resources. The worm does not modify existing files: it is not a virus. The worm propagates by copying itself and compiling itself on each system; it does not modify other programs to do its work for it. Due to its method of infection, it can't count on sufficient privileges to be able to modify programs. The worm does not install trojan horses: its method of attack is strictly active, it never waits for a user to trip over a trap. Part of the reason for this is that the worm can't afford to waste time waiting for trojan horses-it must reproduce before it is discovered. Finally, the worm does not record or transmit decrypted passwords: except for its own static list of favorite passwords, the worm does not propagate cracked passwords on to new worms nor does it transmit them back to some home base. This is not to say that the accounts that the worm penetrated are secure merely because the worm did not tell anyone what their passwords were, of course-if the worm can guess an account's password, certainly others can too. The worm does not try to capture superuser privileges: while it does try to break into accounts, it doesn't depend on having particular privileges to propagate, and never makes special use of such privileges if it somehow gets them. The worm does not propagate over uucp or X.25 or DECNET or BITNET: it specifically requires TCP/IP. The worm does not infect System V systems unless they have been modified to use Berkeley network programs like sendmail, fingerd and rexec.

4. Internals

Now for some details: we shall follow the main thread of control in the worm, then examine some of the worm's data structures before working through each phase of activity.

4.1. The thread of control

When the worm starts executing in main(), it takes care of some initializations, some defense and some cleanup. The very first thing it does is to change its name to sh. This shrinks the window during which the worm is visible in a system status listing as a process with an odd name like x9834753. It then initializes the random number generator, seeding it with the current time, turns off core dumps, and arranges to die when remote connections fail. With this out of the way, the worm processes its argument list. It first looks for an option -p $$, where $$ represents the process I.D. of its parent process; this option indicates to the worm that it must take care to clean up after itself. It proceeds to read in each of the files it was given as arguments; if cleaning up, it removes each file after it reads it. If the worm wasn't given the bootstrap source file l1.c as an argument, it exits silently; this is perhaps intended to slow down people who are experimenting with the worm. If cleaning up, the worm then closes its file descriptors, temporarily cutting itself off from its remote parent worm, and removes some files. (One of these files, /tmp/.dumb, is never created by the worm and the unlinking seems to be left over from an earlier stage of development.) The worm then zeroes out its argument list, again to foil the system status program ps. The next step is to initialize the worm's list of network interfaces; these interfaces are used to find local networks and to check for alternate addresses of the current host. Finally, if cleaning up the worm resets its process group and kills the process that helped to bootstrap it. The worm's last act in main() is to call a function we named doit(), which contains the main loop of the worm.

doit()
{
    /* seed the random number generator with the time */
    /* attack hosts: gateways, Iocal nets, remote nets */
    checkother();
    send message();
    for (;;)
    {
cracksome();
other_sleep(30);
cracksome();
/* change our process ID */
/* attack hosts: gateways, known hosts, remote nets, local nets */
other_sleep(120);
if (/* 12 hours have passed */)
/* reset hosts table */
if (pleasequit && nextw > 10)
  exit(0);
    }
}

"C" pseudo-code for the doit() function

doit() runs a short prologue before actually starting the main loop. It (redundantly) seeds the random number generator with the current time, saving the time so that it can tell how long it has been running. The worm then attempts its first infection. It initially attacks gateways that it found with the netstat network status program; if it can't infect one of these hosts, then it checks random host numbers on local networks, then it tries random host numbers on networks that are on the far side of gateways, in each case stopping if it succeeds. (Note that this sequence of attacks differs from the sequence the worm uses after it has entered the main loop.)

After this initial attempt at infection, the worm calls the routine checkother() to check for another worm already on the local machine. In this check the worm acts as a client to an existing worm which acts as a server; they may exchange "population control" messages, after which one of the two worms will eventually shut down.

One odd routine is called just before entering the main loop. We named this routine send_message(), but it really doesn't send anything at all. It looks like it was intended to cause 1 in 15 copies of the worm to send a 1-byte datagram to a port on the host ernie.berkeley.edu, which is located in the Computer Science Department at UC Berkeley. It has been suggested that this was a feint, designed to draw attention to ernie and away from the author's real host. Since the routine has a bug (it sets up a TCP socket but tries to send a UDP packet), nothing gets sent at all. It's possible that this was a deeper feint, designed to be uncovered only by decompilers; if so, this wouldn't be the only deliberate impediment that the author put in our way. In any case, administrators at Berkeley never detected any process listening at port 11357 on ernie, and we found no code in the worm that listens at that port, regardless of the host.

The main loop begins with a call to a function named cracksome() for some password cracking. Password cracking is an activity that the worm is constantly working at in an incremental fashion. It takes a break for 30 seconds to look for intruding copies of the worm on the local host, and then goes back to cracking. After this session, it forks (creates a new process running with a copy of the same image) and the old process exits; this serves to turn over process I.D. numbers and makes it harder to track the worm with the system status program ps. At this point the worm goes back to its infectious stage, trying (in order of preference) gateways, hosts listed in system tables like /etc/hosts.equiv, random host numbers on the far side of gateways and random hosts on local networks. As before, if it succeeds in infecting a new host, it marks that host in a list and leaves the infection phase for the time being. After infection, the worm spends two minutes looking for new local copies of the worm again; this is done here because a newly infected remote host may try to reinfect the local host. If 12 hours have passed and the worm is still alive, it assumes that it has had bad luck due to networks or hosts being down, and it reinitializes its table of hosts so that it can start over from scratch. At the end of the main loop the worm checks to see if it is scheduled to die as a result of its population control features, and if it is, and if it has done a sufficient amount of work cracking passwords, it exits.

4.2. Data structures

The worm maintains at least four interesting data structures, and each is associated with a set of support routines.

The object structure is used to hold copies of files. Files are encrypted using the function xorbuf() while in memory, so that dumps of the worm won't reveal anything interesting. The files are copied to disk on a remote system before starting a new worm, and new worms read the files into memory and delete the disk copies as part of their start-up duties. Each structure contains a name, a length and a pointer to a buffer. The function getobjectbyname() retrieves a pointer to a named object structure; for some reason, it is only used to call up the bootstrap source file.

The interface structure contains information about the current host's network interfaces. This is mainly used to check for local attached networks. It contains a name, a network address, a subnet mask and some flags. The interface table is initialized once at start-up time.

The host structure is used to keep track of the status and addresses of hosts. Hosts are added to this list dynamically, as the worm encounters new sources of host names and addresses. The list can be searched for a particular address or name, with an option to insert a new entry if no matching entry is found. Flag bits are used to indicate whether the host is a gateway, whether it was found in a system table like /etc/hosts.equiv, whether the worm has found it impossible to attack the host for some reason, and whether the host has already been successfully infected. The bits for "can't infect" and "infected" are cleared every 12 hours, and low priority hosts are deleted to be accumulated again later. The structure contains up to 12 names (aliases) and up to 6 distinct network addresses for each host.

In our sources, what we've called the muck structure is used to keep track of accounts for the purpose of password cracking. (It was awarded the name muck for sentimental reasons, although pw or acct might be more mnemonic.) Each structure contains an account name, an encrypted password a decrypted password (if available) plus the home directory and personal information fields from the password file.

4.3. Population growth

The worm contains a mechanism that seems to be designed to limit the number of copies of the worm running on a given system, but beyond that our current understanding of the design goals is itself limited. It clearly does not prevent a system from being overloaded, although it does appear to pace the infection so that early copies can go undetected. It has been suggested that a simulation of the worm's population control features might reveal more about its design, and we are interested writing such a simulation.

The worm uses a client-and-server technique to control the number of copies executing on the current machine. A routine checkother() is run at start-up time. This function tries to connect to a server listening at TCP port 23357. The connection attempt returns immediately if no server is present, but blocks if one is available and busy; a server worm periodically runs its server code during time-consuming operations so that the queue of connections does not grow large. After the client exchanges magic numbers with the server as a trivial form of authentication, the client and the server roll dice to see who gets to survive. If the exclusive-or of the respective low bits of the client's and the server's random numbers is 1, the server wins, otherwise the client wins. The loser sets a flag pleasequit that eventually allows it to exit at the bottom of the main loop. If at any time a problem occurs-a read from the server fails, or the wrong magic number is returned-the client worm returns from the function, becoming a worm that never acts as a server and hence does not engage in population control. Perhaps as a precaution against a cataleptic server, a test at the top of the function causes 1 in 7 worms to skip population control. Thus the worm finishes the population game in checkother() in one of three states: scheduled to die after some time, with pleasequit set; running as a server, with the possibility of losing the game later; and immortal, safe from the gamble of population control.

A complementary routine other_sleep() executes the server function. It is passed a time in seconds, and it uses the Berkeley select() system call to wait for that amount of time accepting connections from clients. On entry to the function, it tests to see whether it has a communications port with which to accept connections; if not, it simply sleeps for the specified amount of time and returns. Otherwise it loops on select(), decrementing its time remaining after serving a client until no more time is left and the function returns. When the server acquires a client, it performs the inverse of the client's protocol, eventually deciding whether to proceed or to quit. other_sleep() is called from many different places in the code, so that clients are not kept waiting too long.

Given the worm's elaborate scheme for controlling re-infection, what led it to reproduce so quickly on an individual machine that it could swamp it? One culprit is the 1 in 7 test in checkother(): worms that skip the client phase become immortal, and thus don't risk being eliminated by a roll of the dice. Another source of system loading is the problem that when a worm decides it has lost, it can still do a lot of work before it actually exits. The client routine isn't even run until the newly born worm has attempted to infect at least one remote host, and even if a worm loses the roll, it continues executing to the bottom of the main loop, and even then it won't exit unless it has gone through the main loop several times, limited by its progress in cracking passwords. Finally, new worms lose all of the history of infection that their parents had, so the children of a worm are constantly trying to re-infect the parent's host, as well as the other children's hosts. Put all of these factors together and it comes as no surprise that within an hour or two after infection, a machine may be entirely devoted to executing worms.

4.4. Locating new hosts to infect

One of the characteristics of the worm is that all of its attacks are active, never passive. A consequence of this is that the worm can't wait for a user to take it over to another machine like gum on a shoe - it must search out hosts on its own.

The worm has a very distinct list of priorities when hunting for hosts. Its favorite hosts are gateways; the hg() routine tries to infect each of the hosts it believes to be gateways. Only when all of the gateways are known to be infected or infection-proof does the worn go on to other hosts. hg() calls the rt_init() function to get a list of gateways; this list is derived by running the netstat network status program and parsing its output. The worm is careful to skip the loopback device and any local interfaces (in the event that the current host is a gateway); when it finishes, it randomizes the order of the list and adds the first 20 gateways to the host table to speed up the initial searches. It then tries each gateway in sequence until it finds a host that can be infected, or it runs out of hosts.

After taking care of gateways, the worm's next priority is hosts whose names were found in a scan of system files. At the start of password cracking, the files /etc/hosts.equiv (which contains names of hosts to which the local host grants user permissions without authentication) and /.rhosts (which contains names of hosts from which the local host permits remote privileged logins) are examined, as are all users' .forward files (which list hosts to which mail is forwarded from the current host). These hosts are flagged so that they can be scanned earlier than the rest. The hi() function is then responsible for attacking these hosts.

When the most profitable hosts have been used up, the worm starts looking for hosts that aren't recorded in files. The routine hl() checks local networks: it runs through the local host's addresses, masking off the host part and substituting a random value. ha() does the same job for remote hosts, checking alternate addresses of gateways. Special code handles the ARPAnet practice of putting the IMP number in the low host bits and the actual IMP port (representing the host) in the high host bits. The function that runs these random probes, which we named hack_netof(), seems to have a bug that prevents it from attacking hosts on local networks; this may be due to our own misunderstanding, of course, but in any case the check of hosts from system files should be sufficient to cover all or nearly all of the local hosts anyway.

Password cracking is another generator of host names, but since this is handled separately from the usual host attack scheme presented here, it will be discussed below with the other material on passwords.

4.5. Security holes

The first fact to face is that Unix was not developed with security, in any realistic sense, in mind...

This section discusses the TCP services used by the worm to penetrate systems. It's a touch unfair to use the quote above when the implementation of the services we're about to discuss was distributed by Berkeley rather than Bell Labs, but the sentiment is appropriate. For a long time the balance between security and convenience on Unix systems has been tilted in favor of convenience. As Brian Reid has said about the break-in at Stanford two years ago: "Programmer convenience is the antithesis of security, because it is going to become intruder convenience if the programmer's account is ever compromised." The lesson from that experience seems to have been forgotten by most people, but not by the author of the worm.

4.5.1. Rsh and rexec

These notes describe how the design of TCP/IP and the 4.2BSD implementation allow users on untrusted and possibly very distant hosts to masquerade as users on trusted hosts.

Rsh and rexec are network services which offer remote command interpreters. Rexec uses password authentication; rsh relies on a "privileged" originating port and permissions files. Two vulnerabilities are exploited by the worm-the likelihood that a remote machine that has an account for a local user will have the same password as the local account, allowing penetration through rexec, and the likelihood that such a remote account will include the local host in its rsh permissions files. Both of these vulnerabilities are really problems with laxness or convenience for users and system administrators rather than actual bugs, but they represent avenues for infection just like inadvertent security bugs.

The first use of rsh by the worm is fairly simple: it looks for a remote account with the same name as the one that is (unsuspectingly) running the worm on the local machine. This test is part of the standard menu of hacks conducted for each host; if it fails, the worm falls back upon finger, then sendmail. Many sites including Utah already were protected from this trivial attack by not providing remote shells for pseudo-users like daemon or nobody.

A more sophisticated use of these services is found in the password cracking routines. After a password is successfully guessed, the worm immediately tries to penetrate remote hosts associated with the broken account. It reads the user's .forward file (which contains an address to which mail is forwarded) and .rhosts file (which contains a list of hosts and optionally user names on those hosts which are granted permission to access the local machine with rsh bypassing the usual password authentication), trying these hostnames until it succeeds. Each target host is attacked in two ways. The worm first contacts the remote host's rexec server and sends it the account name found in the .forward or .rhosts files followed by the guessed password. If this fails, the worm connects to the local rexec server with the local account name and uses that to contact the target's rsh server. The remote rsh server will permit the connection provided the name of the local host appears in either the /etc/hosts.equiv file or the user's private .rhosts file.

Strengthening these network services is far more problematic than fixing finger and sendmail, unfortunately. Users don't like the inconvenience of typing their password when logging in on a trusted local host, and they don't want to remember different passwords for each of the many hosts they may have to deal with. Some of the solutions may be worse than the disease-for example, a user who is forced to deal with many passwords is more likely to write them down somewhere.

4.5.2. Finger

gets was removed from our [C library] a couple days ago.

Probably the neatest hack in the worm is its co-opting of the TCP finger service to gain entry to a system. Finger reports information about a user on a host, usually including things like the user's full name, where their office is, the number of their phone extension and so on. The Berkeley (3) version of the finger server is a really trivial program: it reads a request from the originating host, then runs the local finger program with the request as an argument and ships the output back. Unfortunately the finger server reads the remote request with gets(), a standard C library routine that dates from the dawn of time and which does not check for overflow of the server's 512 byte request buffer on the stack. The worm supplies the finger server with a request that is 536 bytes long; the bulk of the request is some VAX machine code that asks the system to execute the command interpreter sh and the extra 24 bytes represent just enough data to write over the server's stack frame for the main routine. When the main routine of the server exits, the calling function's program counter is supposed to be restored from the stack, but the worm wrote over this program counter with one that points to the VAX code in the request buffer. The program jumps to the worm's code and runs the command interpreter, which the worm uses to enter its bootstrap.

Not surprisingly, shortly after the worm was reported to use this feature of gets(), a number of people replaced all instances of gets() in system code with sensible code that checks the length of the buffer. Some even went so far as to remove gets() from the library, although the function is apparently mandated by the forthcoming ANSI C standard (4). So far no one has claimed to have exercised the finger server bug before the worm incident, but in May 1988, students at UC Santa Cruz apparently penetrated security using a different finger server with a similar bug. The system administrator at UCSC noticed that the Berkeley finger server had a similar bug and sent mail to Berkeley, but the seriousness of the problem was not appreciated at the time (Jim Haynes, private communication).

One final note: the worm is meticulous in some areas but not in others. From what we can tell, there was no Sun-3 version of the finger intrusion even though the Sun-3 server was just as vulnerable as the VAX one. Perhaps the author had VAX sources available but not Sun sources?

4.5.3. Sendmail

[T]he trap door resulted from two distinct 'features' that, although innocent by themselves, were deadly when combined (kind of like binary nerve gas).

The sendmail attack is perhaps the least preferred in the worm's arsenal, but in spite of that one site at Utah was subjected to nearly 150 sendmail attacks on Black Thursday. Sendmail is the program that provides the SMTP mail service on TCP networks for Berkeley UNIX systems. It uses a simple character-oriented protocol to accept mail from remote sites. One feature of sendmail is that it permits mail to be delivered to processes instead of mailbox files; this can be used with (say) the vacation program to notify senders that you are out of town and are temporarily unable to respond to their mail. Normally this feature is only available to recipients. Unfortunately a little loophole was accidentally created when a couple of earlier security bugs were being fixed-if sendmail is compiled with the DEBUG flag, and the sender at runtime asks that sendmail enter debug mode by sending the debug command, it permits senders to pass in a command sequence instead of a user name for a recipient. Alas, most versions of sendmail are compiled with DEBUG, including the one that Sun sends out in its binary distribution. The worm mimics a remote SMTP connection, feeding in /dev/null as the name of the sender and a carefully crafted string as the recipient. The string sets up a command that deletes the header of the message and passes the body to a command interpreter. The body contains a copy of the worm bootstrap source plus commands to compile and run it. After the worm finishes the protocol and closes the connection to sendmail, the bootstrap will be built on the remote host and the local worm waits for its connection so that it can complete the process of building a new worm.

Of course this is not the first time that an inadvertent loophole or "trap door" like this has been found in sendmail, and it may not be the last. In his Turing Award lecture, Ken Thompson said: "You can't trust code that you did not totally create yourself. (Especially code from companies that employ people like me.)" In fact, as Eric Allman says, "[Y]ou can't even trust code that you did totally create yourself." The basic problem of trusting system programs is not one that is easy to solve.

4.6. Infection

The worm uses two favorite routines when it decides that it wants to infect a host. One routine that we named infect() is used from host scanning routines like hg(). infect() first checks that it isn't infecting the local machine, an already infected machine or a machine previously attacked but not successfully infected; the "infected" and "immune" states are marked by flags on a host structure when attacks succeed or fail, respectively. The worm then makes sure that it can get an address for the target host, marking the host immune if it can't. Then comes a series of attacks: first by rsh from the account that the worm is running under, then through finger, then through sendmail. If infect() fails, it marks the host as immune.

The other infection routine is named hul() and it is run from the password cracking code after a password has been guessed. hul(), like infect(), makes sure that it's not re-infecting a host, then it checks for an address. If a potential remote user name is available from a .forward or .rhosts file, the worm checks it to make sure it is reasonable - it must contain no punctuation or control characters. If a remote user name is unavailable the worm uses the local user name. Once the worm has a user name and a password, it contacts the rexec server on the target host and tries to authenticate itself. If it can, it proceeds to the bootstrap phase; otherwise, it tries a slightly different approach-it connects to the local rexec server with the local user name and password, then uses this command interpreter to fire off a command interpreter on the target machine with rsh. This will succeed if the remote host says it trusts the local host in its /etc/hosts.equiv file, or the remote account says it trusts the local account in its .rhosts file. hul() ignores infect()'s "immune" flag and does not set this flag itself, since hul() may find success on a per-account basis that infect() can't achieve on a per-host basis.

Both infect() and hul() use a routine we call sendworm() to do their dirty work (5). sendworm() looks for the ll.c bootstrap source file in its objects list, then it uses the makemagic() routine to get a communication stream endpoint (a socket), a random network port number to rendezvous at, and a magic number for authentication. (There is an interesting side effect to makemagic() - it looks for a usable address for the target host by trying to connect to its TCP telnet port; this produces a characteristic log message from the telnet server.) If makemagic() was successful, the worm begins to send commands to the remote command interpreter that was started up by the immediately preceding attack. It changes its directory to an unprotected place (/usr/tmp), then it sends across the bootstrap source, using the UNIX stream editor sed to parse the input stream. The bootstrap source is compiled and run on the remote system, and the worm runs a routine named waithit() to wait for the remote bootstrap to call back on the selected port.

The bootstrap is quite simple. It is supplied the address of the originating host, a TCP port number and a magic number as arguments. When it starts, it unlinks itself so that it can't be detected in the filesystem, then it calls fork() to create a new process with the same image. The old process exits, permitting the originating worm to continue with its business. The bootstrap reads its arguments then zeroes them out to hide them from the system status program; then it is ready to connect over the network to the parent worm. When the connection is made, the bootstrap sends over the magic number, which the parent will check against its own copy. If the parent accepts the number (which is carefully rendered to be independent of host byte order), it will send over a series of filenames and files which the bootstrap writes to disk. If trouble occurs, the bootstrap removes all these files and exits. Eventually the transaction completes, and the bootstrap calls up a command interpreter to finish the job.

In the meantime, the parent in waithit() spends up to two minutes waiting for the bootstrap to call back; if the bootstrap fails to call back, or the authentication fails, the worm decides to give up and reports a failure. When a connection is successful, the worm ships all of its files across followed by an end-of-file indicator. It pauses four seconds to let a command interpreter start on the remote side, then it issues commands to create a new worm. For each relocatable object file in the list of files, the worm tries to build an executable object; typically each file contains code for a particular make of computer, and the builds will fail until the worm tries the proper computer type. If the parent worm finally gets an executable child worm built, it sets it loose with the -p option to kill the command interpreter, then shuts down the connection. The target host is marked "infected". If none of the objects produces a usable child worm, the parent removes the detritus and waithit() returns an error indication.

When a system is being swamped by worms, the /usr/tmp directory can fill with leftover files as a consequence of a bug in waithit(). If a worm compile takes more than 30 seconds, resynchronization code will report an error but waithit() will fail to remove the files it has created. On one of our machines, 13 MB of material representing 86 sets of files accumulated over 5.5 hours.

4.7. Password cracking

A password cracking algorithm seems like a slow and bulky item to put in a worm, but the worm makes this work by being persistent and efficient. The worm is aided by some unfortunate statistics about typical password choices. Here we discuss how the worm goes about choosing passwords to test and how the UNIX password encryption routine was modified.

4.7.1. Guessing passwords

For example, if the login name is "abc", then "abc", "cba", and "abcabc" are excellent candidates for passwords.

The worm's password guessing is driven by a little 4-state machine. The first state gathers password data, while the remaining states represent increasingly less likely sources of potential passwords. The central cracking routine is called cracksome(), and it contains a switch on each of the four states.

The routine that implements the first state we named crack_0(). This routine's job is to collect information about hosts and accounts. It is only run once; the information it gathers persists for the lifetime of the worm. Its implementation is straightforward: it reads the files /etc/hosts.equiv and /.rhosts for hosts to attack, then reads the password file looking for accounts. For each account, the worm saves the name, the encrypted password the home directory and the user information fields. As a quick preliminary check, it looks for a .forward file in each user's home directory and saves any host name it finds in that file, marking it like the previous ones.

We unimaginatively called the function for the next state crack_1(). crack_1() looks for trivially broken passwords. These are passwords which can be guessed merely on the basis of information already contained in the password file. Grampp and Morris report a survey of over 100 password files where between 8 and 30 percent of all passwords were guessed using just the literal account name and a couple of variations. The worm tries a little harder than this: it checks the null password, the account name, the account name concatenated with itself, the first name (extracted from the user information field, with the first letter mapped to lower case), the last name and the account name reversed. It runs through up to 50 accounts per call to cracksome(), saving its place in the list of accounts and advancing to the next state when it runs out of accounts to try.

The next state is handled by crack_2(). In this state the worm compares a list of favorite passwords, one password per call, with all of the encrypted passwords in the password file. The list contains 432 words, most of which are real English words or proper names; it seems likely that this list was generated by stealing password files and cracking them at leisure on the worm author's home machine. A global variable nextw is used to count the number of passwords tried, and it is this count (plus a loss in the population control game) that controls whether the worm exits at the end of the main loop - nextw must be greater than 10 before the worm can exit. Since the worm normally spends 2.5 minutes checking for clients over the course of the main loop and calls cracksome() twice in that period, it appears that the worm must make a minimum of 7 passes through the main loop, taking more than 15 minutes (6). It will take at least 9 hours for the worm to scan its built-in password list and proceed to the next state.

The last state is handled by crack_3(). It opens the UNIX online dictionary /usr/dict/words and goes through it one word at a time. If a word is capitalized, the worm tries a lower-case version as well. This search can essentially go on forever: it would take something like four weeks for the worm to finish a typical dictionary like ours.

When the worm selects a potential password, it passes it to a routine we called try_password(). This function calls the worm's special version of the UNIX password encryption function crypt() and compares the result with the target account's actual encrypted password. If they are equal, or if the password and guess are the null string (no password), the worm saves the cleartext password and proceeds to attack hosts that are connected to this account. A routine we called try_forward_and_rhosts() reads the user's .forward and .rhosts files, calling the previously described hul() function for each remote account it finds.

4.7.2. Faster password encryption

The use of encrypted passwords appears reasonably secure in the absence of serious attention of experts in the field.

Unfortunately some experts in the field have been giving serious attention to fast implementations of the UNIX password encryption algorithm. UNIX password authentication works without putting any readable version of the password onto the system, and indeed works without protecting the encrypted password against reading by users on the system. When a user types a password in the clear, the system encrypts it using the standard crypt() library routine, then compares it against a saved copy of the encrypted password. The encryption algorithm is meant to be basically impossible to invert, preventing the retrieval of passwords by examining only the encrypted text, and it is meant to be expensive to run, so that testing guesses will take a long time. The UNIX password encryption algorithm is based on the Federal Data Encryption Standard (DES). Currently no one knows how to invert this algorithm in a reasonable amount of time, and while fast DES encoding chips are available, the UNIX version of the algorithm is slightly perturbed so that it is impossible to use a standard DES chip to implement it.

Two problems have been mitigating against the UNIX implementation of DES. Computers are continually increasing in speed---current machines are typically several times faster than the machines that were available when the current password scheme was invented. At the same time, ways have been discovered to make software DES run faster. UNIX passwords are now far more susceptible to persistent guessing, particularly if the encrypted passwords are already known. The worm's version of the UNIX crypt() routine ran more than 9 times faster than the standard version when we tested it on our VAX 8600. While the standard crypt() takes 54 seconds to encrypt 271 passwords on our 8600 (the number of passwords actually contained in our password file), the worm's crypt() takes less than 6 seconds.

The worm's crypt() algorithm appears to be a compromise between time and space: the time needed to encrypt one password guess versus the substantial extra table space needed to squeeze performance out of the algorithm. Curiously, one performance improvement actually saves a little space. The traditional UNIX algorithm stores each bit of the password in a byte, while the worm's algorithm packs the bits into two 32-bit words. This permits the worm's algorithm to use bit-field and shift operations on the password data, which is immensely faster. Other speedups include unrolling loops, combining tables, precomputing shifts and masks, and eliminating redundant initial and final permutations when performing the 25 applications of modified DES that the password encryption algorithm uses. The biggest performance improvement comes as a result of combining permutations: the worm uses expanded arrays which are indexed by groups of bits rather than the single bits used by the standard algorithm. Matt Bishop's fast version of crypt() does all of these things and also precomputes even more functions, yielding twice the performance of the worm's algorithm but requiring nearly 200 KB of initialized data as opposed to the 6 KB used by the worm and the less than 2 KB used by the normal crypt().

How can system administrators defend against fast implementations of crypt()? One suggestion that has been introduced for foiling the bad guys is the idea of shadow password files. In this scheme, the encrypted passwords are hidden rather than public, forcing a cracker to either break a privileged account or use the host's CPU and (slow) encryption algorithm to attack, with the added danger that password test requests could be logged and password cracking discovered. The disadvantage of shadow password files is that if the bad guys somehow get around the protections for the file that contains the actual passwords, all of the passwords must be considered cracked and will need to be replaced. Another suggestion has been to replace the UNIX DES implementation with the fastest available implementation, but run it 1000 times or more instead of the 25 times used in the UNIX crypt() code. Unless the repeat count is somehow pegged to the fastest available CPU speed, this approach merely postpones the day of reckoning until the cracker finds a faster machine. It's interesting to note that Morris and Thompson measured the time to compute the old M-209 (non-DES) password encryption algorithm used in early versions of UNIX on the PDP-11/70 and found that a good implementation took only 1.25 milliseconds per encryption, which they deemed insufficient; currently the VAX 8600 using Matt Bishop's DES-based algorithm needs 11.5 milliseconds per encryption, and machines 10 times faster than the VAX 8600 at a cheaper price will be available soon (if they aren't already!).

5. Opinions

The act of breaking into a computer system has to have the same social stigma as breaking into a neighbor's house. It should not matter that the neighbor's door is unlocked.

[Creators of viruses are] stealing a car for the purpose of joyriding.

I don't propose to offer definitive statements on the morality of the worm's author, the ethics of publishing security information or the security needs of the UNIX computing community, since people better (and less) qualified than I are still copiously flaming on these topics in the various network newsgroups and mailing lists. For the sake of the mythical ordinary system administrator who might have been confused by all the information and misinformation, I will try to answer a few of the most relevant questions in a narrow but useful way.

Did the worm cause damage? The worm did not destroy files, intercept private mail, reveal passwords, corrupt databases or plant trojan horses. It did compete for CPU time with, and eventually overwhelm, ordinary user processes. It used up limited system resources such as the open file table and the process text table, causing user processes to fail for lack of same. It caused some machines to crash by operating them close to the limits of their capacity, exercising bugs that do not appear under normal loads. It forced administrators to perform one or more reboots to clear worms from the system, terminating user sessions and long-running jobs. It forced administrators to shut down network gateways, including gateways between important nation-wide research networks, in an effort to isolate the worm; this led to delays of up to several days in the exchange of electronic mail, causing some projects to miss deadlines and others to lose valuable research time. It made systems staff across the country drop their ongoing hacks and work 24-hour days trying to comer and kill worms. It caused members of management in at least one institution to become so frightened that they scrubbed all the disks at their facility that were online at the time of the infection, and limited reloading of files to data that was verifiably unmodified by a foreign agent. It caused bandwidth through gateways that were still running after the infection started to become substantially degraded the gateways were using much of their capacity just shipping the worm from one network to another. It penetrated user accounts and caused it to appear that a given user was disturbing a system when in fact they were not responsible. It's true that the worm could have been far more harmful that it actually turned out to be: in the last few weeks, several security bugs have come to light which the worm could have used to thoroughly destroy a system. Perhaps we should be grateful that we escaped incredibly awful consequences, and perhaps we should also be grateful that we have learned so much about the weaknesses in our systems' defenses, but I think we should share our gratefulness with someone other than the worm's author.

Was the worm malicious? Some people have suggested that the worm was an innocent experiment that got out of hand, and that it was never intended to spread so fast or so widely. We can find evidence in the worm to support and to contradict this hypothesis. There are a number of bugs in the worm that appear to be the result of hasty or careless programming. For example, in the worm's if init() routine, there is a call to the block zero function bzero() that incorrectly uses the block itself rather than the block's address as an argument. It's also possible that a bug was responsible for the ineffectiveness of the population control measures used by the worm. This could be seen as evidence that a development version of the worm "got loose" accidentally, and perhaps the author originally intended to test the final version under controlled conditions, in an environment from which it would not escape. On the other hand, there is considerable evidence that the worm was designed to reproduce quickly and spread itself over great distances. It can be argued that the population control hacks in the worm are anemic by design: they are a compromise between spreading the worm as quickly as possible and raising the load enough to be detected and defeated. A worm will exist for a substantial amount of time and will perform a substantial amount of work even if it loses the roll of the (imaginary) dice; moreover, 1 in 7 worms become immortal and can't be killed by dice rolls. There is ample evidence that the worm was designed to hamper efforts to stop it even after it was identified and captured. It certainly succeeded in this, since it took almost a day before the last mode of infection (the finger server) was identified, analyzed and reported widely; the worm was very successful in propagating itself during this time even on systems which had fixed the sendmail debug problem and had turned off rexec. Finally, there is evidence that the worm's author deliberately introduced the worm to a foreign site that was left open and welcome to casual outside users, rather ungraciously abusing this hospitality. He apparently further abused this trust by deleting a log file that might have revealed information that could link his home site with the infection. I think the innocence lies in the research community rather than with the worm's author.

Will publication of worm details further harm security? In a sense, the worm itself has solved that problem: it has published itself by sending copies to hundreds or thousands of machines around the world. Of course a bad guy who wants to use the worm's tricks would have to go through the same effort that we went through in order to understand the program, but then it only took us a week to completely decompile the program, so while it takes fortitude to hack the worm, it clearly is not greatly difficult for a decent programmer. One of the worm's most effective tricks was advertised when it entered - the bulk of the sendmail hack is visible in the log file, and a few minutes' work with the sources will reveal the rest of the trick. The worm's fast password algorithm could be useful to the bad guys, but at least two other faster implementations have been available for a year or more, so it isn't very secret, or even very original. Finally, the details of the worm have been well enough sketched out on various newsgroups and mailing lists that the principal hacks are common knowledge. I think it's more important that we understand what happened, so that we can make it less likely to happen again, than that we spend time in a futile effort to cover up the issue from everyone but the bad guys. Fixes for both source and binary distributions are widely available, and anyone who runs a system with these vulnerabilities needs to look into these fixes immediately, if they haven't done so already.

6. Conclusion

It has raised the public awareness to a considerable degree.

This quote is one of the understatements of the year. The worm story was on the front page of the New York Times and other newspapers for days. It was the subject of television and radio features. Even the Bloom County comic strip poked fun at it.

Our community has never before been in the limelight in this way, and judging by the response, it has scared us. I won't offer any fancy platitudes about how the experience is going to change us, but I will say that I think these issues have been ignored for much longer than was safe, and I feel that a better understanding of the crisis just past will help us cope better with the next one. Let's hope we're as lucky next time as we were this time.

Acknowledgments

No one is to blame for the inaccuracies herein except me, but there are plenty of people to thank for helping to decompile the worm and for helping to document the epidemic. Dave Pare and Chris Torek were at the center of the action during the late night session at Berkeley, and they had help and kibitzing from Keith Bostic, Phil Lapsley, Peter Yee, Jay Lepreau and a cast of thousands. Glenn Adams and Dave Siegel provided good information on the MIT AI Lab attack, while Steve Miller gave me details on Maryland, Jeff Forys on Utah, and Phil Lapsley, Peter Yee and Keith Bostic on Berkeley. Bill Cheswick sent me a couple of fun anecdotes from AT&T Bell Labs. Jim Haynes gave me the run-down on the security problems turned up by his busy little undergrads at UC Santa Cruz. Eric Allman, Keith Bostic, Bill Cheswick, Mike Hibler, Jay Lepreau, Chris Torek and Mike Zeleznik provided many useful review comments. Thank you all, and everyone else I forgot to mention.

Matt Bishop's paper "A Fast Version of the DES and a Password Encryption Algorithm", (c)1987 by Matt Bisbop and the Universities Space Research Association, was helpful in (slightly) parting the mysteries of DES for me. Anyone wishing to understand the worm's DES hacking had better look here first. The paper is available with Bishop's deszip distribution of software for fast DES encryption. The latter was produced while Bishop was with the Research Institute for Advanced Computer Science at NASA Ames Research Center; Bishop is now at Dartmouth College (bishop@bear.dartmouth.edu). He sent me a very helpful note on the worm's implementation of crypt() which I leaned on heavily when discussing the algorithm above.

The following documents were also referenced above for quotes or for other material:

Data Encryption Standard, FIPS PUB 46, National Bureau of Standards, Washington D.C., January 15,1977.

F. T. Grampp and R. H. Morris, "UNIX Operating System Security," in the AT&T Bell Laboratories Technical Journal, October 1984, Vol. 63, No. 8, Part 2, p. 1649.

John Markoff, "Author of computer 'virus' is son of U.S. Electronic Security Expert," p. 1 of the New York Times, November 5, 1988.

John Markoff, "A family's passion for computers, gone sour," p. 1 of the New York Times, November 11, 1988.

Robert Morris and Ken Thompson, "Password Security: A Case History," dated April 3, 1978, in the UNIX Programmer's Manual, in the Supplementary Documents or the System Manager's Manual, depending on where and when you got your manuals.

Robert T. Morris, "A Weakness in the 4.2BSD Unix TCP/IP Software," AT&T Bell Laboratories Computing Science Technical Report #117, February 25, 1985. This paper actually describes a way of spoofing TCP/IP so that an untrusted host can make use of the rsh server on any 4.2 BSD UNIX system, rather than an attack based on breaking into accounts on trusted hosts, which is what the worm uses.

Brian Reid, "Massive UNIX breakins at Stanford," RISKS-FORUM Digest, Vol. 3, Issue 56, September 16, 1986.

Dennis Ritchie "On the Security of UNIX," dated June 10,1977, in the same manual you found the Morris and Thompson paper in.

Ken Thompson, "Reflections on Trusting Trust," 1983 ACM Turing Award Lecture, in the Communications of the ACM, Vol. 27, No. 8, p. 761, August 1984.

Footnotes

(1): The Internet is a logical network made up of many physical networks, all running the IP class of network protocols.
(2): VAX and Sun-3 are models of computers built by Digital Equipment Corp. and Sun Microsystems Inc., respectively. UNIX is a Registered Bell of AT&T Trademark Laboratories.
(3): Actually, like much of the code in the Berkeley distribution, the finger server was contributed from elsewhere; in this case, it appears that MIT was the source.
(4): See for example Appendix B, section 1.4 of the second edition of The C Programming Language by Kernighan and Ritchie.
(5): One minor exception: the sendmail attack doesn't use sendworm() since it needs to handle the SMTP protocol in addition to the command interpreter interface, but the principle is the same.
(6): For those mindful of details: The first call to cracksome() is consumed reading system files. The worm must spend at least one call to cracksome0 in the second state attacking trivial passwords. This accounts for at least one pass through the main loop. In the third state, cracksome() tests one password from its list of favorites on each call; the worm will exit if it lost a roll of the dice and more than ten words have been checked, so this accounts for at least six loops, two words on each loop for five loops to reach 10 words, then another loop to pass that number. Altogether this amounts to a minimum of 7 loops. If all 7 loops took the maximum amount of time waiting for clients this would require a minimum of 17.5 minutes, but the 2-minute check can exit early if a client connects and the server loses the challenge, hence 15.5 minutes of waiting time plus runtime overhead is the minimum lifetime. In this period a worm will attack at least 8 hosts through the host infection routines, and will try about 18 passwords for each account, attacking more hosts if accounts are cracked.

TCL Wat

2026-02-25T09:00:00-06:00

I was talking about my TCL-writing days with a friend and they very helpfully pointed out that one of my claims here was backward and some of the examples could be clearer. I've corrected the inaccuracies and improved examples throughout. All these gotchas and examples are based on TCL 8.6, and I have no idea if later versions make changes.

At FlightAware, I read and write TCL every day. This means I've run into more than a few edge cases in the language, and have even tracked down a few bugs in TCLlib. Here's a collection of the weirdest things I've encountered.

Empty string is a boolean superposition

TCL's string is command can test whether a value is "true" or "false". Without the -strict flag, an empty string is simultaneously both:

string is true  ""  ;# => 1
string is false ""  ;# => 1

The empty string passes both checks. It is true. It is also false. It exists in boolean superposition.

With -strict, the empty string is instead neither true nor false:

set val ""
if {[string is true -strict $val]} {
    puts "This is true"
} elseif {[string is false -strict $val]} {
    puts "This is false"
} else {
    puts "This is neither true nor false"
}
# => This is neither true nor false

Dict set creates from nothing, chokes on something

The dict set command happily creates a dictionary if the variable doesn't exist yet:

dict set my_dict key value
# my_dict is now: key value

But if the variable already exists as a plain string, it fails with a confusing error:

set my_var "hello"
dict set my_var key value
# => missing value to go with key

The error message "missing value to go with key" makes it sound like you forgot an argument, but the real problem is that dict set tries to interpret "hello" as an existing dictionary, and since the string has an odd number of space-separated strings (in this case, one), it doesn't parse as key-value pairs.

Upvar and pass-by-name

TCL is pass-by-value by default. If you pass a variable to a function, the function gets a copy, and the caller's variable is unchanged. But upvar lets you opt into pass-by-name by passing a variable's name as a string and creating a local alias to the caller's variable:

proc increment {varName} {
    upvar $varName var
    incr var
}

proc swap {a b} {
    upvar $a aVar $b bVar
    set temp $aVar
    set aVar $bVar
    set bVar $temp
}

This is actually pretty useful once you get used to it, but it's definitely not what you'd expect coming from languages where you can't reach into your caller's scope by convention.

Insane string matching

Some TCL commands, like string is, allow matching on shortened or abbreviated strings. While this can lead to "concise" code, it may also introduce unintended and interesting bugs:

string is true true
# => 1
string is tru true
# => 1
string is tr true
# => 1
string is t true
# => 1
string is fa 0
# => 1

If a prefix is ambiguous, TCL at least throws an error: string is a "hello" gives ambiguous class "a": must be alnum, alpha, ascii, .... But unambiguous prefixes silently match, which has no practical benefit and serves only to create bugs. Why would a reasonable person ever want to check if a string "is tr" in production code?

Split nested list, get flat list

When using split on a nested list, the result is a list with members representing the escaped syntax of the nested list(s):

set a {aa bb {cc dd}}
split $a " "
# => {aa bb \{cc dd\}}

Notice that the braces of the nested list {cc dd} have been escaped, resulting in a string that looks like a dict, but is not. This is because under the hood, split operates on the string representation (in C, sort of), not the list structure. This has been the source of a number of real bugs at FlightAware.

Dict loops don't garbage-collect

When using dict with inside a loop, it sets local variables for each key in the current dictionary entry. But when the next iteration has fewer keys, the variables from the previous iteration aren't unset, they linger with their old values:

set data {
    item1 {var1 value1 var2 value2}
    item2 {var2 newvalue2}
}

foreach item {item1 item2} {
    dict with data $item {
        puts "Item: $item, var1: $var1, var2: $var2"
    }
}

Output:

Item: item1, var1: value1, var2: value2
Item: item2, var1: value1, var2: newvalue2

In the second iteration, item2 only defines var2. But var1 still holds value1 from the first iteration. If you're familiar with C, imagine a struct being partially overwritten without zeroing the rest. The variables created by dict with are not scoped to the loop body, and TCL doesn't clean them up between iterations. This has been a real source of bugs at FlightAware.

Comments are not comments

In TCL, # is not special syntax for comments, it's a command! A no-op command, but a command nonetheless. This means it only works in command-name position: the start of a line or after a semicolon.

# this works
set x 5 ;# this also works
set x 5 # this is NOT a comment
# => wrong # args: should be "set varName ?newValue?"

That last line fails because TCL sees #, this, is, etc. as extra arguments to set, not as a comment. The ;# idiom ends up very common in TCL programs precisely because you need the semicolon to start a new command before the # can act as one.

It gets worse. Since TCL counts braces before it interprets commands (which is reasonable since scope matters), an unbalanced brace inside a comment breaks the parser:

proc broken {} {
    # closing brace } here ends the proc body early
    puts "hello"
}
# => wrong # args: should be "proc name args body"

This is simply infuriating.

Uplevel is OP

The uplevel command executes a script in a caller's scope. This lets you build new control structures (essentially macros) but it also means any function can reach into its caller's environment and modify variables:

proc with_logging {body} {
    puts "--- begin ---"
    uplevel 1 $body
    puts "--- end ---"
}

set x 10
with_logging {
    set x [expr {$x * 2}]
    puts "x is now $x"
}
puts "x after: $x"
# => --- begin ---
# => x is now 20
# => --- end ---
# => x after: 20

The body passed to with_logging runs in the caller's scope, not inside the function. It reads and modifies the caller's x directly. This is how people build DSLs and custom control structures in TCL, and it's genuinely powerful, but it also means any function you call might be silently mutating your local variables.

Lack of static typing

TCL is a dynamically typed language, which means variables don't have a fixed type. A variable can change its type during runtime:

set my_var 42
puts "Variable type: [string is integer $my_var]"
# => Variable type: 1
set my_var "hello"
puts "Variable type: [string is integer $my_var]"
# => Variable type: 0

This can lead to flexibility in development, but may also cause unexpected behavior. Especially when dealing with JSON or other structured data formats. On the surface, this behavior is expected because "everything is a string". But it causes bugs when you understand TCL well enough to know that nothing is a string at the fundamental level.

Subst is not a separate compilation step

In TCL, the subst command is used to perform variable and command substitutions within strings. This can be handy in some situations, but it's important to note that subst is executed at runtime:

set x 10
set y "\$x + 5"
puts "Before substitution: $y"
# => Before substitution: $x + 5
puts "After substitution: [subst $y]"
# => After substitution: 10 + 5

This may be surprising if you're expecting TCL to act like a Lisp, and means that you might miss syntax errors until the code is actually executed. Worse, subst on user-provided input will execute any [command] substitutions embedded in that input.

Expr injection

Without braces, expr substitutes variables and commands before evaluating the expression. This means embedded [commands] in variable values get executed:

set x {[exec rm important_file]}
expr $x + 1   ;# executes rm!
expr {$x + 1} ;# safe, $x treated as data

The braced version treats $x as data within the expression parser, where it fails safely as a non-numeric value. The unbraced version does TCL substitution first, so the [exec ...] runs before expr ever sees it. TCL style guides consider unbraced expr a defect, but it's common enough in real code that this is one of the language's most dangerous foot-guns.

Two ways of catching errors

TCL provides error handling mechanisms via the catch, try, and error commands:

if {[catch {some_command} result]} {
    puts "Error encountered: $result"
}

try {
    some_command
} on error {errorMsg} {
    puts "Error encountered: $errorMsg"
}

The catch command can be used to capture any errors or exceptions that occur within a script. try and error offer more sophisticated error handling, but they're still not as clean as exceptions in other languages.

One particularly tricky aspect is that these error handling mechanisms will also set the errorCode global variable, which can be both useful and a curse to debugging. The global ::errorInfo variable (the stack trace) compounds this further because it persists from previous errors and can mislead you into debugging the wrong call site. When a TCL library function is the source of the error, these globals can leak error state between different parts of your code, making it hard to track down where errors are actually coming from. It's especially problematic when functions use error handling as a way of checking for dictionary key existence (*cough* json library).

Lower-case numbers

The string tolower command attempts to convert a string's characters to lowercase. When encountering mixed or non-alphabetic input, the results may be unexpected:

set number_string "42A_B8C"
string tolower $number_string
# => 42a_b8c

Even though the numbers remain the same, the non-alphabetic characters have been modified. This is technically correct behavior, but it's weird that you can "lowercase" a number. Then again, "everything is a string".

Incr creates variables

The incr command increments a variable. Even if the variable doesn't exist.

incr nonexistent
# nonexistent is now 1
incr another 5
# another is now 5

The same pattern applies to lappend, which creates an empty list if the variable doesn't exist. This is occasionally convenient, but it means a typo in a variable name silently creates a new counter instead of erroring. That makes for a frustrating prod bug.

So there you have it, a collection of TCL weirdness from my time working at FlightAware. Some of these are actually reasonable design decisions when you understand the philosophy behind TCL, but others are just... wat.

I successfully compiled the xmr-stak miner with CUDA

2018-02-04T09:00:00-06:00

I've been mining Monero for a while now, and I use xmr-stak on most of my machines (except the ones using ARM). Of course, my most powerful machine also happens to be my primary personal computer, so I've been pretty careful with it. I installed xmr-stak a handful of moons ago, and I remember struggling with it a bit. However, brilliant old me didn't bother to record how I actually got it to work, so it was a whole new adventure when I decided to update the software. So learning from my mistake, I'm recording what I did here so I can repeat it in the future. If a couple of other people find this and find it useful, all the better.

To start off, so you know you're not totally wasting your time, here's the specs I'm working with:

OS: Linux Mint 18.3 Sylvia
Kernel: x86_64 4.13.0-26-generic
CPU: Intel Core i7-4700MQ @ 3.4GHz x 4
GPU: NVidia GT 755M x 2

Now, the problems came down to CUDA. Obviously, with two GPUs, I don't want to only mine on the CPU (which was working fine). That's like getting onto a two-engine commercial jet and trying to takeoff with the exhaust from the auxillary power unit. Okay, that's a bit dramatic, I can still get around 200 H/s from my CPU. Anyway, part of the issue was compatibility between CUDA and my driver. When I started this ordeal, I was using CUDA 9.0 and it was working fine. However, I thought as long as I'm updating xmr-stak, why not update CUDA to 9.1? Well I also happen to be using driver 384.111, but 9.1 requires 385 or something. Of course, 9.1 offers to install the driver for you, but you have to be in runlevel 3, and I just didn't want to get into risky stuff like that on my main computer (not again, anyway). So I tried to go back to CUDA 9.0 and xmr-stak just refused to compile again and again. Here's a sampling of errors I continually ran into:

Could NOT find CUDA (missing:  CUDA_INCLUDE_DIRS) (found suitable version "9.0", minimum required is "7.5")

error: cuda_runtime.h: No such file or directory

Error generating
/xmr-stak/xmr-stak/build/CMakeFiles/xmrstak_cuda_backend.dir/xmrstak/backend/nvidia/nvcc_code/./xmrstak_cuda_backend_generated_cuda_core.cu.o

CMake Error at CMakeLists.txt:209 (message):
CUDA NOT found

How I got it to work

Long story short, here's everything I did to make it finally work:

sudo apt install cuda cuda-9-0 cuda-core-9-0 cuda-cublas-* cuda-cudart-* cuda-cufft-* cuda-documentation-9-0 cuda-runtime-9-0 cuda-nvgraph-* cuda-nvrtc-* cuda-gdb-src-9-0 --reinstall

git clone https://github.com/fireice-uk/xmr-stak.git

mkdir xmr-stak/build && cd xmr-stak/build

export CC=/usr/bin/gcc

export CXX=/usr/bin/g++

export CUDA_ROOT=/usr/local/cuda

cmake -DCMAKE_LINK_STATIC=ON -DXMR-STAK_COMPILE=generic -DCUDA_ENABLE=ON -DOpenCL_ENABLE=OFF -DMICROHTTPD_ENABLE=ON -DOpenSSL_ENABLE=ON ..

make install -j 4

For me, at least, this finally got it to compile and I can run it now! I often leave it mining while I'm sleeping or at work. The internal fans provide a nice white noise.

Note, if the GPUs fail to start mining through the software, try reducing the thread count on both before you start looking for other problems. I have mine set to 124 threads with 6 blocks on each GPU, which is lower than the defaults.

Profiles

To maximise the amount of mining I can do, I actually have three "profiles" ready to run on my computer. In case you're interested, here's some options.

All-out (CPU + GPU)

This is probably what you're going for and will get the most bang for your hardware. I compiled using the commands above (all those flags make a difference), and I'm using these two config files:

nvidia.txt

"gpu_threads_conf" :
  [
    // gpu: GeForce GT 755M architecture: 30
    //      memory: 1810/1991 MiB
    //      smx: 2
    { "index" : 0,
    "threads" : 124, "blocks" : 6,
    "bfactor" : 4, "bsleep" :  0,
    "affine_to_cpu" : false,
    },
    // gpu: GeForce GT 755M architecture: 30
    //      memory: 1972/1999 MiB
    //      smx: 2
    { "index" : 1,
    "threads" : 124, "blocks" : 6,
    "bfactor" : 4, "bsleep" :  0,
    "affine_to_cpu" : false,
    },
  ],

cpu.txt

"cpu_threads_conf" :
  [
    { "low_power_mode" : false, "no_prefetch" : true, "affine_to_cpu" : 0 },
    { "low_power_mode" : false, "no_prefetch" : true, "affine_to_cpu" : 1 },
    { "low_power_mode" : false, "no_prefetch" : true, "affine_to_cpu" : 2 },
    { "low_power_mode" : false, "no_prefetch" : true, "affine_to_cpu" : 3 },
  ],

On my system, this gets me around 600 H/s. Not bad, but low enough for me to start considering getting some old GPUs for my weakling Dell Vostro tower.

CPU-full

This profile is sans-GPU, if you ever want that. For this, I compiled without CUDA, using the normal install method but with this set of cmake flags:

cmake -DCMAKE_LINK_STATIC=ON -DXMR-STAK_COMPILE=generic -DCUDA_ENABLE=OFF -DOpenCL_ENABLE=OFF -DMICROHTTPD_ENABLE=ON -DOpenSSL_ENABLE=ON ..

Notice the -DCUDA_ENABLE=OFF which makes it CPU-only (on NVidia systems). Then this is my cpu.txt, same as for the all-out profile above:

"cpu_threads_conf" :
  [
    { "low_power_mode" : false, "no_prefetch" : true, "affine_to_cpu" : 0 },
    { "low_power_mode" : false, "no_prefetch" : true, "affine_to_cpu" : 1 },
    { "low_power_mode" : false, "no_prefetch" : true, "affine_to_cpu" : 2 },
    { "low_power_mode" : false, "no_prefetch" : true, "affine_to_cpu" : 3 },
  ],

Running this profile gets me around 200 H/s.

CPU-lite

Here's the one I really made the profiles for. I run this one in the background while I'm doing light or moderate regular computing. I'll often run this alongside a handy monerod --max-concurrency 1 to keep my local blockchain up to date.

Compile without CUDA as with CPU-full:

cmake -DCMAKE_LINK_STATIC=ON -DXMR-STAK_COMPILE=generic -DCUDA_ENABLE=OFF -DOpenCL_ENABLE=OFF -DMICROHTTPD_ENABLE=ON -DOpenSSL_ENABLE=ON ..

Notice the -DCUDA_ENABLE=OFF which makes it CPU-only (on NVidia systems). Here's the cpu.txt for the lite version:

"cpu_threads_conf" :
  [
    { "low_power_mode" : true, "no_prefetch" : false, "affine_to_cpu" : false },
    { "low_power_mode" : true, "no_prefetch" : false, "affine_to_cpu" : false },
  ],

Running this profile keeps me around 60-75 H/s and doesn't drain enough CPU power for me to notice most of the time. If you're using a pool that offers a separate port for low-end CPUs, I'd use that for this profile.