Getting started with Goblin Store

Goblin Store is a Linux object cache for values large enough that keeping every byte in RAM is wasteful. It keeps the beginning of each object resident, streams later bytes from SSD, and can put the cold tail on HDD. The same store serves memcache, HTTP, HTTPS, and optional native RDMA.

Goblin Store manual: Getting started · Installation · Command-line reference · Ubuntu service

Choose the page you need

Installation installs the Ubuntu build dependencies, builds and tests Goblin Store, and places the binaries in /usr/local/bin.
Command-line reference documents every option accepted by goblin-store, including defaults, repeatable flags, and important incompatibilities.
Ubuntu service creates a dedicated account and storage directories, installs a hardened systemd unit, raises the file and locked-memory limits, and verifies readiness.

The repository README remains the project overview. Architecture decisions and benchmark methodology live in the ADR index and benchmark index.

The storage model in one minute

Choose two or three positional tiers:

The first --ram-head bytes are kept in RAM. The default is 256 KiB.
With only --ssd-dir, the complete disk copy is placed on SSD.
Adding --hdd-dir keeps the first --ssd-prefix bytes on SSD and places the remainder on HDD.

Goblin begins the disk-tail read while the resident head is being delivered. Objects smaller than the configured head are packed into the small-object arena and remain entirely in RAM.

Every SSD, HDD, and persistent-head directory must be prepared once with goblin-store-path-prep. The marker prevents a mistyped path from being wiped. Without --heads-path, Goblin starts with an empty cache and safely clears its prepared SSD/HDD pools. With --heads-path, it verifies the prepared directories and reconstructs valid objects instead.

A local development run

First complete Installation, or run these commands from an existing build tree. This example disables NUMA placement and mlock() so it works from an ordinary development shell:

mkdir -p /var/tmp/goblin-quickstart
./build/goblin-store-path-prep /var/tmp/goblin-quickstart/ssd

./build/goblin-store \
    --ssd-dir /var/tmp/goblin-quickstart/ssd \
    --memory 256M \
    --no-numa \
    --no-mlock

The default listeners are deliberately local-only:

memcache/TCP: 127.0.0.1:11211
HTTP: 127.0.0.1:8080
HTTPS and native RDMA: disabled

In another terminal, check storage readiness:

curl --fail --silent --show-error http://127.0.0.1:8080/__goblin/ready

If nc is installed, insert one object through memcache and retrieve the same key through HTTP:

printf 'set /hello 0 0 6\r\ngoblin\r\n' | nc -N 127.0.0.1 11211
curl --fail http://127.0.0.1:8080/hello

The HTTP response body is goblin. Press Ctrl-C in the server terminal for a graceful shutdown.

Pick a production layout

SSD only

Use one or more repeatable --ssd-dir arguments. Each object has its head in RAM and its complete disk copy striped across the SSD directories:

goblin-store --memory 4G \
    --ssd-dir /mnt/nvme0/goblin \
    --listen-address 10.0.0.20

SSD plus HDD

Add one or more --hdd-dir arguments. Bytes after --ssd-prefix go to the HDD pool:

goblin-store --memory 4G \
    --ram-head 256K \
    --ssd-prefix 32M \
    --ssd-dir /mnt/nvme0/goblin \
    --hdd-dir /mnt/hdd-array/goblin \
    --listen-address 10.0.0.20

Restart-recoverable cache

Prepare a third, separate directory and pass --heads-path. Goblin writes each resident head there and rebuilds the in-memory catalog on restart:

goblin-store-path-prep /mnt/goblin-heads

goblin-store --memory 4G \
    --heads-path /mnt/goblin-heads \
    --ssd-dir /mnt/nvme0/goblin \
    --hdd-dir /mnt/hdd-array/goblin \
    --listen-address 10.0.0.20

The head, SSD, and HDD paths must be different because each tier uses the same digest-derived filenames.

NUMA defaults

NUMA support is enabled by default. Goblin identifies the Linux interface for each exact listening address, selects the interface’s NUMA node, and binds workers there. If listeners resolve to different nodes, startup fails with the interface names, addresses, node IDs, and suitable --numa NODE commands.

Use --numa NODE to select a node explicitly. --memory is allocated on the preferred node; --sub-memory adds the specified amount on every other node. --no-numa is intended for portable development and A/B tests, not for hiding an ambiguous production topology.

Before exposing a listener

Goblin binds TCP to 127.0.0.1 by default. An external --listen-address is an explicit security decision. Before exposing memcache, configure at least one of:

TLS 1.3 with --memcache-tls, --tls-cert, and --tls-key;
memcached ASCII authentication with a mode-0600 --auth-file;
a firewall or private network that limits clients;
a local mode-0600 Unix socket with --memcache-socket.

See the command-line reference for exact combinations and the Ubuntu service guide for a production process wrapper.