<!-- 
Fcron documentation
Copyright 2000-2024 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.
-->


   <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 which adhere to the format defined in <link linkend="fcrontab.5">&fcrontab;(5)</link></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 their &fcrontabf;
		directly (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 it to be
	    edited, and a formatted file is generated for the &fcron; daemon.
		This formatted (non human readable) file with all recent changes
		included is then sent to the daemon.
		The daemon is not informed of the changes immediately but after some time
	    to keep ill disposed users from blocking the daemon by installing
	    &fcrontabf;s over and over (i.e. denial of service attack).
		By default, the file is sent once per minute (about ten seconds before
		the full minute) to the daemon, the build time parameter
		<option>--with-max-fcrontab-reload-delay-seconds</option>
		can be used to specify a different maximum time to send this data.
		We will call
	    "<emphasis>fcrontab</emphasis>" the source file of the &fcrontabf;
	    in the following.</para>
		<para>The fcrontab files that a user modifies has to follow the format
		defined in <link linkend="fcrontab.5">&fcrontab;(5)</link> .</para>
		<para>Users can install a &fcrontabf; if
	    they are listed in <filename>&etc;/&fcron.allow;</filename> and not listed in
	    <filename>&etc;/&fcron.deny;</filename> (see section "<link
	    linkend="fcrontab.1.files">files</link>" below).
		The keyword 'all' is a shorthand for all users. 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 root 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 a single
		     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:
-->
