<!-- 
Fcron documentation
Copyright 2000-2007 Thibault Godouet <fcron@free.fr>
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation.
A copy of the license is included in gfdl.sgml.
-->

<!-- $Id: fcrontab.1.sgml,v 1.12 2007/04/14 18:04:35 thib Exp thib $ -->

   <refentry id="fcrontab.1">
      <refmeta>
	 <refentrytitle>fcrontab</refentrytitle> <manvolnum>1</manvolnum>
	 <refmiscinfo>Fcron &version; <![%devrelease; [
	 (<emphasis>development</emphasis> release)]]></refmiscinfo>
	 <refmiscinfo>&date;</refmiscinfo>
      </refmeta>
      <refnamediv>
	 <refname>fcrontab</refname> <refpurpose>manipulate per-user fcrontab
	    files</refpurpose>
      </refnamediv>

      <refsynopsisdiv id="fcrontab.1.synopsis">
	 <cmdsynopsis>
	    <command>fcrontab</command> <arg>-c
	       <replaceable>file</replaceable></arg> <arg>-n</arg> <arg
	       choice="plain"><replaceable>file</replaceable></arg>
	    <group>
	       <arg><replaceable>user</replaceable></arg> <arg>-u
		  <replaceable>user</replaceable></arg>
	    </group>
	 </cmdsynopsis>
	 <cmdsynopsis>
	    <command>fcrontab</command> <arg>-c
	       <replaceable>file</replaceable></arg> <arg>-n</arg>
	    <group choice="req">
	       <arg>-l</arg> <arg>-r</arg> <arg>-e</arg> <arg>-z</arg>
	    </group>
	    <group>
	       <arg><replaceable>user</replaceable></arg> <arg>-u
		  <replaceable>user</replaceable></arg>
	    </group>
	 </cmdsynopsis>
	 <cmdsynopsis>
	    <command>fcrontab</command> <arg>-h</arg>
	 </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
	 <title>Description</title> <para>&Fcrontab; is the program intended to
	    install, edit, list and remove the tables used by <link
	    linkend="fcron.8">&fcron;(8)</link> daemon. As &fcron; internally
	    uses a non-human readable format (this is needed because &fcron;
	    saves more informations than the user gives, for example the time
	    and date of next execution), the user cannot edit directly his
	    &fcrontabf; (the one used by &fcron;).</para> <para>When a user
	    installs a &fcrontabf;, the source file is saved in the spool
	    directory (<filename>&fcrontabsdir;</filename>) to allow future
	    editions, and a formatted file is generated for the &fcron; daemon,
	    which is signaled once about ten seconds before the next minute for
	    all changes made previously. The daemon is not informed of the changes
	    immediately but at most once a minute
	    to keep ill disposed users from blocking the daemon by installing
	    &fcrontabf;s over and over (ie. denial of service attack). We will call
	    "<emphasis>fcrontab</emphasis>" the source file of the &fcrontabf;
	    in the following.</para> <para>A user can install a &fcrontabf; if
	    he is listed in the <filename>&etc;/&fcron.allow;</filename> and not
	    (unless by the keyword all) listed in
	    <filename>&etc;/&fcron.deny;</filename> (see section "<link
	    linkend="fcrontab.1.files">files</link>" below). If neither
	    <filename>fcron.allow</filename> nor <filename>fcron.deny</filename>
	    exist, all users are allowed. None of these files have to exist, but
	    if they do, the deny file takes precedence.</para> <para>The first
	    form of the command is used to install a new &fcrontabf; file, from
	    any named file or from standard input if the pseudo-filename "-" is
	    given, replacing the previous one (if any): each user can have only
	    one &fcrontabf;.</para> <para>For instance, root can create a
	    systemwide fcrontab file, say <filename>/etc/fcrontab</filename>,
	    and run "<command>fcrontab</command>
	    <filename>/etc/fcrontab</filename>" to install the new version after
	    each change of the file. Or (s)he can create a new fcrontab running
	    a simple "<command>fcrontab</command>", and then maintain it using
	    "<command>fcrontab</command> <option>-e</option>". Same
	    considerations apply to a non privileged user.</para>
      </refsect1>

      <refsect1>
	 <title>Options</title>
	 <variablelist>
	    <varlistentry>
	       <term><option>-u</option> <replaceable>user</replaceable></term>
	       <listitem>
		  <para>Specify the user whose &fcrontabf; will be managed, or
		     "&sysfcrontab;" for the system fcrontab.  Should only be
		     used by root. If not given, the &fcrontabf; file of the
		     user invoking &fcrontab; will be handled. It may be useful
		     since the <application>su</application>(8) command may
		     confuse &fcrontab;.  <note><para>the
		     '<replaceable>user</replaceable>' in the <link
		     linkend="fcrontab.1.synopsis">synopsys</link> is equivalent
		     to a '<option>-u</option>
		     <replaceable>user</replaceable>'.</para> </note></para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><option>-l</option></term>
	       <listitem>
		  <para>List user's current &fcrontabf; to standard
		     output.</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><option>-e</option></term>
	       <listitem>
		  <para>Edit user's current &fcrontabf; using either the editor
		     specified by the environment variable
		     <envar>VISUAL</envar>, or <envar>EDITOR</envar> if
		     <envar>VISUAL</envar> is not set. If none or them are set,
		     <command>&editor;</command> will be used.</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><option>-r</option></term>
	       <listitem>
		  <para>Remove user's &fcrontabf;.</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><option>-z</option></term>
	       <listitem>
		  <para>Reinstall user's &fcrontabf; from its source code. All
		     informations &fcron; may have kept in the binary
		     &fcrontabf; (such as the last execution time and date) will
		     be forgotten (ie. lost).</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><option>-n</option></term>
	       <listitem>
		  <para>Ignore previous version. If this option is not given,
		     &fcron; will try to keep as much information as possible
		     between old and new version of the &fcrontabf; (time and
		     date of next execution, if job is in serial queue, etc) if
		     the line hasn't been modified (same fields, same shell
		     command).</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><option>-c</option> <replaceable>file</replaceable></term>
	       <listitem>
		  <para>Make &fcrontab; use config file
		     <replaceable>file</replaceable> instead of default config
		     file <filename>&etc;/&fcron.conf.location;</filename>. To
		     interact with a running &fcron; process, &fcrontab; must
		     use the same config file as the process. That way, several
		     &fcron; processes can run simultaneously on an only
		     system.</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><option>-d</option></term>
	       <listitem>
		  <para>Run in debug mode. In this mode, many informational
		     messages will be output in order to check if anything went
		     wrong.</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><option>-h</option></term>
	       <listitem>
		  <para>Display a brief description of the options.</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><option>-V</option></term>
	       <listitem>
		  <para>Display an informational message about &fcrontab;,
		     including its version and the license under which it is
		     distributed.</para>
	       </listitem>
	    </varlistentry>
	 </variablelist>
      </refsect1>

      <refsect1>
	 <title>Return values</title> <para>&Fcrontab; returns &exitok; on
	    normal exit and &exiterr; on error.</para>
      </refsect1>

      <refsect1>
	 <title>Conforming to</title> <para>Should be POSIX compliant.</para>
      </refsect1>

      <refsect1 id="fcrontab.1.files">
	 <title>Files</title>
	 <variablelist>
	    <varlistentry>
	       <term><filename>&etc;/&fcron.conf.location;</filename></term>
	       <listitem>
		  <para>Configuration file for &fcron;, &fcrontab; and
		     &fcrondyn;: contains paths (spool dir, pid file) and
		     default programs to use (editor, shell, etc). See <link
		     linkend="fcron.conf.5">&fcron.conf;(5)</link> for more
		     details.</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><filename>&etc;/&fcron.allow;</filename></term>
	       <listitem>
		  <para>Users allowed to use &fcrontab; and &fcrondyn; (one name
		     per line, special name "all" acts for everyone)</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><filename>&etc;/&fcron.deny;</filename></term>
	       <listitem>
		  <para>Users who are not allowed to use &fcrontab; and
		     &fcrondyn; (same format as allow file)</para>
	       </listitem>
	    </varlistentry>
	    <varlistentry>
	       <term><filename>&etc;/pam.d/fcron</filename> (or
		  <filename>&etc;/pam.conf</filename>)</term>
	       <listitem>
		  <para><productname>PAM</productname> configuration file for
		     &fcron;. Take a look at pam(8) for more details.</para>
	       </listitem>
	    </varlistentry>
	 </variablelist>
      </refsect1>

      &manpage-foot;

   </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("fcron-doc.sgml" "book" "chapter" "sect1" "")
End:
-->
