<?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="gfhost.1">

<refentryinfo><date>14 Mar 2019</date></refentryinfo>

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

<refnamediv id="name">
<refname>gfhost</refname>
<refpurpose>Gfarm filesystem node management command</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis">
<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfhost</command>
    <group choice="opt" rep="norepeat">
      <arg choice="plain" rep="norepeat">-H</arg>
      <arg choice="plain" rep="norepeat">-l</arg>
      <arg choice="plain" rep="norepeat">-M</arg>
    </group>
    <arg choice="opt" rep="norepeat">-iLprUv</arg>
    <arg choice="opt" rep="norepeat">-P <replaceable>path</replaceable></arg>
    <arg choice="opt" rep="norepeat">-a <replaceable>architecture</replaceable></arg>
    <arg choice="opt" rep="norepeat">-D <replaceable>domain-name</replaceable></arg>
    <arg choice="opt" rep="norepeat">-j <replaceable>concurrency</replaceable></arg>
    <arg choice="opt" rep="repeat"><replaceable>hostname</replaceable></arg>
</cmdsynopsis>

<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfhost</command>
    <arg choice="plain" rep="norepeat">-c</arg>
    <arg choice="opt"  >-P <replaceable>path</replaceable></arg>
    <arg choice="plain" rep="norepeat">-a <replaceable>architecture</replaceable></arg>
    <arg choice="plain" rep="norepeat">-p <replaceable>port-number</replaceable></arg>
    <arg choice="opt"  >-n <replaceable>number-of-CPUs</replaceable></arg>
    <arg choice="opt"  >-f <replaceable>flags</replaceable></arg>
    <arg choice="plain" rep="norepeat"><replaceable>hostname</replaceable></arg>
</cmdsynopsis>

<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfhost</command>
    <arg choice="plain" rep="norepeat">-m</arg>
    <arg choice="opt" rep="norepeat">-P <replaceable>path</replaceable></arg>
    <arg choice="opt" rep="norepeat">-a <replaceable>architecture</replaceable></arg>
    <arg choice="opt" rep="norepeat">-p <replaceable>port-number</replaceable></arg>
    <arg choice="opt" rep="norepeat">-n <replaceable>number-of-CPUs</replaceable></arg>
    <arg choice="opt"  >-f <replaceable>flags</replaceable></arg>
    <arg choice="plain" rep="norepeat"><replaceable>hostname</replaceable></arg>
</cmdsynopsis>

<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfhost</command>
    <arg choice="plain" rep="norepeat">-d</arg>
    <arg choice="opt  " rep="norepeat">-P <replaceable>path</replaceable></arg>
    <arg choice="plain" rep="repeat"><replaceable>hostname</replaceable></arg>
</cmdsynopsis>

<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfhost</command>
    <arg choice="plain" rep="norepeat">-R</arg>
    <arg choice="opt  " rep="norepeat">-P <replaceable>path</replaceable></arg>
</cmdsynopsis>

<!-- Options sorted by alphabetical order
    (default)	<function moreinfo="none"> display hostname only
    -A		alter hostname, for -m
    -a <arch>	CPU architecture, for (default)/-c/-H/-l/-M/-m
    -c		<function moreinfo="none"> create a host in MetaDB
    -D <domain>	only display specified domain, for (default)/-H/-l/-M
    -d		<function moreinfo="none"> delete a host from MetaDB
    -f		XXX NOTYET ??? force ???, for -d
    -H		<function moreinfo="none"> display information replied from the hosts
    -i		ignore "address_use" directive, for (default)/-H/-l
    -j <number>	concurrency, for (default)/-H/-l
    -L		display by load average order, for (default)/-H/-l
    -l		<function moreinfo="none"> display with long format
    -M		<function moreinfo="none"> display hosts in MetaDB
    -m		<function moreinfo="none"> modify a host in MetaDB
    -n <number>	number of CPUs, for -c/-m
    -P <path>   pathname or Gfarm URL to identify MetaDB
    -R		<function moreinfo="none"> restore hosts to MetaDB
    -r		display by reverse order, for (default)/-H/-l/-M
    -U		UDP only, do not try authentication, for (default)/-H/-l
    -u		display by plain order (don't sort), for (default)/-H/-l/-M
    -v		verbose, print error message, for (default)/-H/-l
-->

<!-- XXX NOTYET
  host-type
	- don't put any file data, use as a CPU server
	- don't use CPU, use as a file server
	  by setting ncpu==0, or arch==NIL?
	- flag which means temporary unavailable, for hardware maintenance.
	  reference from replication metadata still remains,
	  but the host won't be accessed, if the flag is set.
  capability
	- CPU speed, integer/floating-point performance
	- disk I/O speed / mount point
	- disk capacity, free space reservation / mount point
	- network I/O speed
	- network topology, how?
-->

</refsynopsisdiv>

<refsect1 id="description"><title>DESCRIPTION</title>
<para><command moreinfo="none">gfhost</command> displays the
information of filesystem nodes.  It also registers a new filesystem
node, and modifies and deletes the registered information.
</para>
<para>
The function of <command moreinfo="none">gfhost</command> is
determined by the option, -c, -m, -d, -H, -l, -M, and -R.
These functions are mutually exclusive, and only one option
among them can be specified.
If none of them is specified, filesystem nodes will be listed, which
is the default function of <command moreinfo="none">gfhost</command>.
</para>
</refsect1>

<refsect1 id="functions"><title>FUNCTIONS</title>
<para>
  The Gfarm filesystem manages filesystem nodes at the gfmd metadata
  server.  The -c option registers a new filesystem node.  The -m
  option modifies the registered information.  The -d option removes
  an entry of the filesystem node and related file metadata.  The -R
  option restores the dumped information of filesystem nodes, which is
  obtained by the -M option.  These operations require gfarmadm
  privilege.
</para>
<para>
  The -H, -l, -M, or no functional option is specified,
  <command moreinfo="none">gfhost</command> displays filesystem node
  information.
  The -M lists the registered information of filesystem nodes at the
  gfmd metadata server.  Other options
  access <command moreinfo="none">gfsd</command> filesystem daemon to
  obtain more information and also to check the accessibility to a
  filesystem node.  The -i, -j, -U and -v options are available.
</para>
<para>
  When hostnames of filesystem nodes are not specified,
  all registered hosts will be
  displayed, but you can limit the type of hosts displayed 
  by the -a and/or -D option.
  By default, hosts are displayed in alphabetical order, but you can
  change this by the -L, -p, or -r option, although the -L option is
  effective with -H or -l option.
</para>
<para>
  The following is a list of the functions of the <command moreinfo="none">gfhost</command>
  command. You shouldn't specify more than one function at a time.
</para>
<variablelist>

  <varlistentry>
    <term>&lt;none&gt;</term>
    <listitem>
      <para>
	When no function is specified,
	<command moreinfo="none">gfhost</command> accesses to <command moreinfo="none">gfsd</command>,
	and displays the host names which are currently available.
	They are displayed in alphabetical order, by default.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-c</option></term>
    <listitem>
      <para>
	Creates a host entry of a filesystem node that is specified
	by the argument.
	The -a option is mandatory, which specifies
	the architecture of the filesystem node.
	The -p option is mandatory, which specifies
	the port number of <command moreinfo="none">gfsd</command> on
	the filesystem node.
	The -n option is optional, which specifies the number of CPUs
	of the filesystem node.  When it is omitted, 1 CPU is
	assumed.
	The -f option is optional, which specifies the flag of the
	file system node.  When it is omitted, 0 is assumed.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-d</option></term>
    <listitem>
      <para>
	Deletes a host entry.  All file metadata is also
	asynchronously updated to delete invalid replica entries for
	the removed filesystem node, and to create file replicas if
	required, automatically.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-l</option></term>
    <listitem>
      <para>
	Displays in a long format, which consists of the CPU load
	average, authentication method, architecture, the number of
	CPUs, hostname, port number, flags, and the IP address.
      </para>
      <para>
	If the host cannot be accessed due to a machine down or a
	network problem, etc., x.xx/x.xx/x.xx will be displayed in
	the CPU load average field.
	If the host is up, but <command moreinfo="none">gfsd</command> on the host
	cannot be accessed, -.--/-.--/-.-- will be displayed.
      </para>
      <para>
	In the field of the authentication method,
	`G' means the GSI authentication and the encryption,
	`g' means only authentication is performed by GSI and
	actual communication is unprotected plain data (gsi_auth),
	`s' means the gfarm sharedsecret authentication,
	`x' means that the authentication fails,
	and `-' means that the authentication wasn't actually tried.
	With the -U option, there is no authentication method field.
      </para>
      <para>
	In the field of the flags, refer to the -f option.
      </para>
      <para>
	Hostnames are displayed in alphabetical order, by default.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-H</option></term>
    <listitem>
      <para>
	Displays filesystem nodes with the CPU load average and the
	authentication method.
	This function also displays the IP address used to
	access to <command moreinfo="none">gfsd</command> in parentheses just after the hostname.
      </para>
      <para>
	For the field of the CPU load average and the authentication
	method, refer to the -l option.
      </para>
      <para>
	Hostnames are displayed in alphabetical order, by default.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-M</option></term>
    <listitem>
      <para>
	Dumps the metadata information of the registered filesystem
	nodes.
	Hostnames are displayed in alphabetical order, by default.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-m</option></term>
    <listitem>
      <para>
	Modifies the registered metadata information of the filesystem
	node.
	The -a, -p, -n, and/or -f option modify the current value
	of each option.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-R</option></term>
    <listitem>
      <para>
	Restores the metadata information read from standard input.
	The format of the metadata is same as the format
	that the -M function displays.
      </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>-a</option> <parameter moreinfo="none">architecture</parameter></term>
    <listitem>
      <para>
	This option specifies the CPU architecture using a format like
	sparc-sun-solaris8 or i386-redhat8.0-linux, etc.
	If this option is used with the -c or -m function, this means
	the architecture used to add/modify the metadata information.
	If this option is used with -H, -l, -M function or default function,
	this limits hosts to the specified architecture.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-D</option> <parameter moreinfo="none">domain-name</parameter></term>
    <listitem>
      <para>
	This option is used with the -H, -l, -M function or the default
	function to limit hosts to the specified domain.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-i</option></term>
    <listitem>
      <para>
	There is an "address_use" directive in %%SYSCONFDIR%%/gfarm2.conf and
	$HOME/.gfarm2rc to give priorities of network addresses
	for gfarm access.
	This directive works with the <command moreinfo="none">gfhost</command> command,
	but will be ignored, if you specified the -i option with
	<command moreinfo="none">gfhost</command>.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-j</option> <parameter moreinfo="none">concurrency</parameter></term>
    <listitem>
      <para>
	This option specifies the concurrency used for access to
	<command moreinfo="none">gfsd</command>.
	The default value is 10.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-L</option></term>
    <listitem>
      <para>
	Sorts by load average order. This option is effective only with the
	-H and -l functions<!-- XXX FIXME and default function -->.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-n</option> <parameter moreinfo="none">number-of-CPUs</parameter></term>
    <listitem>
      <para>
	This option is used with the -c or -m function, and specifies the
	number of CPUs of the host.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-p</option> <parameter moreinfo="none">port-number</parameter></term>
    <listitem>
      <para>
	This option is used with -c or -m function, and specifies
	the port number of <command moreinfo="none">gfsd</command> on the host.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-f</option> <parameter moreinfo="none">flags</parameter></term>
    <listitem>
      <para>
	This option is used with -c or -m function, and specifies
	the flags of <command moreinfo="none">gfsd</command> on the host.
	Values of flags are constructed by a bitwise-or of the
	following list.
      </para>
      <variablelist>
      <varlistentry>
	<term><constant>1</constant></term>
	<listitem><para>readonly</para></listitem>
      </varlistentry>
      </variablelist>
    </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>-r</option></term>
    <listitem>
      <para>
	Reverses the order of sort.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-u</option></term>
    <listitem>
      <para>
	Plain order. This option stops sorting on the -H, -l, -M function
	or the default function.

	With the -M function, command argument order (if any), or
	the order that the metadata server answers is used for display.

	With the -H, -l function or the default function, the result
	is displayed in the order that each <command moreinfo="none">gfsd</command> answers.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-U</option></term>
    <listitem>
      <para>
	Suppresses authentication attempts by TCP, and only queries
	load average by UDP.
	This option only makes sense if you specified the -H or -l function,
	or if you didn't specify any function. This option
	makes the gfhost command run faster.
	If the -H or -l function is specified, this option makes the 
	authentication method field disappear.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-v</option></term>
    <listitem>
      <para>
	The -H, -l function and the default function don't produce error
	reports on <command moreinfo="none">gfsd</command> accesses;
	these error reports will be produced by this option.
      </para>
    </listitem>
  </varlistentry>

</variablelist>
</refsect1>

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

</refentry>
