Gearmand

Search for Gearman Job Server in Marketplace, select the SecureAnyCloud publisher, and choose Create. Configure the Network Security Group to allow TCP 22 for administration and TCP 443 for the status console, both restricted to trusted source addresses. Do not open TCP 4730. The job protocol is loopback-only by design.

Run these commands from a workstation where you are signed in to the Azure CLI:

RG="gearmand-prod"; LOCATION="eastus"; VM_NAME="gearmand-01" IMAGE_URN="sac1647283583153:gearmand:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:gearmand:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1001
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 443 --priority 1002

Deploy inside your own virtual network, and restrict the Network Security Group to trusted networks.

On first boot, the image generates this instance's status-console password and writes the bcrypt htpasswd entry. It issues a per-instance TLS certificate whose subject alternative name carries this VM's address, seeds the status snapshot, and writes /root/gearmand-credentials.txt. This completes within a minute.

Connect over SSH as azureuser and read the details:

sudo cat /root/gearmand-credentials.txt

The file records GEARMAN_STATUS_USER, GEARMAN_STATUS_PASSWORD and the console URLs. The password is unique to this instance and is never shared with any other VM.

Both gearman-job-server.service and nginx.service are active. The job protocol is bound to 127.0.0.1:4730 only. The ss command shows it on loopback, while only SSH (22), HTTP (80) and HTTPS (443) are reachable off-box.

systemctl is-active gearman-job-server.service nginx.service ss -Hltn | awk '{print $4}' | sort -u

Expected output: the job protocol appears as 127.0.0.1:4730, never 0.0.0.0:4730.

active active 0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:4730 [::]:22 [::]:443 [::]:80

The shipped exposure check enumerates every listening socket. It fails closed on any unexpected non-loopback listener:

sudo /usr/local/sbin/gearman-exposure-check.sh '22 80 443'

This is the core of the product. A worker registers for a named function, a client submits a job for that function, and the result is returned through the job server.

Register a worker for a reverse function backed by the rev command, submit one job, and read the reversed result back. gearadmin --status then reflects the registered function, and gearadmin --workers shows the connected worker.

# Register a worker for the 'reverse' function (backed by /usr/bin/rev), in the background gearman -h 127.0.0.1 -p 4730 -w -f reverse -- /usr/bin/rev & WORKER_PID=$! sleep 2
# gearadmin reflects the registered function: name queued running workers echo "== gearadmin --status ==" gearadmin --status | grep '^reverse'
# Submit a job from a client and read the result returned through the job server echo "== submit a job ==" printf 'Hello Gearman' | gearman -h 127.0.0.1 -p 4730 -f reverse echo
# gearadmin shows the connected worker registered for 'reverse' echo "== gearadmin --workers ==" gearadmin --workers | grep reverse kill "$WORKER_PID" 2>/dev/null

Expected output: the client sends Hello Gearman, the worker reverses it, and the result namraeG olleH returns through the job server.

== gearadmin --status == reverse 0 0 1 == submit a job == namraeG olleH == gearadmin --workers == 37 127.0.0.1 - : reverse

Background jobs are accepted immediately and queued for a worker to pick up later. They are written to an on-box persistent SQLite queue, so work accepted before a restart is replayed after it rather than lost.

Submit a background job, check that it is in the queue and persisted to SQLite, then drain it with a worker.

# Submit a BACKGROUND job (returns immediately with a job handle) printf 'process-me' | gearman -h 127.0.0.1 -p 4730 -b -f demo_bg sleep 1
# The job is queued (queued count is 1) ...
echo "== queued ==" gearadmin --status | grep '^demo_bg'
# ... and persisted to the on-box SQLite queue database
echo "== persisted to SQLite =="
sudo sqlite3 -readonly /var/lib/gearman/gearmand-queue.db \
  "select function_name, length(data) as bytes from gearman_queue where function_name='demo_bg';"
# Drain it with a one-shot worker
echo "== drain ==" gearman -h 127.0.0.1 -p 4730 -w -c 1 -f demo_bg -- /bin/cat >/dev/null && echo "background job drained by a worker"

A read-only status console is served over HTTPS on port 443. It shows live queue depth, registered functions, connected workers and the running version. These are the numbers you need for capacity planning and alerting. The console never exposes the job protocol itself.

The console is protected by HTTP basic authentication, with a password generated for this instance on first boot. A separate unauthenticated /healthz endpoint is provided for load balancer and monitoring probes. Because the console serves the per-instance self-signed certificate, the commands use curl with -k.

STATUS_USER=$(sudo grep '^GEARMAN_STATUS_USER=' /root/gearmand-credentials.txt | cut -d= -f2-)
STATUS_PASS=$(sudo grep '^GEARMAN_STATUS_PASSWORD=' /root/gearmand-credentials.txt | cut -d= -f2-)
echo -n 'healthz (unauthenticated): HTTP '; curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1/healthz
echo -n '/status without a password: HTTP '; curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1/status
echo '--- /status with this instance credentials ---' curl -sk -u "$STATUS_USER:$STATUS_PASS" https://127.0.0.1/status | head -14

Expected output: /healthz returns 200 unauthenticated. /status returns 401 without the password and the live snapshot with it.

healthz (unauthenticated): HTTP 200 /status without a password: HTTP 401 --- /status with this instance credentials --- sac Gearman Job Server - status generated : ... host : ... listening : 127.0.0.1:4730

The job protocol is loopback-only. You can prove it: the port refuses a connection on this VM's own routable (private NIC) address, because only 127.0.0.1 is bound.

The start-time guard also refuses to start the service against a world-open listen address such as 0.0.0.0, the upstream default.

# The routable NIC address of this VM
PRIV=$(hostname -I | awk '{print $1}')
echo "routable address: $PRIV"
# A connection to 4730 there MUST be refused (the port is loopback-only) if timeout 5 bash -c "exec 3<>/dev/tcp/$PRIV/4730" 2>/dev/null; then
echo "UNEXPECTED: 4730 was reachable on $PRIV" else
echo "OK: 4730 refused on the routable address $PRIV (loopback only)" fi
# The start-time guard refuses a world-open listen address (the upstream default) GEARMAND_LISTEN=0.0.0.0 /usr/local/sbin/gearman-listen-guard.sh \
  || echo "OK: the start-time guard refuses GEARMAND_LISTEN=0.0.0.0"
# The credentials file is root-readable only
sudo stat -c '%n %a %U:%G' /root/gearmand-credentials.txt

Gearman has no native authentication, so exposing port 4730 is a deliberate decision, not a default. To let workers on other hosts in your own private subnet reach the job server, make a two-part change. Scope it tightly to your own network, never to the internet.

First, change the listen address in /etc/default/gearman-job-server from loopback to this VM's private address. Use a specific private IP, never 0.0.0.0, because the start-time guard refuses a world-open value:

# /etc/default/gearman-job-server (excerpt)
# Set to THIS VM's private NIC address, e.g. 10.0.0.14 — never 0.0.0.0. GEARMAND_LISTEN=10.0.0.14

Then restart the service and add one Network Security Group rule that allows TCP 4730 only from your own VNet/subnet CIDR:

sudo systemctl restart gearman-job-server.service az network nsg rule create --resource-group "$RG" --nsg-name "$NSG" \
  --name AllowGearmanFromSubnet --priority 1004 \
  --access Allow --protocol Tcp --direction Inbound \
  --destination-port-ranges 4730 --source-address-prefixes "<your-vnet-cidr>"

Because Gearman has no authentication, anyone who can reach port 4730 can submit and consume jobs. Keep the source scoped to your own private CIDR, and never add a rule for 4730 from 0.0.0.0/0 or Internet.

For stronger isolation, front the job server with mutual TLS through a proxy such as stunnel, or place workers and the job server in a dedicated private subnet.

Point your load balancer or monitoring system at the unauthenticated health endpoint. Read live queue metrics from the authenticated status console or with gearadmin:

# Liveness for a load balancer or uptime monitor (no credential needed)
curl -sk -o /dev/null -w 'healthz: HTTP %{http_code}\n' https://127.0.0.1/healthz
# Live queue depth and worker counts (function queued running workers) gearadmin --status

A worker connects to the job server, registers for one or more function names, and executes jobs. The CLI worker used above wraps any command. In production, you use a client library. For example, in Python with python-gearman:

import gearman class Worker(gearman.GearmanWorker): pass worker = Worker(['127.0.0.1:4730']) def reverse(worker, job): return job.data[::-1] worker.register_task('reverse', reverse) worker.work()

Client libraries exist for PHP, Perl, Python, Ruby, Java, Go, C and Node.js. Point each worker at 127.0.0.1:4730 on the job server host. For workers on other hosts in your subnet, use the private address you configured in Step 9.

Subscribe to the SecureAnyCloud Gearman Job Server listing and launch an instance. Pick m5.large and choose your VPC and subnet. Attach a security group that allows inbound TCP 22 and TCP 443 from your trusted CIDR only.

The instance boots with two volumes: the operating system disk, and a dedicated volume mounted at /var/lib/gearman that holds the persistent job queue.

Connect to the instance:

ssh ubuntu@<public-ip>

The login banner prints the status console URL and the commands you need most.

Two services make up the appliance: the job server itself and the nginx front end that serves the status console.

sudo systemctl is-active gearman-job-server nginx

active active

This is the most important check on the instance. gearmand must listen on 127.0.0.1 and nowhere else.

BIND="$(sudo ss -Hltn | awk '{print $4}' | grep ':4730$')" echo "Gearman job protocol is listening on: ${BIND}" case "${BIND}" in 127.0.0.1:4730) echo "CONFIRMED: loopback only - not reachable from any other host" ;; *) echo "This job server is NOT loopback bound; review /etc/default/gearman-job-server"; exit 1 ;; esac

Gearman job protocol is listening on: 127.0.0.1:4730 CONFIRMED: loopback only - not reachable from any other host

The shipped configuration file records the same setting, along with the procedure for widening access safely:

sudo grep -E '^GEARMAND_' /etc/default/gearman-job-server

GEARMAND_LISTEN=127.0.0.1 GEARMAND_PORT=4730 GEARMAND_QUEUE_DB=/var/lib/gearman/gearmand-queue.db GEARMAND_EXTRA_OPTS=

The image ships a fail-closed exposure audit. It lists every socket bound to a non-loopback address. It exits non-zero if anything outside the allow list appears, or if the job protocol has been bound off loopback. The same check runs during the build, before the image is captured.

sudo /usr/local/sbin/gearman-exposure-check.sh "22 80 443"

--- non-loopback TCP listeners --- tcp 0.0.0.0:443 tcp 0.0.0.0:22 tcp 0.0.0.0:80 tcp [::]:443 tcp [::]:22 tcp [::]:80 --- non-loopback UDP listeners --- udp 172.31.93.204%ens5:68 --- gearman job protocol binding --- 127.0.0.1:4730 exposure check clean: only 22 80 443 (tcp) are non-loopback

Only SSH and the status console are reachable from the network. The job protocol is not.

First boot writes a root-only credentials file. It holds the status console user, the password generated for this instance, and the console URLs. Nothing in it is shared with any other instance.

The command below prints the key names only, never the values. It is safe to run in a shared terminal or paste into a ticket.

sudo grep -oE '^[A-Z_]+=' /root/gearmand-credentials.txt

GEARMAN_STATUS_USER= GEARMAN_STATUS_PASSWORD= <set-at-first-boot>= GEARMAN_HEALTH_URL= GEARMAN_JOB_SERVER=

To read the whole file, including the password, run sudo cat /root/gearmand-credentials.txt on your own instance.

The console is served over HTTPS. Without credentials it returns 401, and with them it returns 200. The block below reads the password into a shell variable rather than printing it.

sudo bash -c ' U=$(grep -m1 "^GEARMAN_STATUS_USER=" /root/gearmand-credentials.txt | cut -d= -f2-) P=$(grep -m1 "^GEARMAN_STATUS_PASSWORD=" /root/gearmand-credentials.txt | cut -d= -f2-) UNAUTH=$(curl -sk -o /dev/null -w "%{http_code}" https://127.0.0.1/status) AUTH=$(curl -sk -o /dev/null -w "%{http_code}" -u "$U:$P" https://127.0.0.1/status) echo "status console, no credentials : HTTP ${UNAUTH}" echo "status console, with credentials : HTTP ${AUTH}" [ "${UNAUTH}" = 401 ] && [ "${AUTH}" = 200 ] || { echo "the status console did not behave as documented"; exit 1; } '

status console, no credentials : HTTP 401 status console, with credentials : HTTP 200

The certificate is a per-instance self-signed certificate issued at first boot, with your instance address in its subject alternative name. The commands use -k because the certificate is self-signed. To replace it with your own, see the certificate section below.

The console shows the server version and process id, the queue (one row per registered function, with queued, running and worker counts) and the connected workers. It is strictly read-only, and it never proxies the job protocol.

sudo bash -c ' U=$(grep -m1 "^GEARMAN_STATUS_USER=" /root/gearmand-credentials.txt | cut -d= -f2-) P=$(grep -m1 "^GEARMAN_STATUS_PASSWORD=" /root/gearmand-credentials.txt | cut -d= -f2-) curl -sk -u "$U:$P" https://127.0.0.1/status'

sac Gearman Job Server - status generated : 2026-07-26T08:39:13Z host : ip-172-31-93-204 listening : 127.0.0.1:4730 == server == version : 1.1.20+ds pid : 7458 == queue (function queued running workers) == . == workers == 37 127.0.0.1 - : .

From your own workstation, browse to the GEARMAN_STATUS_URL value in the credentials file. Sign in with the status user and the generated password.

Load balancer and monitoring probes need a target that does not require a credential. /healthz is a static 200 on both port 80 and port 443. It exposes nothing about the queue.

curl -s -o /dev/null -w 'health endpoint: HTTP %{http_code}\n' http://127.0.0.1/healthz

health endpoint: HTTP 200

A Gearman round trip needs two halves. A worker registers a function name and does the work. A client submits a job for that function name and waits for the result.

The block below registers a worker for a function called reverse that runs the rev command, submits one job to it, and asserts that the result came back correctly. The -c 1 option makes the worker exit after a single job, so the example is self-contained.

timeout 30 gearman -h 127.0.0.1 -p 4730 -w -c 1 -f reverse -- rev >/dev/null 2>&1 & sleep 2 RESULT="$(printf 'gearman on sac' | timeout 30 gearman -h 127.0.0.1 -p 4730 -f reverse)" wait echo "worker returned: ${RESULT}" [ "${RESULT}" = "gmiduolc no namraeg" ] || { echo "the round trip did not return the reversed payload"; exit 1; }

worker returned: gmiduolc no namraeg

The payload went from the client, through the job server, into the worker's standard input. The worker's standard output came back as the job result.

Background jobs are the reason most people run Gearman. The client submits and returns immediately, and a worker picks the job up whenever it is free. This image writes those jobs to a SQLite queue on the dedicated volume, so a job accepted before a restart is still there afterwards.

The block below submits a background job and proves that it is both queued in memory and persisted to disk. It then starts a worker to drain the job and proves that the queue is empty again.

printf 'nightly-report' | timeout 20 gearman -h 127.0.0.1 -p 4730 -b -f build_report sleep 2 gearadmin --status | grep '^build_report' || { echo "the background job was not queued"; exit 1; }
sudo sqlite3 -readonly /var/lib/gearman/gearmand-queue.db "select function_name, unique_key from gearman_queue;" timeout 30 gearman -h 127.0.0.1 -p 4730 -w -c 1 -f build_report -- cat >/dev/null 2>&1 sleep 1 echo "after the worker ran:" gearadmin --status | grep '^build_report' REMAIN="$(sudo sqlite3 -readonly /var/lib/gearman/gearmand-queue.db 'select count(*) from gearman_queue;')" echo "rows still persisted: ${REMAIN}" [ "${REMAIN}" = "0" ] || { echo "the queue did not drain"; exit 1; }

build_report 1 0 0 build_report|7aa82032-88cd-11f1-8d4f-12d811d5a21d after the worker ran: build_report 0 0 0 rows still persisted: 0

The four columns from gearadmin --status are function name, queued, running and connected workers. The job appeared as one queued item and one row in the SQLite queue. Both cleared once a worker had run it.

gearadmin is the administration client. It talks to the job server over the same loopback socket. To see the queue, run:

gearadmin --status

build_report 0 0 0 .

Other useful subcommands, all safe to run on a live server:

gearadmin --server-version gearadmin --getpid gearadmin --workers

1.1.20+ds 7458 37 127.0.0.1 - : .

The persistent queue lives on its own block storage volume, not on the operating system disk. You can resize it independently as your queue depth grows.

findmnt -no SOURCE,TARGET,FSTYPE,SIZE /var/lib/gearman df -h /var/lib/gearman | tail -1

/dev/nvme1n1 /var/lib/gearman ext4 19.5G /dev/nvme1n1 20G 36K 19G 1% /var/lib/gearman

The mount is recorded in /etc/fstab by filesystem UUID, so it reattaches on every boot. To grow it, expand the EBS volume in the AWS console, and then run sudo resize2fs /dev/nvme1n1.

Print the installed versions:

/usr/sbin/gearmand -V dpkg-query -W -f='${Package} ${Version}\n' gearman-job-server gearman-tools

gearmand 1.1.20+ds - https://github.com/gearman/gearmand/issues gearman-job-server 1.1.20+ds-1.2build4 gearman-tools 1.1.20+ds-1.2build4