DEV Community: Franklin Yu

How the shell aliases affect shell functions: two pitfalls

Franklin Yu — Fri, 04 Oct 2024 05:59:58 +0000

If you have this in your .bashrc:

alias foo=bar
foo() {
    echo 1
}

You would expect the alias to “shadow” the function, so when you execute foo you think it is executing bar instead of echo 1. Right?

Wrong! The alias takes immediate effect, so when Bash sees the function definition, it actually regard it as

bar() {
    echo 1
}

which defines a function named bar. So you end up with foo as an alias, and bar as a function. Zsh is a bit better in this case; if Zsh sees the same snippet trying to define a function after alias, the function-definition command will fail (since defining bar as a function is almost never intended anyway). To fix it, define the function with the function keyword instead, whenever POSIX-compliance isn’t needed. This fix works both in Bash and in Zsh.

Another interesting behavior is how Bash and Zsh expand aliases in function bodies. For example:

alias ls='ls --color'
function ls_repos() {
    ls ~/repos  # expands to "ls --color ~/repos"
}

The order between the alias and the function is important, because aliases are expanded when the function is defined, not when it is called. The ls in the function body is expanded only if the alias exists before the function is defined. When you query the function definition with type -f you actually see the one after the expansion.

This behavior is actually well-documented. In Bash documentation:

Aliases are expanded when a function definition is read, not when the function is executed, because a function definition is itself a command.

Zsh documentation:

Note that aliases are expanded when the function definition is parsed, not when the function is executed.

On the plus side, one can make use of this behavior to avoid some annoyance. For example, if one of your alias in your .bashrc breaks some external script (such as nvm.sh), you can simply move the alias around in your .bashrc, defining them after sourcing nvm.

signify: replacement for PGP signing?

Franklin Yu — Mon, 24 Jun 2024 08:36:10 +0000

OpenBSD is a security-focused, free and open-source, Unix-like operating system based on the Berkeley Software Distribution (BSD). Theo de Raadt created OpenBSD in 1995 by forking NetBSD 1.0. The OpenBSD project emphasizes portability, standardization, correctness, proactive security, and integrated cryptography.

View on Wikipedia>

OpenBSD is a Unix-like operating system focusing on security. Like all other unix-like open-sourced operating system, OpenBSD has its package manager, and packages are signed. However, all other Unix-like open-sourced operating systems sign their packages with GnuPG:

GNU Privacy Guard is a free-software replacement for Symantec's cryptographic software suite PGP. The software is compliant with RFC 4880, the IETF standards-track specification of OpenPGP. Modern versions of PGP are interoperable with GnuPG and other OpenPGP v4-compliant systems.

View on Wikipedia>

In contrast, OpenBSD wrote their own tool for it: signify. As mentioned in the blog, it focuses on one thing, and does it well: sign a piece of data. It is much simpler than GnuPG (or OpenPGP in general), therefore a smaller attack surface, and therefore more secure.

Unfortunately, the tool is only for OpenBSD, not portable. There is a port to macOS (packaged in Homebrew and MacPorts):

jpouellet / signify-osx

OS X port of OpenBSD's signify(1)

macOS port of OpenBSD's signify(1)

This macOS port of OpenBSD's signify utility intentionally tracks upstream OpenBSD sources directly, keeping only the smallest portability layer possible with the explicit #1 goal of making it as easy to audit as possible.

The latest version was tested on macOS 10.14.2 with Apple LLVM 9.1.0.

Older versions were previously tested as far back as OS X 10.6.8 with GCC 4.2.1.

Some of the OpenBSD-specific functions used by signify that previously required portability shims were introduced in macOS 10.12(.1), and the corresponding portability shims have been removed to keep the code as lean and easily auditable as possible. If you need support for a newer signify on an older macOS, feel free to open an issue.

Man page at https://man.openbsd.org/signify.1

src/ is the result of make fetch (cvs get) and make hash-helpers (sed) as of the time of the last commit.

If you don't trust…

View on GitHub

There is another portable version, more popular and apparently better maintained:

aperezdc / signify

OpenBSD tool to sign and verify signatures on files. Portable version.

Signify - Sign and Verify

OpenBSD tool to sign and verify signatures on files. This is a portable version which uses libbsd (version 0.11 or newer is required).

See https://www.tedunangst.com/flak/post/signify for more information.

License

Signify is distributed under the terms of the ISC license.

Installation

Some GNU/Linux distributions have readily available packages in their repositories. It is recommended to use these, unless you absolutely need to build from source code:

Alpine Linux: apk add signify
Arch Linux: pacman -S signify
Debian/Ubuntu: apt install signify-openbsd
CentOS/RHEL/Rocky: dnf install epel-release then dnf install signify
Fedora: dnf install signify

Building

Dependencies

GNU Make (any version above 3.70).
C compiler. Both GCC and Clang are tested and supported.
libbsd 0.11 or newer.

If your system does not provide a package for libbsd, it is possible to use a bundled copy, check the build options section for more details.

Options

The following options…

View on GitHub

However, two concerns are still mentioned in this Whonix forum post:

signify-openbsd - Development - Whonix Forum

https://www.openbsd.org/papers/bsdcan-signify.html https://kushaldas.in/posts/using-signify-tool-for-sign-and-verification.html https://manpages.debian.org/signify-openbsd

forums.whonix.org

First, the signature format doesn’t support embedding filename or timestamp; second, signify only signs files that fit in RAM (1 GiB by default). The second concern is also mentioned in GitHub:

large file support #42

adrelanos posted on Jul 25, 2023

Created a 2G file for test purposes.

fallocate -l 2G test.img

Tried to sign it.

signify-openbsd -S -s ./keyname.sec -m ./test.img -x ./test.img.sig

result:

signify-openbsd: msg too large in ./test.img

Could you please add support for signing arbitrarily large files?

View on GitHub

The Whonix forum post mentioned that a partially-compatible project minisign can help:

jedisct1 / minisign

A dead simple tool to sign files and verify digital signatures.

Minisign

Minisign is a dead simple tool to sign files and verify signatures.

For more information, please refer to the Minisign documentation

Tarballs and pre-compiled binaries can be verified with the following public key:

RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3

Compilation / installation

Using Zig:

Dependencies:

libsodium

Compilation:

$ zig build -Drelease

Using cmake and gcc or clang:

libsodium
cmake
pkg-config
gcc or clang

Compilation:

$ mkdir build
$ cd build
$ cmake ..
$ make
# make install

Alternative configuration for static binaries:

$ cmake -D STATIC_LIBSODIUM=1 ..

or:

$ cmake -D BUILD_STATIC_EXECUTABLES=1 ..

Minisign is also available in Homebrew:

$ brew install minisign

Minisign is also available in Scoop on Windows:

$ scoop install minisign

Minisign is also available in chocolatey on Windows:

$ choco install minisign

Minisign is also available with docker:

$ docker run -i --rm jedisct1/minisign

The image can be verified with the following cosign public key:

-----BEGIN PUBLIC

…

View on GitHub

Its “trusted comments” feature addresses the first concern; for example, projects can define machine-readable format for the trusted comment. It addresses the second concern by pre-hashing the file with BLAKE:

BLAKE is a cryptographic hash function based on Daniel J. Bernstein's ChaCha stream cipher, but a permuted copy of the input block, XORed with round constants, is added before each ChaCha round. Like SHA-2, there are two variants differing in the word size. ChaCha operates on a 4×4 array of words. BLAKE repeatedly combines an 8-word hash value with 16 message words, truncating the ChaCha result to obtain the next hash value. BLAKE-256 and BLAKE-224 use 32-bit words and produce digest sizes of 256 bits and 224 bits, respectively, while BLAKE-512 and BLAKE-384 use 64-bit words and produce digest sizes of 512 bits and 384 bits, respectively.

View on Wikipedia>

This project also seems to be more active than the previous two ports, so it makes sense to sign binary releases (especially big files like disk images) with minisign instead of signify. signify remains feasible for small files like emails or plain text files.

Note that minisign is only one-way compatible with signify in that minisign legacy signatures (i.e. signed with the -l switch) can be verified by signify. See:

Can't verify Signify signatures #59

Macil posted on Jul 23, 2019

Minisign gives me an error when I try to use it to verify a signature made by Signify. From the docs it seems like this is intended to work.

$ echo VGhpcyBpcyBhIHRlc3QgbWVzc2FnZS4K | base64 --decode > message.txt
$ signify -G -p sign.pub -s sign.sec
passphrase: (z)
confirm passphrase: (z)
$ cat sign.sec
untrusted comment: signify secret key
RWRCSwAAACrVwvFk3aEyZFmPQ3kkX8eVAXYt/DvCvS3JD4o2QgWw5dPT1GwM0/u9lgqB03XQqr5yJJx9f49kmX5vd6NBBHa0rk4e9XC8mVs6Q1jWMCmO6aQTjcLOHFhLr9Vxc+W+NSw=
$ signify -S -s sign.sec -m message.txt
passphrase: (z)
$ cat message.txt.sig
untrusted comment: verify with sign.pub
RWTJD4o2QgWw5Yl4xS5JBgxC4Zv+KnDXYfDJzpE6LU/FZbs5vHq2kVJ5E7ruNvUUL+sg1/OSOvnI6N6A57wpc2VrWwujA/m8mwU=
$ ls
message.txt     message.txt.sig sign.pub        sign.sec
$ signify -V -p sign.pub -m message.txt -x message.txt.sig
Signature Verified
$ minisign -V -p sign.pub -m message.txt -x message.txt.sig
message.txt.sig: Undefined error: 0
$ minisign -v
minisign 0.8

The other way around works okay. Signify can verify minisign signatures:

$ rm sign.pub sign.sec
$ minisign -G -p sign.pub -s sign.sec
Please enter a password to protect the secret key.

Password: (z)
Password (one more time):
Deriving a key from the password in order to encrypt the secret key... done

The secret key was saved as sign.sec - Keep it secret!
The public key was saved as sign.pub - That one can be public.

Files signed using this key pair can be verified with the following command:

minisign -Vm <file> -P RWSaFhePk+tC9vTTi+yeIO4Wl6ncKXi9+ic+Rj0nohuwNC/ZWZLgBoEx
$ cat sign.sec
untrusted comment: minisign encrypted secret key
RWRTY0Iy8Ih0p+rQl2n6xucscPJOdSK48PM+Un6uFrhB74CZR/oAAAACAAAAAAAAAEAAAAAAXEf+5XzHb5GZ0vHG9ToGyICcgqEyB6kj1FAX0o/rO5o6bjIPvf3dJYo9qbOUYhWCv+56u9rnEywSGLzL9+XFmp3B2wwh14cw2+VsVe6saQG/fjrI2/C3vjUbpX1pKzGhGO391w6IawQ=
$ minisign -S -s sign.sec -m message.txt
Password: (z)
Deriving a key from the password and decrypting the secret key... done
$ cat message.txt.minisig
untrusted comment: signature from minisign secret key
RWSaFhePk+tC9snG7mzd/58ED3RdUFmO3KkyR5K8Vx/4WJCkRqHKBtUAVe4zSkoG2TgDGAImnjKBmHChbbjAxoD+TaY81Owx6AE=
trusted comment: timestamp:1563858228   file:message.txt
D1HGUOIL0Qc9OqibpK7QwMO3crzhoUdaur25n1eyMBL2q4r0loThMZycevcN1bMOg61h6cA5+PuBY8kE6MxFAw==
$ minisign -V -p sign.pub -m message.txt -x message.txt.minisig
Signature and comment signature verified
Trusted comment: timestamp:1563858228   file:message.txt
$ signify -V -p sign.pub -m message.txt -x message.txt.minisig
Signature Verified

Just in case this is somehow system-specific, I'm on MacOS with minisign and signify installed from Homebrew.

$ brew info signify-osx
signify-osx: stable 1.4 (bottled), HEAD
Cryptographically sign and verify files
https://man.openbsd.org/signify.1
/usr/local/Cellar/signify-osx/1.4 (6 files, 174.8KB) *
  Poured from bottle on 2019-07-22 at 14:46:59
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/signify-osx.rb
==> Options
--HEAD
    Install HEAD version
==> Analytics
install: 28 (30 days), 59 (90 days), 221 (365 days)
install_on_request: 28 (30 days), 58 (90 days), 208 (365 days)
build_error: 0 (30 days)
$ brew info minisign
minisign: stable 0.8 (bottled)
Sign files & verify signatures. Works with signify in OpenBSD
https://jedisct1.github.io/minisign/
/usr/local/Cellar/minisign/0.8 (6 files, 38.1KB) *
  Poured from bottle on 2019-07-22 at 13:40:52
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/minisign.rb
==> Dependencies
Build: cmake ✔
Required: libsodium ✔
==> Analytics
install: 85 (30 days), 172 (90 days), 644 (365 days)
install_on_request: 63 (30 days), 116 (90 days), 420 (365 days)
build_error: 0 (30 days)

View on GitHub

Also note that the size-limitation of signify also affects signature verification, so the “legacy switch” doesn’t make sense for large files (since you can’t verify with signify anyway).

Redis license change, and Rails Solid Cache

Franklin Yu — Mon, 13 May 2024 07:10:04 +0000

Redis switched the license of the main repository from BSD to dual license of SSPLv1 + RSALv2 in March. This was reported by The Register, and got heavily discussed on Hacker News. The GitHub pull request also received many comments:

Change license from BSD-3 to dual RSALv2+SSPLv1 #13157

K-Jo posted on Mar 20, 2024

Read more about the license change here: Redis Adopts Dual Source-Available Licensing Live long and prosper 🖖

View on GitHub

The comments mentioned several alternatives, including forks, and some competitors. Among those is a wire-format-compatible implementation from Microsoft:

microsoft / garnet

Garnet is a remote cache-store from Microsoft Research that offers strong performance (throughput and latency), scalability, storage, recovery, cluster sharding, key migration, and replication features. Garnet can work with existing Redis clients.

Garnet

Garnet is a new remote cache-store from Microsoft Research, that offers several unique benefits:

Garnet adopts the popular RESP wire protocol as a starting point, which makes it possible to use Garnet from unmodified Redis clients available in most programming languages of today, such as StackExchange.Redis in C#.
Garnet offers much better throughput and scalability with many client connections and small batches, relative to comparable open-source cache-stores, leading to cost savings for large apps and services.
Garnet demonstrates extremely low client latencies (often less than 300 microseconds at the 99.9th percentile) using commodity cloud (Azure) VMs with Accelerated Networking enabled, which is critical to real-world scenarios.
Based on the latest .NET technology, Garnet is cross-platform, extensible, and modern. It is designed to be easy to develop for and evolve, without sacrificing performance in the common case. We leveraged the rich library ecosystem of .NET for API breadth, with open…

View on GitHub

Coincidentally, the Rails team planned their next release earlier this year, where they intended to provide Solid Cache, a cache store backed by a SQL database, as an alternative to Redis-based cache store:

rails / solid_cache

A database-backed ActiveSupport::Cache::Store

Solid Cache

Solid Cache is a database-backed Active Support cache store that let's you keep a much larger cache than is typically possible with traditional memory-only Redis or Memcached stores. This is thanks to the speed of modern SSD drives, which make the access-time penalty of using disk vs RAM insignificant for most caching purposes. Simply put, you're now usually better off keeping a huge cache on disk rather than a small cache in memory.

Installation

Solid Cache is configured by default in new Rails 8 applications. But if you're running an earlier version, you can add it manually following these steps:

bundle add solid_cache
bin/rails solid_cache:install

This will configure Solid Cache as the production cache store, create config/cache.yml, and create db/cache_schema.rb.

You will then have to add the configuration for the queue database in config/database.yml. If you're using sqlite, it'll look like this:

production
  primary

…

View on GitHub

This announcement thread in Rails forum mentioned some caveat (which is also on the GitHub ReadMe), a blog post, and a video for the talk:

Actually DHH blogged about this gem in December, before the plan of Rails 8 was announced. Overall it sounds like a feasible solution, given the recent performance improvements of NVMe SSD.

Error of “RUBY_FUNCTION_NAME_STRING” when compiling Ruby

Franklin Yu — Sat, 02 Dec 2023 07:19:17 +0000

TL;DR

An unintended behavior when using ruby-install when both MacPorts and Homebrew are installed, a.k.a. “three hours lost in my life”.

Installation failure

It has been a few weeks since I last wrote some Ruby code, and my Ruby (installed with ruby-install) doesn’t work, because MacPorts were updated. This is pretty expected, and I went ahead to reinstall the version of Ruby. When I run ruby-install for that, I hit an compilation error:

compiling compile.c
In file included from compile.c:40:
./vm_callinfo.h:175:9: error: use of undeclared identifier 'RUBY_FUNCTION_NAME_STRING'
        rp(ci);
        ^
./internal.h:94:72: note: expanded from macro 'rp'
#define rp(obj) rb_obj_info_dump_loc((VALUE)(obj), __FILE__, __LINE__, RUBY_FUNCTION_NAME_STRING)

In file included from compile.c:40:
./vm_callinfo.h:216:16: error: use of undeclared identifier 'RUBY_FUNCTION_NAME_STRING'
    if (debug) rp(ci);
               ^
./internal.h:94:72: note: expanded from macro 'rp'
#define rp(obj) rb_obj_info_dump_loc((VALUE)(obj), __FILE__, __LINE__, RUBY_FUNCTION_NAME_STRING)
                                                                       ^
2 errors generated.
make: *** [compile.o] Error 1
!!! Compiling ruby 3.1.2 failed!

My quick reaction was to Google this error message. Everyone said that their issue were fixed by reinstall the Xcode CLT (Command Line Tool). Tried it, didn’t help; so I had to actually dig into the issue.

Understanding the Ruby configuration

From the affected C code, RUBY_FUNCTION_NAME_STRING looks like a macro. I searched the source code for the macro, and found that it was defined here:

AC_CACHE_CHECK(for function name string predefined identifier,
    rb_cv_function_name_string,
    [AS_CASE(["$target_os"],[openbsd*],[
      rb_cv_function_name_string=__func__
     ],[
     rb_cv_function_name_string=no
      RUBY_WERROR_FLAG([
        for func in __func__ __FUNCTION__; do
            AC_LINK_IFELSE([AC_LANG_PROGRAM([[@%:@include <stdio.h>]],
                        [[puts($func);]])],
            [rb_cv_function_name_string=$func
            break])
        done
      ])])]
)
AS_IF([test "$rb_cv_function_name_string" != no], [
    AC_DEFINE_UNQUOTED(RUBY_FUNCTION_NAME_STRING, [$rb_cv_function_name_string])
])

This file (configure.ac) is a GNU Autoconf script. This section of the script sets the value of the macro:

If compiling for OpenBSD, set it to __func__.
Otherwise, check whether the compiler supports the magic __func__, by compiling a minimal C program with it. If it does, set the macro to __func__.
Otherwise, do the same with __FUNCTION__.
If none of the above works, then leave the macro unset.

Indeed the output of ruby-install (actually ./configure) contains

checking for function name string predefined identifier... no

So it did fall into the last branch, leaving the macro unset. I tried compiling the same piece of C code; my compiler do support __func__. My next thoughts were: anyway for me to force it skipping the detection and use __func__ anyway?

./configure --help gives the answer: it supports --enable-FLAG=VALUE to override any feature detection. So I ran

./configure --enable-rb_cv_function_name_string=__func__

And indeed that line of log became

checking for function name string predefined identifier... __func__

In addition, subsequent make compiler.o succeeded without complaint. So the workaround sounds simple: just pass this flag as a “configure option” to ruby-install, like

ruby-install ruby-3.1.2 -- --enable-rb_cv_function_name_string=__func__

right?

Finding the next (real) broken thing

Nope, it didn’t work; the feature was set back to “no”. After scratching my head and reading the source code of ruby-install, I noticed that it supports a flag: -D/--debug, which prints the command it runs. I ran ruby-install again with that flag, and it printed

[DEBUG] ./configure --prefix=/Users/franklinyu/.rubies/ruby-3.1.2 --with-opt-dir=/Users/franklinyu/.local/opt/openssl@1.1:/Users/franklinyu/.local/opt/readline:/Users/franklinyu/.local/opt/libyaml:/Users/franklinyu/.local/opt/gdbm --enable-rb_cv_function_name_string=__func__

So it did have the --enable-xxx flags that I wanted; the --prefix looks legit. But the --with-opt-dir looks suspicious, because those paths didn’t actually exist on my system. I tried running this ./configure command, and I could reproduce the problem of feature set to “no”. I tried running with only the --prefix flag, and the feature was set to __func__ even without my --enable-xxx hack. So the root cause was actually the --with-opt-dir. Why was it set?

Reading the source code again, the relevant part is this:

case "$package_manager" in
    brew)
        opt_dir="$(brew --prefix readline):$(brew --prefix libyaml):$(brew --prefix gdbm)"
        openssl_dir="$(brew --prefix openssl@1.1)"
        ;;
    port)
        opt_dir="/opt/local"
        ;;
esac

run ./configure --prefix="$install_dir" \
        "${opt_dir:+--with-opt-dir="$opt_dir"}" \
        "${openssl_dir:+--with-openssl-dir="$openssl_dir"}" \
        "${configure_opts[@]}" || return $?

I didn’t set --package_manager for ruby-install because I did set --no-install-deps, and I thought it is sufficient. The problem was finally resolved by replacing --no-install-deps with --package_manager port. (Note: ruby-install doesn’t support the flag format --key=val.)

Background

I use MacPorts to manage FOSS on my Mac. I switched from Homebrew to MacPorts because Homebrew doesn’t record whether a package is “explicitly installed” or pulled in as dependencies; also Homebrew doesn’t support “virtual packages”. However, MacPorts seems to be mainly (only?) for FOSS, and is not interested in distributing binaries compiled upstream. This is includes Docker for Mac, coconutBattery, Acrobat Reader, Vagrant, and VirtualBox. Managing them via Homebrew Cask allows clean uninstallation, which is important for me, so I’d keep them coexist for a while.

Monitor home Internet connectivity with Cloudprober

Franklin Yu — Sat, 07 Oct 2023 03:49:00 +0000

Background

From time to time, my home is disconnected from the Internet, typically due to an outage of the Internet Service Provider. I do receive notification about my cameras going offline, but I have no idea how long it lasts; it can range from 10 minutes to 12 hours, and Comcast won’t tell you how long (you don’t even have access to the outage information unless you log in with the Comcast account). In addition, sometimes the Internet isn’t fully down, but the quality drops, so I’d like to set up something to monitor my Internet connection.

Journey of solution-hunting

The principle is simple: I set up something to ping (or cURL) https://google.com. Given the historical availability of that page, this probe is going to tell me whether I can reach Internet. Now the real question is, what tool can do the queries, save the data, and visualize the latency for me.

I did some research, and asked around. Most people don’t care; the ones who care typically uses SmokePing:

oetiker / SmokePing

The Active Monitoring System

____                  _        ____  _             
/ ___| _ __ ___   ___ | | _____|  _ \(_)_ __   __ _ 
\___ \| '_ ` _ \ / _ \| |/ / _ \ |_) | | '_ \ / _` |
 ___) | | | | | | (_) |   <  __/  __/| | | | | (_| |
|____/|_| |_| |_|\___/|_|\_\___|_|   |_|_| |_|\__, |
                                              |___/

Original Authors: Tobias Oetiker and Niko Tyni

SmokePing is a latency logging and graphing and alerting system. It consists of a daemon process which organizes the latency measurements and a CGI which presents the graphs.

SmokePing is ...

extensible through plug-in modules
easy to customize through a webtemplate and an extensive configuration file.
written in perl and should readily port to any unix system
an RRDtool frontend
able to deal with DYNAMIC IP addresses as used with Cable and ADSL internet.

cheers tobi

View on GitHub

SmokePing has its own web UI to show the data. The UI looks good enough for most users, but I’m not an average user, but this is insufficient for an SRE-SWE. I’m more of a backend guy, so not very good at implementing the interactive features myself. Another option I found was Nagios:

Nagios Core, formerly known as Nagios, is a free and open-source computer-software application that monitors systems, networks and infrastructure. Nagios offers monitoring and alerting services for servers, switches, applications and services. It alerts users when things go wrong and alerts them a second time when the problem has been resolved.

View on Wikipedia

I tried it briefly, before I had another idea: simply make a daemon (or a scheduled task) to post to some data-hosting service, such as Google Cloud Monitoring (also known as “StackDriver”. (Disclaimer: I’m a Googler.) I did some more research, and summarized my options in a GitHub issue:

Create a prober for connectivity of home Internet #23

FranklinYu posted on Oct 07, 2022

Need to know how good the connection is.

View on GitHub

When I was collecting libraries for this idea, I found Cloudprober.

Cloudprober

cloudprober / cloudprober

An active monitoring software to detect failures before your customers do.

NOTE: Cloudprober's active development has moved to github.com/cloudprober/cloudprober from ~~github.com/google/cloudprober~~.

Cloudprober is a monitoring software that makes it super-easy to monitor availability and performance of various components of your system. Cloudprober employs the "active" monitoring model. It runs probes against (or on) your components to verify that they are working as expected. For example, it can run a probe to verify that your frontends can reach your backends. Similarly it can run a probe to verify that your in-Cloud VMs can actually reach your on-premise systems. This kind of monitoring makes it possible to monitor your systems' interfaces regardless of the implementation and helps you quickly pin down what's broken in your system.

Features

Out of the box, config based, integration with many popular monitoring systems:
Multiple options for checks:
- Efficient, highly scalable, built-in probes HTTP PING…

View on GitHub

Cloudprober was created by Googlers (probably as a side project), and it supports uploading data to Google Cloud Monitoring (exactly what I needed). The tool was designed for black-box service monitoring of owned services, but it can actually be pointed to any service. For example, I monitor the Google homepage with this configuration:

# proto-file: https://github.com/cloudprober/cloudprober/blob/master/config/proto/config.proto
# proto-message: cloudprober.ProberConfig

probe: {
  name: "google_homepage"
  type: HTTP
  targets: {
    host_names: "www.google.com"
  }
  interval: "30s"
  timeout: "1s"
  latency_distribution: {
    exponential_buckets: {
      scale_factor: 100
      base: 1.1
      num_buckets: 25
      # last bucket starts at: 100 * 1.1^24 = 985 ms
    }
  }
  latency_unit: "ms"
  http_probe: {
    protocol: HTTPS
  }
}

surfacer: {
  type: STACKDRIVER
  stackdriver_surfacer: {
    project: "franklinyu-home"
  }
}

This creates nice charts on Google Cloud console like

Starting Cloudprober yourself

First, of course you need to download Cloudprober. You can follow the official guide to download the pre-built binary, or (if you are using Arch Linux) use my AUR package.

Then you need a Google Cloud project, and create a service account key. Follow the Google Cloud documentation to set the environment variable.

Now save the configuration file somewhere, for example in ~/Desktop/cloudprober.textproto, and run Cloudprober like

cloudprober --config_file ~/Desktop/cloudprober.textproto

Wait for a while, and the metric should appear in Google Cloud Console as

custom/cloudprober/http/google_homepage/latency

And you can see the data in Metric Explorer.

Configuration

The configuration file is specified in the text format of Procotol Buffer, also known (in Google) as “Text-Proto”. Most parts are straight forward; the latency_distribution stanza is explained in Google Cloud documentation. If we denote the scale-factor as “k” and base as “a”, then basically the buckets are the right-open intervals

k a^i, k a^{i+1})

except the first and last bucket (which has to cover the minimum and maximum). My strategy of choosing the base and the scale factor boils down to the “target interval”, which is the interval of latency that I care about. If we denote the number of buckets as “n”, then my strategy is that the entire “target interval” should be covered by buckets from second to the “second to last”. In other words, the “target interval” is supposed to be a subset of

k, k a^{n-2})