diff --git a/userspace/marsadm.8 b/userspace/marsadm.8 index f3c35035..c66d3e43 100644 --- a/userspace/marsadm.8 +++ b/userspace/marsadm.8 @@ -1,33 +1,552 @@ -.TH marsadm 8 "January 20, 2015" "" "MARS Admin Tool" - +.TH marsadm 8 "February 12, 2015" "MARS light0.1stable11\-26\-ge065dbd" "MARS Admin Tool" .SH NAME -marsadm \- management of MARS resources +marsadm \- Administration tool for MARS.\" marsadm .SH SYNOPSIS -.B "marsadm \-h \-\-help" +.B marsadm \-h \-\-help .br -.B "marsadm \-v \-\-version " +.B marsadm \-v \-\-version .br +.B marsadm {\fIglobal_option\fR} \fIcommand\fR [\fIresource_name\fR | all | {arg}] +.br +.B marsadm {\fIglobal_option\fR} view[\-\fImacroname\fR] [\fIresource_name\fR | all] .br - .SH DESCRIPTION -MARS is a kernel-level asynchronous replication system for block devices. -It is tailored for long-distance replication and through network +MARS is a kernel\-level asynchronous replication system for block devices. +It is tailored for long\-distance replication and through network bottlenecks. By default, it works asynchronously (in contrast to DRBD). .br More infomation on concepts and differences to DRDB can be found at https://github.com/schoebel/mars/blob/master/docu/MARS_LinuxTag2014.pdf?raw=true -.SH NOTICE -This manual page is only a placeholder. -Complete / authoritative documentation can be found in mars-manual.pdf -which should be also installed at your system. -.br -In addition, the newest version can be found at -https://github.com/schoebel/mars/blob/master/docu/mars-manual.pdf?raw=true +.SH OPTIONS + \fB\-\-force\fR + Skip safety checks. + Use this only when you really know what you are doing! + Warning! This is dangerous! First try \fB\-\-dry\-run\fR. + Not combinable with 'all'. + \fB\-\-dry\-run\fR + Don't modify the symlink tree, but tell what would be done. + Use this before starting potentially harmful actions such as + 'delete\-resource'. + \fB\-\-verbose\fR + Increase speakyness of some commands. + \fB\-\-logger\fR=/path/to/usr/bin/logger + Use an alternative syslog messenger. + When empty, disable syslogging. + \fB\-\-timeout\fR=\fIseconds\fR + Abort safety checks after timeout with an error. + When giving 'all' as resource agument, this works for each + resource independently. + \fB\-\-window\fR=\fIseconds\fR + Treat other cluster nodes as healthy when some communcation has + occured during the given time window. + \fB\-\-threshold\fR=\fIbytes\fR + Some macros like 'fetch\-threshold\-reached' use this for determining + their sloppyness. + \fB\-\-host\fR=\fIhostname\fR + Act as if the command was running on cluster node \fIhostname\fR. + Warning! This is dangerous! First try \fB\-\-dry\-run\fR + \fB\-\-ip\fR=\fIip\fR + Override the IP address stored in the symlink tree, as well as + the default IP determined from the list of network interfaces. + Usually you will need this only at 'create\-cluster' or + 'join\-cluster' for resolving ambiguities. + \fB\-\-macro\fR=\fItext\fR + Handy for testing short macro evaluations at the command line. -.br -A short summary of all available sub-commands and options can be -retrieved by invoking "marsadm --help". + +.SH ORDINARY COMMANDS +\fB attach\fR + usage: attach \fIresource_name\fR + Attaches the local disk (backing block device) to the resource. + The disk must have been previously configured at + {create,join}\-resource. + When designated as a primary, /dev/mars/$res will also appear. + This does not change the state of {fetch,replay}. + For a complete local startup of the resource, use 'marsadm up'. + +\fB cat\fR + usage: cat \fIpath\fR + Print internal debug output in human readable form. + Numerical timestamps and numerical error codes are replaced + by more readable means. + Example: marsadm cat /mars/5.total.status + +\fB connect\fR + usage: connect \fIresource_name\fR + See resume\-fetch\-local. + +\fB connect\-global\fR + usage: connect\-global \fIresource_name\fR + Like resume\-fetch\-local, but affects all resource members + in the cluster (remotely). + +\fB connect\-local\fR + usage: connect\-local \fIresource_name\fR + See resume\-fetch\-local. + +\fB create\-cluster\fR + usage: create\-cluster (no parameters) + This must be called exactly once when creating a new cluster. + Don't call this again! Use join\-cluster on the secondary nodes. + Please read the PDF manual for details. + +\fB create\-resource\fR + usage: create\-resource \fIresource_name\fR \fI/dev/lv/mydata\fR + (further syntax variants are described in the PDF manual). + Create a new resource out of a pre\-existing disk (backing + block device) /dev/lv/mydata (or similar). + The current node will start in primary role, thus + /dev/mars/\fIresource_name\fR will appear after a short time, initially + showing the same contents as the underlying disk /dev/lv/mydata. + It is good practice to name the resource \fIresource_name\fR and the + disk name identical. + +\fB delete\-resource\fR + usage: delete\-resource \fIresource_name\fR + CAUTION! This is dangerous when the network is somehow + interrupted, or when damaged nodes are later re\-surrected + in any way. + + Precondition: the resource must no longer have any members + (see leave\-resource). + This is only needed when you _insist_ on re\-using a damaged + resource for re\-creating a new one with exactly the same + old \fIresource_name\fR. + HINT: best practice is to not use this, but just create a _new_ + resource with a new \fIresource_name\fR out of your local disks. + Please read the PDF manual on potential consequences. + +\fB detach\fR + usage: detach \fIresource_name\fR + Detaches the local disk (backing block device) from the + MARS resource. + Caution! you may read data from the local disk afterwards, + but ensure that no data is written to it! + Otherwise, you are likely to produce harmful inconsistencies. + When running in primary role, /dev/mars/$res will also disappear. + This does not change the state of {fetch,replay}. + For a complete local shutdown of the resource, use 'marsadm down'. + +\fB disconnect\fR + usage: disconnect \fIresource_name\fR + See pause\-fetch\-local. + +\fB disconnect\-global\fR + usage: disconnect\-global \fIresource_name\fR + Like pause\-fetch\-local, but affects all resource members + in the cluster (remotely). + +\fB disconnect\-local\fR + usage: disconnect\-local \fIresource_name\fR + See pause\-fetch\-local. + +\fB down\fR + usage: down \fIresource_name\fR + Shortcut for detach + pause\-sync + pause\-fetch + pause\-replay. + +\fB get\-emergency\-limit\fR + usage: get\-emergency\-limit \fIresource_name\fR + Counterpart of set\-emergency\-limit (per\-resource emergency limit) + +\fB get\-sync\-limit\-value\fR + usage: get\-sync\-limit\-value (no parameters) + For retrieval of the value set by set\-sync\-limit\-value. + +\fB invalidate\fR + usage: invalidate \fIresource_name\fR + Only useful on a secondary node. + Forces MARS to consider the local replica disk as being + inconsistent, and therefore starting a fast full\-sync from + the currently designated primary node (which must exist; + therefore avoid the 'secondary' command). + This is usually needed for resolving emergency mode. + When having k=2 replicas, this can be also used for + quick\-and\-simple split\-brain resolution. + In other cases, or when the split\-brain is not resolved by + this command, please use the 'leave\-resource' / 'join\-resource' + method as described in the PDF manual (in the right order as + described there). + +\fB join\-cluster\fR + usage: join\-cluster \fIhostname_of_primary\fR + Establishes a new cluster membership. + This must be called once on any new cluster member. + This is a prerequisite for join\-resource. + +\fB join\-resource\fR + usage: join\-resource \fIresource_name\fR \fI/dev/lv/mydata\fR + (further syntax variants are described in the PDF manual). + The resource \fIresource_name\fR must have been already created on + another cluster node, and the network must be healthy. + The contents of the local replica disk /dev/lv/mydata will be + overwritten by the initial fast full sync from the currently + designated primary node. + After the initial full sync has finished, the current host will + act in secondary role. + For details on size constraints etc, refer to the PDF manual. + +\fB leave\-cluster\fR + usage: leave\-cluster (no parameters) + This can be used for final deconstruction of a cluster member. + Prior to this, all resources must have been left + via leave\-resource. + Notice: this will never destroy the cluster UID on the /mars/ + filesystem. + Please read the PDF manual for details. + +\fB leave\-resource\fR + usage: leave\-resource \fIresource_name\fR + Precondition: the local host must be in secondary role. + Stop being a member of the resource, and thus stop all + replication activities. The status of the underlying disk + will remain in its current state (whatever it is). + +\fB log\-delete\fR + usage: log\-delete \fIresource_name\fR + When possible, globally delete at most one old transaction logfile + which is known to be superfluous, i.e. all secondaries no longer + need to replay it. + Hint: use this only for testing and manual inspection. + For regular maintainance cron jobs, please prefer log\-delete\-all. + +\fB log\-delete\-all\fR + usage: log\-delete\-all \fIresource_name\fR + When possible, globally delete all old transaction logfiles which + are known to be superflous, i.e. all secondaries no longer need + to replay them. + This must be regularly called by a cron job or similar, in order + to prevent overflow of the /mars/ directory. + For details and best practices, please refer to the PDF manual. + +\fB log\-purge\-all\fR + usage: log\-purge\-all \fIresource_name\fR + This is potentially dangerous. + Use this only if you are really desperate in trying to resolve a + split brain. Use this only after reading the PDF manual! + +\fB log\-rotate\fR + usage: log\-rotate \fIresource_name\fR + Only useful at the primary side. + Start writing transaction logs into a new transaction logfile. + This must be regularly called by a cron job or similar. + For details and best practices, please refer to the PDF manual. + +\fB pause\-fetch\fR + usage: pause\-fetch \fIresource_name\fR + See pause\-fetch\-local. + +\fB pause\-fetch\-global\fR + usage: pause\-fetch\-global \fIresource_name\fR + Like pause\-fetch\-local, but affects all resource members + in the cluster (remotely). + +\fB pause\-fetch\-local\fR + usage: pause\-fetch\-local \fIresource_name\fR + Stop fetching transaction logfiles from the current + designated primary. + This is independent from any {pause,resume}\-replay operations. + Only useful on a secondary node. + +\fB pause\-replay\fR + usage: pause\-replay \fIresource_name\fR + See pause\-replay\-local. + +\fB pause\-replay\-global\fR + usage: pause\-replay\-global \fIresource_name\fR + Like pause\-replay\-local, but affects all resource members + in the cluster (remotely). + +\fB pause\-replay\-local\fR + usage: pause\-replay\-local \fIresource_name\fR + Stop replaying transaction logfiles for now. + This is independent from any {pause,resume}\-fetch operations. + This may be used for freezing the state of your replica for some + time, if you have enough space on /mars/. + Only useful on a secondary node. + +\fB pause\-sync\fR + usage: pause\-sync \fIresource_name\fR + See pause\-sync\-local. + +\fB pause\-sync\-global\fR + usage: pause\-sync\-global \fIresource_name\fR + Like pause\-sync\-local, but affects all resource members + in the cluster (remotely). + +\fB pause\-sync\-local\fR + usage: pause\-sync\-local \fIresource_name\fR + Pause the initial data sync at current stage. + This has only an effect if a sync is actually running (i.e. + there is something to be actually synced). + Don't pause too long, because the local replica will remain + inconsistent during the pause. + Use this only for limited reduction of system load. + Only useful on a secondary node. + +\fB primary\fR + usage: primary \fIresource_name\fR + Promote the resource into primary role. + This is necessary for /dev/mars/$res to appear on the local host. + Notice: by concept there can be only _one_ designated primary + in a cluster at the same time. + The role change is automatically distributed to the other nodes + in the cluster, provided that the network is healthy. + The old primary node will _automatically_ go + into secondary role first. This is different from DRBD! + With MARS, you don't need an intermediate 'secondary' command + for switching roles. + It is usually better to _directly_ switch the primary roles + between both hosts. + When \-\-force is not given, a planned handover is started: + the local host will only become actually primary _after_ the + old primary is gone, and all old transaction logs have been + fetched and replayed at the new designated priamry. + When \-\-force is given, no handover is attempted. A a consequence, + a split brain situation is likely to emerge. + Thus, use \-\-force only after an ordinary handover attempt has + failed, and when you don't care about the split brain. + For more details, please refer to the PDF manual. + +\fB resize\fR + usage: resize \fIresource_name\fR + Prerequisite: all underlying disks (usually /dev/vg/$res) must + have been already increased, e.g. at the LVM layer (cf. lvresize). + Causes MARS to re\-examine all sizing constraints on all members of + the resource, and increase the global logical size of the resource + accordingly. + Shrinking is currently not yet implemented. + When successful, /dev/mars/$res at the primary will be increased + in size. In addition, all secondaries will start an incremental + fast full\-sync to get the enlarged parts from the primary. + +\fB resume\-fetch\fR + usage: resume\-fetch \fIresource_name\fR + See resume\-fetch\-local. + +\fB resume\-fetch\-global\fR + usage: resume\-fetch\-global \fIresource_name\fR + Like resume\-fetch\-local, but affects all resource members + in the cluster (remotely). + +\fB resume\-fetch\-local\fR + usage: resume\-fetch\-local \fIresource_name\fR + Start fetching transaction logfiles from the current + designated primary node, if there is one. + This is independent from any {pause,resume}\-replay operations. + Only useful on a secondary node. + +\fB resume\-replay\fR + usage: resume\-replay \fIresource_name\fR + See resume\-replay\-local. + +\fB resume\-replay\-global\fR + usage: resume\-replay\-global \fIresource_name\fR + Like resume\-replay\-local, but affects all resource members + in the cluster (remotely). + +\fB resume\-replay\-local\fR + usage: resume\-replay\-local \fIresource_name\fR + Restart replaying transaction logfiles, when there is some + data left. + This is independent from any {pause,resume}\-fetch operations. + This should be used for unfreezing the state of your local replica. + Only useful on a secondary node. + +\fB resume\-sync\fR + usage: resume\-sync \fIresource_name\fR + See resume\-sync\-local. + +\fB resume\-sync\-global\fR + usage: resume\-sync\-global \fIresource_name\fR + Like resume\-sync\-local, but affects all resource members + in the cluster (remotely). + +\fB resume\-sync\-local\fR + usage: resume\-sync\-local \fIresource_name\fR + Resume any initial / incremental data sync at the stage where it + had been interrupted by pause\-sync. + Only useful on a secondary node. + +\fB secondary\fR + usage: secondary \fIresource_name\fR + Promote all cluster members into secondary role, globally. + In contrast to DRBD, this is not needed as an intermediate step + for planned handover between an old and a new primary node. + The only reasonable usage is before the last leave\-resource of the + last cluster member, immediately before leave\-cluster is executed + for final deconstruction of the cluster. + In all other cases, please prefer 'primary' for direct handover + between cluster nodes. + Notice: 'secondary' sets the global designated primary node + to '(none)' which in turn prevents the execution of 'invalidate' + or 'join\-resource' or 'resize' anywhere in the cluster. + Therefore, don't unnecessarily give 'secondary'! + +\fB set\-emergency\-limit\fR + usage: set\-emergency\-limit \fIresource_name\fR \fIvalue\fR + Set a per\-resource emergency limit for disk space in /mars. + See PDF manual for details. + +\fB set\-sync\-limit\-value\fR + usage: set\-sync\-limit\-value \fInew_value\fR + Set the maximum number of resources which should by syncing + concurrently. + +\fB up\fR + usage: up \fIresource_name\fR + Shortcut for attach + resume\-sync + resume\-fetch + resume\-replay. + +\fB wait\-cluster\fR + usage: wait\-resource [\fIresource_name\fR] + Waits until a ping\-pong communication has succeeded in the + whole cluster (or only the members of \fIresource_name\fR). + NOTICE: this is extremely useful for avoiding races when scripting + in a cluster. + +\fB wait\-connect\fR + usage: wait\-connect [\fIresource_name\fR] + See wait\-cluster. + +\fB wait\-resource\fR + usage: wait\-resource \fIresource_name\fR + [[attach|fetch|replay|sync][\-on|\-off]] + Wait until the given condition is met on the resource, locally. + +\fB wait\-umount\fR + usage: wait\-umount \fIresource_name\fR + Wait until /dev/mars/\fIresource_name\fR has disappeared in the + cluster (even remotely). + Useful on both primary and secondary nodes. + + +.SH EXPERT COMMANDS +\fB delete\-file\fR + usage: delete\-file \fIpath\fR + VERY dangerous! + Only for experts. + +\fB fake\-sync\fR + usage: fake\-sync \fIresource_name\fR + Attention: this is potentially dangerous. + Only for experts. + Please read the PDF manual to understand the risks! + +\fB get\-link\fR + usage: get\-link \fIpath\fR + Only for experts. + Will disappear in a future MARS release. + +\fB set\-link\fR + usage: set\-link \fIpath\fR \fIvalue\fR + Only for experts. + Will disappear in a future MARS release. + +\fB set\-replay\fR + usage: set\-replay \fIresource_name\fR + VERY dangerous! + Only for experts. + + +.SH 1&1 INTERNAL COMMANDS +\fB get\-connect\-pref\-list\fR + usage: get\-connect\-pref\-list \fIresource_name\fR + Provisionary command for internal use at 1&1. Will be replaced by + a better concept somewhen. + Shows the outcome of set\-connect\-pref\-list. + +\fB get\-sync\-pref\-list\fR + usage: get\-sync\-pref\-list \fIresource_name\fR + Provisionary command for internal use at 1&1. Will be replaced by + a better concept somewhen. Shows the outcome of set\-sync\-pref\-list. + +\fB set\-connect\-pref\-list\fR + usage: set\-connect\-pref\-list \fIresource_name\fR \fIhost_list\fR + Provisionary command for internal use at 1&1. Will be replaced by + a better concept somewhen. The \fIhost_list\fR must be comma\-separated. + +\fB set\-sync\-pref\-list\fR + usage: set\-sync\-pref\-list \fIresource_name\fR \fIhost_list\fR + Provisionary command for internal use at 1&1. Will be replaced by + a better concept somewhen. The \fIhost_list\fR must be comma\-separated. + + +.SH DEPRECATED COMMANDS +\fB role\fR + usage: role \fIresource_name\fR + Deprecated. + Please use the macro command 'view\-role' instead. + For even better summary information, use plain 'view'. + +\fB show\fR + usage: show \fIresource_name\fR + Deprecated old low\-level tool. Don't use. Use macros instead. + +\fB show\-errors\fR + usage: show\-errors \fIresource_name\fR + Deprecated old low\-level tool. Don't use. Use macros instead. + +\fB show\-info\fR + usage: show\-info \fIresource_name\fR + Deprecated old low\-level tool. Don't use. Use macros instead. + +\fB show\-state\fR + usage: show\-state \fIresource_name\fR + Deprecated old low\-level tool. Don't use. Use macros instead. + +\fB state\fR + usage: state \fIresource_name\fR + Deprecated. + Please use the macro command 'view\-role' instead. + For even better summary information, use plain 'view'. + + +.SH SELECTED MACROS +This is a small selection of some useful macros for humans. For a full list and for detailed information as well as for scripting instructions, please refer to the PDF manual. + +\fB view all\fR + Show standard information about the local state of MARS at the local host. + +\fB view\-replstate all\fR + Show only the replication state part of plain view. + +\fB view\-flags all\fR + Show only the flags part from plain view. + +\fB view\-primarynode all\fR + Display (none) or the hostname of the current designated primary. + +\fB view\-the\-pretty\-err\-msg all\fR + Show reported error messages. + +\fB view\-the\-pretty\-wrn\-msg all\fR + Show reported warnings. + +\fB view\-is\-emergency all\fR + Tell whether emergency mode has been entered. + +\fB view\-rest\-space\fR + Show the internal rest space calculations used for calculating emergency mode. This value should not go down to 0. + +\fB view\-get\-disk all\fR + Show the underlying disk name for each resource. + +.SH AUTHOR +Written by Thomas Schoebel\-Theuer. + +.SH COPYRIGHT +Copyright 2010\-2015 Thomas Schoebel\-Theuer + +Copyright 2011\-2015 1&1 Internet AG + +This is free software; see the source for copying conditions. +There is NO warranty; not even for MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE. + +.SH NOTES +http://schoebel.github.io/mars/ + +http://github.com/schoebel/mars/