<?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>set up a metadata server of Gfarm</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis">
<cmdsynopsis sepchar=" ">
  <command moreinfo="none">config-gfarm</command>
    <arg choice="opt" rep="norepeat"><replaceable>options</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para>
<command moreinfo="none">config-gfarm</command> is a utility to set up a
metadata server of Gfarm file system.
The server program for a metadata server is named
<command moreinfo="none">gfmd</command>.
<command moreinfo="none">config-gfarm</command> is required to be run with
the root privilege, unless you use the file system for private purpose such
as development, evaluation or test of Gfarm.
</para>

<para>
<command moreinfo="none">config-gfarm</command> performs the following
processes, in that order:
</para>

<orderedlist numeration="arabic" inheritnum="ignore" continuation="restarts">
<listitem>
<para>
Set up the backend database.
</para>
</listitem>

<listitem>
<para>
Generate Gfarm configuration files
<filename moreinfo="none">%%SYSCONFDIR%%/gfarm2.conf</filename> and
<filename moreinfo="none">%%SYSCONFDIR%%/gfmd.conf</filename>.
</para>
</listitem>

<listitem>
<para>
Create scripts (or configuration files) to start/stop the backend
database and <command moreinfo="none">gfmd</command>.
</para>

<para>
On most systems, <command moreinfo="none">config-gfarm</command> puts
start/stop scripts <command moreinfo="none">gfmd</command> and
<command moreinfo="none">gfarm-pgsql</command> onto either
<filename moreinfo="none">/etc/init.d</filename> or
<filename moreinfo="none">/etc/rc.d/init.d</filename>, according to the
operating system.
</para>

<para>
On Linux with systemd such as Red Hat Enterprise Linux 7 or later,
<command moreinfo="none">config-gfarm</command> puts the unit configuration
files <filename moreinfo="none">gfmd.service</filename> and
<filename moreinfo="none">gfarm-pgsql.service</filename> onto
<filename moreinfo="none">/etc/systemd/system</filename>, and then executes
<command moreinfo="none">systemctl enable gfmd.service</command> and
<command moreinfo="none">systemctl enable gfarm-pgsql.service</command>
respectively.
</para>
</listitem>

<listitem>
<para>
Start the backend database and <command moreinfo="none">gfmd</command>.
</para>
</listitem>

<listitem>
Put the script <command moreinfo="none">unconfig-gfarm.sh</command> on
%%SYSCONFDIR%%.
The script does unconfiguration of the metadata server.
It stops <command moreinfo="none">gfmd</command> and the backend database,
and removes all files created by
<command moreinfo="none">config-gfarm</command> including 
<command moreinfo="none">unconfig-gfarm.sh</command> itself.
</listitem>
</orderedlist>

<para>
Before set up a metadata server using
<command moreinfo="none">config-gfarm</command>,
it is recommended to execute
<command moreinfo="none">config-gfarm -t</command>.
With <option>-t</option> option, the sets up is not performed.
Instead, it shows values of all configurable parameters:
</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>
The option name surrounded by [ ] means that you can specify a value with
that option.
</para>

</refsect1>

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

<varlistentry>
<term><option>--prefix</option> <parameter moreinfo="none">path</parameter></term>
<listitem>
<para>
Configure some paths related to <command moreinfo="none">gfmd</command>
and the backend database.
Specifically, the followings are affected.
</para>

  <itemizedlist>
  <listitem>
  <para>
  The directory to put metadata of Gfarm.
  That is <filename moreinfo="none">PREFIX/var/gfarm-pgsql</filename> if
  the backend database is PostgreSQL.
  The path can also be changed by <option>-l</option> option.
  When both options are specified, <option>-l</option> option has preference.
  </para>
  </listitem>

  <listitem>
  <para>
  The directory to put log files about metadata.
  That is <filename moreinfo="none">PREFIX/var/gfarm-pgsql/pg_xlog</filename>
  if the backend database is PostgreSQL.
  The path can also be changed by <option>-L</option> option.
  When both options are specified, <option>-L</option> option has preference.
  </para>
  </listitem>

  <listitem>
  <para>
  The directory to put journal files of
  <command moreinfo="none">gfmd</command>.
  That is
  <filename moreinfo="none">PREFIX/var/gfarm-metadata/journal</filename>.
  The path can also be changed by <option>-j</option> option.
  When both options are specified, <option>-j</option> option has preference.
  </para>
  </listitem>

  <listitem>
  <para>
  The directory to put PID files of <command moreinfo="none">gfmd</command>
  and the backend database.
  That is <filename moreinfo="none">PREFIX/var/run</filename>.
  </para>
  </listitem>

  <listitem>
  <para>
  The directory to put configuration files.
  That is <filename moreinfo="none">PREFIX/etc</filename>.
  </para>
  </listitem>

  <listitem>
  <para>
  The directory of start/stop scripts for
  <command moreinfo="none">gfmd</command> and its backend database.
  That is <filename moreinfo="none">PREFIX/etc/init.d</filename> or
  <filename moreinfo="none">PREFIX/rc.d/init.d/etc</filename> which is
  depending on operating systems.
  </para>
  </listitem>

  <listitem>
  <para>
  If systemd is running on the host, there is a special exception.
  When an empty prefix is given by <option>--prefix</option> option on
  such host, <command moreinfo="none">config-gfarm</command> doesn't
  put unit configuration files for systemd.
  Instead, it puts traditional start/stop scripts at
  <filename moreinfo="none">PREFIX/etc/init.d</filename>.
  </para>
  </listitem>

  <listitem>
  <para>
  The unconfiguration script
  <command moreinfo="none">unconfig-gfarm.sh</command>.
  That is <command moreinfo="none">PREFIX/etc/unconfig-gfarm.sh</command>.
  </para>
  </listitem>
  </itemizedlist>

<para>
The default is "" (empty).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-b</option> <parameter moreinfo="none">backend</parameter></term>
<listitem>
<para>
Specify backend database.
It currently supports "postgresql" (for PostgreSQL) only.
"ldap" (for LDAP) was supported in the past, but not maintained any longer.
<command moreinfo="none">config-gfarm -t</command> lists which backend
databases are available.
</para>

<para>
PostgreSQL is chosen by default if "postgresql" is in the list.
If the available backend is "ldap" only, it is still chosen by default.
Note that you need to recompile Gfarm if you'd like to make Gfarm on
your system support a backend database not in the list.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-d</option> <parameter moreinfo="none">digest_type</parameter></term>
<listitem>
<para>
Enable checksum calculation and specify the digest type of the checksum.
The <parameter moreinfo="none">digest_type</parameter> argument is a
lower-case name which is supported by the OpenSSL library on the host,
such as "md5".
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-U</option> <parameter moreinfo="none">username</parameter></term>
<listitem>
<para>
Specify administrator's username of the Gfarm file system.
Since the default value differs depending on operating systems, execute
<command moreinfo="none">config-gfarm -t</command> to confirm the username.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-u</option> <parameter moreinfo="none">username</parameter></term>
<listitem>
<para>
The configured <command moreinfo="none">gfmd</command> will connect to
the backend database as the specified username.
The default is "gfarm".
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-P</option> <parameter moreinfo="none">prefix</parameter></term>
<listitem>
<para>
Specify an installation prefix of the backend database (e.g. /usr/local).
When <command moreinfo="none">config-gfarm</command> executes an
administration command of the backend database, it assumes the command is
installed under the given prefix.
An example of those commands is
<command moreinfo="none">initdb</command> of PostgreSQL.
If this option is omitted, <command moreinfo="none">config-gfarm</command>
searches directories listed in the environment variable <envar>PATH</envar>
for the commands.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-V</option> <parameter moreinfo="none">version</parameter></term>
<listitem>
<para>
Tell version of the backend database to
<command moreinfo="none">config-gfarm</command>.
In most cases, <command moreinfo="none">config-gfarm</command> can detect
a correct version number by itself.
This option should be used only when
<command moreinfo="none">config-gfarm</command> fails to get the correct
version number.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-l</option> <parameter moreinfo="none">directory</parameter></term>
<listitem>
<para>
Specify a path to the directory where the backend database puts files to
store metadata of Gfarm.
</para>
<para>
If the backend database is PostgreSQL, the directory is commonly called
PGDATA directory.
The default is <filename moreinfo="none">PREFIX/var/gfarm-pgsql</filename>
where PREFIX is a prefix given by <option>--prefix</option> option.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-L</option> <parameter moreinfo="none">directory</parameter></term>
<listitem>
<para>
Specify a path to the directory where the backend database puts log files.
If the backend database is PostgreSQL, the default is
<filename moreinfo="none">PREFIX/var/gfarm-pgsql/pg_xlog</filename> where
PREFIX is a prefix given by <option>--prefix</option> option.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-h</option> <parameter moreinfo="none">hostname</parameter></term>
<listitem>
<para>
Specify a hostname which is used to identify the metadata server.
The default is the fully qualified domainname of the host.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-j</option> <parameter moreinfo="none">directory</parameter></term>
<listitem>
<para>
Specify a path to the directory where
<command moreinfo="none">gfmd</command> puts journal files.
This option takes an effect only when metadata replication is enabled by
<option>-r</option> option.
The default value is
<filename moreinfo="none">PREFIX/var/gfarm-metadata/journal</filename>
where PREFIX is a prefix given by <option>--prefix</option> option.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-A</option> <parameter moreinfo="none">username</parameter></term>
<listitem>
<para>
Specify administrator of the Gfarm file system.
If this option is omitted,
<command moreinfo="none">config-gfarm</command> gets a username by executing
<command moreinfo="none">who am i</command> command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-D</option> <parameter moreinfo="none">subject-dn</parameter></term>
<listitem>
<para>
Specify a subject DN of global administrator.
This option is mandatory, in case that the authentication method is GSI,
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-p</option> <parameter moreinfo="none">port</parameter></term>
<listitem>
<para>
Specify a TCP port number the configured backend database listens on.
The default is 10602.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-m</option> <parameter moreinfo="none">port</parameter></term>
<listitem>
<para>
Specify a TCP port number the configured
<command moreinfo="none">gfmd</command> listens on.
The default value is 10601 in case of the private mode, 601 otherwise.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-a</option> <parameter moreinfo="none">method</parameter></term>
<listitem>
<para>
Specify an authentication method.
It currently recognizes "sharedsecret" or "gsi".
The default is "sharedsecret".
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--help</option></term>
<listitem>
<para>
Show usage, then exit.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-S</option></term>
<listitem>
<para>
Enable the private mode.
<command moreinfo="none">config-gfarm</command> sets up the Gfarm
file system which can be run without root privilege.
Specifically, <command moreinfo="none">config-gfarm</command> changes
the configuration procedures as follows:
</para>

  <itemizedlist>
  <listitem>
  <para>
  The default listen port of <command moreinfo="none">gfmd</command>
  (corresponding with <option>-m</option> option) is changed from 601
  to 10601.
  </para>
  </listitem>

  <listitem>
  <para>
  The user map file
  <filename moreinfo="none">%%SYSCONFDIR%%/usermap</filename>
  is also created.
  The metadata server reads this file when it starts.
  In the non-private mode, it is required to create the user accounts for
  _gfarmmd and _gfarmfs on the operating system.
  With the user map file, the creation of the user accounts is not needed.
  The file defines mappings of Gfarm system users to actual user accounts.
  </para>
  </listitem>

  <listitem>
  <para>
  The configuration file for gfsd,
  <filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename> is also
  created.
  In the non-private mode, gfsd reads the configuration file
  <filename moreinfo="none">%%SYSCONFDIR%%/gfarm2.conf</filename> instead,
  which is read by all Gfarm programs connecting with a metadata server.
  <filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename> is a
  configuration file cutomized for gfsd running under the private mode.
  </para>
  </listitem>
  </itemizedlist>
<para>
<option>-S</option> option never changes locations of start/stop scripts
and configuration files.
Since the default locations of those files are usually writable only for
privilege users, <command moreinfo="none">config-gfarm</command> fails to
create them.
To avoid this problem, also specify <option>--prefix</option> option.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-N</option></term>
<listitem>
<para>
Do not start <command moreinfo="none">gfmd</command> or the backend database.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-f</option></term>
<listitem>
<para>
Force overwriting an existing set up.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-t</option></term>
<listitem>
<para>
Show values of all configurable parameters in human readable format,
then exit immediately.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-T</option></term>
<listitem>
<para>
Like <option>-t</option> option, but it shows values in KEY=VALUE format.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-r</option></term>
<listitem>
<para>
Enable metadata replication among metadata servers.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-W</option> <parameter moreinfo="none">password</parameter></term>
<listitem>
<para>
Specify administrator's password of backend database.
This option corresponds with <option>-U</option> option which specifies
the username.
By default, the password is generated automatically.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-w</option> <parameter moreinfo="none">password</parameter></term>
<listitem>
<para>
The configured <command moreinfo="none">gfmd</command> will connect the
backend database with the specified password.
This option corresponds with <option>-u</option> option which specifies
the username.
By default, the password is generated automatically.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-X</option></term>
<listitem>
<para>
Enable XML Path Language (XPath) support for querying XML extended attributes.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-E</option></term>
<listitem>
<para>
Set up PostgreSQL with the data checksums option.
<command moreinfo="none">config-gfarm</command> gives
<option>--data-checksums</option> option to
<command moreinfo="none">initdb</command> command of PostgreSQL.
Note that PostgreSQL 9.3 or later is required to use this feature.
This option takes an effect only when the backend database is 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>
configuration file for Gfarm clients
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">%%SYSCONFDIR%%/gfmd.conf</filename></term>
<listitem>
<para>
configuration file for <command moreinfo="none">gfmd</command>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename></term>
<listitem>
<para>
configuration file for gfsd (used only in the private mode)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">%%SYSCONFDIR%%/usermap</filename></term>
<listitem>
<para>
user mapping definition file (used only in the private mode)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">/etc/init.d/gfarm-pgsql</filename></term>
<listitem>
<para>
start/stop script for PostgreSQL running as backend database of Gfarm
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">/etc/init.d/gfmd</filename></term>
<listitem>
<para>
start/stop script for <command moreinfo="none">gfmd</command>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">/etc/systemd/system/gfarm-pgsql.service</filename></term>
<listitem>
<para>
unit configuration file for PostgreSQL running as backend database of Gfarm,
read by systemd
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename moreinfo="none">/etc/systemd/system/gfmd.service</filename></term>
<listitem>
<para>
unit configuration file for <command moreinfo="none">gfmd</command>,
read by systemd
</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>
