<?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 ファイルシステムノード管理コマンド</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="opt"  >-f <replaceable>フラグ</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"  >-f <replaceable>フラグ</replaceable></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>
  Gfarmファイルシステムでは、ファイルシステムノードはメタデータサーバで管理しています。
  機能指定のうち、-c, -d, -M, -m, -R はメタデータサーバのみを
  アクセスし、登録されているホスト情報の追加、削除、表示、変更を行ないます。
  -M 以外は、gfarmadm権限が必要です。
</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 だとみなします。
	オプション -f で、そのホストのフラグを指定します。
	省略した場合は、0 が指定されます。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-d</option></term>
    <listitem>
      <para>
	引数に指定したホスト情報をメタデータから削除します。
	さらに、該当ホストに格納されているファイルの複製情報も削除されます。
	これに伴い、ファイル複製数が足りなくなった場合は自動的に複製が作成されます。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-l</option></term>
    <listitem>
      <para>
	ロングフォーマットで出力します。出力の形式は、ロードアベレージ、
	認証手段、アーキテクチャ、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>
	フラグ欄については -f オプションの項目をご覧ください。
      </para>
      <para>
	デフォールトでは、ホスト名のアルファベット順で表示します。
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>-H</option></term>
    <listitem>
      <para>
	<command moreinfo="none">gfsd</command> に問い合わせて得た情報、
	すなわちロードアベレージと認証手段を表示します。
	また、ホスト名の後に、アクセスに用いられた IP アドレスを括弧で
	囲って表示します。
      </para>
      <para>
	ロードアベレージと認証手段の欄については -l オプションと同様です。
      </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 オプション、-p オプション、-n オプションおよび -f オプションは、
	それぞれ既存の値を置き換えます。
      </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>-f</option> <parameter moreinfo="none">フラグ値</parameter></term>
    <listitem>
      <para>
	-c および -m 機能で、ホスト情報を追加・変更する際に、
	そのホストの <command moreinfo="none">gfsd</command> にフラグ値を設定します。
	フラグ値には以下の数値の bitwise-or を 10 進非負整数で指定します。
      </para>
      <variablelist>
      <varlistentry>
	<term><constant>1</constant></term>
	<listitem><para>読込専用にします。</para></listitem>
      </varlistentry>
      </variablelist>
    </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>
