<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">


<refentry id="gfmdhost.1">

<refentryinfo><date>11 March 2014</date></refentryinfo>

<refmeta>
<refentrytitle>gfmdhost</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Gfarm</refmiscinfo>
</refmeta>

<refnamediv id="name">
<refname>gfmdhost</refname>
<refpurpose>Gfarm metadata server host maintenance command</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis">
<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfmdhost</command>
  <arg choice="opt" rep="norepeat">-l</arg>
  <arg choice="opt" rep="norepeat">-P <replaceable>path</replaceable></arg>
  <arg choice="opt" rep="norepeat">-1</arg>
</cmdsynopsis>

<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfmdhost</command>
  <arg choice="opt" rep="norepeat">-N</arg>
  <arg choice="opt" rep="norepeat">-P <replaceable>path</replaceable></arg>
  <arg choice="opt" rep="norepeat">-1</arg>
</cmdsynopsis>

<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfmdhost</command>
  <group choice="req" rep="norepeat">
    <arg choice="plain" rep="norepeat">-c</arg>
    <arg choice="plain" rep="norepeat">-m</arg>
  </group>
  <arg choice="opt" rep="norepeat">-P <replaceable>path</replaceable></arg>
  <arg choice="opt" rep="norepeat">-1</arg>
  <arg choice="opt" rep="norepeat">-p <replaceable>port-number</replaceable></arg>
  <arg choice="opt" rep="norepeat">-C <replaceable>cluster-name</replaceable></arg>
  <arg choice="opt" rep="norepeat">-t 
    <group choice="req" rep="norepeat">
      <arg choice="plain" rep="norepeat">m</arg>
      <arg choice="plain" rep="norepeat">c</arg>
      <arg choice="plain" rep="norepeat">s</arg>
    </group>
  </arg>
  <arg choice="req" rep="norepeat"><replaceable>metadata-server-name</replaceable></arg>
</cmdsynopsis>

<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfmdhost</command>
  <arg choice="req" rep="norepeat">-d</arg>
  <arg choice="opt" rep="norepeat">-P <replaceable>path</replaceable></arg>
  <arg choice="opt" rep="norepeat">-1</arg>
  <arg choice="req" rep="norepeat"><replaceable>metadata-server-name</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id="description"><title>DESCRIPTION</title>
<para><command moreinfo="none">gfmdhost</command> is used to display and maintain
the information about synchronous and asynchronous replicated metadata
servers.
<command moreinfo="none">gfmdhost</command> has functions which can be selected by
-l, -c, -m and -d options.
These functions are mutually exclusive, and only one option
among them can be specified.
If none of them is specified, registered metadata server (gfmd host)
names will be listed.
</para>
</refsect1>

<refsect1 id="functions"><title>FUNCTIONS</title>
<para>
  The functions of <command moreinfo="none">gfmdhost</command> command are listed in following.
</para>
<variablelist>

  <varlistentry>
    <term>&lt;none&gt;</term>
    <listitem>
      <para>
        If no function is specified,
	all the registered gfmd hosts are displayed
	in alphabetical order.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-l</option></term>
    <listitem>
      <para>
        All registered gfmd hosts are listed with detailed information.
	They are grouped by the clusters and ordered alphabetically.
      </para>
      <para>
        The detailed information is displayed in the following order.
      </para>
      <para><option>Connection State (+|||-|?|x|e|u)</option></para>
      <para>
        "+" means that the gfmd is connected to the master gfmd, and
	its metadata are synchronized.
	"|" means that the gfmd is connected to the master gfmd, but
	its metadata have not been synchronized yet. Note that this
	may happen even on a synchronous slave gfmd, when the slave
	is just connecting to the master, or in the middle of metadata
	transfer even if it has been already synchronized.
        "-" means that the gfmd is not connected to the master gfmd.
	"?" means either the gfmd state is unknown because it's just
	after the connection was established, or the master gfmd is
	Gfarm-2.5.0, but this gfmdhost command is 2.5.1 or later.
	"x" means that the connection with master gfmd was established,
	but automatic synchronization was impossible because of too many
        metadata changes, thus, manual synchronization via dump and
	restore of the backend database is necessary.
	"e" means an error happened, and log file must be checked manually.
	In the case of "x" or "e", it may be displayed even when the
	slave gfmd is down.
        "u" means that the slave gfmd is connected to the master gfmd, but
	the state is not supported by this gfmdhost command.
	This column for the master gfmd is always "+".
      </para>
      <para><option>Server Type (master|slave)</option></para>
      <para>
        This represents whether the gfmd is master or slave.
      </para>
      <para><option>Replication Type (sync|async|-)</option></para>
      <para>
        "sync" means a synchronous replication.
        "async" means an asynchronous replication.
	This column for the master is always "-".
      </para>
      <para><option>Configration of Master Candidate (c|m|s)</option></para>
      <para>
        "m" means the default master gfmd, "c" means a master
	candidate that can be selected as a master gfmd,
	and "s" means a gfmd that is not a master candidate and only
	works for a slave gfmd.
      </para>
      <para><option>Cluster Name</option></para>
      <para>
        A cluster name where the gfmd belongs to.
        "(default)" is displayed for the default cluster.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-N</option></term>
    <listitem>
      <para>
	Displays a hostname and port number of the connected metadata
	server.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-c</option></term>
    <listitem>
      <para>
        Registers the gfmd host that is specified in the argument.
	-C, -p, -t can be optionally specified.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-m</option></term>
    <listitem>
      <para>
        Modifies the gfmd host that is specified in the argument.
	-C, -p, -t can be optionally specified.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-d</option></term>
    <listitem>
      <para>
        Deletes the gfmd host that is specified in the argument.
	The master gfmd cannot be deleted.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-?</option></term>
    <listitem>
      <para>Prints usage.</para>
    </listitem>
  </varlistentry>

</variablelist>
</refsect1>

<refsect1 id="options"><title>OPTIONS</title>
<variablelist>

  <varlistentry>
    <term><option>-C</option> <parameter moreinfo="none">cluster-name</parameter></term>
    <listitem>
      <para>
	This option specifies a cluster name where the gfmd host
	belongs to.  If it is not specified, the default cluster is
	assumed.  This option is only available with -c or -m option.
      </para>
      <para>
	The cluster name means a group of synchronous replicated
	metadata servers.  That is, slave metadata servers in the same
	cluster with the master metadata server are synchronously
	replicated servers that can be changed to a master metadata
	server without any loss of metadata operations.  Other
	metadata servers are asynchronously replicated servers.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-p</option> <parameter moreinfo="none">port-number</parameter></term>
    <listitem>
      <para>
        This option specifies a port number of the gfmd.
	If it is not specified, 601 is assumed.
	This option is only available with -c or -m option.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-t</option> {m|c|s}</term>
    <listitem>
      <para>
        This option specifies a configuration of master candidate.
        It is only available with -c or -m option.
	"m" means the default master, "c" means a master candidate and
	and "s" means a slave only gfmd.
	If it is not specified, "c" is assumed.
	The gfmd configured as the default master cannot be changed to
	a master candidate or slave-only directly.
	If the gfmd that is not the default master is changed to the
	default master by "-t m", the original default master is
        changed to a master candidate at the same time.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-P</option> <parameter moreinfo="none">path</parameter></term>
    <listitem>
      <para>
	This option specifies a pathname or a Gfarm URL to identify
	a metadata server which will be accessed by this command.
	If not specified, "/" is used as the default value.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-1</option></term>
    <listitem>
      <para>
	With this option, gfmdhost only tries to connect with one
	metadata server specified by -P option, or if missing,
	<token>metadb_server_host</token> statement in
	<filename moreinfo="none">gfarm2.conf</filename> file.
      </para>
    </listitem>
  </varlistentry>

</variablelist>
</refsect1>

<refsect1 id="see-also"><title>SEE ALSO</title>
<para>
  <citerefentry>
  <refentrytitle>gfarm2.conf</refentrytitle><manvolnum>5</manvolnum>
  </citerefentry>
</para>
</refsect1>

</refentry>
