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

<refentryinfo><date>19 May 2012</date></refentryinfo>

<refmeta>
<refentrytitle>gfperf.rb</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Gfarm</refmiscinfo>
</refmeta>
<refnamediv id="name">
<refname>gfperf.rb</refname>
<refpurpose>Gfarm measure performance</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis">
<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfperf.rb</command>
    <arg choice="opt" rep="norepeat">-c, --check</arg>
    <arg choice="plain" rep="norepeat"><replaceable>config file</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para>
This command measure peformance of gfarm file system according to <parameter moreinfo="none">config file</parameter>.
<parameter moreinfo="none">config file</parameter> is written in YAML.
</para>
<para>
Example config files are (gfarm install directory)/share/gfarm/config/gfperf-[config|simple].yml .
</para>
</refsect1>

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

<varlistentry>
<term><option>-c, --check</option></term>
<listitem>
<para>
Check <parameter moreinfo="none">config file</parameter> syntax.
</para>
</listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1 id="examples"><title>EXAMPLES</title>
<para>
Config file example is following.
</para>
<literallayout format="linespecific" class="normal">
database: {filename: "/var/www/database.db", check span: "10days",
	   backup: "/var/www/databse.db.bak" }
errlog: "/tmp/gfperf.err.log"
authentication: ["sharedsecret", "gsi_auth", "gsi"]
gfarm2fs_mountpoint: ["/mnt/gfarm2fs"]
metadata: [ {testdir: "gfarm:///tmp", number: "250"},
            {testdir: "file:///mnt/gfarm2fs/tmp", number: "250"} ]
tree: [ {testdir: "gfarm:///tmp", width: "5", depth: "3"},
        {testdir: "file:///mnt/gfarm2fs/tmp", width: "5", depth: "3"} ]
copy: [
   {src: "file:///tmp", dst: "gfarm:///tmp", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd0.local"},
   {src: "gfarm:///tmp", dst: "file:///tmp", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd0.local"},
   {src: "file:///tmp", dst: "gfarm:///tmp", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd1.local"},
   {src: "gfarm:///tmp", dst: "file:///tmp", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd1.local"},
   {src: "file:///tmp", dst: "gfarm:///tmp", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd0.local", gfarm2fs: "/mnt/gfarm2fs"},
   {src: "gfarm:///tmp", dst: "file:///tmp", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd0.local", gfarm2fs: "/mnt/gfarm2fs"},
   {src: "file:///tmp", dst: "gfarm:///tmp", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd1.local", gfarm2fs: "/mnt/gfarm2fs"},
   {src: "gfarm:///tmp", dst: "file:///tmp", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd1.local", gfarm2fs: "/mnt/gfarm2fs"}
      ]
read: [
   {testdir: "gfarm:///tmp", filesize: "1M", bufsize: "4K",
    gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", filesize: "1M", bufsize: "4K",
     gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", random: "true", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", random: "true", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", random: "true",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", random: "true",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd1.local"}
      ]
write: [
   {testdir: "gfarm:///tmp", filesize: "1M", bufsize: "4K",
    gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", filesize: "1M", bufsize: "4K",
    gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", random: "true", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", random: "true", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", overwrite: "true", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", overwrite: "true", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", overwrite: "true", random: "true",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", overwrite: "true", random: "true",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", filesize: "1M",
    bufsize: "4K", gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", random: "true",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", random: "true",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs",
    overwrite: "true", filesize: "1M", bufsize: "4K",
    gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs",
    overwrite: "true", filesize: "1M", bufsize: "4K",
    gfsd: "gfsd1.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs",
    overwrite: "true", random: "true", filesize: "1M", bufsize: "4K",
    gfsd: "gfsd0.local"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs",
    overwrite: "true", random: "true", filesize: "1M", bufsize: "4K",
    gfsd: "gfsd1.local"}
      ]
replica: [
   {testdir: "gfarm:///tmp", src: "gfsd0.local", dst: "gfsd1.local",
    filesize: "1M"},
   {testdir: "gfarm:///tmp", src: "gfsd1.local", dst: "gfsd0.local",
    filesize: "1M"}
	 ]
autoreplica: [
   {testdir: "gfarm:///tmp", filesize: "1M", number: "3", replica: "1"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", filesize: "1M",
    number: "3", replica: "1"},
   {testdir: "gfarm:///tmp", filesize: "1M", number: "3", replica: "2"},
   {testdir: "gfarm:///tmp", gfarm2fs: "/mnt/gfarm2fs", filesize: "1M",
    number: "3", replica: "2"}
	 ]
parallel: {
  group1: [
   {rhost: "gfsd0.local", type: "read", testdir: "gfarm:///tmp",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd0.local"},
   {rhost: "gfsd0.local", type: "read", testdir: "gfarm:///tmp",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd1.local"}
        ],
  group2: [
   {rhost: "gfsd0.local", type: "write", testdir: "gfarm:///tmp",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd0.local"},
   {rhost: "gfsd0.local", type: "write", testdir: "gfarm:///tmp",
    filesize: "1M", bufsize: "4K", gfsd: "gfsd1.local"}
       ],
  group3: [
   {type: "replica", testdir: "gfarm:///tmp", src: "gfsd0.local",
    dst: "gfsd1.local", filesize: "1M"},
   {type: "replica", testdir: "gfarm:///tmp", src: "gfsd1.local",
    dst: "gfsd0.local", filesize: "1M"}
       ]
}
parallel-autoreplica: {
  group4: [
     {testdir: "gfarm:///tmp1", filesize: "1M", number: "3",
      replica: "2"},
     {testdir: "gfarm:///tmp2", filesize: "1M", number: "3",
      replica: "2"},
     {testdir: "gfarm:///tmp3", filesize: "1M", number: "3",
      replica: "2"},
     {testdir: "gfarm:///tmp4", filesize: "1M", number: "3",
      replica: "2"}
       ],
  group5: [
     {testdir: "gfarm:///tmp1", gfarm2fs: "/mnt/gfarm2fs",
      filesize: "1M", number: "3", replica: "2"},
     {testdir: "gfarm:///tmp2", gfarm2fs: "/mnt/gfarm2fs",
      filesize: "1M", number: "3", replica: "2"}
       ]    
}
</literallayout>
<para>
Following sentences explain keywords of the YAML.
</para>
<variablelist>
  <varlistentry>
    <term>database</term>
    <listitem>
      <para>
	Specify databse filename in filename: .
	Specify backup of database file in backup: .
	check span: specifies time span of calculating average and standard deviation.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>errlog</term>
    <listitem>
      <para>
	This commands prints error messsages in the file specified by errlog: .
	All error messages are also written in the database.
	If you don't need to error log file, this parameter can be omitted.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>authentication</term>
    <listitem>
      <para>
	Specify authentication types of performance measuring.
	Authentication types are sharedsecret, gsi_auth and gsi.
	Performance test is executed on all specified types.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>gfarm2fs_mountpoint</term>
    <listitem>
      <para>
	Specify gfarm2fs mount point.
	When start testing, this command mounts all gfarm2fs mount point automatically. At the end of testing, unmounted automatically.
	When changing authenticaion type, remounted automatically.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>metadata</term>
    <listitem>
      <para>
	Perfomance measuring using gfperf-metadata.
	Parameters are gfperf-metadata long options.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>tree</term>
    <listitem>
      <para>
	Perfomance measuring using gfperf-tree.
	Parameters are gfperf-tree long options.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>copy</term>
    <listitem>
      <para>
	Perfomance measuring using gfperf-copy.
	Parameters are gfperf-copy long options.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>read</term>
    <listitem>
      <para>
	Perfomance measuring using gfperf-read.
	Parameters are gfperf-read long options.
	If you need to test sequentially read, remove random option.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>write</term>
    <listitem>
      <para>
	Perfomance measuring using gfperf-write.
	Parameters are gfperf-write long options.
	If you need to test sequentially write, remove random option.
	If you need to test append write, remove overwrite option.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>replica</term>
    <listitem>
      <para>
	Perfomance measuring using gfperf-replica.
	Parameters are gfperf-replica long options.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>autoreplica</term>
    <listitem>
      <para>
	Perfomance measuring using gfperf-autoreplica.
	Parameters are gfperf-autoreplica long options.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>parallel</term>
    <listitem>
      <para>
	Specify parallel test patterns.
	At first, specify group name that is a sinbol of parallel testing.
	Group name must be uniq in all parallel testing (includes parallel-autoreplica).
	Specify remote host in rhost: . This command uses ssh for executing command.
	type: specifies one of read, write, replica. These types corresponds to gfperf-parallel-read, gfperf-parallel-write, gfperf-parallel-replica.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>parallel-autoreplica</term>
    <listitem>
      <para>
	Specify auto replication test in parallel.
	At first, specify group name that is a sinbol of parallel testing.
	Group name must be uniq in all parallel testing (includes parallel).
	Test parameters are gfperf-parallel-autoreplica long options.
	The result is average of gfperf-parallel-autoreplica outputs.
      </para>
    </listitem>
  </varlistentry>

</variablelist>
</refsect1>


<refsect1 id="see-also"><title>SEE ALSO</title>
<para>
  <citerefentry>
  <refentrytitle>gfperf-metadata</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-tree</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-copy</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-read</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-write</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-replica</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-autoreplica</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-parallel-read</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-parallel-write</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-parallel-replica</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
  <citerefentry>
  <refentrytitle>gfperf-parallel-autoreplica</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>,
</para>
</refsect1>

<refsect1 id="notes"><title>NOTES</title>
<para>
Using ssh command execution, no password is recommended.
</para>
<para>
Bash doesn't read ~/.bashrc in some envronment.
Please check before running gfperf.rb.
</para>
</refsect1>

</refentry>
