<?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>20 Jan 2010</date></refentryinfo>

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

<refnamediv id="name">
<refname>gfhost</refname>
<refpurpose>Gfarm host maintenance 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="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" rep="norepeat">-A</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> is used to display and maintain
information about filesystem nodes. The function that 
<command moreinfo="none">gfhost</command> performs is determined by an option, -c, -d,
-H, -l, -M, -m, -R.
These functions are mutually exclusive, and only one option
among them can be specified.
If none of them is specified, host name will be displayed as
the default function of <command moreinfo="none">gfhost</command>.
</para>
</refsect1>

<refsect1 id="functions"><title>FUNCTIONS</title>
<para>
  Metadata in the metadata server will be accessed by function -c, -d,
  -M, -m or
  -R. These functions add/delete/display/modify/restore host information
  in the metadata.
</para>
<para>
  If -H, -l or -M is specified, or none of the functions are specified,
  <command moreinfo="none">gfhost</command> displays filesystem node information.
  The -M function only accesses information in the metadata server.
  Display functions other than -M also access <command moreinfo="none">gfsd</command>,
  which is running on filesystem nodes. For functions which access
  <command moreinfo="none">gfhost</command>, the access option can be specified
  by options -i, -j, -U and -v.
</para>
<para>
  You don't have to specify hostnames for display functions.
  In that case, all hosts which are registered in metadata will be
  displayed, but you can limit the type of hosts displayed 
  by the -a or -D option.
  By default, hosts are displayed in alphabetical order, but you can
  change this by the -L, -p, or -r options. Although the -L option is ignored
  in the -M function <!-- XXX FIXME BEGIN --> and in the default function.
  <!-- FIXME END -->.
</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 functions at a time.
</para>
<variablelist>

  <varlistentry>
    <term>&lt;none&gt;</term>
    <listitem>
      <para>
	If you don't specify any of the functions,
	<command moreinfo="none">gfhost</command> accesses <command moreinfo="none">gfsd</command>,
	and displays the names of hosts which are currently available
	as its default function.
	Hostnames are displayed in alphabetical order, by default.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-c</option></term>
    <listitem>
      <para>
	Creates the metadata information for the host that is specified
	in the argument.
	Option -a is mandatory for this function, this option specifies
	the architecture of the host.
	Option -p is mandatory in this function too, this option specifies
	the port number of <command moreinfo="none">gfsd</command> on the host.
	Option -n may be used to specify the number of CPUs of the host,
	and 1 CPU is assumed, if -n is omitted.
      </para>
      <para>
	<!-- XXX FIXME check hostname duplication -->
	You can specifiy multiple hostnames in this function.
	In that case, the first hostname is treated as the identifier of
	the host, and the host identifier is used for replication
	information management.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-d</option></term>
    <listitem>
      <para>
	Deletes host information from metadata.
	<!-- XXX --> Currently, even hosts which are referred by
	replica catalog can be deleted. But be careful, because
	such deletions cause inconsistencies of metadata.
	<!-- XXX??? must deny deletion, if the host is referred as replica ???
	  In that case, provide -f option to delete hosts which are referred,
	  even. Replication information will be deleted by the -f option.
	  If one want to leave replication information, but don't want to
	  make accesss to a host, use "temporary unavailable" flag. -->
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-H</option></term>
    <listitem>
      <para>
	Displays load average and authentication method.
	With this function, the exact hostname passed by the gfhost command
	arguments will be displayed instead of the canonical host identifier.
	Also, this function displays the IP address used to
	access <command moreinfo="none">gfsd</command> in parentheses just after the hostname.
      </para>
      <para>
	If the host cannot be accessed due to a machine down or
	network problem, etc., x.xx/x.xx/x.xx will be displayed in
	the 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>
	The next field is the authentication method used with the host.
	`G' in this field means GSI authentication and encryption,
	`g' means only authentication is performed by GSI and
	actual communication is unprotected plain data (gsi_auth),
	`s' means gfarm sharedsecret authentication,
	`x' means that the authentication failed,
	and `-' means that the authentication wasn't actually tried.
	If the -U option is specified, this authentication method field
	won't be provided.
      </para>
      <para>
	Hostnames are displayed in alphabetical order, by default.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-l</option></term>
    <listitem>
      <para>
	Displays in the long format.
	This function displays both information retrieved from gfsd
	and the metadata server.
	The types of information retrieved from gfsd are load average and
	authentication method.
	And the types of information retrieved from the metadata server are
	architecture name, number of CPUs and host identifier.
	IP address will be displayed in parentheses just after the
	hostname used for the access to <command moreinfo="none">gfsd</command>.
      </para>
      <para>
	If the host cannot be accessed due to a machine down or
	network problem, etc., x.xx/x.xx/x.xx will be displayed in
	the 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>
	The next field is the authentication method used with the host.
	`G' in this field means GSI authentication and encryption,
	`g' means only authentication is performed by GSI and
	actual communication is unprotected plain data (gsi_auth),
	`s' means gfarm sharedsecret authentication,
	`x' means that the authentication failed,
	and `-' means that the authentication wasn't actually tried.
	If that -U option is specified, this authentication method field
	won't be provided.
      </para>
      <para>
	Hostnames are displayed in alphabetical order, by default.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-M</option></term>
    <listitem>
      <para>
	The metadata information of the hosts will be displayed.
	Hostnames are displayed in alphabetical order, by default.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-m</option></term>
    <listitem>
      <para>
	Modifies metadata information of the host, by specifying
	the host identifier.
	The -a and -n options overwrite the current value of each option.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-R</option></term>
    <listitem>
      <para>
	Restores 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>-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>
