path: root/doc/gluster.8

.\"  Copyright (c) 2006-2012 Red Hat, Inc. <http://www.redhat.com>
.\"  This file is part of GlusterFS.
.\"
.\"  This file is licensed to you under your choice of the GNU Lesser
.\"  General Public License, version 3 or any later version (LGPLv3 or
.\"  later), or the GNU General Public License, version 2 (GPLv2), in all
.\"  cases as published by the Free Software Foundation.
.\"
.\"
.TH Gluster 8 "Gluster command line utility" "07 March 2011" "Gluster Inc."
.SH NAME
gluster - Gluster Console Manager (command line utility)
.SH SYNOPSIS
.B gluster
.PP
To run the program and display gluster prompt:
.PP
.B gluster [--xml]
.PP
(or)
.PP
To specify a command directly:
.PP
.B gluster
.I [commands] [options] [--xml]

.SH DESCRIPTION
The Gluster Console Manager is a command line utility for elastic volume management. You can run the gluster command on any export server. The command enables administrators to perform cloud operations, such as creating, expanding, shrinking, rebalancing, and migrating volumes without needing to schedule server downtime.
.SH COMMANDS

.SS "Volume Commands"
.PP
.TP

\fB\ volume info [all|<VOLNAME>] \fR
Display information about all volumes, or the specified volume.
.TP
\fB\ volume create <NEW-VOLNAME> [stripe <COUNT>] [replica <COUNT>] [disperse [<COUNT>]] [redundancy <COUNT>] [transport <tcp|rdma|tcp,rdma>] <NEW-BRICK> ... \fR
Create a new volume of the specified type using the specified bricks and transport type (the default transport type is tcp).
To create a volume with both transports (tcp and rdma), give 'transport tcp,rdma' as an option.
.TP
\fB\ volume delete <VOLNAME> \fR
Delete the specified volume.
.TP
\fB\ volume start <VOLNAME> \fR
Start the specified volume.
.TP
\fB\ volume stop <VOLNAME> [force] \fR
Stop the specified volume.
.TP
\fB\ volume set <VOLNAME> <OPTION> <PARAMETER> [<OPTION> <PARAMETER>] ... \fR
Set the volume options.
.TP
\fB\ volume get <VOLNAME> <OPTION/all>\fR
Get the volume options.
.TP
\fB\ volume help \fR
Display help for the volume command.
.SS "Brick Commands"
.PP
.TP
\fB\ volume add-brick <VOLNAME> <NEW-BRICK> ... \fR
Add the specified brick to the specified volume.
.TP
\fB\ volume remove-brick <VOLNAME> <BRICK> ... \fR
Remove the specified brick from the specified volume.
.IP
.B 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
.B replace-brick
option.
.TP
\fB\ volume replace-brick <VOLNAME> <SOURCE-BRICK> <NEW-BRICK> commit force \fR
Replace the specified source brick with a new brick.
.TP
\fB\ volume rebalance <VOLNAME> start \fR
Start rebalancing the specified volume.
.TP
\fB\ volume rebalance <VOLNAME> stop \fR
Stop rebalancing the specified volume.
.TP
\fB\ volume rebalance <VOLNAME> status \fR
Display the rebalance status of the specified volume.
.SS "Log Commands"
.TP
\fB\ volume log filename <VOLNAME> [BRICK] <DIRECTORY> \fB
Set the log directory for the corresponding volume/brick.
.TP
\fB\ volume log locate <VOLNAME> [BRICK] \fB
Locate the log file for corresponding volume/brick.
.TP
\fB\ volume log rotate <VOLNAME> [BRICK] \fB
Rotate the log file for corresponding volume/brick.
.SS "Peer Commands"
.TP
\fB\ peer probe <HOSTNAME> \fR
Probe the specified peer. In case the <HOSTNAME> given belongs to an already probed peer, the peer probe command will add the hostname to the peer if required.
.TP
\fB\ peer detach <HOSTNAME> \fR
Detach the specified peer.
.TP
\fB\ peer status \fR
Display the status of peers.
.TP
\fB\ peer help \fR
Display help for the peer command.
.SS "Tier Commands"
.TP
\fB\ volume tier <VOLNAME> attach [<replica COUNT>] <NEW-BRICK>... \fR
Attach to an existing volume a tier of specified type using the specified bricks.
.TP
\fB\ volume tier <VOLNAME> status \fR
Display statistics on data migration between the hot and cold tiers.
.TP
\fB\ volume tier <VOLNAME> detach start\fR
Begin detaching the hot tier from the volume. Data will be moved from the hot tier to the cold tier.
.TP
\fB\ volume tier <VOLNAME> detach commit [force]\fR
Commit detaching the hot tier from the volume. The volume will revert to its original state before the hot tier was attached.
.TP
\fB\ volume tier <VOLNAME> detach status\fR
Check status of data movement from the hot to cold tier.
.TP
\fB\ volume tier <VOLNAME> detach stop\fR
Stop detaching the hot tier from the volume.
.SS "Geo-replication Commands"
.TP
\fI\ Note\fR: password-less ssh, from the master node (where these commands are executed) to the slave node <SLAVE_HOST>, is a prerequisite for the geo-replication commands.
.TP
\fB\ system:: execute gsec_create\fR
Generates pem keys which are required for push-pem
.TP
\fB\ volume geo-replication <MASTER_VOL> <SLAVE_HOST>::<SLAVE_VOL> create [push-pem] [force]\fR
Create a new geo-replication session from <MASTER_VOL> to <SLAVE_HOST> host machine having <SLAVE_VOL>.
Use push-pem to push the keys automatically.
.TP
\fB\ volume geo-replication <MASTER_VOL> <SLAVE_HOST>::<SLAVE_VOL> {start|stop} [force] \fR
Start/stop the geo-replication session from <MASTER_VOL> to <SLAVE_HOST> host machine having <SLAVE_VOL>.
.TP
\fB\ volume geo-replication [<MASTER_VOL> [<SLAVE_HOST>::<SLAVE_VOL>]] status [detail] \fR
Query status of the geo-replication session from <MASTER_VOL> to <SLAVE_HOST> host machine having <SLAVE_VOL>.
.TP
\fB\ volume geo-replication <MASTER_VOL> <SLAVE_HOST>::<SLAVE_VOL> {pause|resume} [force] \fR
Pause/resume the geo-replication session from <MASTER_VOL> to <SLAVE_HOST> host machine having <SLAVE_VOL>.
.TP
\fB\ volume geo-replication <MASTER_VOL> <SLAVE_HOST>::<SLAVE_VOL> delete [reset-sync-time]\fR
Delete the geo-replication session from <MASTER_VOL> to <SLAVE_HOST> host machine having <SLAVE_VOL>.
Optionally you can also reset the sync time in case you need to resync the entire volume on session recreate.
.TP
\fB\ volume geo-replication <MASTER_VOL> <SLAVE_HOST>::<SLAVE_VOL> config [[!]<options> [<value>]] \fR
View (when no option provided) or set configuration for this geo-replication session.
Use "!<OPTION>" to reset option <OPTION> to default value.
.SS "Bitrot Commands"
.TP
\fB\ volume bitrot <VOLNAME> {enable|disable} \fR
Enable/disable bitrot for volume <VOLNAME>
.TP
\fB\ volume bitrot <VOLNAME> scrub-throttle {lazy|normal|aggressive} \fR
Scrub-throttle value is a measure of how fast or slow the scrubber scrubs the filesystem for volume <VOLNAME>
.TP
\fB\ volume bitrot <VOLNAME> scrub-frequency {daily|weekly|biweekly|monthly} \fR
Scrub frequency for volume <VOLNAME>
.TP
\fB\ volume bitrot <VOLNAME> scrub {pause|resume} \fR
Pause/Resume scrub. Upon resume, scrubber continues where it left off.
.TP
\fB\ volume bitrot <VOLNAME> scrub status \fR
Show the statistics of scrubber status
.SS "Snapshot Commands"
.PP
.TP
\fB\ snapshot create <snapname> <volname> [no-timestamp] [description <description>] [force] \fR
Creates a snapshot of a GlusterFS volume. User can provide a snap-name and a description to identify the snap. Snap will be created by appending timestamp in GMT. User can override this behaviour using "no-timestamp" option. The description cannot be more than 1024 characters. To be able to take a snapshot, volume should be present and it should be in started state.
.TP
\fB\ snapshot restore <snapname> \fR
Restores an already taken snapshot of a GlusterFS volume. Snapshot restore is an offline activity therefore if the volume is online (in started state) then the restore operation will fail. Once the snapshot is restored it will not be available in the list of snapshots.
.TP
\fB\ snapshot clone <clonename> <snapname> \fR
Create a clone of a snapshot volume, the resulting volume will be GlusterFS volume. User can provide a clone-name. To be able to take a clone, snapshot should be present and it should be in activated state.
.TP
\fB\ snapshot delete ( all | <snapname> | volume <volname> ) \fR
If snapname is specified then mentioned snapshot is deleted. If volname is specified then all snapshots belonging to that particular volume is deleted. If keyword *all* is used then all snapshots belonging to the system is deleted.
.TP
\fB\ snapshot list [volname] \fR
Lists all snapshots taken. If volname is provided, then only the snapshots belonging to that particular volume is listed.
.TP
\fB\ snapshot info [snapname | (volume <volname>)] \fR
This command gives information such as snapshot name, snapshot UUID, time at which snapshot was created, and it lists down the snap-volume-name, number of snapshots already taken and number of snapshots still available for that particular volume, and the state of the snapshot. If snapname is specified then info of the  mentioned  snapshot is  displayed.  If volname is specified then info of all snapshots belonging to that volume is displayed.  If  both  snapname and  volname  is  not specified then info of all the snapshots present in the system are displayed.
.TP
\fB\ snapshot status [snapname | (volume <volname>)] \fR
This command gives 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 to which the snapshots belong to, and total size of the logical volume.

If snapname is specified then status of the mentioned snapshot is displayed. If volname is specified then status of all snapshots belonging to that volume is displayed. If both snapname and volname is not specified then status of all the snapshots present in the system are displayed.
.TP
\fB\ 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.

snapshot config without any keywords displays the snapshot config values of all volumes in the system. If volname is provided, then the snapshot config values of that volume is displayed.

Snapshot config command along with keywords can be used to change the existing config values. If volname is provided then config value of that volume is changed, else it will set/change the system limit.

snap-max-soft-limit and auto-delete are global options, that will be inherited by all volumes in the system and cannot be set to individual volumes.

snap-max-hard-limit can be set globally, as well as 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, which is applied on the "Effective snap-max-hard-limit" to get the "Effective snap-max-soft-limit".

When auto-delete feature is enabled, then upon reaching the "Effective snap-max-soft-limit", with every successful snapshot creation, the oldest snapshot will be deleted.

When auto-delete feature is disabled, then upon reaching the "Effective snap-max-soft-limit", the user gets a warning with every successful snapshot creation.

When auto-delete feature is disabled, then upon reaching the "Effective snap-max-hard-limit", further  snapshot  creations  will not be allowed.

activate-on-create is disabled by default. If you enable activate-on-create, then further snapshot will be activated during the time of snapshot creation.
.TP
\fB\ snapshot activate <snapname> \fR
Activates the mentioned snapshot.

Note : By default the snapshot is activated during snapshot creation.
.TP
\fB\ snapshot deactivate <snapname> \fR
Deactivates the mentioned snapshot.
.TP
\fB\ snapshot help \fR
Display help for the snapshot commands.
.SS "Self-heal Commands"
.TP
\fB\ volume heal <VOLNAME>\fR
Triggers index self heal for the files that need healing.

.TP
\fB\ volume heal  <VOLNAME> [enable | disable]\fR
Enable/disable self-heal-daemon for volume <VOLNAME>.

.TP
\fB\ volume heal <VOLNAME> full\fR
Triggers self heal on all the files.

.TP
\fB\ volume heal <VOLNAME> info \fR
Lists the files that need healing.

.TP
\fB\ volume heal <VOLNAME> info split-brain \fR
Lists the files which are in split-brain state.

.TP
\fB\ volume heal <VOLNAME> statistics \fR
Lists the crawl statistics.

.TP
\fB\ volume heal <VOLNAME> statistics heal-count \fR
Displays the count of files to be healed.

.TP
\fB\ volume heal <VOLNAME> statistics heal-count replica <HOSTNAME:BRICKNAME> \fR
Displays the number of files to be healed from a particular replica subvolume to which the brick <HOSTNAME:BRICKNAME> belongs.

.TP
\fB\ volume heal <VOLNAME> split-brain bigger-file <FILE> \fR
Performs healing of <FILE> which is in split-brain by choosing the bigger file in the replica as source.

.TP
\fB\ volume heal <VOLNAME> split-brain source-brick <HOSTNAME:BRICKNAME> \fR
Selects <HOSTNAME:BRICKNAME> as the source for all the files that are in split-brain in that replica and heals them.

.TP
\fB\ volume heal <VOLNAME> split-brain source-brick <HOSTNAME:BRICKNAME> <FILE> \fR
Selects the split-brained <FILE> present in <HOSTNAME:BRICKNAME> as source and completes heal.
.SS "Other Commands"
.TP
\fB\ help \fR
Display the command options.
.TP
\fB\ quit \fR
Exit the gluster command line interface.

.SH FILES
/var/lib/glusterd/*
.SH SEE ALSO
.nf
\fBfusermount\fR(1), \fBmount.glusterfs\fR(8), \fBglusterfs\fR(8), \fBglusterd\fR(8)
\fR
.fi
.SH COPYRIGHT
.nf
Copyright(c) 2006-2011  Gluster, Inc.  <http://www.gluster.com>