DEV Community: Jonathan Apodaca

Exposing Services from Your Devices and Making Them Accessible from Anywhere Using SSH

Jonathan Apodaca — Sun, 28 Feb 2021 05:32:31 +0000

Introduction and Goal

There are many use cases where you want to forward traffic from a Gateway server to some other computer. Perhaps one of the most famous examples of this are developer tools that "publish" local ports to publicly accessible endpoints (viz. Ngrok, localtunnel, etc). What many forget to mention, and thus what took me an embarrassingly long amount to time to rediscover, is that, for certain use cases, there already exists a tool built-in to UNIX that can do this out of the box (with one small configuration change on the Gateway server).

SSH: Background

While SSH is generally thought of as a way to log-in to a remote server and get a shell to execute commands, it also supports many, many more less-mentioned features. The one we are most interested in in the context of this post is port forwarding. SSH supports two modes of port forwarding: local (controlled with the -L switch), and remote (-R). Which one you use depends on which way you want traffic to flow:

local: forwards local traffic to the remote host over the SSH tunnel
remote: forwards remote traffic to the local host over the SSH tunnel

Local Port-Forwarding

In a contrived scenario where your friend has given you SSH access to a server on their LAN, and you want to log into their routers admin page, you can execute:

ssh -L 8081:192.168.1.1:80 theserveryouhaveaccessto.com

...and then you can open a browser on your local machine, point it at http://localhost:8081, and all traffic will be piped through the SSH tunnel to their router's admin page. (Hopefully your friend has changed the default password to their router to prevent any nefarious subsequent action...)

Remote port-forwarding.

Now let's make traffic flow in the opposite direction: let's say we have another contrived scenario where you are developing a website, and you access it at the local port 3000 (http://localhost:3000). Now say you want to show your same friend how the website is looking in your current stage of development. You have a problem: how do you "publish" your local port to a public place? Well, in this case we can execute:

ssh -R 3000:127.0.0.1:3000 theserveryouhaveaccessto.com

Now tell your friend to type this into the address bar of their preferred browser: http://theserveryouhaveaccessto.com:3000. Voiala! They will be able to access the web-server running on your local machine.

Setting up the Server

Since remote port forwarding is (potentially) undesired default behavior, you do have to make a configuration change to support it on the SSH server. Make sure you have this option enabled in /etc/sshd/config:

GatewayPorts yes

Restart sshd, and you're all set!

Now, all of this is well and good, except that it is a manual process to setup forwarded ports, and following a reboot of your computer, you have to remember a lengthy command to run in order to publish ports on your gateway. To complicate matters further, if your network connection between your machine and the gateway gets interrupted, you have to restart the command manually. Suppose you want to automate this process and remove the manual steps: how would one accomplish such a task?

I'm glad you asked...

AutoSSH

From autossh's man page:

autossh is a program to start a copy of ssh and monitor it, restarting it as necessary should it die or stop passing traffic.

This sounds perfect: it is exactly what we were looking for. In order to automatically start publishing ports to a gateway involves basically replacing ssh with autossh, plus a few extra switches.

Here is an example that I found to be "low-maintenance", yet may have debatably insecure practices. Use at your own risk.

autossh -N -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -R 22223:localhost:22 theserverihaveaccessto.com

Now all we have to do is get the command to run whenever the system powers on. There are a few ways to do this, depending on what OS you are running...

Linux: `systemd` Sample Unit File

If you are running systemd (Linux), this is the section that applies to you.

Put this in /etc/systemd/system/my-ssh-tunnel.service and enable with systemctl enable my-ssh-tunnel.service. Don't forget to start it after enabling it (systemctl start my-ssh-tunnel.service).

[Unit]
Description=my-ssh-tunnel
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=YOUR_USER_NAME_HERE
PIDFile=/tmp/my-ssh-tunnel.pid
Environment=AUTOSSH_PIDFILE=/tmp/my-ssh-tunnel.pid
Environment=AUTOSSH_DEBUG=1
ExecStart=/usr/bin/autossh -N -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -R 22223:localhost:22 theserverihaveaccessto.com
ExecStop=/usr/bin/pkill -F /tmp/my-ssh-tunnel.pid
Restart=always
RestartSec=60

[Install]
WantedBy=multi-user.target

MacOS: `launchd` Sample `plist`

MacOS does not come with systemd, but rather its own process manager called launchd.

<!-- put in /Library/LaunchDaemons/my-ssh-tunnel.plist -->
<!-- to enable it: launchctl load /Library/LaunchDaemons/my-ssh-tunnel.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>my-ssh-tunnel</string>
  <key>UserName</key>
  <string>YOUR_USER_NAME_HERE</string>
  <key>KeepAlive</key>
  <true/>
  <key>ThrottleInterval</key>
  <integer>30</integer>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/autossh</string>
    <string>-N</string>
    <string>-o</string>
    <string>UserKnownHostsFile=/dev/null</string>
    <string>-o</string>
    <string>StrictHostKeyChecking=no</string>
    <string>-R</string>
    <string>22222:localhost:22</string>
    <string>theserverihaveaccessto.com</string>
  </array>
</dict>
</plist>

Drawbacks

SSH is an extremely versatile tool, that supports more features than meets the eye upon first inspection. For a short time, I used the methodology described in this post to create my own poor-man's VPN: I exposed ports from several of my personal computers on a gateway so that I could access them from anywhere.

The major downside to this approach is that once a port is exposed on a gateway, anybody can access the service on that port. Please utilize this approach judiciously.

Further Research

In an upcoming post I will discuss how to easily set up a VPN amongst your personal devices so that you can access them from anywhere, without any tricky port mapping!

Things I Use

Jonathan Apodaca — Tue, 28 Jul 2020 20:49:19 +0000

If you have 3 developers in a room, and you ask them which tools they prefer, you will inevitably get at least 4 different opinions. One or two of them may vehemently defend one camp or another, while the others might hand-wave while muttering something about "the best tool for the job". Still another may rise on a pedestal and start preaching about Emacs.

Such is the landscape when it comes to the tools we all as developers use. Today, you get to hear my voice of opinion regarding the things I have come to rely on for my day-to-day work. As this will be a rather lengthy post, let's get right into it.

Goals

When choosing tooling and utilities, my goal is to make development as efficient as possible. In the past, I had other goals as well, such as building a system that supports music production: this is still important to me, but it is no longer something I spend a lot of time on, due to various reasons. In the end, then, I want to be able to "boot to development" as fast as possible.

Operating Systems

At the very moment when a developer sits down at their desk and starts their computer, lines have already been drawn. A side has already been chosen: what is your Operating System of preference? Speaking in very general terms, you can pretty much loosely divide Operating Systems into two families: UNIX, and Windows. The UNIX family of Operating Systems can be further divided into commercial variants (e.g., macOS, among others), and non-commercial variants.

In the past, I have done development work on Windows, but nowadays I prefer to develop exclusively on UNIX OSes. They say that "UNIX is an IDE", and that is definitely true. I typically have many dependencies on several tools to create an IDE experience on UNIX. Here are the different flavors I have come to enjoy:

macOS
Ubuntu Linux
Android

When it comes to an all-in-one, polished package, macOS is a very nice UNIX-variant. I thoroughly enjoy working on macOS, and that is my requested preference when working at a company if they are willing to provide a Mac as a workstation. However, I am unwilling to purchase Macs for my personal use, as I believe that their hardware is overpriced. Enter the other distributions that I listed above. At home, I run Ubuntu Linux on my Desktop (and yes, I do dual-boot Windows so that I can run certain programs). I have tried Arch in the past, but have come to realize that I prefer Debian-based Linux distros.

When on-the-go, I use Android. See the "mobile" section for more information on my setup there.

Terminal

For me, most of my interaction with my computer happens in the Terminal, and therefore I spend some time setting it up in ways that make my time spent there easier. Lately, my terminal emulator of choice has been kitty. Kitty has all of the features that I want in a terminal emulator: it is fast, can render ligatures, and is configurable via dotfiles. The close runner-up to Kitty is Alacritty, which can do all of that, except that, as of the time of this writing, it cannot render font ligatures (yet).

I wish I had time to write about each of these projects individually, but in the interest of time, I will leave a list here:

KiTTY
tmux
Fish
Dotfiles - YADM
JetBrains Mono Nerd Font
FZF
jq
lazygit
mkcert
rclone
supervisor - when developing a microservice-architecture locally, this tool is truely invaluable
watch

Text Editors

My text-editing journey has endured many changes, and over the years, I have tried pretty much everything out. The only editor I haven't fully dived into would be Emacs. Up until about a year ago, I was an avid fan of VSCode, for it blends the best of many editors. Having a built-in terminal, there was little not to love. I kept, however, hearing the tales of the absurd efficiency of VI, but could not relate to it, mostly due to an unguided learning experience with it that over 10 years ago at my university. I had forced myself to code a C++ project in ViM, and I learned enough to move around and get the project done. However, what I did not know was that I was only utilizing around 5% of the power of ViM.

This all changed recently when I bought a ViM course during one of Udemy's flash-sales. I was quickly sold when I realized that I had never used text objects beyond the verb "word" and that I could couple them with visual selection, among many other ViM actions. Today, I probably still utilize a mere fraction of ViM's power, but I am nonetheless much happier with the efficiency of text-editing in ViM on a day-to-day basis.

I have chosen NeoVim as the particular flavor that I prefer to use if not for the simple fact that the devs of NeoVim are attempting to bring ViM into the 21st century. I consider the following features to be game-changers:

Built-in LSP client (coming soon)
Scriptable with Lua - I believe VimL is an extremely archane language that is showing its age. While NeoVim will always have support for VimL, I believe Lua is the future to scripting ViM.
...and many more features!

macOS-specific utilities

Homebrew
Flycut
Karabiner Elements - needed by Capslock
Capslock - Make Capslock Great Again!
Rectangle
Espanso

Languages

Practically speaking, there are many ways a developer may dictate their intent to the computer being controlled. Over the years, many different languages have arisen with different paradigms that all accomplish different goals in slightly different manners. Here is a short list of languages and tools I reach for when solving a new problem. Although I am capable of using other languages and tools, these are the ones I utilize if the choice is mine:

Config/Data/Declarative
- YAML
- JSON
- TOML
Shell
- Fish
- Bash
Scripting
- JavaScript/TypeScript/NodeJS
UI - Web technologies + JSX
Rust

Miscellaneous Productivity

Mobile

On the go, it is convenient to be able to develop if I am in a pinch. I do not primarily develop on mobile, but there are tools I use to make it possible if an emergency arises.

Hardware

PC: 6-core...
Laptop: MacBook Pro
Keyboard: 65% Drop Alt (formerly an Anne Pro II)
Mouse: Logitech MX Master 2S
Headphones: Panasonic...

Things I have my eye on

Arch Linux

Embarking on the Quest of Building Your Own Mechanical Keyboard

Jonathan Apodaca — Sat, 23 May 2020 05:19:34 +0000

For way too long into my development career, I gave a disgraceful little thought to the equipment I used. No exception to this rule was paid to how I viewed and selected the keyboard that I would use as my main utensil. Recently, however, through a fortuitous chain of events, my path would finally cross with the world of mechanical keyboards, and I am forever ruined from using an OEM-keyboard as my daily driver.

Don't get me wrong: this journey is fraught with its own downsides. For one, the cost is significant. While one may hop on over to Best Buy and pick up a keyboard for the price of a decent 6-pack, one would be hard-pressed to get a good mechanical keyboard for under $50. Let alone when one begins to go down the road of the different customizations that can be applied to their existing hardware! Neglect to pay attention, and your pocket-book will be $300 lighter. However, for the patient, a great benefit waits at the end, and once greeted by its rewards, nearly impossible it becomes to return to former habits.

Why?

I was first introduced to the world of "superior" keyboards when I ran across a side-gig of Jeff Atwood's[1]: The Code Keyboard. The thought of a keyboard that was dedicated to the situation of my craft piqued my imagination. What then could be so enticing as to transcend the membrane keyboard I currently typed on at the time? I didn't previously know there were different types of switches for keyboards. Why? I suppose I just never really thought about it. I began reading that one could even customize their experience by choosing a specific switch, of which there existed at least 5 different choices[2].

I was just about sold, and proceeded to check out the store, that is until I saw the price-tag. At the time, $120 seemed a high premium for such a "frivolous" accessory. Then it seemed little more than a luxury. A mechanical keyboard could definitely not be a necessity.

Thought was hastily demoted to Aspiration: to be investigated at a later date, say, perhaps when the pocket-book was more willing to rise to the occasion.

Enter the 2018 MacBook Pro, which my boss bought me when I started a new job. Now there was a premium machine, in all her 6-core beastly speed. The honeymoon period was abruptly over, however, when the keyboard began to malfunction, and my text was increasingly littered with extraneous i's and u's. After a full day of coding, annoyance gave full birth to furry. Even that open-source debounce utility could not catch all of the double-key-presses. Now, Apple had issued a recall on the keyboard, but time could not be afforded. The machine would need to be admitted for a minimum of 3-days before the situation could be righted, and even at that, the procedure was a replacement with the same parts.

There were no two ways about it. Something had to be done. Amazon was cordially consulted, and her benevolence suggested a wireless solution. Something low-profile, say. Perhaps it would even fit atop the laptop's face-plate. Also, here is the perfect excuse you have been looking for to try out a mechanical keyboard.

Sold. It will be here in two days.

It was a dream for all of five minutes until I realized that whoever laid out the keyboard had placed the "?" to the right of the shift key. That purchase was quickly returned in favor of slightly more research.

I did finally end up with a keyboard that I liked. However, my sights were set high, and my new Aspiration was to build a fully custom mechanical keyboard.

Parameters - Many Dimensions

Alright, let's get down to the nitty-gritty details: just what are some of the benefits of mechanical keyboards? Let us reduce the whole world into a few attributes:

Size
Switches
Layout
Programmability

Keyboard Size

Keyboards come in many different sizes to accommodate many different use-cases, and they range from very small, to quite large! Sizes are typically rated in %-ages, e.g., "100%" / "65%" / "60%" / "40%" / etc. Loosely the percentage refers to how many keys are on the board. If you want to see some really tiny keyboards, just plug "40% keyboard" into Google, and enjoy the gallery.

The size that I prefer (for the moment) is 60%. This size seems to strike a good balance in that it is big enough that most keys are available without hitting too many "Fn" keys, and yet it is small enough that most keys are within reach without stretching my fingers too far. It also fits nicely in my backpack, atop my laptop, or cleanly on my desk leaving ample space for whatever else might live on my desk-related workspace.

Switches

Now here is where the customization begins to get fun. There being ample reading material on this topic already available, I will provide a short synopsis of the different types of switches here:

Linear
An even amount of pressure is required to actuate the key. Typically preferred by gamers.

Tactile
The key travels down, and activation coincides with a tactile "bump" the typist can "feel". This bump serves to involve the senses when typing quickly by providing queues to your brain about when keys have activated.

Clicky
Similar to tactile switches, a bump is present during actuation, along with an audible "click". This serves to involve not only the touch-sensation but also the typist's audio-sensory system to know precisely when keys have activated.

There are many, many different switches in each category, and there are even more categories than those presented here.

Layout

Mechanical layout is to be differentiated from "key mapping". The mechanical layout is the layout your eyes see when looking at the keyboard. "The rightmost key on the middle row is about so-wide". "There are keys in all four corners". That kind of stuff. That being said, withing a generalized layout, you are pretty much free to customize it as you see fit.

ANSI
This is the traditional layout you will find on most keyboards-- at least in the USA.

ISO
This layout has a double-row enter key, along with other differences.

JIS
Japanese layout

HHKB
This layout has fewer keys on the bottom row.

Ortholinear
Have you ever noticed that on pretty much every keyboard, the rows are staggered? Well, on an ortholinear keyboard, the keys are arranged in a grid. This has benefits like making many keys easier to reach, but you may need to re-train your brain to adjust!

Programmability

The programmability of custom keyboards is one of my favorite attributes. I like to make better use of my CapsLock key, but going about that through the usual OS-provided channels can be rather difficult on some operating systems. If the keyboard firmware itself lets you remap keys, then this is a cinch! Also, it's portable: I can plug my programmed keyboard into my Mac laptop, my Windows desktop, or my Linux desktop, and things just work.

Some keyboards have modes you can enter (via nefarious key combinations) that let you remap keys from the keyboard itself, others provide proprietary software, but by-and-large, my favorite keyboards are those that operate off of the open-source QMK firmware. The downside to QMK is that you may have to drop to a terminal compile your firmware when you want to remap keys. There is an online "configurator" that you can use, but QMK is definitely the least user-friendly of all these options. However, given its power, it is nonetheless my favorite option.

Also, if editing your keyboards C-code firmware sounds exciting, QMK offers that possibility to you as well. This is just really cool!

Parts

Initiating acquisition of the necessary parts you will need to build your keyboard is a matter of following a checklist. You will need:

Case - to contain all the other components in a presentable fashion
PCB ("Printed Circuit Board") - the electronic hub that connects all of the switches to a chip, exposing (usually) a USB interface. There are two major connector types: soldered, and "hot-swappable". Hot-swappable sockets hold the switches in by friction, allowing one to replace switches without going through the hassle of desoldering/re-soldering.
Plate - this is the part I most misunderstood: while the PCB has predefined holes that you will solder your switches to, each switch would have a little bit of wiggle-room if mounted to the PCB without a plate. The plate acts as a precise mount. It stands off of the PCB about 1/4", and each switch "clicks" into the plate, with their connector prongs sticking out below to connect to the PCB.
Switches - you have a lot of choices here! Some have an extra post (for extra stabilization) that a few PCBs do not have corresponding holes for: they can be easily clipped off with wire-cutters, so don't worry too much about that.
Stabilizers/Lubricant - stabilizers mechanically link the two sides of longer keys, so that when one extremity of the key is depressed, the whole switch depresses uniformly. You will want to lubricate the stabilizers for a smooth switch depression. I forgot to buy lubricant, and built my board without it: a decision I now regret, as now that the switches are soldered to the board, getting at the stabilizers would mean de-soldering every switch (they are under the plate)! I'm sure I can put some lubricant on a Q-tip and wiggle it between all of the pieces, but I really wish I had just done this right from the start.
Keycaps - just make sure the caps you buy are compatible with the switches. There are a variety of keycap profiles to choose from.
Supplies
- Soldering iron
- Solder: 60/40 lead-based is recommended
- Solder sucker: get a high-quality one: the chances that you have to de-solder a switch during your build depend on a lot of factors, but I was left wishing that I had a more powerful solder-sucker than the one that came with the soldering-kit that I bought.

Assembly

Once delivery of all the aforementioned parts have been made, the first thing you will want to do is test the PCB. If it is not working, you want to correct the situation before going any further! This turns out to be an elementary exercise: plug the PCB into your computer, open a "key-tester" (either online, or download), and, using tweezers, short the connectors where the switches will go, one at a time, checking that the corresponding switch is detected in the key-tester.

One more important task presented itself to me when I took inventory of all my parts: the PCB I purchased (the DZ60) supports multiple layouts, and upon settling on a given layout, I laid each keycap out with respect to my chosen layout in order to make certain that everything lined up. This saved me any guess-work that would come later, and also aided me in locating the exact pin-locations where each switch would go (the DZ60 sometimes has multiple closely-positioned "alternate" holes to support small variances in switch-position). Once I had that figured out, I was ready to start assembling the keyboard!

The first things that must be mounted to the PCB are the stabilizers. There is one good way to learn to assemble your stabilizers: watch a video. These usually clip to the board. Once they are in position, you are ready to start placing the switches.

The switches clip into the plate, with their pins protruding downward into the holes on the PCB. You will want to take care to line them up precisely, especially if the plate allows any variance in position. A few of mine ended up slightly crooked, and though someone else might notice, I wish I had spent even a slight bit more time on this. Start by clipping a few switches in each corner of the board, to give the build added stability, then add more switches. Solder incrementally, then add more switches, rinse and repeat. Occasionally plug the board in and key-test the switches that you recently have added, just to be certain you have no "duds".

Once your switches are soldered to the board, you can screw the PCB/plate to the case! There is nothing extra to mention here, and at this point, anticipation of the end of the project runs high!

You can now perform what is most likely the most routing chore thus far: press each key-cap onto the switches! Plug the board in, and key-test once more for good measure.

Flashing

Phew! If you thought that was a process, there is yet an extra mile you can go, depending on the capabilities of the PCB which you purchased. This is the part I love the most, and is, in my mind, one of the chief reasons for owning a customized keyboard: flash custom firmware to your keyboard!

The PCB which I purchased supports QMK firmware (highly recommended), and the process for customizing the firmware can either be the "simple-mode", or the more thorough route:

Use the QMK online configurator (UI)
Fork the QMK repo and follow their documentation for creating your custom firmware
... there is yet one more option: use a combination of 1 + 2: the QMK command-line tools allow one to use the UI to produce a JSON configuration file that may be converted to C-code (via the command qmk json2c ...). This is the option I used.

Conclusion

Daunting? Yes, yet extremely rewarding. This is a project that I would highly recommend, especially if you spend the majority of your time typing. The keyboard is a typists' most necessary utensil, and being specially crafted removes yet more of the barrier know as the "human-computer-interface".

Post-Script: My Parts List

PCB: DZ60 revision 3.0 with Cherry stabilizers（6.25Ux1 2U x4)

Plate: DZ60 CNC - Plate-A（left shift is 2U)

Case: 60% aluminum low profile case - Silver

Switches: Gateron RGB brown

Key-caps: R1 XDA Dye-sub 60%

Footnotes
[1] Jeff Atwood co-founded Stack Overflow
[2] There are, in reality, many more switch choices than 5

`git switch`/`git restore`

Jonathan Apodaca — Wed, 18 Dec 2019 14:20:01 +0000

Saw some cool new Git commands show up! What'y'all think?

Mislav Marohnić

@mislav

The `git checkout` command was confusingly named and too overloaded in functionality.
“How do I switch to a branch?” - checkout
“How do I restore a file to a previous version?” - checkout

Enter Git 2.23:
- `git switch <branch>`
- `git restore <file>`

github.com/git/git/blob/m…

14:00 PM - 17 Dec 2019

929 2580

I personally will be trying these out today as I work.

Why I am not switching to ZSH

Jonathan Apodaca — Thu, 11 Jul 2019 17:22:11 +0000

Recently Apple made a surprising announcement: due to licensing issues with Bash, they decided to change the default shell on macOS from Bash to ZSH. This change affects macOS Catalina and later. It is no secret that many developers enjoy a UNIX-like development experience from the comfort of a Mac, and it is thus no surprise that in the wake of Apple's announcement, my Twitter feed began to fill up with a lot of ZSH buzz.

A lot of people are jumping ship to ZSH.

Now, ZSH is certainly not new in the UNIX-shell space. I have been hearing about this shell for some years now, and why I should be switching to it. Heck, I even gave it a try in 2017. I spent ample time customizing it, and enjoying its superior interactivity, customizability, and completion experience. Ultimately, however, I switched back to Bash. Why, you may ask, did I downgrade from ZSH to Bash? There were numerous factors, but overall the big reason was that the extra wins that I gained in using ZSH over Bash were dwarfed by the fact that I was remoting into boxes at the time that had their default shells locked to Bash. Given that most of the boxes I was using already had Bash, and Bash could be customized nearly to the same level of ZSH using Bash-it, I decided to unify my experience and converge back to one shell everywhere: Bash.

So what is the problem, exactly? Don't get me wrong: I love ZSH, but in this case I just wanted to consolidate my efforts to customizing one shell. In the end, I had almost all of the things I originally had with ZSH, but this time everywhere with Bash-it. Score? 90% win. I'll take it!

Weighing The "Cost of Adoption"

You see, for most of us, we will continue to use Bash everyday, as long as we are on machines that have us locked to Bash shells. It is therefore safe to assume -- at least in my case -- that Bash is not leaving my life anytime soon. Therefore, it is worth me spending some amount of time customizing Bash to suite my needs. We could even pretend that there is a semi-mathematical way to view this:

CostOfAdopting(X) = CostOfMaintainingStatusQuo + CostOfCustomizing(X)

Do you see what the constant in that equation is? Yep: maintaining the status-quo. And what is the status quo in my case? Customizing Bash.

So, according to the above equation, for me to have incentive to adopt a new shell "X", it must have a low cost of customization.

Hmmm. I wonder what shell that sounds like.

Enter Fish Shell

Some time ago, I took the Fish Shell for a test drive, and promptly gave up when I realized it was not POSIX compliant. For many this is a big deal, especially in one case: sourcing other script files. While my daily workflow often still relies on being able to source a few script files, I have recently brought the Fish Shell back into my evaluation process. I am excited to report that I am now using the Fish Shell as my daily (personal) shell!

I have lead right into the "why", but I will state it anyway: Fish Shell has an extremely low cost of adoption in my case. Zero Config, is all the rage right now, and for good reason: in this age of ephemeral everything, it needs to be easy to go from 0-60 fast. Fish Shell is no exception! In its default state, it provides so many sane defaults:

syntax highlighting
a killer completion story
~~aliases~~ -- who needs 'em when you have abbreviations [1]?
a more sane and consistent language
killer documentation
seriously: funced/funcsave

Sure, I cannot have Fish everywhere, but it is so easy to work with, that I am willing to commit to using it as my daily driver on my development machines. Soon I hope to write more regarding my development setup, and the customizations I have been able to (easily) make to Fish.

In the meantime, during limited exposure to Fish, the following are my favorite addons:

[1] Fish abbreviations are similar in function to other shells' aliases, but they expand in place on the shell-edit-line, so you can see exactly what they are expanding to. In my humble opinion, this is great because it removes the "magic" of aliases: especially if another developer is looking over your shoulder: no longer do you need to explain that gc is short for git commit.

Which do you prefer?: DSL or a well-designed Library?

Jonathan Apodaca — Tue, 02 Apr 2019 14:26:15 +0000

Lately, I am preferring libraries over DSLs more and more. As I have ventured into learning Rust, it seems that all too many Crate authors abuse the (otherwise awesome) macro-system to create their own DSL. If more library-developers spent their time on designing a well-put-together API, then I would have the benefit of everything else my IDE supports:

Syntax I am familiar with: nothing else to learn besides the API surface
Autocomplete for discovery! (instead of switching between a Docs page and my text-editor)
Inline documentation, if methods were documented
etc.

The epitome of this philosophy would be RethinkDB's query language, which is actually an API, and not its own query language!

What do you all prefer?

Creating an Alerting Callback Plugin in Ansible - Part I

Jonathan Apodaca — Fri, 03 Aug 2018 21:55:39 +0000

Recently my department has been adopting Ansible into more of our workflows. I like it so much that I converted my dotfiles repo over to use Ansible. Notwithstanding our intrepid exhilaration at having so much more of our workflow inducted into an automated process, we recently were made privy to the fact that our visibility into what Ansible is actually doing to our infrastructure is less than perfect.

Rewind to Monday morning, when I started receiving email complaints that one of our batch jobs had failed to complete. After pouring over a monolithic log file, I discovered that the issue was that the user attempting to execute one of our scripts did not have directory-execute permissions on one of the parent directories that our script resided in. It was a simple fix: chmod .... The job was released and ran to completion. Still, I wondered what had happened to change the directory permissions, especially since I knew that neither I, nor others, had been making any modifications to that particular system.

Sure enough, after reaching out to our sysadmins, it was confirmed that a playbook had been run with the aforementioned undesired outcome. No biggie: within 15 minutes the problematic playbook had been remedied.

Crisis averted. Conflict resolved. However, I began to go over in my mind how we might avoid this situation in the future, and it gave me an idea: We (conveniently) have our host inventory separated into groups by teams. Wouldn't it be convenient if there was a plugin that could, when a host had been changed, lookup variables on that host to see if any "alerting configuration" had been set, and alert the appropriate stakeholders for a given system?

Proposed Solution

Let's start with my desired solution and work backward. Say I have the following inventory:

[webteam]
webteam1.tld
webteam2.tld

[systeam]
systeam1.tld
systeam2.tld

I would like to manage who I want to alert, upon a system change, via group_vars:

group_vars/webteam.yml:

notify_on_change:
  email:
    - somebody1@domain.tld
    - somebody2@domain.tld
  slack:
    ...slack config...

Fantastic. But Ansible does not come with such functionality out-of-the-box. But wait a minute! It turns out that developing a plugin is relatively painless. It turns out that what I want to develop is called a "callback plugin". A callback plugin is a Python class that gets called during different phases of Ansible's lifecycle. The shortest callback plugin we could write would be the following:

from ansible.plugins.callback import CallbackBase

class CallbackModule(CallbackBase):
  CALLBACK_VERSION = 2.0
  CALLBACK_TYPE = 'aggregate'
  CALLBACK_NAME = 'custom'

This callback plugin will not do anything, but there are a few takeaways to note already: this callback plugin is advertising that:

it wishes to consume the v2 API
its type is aggregate: a callback plugin's type is important. More specifically, what type a callback plugin is not is even more important, as only one callback plugin of type stdout can be enabled at once.
its name is custom. We will refer to the callback plugin later by this name. As far as I know, the filename (e.g., whatever.py) is not used to refer to the callback plugin

As previously stated, multiple callbacks can be active at once, but only one callback plugin of type stdout can be active at once. So how do we enable a callback plugin? Easy, jump into your friendly ansible.cfg, and set the following config:

[defaults]
# ...
# comma separate callback plugins to whitelist:
callback_whitelist = custom

This will instruct Ansible to enable the callback plugin that we have defined. But where do these callback plugins go? Once again, Ansible has an easy answer to this: in the callback_plugins/ directory, either 1) within one of the roles you include, or 2) adjacent to your playbook(s). So far, a possible directory structure could look like the following:

my-playbook-folder/
  callback_plugins/
    my-callback-plugin.py
  ansible.cfg
  playbook.yml

Building the Callback Plugin

Alright, so what exactly should our plugin do? To keep things simple, we will specify the behavior of our plugin to do the following:

Use Slack as a notification service
Do not send a notification unless a Task reports that it "changed" the target system
If a change occurred, lookup the stakeholders for a given system using the particular hosts host-/group- vars.

This is where things start to get slightly hairy: in order to inspect the state of the Play(s) and Task(s), we will be digging into Ansible internals. Thankfully, there exists a great community to support you in this endeavor, but let us start by mentioning that all the methods that your callback plugin can override can be found in in the CallbackBase class. After a bit of digging around, and a little waiting for an answer on a StackOverflow question, I settled on the following base code:

from ansible.plugins.callback import CallbackBase

class CallbackModule(CallbackBase):
  CALLBACK_VERSION = 2.0
  CALLBACK_TYPE = 'aggregate'
  CALLBACK_NAME = 'is'

  def v2_playbook_on_play_start(self, play):
    self.vm = play.get_variable_manager()

  def v2_runner_on_ok(self, result):
    if self.vm.get_vars()['ansible_check_mode']:
      return

    host_vars = self.vm.get_vars()['hostvars'][result._host.name]
    if 'notify_on_change' in host_vars and result.is_changed():
      pass
      # TODO: Post Slack message

WARNING: I do NOT know Ansible internals and have found the above code to "work" after a lot of trial and error. My impression is that host and group vars are instantiated and merged on a per-play basis. That is why the variable manager is captured "on play start" and stored for later use. Later, when a task finishes, we use the variable manager to check 1) whether Ansible is running in --check-mode, and then later to retrieve the specific host's notify_on_change configuration.

A Bit of Debugging Strategy

So this is the part of the article where I get irrationally angry that Python does not support type-annotations. If it did, I might be able to engage in rapid discovery surrounding exactly what I could pull out of the parameters being passed to my callback plugin's hooks. Who knows, I might even be able to use IDE hints like IntelliSense or Content Assist to quickly retrieve what I need.

If you could see me at this moment, my face red with rage, sweat dripping down my neck, you might notice that I am calming down and reminding myself of the merits of scripting languages. In fact, one of my favorite rapid-development-tools is Node.JS. At this point, I set my bias aside and trudge on. Time to pull out some debugging-fu.

After a little poking around, there is a one-line technique you can use to suspend any Python program and invoke an interactive debugger:

import pdb; pdb.set_trace()

Fantastic! I can now drop this into my plugin at a point where I would like to inspect vars and iterate (very slowly) until I get some code that works.

For example:

class CallbackModule(CallbackBase):
  # ...
  def v2_runner_on_ok(self, result):
    import pdb; pdb.set_trace()
    # ... same code as before
  # ...

Now, if I invoke Ansible like normal, it will run until it calls my v2_runner_on_ok method, and it will immediately suspend, dropping me into a request-evaluate-print-loop (REPL) where I can interactively step through my code and inspect variables in my scope!

That's All For Now

I'm going to end this article here, as it is already turning out longer than I had planned. Even if it was not for that, I would still have to end it, as that is all I have implemented at this point. Hopefully I will finish my callback plugin soon (or one of you will beat me to it), and I will share my findings and code in a "Part II".

What I Learned this Week (March 30, 2018)

Jonathan Apodaca — Fri, 30 Mar 2018 20:48:06 +0000

Directed Graphs: Connected Components

I started researching algorithms for finding Connected Components in a Directed Graph, for the purpose of being able to more efficiently add visibility into large dependency graphs (particularly in a database; e.g., job J uses table T to produce T'...). This information could be used to develop more time-efficient schedules that produce data at my institution. Having an idea how I would find "islands" in our dependency graph, I decided to research it and try to learn something about Graph Theory.

Further reading for me: Strongly Connected Components is a method to determine areas in a graph that are more strongly connected than others. This seems pretty cool. I wish I had a practical use for it!

Relearn: DAG: Topological Sort

Regarding the above problem, I implemented a topological sort of our dependency graph to find all of the jobs that can run in parallel to make our scheduling more efficient. Finally: I used something from a class in my job! It is always satisfying using something that used to be homework.

libclang

Apparently, you can leverage C frontend built for LLVM via the libclang library. See this post for more details. Utilizing this, you can parse C++, traverse the AST--Great stuff.

There are even nodejs bindings.

RPython

If you are wanting to produce a VM that supports interpreting and a Just-in-Time compilation, RPython is pretty amazing. This article is a very interesting read.

TLDR; RPython is a VM generator: it consists of a language (a subset of Python) and a tool that analyzes (interpreter code + hints) and produces a (C-based) VM (interpreter + JIT) for you.

Shibboleth

Recently I was brought on as a resource on a project in my department that requires integration with the Single Sign-On service Shibboleth. Fun-fact: Shibboleth is mentioned in the Bible (Judges 12:6) as a way that the ancient Israelites enforced border-control during a time of hostility amongst their own clans.

Shibboleth as a product is highly configurable, and a semi-complex beast. While I have previous experience with setting it up, it seems there is always something else to learn about it. Most of my learning on this front has been spent in frustration whilst attempting to make it work in an equally complex, load-balanced environment.

What I Learned this Week (March 23, 2018)

Jonathan Apodaca — Mon, 26 Mar 2018 16:48:20 +0000

This week's list will be a bit shorter, as I was caught up in a lot of administrative tasks this week.

Docker: Service vs. Stack

When using Docker in Swarm Mode, a stack describes multiple "services" to run in your cluster. As docker-compose is to docker run, so is a Docker stack to a Docker service. Incidentally, stacks are also described in a very similar manner via YML as you would in a docker-compose.yml file.

A Docker service is a collection of homogeneous containers, that is, with the same image:tag. Docker Swarm will replicate the service across multiple nodes according to the rules you set.

What I Learned This Week (March 16, 2018)

Jonathan Apodaca — Fri, 16 Mar 2018 17:12:31 +0000

One of the things I value highly where I work is that, each week, our Director emails out a "What I Learned This Week". It got me thinking that a good way for me to reflect on what I have learned would be for me to publish the same thing each Friday.

So without further delay, I present to you the things that I learned this week:

Common Themes

We recently started our DevOps committee where I work, and we have been discussing what our current direction will be for the next six months. With that in mind, I have personally been reviewing the following technologies for possible recommendation as things we can look into:

Kubernetes via Minikube

Last time I looked into learning Kubernetes (affectionately abbreviated as k8s by the community), it was prohibitively difficult to get into and learn due to having to spin up a small cluster sandbox merely to experiment with. Imagine my excitement at learning that a tool, minikube, exists that allows you to play with Kubernetes locally on your development machine! Seriously, go install it and start playing with Kubernetes.

HashiCorp

HashiCorp is famous for developing the amazing tool, Vagrant. Well, it turns out that they have a ton of other awesome projects:

Terraform - represent your infrastructure as code
Nomad - a deployment tool that is awesome
Vault - secret management tool

The major win with these tools is they are modular and modularly adopt-able. That is also their weakness, however: there is more to set up in order to play with them.

Ansible

This week I also rediscovered Ansible. By rediscovered, I mean I delved more into how it works and fell in love with it all over again. We are already using this tool at my job, but up until now, it has mostly had major wins on our Systems Support team. This week, it finally "clicked" how Ansible configuration works, and it is now no longer such a (great) mystery. I will definitely be integrating this into more of my workflows more often.

Conclusions

I am just going to keep these short and sweet, so that's all folks!

Pratt Parsing

Jonathan Apodaca — Fri, 11 Aug 2017 21:35:45 +0000

Ever since I started programming, I have tried to come up with interesting projects for myself, even if they are purely for educational purposes. The joy of programming is the goal sometimes. Couple with that an opportunity to learn a new concept and you have got my attention! Some of my first projects were about as simple as they get:

When wanting to learn Java Swing, I created a number guessing game. ("I'm thinking of a number between 1 and 10...you have 10 tries to guess it"...)
When wanting to learn how to interact with XML, I created a simple "Mail" program in .NET that I used to communicate with my siblings, storing each mailbox in a flat XML file (eesh, not a very robust DB store)

That was a while ago. Since then, I would hope that my skills have improved and that I have been able to solve the problems since then with more elegance and maturity.

However, there has always been one project that I could never finish: writing a calculator. I never was good at parsing text. Funny thing is, now that I look back on my methodologies, in hindsight I can acknowledge that I was on the right track in some respects, and way off base with others. The truth is, it takes some forethought when creating a calculator. This post will document where I currently am at in my understanding of how to tackle this seemingly simple task. I do not claim to have arrived at an expert understanding.

The Problem

Let us start with the end goal and work backward from there. In the end, I want to produce a program--let it go under the moniker calc-- that I can invoke like:

$ calc
Welcome to Calculator 1.0
Please enter an expression on the following line:
> 1 + 2 * -3 + 2^+3^2
=> The answer is 507
> 1 + 2 * (-3 + 2^+3^2)
=> The answer is 1019

Hmm, let us try and draw some specifications out of this theoretical demo:

We need to support things like:

operator precedence
right associativity (1^2^3 means 1^(2^3), not (1^2)^3)
some operators are both infix and unary
- in the expression 1 - 2, the - is an infix operator
- in the expression -2, the - is a unary operator
use of parenthesis can override operator precedence

Back when I first tried to tackle this problem, #4 seemed to be the easiest bullet to tackle. When I first attempted to code this program, I had a first pass that would find groups of parenthesis (by finding matching parenthesis), and pull those groups out into what started to look like an abstract syntax tree. But in the end, that was as far as I got before I had to abandon the project for my number-guessing game.

Work, dang-it

Shortly after I realized that the problem of operator precedence parsing was not as trivial as I had assumed, I found the splendid tool called ANTLR. ANTLR is a parser-generator that takes a grammar as input, and produces code that parses the text that conforms to the grammer into an abstract syntax tree. This means you can write a grammar such as:

NUM: '\d+';
e:
    NUM
  | '-' e
  | e '^' e <assoc=right>
  | e '*' e
  | e '/' e
  | e '+' e
  | e '-' e
  ;

ANTLR can use a grammar akin to this to produce a parser for you. This parser will take input text, say 1 + 2 * 3, and produce an abstract syntax tree like the following:

  +
 / \
1   *
   / \
  2   3

Notice that this tree follows the precedence rules that you define in your grammar.

Yay! Creating a parser was pretty easy after all! Well-- until your curiosity gets the better of you and you wonder how in the heck this amazing thing called a parser generator works. Also, try not to look at the generated parser code: it gets--gnarly.

At the end of the day I heard how more and more languages are using hand-coded recursive decent parsers, and I got curious. How would I code that calculator app with code that I wrote 100% myself?

Meet my friend, Vaughan Pratt

Well, he is not actually my friend, but I cannot help but think of him on friendly terms after learning his strategy for top-down-operator-precedence parsing. At a high level, Pratt parsing works by scanning the input tokens, and classifying them into two categories:

operators that operate to the right, with no left-context
- An example of this would be unary minus -1
- Pratt calls the specification of how an operator consumes to the right with no left-context its "Null-Denotation", or "NUD" for short
- For example, nud('-') could produce an AST node Negative(operand=...)
operators that operate from left-to-right, on two operands
- This is any simple infix operator; for example: 1 + 2
- Pratt calls the specification of how an operator consumes to the right with a left-context its "Left-Denotation", or "LED" for short
- For example, led(left, '-') could produce an AST node Subtraction(left=left, right=...)

Notice that in this case we are scanning left-to-right. What this means is we are forming the AST as we are scanning the input. For example, let us Pratt-parse the string 1 + 2 + 3:

We start at our first token, and note how we cannot see the rest (here denoted with underscores "_"):

1 _ _ _ _

When we first start out, we have no left-context, so we take the NUD of the first token: NUD(1). In this simple case, the NUD of a number is the number itself, so the 1 remains a 1. Let us move on and look at the next token:

1 + _ _ _

This time around, we have a left-context (which is 1), so we will take LED(1, '+'). For now, let us say that all LED needs to do is consume the next number and return the subtree so far. In this case, LED will produce:

  + _ _
 / \
1   2

This subtree is our new "left". We will then pop the next operator:

  + + _
 / \
1   2

Okay, the operator is "+", and we have a left-context (our subtree), so we take LED(left, '+') again:

We are now at the end of our input, and so parsing stops and we have our abstract syntax tree! We could pseudo-code-ize our process so far:

function expr() {
    let left = nud(next())
    while (!eof)
        left = led(left, next())
    return left
}

So far, so good.

Precedence though...

Okay we have a problem. If we execute our pseudo-code on the string 1 + 2 * 3, we will get the following abstract syntax tree:

This is not correct: it would evaluate the "+" before the "*", so we have a problem. What we need is some way to encode operator precedence. In fact, the problem lies when we are here with the parsing:


1 + _ _ _

We do not know that a multiplication is coming up and that we need to parse the 2 * 3 as its own expression.

Hmm, there were some key words in there that we should pay attention to: we need to parse the 2 * 3 as its own expression. What this implies is that our expr() function needs to be called recursively. Currently, we have defined LED like so:

LED(left, operator) = Tree(left, operator, right=next())

What if it were more like this?:

LED(left, operator) = Tree(left, operator, right=expr())
                                                 ^^^^

However, when we want the LED of an operator, we do not want to call expr() and consume the rest of the input. We will want it to stop at some point. For example, say we are parsing the string 1 * 2 - 3 and we are at this point in the parsing process:

1 * _ _ _

In this case, we only want expr() to parse the next number, not the entire expression 2 - 3. We need a way to signal expr() when to stop.

But what is the pattern for when we want to stop/run? I will give you a clue: it has to do with the operator precedence...

Power in precedence

It turns out that as humans, we can pick out operator precedence pretty intuitively. We look at an expression such as 1 + 2 * 3, and we know that the * in this expression binds with the 2 and 3. The plus binds with the 1 and the sub-expression. Let us give that a name. Let us give each operator a binding power. In this case, * has a greater binding power than +. In fact, let us put some numbers to this so-called binding power:

+ - 10
* - 20

In fact, these numbers are arbitrary. What is important is that the binding power for * is greater than the binding power for +. But how does this help us? Well, when we are parsing an expression at a specific binding power, we need to stop when we encounter a binding power less than the one we are currently parsing for. In other words, when we encounter lower binding powers, we bail and call it quits.

Let us put this verbiage into our pseudo-code (rbp stands for "right binding power"):

function expr(rbp = 0) {
    let left = nud(next())
    while (bp(peek()) > rbp)
        left = led(left, next())
    return left
}

This is actually our final version of expr(). This is what a Pratt parser is based around. In the end, what we have to provide are all the binding powers, and define NUD/LED for each operator.

What this means is that we need to redefine LED from above. Whereas it was previously:

LED(left, operator) = Tree(left, operator, right=expr())

It now needs to be:

LED(left, operator) = Tree(left, operator, right=expr(bp(operator)))
                                                      ^^

Let us follow how this works through and example. Let us parse 1 * 2 + 3:

// call expr(rbp = 0)
1 _ _ _ _
// take NUD(1)
1 * _ _ _
// take LED(1, '*') = Tree(1, '*', right=expr(bp('*')))
//                  = Tree(1, '*', right=expr(20))
  * _ _ _
 / \
1   expr(20)


// start recursion: expr(20)
// take NUD(2)
2 + _
// 20 < bp('+') ?
// nope, return left so far (2)

// resume previous recursion
  * + _
 / \
1   2
// 0 (current rbp) < bp('+')?
// yes! continue parsing...
// take LED(left, '+') = Tree(left, '+', right=expr(bp('+')))
//                     = Tree(left, '+', right=expr(10))
    +
   / \
  *   expr(10)
 / \
1   2

// start recursion: expr(10)
// abbreviated: will return 3

// resume previous recursion
    +
   / \
  *   3
 / \
1   2

Hopefully, that was not too hard to follow. My mind bends every time I follow this process through to completion. But we are done! Note how operator precedence is correctly preserved in the produced abstract syntax tree.

Not to be pedantic, but how do you handle right associativity?

This turns out to be almost too easy. Let us say we want our exponentiation operator to be right associative (as it should). If we implement LED(left, '^') as we have implemented our other infix operators, for example:

LED(left, '^') = Tree(left, '^', expr(bp('^')))

Then the right binding power will kick us out when we hit an operator of lesser (or equal!) binding power, including our own, meaning that we will parse 1^2^3 as:

However, if we tweak our definition of LED to be:

LED(left, '^') = Tree(left, '^', expr(bp('^') - 1))
                                              ^^^

Now the right binding power passed into expr(...) will be less than the binding power of '^'. This will produce the correct tree:

Wait, right associativity was that easy??

Conclusions

Pratt parsers are awesome, and once you understand what is going on under the hood, they are really simple. As it turns out, one of my side-projects right now is a parser that parses JavaScript. With Pratt parsing, even parsing JSX is not too bad. If you would like to see my Pratt-parser-calculator that I finished (finally, after all these years), then hop on over to the project's GitHub. Thanks for reading!

DEV Community: Jonathan Apodaca

Exposing Services from Your Devices and Making Them Accessible from Anywhere Using SSH

Introduction and Goal

SSH: Background

Local Port-Forwarding

Remote port-forwarding.

Setting up the Server

AutoSSH

Linux: systemd Sample Unit File

MacOS: launchd Sample plist

Drawbacks

Further Research

Things I Use

Goals

Operating Systems

Terminal

Text Editors

macOS-specific utilities

Languages

Miscellaneous Productivity

Mobile

Hardware

Things I have my eye on

Embarking on the Quest of Building Your Own Mechanical Keyboard

Why?

Parameters - Many Dimensions

Keyboard Size

Switches

Layout

Programmability

Parts

Assembly

Flashing

Conclusion

Post-Script: My Parts List

`git switch`/`git restore`

Why I am not switching to ZSH

Weighing The "Cost of Adoption"

Enter Fish Shell

Which do you prefer?: DSL or a well-designed Library?

Creating an Alerting Callback Plugin in Ansible - Part I

Proposed Solution

Building the Callback Plugin

A Bit of Debugging Strategy

That's All For Now

What I Learned this Week (March 30, 2018)

Directed Graphs: Connected Components

Relearn: DAG: Topological Sort

libclang

RPython

Shibboleth

What I Learned this Week (March 23, 2018)

Docker: Service vs. Stack

What I Learned This Week (March 16, 2018)

Common Themes

Kubernetes via Minikube

HashiCorp

Ansible

Conclusions

Pratt Parsing

The Problem

Work, dang-it

Meet my friend, Vaughan Pratt

Precedence though...

Power in precedence

Not to be pedantic, but how do you handle right associativity?

Conclusions

Linux: `systemd` Sample Unit File

MacOS: `launchd` Sample `plist`