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

<refentryinfo><date>13 Feb 2020</date></refentryinfo>

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

<refnamediv id="name">
<refname>gfkey</refname>
<refpurpose>management of Gfarm session keys</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis">
<cmdsynopsis sepchar=" ">
  <command moreinfo="none">gfkey</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">gfkey</command> manages the session key file,
<filename moreinfo="none">$HOME/.gfarm_shared_key</filename>,
that is used for user authentication by a shared secret key
in a trusted environment when
connecting to gfsd and/or gfmd.
The location of the seesion key file can be specified by
shared_key_file in gfarm2.conf.
</para>

<para>When the home directory is shared among filesystem nodes, it is not
necessary to use this command.  If not, it is necessary to distribute
a session key  created with
the -c or -f option to every filesystem node, in advance.
</para>

</refsect1>

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

<varlistentry>
<term><option>-c</option></term>
<listitem>
<para>Creates a new session key when there is no valid session key.  If
a valid session key already exists, no operation is performed.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-f</option></term>
<listitem>
<para>Forces the creation of a new session key, even if a valid session
key already exists.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-p</option> <parameter moreinfo="none">period</parameter></term>
<listitem>
<para>Specifies the term of validity in seconds.  This option has to be
used with the -c or -f option.  Default is 86400 seconds (1 day).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-l</option></term>
<listitem>
<para>Displays the current key.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-e</option></term>
<listitem>
<para>Displays the expiration date of the current key.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-L</option> <parameter moreinfo="none">message-priority-level</parameter></term>
<listitem>
<para>Specifies a level of the log priority.  The log messages that
have higher or the same priority than the specified priority are
displayed to the standard error.  The default priority is info.  Refer
to the <token>log_level</token> directive described in the manual page
of gfarm2.conf(5) for the priority level which can be specified by
this option.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-V</option></term>
<listitem>
<para>Displays the version information.</para>
</listitem>
</varlistentry>

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

</variablelist>
</refsect1>

<refsect1 id="files"><title>FILES</title>

<variablelist>
<varlistentry>
<term><filename moreinfo="none">$HOME/.gfarm_shared_key</filename></term>
<listitem>
<para>a file for a session key</para>
</listitem>
</varlistentry>
</variablelist>

</refsect1>
</refentry>
