diff --git a/gfs2/man/gfs2.5 b/gfs2/man/gfs2.5 index 436abc0..8f67ce2 100644 --- a/gfs2/man/gfs2.5 +++ b/gfs2/man/gfs2.5 @@ -48,7 +48,7 @@ currently these are \fIlock_nolock\fR and \fIlock_dlm\fR. The default lock protocol name is written to disk initially when creating the filesystem with \fBmkfs.gfs2\fP(8), -p option. It can be changed on-disk by -using the \fBgfs2_tool\fP(8) utility's \fBsb proto\fP command. +using the \fBtunegfs2\fP(8) command. The \fBlockproto\fP mount option should be used only under special circumstances in which you want to temporarily use a different lock protocol @@ -70,7 +70,7 @@ The format of \fILockTableName\fR is lock-module-specific. For The default cluster/filesystem name is written to disk initially when creating the filesystem with \fBmkfs.gfs2\fP(8), -t option. It can be changed on-disk -by using the \fBgfs2_tool\fP(8) utility's \fBsb table\fP command. +by using the \fBtunegfs2\fP(8) command. The \fBlocktable\fP mount option should be used only under special circumstances in which you want to mount the filesystem in a different cluster, diff --git a/gfs2/man/gfs2.5.bz1818983-gfs2_5_Update_some_mentions_of_gfs2_tool b/gfs2/man/gfs2.5.bz1818983-gfs2_5_Update_some_mentions_of_gfs2_tool new file mode 100644 index 0000000..436abc0 --- /dev/null +++ b/gfs2/man/gfs2.5.bz1818983-gfs2_5_Update_some_mentions_of_gfs2_tool @@ -0,0 +1,268 @@ +.TH gfs2 5 + +.SH NAME +gfs2 \- GFS2 reference guide + +.SH SYNOPSIS +Overview of the GFS2 filesystem + +.SH DESCRIPTION + +GFS2 is a clustered filesystem, designed for sharing data between +multiple nodes +connected to a common shared storage device. It can also be used as a +local filesystem on a single node, however since the design is aimed +at clusters, that will usually result in lower performance than using +a filesystem designed specifically for single node use. + +GFS2 is a journaling filesystem and one journal is required for each node +that will mount the filesystem. The one exception to that is spectator +mounts which are equivalent to mounting a read-only block device and as +such can neither recover a journal or write to the filesystem, so do not +require a journal assigned to them. + +The GFS2 documentation has been split into a number of sections: + +\fBmkfs.gfs2\fP(8) Create a GFS2 filesystem +.br +\fBfsck.gfs2\fP(8) The GFS2 filesystem checker +.br +\fBgfs2_grow\fP(8) Growing a GFS2 filesystem +.br +\fBgfs2_jadd\fP(8) Adding a journal to a GFS2 filesystem +.br +\fBtunegfs2\fP(8) Tool to manipulate GFS2 superblocks +.br +\fBgfs2_edit\fP(8) A GFS2 debug tool (use with caution) + +.SH MOUNT OPTIONS + +.TP +\fBlockproto=\fP\fILockProtoName\fR +This specifies which inter-node lock protocol is used by the GFS2 filesystem +for this mount, overriding the default lock protocol name stored in the +filesystem's on-disk superblock. + +The \fILockProtoName\fR must be one of the supported locking protocols, +currently these are \fIlock_nolock\fR and \fIlock_dlm\fR. + +The default lock protocol name is written to disk initially when creating the +filesystem with \fBmkfs.gfs2\fP(8), -p option. It can be changed on-disk by +using the \fBgfs2_tool\fP(8) utility's \fBsb proto\fP command. + +The \fBlockproto\fP mount option should be used only under special +circumstances in which you want to temporarily use a different lock protocol +without changing the on-disk default. Using the incorrect lock protocol +on a cluster filesystem mounted from more than one node will almost +certainly result in filesystem corruption. +.TP +\fBlocktable=\fP\fILockTableName\fR +This specifies the identity of the cluster and of the filesystem for this +mount, overriding the default cluster/filesystem identify stored in the +filesystem's on-disk superblock. The cluster/filesystem name is recognized +globally throughout the cluster, and establishes a unique namespace for +the inter-node locking system, enabling the mounting of multiple GFS2 +filesystems. + +The format of \fILockTableName\fR is lock-module-specific. For +\fIlock_dlm\fR, the format is \fIclustername:fsname\fR. For +\fIlock_nolock\fR, the field is ignored. + +The default cluster/filesystem name is written to disk initially when creating +the filesystem with \fBmkfs.gfs2\fP(8), -t option. It can be changed on-disk +by using the \fBgfs2_tool\fP(8) utility's \fBsb table\fP command. + +The \fBlocktable\fP mount option should be used only under special +circumstances in which you want to mount the filesystem in a different cluster, +or mount it as a different filesystem name, without changing the on-disk +default. +.TP +\fBlocalflocks\fP +This flag tells GFS2 that it is running as a local (not clustered) filesystem, +so it can allow the kernel VFS layer to do all flock and fcntl file locking. +When running in cluster mode, these file locks require inter-node locks, +and require the support of GFS2. When running locally, better performance +is achieved by letting VFS handle the whole job. + +This is turned on automatically by the lock_nolock module. +.TP +\fBerrors=\fP\fI[panic|withdraw]\fR +Setting errors=panic causes GFS2 to oops when encountering an error that +would otherwise cause the +mount to withdraw or print an assertion warning. The default setting +is errors=withdraw. This option should not be used in a production system. +It replaces the earlier \fBdebug\fP option on kernel versions 2.6.31 and +above. +.TP +\fBacl\fP +Enables POSIX Access Control List \fBacl\fP(5) support within GFS2. +.TP +\fBspectator\fP +Mount this filesystem using a special form of read-only mount. The mount +does not use one of the filesystem's journals. The node is unable to +recover journals for other nodes. +.TP +\fBnorecovery\fP +A synonym for spectator +.TP +\fBsuiddir\fP +Sets owner of any newly created file or directory to be that of parent +directory, if parent directory has S_ISUID permission attribute bit set. +Sets S_ISUID in any new directory, if its parent directory's S_ISUID is set. +Strips all execution bits on a new file, if parent directory owner is different +from owner of process creating the file. Set this option only if you know +why you are setting it. +.TP +\fBquota=\fP\fI[off/account/on]\fR +Turns quotas on or off for a filesystem. Setting the quotas to be in +the "account" state causes the per UID/GID usage statistics to be +correctly maintained by the filesystem, limit and warn values are +ignored. The default value is "off". +.TP +\fBdiscard\fP +Causes GFS2 to generate "discard" I/O requests for blocks which have +been freed. These can be used by suitable hardware to implement +thin-provisioning and similar schemes. This feature is supported +in kernel version 2.6.30 and above. +.TP +\fBbarrier\fP +This option, which defaults to on, causes GFS2 to send I/O barriers +when flushing the journal. The option is automatically turned off +if the underlying device does not support I/O barriers. We highly +recommend the use of I/O barriers with GFS2 at all times unless +the block device is designed so that it cannot lose its write cache +content (e.g. its on a UPS, or it doesn't have a write cache) +.TP +\fBcommit=\fP\fIsecs\fR +This is similar to the ext3 \fBcommit=\fP option in that it sets +the maximum number of seconds between journal commits if there is +dirty data in the journal. The default is 60 seconds. This option +is only provided in kernel versions 2.6.31 and above. +.TP +\fBdata=\fP\fI[ordered|writeback]\fR +When data=ordered is set, the user data modified by a transaction is +flushed to the disk before the transaction is committed to disk. This +should prevent the user from seeing uninitialized blocks in a file +after a crash. Data=writeback mode writes the user data to the disk +at any time after it's dirtied. This doesn't provide the same +consistency guarantee as ordered mode, but it should be slightly +faster for some workloads. The default is ordered mode. +.TP +\fBmeta\fP +This option results in selecting the meta filesystem root rather than +the normal filesystem root. This option is normally only used by +the GFS2 utility functions. Altering any file on the GFS2 meta filesystem +may render the filesystem unusable, so only experts in the GFS2 +on-disk layout should use this option. +.TP +\fBquota_quantum=\fP\fIsecs\fR +This sets the number of seconds for which a change in the quota +information may sit on one node before being written to the quota +file. This is the preferred way to set this parameter. The value +is an integer number of seconds greater than zero. The default is +60 seconds. Shorter settings result in faster updates of the lazy +quota information and less likelihood of someone exceeding their +quota. Longer settings make filesystem operations involving quotas +faster and more efficient. +.TP +\fBstatfs_quantum=\fP\fIsecs\fR +Setting statfs_quantum to 0 is the preferred way to set the slow version +of statfs. The default value is 30 secs which sets the maximum time +period before statfs changes will be syned to the master statfs file. +This can be adjusted to allow for faster, less accurate statfs values +or slower more accurate values. When set to 0, statfs will always +report the true values. +.TP +\fBstatfs_percent=\fP\fIvalue\fR +This setting provides a bound on the maximum percentage change in +the statfs information on a local basis before it is synced back +to the master statfs file, even if the time period has not +expired. If the setting of statfs_quantum is 0, then this setting +is ignored. +.TP +\fBrgrplvb\fP +This flag tells gfs2 to look for information about a resource group's free +space and unlinked inodes in its glock lock value block. This keeps gfs2 from +having to read in the resource group data from disk, speeding up allocations in +some cases. This option was added in the 3.6 Linux kernel. Prior to this +kernel, no information was saved to the resource group lvb. \fBNote:\fP To +safely turn on this option, all nodes mounting the filesystem must be running +at least a 3.6 Linux kernel. If any nodes had previously mounted the filesystem +using older kernels, the filesystem must be unmounted on all nodes before it +can be mounted with this option enabled. This option does not need to be +enabled on all nodes using a filesystem. +.TP +\fBloccookie\fP +This flag tells gfs2 to use location based readdir cookies, instead of its +usual filename hash readdir cookies. The filename hash cookies are not +guaranteed to be unique, and as the number of files in a directory increases, +so does the likelihood of a collision. NFS requires readdir cookies to be +unique, which can cause problems with very large directories (over 100,000 +files). With this flag set, gfs2 will try to give out location based cookies. +Since the cookie is 31 bits, gfs2 will eventually run out of unique cookies, +and will fail back to using hash cookies. The maximum number of files that +could have unique location cookies assuming perfectly even hashing and names of +8 or fewer characters is 1,073,741,824. An average directory should be able to +give out well over half a billion location based cookies. This option was added +in the 4.5 Linux kernel. Prior to this kernel, gfs2 did not add directory +entries in a way that allowed it to use location based readdir cookies. +\fBNote:\fP To safely turn on this option, all nodes mounting the filesystem +must be running at least a 4.5 Linux kernel. If this option is only enabled on +some of the nodes mounting a filesystem, the cookies returned by nodes using +this option will not be valid on nodes that are not using this option, and vice +versa. Finally, when first enabling this option on a filesystem that had been +previously mounted without it, you must make sure that there are no outstanding +cookies being cached by other software, such as NFS. + +.SH SETUP + +GFS2 clustering is driven by the dlm, which depends on dlm_controld to provide +clustering from userspace. dlm_controld clustering is built on corosync +cluster/group membership and messaging. GFS2 also requires clustered lvm which +is provided by lvmlockd or, previously, clvmd. Refer to the documentation for +each of these components and ensure that they are configured before setting up +a GFS2 filesystem. Also refer to your distribution's documentation for any +specific support requirements. + +Ensure that gfs2-utils is installed on all nodes which mount the filesystem as +it provides scripts required for correct withdraw event response. + +.B 1. Create the gfs2 filesystem + +mkfs.gfs2 -p lock_dlm -t cluster_name:fs_name -j num /path/to/storage + +The cluster_name must match the name configured in corosync (and thus dlm). +The fs_name must be a unique name for the filesystem in the cluster. +The -j option is the number of journals to create; there must +be one for each node that will mount the filesystem. + +.PP +.B 2. Mount the gfs2 filesystem + +If you are using a clustered resource manager, see its documentation for +enabling a gfs2 filesystem resource. Otherwise, run: + +mount /path/to/storage /mountpoint + +Run "dlm_tool ls" to verify the nodes that have each fs mounted. + +.PP +.B 3. Shut down + +If you are using a clustered resource manager, see its documentation for +disabling a gfs2 filesystem resource. Otherwise, run: + +umount -a -t gfs2 + +.PP +.SH SEE ALSO + +\fBmount\fP(8) and \fBumount\fP(8) for general mount information, +\fBchmod\fP(1) and \fBchmod\fP(2) for access permission flags, +\fBacl\fP(5) for access control lists, +\fBlvm\fP(8) for volume management, +\fBdlm_controld\fP(8), +\fBdlm_tool\fP(8), +\fBdlm.conf\fP(5), +\fBcorosync\fP(8), +\fBcorosync.conf\fP(5),