<?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">

<!-- $Id$ -->

<refentry id="confog-gfarm.8">

<refentryinfo><date>20 Jan 2015</date></refentryinfo>

<refmeta>
<refentrytitle>config-gfarm</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo>Gfarm</refmiscinfo>
</refmeta>

<refnamediv id="name">
<refname>config-gfarm</refname>
<refpurpose>Gfarmのメタデータサーバのセットアップ</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis">
<cmdsynopsis sepchar=" ">
  <command moreinfo="none">config-gfarm</command>
    <arg choice="opt" rep="norepeat"><replaceable>オプション</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para>
<command moreinfo="none">config-gfarm</command>は、
Gfarm ファイルシステムのメタサーバをセットアップするためのユーティリティです。
メタデータサーバのサーバプログラムは'gfmd'と呼ばれています。
Gfarmの開発、評価、またはテストといった
私的な用途でファイルシステムを使用する場合を除き、
<command moreinfo="none">config-gfarm</command>を実行するためには、
ルート権限が必要です。
</para>

<para>
<command moreinfo="none">config-gfarm</command>は下記に示した順に処理を実行します。
</para>

<orderedlist numeration="arabic" inheritnum="ignore" continuation="restarts">
<listitem>
<para>
バックエンドDBをセットアップします。
</para>
</listitem>

<listitem>
<para>
Gfarmの設定ファイル
<filename moreinfo="none">%%SYSCONFDIR%%/gfarm2.conf</filename>や
<filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename>を生成します。
</para>
</listitem>

<listitem>
<para>
バックエンドDBや、<command moreinfo="none">gfmd</command>と呼ばれる
Gfarmメタデータサーバを起動/停止するためのスクリプト(または、設定ファイル)を作成します。
</para>

<para>
大抵のOSにおいて、
<command moreinfo="none">config-gfarm</command>は、
起動/停止スクリプト<command moreinfo="none">gfmd</command>と
<command moreinfo="none">gfarm-pgsql</command>を
<filename moreinfo="none">/etc/init.d</filename>または
<filename moreinfo="none">/etc/rc.d/init.d</filename>に置きます。
(どちらに置くのかは、OSに依存します。)
</para>

<para>
Red Hat Enterprise Linux 7 またはそれ以降のsystemdで動作するLinuxにおいて、
<command moreinfo="none">config-gfarm</command>は、
ユニット設定ファイルである<filename moreinfo="none">gfmd.service</filename>や
<filename moreinfo="none">gfarm-pgsql.service</filename>を
<filename moreinfo="none">/etc/systemd/system</filename>ディレクトリに置きます。
その後、
<command moreinfo="none">systemctl enable gfmd.service</command>、
<command moreinfo="none">systemctl enable gfarm-pgsql.service</command>
を順に実行します。
</para>
</listitem>

<listitem>
<para>
バックエンドDBや、<command moreinfo="none">gfmd</command>を起動します。
</para>
</listitem>

<listitem>
<para>
<command moreinfo="none">unconfig-gfarm.sh</command> というスクリプトを
%%SYSCONFDIR%% 上に作成します。
このスクリプトは、メタデータサーバのセットアップの取り消しを行います。
<command moreinfo="none">gfmd</command> とバックエンドDBを停止し、
<command moreinfo="none">config-gfarm</command> によって作成されたファイル
(<command moreinfo="none">unconfig-gfarm.sh</command> スクリプト自身を含む)
をすべて消去します。
</para>
</listitem>
</orderedlist>

<para>
<command moreinfo="none">config-gfarm</command>を使用して
メタデータサーバをセットアップする前に、
<command moreinfo="none">config-gfarm -t</command>を実行することを推奨します。
<option>-t</option>オプションを付けて実行することにより、
セットアップする代わりに全ての設定パラメータを表示します。
</para>

<screen>
$ config-gfarm -t
prefix                 [--prefix]:
metadata backend             [-b]: postgresql
(available backend: postgresql )
metadata     directory       [-l]: /var/gfarm-pgsql
metadata log directory       [-L]: /var/gfarm-pgsql/pg_xlog
postgresql admin user        [-U]: miles
postgresql admin password    [-W]: (auto generated)
postgresql user              [-u]: gfarm
postgresql password          [-w]: (auto generated)
postgresql prefix            [-P]: /usr
postgresql version           [-V]: 9.2
postgresql XML supported     [-X]: no
metadata replication         [-r]: no
metaserver hostname          [-h]: host1.example.org
matadata admin user          [-A]: miles
matadata admin dn            [-D]:
portmaster port              [-p]: 10602
gfmd port                    [-m]: 601
auth type                    [-a]: sharedsecret
rc script for gfmd               : /etc/init.d/gfmd
rc script for backend            : /etc/init.d/gfarm-pgsql
gfmd conf file                   : /etc/gfmd.conf
gfarm client conf file           : /etc/gfarm2.conf
gfmd pid file                    : /var/run/gfmd.pid
backend pid file                 : /var/run/postmaster.pid
</screen>

<para>
[ ]で囲まれたオプション名は、
オプションとして指定できることを意味しています。
</para>

</refsect1>

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

<varlistentry>
<term><option>--prefix</option> <parameter moreinfo="none">パス</parameter></term>
<listitem>
<para>
このオプションを与えた場合、
以下に挙げた<command moreinfo="none">gfmd</command>とバックエンドDBに関連する
複数のパスが設定されます。
具体的には、以下の通りです。
</para>

  <itemizedlist>
  <listitem>
  <para>
  Gfarmのメタデータを置くためのディレクトリ。
  バックエンドDBがPostgreSQLである場合は、
  <filename moreinfo="none">PREFIX/var/gfarm-pgsql</filename>となります。
  また、このパスは<option>-L</option>オプションによって変更可能です。
  <option>--prefix</option>と<option>-l</option>オプションを同時に指定した場合、
  <option>-l</option>オプションが優先されます。
  </para>
  </listitem>

  <listitem>
  <para>
  Gfarmのメタデータに対するログファイルを置くためのディレクトリ。
  バックエンドDBがPostgreSQLである場合は、
  <filename moreinfo="none">PREFIX/var/gfarm-pgsql/pg_xlog</filename>となります。
  また、このパスは<option>-L</option>オプションによって変更可能です。
  <option>--prefix</option>と<option>-L</option>オプションを同時に指定した場合、
  <option>-L</option>オプションが優先されます。
  </para>
  </listitem>

  <listitem>
  <para>
  <command moreinfo="none">gfmd</command>のジャーナルファイルを置くためのディレクトリ。
  これは、<filename moreinfo="none">PREFIX/var/gfarm-metadata/journal</filename>となります。
  また、このパスは<option>-j</option>オプションによって変更可能です。
  <option>--prefix</option>と<option>-j</option>オプションを同時に指定した場合、
  <option>-j</option>オプションが優先されます。
  </para>
  </listitem>

  <listitem>
  <para>
  <command moreinfo="none">gfmd</command>とバックエンドDBのPIDファイル
  を置くためのディレクトリ。
  これは、<filename moreinfo="none">PREFIX/var/run</filename>となります。
  </para>
  </listitem>

  <listitem>
  <para>
  設定ファイルを置くためのディレクトリ。
  これは、<filename moreinfo="none">PREFIX/etc</filename>となります。
  </para>
  </listitem>

  <listitem>
  <para>
  <command moreinfo="none">gfmd</command>とバックエンドDBの起動/停止スクリプト
  を置くためのディレクトリ。
  これは、<filename moreinfo="none">PREFIX/etc/init.d</filename>、または
  <filename moreinfo="none">PREFIX/rc.d/init.d/etc</filename>となります。
  (どちらに置くのかは、OSに依存します。)
  </para>
  </listitem>

  <listitem>
  <para>
  ホスト上でsystemdが起動している場合に、特殊な例外が存在します。
  そのホスト上で<option>--prefix</option>オプションとして空文字列以外を指定すると、
  <command moreinfo="none">config-gfarm</command>はsystemdにユニット設定ファイルを置きません。
  その代わりに、<filename moreinfo="none">PREFIX/etc/init.d</filename>に
  旧形式の起動/停止スクリプトを置きます。
  </para>
  </listitem>

  <listitem>
  <para>
  セットアップの取り消しを行うスクリプト
  <command moreinfo="none">unconfig-gfarm.sh</command>。
  これは、<command moreinfo="none">PREFIX/etc/unconfig-gfarm.sh</command>
  となります。
  </para>
  </listitem>
  </itemizedlist>

<para>
デフォルトでは""(空文字列)です。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-b</option> <parameter moreinfo="none">バックエンドDB</parameter></term>
<listitem>
<para>
バックエンドDBを指定することができます。
現在、"postgresql" (PostgreSQL) だけがサポートされています。
"ldap" (LDAP) は以前にサポートされていましたが、
サポートは継続されていません。
<command moreinfo="none">config-gfarm -t</command>は、
利用可能なバックエンドDBをリスト表示します。
</para>

<para>
"postgresql" がリストに存在する場合、PostgreSQLがデフォルトとして選択されます。
利用可能なバックエンドDBがldapのみである場合、
LDAPがデフォルトとして選択されてしまいます。
リストにないバックエンドDBをGfarmにサポートさせたい場合、
Gfarmを再度コンパイルする必要があるため、
注意してください。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-d</option> <parameter moreinfo="none">ダイジェストタイプ</parameter></term>
<listitem>
<para>
チェックサム計算を有効するとともに、チェックサムのダイジェストタイプを
指定します。
引数 <parameter moreinfo="none">ダイジェストタイプ</parameter> には、
ホスト上にインストールされた OpenSSL ライブラリが対応している
ダイジェストタイプ名を小文字 (例: "md5") で記します。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-U</option> <parameter moreinfo="none">Gfarmの管理ユーザ名</parameter></term>
<listitem>
<para>
Gfarmファイルシステムの管理ユーザ名を指定することができます。
デフォルト値はOSによって異なるため、
<command moreinfo="none">config-gfarm -t</command>を実行し、
ユーザ名を確認してください。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-u</option> <parameter moreinfo="none">ユーザ名</parameter></term>
<listitem>
<para>
このオプションを付与した場合、
セットアップした<command moreinfo="none">gfmd</command>は、
指定したユーザ名でバックエンドDBに接続します。
デフォルトは、"gfarm"です。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-P</option> <parameter moreinfo="none">インストール先のディレクトリ</parameter></term>
<listitem>
<para>
このオプションを付与した場合、
バックエンドDBに対するインストール先のディレクトリ
(例えば、/usr/local)を指定することができます。
<command moreinfo="none">config-gfarm</command>がバックエンドDBの管理コマンド
(例えば、PostgreSQLでの<command moreinfo="none">initdb</command>)を実行する際、
指定したディレクトリの下にこのコマンドが
インストールされていることを前提としています。
このオプションを省略した場合、
<command moreinfo="none">config-gfarm</command>は、
環境変数<envar>PATH</envar>のリストからそのコマンドへのディレクトリを
探し出します。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-V</option> <parameter moreinfo="none">バージョン</parameter></term>
<listitem>
<para>
<command moreinfo="none">config-gfarm</command>に対するバックエンドDBの
バージョンを表示することができます。
多くの場合、<command moreinfo="none">config-gfarm</command>は、
正しいバージョン番号を検出することができます。
そのため、<command moreinfo="none">config-gfarm</command>が
バージョン番号の検出に失敗した場合にのみ、
このオプションを使用することをお勧めします。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-l</option> <parameter moreinfo="none">メタデータ用ディレクトリ</parameter></term>
<listitem>
<para>
バックエンドDBがGfarmのメタデータを記録したファイルを置く
ディレクトリへのパスを指定することができます。
</para>
<para>
バックエンドDBがPostgreSQLである場合、
指定したディレクトリは一般にPGDATAと呼ばれています。
デフォルトでは<filename moreinfo="none">PREFIX/var/gfarm-pgsql</filename>
が設定されており、このPREFIXは<option>--prefix</option>オプションで
与えられた値となります。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-L</option> <parameter moreinfo="none">ログファイル用ディレクトリ</parameter></term>
<listitem>
<para>
バックエンドDBがログファイルを置くディレクトリへのパスを指定することができます。
バックエンドDBがPostgreSQLである場合、
デフォルトでは<filename moreinfo="none">PREFIX/var/gfarm-pgsql/pg_xlog</filename>
が設定されており、このPREFIXは<option>--prefix</option>オプションで
与えられた値となります。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-h</option> <parameter moreinfo="none">ホスト名</parameter></term>
<listitem>
<para>
メタデータサーバを認識するために使用されるホスト名を指定することができます。
デフォルトでは、DNS上におけるそのホストの完全修飾ドメイン名(FQDN)となります。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-j</option> <parameter moreinfo="none">ジャーナルファイル用ディレクトリ</parameter></term>
<listitem>
<para>
<command moreinfo="none">gfmd</command>がジャーナルファイルを置くディレクトリ
のパスを指定することができます。
このオプションは、<option>-r</option>オプションによりメタデータの複製が
有効となっている場合にのみ影響を及ぼします。デフォルトでは、
<filename moreinfo="none">PREFIX/var/gfarm-metadata/journal</filename>
が設定されており、このPREFIXは<option>--prefix</option>オプションで
与えられた値となります。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-A</option> <parameter moreinfo="none">ユーザ名</parameter></term>
<listitem>
<para>
Gfarmファイルシステムの管理者を指定することができます。
このオプションを省略した場合、
<command moreinfo="none">config-gfarm</command>は
<command moreinfo="none">who am i</command>コマンド
を実行することによりユーザ名を取得します。

</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-D</option> <parameter moreinfo="none">サブジェクトDN</parameter></term>
<listitem>
<para>
グローバルユーザとしての管理者のサブジェクトDNを指定することができます。
GSI認証を行う場合、このオプションは必須です。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-p</option> <parameter moreinfo="none">バックエンドDB用ポート番号</parameter></term>
<listitem>
<para>
設定したバックエンドDBが待ち受けるTCPポート番号を指定することができます。
デフォルトでは10602が指定されます。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-m</option> <parameter moreinfo="none">gfmd用ポート番号</parameter></term>
<listitem>
<para>
設定した<command moreinfo="none">gfmd</command>が待ち受ける
TCPポート番号を指定することができます。
デフォルトではプライベートモードの場合に10601、
それ以外では601が指定されます。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-a</option> <parameter moreinfo="none">認証方法</parameter></term>
<listitem>
<para>
認証方法を指定することができます。
現在は、"sharedsecret" または "gsi" を使用することができ、
デフォルトは "sharedsecret"となっています。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--help</option></term>
<listitem>
<para>
このオプションを付与した場合、
config-gfarmの使用法を表示した後、
終了します。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-S</option></term>
<listitem>
<para>
このオプションを付与した場合、
プライベートモードを有効にします。
<command moreinfo="none">config-gfarm</command>は、
ルート権限なしで実行可能なGfarmファイルシステムをセットアップします。
具体的には、以下の通りに設定手順を変更します。
</para>

  <itemizedlist>
  <listitem>
  <para>
  <command moreinfo="none">gfmd</command>のデフォルト待ち受けポート番号
  (<option>-m</option>オプションに対応)は、601から10601に変更されます。
  </para>
  </listitem>

  <listitem>
  <para>
  ユーザマップファイル<filename moreinfo="none">%%SYSCONFDIR%%/usermap</filename>が
  作成されます。
  メタデータサーバは、起動時にこのファイルを読み込みます。
  プライベートモードでない場合、OS上にユーザアカウント _gfarmmd と _gfarmfs が
  作成されていなければいけません。
  ユーザマップファイルがあれば、ユーザアカウントの作成は必要ありません。
  このファイルは、実際のユーザアカウントに対する
  Gfarmシステムユーザのマッピングを定義しています。
  </para>
  </listitem>

  <listitem>
  <para>
  gfsd設定ファイル<filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename>
  が作成されます。
  プライベートモードでない場合、
  gfsdは、メタデータサーバと接続する全てのGfarmプログラムが読み込む前に、
  gfarm設定ファイル
  <filename moreinfo="none">%%SYSCONFDIR%%/gfarm2.conf</filename>
  を読み込みます。
  <filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename>は、
  プライベートモードで起動するgfsd向けにカスタマイズされた
  設定ファイルです。
  </para>
  </listitem>
  </itemizedlist>
<para>
<option>-S</option>オプションは、起動/停止スクリプトや
設定ファイルの位置を決して変更しません。
これらのファイルのデフォルト位置は
通常では特権ユーザの場合のみ書き込み可能であるため、
<command moreinfo="none">config-gfarm</command>はこれらのファイルの生成に
失敗してしまいます。この問題を回避するためには、
<option>--prefix</option>オプションを合わせて指定してください。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-N</option></term>
<listitem>
<para>
このオプションを付与した場合、
<command moreinfo="none">gfmd</command>とバックエンドDBを起動しません。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-f</option></term>
<listitem>
<para>
このオプションを付与した場合、
強制的に存在しているセットアップを上書きします。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-t</option></term>
<listitem>
<para>
このオプションを付与した場合、
人間が読みやすい形式で全ての設定パラメータの値を表示した後、
すぐに終了します。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-T</option></term>
<listitem>
<para>
<option>-t</option>オプションと似ていますが、
設定値をKEY=VALUE形式で表示します。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-r</option></term>
<listitem>
<para>
このオプションを付与した場合、
メタデータサーバ同士でのメタデータの複製を有効にします。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-W</option> <parameter moreinfo="none">バックエンドDB用パスワード</parameter></term>
<listitem>
<para>
バックエンドDBの管理者パスワードを指定することができます。
このオプションは、ユーザ名を指定する<option>-U</option>オプションに対応します。
デフォルトで、パスワードは自動的に生成されます。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-w</option> <parameter moreinfo="none">バックエンドDBへの接続用パスワード</parameter></term>
<listitem>
<para>
設定された<command moreinfo="none">gfmd</command>は、
指定されたパスワードを使用してバックエンドDBと接続します。
このオプションは、ユーザ名を指定する<option>-u</option>オプションに対応します。
デフォルトで、パスワードは自動的に生成されます。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-X</option></term>
<listitem>
<para>
このオプションを付与した場合、
拡張ファイル属性をクエリするためのXML Path言語(XPath)
のサポートを有効にします。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-E</option></term>
<listitem>
<para>
このオプションを付与した場合、
データチェックサムオプションを付けたPostgreSQLセットアップします。
<command moreinfo="none">config-gfarm</command>は、
<option>--data-checksums</option>オプションをPostgreSQLコマンド
<command moreinfo="none">initdb</command>に渡します。
この機能を使用するには、PostgreSQL 9.3またはそれ以降のバージョンが必要です。
このオプションは、バックエンドDBがPostgreSQLであるときのみ機能します。
</para>
</listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1 id="files"><title>FILES</title>
<variablelist>
<varlistentry>
<term><filename moreinfo="none">%%SYSCONFDIR%%/gfarm2.conf</filename></term>
<listitem>
<para>
Gfarmのクライアントが参照する設定ファイル
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">%%SYSCONFDIR%%/gfmd.conf</filename></term>
<listitem>
<para>
<command moreinfo="none">gfmd</command>が参照する設定ファイル
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename></term>
<listitem>
<para>
<command moreinfo="none">gfsd</command>が参照する設定ファイル
(プライベートモードの場合のみ使用)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">%%SYSCONFDIR%%/usermap</filename></term>
<listitem>
<para>
ユーザマッピングを定義しているファイル
(プライベートモードの場合のみ使用)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">/etc/init.d/gfarm-pgsql</filename></term>
<listitem>
<para>
GfarmのバックエンドDBとして動作する
PostgreSQLの起動/停止スクリプトファイル
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">/etc/init.d/gfmd</filename></term>
<listitem>
<para>
<command moreinfo="none">gfmd</command>が参照する起動/停止スクリプトファイルです。
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">/etc/systemd/system/gfarm-pgsql.service</filename></term>
<listitem>
<para>
systemdにより読み込まれ、
GfarmのバックエンドDBとして動作する
PostgreSQLのユニット設定ファイル
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">/etc/systemd/system/gfmd.service</filename></term>
<listitem>
<para>
systemdにより読み込まれる、
<command moreinfo="none">gfmd</command>のユニット設定ファイル
</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>config-gfsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>

</refsect1>

</refentry>
