SHEEPDOG(8)

✨ SHEEPDOG(8) ✨ — like, the sheep(8) page, bestie

okay so real talk, this is the sheep daemon from Sheepdog, and it's literally the whole personality of this manual. Let's get into it 💅

---

🐑 NAME

sheep — a Distributed Block Storage System for QEMU. yes that's the whole name. iconic.

---

🦋 SYNOPSIS

sheep [options] [PATH]

---

💖 DESCRIPTION

okay so sheep is Sheepdog, a distributed storage system for QEMU. It hands out highly available block level storage volumes to virtual machines, like a little fairy godmother but for disks 🧚

Sheepdog does the advanced volume management stuff — snapshot, cloning, and thin provisioning. And the architecture? Fully symmetric. There is no central node, no meta-data server, nobody sitting at the top being the main character. everyone's equal, we love to see it 👑

The server daemon itself is called sheep(8). There's also a command line utility you can vibe with, dog(8). And QEMU virtual machines talk to the sheep daemon through a block driver that lives in qemu(1).

---

🎀 OPTIONS 🎀

• -b, --bindaddr — tell sheep which IP address of which interface it should listen on.

Example:

$ sheep -b 192.168.1.1 ...

This tries to teach sheep listen to the NIC of 192.168.1.1. 🫶

Example:

$ sheep -b 0.0.0.0 ...

This tries to teach sheep listen to all the NICs available. Super useful when you want sheep to respond to dog without you specifying an address and port. no cap.

• -c, --cluster — pick your cluster driver. (default: corosync)

Available arguments:

• local: use local driver
• corosync: use corosync driver
• zookeeper: use zookeeper driver, and it needs extra arguments

zookeeper arguments: connection-string,timeout=value (default as 3000)

Example:

$ sheep -c zookeeper:IP1:PORT1,IP2:PORT2,IP3:PORT3[/cluster_id][,timeout=1000] ...

This tries to use a 3 node zookeeper cluster, reachable by IP1:PORT1, IP2:PORT2, IP3:PORT3, to manage membership and broadcast messages — and it sets the node heartbeat timeout to 1000 milliseconds. cluster_id is how you say which cluster it belongs to; if you don't set it, /sheepdog is used internally as the default. periodt.

• -D, --directio — use direct IO for the backend store.
• -f, --foreground — make the program run in the foreground.
• -g, --gateway — make the program run as a gateway mode.
• -h, --help — display this help and exit. (the classic 🥰)
• -i, --ioaddr — use a separate network card to handle IO requests. (default: disabled)

Example:

$ sheep -i host=192.168.1.1,port=7002 ...

This tries to add a dedicated IO NIC of 192.168.1.1:7002 to transfer data. And if the IO NIC is down, sheep will fallback to the non IO NIC to transfer data. resilience queen 💅

• -j, --journal — use a journal file to log all the write operations. (default: disabled)

Available arguments:

• size=: size of the journal in megabyes
• dir=: path to the location of the journal (default: $STORE)
• skip: if specified, skip the recovery at startup

Example:

$ sheep -j dir=/journal,size=1G

This tries to use /journal as the journal storage of the size 1G. 🍓

• -l, --log — specify the log level, the log directory and the log format. (log level default: 6 [SDOG_INFO])

Example:

$ sheep -l dir=/var/log/,level=debug,format=server ...

Available arguments:

• dir=: path to the location of sheep.log
• level=: log level of sheep.log
• format=: log format type
• dst=: log destination type

if dir is not specified, use the metastore directory.

Available log levels:

• emerg — system has failed and is unusable 😭
• alert — action must be taken immediately
• crit — critical conditions
• err — error conditions
• warning — warning conditions
• notice — normal but significant conditions
• info — informational notices
• debug — debugging messages default log level is info

Available log format:

• default — raw format
• server — raw format with timestamp
• json — json format

Available log destination:

• default — dedicated file in a directory used by sheep
• syslog — syslog of the system
• stdout — standard output

• -n, --nosync — drop O_SYNC for write of backend.
• -p, --port — specify the TCP port on which to listen. (default: 7000)
• -P, --pidfile — create a pid file.
• -R, --recovery — specify the recovery speed throttling.

Available arguments:

• max=: object recovery process maximum count of each interval
• interval=: object recovery interval time (millisec)

Example:

$ sheep -R max=50,interval=1000 ...

• -u, --upgrade — upgrade to the latest data layout.
• -v, --version — show the version.

Sheepdog daemon version 1.0.1

• -V, --vnodes — set number of vnodes.

Example:

$ sheep -V 128

set number of vnodes

• -w, --wq-threads — specify a number of threads for workqueue.
• -W, --wildcard-recovery — wildcard recovery for first time.
• -y, --myaddr — specify the address advertised to other sheep.

Example:

$ sheep -y 192.168.1.1 ...

This tries to tell other nodes through what address they can talk to this sheep. 📣

• -z, --zone — specify the zone id. (default: determined by listen address)

Example:

$ sheep -z 1 ...

This tries to set the zone ID of this sheep to 1, and sheepdog won't store more than one copy of any object into this same zone.

---

🌸 PATH 🌸

Proper LSB systems will store sheepdog files in /var/lib/sheepdog. The init script uses this directory by default.

The directory must be on a filesystem with xattr support. In the case of ext3, user_xattr should be added to the mount options. don't skip this one bestie, fr fr.

mount -o remount,user_xattr /var/lib/sheepdog

---

🌈 DEPENDENCIES 🌈

sheepdog requires QEMU 0.13.z or later and Corosync 1.y.z. no substitutions, we don't do that here 💀

---

⭐ FILES ⭐

• /var/lib/sheepdog — Directory containing block storage information

---

👑 SEE ALSO 👑

dog(8), qemu(1), sheepfs(8), corosync_overview(8)

---

💜 AUTHORS 💜

This software is developed by the sheepdog community, which may be reached via mailing list at <sheepdog@lists.wpkg.org>.

---

okay that's the whole page, you ate that 🫶 this was the System Manager's Manual version of SHEEPDOG(8), dated 2025-07-26 — go forth and store some blocks, bestie 💖✨