<?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-gfsd.8">

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

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

<refnamediv id="name">
<refname>config-gfsd</refname>
<refpurpose>set up a file spool node of Gfarm</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis">
<cmdsynopsis sepchar=" ">
  <command moreinfo="none">config-gfsd</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-gfsd</command> is a utility to set up a
file sppol node of Gfarm file system.
The server program for a file spool node is named 
<command moreinfo="none">gfsd</command>.
<command moreinfo="none">config-gfsd</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-gfsd</command> assumes that the
configuration file
<filename moreinfo="none">%%SYSCONFDIR%%/gfarm2.conf</filename> (or
<filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename> in case of
the private-mode) exists on the host.
Please copy the file from the metadata server, if missing.
</para>

<para>
It performs the following processes, in that order:
</para>

<orderedlist numeration="arabic" inheritnum="ignore" continuation="restarts">
<listitem>
<para>
Crerate a spool directory.
</para>
</listitem>

<listitem>
<para>
Update the Gfarm configuration file
<filename moreinfo="none">%%SYSCONFDIR%%/gfarm2.conf</filename> or
<filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename>.
</para>
</listitem>

<listitem>
<para>
Create a script (or a configuration file) to start/stop
<command moreinfo="none">gfsd</command>.
</para>

<para>
On most systems, <command moreinfo="none">config-gfsd</command> puts
a start/stop script <command moreinfo="none">gfsd</command> (or
<command moreinfo="none">gfsd-ADDRESS</command> in case of the private
mode) 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-gfsd</command> puts the unit configuration
file <filename moreinfo="none">gfsd.service</filename> (or
<filename moreinfo="none">gfsd-ADDRESS.service</filename> in case of the
private mode) onto <filename moreinfo="none">/etc/systemd/system</filename>,
and then executes
<command moreinfo="none">systemctl enable gfsd.service</command> (or
<command moreinfo="none">systemctl enable gfsd-ADDRESS.service</command>
respectively).
</para>
</listitem>

<listitem>
<para>
In case of the private mode, <command moreinfo="none">config-gfsd</command>
registers the host as a file spool node to the metadata server, by executing
<command moreinfo="none">gfhost -c</command> command.
In the non-private mode, it shows how to register the host as a file spool
node to the metadata server, like this:

<screen>
Please ask admin_user to register your host by the following command:

/usr/bin/gfhost -c -a x86_64-centos7.0-linux -p 600 -n 2 ext540
</screen>
</para>
</listitem>

<listitem>
<para>
In case of the private mode, <command moreinfo="none">config-gfsd</command>
starts <command moreinfo="none">gfsd</command>.
In the non-private mode, it shows how to start
<command moreinfo="none">gfsd</command>, like as follows:
<screen>
After that, start gfsd by the following command as a root:

systemctl start gfsd.service
</screen>
</para>
</listitem>

<listitem>
Puts the script <command moreinfo="none">unconfig-gfsd.sh</command> on
%%SYSCONFDIR%%.
The script does unconfiguration of <command moreinfo="none">gfsd</command>.
It stops <command moreinfo="none">gfsd</command> and removes all files
created by <command moreinfo="none">config-gfsd</command> including 
<command moreinfo="none">unconfig-gfsd.sh</command> itself.
</listitem>
</orderedlist>

<para>
Before set up a file spool node using
<command moreinfo="none">config-gfsd</command>,
it is recommended to execute
<command moreinfo="none">config-gfsd -t</command>.
With <option>-t</option> option, the sets up is not performed.
Instead, it shows values of all configurable parameters:
</para>

<screen>
$ config-gfsd -t

prefix                 [--prefix]:
hostname                     [-h]: host1.example.org
listen address               [-l]: (all local IP addresses)
architecture                 [-a]: x86_64-centos6.5-linux
port                         [-p]: 600
ncpu                         [-n]: 8
spool directory                  : /var/gfarm-spool
rc script                        : /etc/init.d/gfsd
gfarm client conf file           : /etc/gfarm2.conf
gfsd pid file                    : /var/run/gfsd.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">gfsd</command>.
Specifically, the followings are affected.
</para>

  <itemizedlist>
  <listitem>
  <para>
  The spool directory of <command moreinfo="none">gfsd</command>.
  That is <filename moreinfo="none">PREFIX/var/gfarm-spool</filename>.
  </para>
  </listitem>

  <listitem>
  <para>
  The directory to put a PID file of <command moreinfo="none">gfsd</command>.
  That is <filename moreinfo="none">PREFIX/var/run</filename>.
  </para>
  </listitem>

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

  <listitem>
  <para>
  The directory of start/stop script for
  <command moreinfo="none">gfsd</command>.
  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-gfsd</command> doesn't
  put a unit configuration file for systemd.
  Instead, it puts traditional start/stop script at
  <filename moreinfo="none">PREFIX/etc/init.d</filename>.
  </para>
  </listitem>

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

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

<varlistentry>
<term><option>-a</option> <parameter moreinfo="none">architecture</parameter></term>
<listitem>
<para>
Specify architecture of the host.
<command moreinfo="none">config-gfsd</command> gives this value to
<command moreinfo="none">gfhost -c</command> as an argument of
<option>-a</option> option.
<command moreinfo="none">config-gfsd</command> guesses the architecture,
and use it by default.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-p</option> <parameter moreinfo="none">port</parameter></term>
<listitem>
<para>
Specify a TCP port number the configured
<command moreinfo="none">gfsd</command> listens on.
The default is 10600 if the private mode, 600 otherwise.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-h</option> <parameter moreinfo="none">hostname</parameter></term>
<listitem>
<para>
Specify a hostname of the host.
<command moreinfo="none">config-gfsd</command> gives this value to
<command moreinfo="none">gfhost -c</command> as an non-option argument.
The default is the fully qualified domainname of the host on DNS.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-l</option> <parameter moreinfo="none">address</parameter></term>
<listitem>
<para>
Specify a listen address of <command moreinfo="none">gfsd</command>.
By default, it listens on all local IP addresses.
If this option is specified, also the following changes occur:
</para>

  <itemizedlist>
  <listitem>
  <para>
  The name of start/stop script is changed from
  <filename moreinfo="none">gfsd</filename> to
  <filename moreinfo="none">gfsd-ADDRESS</filename>, when
  <command moreinfo="none">config-gfsd</command> creates the script.
  </para>
  </listitem>

  <listitem>
  <para>
  The name of unit configuration file for systemd is changed from
  <filename moreinfo="none">gfsd.service</filename> to
  <filename moreinfo="none">gfsd-ADDRESS.service</filename>, when
  <command moreinfo="none">config-gfsd</command> creates the file.
  </para>
  </listitem>

  <listitem>
  <para>
  The spool directory is changed from
  <filename moreinfo="none">PREFIX/var/gfarm-spool</filename> to
  <filename moreinfo="none">PREFIX/var/gfarm-spool-ADDRESS</filename>,
  where PREFIX is a prefix given by <option>--prefix</option> option.
  </para>
  </listitem>
  </itemizedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-n</option> <parameter moreinfo="none">ncpu</parameter></term>
<listitem>
<para>
Specify the number of CPUs of the host.
<command moreinfo="none">config-gfsd</command> gives this value to
<command moreinfo="none">gfhost -c</command> as an argument of
<option>-n</option> option.
<command moreinfo="none">config-gfsd</command> guesses the number of CPUs,
and use it by default.
</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-gfsd</command> sets up the Gfarm
file system which can be run without root privilege.
Specifically, <command moreinfo="none">config-gfsd</command> changes
the configuration procedures as follows:
</para>

  <itemizedlist>
  <listitem>
  <para>
  The default listen port of <command moreinfo="none">gfsd</command>
  (corresponding with <option>-p</option> option) is changed from 600
  to 10600.
  </para>
  </listitem>

  <listitem>
  <para>
  It updates the configuration file
  <filename moreinfo="none">%%SYSCONFDIR%%/gfsd.conf</filename>, instead
  of <filename moreinfo="none">%%SYSCONFDIR%%/gfarm2.conf</filename>.
  </para>
  </listitem>

  <listitem>
  <para>
  It registers the file spool node by executing
  <command moreinfo="none">gfhost -c</command>.
  </para>
  </listitem>

  <listitem>
  <para>
  It starts <command moreinfo="none">gfsd</command>, unless
  <option>-N</option> option is given.
  </para>
  </listitem>
  </itemizedlist>
<para>
<option>-S</option> option never changes locations of a start/stop
script and a configuration file.
Since the default locations of those files are usually writable only for
privilege users, <command moreinfo="none">config-gfsd</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">gfsd</command>.
</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 '-t', but it shows values in KEY=VALUE format.
</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%%/gfsd.conf</filename></term>
<listitem>
<para>
configuration file for <command moreinfo="none">gfsd</command> (used only
in the private mode)
</para>
</listitem>
</varlistentry>

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

<varlistentry>
<term><filename moreinfo="none">/etc/systemd/system/gfsd.service</filename></term>
<listitem>
<para>
unit configuration file for <command moreinfo="none">gfsd</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-gfarm</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gfsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>

</refsect1>

</refentry>
