Gluster(8)

✨ gluster — the whole vibe (NAME) ✨

okay bestie, buckle up 🫶 this page is Gluster(8) from Gluster Inc., and the star of the show is gluster — the Gluster Console Manager, aka a command line utility. that's the name section, short and iconic, periodt 💅

---

🌸 SYNOPSIS 🌸

run it with nothing and it just... exists, ready to chat:

gluster

to run the program and display the gluster prompt:

gluster [--remote-host=<gluster_node>] [--mode=script] [--xml]

(or)

to specify a command directly:

gluster [commands] [options] [--remote-host=<gluster_node>]
[--mode=script] [--xml]

---

💖 DESCRIPTION 💖

The Gluster Console Manager is a command line utility for elastic volume management. you can literally run the gluster command on any export server, no cap. it lets administrators do their cloud operations — creating, expanding, shrinking, rebalancing and migrating volumes — without needing to schedule server downtime. no downtime?? that's the dream, fr fr 🦋

---

👑 COMMANDS 👑

🎀 Volume Commands 🎀

• volume info [all|<VOLNAME>] — display info about all the volumes, or just the one you named. your pick, bestie.
• volume list — list every single volume in the cluster. the full roster 💅
• volume status [all | <VOLNAME> [nfs|shd|<BRICK>|quotad]] [detail|clients|mem|inode|fd|callpool|tasks|client-list] — display the status of all volumes, or of the volume(s)/brick you specified. vibe check on your storage ✨
• volume create <NEW-VOLNAME> [stripe <COUNT>] [[replica <COUNT> [arbiter <COUNT>]]|[replica 2 thin-arbiter 1]] [disperse [<COUNT>]] [disperse-data <COUNT>] [redundancy <COUNT>] [transport <tcp|rdma|tcp,rdma>] <NEW-BRICK> ... <TA-BRICK> — create a brand new volume of the type you want, using the bricks and transport type you gave it. heads up: the default transport type is tcp. and if you want a volume with both transports (tcp and rdma), just pass 'transport tcp,rdma' as an option. slay 🌈
• volume delete <VOLNAME> — delete the volume you named. bye girl 💀
• volume start <VOLNAME> — start the specified volume. wake up queen 👑
• volume stop <VOLNAME> [force] — stop the specified volume. (there's a force if it's being dramatic.)
• volume set <VOLNAME> <OPTION> <PARAMETER> [<OPTION> <PARAMETER>] ... — set the volume options. you can stack as many option/parameter pairs as you want 🎀
• volume get <VOLNAME/all> <OPTION/all> — get the value of all options, or of the given option, for volume <VOLNAME> or for all. and psst — gluster volume get all all is how you get all the global options. iykyk ✨
• volume reset <VOLNAME> [option] [force] — reset all the reconfigured options. factory reset energy 🔄
• volume barrier <VOLNAME> {enable|disable} — barrier/unbarrier file operations on a volume 🚧
• volume clear-locks <VOLNAME> <path> kind {blocked|granted|all}{inode [range]|entry [basename]|posix [range]} — clear the locks held on a path. unlock the drama 🔓
• volume help — display help for the volume command. always ask for help, no shame 💜

🧱 Brick Commands 🧱

• volume add-brick <VOLNAME> <NEW-BRICK> ... — add the brick(s) you listed to the volume you named. more bricks, more room 🫶
• volume remove-brick <VOLNAME> <BRICK> ... — remove the specified brick(s) from the specified volume.

Note: if you remove the brick, the data stored in that brick will not be available. 😭 you can migrate data from one brick to another using the replace-brick option.

• volume reset-brick <VOLNAME> <SOURCE-BRICK> {{start} | {<NEW-BRICK> commit}} — brings down, or replaces, the specified source brick with the new brick.
• volume replace-brick <VOLNAME> <SOURCE-BRICK> <NEW-BRICK> commit force — replace the specified source brick with a new brick. glow-up for bricks ✨
• volume rebalance <VOLNAME> start — start rebalancing the specified volume.
• volume rebalance <VOLNAME> stop — stop rebalancing the specified volume.
• volume rebalance <VOLNAME> status — display the rebalance status of the specified volume.

📜 Log Commands 📜

• volume log <VOLNAME> rotate [BRICK] — rotate the log file for the corresponding volume/brick. out with the old 🌀
• volume profile <VOLNAME> {start|info [peek|incremental [peek]|cumulative|clear]|stop} [nfs] — profile operations on the volume. once you've started it, volume profile <volname> info gives you the cumulative statistics of the FOPs performed. numbers, but make it fashion 📊
• volume top <VOLNAME> {open|read|write|opendir|readdir|clear} [nfs|brick <brick>] [list-cnt <value>] | {read-perf|write-perf} [bs <size> count <count>] [brick <brick>] [list-cnt <value>] — generates a profile of a volume showing the performance and the bottlenecks/hotspots of each brick. finding the problem child, lovingly 🔍
• volume statedump <VOLNAME> [[nfs|quotad] [all|mem|iobuf|callpool|priv|fd|inode|history]... | [client <hostname:process-id>]] — dumps the in-memory state of the specified process, or of the bricks of the volume. brain dump, but make it technical 🧠
• volume sync <HOSTNAME> [all|<VOLNAME>] — sync the volume information from a peer. sharing is caring 💞

🤝 Peer Commands 🤝

• peer probe <HOSTNAME> — probe the specified peer. and fun fact: if the <HOSTNAME> you gave belongs to a peer that's already been probed, peer probe will add the hostname to the peer if required. no harm, no foul 💅
• peer detach <HOSTNAME> — detach the specified peer. it's not you, it's the topology 💀
• peer status — display the status of peers. group chat member list 🫶
• pool list — list all the nodes in the pool (including localhost). don't forget yourself, bestie ✨
• peer help — display help for the peer command.

💰 Quota Commands 💰

• volume quota <VOLNAME> enable — enable quota on the specified volume. this makes every directory in the filesystem hierarchy get accounted, and updated from then on with every operation in the filesystem. and to kick start that accounting, a crawl is done over the hierarchy with an auxiliary client. so much admin energy 🔥
• volume quota <VOLNAME> disable — disable quota on the volume. this disables enforcement and accounting in the filesystem, and heads up — any configured limits will be lost. gone. poof 😭
• volume quota <VOLNAME> limit-usage <PATH> <SIZE> [<PERCENT>] — set a usage limit on the given path. any previously set limit gets overridden to the new value. the soft limit can optionally be specified (as a percentage of the hard limit), and if you don't give the soft limit percentage, the default soft limit value for the volume is used to decide the soft limit 🎀
• volume quota <VOLNAME> limit-objects <PATH> <SIZE> [<PERCENT>] — set an inode limit on the given path. any previously set limit gets overridden to the new value. the soft limit can optionally be specified (as a percentage of the hard limit), and if the soft limit percentage isn't provided, the default soft limit value for the volume decides it 💅

NOTE: valid units of SIZE are: B, KB, MB, GB, TB, PB. if no unit is specified, the unit defaults to bytes.

• volume quota <VOLNAME> remove <PATH> — remove any usage limit configured on the specified directory. careful though: if a limit is configured on the ancestors of this directory (the previous directories along the path), those will still be honored and enforced. the parents always find out 🙈
• volume quota <VOLNAME> remove-objects <PATH> — remove any inode limit configured on the specified directory. same deal — if any limit is configured on the ancestors of this directory (previous directories along the path), they will still be honored and enforced.
• volume quota <VOLNAME> list <PATH> — lists the usage and limits configured on directory(s). if you give a path, only the limit configured on that directory (if any) is displayed, along with the directory's usage. if you give no path, usage and limits are displayed for all directories that have limits configured ✨
• volume quota <VOLNAME> list-objects <PATH> — lists the inode usage and inode limits configured on directory(s). if you give a path, only the limit configured on that directory (if any) is displayed, along with the directory's inode usage. if you give no path, usage and limits are displayed for all directories that have limits configured.
• volume quota <VOLNAME> default-soft-limit <PERCENT> — set the percentage value for the default soft limit for the volume.
• volume quota <VOLNAME> soft-timeout <TIME> — set the soft timeout for the volume. that's the interval in which limits are retested before the soft limit is breached ⏳
• volume quota <VOLNAME> hard-timeout <TIME> — set the hard timeout for the volume. that's the interval in which limits are retested after the soft limit is breached.
• volume quota <VOLNAME> alert-time <TIME> — set the frequency at which warning messages need to be logged (in the brick logs) once the soft limit is breached. the logs are gonna be chatty 🗣️
• volume inode-quota <VOLNAME> enable/disable — enable/disable inode-quota for <VOLNAME>.
• volume quota help — display help for volume quota commands.

NOTE: valid units of time and their symbols are: hours(h/hr), minutes(m/min), seconds(s/sec), weeks(w/wk), Days(d/days).

🌍 Geo-replication Commands 🌍

Note: password-less ssh, from the primary node (where these commands are executed) to the secondary node <SECONDARY_HOST>, is a prerequisite for the geo-replication commands. set it up first, bestie, it's literally required 🔑

• system:: execute gsec_create — generates pem keys which are required for push-pem 🔐
• volume geo-replication <PRIMARY_VOL> <SECONDARY_HOST>::<SECONDARY_VOL> create [[ssh-port n][[no-verify]|[push-pem]]] [force] — create a new geo-replication session from <PRIMARY_VOL> to the <SECONDARY_HOST> host machine that has <SECONDARY_VOL>. use ssh-port n if a custom SSH port is configured on the secondary nodes. use no-verify if the rsa-keys of the nodes in the primary volume are distributed to the secondary nodes through an external agent. use push-pem to push the keys automatically. it's giving long-distance relationship, but with data 💞
• volume geo-replication <PRIMARY_VOL> <SECONDARY_HOST>::<SECONDARY_VOL> {start|stop} [force] — start/stop the geo-replication session from <PRIMARY_VOL> to the <SECONDARY_HOST> host machine having <SECONDARY_VOL>.
• volume geo-replication [<PRIMARY_VOL> [<SECONDARY_HOST>::<SECONDARY_VOL>]] status [detail] — query the status of the geo-replication session from <PRIMARY_VOL> to the <SECONDARY_HOST> host machine having <SECONDARY_VOL>. vibe check on the sync 🦋
• volume geo-replication <PRIMARY_VOL> <SECONDARY_HOST>::<SECONDARY_VOL> {pause|resume} [force] — pause/resume the geo-replication session from <PRIMARY_VOL> to the <SECONDARY_HOST> host machine having <SECONDARY_VOL>. sometimes you just need a lil break ⏸️
• volume geo-replication <PRIMARY_VOL> <SECONDARY_HOST>::<SECONDARY_VOL> delete [reset-sync-time] — delete the geo-replication session from <PRIMARY_VOL> to the <SECONDARY_HOST> host machine having <SECONDARY_VOL>. optionally, you can also reset the sync time, in case you need to resync the entire volume on session recreate. it's giving fresh start ✨
• volume geo-replication <PRIMARY_VOL> <SECONDARY_HOST>::<SECONDARY_VOL> config [[!]<options> [<value>]] — view (when no option is provided) or set the configuration for this geo-replication session. and pro tip: use "!<OPTION>" to reset option <OPTION> to its default value 💅

🦋 Bitrot Commands 🦋

ok so bitrot is that whole thing where your files quietly rot and nobody tells you, and these are the commands that make gluster care 💖

• volume bitrot <VOLNAME> {enable|disable} — turns bitrot ON or OFF for volume <VOLNAME>. no in-between, bestie, it's a binary mood.
• volume bitrot <VOLNAME> signing-time <time-in-secs> — how long an object just sits there waiting, after its last fd gets closed, before the signing process kicks off. it's giving "let them chill for a sec" ⏳
• volume bitrot <VOLNAME> signer-threads <count> — how many signing process threads you want. lowkey everyone just sets this to however many cores they have, slay.
• volume bitrot <VOLNAME> scrub-throttle {lazy|normal|aggressive} — the scrub-throttle value is literally just a measure of how fast or slow the scrubber scrubs the filesystem for volume <VOLNAME>. pick your cardio level 🏃‍♀️
• volume bitrot <VOLNAME> scrub-frequency {hourly|daily|weekly|biweekly|monthly} — how often the scrub happens for volume <VOLNAME>. hourly is feral, monthly is chill, choose your vibe.
• volume bitrot <VOLNAME> scrub {pause|resume|status|ondemand} — pause/resume the scrub. when you resume, the scrubber picks up exactly where it left off (no starting over, we love a queen who remembers 💅). status shows you the scrubber's statistics. ondemand starts scrubbing immediately, but only if the scrubber isn't already paused or already running — it's not gonna double-book itself, no cap.
• volume bitrot help — shows you the help for the volume bitrot commands. when in doubt, ask for help, it's not embarrassing, it's ✨research✨

---

📸 Snapshot Commands 📸

snapshots are your little time capsules and these commands are how you take them, clone them, restore them and generally boss them around 🎀

• snapshot create <snapname> <volname> [no-timestamp] [description <description>] [force] — makes a snapshot of a GlusterFS volume. you can hand it a snap-name and a description so you can actually tell your snaps apart later. by default the snap gets created with a timestamp appended in GMT. you can override that whole timestamp situation with the no-timestamp option. the description cannot be more than 1024 characters, so no novel-length poetry in there. and heads up: to take a snapshot, the volume has to actually exist and it has to be in started state. no started volume, no snapshot, periodt.
• snapshot restore <snapname> — restores a snapshot you already took of a GlusterFS volume. important: snapshot restore is an offline activity, so if the volume is online (i.e. in started state) the restore will just fail on you 😭. and once the snapshot is restored, it will not be available in the list of snapshots anymore. it's gone, it's ascended, it's part of the volume now.
• snapshot clone <clonename> <snapname> — creates a clone of a snapshot volume, and the resulting thing is a GlusterFS volume. you get to pick a clone-name. to be able to take a clone, the snapshot needs to be present and it has to be in activated state. activated only, we don't do dormant here.
• snapshot delete ( all | <snapname> | volume <volname> ) — if you name a snapname, that one snapshot gets deleted. if you name a volname, then all the snapshots belonging to that particular volume get deleted. and if you use the keyword all, then every single snapshot belonging to the system gets deleted. yes, all of them. be so serious when you type this one 🫣
• snapshot list [volname] — lists all the snapshots taken. if you give it a volname, then it only lists the snapshots belonging to that particular volume.
• snapshot info [snapname | (volume <volname>)] — gives you the lore: snapshot name, snapshot UUID, the time the snapshot was created, plus it lists the snap-volume-name, how many snapshots are already taken, how many snapshots are still available for that particular volume, and the state of the snapshot. if you name a snapname, you get the info for that mentioned snapshot. if you name a volname, you get info for all snapshots belonging to that volume. if you give it neither snapname nor volname, then you get info on all the snapshots present in the system. the full feed, no filter.
• snapshot status [snapname | (volume <volname>)] — gives you the status of the snapshot. the details included are: snapshot brick path, volume group (LVM details), status of the snapshot bricks, PID of the bricks, data percentage filled for that particular volume group the snapshots belong to, and the total size of the logical volume.

if you name a snapname, you get the status of that mentioned snapshot. if you name a volname, you get the status of all snapshots belonging to that volume. if you give it neither snapname nor volname, then you get the status of all the snapshots present in the system. same energy as info, different receipts 💅

• snapshot config [volname] ([snap-max-hard-limit <count>] [snap-max-soft-limit <percent>]) | ([auto-delete <enable|disable>]) | ([activate-on-create <enable|disable>]) — displays and sets the snapshot config values. multitasking icon.

snapshot config with no keywords at all displays the snapshot config values of every volume in the system. if you hand it a volname, then you get the snapshot config values of that volume.

snapshot config with keywords is how you change the existing config values. if you provide a volname then the config value of that volume changes, otherwise it sets/changes the system limit.

snap-max-soft-limit and auto-delete are global options — they get inherited by all volumes in the system and they cannot be set on individual volumes. sorry, no per-volume customisation for those two.

snap-max-hard-limit can be set globally, and also per volume. the lowest limit between the global system limit and the volume specific limit becomes the "Effective snap-max-hard-limit" for a volume.

snap-max-soft-limit is a percentage value, and it gets applied on the "Effective snap-max-hard-limit" to get the "Effective snap-max-soft-limit".

when the auto-delete feature is enabled, then once you reach the "Effective snap-max-soft-limit", with every successful snapshot creation the oldest snapshot gets deleted. it's a whole rota.

when the auto-delete feature is disabled, then once you reach the "Effective snap-max-soft-limit", you just get a warning with every successful snapshot creation. no deletion, just ✨feedback✨.

when the auto-delete feature is disabled, then once you reach the "Effective snap-max-hard-limit", further snapshot creations will not be allowed. hard stop, the end, go home.

activate-on-create is disabled by default. if you enable activate-on-create, then further snapshots will be activated during the time of snapshot creation. convenient!! 🌸

• snapshot activate <snapname> — activates the mentioned snapshot.

note: by default the snapshot is activated during snapshot creation anyway, so this is for the ones that slipped through 💖

• snapshot deactivate <snapname> — deactivates the mentioned snapshot. the opposite of the above, obviously, but we're saying it out loud for completeness bestie.
• snapshot help — displays help for the snapshot commands. always available, never judges.

---

💖 Self-heal Commands 💖

your volume got a boo-boo, these commands kiss it better 🩹

• volume heal <VOLNAME> — triggers index self heal for the files that need healing.
• volume heal <VOLNAME> [enable | disable] — enable/disable the self-heal-daemon for volume <VOLNAME>.
• volume heal <VOLNAME> full — triggers self heal on all the files. every last one. full send.
• volume heal <VOLNAME> info — lists the files that need healing.
• volume heal <VOLNAME> info split-brain — lists the files that are in split-brain state. the messy ones 🫠
• volume heal <VOLNAME> statistics — lists the crawl statistics.
• volume heal <VOLNAME> statistics heal-count — displays the count of files to be healed.
• volume heal <VOLNAME> statistics heal-count replica <HOSTNAME:BRICKNAME> — displays the number of files to be healed from a particular replica subvolume that the brick <HOSTNAME:BRICKNAME> belongs to.
• volume heal <VOLNAME> split-brain bigger-file <FILE> — performs healing of <FILE> which is in split-brain, by choosing the bigger file in the replica as the source. size matters, apparently 👑
• volume heal <VOLNAME> split-brain source-brick <HOSTNAME:BRICKNAME> — picks <HOSTNAME:BRICKNAME> as the source for all the files that are in split-brain in that replica, and heals them.
• volume heal <VOLNAME> split-brain source-brick <HOSTNAME:BRICKNAME> <FILE> — picks the split-brained <FILE> present in <HOSTNAME:BRICKNAME> as the source and completes the heal. one file, one source, done.

---

🌈 Other Commands 🌈

the leftovers, but make them iconic

• get-state [<daemon>] [[odir </path/to/output/dir/>] [file <filename>]] [detail|volumeoptions] — gets the local state representation of the mentioned daemon and stores the data in the path information you provided.
• help — displays the command options. hi, hello, here's everything.
• quit — exits the gluster command line interface. bye bestie 👋

---

📁 FILES 📁

• /var/lib/glusterd/*

---

👀 SEE ALSO 👀

• fusermount(1)
• mount.glusterfs(8)
• glusterfs(8)
• glusterd(8)

---

©️ COPYRIGHT ©️

Copyright(c) 2006-2011 Gluster, Inc. <http://www.gluster.com>

---

and that's the whole page, bestie 🫶 this one's the Gluster command line utility, dated 07 March 2011, living in section Gluster(8) — go forth and command line, you absolute legend 💅✨