<?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>

<refentryinfo><date>12 Nov 2006</date></refentryinfo>

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

<refnamediv>
<refname>gfrcmd</refname>
<refpurpose>Gfarm remote shell</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfrcmd</command>
    <arg choice="plain" rep="norepeat"><replaceable>host</replaceable></arg>
    <arg choice="plain" rep="repeat"><replaceable>command</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para><command moreinfo="none">gfrcmd</command> logs into a filesystem node <parameter moreinfo="none">host</parameter> and executes
<parameter moreinfo="none">command</parameter>s on the filesystem node.  It provides a similar
functionality to rsh.  The following is a list of differences, however.</para>

<para>A remote server is not executed by inetd, but is incorporated with
gfsd(8).</para>

<para>The user is authenticated and authorized by the Gfarm security
mechanism.  Since this does not rely on privileged TCP ports  for
authentication like rsh, the maximum number of remote executions is
not limited by the number of privileged ports.</para>

<para>Unlike rsh, <command moreinfo="none">gfrcmd</command> utilizes a single TCP connection to a
filesystem node.  It requires less kernel resources than rsh when
several processes are executed.</para>

<para><command moreinfo="none">gfrcmd</command> inherits the environment variable DISPLAY and the
authentication information of the X Window System.</para>

<para>On the filesystem node, the current working directory is not the home
directory that is often shared using NFS, but a spool directory of the
Gfarm filesystem, which makes it possible to leave core files on each
filesystem node when debugging.</para>

<para>It has functionality that invokes a debugger when a fatal signal
occurs.</para>

</refsect1>

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

<variablelist>

<varlistentry>
<term><option>-l</option><parameter moreinfo="none">username</parameter></term>
<listitem>
<para>Specifies a username on a remote host.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-n</option></term>
<listitem>
<para>Redirects the standard input from the special device /dev/null.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-r</option></term>
<listitem>
<para>Executes a remote command directly without using a login shell.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-y</option></term>
<listitem>
<para>Inherits the environment variable, DISPLAY.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-X</option></term>
<listitem>
<para>Inherits the authentication information of the X Window System.  It
is useful in a situation where the home directory is not
shared.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-v</option></term>
<listitem>
<para>Displays error message verbosely.
</para>
</listitem>
</varlistentry>

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

</variablelist>

</refsect1>

<refsect1 id="environment-variables"><title>ENVIRONMENT VARIABLES</title>

<variablelist>
<varlistentry>
<term><envar>GFARM_DEBUG_MODE</envar></term>
<listitem>
<para>Specifies the debugger command that is invoked when a remotely
executed command aborts with a fatal signal.  When gdb is specified,
xterm and the GNU debugger gdb are executed.
To utilize this functionality, it is necessary to invoke <command moreinfo="none">gfrcmd</command>
on the X Window System.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 id="bugs"><title>BUGS</title>
<para>The -l option is not implemented yet.
</para>
</refsect1>
</refentry>
