<?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="gfservice.1">

<refentryinfo><date>6 Jun 2013</date></refentryinfo>

<refmeta>
<refentrytitle>gfservice</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Gfarm</refmiscinfo>
</refmeta>

<refnamediv id="name">
<refname>gfservice</refname>
<refpurpose>control Gfarm servers from a remote host</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis">
<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfservice</command>
    <arg choice="opt" rep="norepeat"><replaceable>options</replaceable></arg>
    <arg choice="plain" rep="norepeat">sub-command</arg>
    <arg choice="opt" rep="norepeat">host-id</arg>
    <arg choice="opt" rep="norepeat"><replaceable>argument ...</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>

<para>
<command moreinfo="none">gfservice</command> is an utility for Gfarm administrators
to operate servers (<command moreinfo="none">gfmd</command>, <command moreinfo="none">gfsd</command> and
PostgreSQL) on remote hosts.
OpenLDAP is not supported currently.
It can start, stop, set up (execute <command moreinfo="none">config-gfarm</command>
and <command moreinfo="none">config-gfsd</command>) and clean up the servers, for example.
</para>

<para>
A sample command line of <command moreinfo="none">gfservice</command> looks like:
</para>

<literallayout format="linespecific" class="normal">
	<command moreinfo="none">gfservice <replaceable>start-gfmd</replaceable> <replaceable>gfmd2</replaceable></command>
</literallayout>

<para>
where "<replaceable>start-gfmd</replaceable>" is a sub-command and
<replaceable>gfmd2</replaceable> is a host-id respectively.
Executing the command, <command moreinfo="none">gfservice</command> tries to start gfmd
on the host named <replaceable>gfmd2</replaceable>.
To specify a remote server host, <command moreinfo="none">gfservice</command> uses
host-id instead of hostname.
All host-ids (<replaceable>gfmd1</replaceable>,
<replaceable>gfmd2</replaceable>, and so on) are defined in a configuration
file of <command moreinfo="none">gfservice</command>.
Here is an example of the configuration file:
</para>

<literallayout format="linespecific" class="normal">
	gfmd1=metadb1.example.com
	gfmd1_CONFIG_GFARM_OPTIONS="-A $LOGNAME -X"
	gfmd2=metadb2.example.com
	gfmd2_CONFIG_GFARM_OPTIONS="-A $LOGNAME -X"

	gfsd1=spool1.example.com
	gfsd2=spool2.example.com
</literallayout>

<para>
<command moreinfo="none">gfservice</command> determines a path of the configuration
file to be read with the following procedures:
</para>

<orderedlist numeration="arabic" inheritnum="ignore" continuation="restarts">
<listitem>
<para>
<option>-f</option> <parameter moreinfo="none">file</parameter> option is specified, read
<parameter moreinfo="none">file</parameter>.
</para>
</listitem>

<listitem>
<para>Otherwise, the environment variable
<varname>GFSERVICE_CONF</varname> is defined and not empty, read the file.
</para>
</listitem>

<listitem>
<para>Otherwise, read <filename moreinfo="none">$HOME/.gfservice</filename>.
</para>
</listitem>
</orderedlist>

<para>
If <command moreinfo="none">gfservice</command> fails to read a configuration file,
it prints an error message and exits immediately.
Note that the configuration file itself is a Bourne-shell script and
<command moreinfo="none">gfservice</command> includes (exactly to say, 
<emphasis>evaluates</emphasis>) the file.
See gfservice.conf(5) for more details about the configuration file.
</para>

<para>
<command moreinfo="none">gfservice</command> uses SSH (Secure Shell) to connect with
a remote host.
Since it may execute <command moreinfo="none">ssh</command> several times during a
sub-command operation, it is recommended to use an SSH agent
(e.g. <command moreinfo="none">ssh-agent</command> of OpenSSH) or an authentication key
with an empty passphrase to avoid typing a passphrase every time.
</para>

<para>
In addition with SSH, <command moreinfo="none">gfservice</command> uses Sudo to get
root privilege on the remote host.
Please add a line like below to <filename moreinfo="none">sudoers</filename> file
(Sudo's configuration file) on each remote host.
</para>

<literallayout format="linespecific" class="normal">
	<replaceable>user</replaceable> ALL=(root, _gfarmfs, _gfarmmd) NOPASSWD: gfservice-agent
</literallayout>

<para>
where <replaceable>user</replaceable> is an user name who executes
<command moreinfo="none">gfservice</command>.
The NOPASSWD option is not mandatory, but <command moreinfo="none">sudo</command> may
ask you a password several times if omitted.
</para>

<para>
Since <command moreinfo="none">gfservice</command> executes an agent command named
<command moreinfo="none">gfservice-agent</command> on the remote host using SSH and Sudo,
<command moreinfo="none">gfservice-agent</command> command must have been installed on
all hosts you want to operate using <command moreinfo="none">gfservice</command>.
</para>

<para>
<command moreinfo="none">gfservice</command> has a plug-in system so that user can add
new sub-commands. See "PLUG-IN SYSTEM" section of this man page for
more details.
</para>

</refsect1>

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

<variablelist>

<varlistentry>
<term><option>-d</option></term>
<listitem>
<para>
Print debug information.
<command moreinfo="none">gfservice</command> passes this option to
<command moreinfo="none">gfservice-agent</command> so that also
<command moreinfo="none">gfservice-agent</command> outputs debug information.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-f</option> <parameter moreinfo="none">file</parameter></term>
<listitem>
<para>
Read configuration from <parameter moreinfo="none">file</parameter> instead of the default.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-t</option> <parameter moreinfo="none">time</parameter></term>
<listitem>
<para>
Set operation timeout in <parameter moreinfo="none">time</parameter> seconds.
When <command moreinfo="none">gfservice</command> tries to start or stop a server program
(gfmd, gfsd or a backend database), it waits until the operation is complete
or <parameter moreinfo="none">time</parameter> interval is elapsed.
If "no" is specified as <parameter moreinfo="none">time</parameter>, timeout never occurs.
The default value is "no".
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-k</option></term>
<listitem>
<para>
When this option is specified with sub-command
<command moreinfo="none">config-gfarm</command> or
<command moreinfo="none">config-gfarm-master</command>, <command moreinfo="none">gfservice</command>
creates a shared secret key files using <command moreinfo="none">gfkey</command>
command.
</para>
</listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1 id="gfmd-sub-commands"><title>SUB-COMMANDS FOR GFMD</title>

<para>
The followings are sub-commands which operate <command moreinfo="none">gfmd</command>.
The given host-id argument must be "gfmd<replaceable>n</replaceable>"
(gfmd1, gfmd2, ...).
Otherwise <command moreinfo="none">gfservice</command> reports an error and exits
immediately.
</para>

<variablelist>

<varlistentry>
<term>
<command moreinfo="none">backend-db-status</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Exit with an exit code 0, if a backend database is currently running.
Otherwise exits with 1.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">gfmd-status</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Exit with an exit code 0, if <command moreinfo="none">gfmd</command> is currently running.
Otherwise exits with 1.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">start-backend-db</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Start a backend database if it is not running currently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">start-gfmd</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Start <command moreinfo="none">gfmd</command> if it is not running currently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">start-gfmd-master</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
An alias of "<command moreinfo="none">start-gfmd</command>" sub-command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">start-gfmd-slave</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
This sub-command is the same as "<command moreinfo="none">start-gfmd</command>",
but <option>-S</option> option is added to <command moreinfo="none">gfmd</command>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">start-gfarm</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Start a backend database and <command moreinfo="none">gfmd</command> if they are
not running currently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">start-gfarm-master</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
An alias of "<command moreinfo="none">start-gfarm</command>" sub-command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">start-gfarm-slave</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
This sub-command is the same as "<command moreinfo="none">start-gfarm</command>",
but <option>-S</option> option is added to <command moreinfo="none">gfmd</command>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">stop-backend-db</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Stop a backend database if it is running currently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">stop-gfmd</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Stop <command moreinfo="none">gfmd</command> if it is running currently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">stop-gfarm</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Stop <command moreinfo="none">gfmd</command> and a backend database if they are running
currently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">kill-gfmd</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Kill <command moreinfo="none">gfmd</command> (send SIGKILL) if it is running currently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restart-backend-db</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Perform "<command moreinfo="none">stop-backend-db</command>" and 
"<command moreinfo="none">start-backend-db</command>" sub-commands successively.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restart-gfmd</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Perform "<command moreinfo="none">stop-gfmd</command>" and
"<command moreinfo="none">start-gfmd</command>" sub-commands successively.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restart-gfmd-master</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
An alias of "<command moreinfo="none">restart-gfmd</command>" sub-command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restart-gfmd-slave</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Perform "<command moreinfo="none">stop-gfmd</command>" and 
"<command moreinfo="none">start-gfmd-slave</command>" sub-commands successively.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restart-gfarm</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Perform "<command moreinfo="none">stop-gfarm</command>" and 
"<command moreinfo="none">start-gfarm</command>" sub-commands successively.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restart-gfarm-master</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
An alias of "<command moreinfo="none">restart-gfarm</command>" sub-command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restart-gfarm-slave</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Perform "<command moreinfo="none">stop-gfarm</command>" and 
"<command moreinfo="none">start-gfarm-slave</command>" sub-commands successively.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">promote</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Promote <command moreinfo="none">gfmd</command> from a slave to a master.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">promote-gfmd</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
An alias of "<command moreinfo="none">promote</command>" sub-command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">set-gfmd-conf</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directive</parameter>
<parameter moreinfo="none">value</parameter>
</term>
<listitem>
<para>
Add
</para>

<literallayout format="linespecific" class="normal">
	<parameter moreinfo="none">directive</parameter> <parameter moreinfo="none">value</parameter>
</literallayout>

<para>
line to <filename moreinfo="none">gfmd.conf</filename> file on the remote host.
If <filename moreinfo="none">gfmd.conf</filename> already has a
<parameter moreinfo="none">directive</parameter> line, <command moreinfo="none">gfservice</command>
deletes it and then add a new line.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">set-gfsd-conf</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directive</parameter>
<parameter moreinfo="none">value</parameter>
</term>
<listitem>
<para>
Add
</para>

<literallayout format="linespecific" class="normal">
	<parameter moreinfo="none">directive</parameter> <parameter moreinfo="none">value</parameter>
</literallayout>

<para>
line to <filename moreinfo="none">gfsd.conf</filename> file on the remote host.
If <filename moreinfo="none">gfsd.conf</filename> already has a
<parameter moreinfo="none">directive</parameter> line, <command moreinfo="none">gfservice</command>
deletes it and then add a new line.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unset-gfmd-conf</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directive</parameter>
</term>
<listitem>
<para>
Delete a <parameter moreinfo="none">directive</parameter> line in
<filename moreinfo="none">gfmd.conf</filename> file on the remote host.
If <filename moreinfo="none">gfmd.conf</filename> file doesn't contain
<parameter moreinfo="none">directive</parameter> line, the file is unchanged.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unset-gfsd-conf</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directive</parameter>
</term>
<listitem>
<para>
Delete a <parameter moreinfo="none">directive</parameter> line in
<filename moreinfo="none">gfsd.conf</filename> file on the remote host.
If <filename moreinfo="none">gfsd.conf</filename> file doesn't contain
<parameter moreinfo="none">directive</parameter> line, the file is unchanged.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">backup-backend-db</command>
</term>
<listitem>
<para>
Backup a backend database on the remote host and output the backup data
to standard out.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">backup-gfmd-conf</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Output <filename moreinfo="none">gfmd.conf</filename> file on the remote host to
standard out.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">backup-gfsd-conf</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Output <filename moreinfo="none">gfsd.conf</filename> file on the remote host to
standard out.
This sub-command can be worked only when the remote host is configured
in the private mode.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">backup-usermap</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Output <filename moreinfo="none">usermap</filename> file on the remote host to
standard out.
This sub-command can be worked only when the remote host is configured
in the private mode.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restore-backend-db</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Restore a backend database on the remote host.
The backup data are read from standard in.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restore-gfmd-conf</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Recover <filename moreinfo="none">gfmd.conf</filename> file on the remote host.
<command moreinfo="none">gfservice</command> reads a backup of <filename moreinfo="none">gfmd.conf</filename>
from standard in.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restore-gfsd-conf</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Recover <filename moreinfo="none">gfsd.conf</filename> file on the remote host.
<command moreinfo="none">gfservice</command> reads a backup of <filename moreinfo="none">gfsd.conf</filename>
from standard in.
This sub-command can be worked only when the remote host is configured
in the private mode.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restore-usermap</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Recover <filename moreinfo="none">usermap</filename> file on the remote host.
<command moreinfo="none">gfservice</command> reads a backup of <filename moreinfo="none">usermap</filename>
from standard in.
This sub-command can be worked only when the remote host is configured
in the private mode.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">config-gfarm</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Execute <command moreinfo="none">config-gfarm</command> command on the remote host.
If "gfmd<replaceable>n</replaceable>_CONFIG_GFARM_OPTIONS" variable is
declared in the configuration file of <command moreinfo="none">gfservice</command>,
its value is passed to <command moreinfo="none">config-gfarm</command> command as
options.
Don't use this sub-command when you want to enable replication of gfmd.
Instead, use "<command moreinfo="none">config-gfarm-master</command>" or
"<command moreinfo="none">config-gfarm-slave</command>" sub-command in that case.
If <option>-k</option> option is specified, <command moreinfo="none">gfservice</command>
also creates a shared secret key files onto the gfmd host, using
<command moreinfo="none">gfkey</command> command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">config-gfarm-master</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
This sub-command is the same as <command moreinfo="none">config-gfarm</command>
but gfmd replication is enabled automatically.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">config-gfarm-slave</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">master-host-id</parameter>
</term>
<listitem>
<para>
This sub-command is the same as <command moreinfo="none">config-gfarm</command>
but gfmd replication is enabled automatically and the remote gfmd host
is configured as a slave of <parameter moreinfo="none">master-host-id</parameter>.
Then <command moreinfo="none">gfservice</command> registers the slave host to a server list
using <command moreinfo="none">gfmdhost</command> command.
<command moreinfo="none">gfservice</command> also adds the slave host to
<varname>metadb_server_list</varname> directive in
<filename moreinfo="none">gfarm2.conf</filename> file on the master gfmd host and
distribute the updated <filename moreinfo="none">gfarm2.conf</filename> file to all hosts
defined in the configuration file.
It also updates <filename moreinfo="none">gfsd.conf</filename> file and distributes it to
all gfmd and gfsd hosts, if "gfmd<replaceable>n</replaceable>_PRIVATE_MODE"
variable is set to "true".
If the value of the variable "gfmd<replaceable>n</replaceable>_AUTH_TYPE"
is "sharedsecret", it also copies a shared key file from the maste gfmd
to the slave gfmd host.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unconfig-gfarm</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Execute "<command moreinfo="none">stop-gfarm</command>" sub-command and then delete all
files and directories created by gfmd and a backend database.
If you want to unconfigure a slave gfmd, use
"<command moreinfo="none">unconfig-gfarm-slave</command>" sub-command instead.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unconfig-gfarm-master</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
An alias of "<command moreinfo="none">unconfig-gfarm</command>" sub-command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unconfig-gfarm-slave</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">master-host-id</parameter>
</term>
<listitem>
<para>
This sub-command is the same as "<command moreinfo="none">unconfig-gfarm</command>",
but <command moreinfo="none">gfservice</command> does some additional works.
It also deletes the slave host from a server list using
<command moreinfo="none">gfmdhost</command> command and from
<varname>metadb_server_list</varname> directive in
<filename moreinfo="none">gfarm2.conf</filename> file on all hosts defined in the
configuration file.
It also updates <filename moreinfo="none">gfsd.conf</filename> file and distributes it to
all gfmd and gfsd hosts, if "gfmd<replaceable>n</replaceable>_PRIVATE_MODE"
variable is set to "true".
</para>
</listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1 id="gfsd-sub-commands"><title>SUB-COMMANDS FOR GFSD</title>

<para>
The followings are sub-commands which operate <command moreinfo="none">gfsd</command>.
The given host-id argument must be "gfsd<replaceable>n</replaceable>"
(gfsd1, gfsd2, ...).
Otherwise <command moreinfo="none">gfservice</command> reports an error and exits
immediately.
</para>

<variablelist>

<varlistentry>
<term>
<command moreinfo="none">gfsd-status</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Exit with an exit code 0, if <command moreinfo="none">gfsd</command> is currently running.
Otherwise exits with 1.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">start-gfsd</command>
</term>
<listitem>
<para>
Start <command moreinfo="none">gfsd</command> if it is not running currently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">stop-gfsd</command>
</term>
<listitem>
<para>
Stop <command moreinfo="none">gfsd</command> if it is running currently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restart-gfsd</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Perform "<command moreinfo="none">stop-gfsd</command>" and "<command moreinfo="none">start-gfsd</command>"
sub-commands successively.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">set-gfsd-conf</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directive</parameter>
<parameter moreinfo="none">value</parameter>
</term>
<listitem>
<para>
Same as <command moreinfo="none">set-gfsd-conf</command> sub-command for gfmd.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unset-gfsd-conf</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directive</parameter>
</term>
<listitem>
<para>
Same as <command moreinfo="none">unset-gfsd-conf</command> sub-command for gfmd.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">backup-gfsd-conf</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Same as <command moreinfo="none">backup-gfsd-conf</command> sub-command for gfmd.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">backup-usermap</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Same as <command moreinfo="none">backup-usermap</command> sub-command for gfmd.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restore-gfsd-conf</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Same as <command moreinfo="none">restore-gfsd-conf</command> sub-command for gfmd.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restore-usermap</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Same as <command moreinfo="none">restore-usermap</command> sub-command for gfmd.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">config-gfsd</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Execute "<command moreinfo="none">config-gfsd</command>" command on the remote host.
If "gfsd<replaceable>n</replaceable>_CONFIG_GFSD_OPTIONS" variable is
declared in the configuration file of <command moreinfo="none">gfservice</command>,
its value is passed to <command moreinfo="none">config-gfsd</command> command as
options.
<command moreinfo="none">gfservice</command> also registers the configured remote host
as a filesystem node using <command moreinfo="none">gfhost</command> command.
If the value of the variable "gfsd<replaceable>n</replaceable>_AUTH_TYPE"
is "sharedsecret", it also copies a shared key file from gfmd1 to the
gfsd host.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unconfig-gfsd</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Execute "<command moreinfo="none">stop-gfsd</command>" sub-command and then delete all
files and directories created by gfsd.
</para>
</listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1 id="client-sub-commands"><title>SUB-COMMANDS FOR CLIENT</title>

<para>
The followings are sub-commands which operate a client.
The given host-id argument must be "gfmd<replaceable>n</replaceable>"
(gfmd1, gfmd2, ...), "gfsd<replaceable>n</replaceable>" (gfsd1, gfsd2, ...)
or "client<replaceable>n</replaceable>" (client1, client2, ...).
Otherwise <command moreinfo="none">gfservice</command> reports an error and exits
immediately.
</para>

<variablelist>

<varlistentry>
<term>
<command moreinfo="none">mount</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directory</parameter>
<parameter moreinfo="none">option...</parameter>
</term>
<listitem>
<para>
Mount a Gfarm2 filesystem on <parameter moreinfo="none">directory</parameter> on the
remote host.
The argument <parameter moreinfo="none">option</parameter> is an option to 
<command moreinfo="none">gfarm2fs</command> command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unmount</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directory</parameter>
</term>
<listitem>
<para>
Unmount a Gfarm2 filesystem on <parameter moreinfo="none">directory</parameter> on the
remote host.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">umount</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directory</parameter>
</term>
<listitem>
<para>
An alias of "<command moreinfo="none">unmount</command>" sub-command.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">set-gfarm-conf</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directive</parameter>
<parameter moreinfo="none">value</parameter>
</term>
<listitem>
<para>
Add
</para>

<literallayout format="linespecific" class="normal">
	<parameter moreinfo="none">directive</parameter> <parameter moreinfo="none">value</parameter>
</literallayout>

<para>
line to <filename moreinfo="none">gfarm2.conf</filename> file on the remote host.
If <filename moreinfo="none">gfarm2.conf</filename> already has a
<parameter moreinfo="none">directive</parameter> line, <command moreinfo="none">gfservice</command>
deletes it and then add a new line.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unset-gfarm-conf</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">directive</parameter>
</term>
<listitem>
<para>
Delete a <parameter moreinfo="none">directive</parameter> line in
<filename moreinfo="none">gfarm2.conf</filename> file on the remote host.
If <filename moreinfo="none">gfarm2.conf</filename> file doesn't contain
<parameter moreinfo="none">directive</parameter> line, the file is unchanged.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">backup-gfarm-conf</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Output <filename moreinfo="none">gfarm2.conf</filename> file on the remote host to
standard out.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">backup-shared-key</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Output a shared secret key file to standard out.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restore-gfarm-conf</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Recover <filename moreinfo="none">gfarm2.conf</filename> file on the remote host.
<command moreinfo="none">gfservice</command> reads a backup of <filename moreinfo="none">gfarm2.conf</filename>
from standard in.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restore-shared-key</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Recover a shared secret key file on the remote host.
<command moreinfo="none">gfservice</command> reads a backup of the shared secret key from
standard in.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">config-client</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Copy <filename moreinfo="none">gfarm2.conf</filename> file from gfmd1 to the client
host.
If the value of the variable "client<replaceable>n</replaceable>_AUTH_TYPE"
is "sharedsecret", it also copies a shared key file from gfmd1 to the
client host.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unconfig-client</command>
<parameter moreinfo="none">host-id</parameter>
</term>
<listitem>
<para>
Delete <filename moreinfo="none">gfarm2.conf</filename> file and a shared secret key file
on the remote host.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">gfcmd</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">command-name</parameter>
<parameter moreinfo="none">command-argument ...</parameter>
</term>
<listitem>
<para>
Execute a Gfarm command on the remote host.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">gfcmd-root</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">command-name</parameter>
<parameter moreinfo="none">command-argument ...</parameter>
</term>
<listitem>
<para>
Execute a Gfarm command on the remote host with root privilege.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">grid-proxy-init</command>
<parameter moreinfo="none">host-id</parameter>
<parameter moreinfo="none">command-argument ...</parameter>
</term>
<listitem>
<para>
Execute <command moreinfo="none">grid-proxy-init</command> command on
the remote host.
</para>
</listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1 id="multi-host-sub-commands">
<title>SUB-COMMANDS FOR MULTIPLE HOSTS</title>

<para>
The followings are sub-commands which operate on multiple hosts.
The host-id argument must not be specified.
</para>

<variablelist>

<varlistentry>
<term>
<command moreinfo="none">start-all</command>
</term>
<listitem>
<para>
Start all backend databases, <command moreinfo="none">gfmd</command> servers and 
<command moreinfo="none">gfsd</command> servers.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">stop-all</command>
</term>
<listitem>
<para>
Stop all <command moreinfo="none">gfsd</command> servers, <command moreinfo="none">gfmd</command> servers
and backend databases,
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">kill-gfmd-all</command>
</term>
<listitem>
<para>
Kill (send SIGKILL) all <command moreinfo="none">gfmd</command> servers.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">restart-all</command>
</term>
<listitem>
<para>
Perform "<command moreinfo="none">stop-all</command>" and
"<command moreinfo="none">start-all</command>" sub-commands successively.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">config-all</command>
</term>
<listitem>
<para>
Perform "<command moreinfo="none">config-gfarm-master</command>" for
<replaceable>gfmd1</replaceable> and "<command moreinfo="none">config-gfarm-slave</command>"
for all other gfmd nodes.
Then, perform "<command moreinfo="none">config-gfsd</command>" for all gfds nodes.
Finally, perform "<command moreinfo="none">config-client</command>" for all client nodes.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<command moreinfo="none">unconfig-all</command>
</term>
<listitem>
<para>
Perform "<command moreinfo="none">unconfig-client</command>" for all client nodes.
Then, perform "<command moreinfo="none">unconfig-gfsd</command>" for all gfds nodes.
Finally, perform "<command moreinfo="none">unconfig-gfarm</command>" for all gfmd nodes.
</para>
</listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1 id="plugin"><title>PLUG-IN SYSTEM</title>

<para>
<command moreinfo="none">gfservice</command> has a plug-in system so that user can add
new sub-commands. If given sub-command is not provided by
<command moreinfo="none">gfservice</command>, <command moreinfo="none">gfservice</command> refers to
a file which has name of sub-command under %%DATADIR%%/gfarm/gfservice
directory.
</para>

<para>
Sub-command file must be written as Bourne shell script. Sub-command
file for sub-command "<replaceable>name</replaceable>", must have
shell function named
"<function moreinfo="none">subcmd_<replaceable>name</replaceable></function>" which
will be executed from <command moreinfo="none">gfservice</command>, and
"<function moreinfo="none">subcmd_<replaceable>name</replaceable>_agent</function>"
which will be executed from <command moreinfo="none">gfservice-agent</command>.
</para>

<para>
For the case a sub-command depends on a other user provided
sub-command, Sub-command file for sub-command
"<replaceable>name</replaceable>", must have shell function named
"<function moreinfo="none"><replaceable>name</replaceable>_depends</function>" which
must return list of sub-commands. List of sub-commands must be a
string which is space separated list of sub-command names. If
sub-command or it's agent does not have dependencies, return empty
string.  Similarly, sub-command file must have shell function named
"<function moreinfo="none"><replaceable>name</replaceable>_agent_depends</function>"
which must return list of sub-command's agents.
</para>

</refsect1>
</refentry>
