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

<refentryinfo><date>22 Dec 2014</date></refentryinfo>

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

<refnamediv id="name">
<refname>gfsched</refname>
<refpurpose>
<!-- create a host file using file-affinity scheduling -->
schedule and display available file system nodes
</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis">

<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfsched</command>
   <!--
    <arg choice="opt" rep="norepeat">-I <replaceable>fragment-index</replaceable></arg>
    <arg choice="opt" rep="norepeat">-p <replaceable>gfarm-program-URL</replaceable></arg>
   -->
    <arg choice="plain" rep="norepeat">-f <replaceable>gfarm-URL</replaceable></arg>
    <arg choice="opt" rep="norepeat">-D <replaceable>domain-name</replaceable></arg>
    <arg choice="opt" rep="norepeat">-n <replaceable>number</replaceable></arg>
    <arg choice="opt" rep="norepeat">-LMOSclw</arg>
</cmdsynopsis>

<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfsched</command>
   <!--
    <arg choice="plain" rep="norepeat">-N <replaceable>number</replaceable></arg>
    <arg choice="opt" rep="norepeat">-p <replaceable>gfarm-program-URL</replaceable></arg>
   -->
    <arg choice="opt" rep="norepeat">-P <replaceable>gfarm-URL</replaceable></arg>
    <arg choice="opt" rep="norepeat">-D <replaceable>domain-name</replaceable></arg>
    <arg choice="opt" rep="norepeat">-n <replaceable>number</replaceable></arg>
    <arg choice="opt" rep="norepeat">-LMOSlw</arg>
</cmdsynopsis>

</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para>
  The <command moreinfo="none">gfsched</command> command
  with the <option>-f</option> <parameter moreinfo="none">gfarm-URL</parameter> option
  displays available file system nodes which have a file replica of the
  specified gfarm-URL.
<!--
  The <command moreinfo="none">gfsched</command> command displays a host list
  using the file-affinity scheduling of <parameter moreinfo="none">gfarm-URL</parameter>.
  In other words, the <command moreinfo="none">gfsched</command> command chooses and displays
  hostnames, matching the number with the fragments of
  the <parameter moreinfo="none">gfarm-URL</parameter>, giving priority, as far as possible to
  the host which has the fragment.
-->
</para>

<para>
  When the <option>-f</option> <parameter moreinfo="none">gfarm-URL</parameter> option
  is not specified, the <command moreinfo="none">gfsched</command> command just displays
  available file system nodes.  In this case, you can specify a metadata
  server by the <option>-P</option> <parameter moreinfo="none">gfarm-URL</parameter> option,
  if necessary.
</para>

</refsect1>

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

<!--
<varlistentry>
<term><option>-I</option> <parameter moreinfo="none">fragment-index</parameter></term>
<listitem>
<para>Specifies the fragment index to be scheduled.
If the <parameter moreinfo="none">gfarm-URL</parameter> is an executable file,
an architecture name, for example, sparc-sun-solaris8,
can be used to select a host which holds the executable file
for the architecture.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-p</option> <parameter moreinfo="none">program-URL</parameter></term>
<listitem>
<para>Creates a host file with a program name which will be used
to process the <parameter moreinfo="none">gfarm-URL</parameter>.
In other words, only hosts which can run the <parameter moreinfo="none">program-URL</parameter>
will be selected, if this option is specified.
</para>
</listitem>
</varlistentry>
-->

<varlistentry>
<term><option>-D</option> <parameter moreinfo="none">domain-name</parameter></term>
<listitem>
<para>Limits file system node by specifying a domain name or a hostname.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-c</option></term>
<listitem>
<para>Displays scheduling information for a file creation,
if the file specified by <option>-f</option> doesn't exist.
</para>
<para>
Currently, this option creates the specified file.
But please note that this behavior may be changed in future.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-L</option></term>
<listitem>
<para>Suppresses authentication check.
Without this option, the scheduler checks whether the user will be 
successfully authenticated with the hosts or not.
This option omits the check to make scheduling faster,
but that creates a risk that hosts which fail authentication with
the user may be scheduled.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-M</option></term>
<listitem>
<para>Suppresses client-side scheduling and only performs metadata-server-side
scheduling.
This option makes scheduling faster,
but also creates a risk that hosts which is network-unreachable or
fails authentication with the user may be scheduled.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-O</option></term>
<listitem>
<para>
Displays filesystem nodes where the hosts are other than the host that
the gfsched command is running.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-P</option> <parameter moreinfo="none">gfarm-URL</parameter></term>
<listitem>
<para>Specifies a <parameter moreinfo="none">gfarm-URL</parameter> or a pathname
to identify a metadata server which is used for the scheduling.
This option conflicts with the <option>-f</option> option.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-S</option></term>
<listitem>
<para>
Displays a filesystem node where the host is same with the host that
the gfsched command is running.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-f</option> <parameter moreinfo="none">gfarm-URL</parameter></term>
<listitem>
<para>The <command moreinfo="none">gfsched</command> command schedules file system nodes
which have a replica of a file specified by this option.
This option conflicts with the <option>-P</option> option.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-l</option></term>
<listitem>
<para>Long format.
This option displays port numbers as well as hostnames.
Note that the display format of this option may be changed in future.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-n</option> <parameter moreinfo="none">number</parameter></term>
<listitem>
<para>Displays specified number of file system nodes at most.
If this option is not specified, it displays all available nodes.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-w</option></term>
<listitem>
<para>Schedules with write-mode.
When this option is specified, file system nodes which don't have
enough free space won't be displayed.
</para>
<para>
When both this option and the <option>-f</option> are specified,
and if the file is already opened by an existing process with write-mode,
the <command moreinfo="none">gfsched</command> command only displays one file system node
which is assigned for writing to the file.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-?</option></term>
<listitem>
<para>Displays a list of command options.</para>
</listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1 id="examples"><title>EXAMPLES</title>
<para>
The following is an example to inquire file system nodes that the metadata
server thinks they are currently working.
</para>
<literallayout format="linespecific" class="normal">
$ gfsched -M
</literallayout>
</refsect1>

</refentry>
