Merge branch 'master' into squeeze

[debian/amanda] / man / xml-source / amanda-interactivity.7.xml

diff --git a/man/xml-source/amanda-interactivity.7.xml b/man/xml-source/amanda-interactivity.7.xml
new file mode 100644 (file)
index 0000000..66616f7
--- /dev/null
+++ b/man/xml-source/amanda-interactivity.7.xml
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
+[
+  <!-- entities files to use -->
+  <!ENTITY % global_entities SYSTEM 'global.entities'>
+  %global_entities;
+]>
+
+<refentry id='amanda-interactivity.7'>
+
+<refmeta>
+<refentrytitle>amanda-interactivity</refentrytitle>
+<manvolnum>7</manvolnum>
+&rmi.source;
+&rmi.version;
+&rmi.manual.7;
+</refmeta>
+<refnamediv>
+<refname>amanda-interactivity</refname>
+<refpurpose>Configuring Interactivity with Amanda Amanda</refpurpose>
+</refnamediv>
+<refentryinfo>
+&author.jlm;
+</refentryinfo>
+<!-- body begins here -->
+
+<refsect1><title>DESCRIPTION</title>
+
+<para>Amanda uses interactivity to ask user to load specific volumes when
+they are needed.  This manual page describes the interactivity modules
+included with Amanda.</para>
+
+<para>This is a <emphasis>user-level</emphasis> description of the API, and
+does not address details that are only of concern to developers of new
+interactivity plugins.  For that purpose, consult the Amanda source code,
+perldoc 'Amanda::Interactivity' and http://wiki.zmanda.com.</para>
+
+</refsect1>
+
+<refsect1><title>DEFINING INTERACTIVITY</title>
+
+<para>Interactivity is specified in &amconf; as follows:
+
+<programlisting>
+define interactivity $interactivity_name {
+   comment "$comment"
+   plugin "$pluginname"
+   property "$PROPERTY_NAME" "$PROPERTY_VALUE"
+   ...
+}
+</programlisting>
+and then referenced in the global section as
+<programlisting>
+  interactivity "$interactivity_name"
+</programlisting></para>
+
+<para>Interactivity properties, like Amanda configuration parameters, are
+insensitive to case, and <literal>-</literal> (dash) and
+<literal>_</literal> (underscore) may be used interchangeably.</para>
+
+<para>See the individual plugin sections, below for properties applicable to
+each plugin.</para>
+
+</refsect1>
+
+<refsect1><title>INTERACTIVITY MODULES</title>
+
+<para>Amanda provides three interactivity modules, <emphasis>tty</emphasis>,
+<emphasis>email</emphasis> and <emphasis>tty_email</emphasis>.</para>
+
+<refsect2><title>TTY</title>
+
+<para>The <emphasis>tty</emphasis> interactivity module uses the tty to
+communicate with the user, it works only if a terminal is available, which is
+the case if amanda is executed from a command line.</para>
+
+<para>When promted for a volume, the user must put the requested volume
+in the changer and type &lt;enter&gt;. User can type the name of another
+changer if the volume is available in that changer. Typing 'abort' will
+abort the operation.</para>
+
+</refsect2>
+
+<refsect2><title>EMAIL</title>
+
+<para>The <emphasis>email</emphasis> interactivity module uses email to send requests to the user, and reads replies from the filesystem.</para>
+
+<para>The <emphasis>email</emphasis> module has many properties:</para>
+
+<variablelist>
+ <!-- ==== -->
+ <varlistentry><term>check-file</term><listitem>
+If set, amanda will check this file for user input.  The user can touch the
+file to tell amanda that the requested volume was inserted in the changer.  If the user
+writes the name of a changer into the file, Amanda will use that changer.  If the user
+writes the word 'abort' into the file, the scan will be aborted.
+</listitem></varlistentry>
+ <!-- ==== -->
+ <varlistentry><term>check-file-delay</term><listitem>
+Default: 10. This integer property indicates the time in seconds between each check of the check-file.
+</listitem></varlistentry>
+ <!-- ==== -->
+ <varlistentry><term>mailto</term><listitem>
+Default: global value of <amkeyword>mailto</amkeyword>.  The email addresses to which
+the email should be sent.  If multiple addresses are given, they should be
+separated by spaces. 
+</listitem></varlistentry>
+ <!-- ==== -->
+ <varlistentry><term>resend-delay</term><listitem>
+Default 0. The time in seconds between emails.  Amanda will resend the same
+email at this frequency, which can be useful if <amkeyword>mailto</amkeyword>
+is a pager or phone.  If set to 0, only one email is sent.
+</listitem></varlistentry>
+</variablelist>
+
+</refsect2>
+
+<refsect2><title>TTY_EMAIL</title>
+
+<para>The <emphasis>tty_email</emphasis> interactivity module uses the
+<emphasis>tty</emphasis> module if a terminal is available and uses the
+<emphasis>email</emphasis> module otherwise.  Its properties are a
+combination of properties from each module.</para>
+
+</refsect2>
+</refsect1>
+
+<refsect1><title>EXAMPLE</title>
+
+<para><programlisting>
+  define interactivity "by-tty-or-email" {
+    comment "Send email on runs from cron; use terminal on command line"
+    plugin "tty_email"
+    property "mailto" "admin1" "admin2" "me@home"
+    property "resend-delay" "1800"               #every 30 minutes
+    property "check-file" "/tmp/email_input"
+    property "check-file-delay" "10"             #every 10 seconds
+  }
+</programlisting></para>
+
+</refsect1>
+
+<seealso>
+<manref name="amanda.conf" vol="5"/>,
+</seealso>
+
+</refentry>