<?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 ホスト管理コマンド</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>アーキテクチャ</replaceable></arg>
    <arg choice="opt" rep="norepeat">-D <replaceable>ドメイン名</replaceable></arg>
    <arg choice="opt" rep="norepeat">-j <replaceable>並列度</replaceable></arg>
    <arg choice="opt" rep="repeat"><replaceable>ホスト名</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>アーキテクチャ</replaceable></arg>
    <arg choice="plain" rep="norepeat">-p<replaceable>ポート番号</replaceable></arg>
    <arg choice="opt"  >-n<replaceable>CPU数</replaceable></arg>
    <arg choice="plain" rep="norepeat"><replaceable>ホスト名</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>アーキテクチャ</replaceable></arg>
    <arg choice="opt" rep="norepeat">-p<replaceable>ポート番号</replaceable></arg>
    <arg choice="opt" rep="norepeat">-n<replaceable>CPU数</replaceable></arg>
    <arg choice="opt" rep="norepeat">-A</arg>
    <arg choice="plain" rep="norepeat"><replaceable>ホスト名</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>ホスト名</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 <port>	gfsd port number, for -c
    -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
  ホスト種別
	- ファイルデータは置かず、CPU サーバーとしてのみ利用
	- CPU は利用せず、ファイルサーバーとしてのみ利用。
	  これは ncpu==0 とするか、あるいは arch==NIL とする？
	- 故障時等のための、一時的な不使用フラグ。複製情報としての参照は
	  残るが、アクセスは起きない。
  能力
	- CPU 速度。整数演算/浮動小数点演算
	- ディスク I/O 速度 / マウント・ポイント
	- ディスク容量、空き容量予約 / マウント・ポイント
	- ネットワーク I/O 速度
	- ネットワーク・トポロジ。どうやって？
-->

</refsynopsisdiv>

<refsect1 id="description"><title>DESCRIPTION</title>
<para><command moreinfo="none">gfhost</command> は、gfarm のファイルシステムノードに
関する情報の表示や管理を行ないます。<command moreinfo="none">gfhost</command> が
実行する機能は、-c, -d, -H, -l, -M, -m, -R のオプションで指定します。
これら機能の指定は排他的であり、どれか一つだけを指定することができます。
また、一つも指定しなかった場合には、デフォールトの機能であるホスト名
表示が行なわれます。
</para>
</refsect1>

<refsect1 id="functions"><title>FUNCTIONS</title>
<para>
  機能指定のうち、-c, -d, -M, -m, -R はメタデータサーバーのみを
  アクセスし、登録されているホスト情報の追加、削除、表示、変更を行ないます。
</para>
<para>
  機能指定のうち、-H, -l, -M, および特に機能を指定しなかった場合は、
  ファイルシステムノードに関する情報を表示します。
  このうち -M はメタデータサーバーのみをアクセスしますが、
  それ以外の機能はファイルシステムノードで動作している
  <command moreinfo="none">gfsd</command> にもアクセスします。
  <command moreinfo="none">gfsd</command> にアクセスする機能に関しては、そのアクセスに
  関するオプションを -i, -j, -U, -v で指定できます。
</para>
<para>
  表示機能に関しては、ホスト名の指定を省略することができます。この場合、
  メタデータに登録されている全てのホストに関する表示を試みます。
  また、-a および -D オプションで表示するホストの種類を限定
  することもできます。
  表示の順序は、ホスト名のアルファベット順ですが、-L, -r, -u オプションで
  順序を変更することができます。ただし、-M 機能
  <!-- XXX FIXME BEGIN --> と、機能を指定しなかった場合 <!-- FIXME END -->
  に関しては -L オプションは無効です。
</para>
<para>
  下記は、gfhost コマンドの機能一覧です。二つ以上の機能を同時に
  指定することはできません。
</para>
<variablelist>

  <varlistentry>
    <term>無指定</term>
    <listitem>
      <para>
	機能を特に指定しなかった場合、<command moreinfo="none">gfsd</command> への
	問い合わせを行ない、動作しているホストのホスト名のみを表示します。
	デフォールトでは、ホスト名のアルファベット順で表示します。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-c</option></term>
    <listitem>
      <para>
	引数で指定したホストをメタデータへ登録します。
	オプション -a で、そのホストのアーキテクチャを指定する必要があります。
	同様にオプション -p で、そのホストのポート番号を指定する必要があります。
	オプション -n で、そのホストの CPU 数を指定します。省略した場合には
	1 CPU だとみなします。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-d</option></term>
    <listitem>
      <para>
	引数に指定したホスト情報をメタデータから削除します。
	<!-- XXX --> 現在のところ、複製情報として参照されているホストも
	削除できてしまいますが、これを行なうと複製データベースが不整合
	状態となってしまいますので注意が必要です。
	<!-- XXX??? 参照されている場合はエラーではじくようにする ???
	  その場合、別途 -f オプションを提供し、参照されていても削除できる
	  ようにする。このとき、複製情報に関しても削除する。
	  複製情報を残したいが、実際のアクセスはさせたくない場合には、
	  一時的な不使用フラグを用いる。-->
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-H</option></term>
    <listitem>
      <para>
	<command moreinfo="none">gfsd</command> に問い合わせて得た情報、すなわち
	ロードアベレージと認証手段を表示します。
	この機能に関しては、引数でホスト名を指定した場合、表示される
	のは、固有識別子として用いられているホスト名ではなく、引数
	で指定した名前になります。
	また、ホスト名の後に、アクセスに用いられた IP アドレスを括弧で
	囲って表示します。
      </para>
      <para>
	ホストが停止やネットワーク障害のためにアクセスできなかった場合、
	ロードアベレージの部分に x.xx/x.xx/x.xx と表示します。
	ホストが動作しているが、そのホストの <command moreinfo="none">gfsd</command> へ
	アクセスできなかった場合には -.--/-.--/-.-- と表示します。
      </para>
      <para>
	その次の一桁の欄は認証手段で、「G」は GSI 認証および暗号化、
	「g」は認証処理のみ GSI で認証後は保護のない生データ (gsi_auth)、
	「s」は sharedsecret 認証、「x」は認証失敗、「-」は認証を
	試みなかったことを示します。また、「-U」オプション指定時には、
	この認証手段の表示欄はなくなります。
      </para>
      <para>
	デフォールトでは、ホスト名のアルファベット順で表示します。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-l</option></term>
    <listitem>
      <para>
	<command moreinfo="none">gfsd</command> に問い合わせて得た情報、
	すなわちロードアベレージおよび認証手段と、
	メタデータ・サーバーに問い合わせて得た情報、
	すなわちアーキテクチャ名、CPU数を
	全て表示します。またアクセスに用いられたホスト名の後に、
	IP アドレスを括弧で囲って表示します。
      </para>
      <para>
	ホストが停止やネットワーク障害のためにアクセスできなかった場合、
	ロードアベレージの部分に x.xx/x.xx/x.xx と表示します。
	ホストが動作しているが、そのホストの <command moreinfo="none">gfsd</command> へ
	アクセスできなかった場合には -.--/-.--/-.-- と表示します。
      </para>
      <para>
	その次の一桁の欄は認証手段で、「G」は GSI 認証および暗号化、
	「g」は認証処理のみ GSI で認証後は保護のない生データ (gsi_auth)、
	「s」は sharedsecret 認証、「x」は認証失敗、「-」は認証を
	試みなかったことを示します。また、「-U」オプション指定時には、
	この認証手段の表示欄はなくなります。
      </para>
      <para>
	デフォールトでは、ホスト名のアルファベット順で表示します。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-M</option></term>
    <listitem>
      <para>
	メタデータに登録されているホスト情報を表示します。
	デフォールトでは、ホスト名のアルファベット順で表示します。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-m</option></term>
    <listitem>
      <para>
	固有識別子として用いられているホスト名を指定し、メタデータ
	に登録されているホスト情報を変更します。
	-a オプションおよび -n オプションは、それぞれ既存の値を置き換えます。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-R</option></term>
    <listitem>
      <para>
	標準入力からホストに関する情報を読み込み、メタデータに
	追加します。与える情報の形式は、-M 機能の表示形式と同じです。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-?</option></term>
    <listitem>
      <para>引数オプションを表示します。</para>
    </listitem>
  </varlistentry>

</variablelist>
</refsect1>

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

  <varlistentry>
    <term><option>-a</option> <parameter moreinfo="none">アーキテクチャ</parameter></term>
    <listitem>
      <para>
	CPUアーキテクチャを、sparc-sun-solaris8 や i386-redhat8.0-linux の
	ような形式で指定します。
	-c および -m 機能の場合には、追加・変更するホストのアーキテクチャと
	して、このオプションを用います。
	-H, -l, -M および特に機能を指定しなかった場合で、かつ
	ホスト名を省略した場合には、指定したアーキテクチャのホストに
	関してのみ表示を行ないます。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-D</option> <parameter moreinfo="none">ドメイン名</parameter></term>
    <listitem>
      <para>
	-H, -l, -M および特に機能を指定しなかった場合で、かつ
	ホスト名を省略した場合に、このオプションで、表示するドメイン名を
	限定できます。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-i</option></term>
    <listitem>
      <para>
	%%SYSCONFDIR%%/gfarm2.conf ないし $HOME/.gfarm2rc 中で「address_use」を指定すると、
	アクセスに用いるネットワークアドレスに優先順位をつけることができます。
	gfhost コマンドに対しても、この優先順位は影響しますが、-i オプションを
	つけると、この指定を無視して <command moreinfo="none">gfsd</command> にアクセス
	するようになります。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-j</option> <parameter moreinfo="none">並列度</parameter></term>
    <listitem>
      <para>
	<command moreinfo="none">gfsd</command> にアクセスする際の並列度を指定します。
	デフォールトは 10 です。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-L</option></term>
    <listitem>
      <para>
	-H、-l 機能の場合
	<!-- XXX FIXME および機能を指定しなかった場合 -->、このオプションで、
	表示順序を、ロードアベレージ順に変更します。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-n</option> <parameter moreinfo="none">CPU数</parameter></term>
    <listitem>
      <para>
	-c および -m 機能で、ホスト情報を追加・変更する際に、
	そのホストが持つ CPU の数を指定します。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-p</option> <parameter moreinfo="none">ポート番号</parameter></term>
    <listitem>
      <para>
	-c および -m 機能で、ホスト情報を追加・変更する際に、
	そのホストの <command moreinfo="none">gfsd</command> が用いるポート番号を指定します。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-P</option> <parameter moreinfo="none">パス名</parameter></term>
    <listitem>
      <para>
	このコマンドがアクセスするメタデータサーバを特定するための
	パス名または Gfarm URL を指定します。
	省略した場合は、「/」を指定したのと同じ意味になります。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-r</option></term>
    <listitem>
      <para>
	表示を整列している場合、表示の順序を逆にします。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-u</option></term>
    <listitem>
      <para>
	-H, -l, -M および特に機能を指定しなかった場合に、表示する順序を
	アルファベット順に整列するのを止めます。

	-M 機能の場合、引数でホスト名を指定した場合には
	その順序、さもなくばメタデータから取得した順序で表示します。
	
	-H, -l 機能の場合および特に機能を指定しなかった場合、
	ホストに順に問い合わせを行い、返事の返ってきた順序で表示します。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-U</option></term>
    <listitem>
      <para>
	TCP による認証をやめ、
	UDP によるロードアベレージの問い合わせのみを行うようにします。
	このオプションは、-H ないし -l 機能を指定した場合および
	特に機能を指定しなかった場合に意味のあるオプションで、
	実行速度が速くなる効果があります。
	-H ないし -l を指定している場合、このオプションを指定すると、
	認証方式の表示欄がなくなります。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-v</option></term>
    <listitem>
      <para>
	-H ないし -l 機能を指定した場合および特に機能を指定しなかった場合、
	デフォールトでは、gfsd に対する問い合わせに関するエラーメッセージ
	を表示しません。-v オプションを指定すると、このエラーメッセージを
	表示するようになります。
      </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>
