File: Autodir-HOWTO.html

package info (click to toggle)
autodir 0.99.9-2
  • links: PTS
  • area: non-free
  • in suites: lenny
  • size: 1,932 kB
  • ctags: 832
  • sloc: sh: 8,611; ansic: 7,682; xml: 431; makefile: 104
file content (81 lines) | stat: -rw-r--r-- 53,319 bytes parent folder | download | duplicates (2) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Autodir HOWTO</title><meta name="generator" content="DocBook XSL Stylesheets V1.61.2"><meta name="description" content="
		This HOWTO is about Autodir installation, configuration and other issues related to Autodir.
        "></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id3484882"></a>Autodir HOWTO</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Venkata Ramana</span> <span class="surname">Enaganti</span></h3><div class="affiliation"><div class="address"><p><tt class="email">&lt;<a href="mailto:ramana%20&lt;&gt;%20intraperson%20dot%20com">ramana&lt;&gt;intrapersondotcom</a>&gt;</tt></p></div></div></div></div><div><p class="pubdate">2004-09-23</p></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 1.02</td><td align="left">2004-12-25</td><td align="left">VRE</td></tr><tr><td align="left" colspan="3">Minor updates</td></tr><tr><td align="left">Revision 1.00</td><td align="left">2004-09-23</td><td align="left">VRE</td></tr><tr><td align="left" colspan="3">Initial release, reviewed by Rahul Sundaram at TLDP</td></tr><tr><td align="left">Revision 0.32</td><td align="left">2004-09-13</td><td align="left">VRE</td></tr><tr><td align="left" colspan="3">New sections like requirements and others.</td></tr><tr><td align="left">Revision 0.10</td><td align="left">2004-06-24</td><td align="left">VRE</td></tr><tr><td align="left" colspan="3">second draft</td></tr><tr><td align="left">Revision 0.9</td><td align="left">2004-06-11</td><td align="left">VRE</td></tr><tr><td align="left" colspan="3">first draft</td></tr></table></div></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>
		This HOWTO is about <span class="bold"><b>Autodir</b></span> installation, configuration and other issues related to <span class="bold"><b>Autodir</b></span>.
        </p></div></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#intro">Introduction</a></dt><dd><dl><dt><a href="#copyright">Copyright and License</a></dt><dt><a href="#disclaimer">Disclaimer</a></dt><dt><a href="#feedback">Feedback</a></dt><dt><a href="#id3416903">New Versions of this Document</a></dt><dt><a href="#credits">Credits / Contributors</a></dt></dl></dd><dt><a href="#id3475924">Before going to details...</a></dt><dt><a href="#id3475979">Why not pam_mkhomedir?</a></dt><dt><a href="#id3476072">Where it can be used</a></dt><dt><a href="#id3476115">What it is not</a></dt><dt><a href="#id3476144">Differences between Autodir and Autofs</a></dt><dt><a href="#id3415905">How it works</a></dt><dt><a href="#id3470663">Some definitions</a></dt><dt><a href="#dirorg">Directory organization under real base directory</a></dt><dt><a href="#vdexp">Virtual directory expiration</a></dt><dt><a href="#backup">Backup support</a></dt><dt><a href="#backupreq">Backup program requirements</a></dt><dt><a href="#id3476718">Module options</a></dt><dt><a href="#id3476821">Autodir requirements</a></dt><dt><a href="#autofs_kmod">Loading autofs kernel module</a></dt><dt><a href="#id3417555">Importing user and group accounts</a></dt><dt><a href="#id3417580">Getting it</a></dt><dt><a href="#homedir">Managing Home directories</a></dt><dd><dl><dt><a href="#id3469861">Base directories for autohome</a></dt><dt><a href="#id3470068">Directory organization</a></dt><dt><a href="#id3470116">Misc suboptions for autohome</a></dt><dt><a href="#id3470169">Summing up with an example</a></dt></dl></dd><dt><a href="#id3470352">Managing group directories</a></dt><dt><a href="#aoptions">Autodir options</a></dt><dt><a href="#backupopts">Backup options</a></dt><dt><a href="#id3418240">Examples</a></dt><dt><a href="#id3418279">RPM specific</a></dt><dt><a href="#moreinfo">Further Information</a></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro"></a>Introduction</h2></div></div><div></div></div><p><span class="bold"><b>Autodir</b></span> offers a simple and effective means to create directories like home directories in a transparent manner. It relies on the <a href="htp://www.autofs.org" target="_top">autofs</a> protocol for its operation.</p><p>This document explains how to create directories on demand using <span class="bold"><b>Autodir</b></span> in a transparent way to the applications. This document also explains using transparent backup feature that is possible with <span class="bold"><b>Autodir</b></span> without bringing system down for backup purpose for all directories managed by <span class="bold"><b>Autodir</b></span>.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="copyright"></a>Copyright and License</h3></div></div><div></div></div><p>
     This document, <span class="emphasis"><em>Autodir HOWTO</em></span>,
     is copyrighted (c) 2004 by <span class="emphasis"><em>Venkata Ramana Enaganti</em></span>.

This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit <a href="http://creativecommons.org/licenses/by/2.0" target="_top">http://creativecommons.org/licenses/by/2.0/</a> or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

    </p><p>
     Linux is a registered trademark of Linus Torvalds.
    </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="disclaimer"></a>Disclaimer</h3></div></div><div></div></div><p>
     No liability for the contents of this document can be accepted.
     Use the concepts, examples and information at your own risk.
     There may be errors and inaccuracies, that could be damaging to
     your system.  Proceed with caution, and although this is highly
     unlikely, the author(s) do not take any responsibility.
    </p><p>
     All copyrights are held by their by their respective owners,
     unless specifically noted otherwise.  Use of a term in this
     document should not be regarded as affecting the validity of any
     trademark or service mark.  Naming of particular products or
     brands should not be seen as endorsements.
    </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="feedback"></a>Feedback</h3></div></div><div></div></div><p>
     Feedback is most certainly welcome for this document. Send
     your additions, comments and criticisms to the following
     email address : <tt class="email">&lt;<a href="mailto:ramana%20&lt;&gt;%20intraperson%20dot%20com">ramana &lt;&gt; intraperson dot com</a>&gt;</tt>.
    </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3416903"></a>New Versions of this Document</h3></div></div><div></div></div><p>The latest version of this HOWTO will be made available from <a href="http://www.intraperson.com/autodir/" target="_top">http://www.intraperson.com/autodir/</a>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="credits"></a>Credits / Contributors</h3></div></div><div></div></div><p>
     In this document, I have the pleasure of acknowledging for language and technical review work:
    </p><div class="itemizedlist"><ul type="disc"><li><p>Rahul Sundaram<tt class="email">&lt;<a href="mailto:rahulsundaram@yahoo.co.in">rahulsundaram@yahoo.co.in</a>&gt;</tt></p></li></ul></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3475924"></a>Before going to details...</h2></div></div><div></div></div><p>After releasing intraperson beta, I started working on a administration guide that deals with administration aspects of <span class="bold"><b>intraPerson</b></span>. For more details check <a href="http://www.intraperson.com" target="_top"> http://www.intraperson.com</a>. But I was stuck with one simple thing. It is easy to create users in ldap -- at least I think so; but how to create home directories for those users in ldap wherever those ldap accounts are imported?</p><p>I found some solutions But I was not satisfied as every solution has serious drawback attached with it. But after going through autofs documents and hacking little bit, I arrived at conclusion that autofs protocol might offer much better solution to this challenge.</p><p>The result is <span class="bold"><b>Autodir</b></span>, based on the autofs protocol.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3475979"></a>Why not pam_mkhomedir?</h2></div></div><div></div></div><p>PAM module <tt class="literal">pam_mkhomedir</tt> uses Pluggable Authentication Module architecture for its operation. As such, there are some limitations associated with it. For instance:</p><div class="itemizedlist"><ul type="disc"><li><p>Some servers may not authenticate users but they may expect user directories to exist. This means they do not use PAM, and in turn, <tt class="literal">pam_mkhomedir</tt> does not get a chance to create home directories. The notorious example is on email servers.</p></li><li><p>PAM is always an optional component for authentication. Some may not use PAM at all and use a different method to authenticate users. In this case <tt class="literal">pam_mkhomedir</tt> is never going to be used.</p></li><li><p>Generally <tt class="filename">/home</tt> is owned by root and only root users can create home directories in it. Therefore the server that wishes to create home directories through PAM must be run as root, or else the home directory must be made similar in permission to <tt class="filename">/tmp</tt>.</p></li></ul></div><p>Finally, <span class="bold"><b>Autodir</b></span> is much wider in scope and supports many more interesting features.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3476072"></a>Where it can be used</h2></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>Where user accounts reside in centralized database like ldap, SQL, NIS, NIS+ or other databases, from which user and groups are imported to other systems. To create, for example home, group directories in those systems which import these accounts from centralized database, on demand.</p></li><li><p>To exploit its transparent backup feature for 24*7 online systems.</p></li><li><p>It can be also used even when accounts are in a local system, to some extent hiding what accounts exist in <tt class="filename">/home</tt> directory, for example.</p></li></ul></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3476115"></a>What it is not</h2></div></div><div></div></div><p><span class="bold"><b>Autodir</b></span> can create directories but it does not remove them once user, group entries are removed from system accounts database. And there may be some more limitations with modules used with <span class="bold"><b>Autodir</b></span>. Check appropriate sections.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3476144"></a>Differences between Autodir and Autofs</h2></div></div><div></div></div><p>Now the important issue arises as there is already an autofs package to handle mounts and Autodir is in similar line with the autofs package.</p><div class="itemizedlist"><ul type="disc"><li><p>The main purpose of autofs is to deal with network mounts on demand instead of mounting all at the same time, which results in preserving system resources. Though there is some support in the autofs package to mount home directories on demand, the requirement is that <span class="emphasis"><em>these home directories must exist already</em></span>.</p><p>On the other side, <span class="bold"><b>Autodir</b></span> specializes <span class="emphasis"><em>only</em></span> in local directory creation and mounting them on demand.</p><p><span class="bold"><b>Autodir</b></span> can also create real directories in disk file systems such that they do not reside in one single flat base directory. This is how utilities like <b class="command">useradd</b> create by default. In a standard file system setup, all home directories reside in base <tt class="filename">/home</tt> directory. For file systems like ext2, ext3 performance will degrade if large number of home directories exist in single base directory.</p><p> For applications accessing these directories, <span class="bold"><b>Autodir</b></span> presents all directories for them in a <span class="emphasis"><em>single</em></span> autofs mounted virtual base directory <span class="emphasis"><em>on demand</em></span>; actual directories are created in subdirectories of some other directory in hierarchical style.</p><p> For example, the real home for a user with uid <tt class="literal">user1</tt> will be created as <tt class="filename">/autohome/u/us/user1</tt> if configured that way, but mounted in <tt class="filename">/home</tt> on demand for applications accessing home directory in <tt class="filename">/home/user1</tt>.</p><p>Permissions for real base directory, where actual home directories are kept <tt class="filename">/autohome</tt> in the above example, are kept in such a way that <tt class="filename">/autohome</tt> can not be accessed by anyone except by root.</p><p>This mounting of directories on demand and unmounting when not in use presents an interesting opportunity -- the ability to tell when a directory is in use and when it is not in use. This simply means a program like backup can be started when a directory is unmounted.</p><p><span class="bold"><b>Autodir</b></span> exploits this capability by starting the command-line mentioned backup whenever a directory becomes unused.</p></li><li><p>There is one more important issue to be presented if you are an administrator reading this document. <span class="bold"><b>Autodir</b></span> does not call external programs <b class="command">mount</b> and <b class="command">umount</b>, as is the case with the autofs package; rather, it uses system calls directly. As a side effect, it is faster and more reliable, but <tt class="filename">mtab</tt> is not updated. I felt this was not necessary as all mounts and unmounts are local directories.</p></li><li><p>Another minor difference is that <span class="bold"><b>Autodir</b></span> is completely <span class="emphasis"><em>multi-threaded</em></span>. Autofs is also expected to be multi-threaded in future versions.</p></li></ul></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3415905"></a>How it works</h2></div></div><div></div></div><p><span class="bold"><b>Autodir</b></span> uses modules to get specific functionality. The core <span class="bold"><b>Autodir</b></span> implements generic functionality on which modules can exploit and add specific functionality of their own.</p><p>At any moment only one module can be added to <span class="bold"><b>Autodir</b></span>. If there are two modules, for example <tt class="literal">autohome</tt>, <tt class="literal">autogroup</tt>, two processes of <span class="bold"><b>Autodir</b></span> should be created so that each process will have required modules attached to it.</p><p>For further explanation I chose the <tt class="literal">autohome</tt> module which handles transparent home directory creation.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">autohome</tt> module creates user home directories on demand if these does not exist already.</p></li><li><p>It is assumed user accounts exists but not their home directories.  Either because these accounts were created with the <tt class="literal">-M</tt> option with <b class="command">useradd</b> or these accounts were imported from ldap, NIS or some other external database for which home directories are yet to be created.</p></li><li><p>It also assumed <span class="emphasis"><em>for this explanation only</em></span> that all user home directories are expected to be in the <tt class="filename">/home</tt> directory.</p></li></ul></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Some fine details are intentionally kept aside to make explanation easy to understand.</p></div><p>First autofs file system is mounted on <tt class="filename">/home</tt> directory by <span class="bold"><b>Autodir</b></span>. And this is informed to the Linux kernel that <tt class="filename">/home</tt> is managed by user space application <span class="bold"><b>Autodir</b></span> from now on.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Do not bother too much about autofs file system if you do not understand about it. Just think some special kind of file system something in similarity with memory based file system but with some additional special properties.</div><pre class="screen">

                                +----------------+
                                |  Linux Kernel  |
                                +----------------+
                                  /        \
                                 /          \
                                /            \
                               /              \
   +-------------+       +--------+       +------------+        +-----------------+
   | Application |------&gt;| /home  |&lt;-----&gt;|  Autodir   |&lt;------&gt;| autohome module |
   +-------------+       +--------+       +------------+        +-----------------+
                              \                                          /
                               \  +----------------+                    /
                                +-|   /autohome    |&lt;------------------+
                                  +----------------+
</pre><p>Whenever an application or daemon needs access to user's home directory, for example <tt class="filename">/home/userhome1</tt>, they directly enter into <tt class="filename">/home/userhome1</tt> to access it. Kernel which notices this, informs to <span class="bold"><b>Autodir</b></span> if <tt class="filename">userhome1</tt> directory does not exist already in <tt class="filename">/home</tt>.</p><p><span class="bold"><b>Autodir</b></span>, in turn, passes this request to <tt class="literal">autohome</tt> module. <tt class="literal">autohome</tt> module does not touch <tt class="filename">/home</tt> directory. Instead it manages <span class="emphasis"><em>real home directories</em></span> some where else, for example in <tt class="filename">/autohome</tt> as shown in the above figure.</p><p><tt class="literal">autohome</tt> module creates real home directory if it does not exist already in <tt class="filename">/autohome</tt> directory. After it is successfully created or failed to created, whatever the outcome, it is reported back to <span class="bold"><b>Autodir</b></span> along with the path to real home directory -- if successful.</p><p>If <tt class="literal">autohome</tt> module reports success, <span class="bold"><b>Autodir</b></span> creates <tt class="filename">userhome1</tt> directory under <tt class="filename">/home</tt> and mounts <span class="emphasis"><em>real home directory</em></span> from <tt class="filename">/autohome</tt> on it. At the end <span class="bold"><b>Autodir</b></span> informs this to the kernel whether this whole operation successful or failure. Accordingly kernel allows application to enter the directory or reports that no such directory exists, in case of failure, back to the application.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3470663"></a>Some definitions</h2></div></div><div></div></div><p>Before going further it is better to understand the following terms to simplify explanation.</p><div class="variablelist"><dl><dt><span class="term"><span class="bold"><b>Virtual directories</b></span></span></dt><dd><p> These directories do not exist on disk.  Instead these are created and deleted on demand in memory. If system reboots all these directories vanish. In the previous figure, all directories under <tt class="filename">/home</tt> are <span class="emphasis"><em>virtual directories</em></span>.</p></dd><dt><span class="term"><span class="bold"><b>Virtual base directory</b></span></span></dt><dd><p> This is the directory that holds all <span class="emphasis"><em>Virtual directories</em></span>. This directory <span class="emphasis"><em>does</em></span> exist on disk and therefore it remains even after reboot. In the previous figure <tt class="filename">/home</tt> is <span class="emphasis"><em>virtual base directory</em></span>.</p></dd><dt><span class="term"><span class="bold"><b>Real directories</b></span></span></dt><dd><p> These are the directories that actually reside on the disk. Even after reboot, these remain intact. In the previous figure all directories created under <tt class="filename">/autohome</tt> are <span class="emphasis"><em>real directories</em></span>.</p></dd><dt><span class="term"><span class="bold"><b>Real base directory</b></span></span></dt><dd><p> This is the directory that holds all real directories. In the above figure <tt class="filename">/autohome</tt> is <span class="emphasis"><em>real base directory</em></span>.</p></dd></dl></div><p>Each <span class="emphasis"><em>virtual directory</em></span> is mapped to <span class="emphasis"><em>real directory</em></span>. Which means whatever written or modified to <span class="emphasis"><em>virtual directory</em></span> is actually sent to <span class="emphasis"><em>real directory</em></span>.</p><p>On reboot of the system <span class="emphasis"><em>real directories</em></span> and their content remain intact. But <span class="emphasis"><em>virtual directories</em></span> are again created on demand as exactly as they were before.</p><p><span class="emphasis"><em>Virtual directories</em></span> are removed if these are not used for a specified time period and created again if necessary. When <span class="emphasis"><em>Virtual directory</em></span> is removed backup program is started on corresponding <span class="emphasis"><em>real directory</em></span> if backup is configured.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Applications should access only <span class="emphasis"><em>virtual directories</em></span>. <span class="emphasis"><em>Real directories</em></span> are hidden from applications except for root. But there is one exception. Backup programs always access only <span class="emphasis"><em>real directories</em></span>.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dirorg"></a>Directory organization under real base directory</h2></div></div><div></div></div><p>Why special organization under <span class="emphasis"><em>real base directory</em></span>? If we just create all <span class="emphasis"><em>real directories</em></span> in one <span class="emphasis"><em>real base directory</em></span> there could be performance penalty when there are large number of <span class="emphasis"><em>real directories</em></span> to be created. File systems like ext2/ext3 are not optimized for this kind of flat directory structure.</p><p>It would be much better if <span class="emphasis"><em>real base directory</em></span> is divided into more subdirectories or even dividing these subdirectories again into more subdirectories. And in the final subdirectories actual home directories are kept!</p><p>There are three types of directory organization.</p><div class="variablelist"><dl><dt><span class="term"><span class="bold"><b>level 0</b></span></span></dt><dd><p>Actually no organization. All home directories are created directly under <span class="emphasis"><em>real base directory</em></span>.</p></dd><dt><span class="term"><span class="bold"><b>level 1</b></span></span></dt><dd><p><span class="emphasis"><em>Real base directory</em></span> is divided into more subdirectories. These subdirectories names are derived from first letter of the final directory to be created. For example, if <tt class="filename">user1</tt> directory is to be created, first a directory named 'u' is created under <span class="emphasis"><em>real base directory</em></span>. Then in that subdirectory actual directory <tt class="filename">user1</tt> created as <tt class="filename">/&lt;real_base_directory&gt;/u/user1</tt>.</p></dd><dt><span class="term"><span class="bold"><b>level 2</b></span></span></dt><dd><p>Same as level 1 organization but after first level of subdirectories, second level subdirectories also created. Name for which is derived form starting two letters of the final directory to be created. For example, for user <tt class="literal">user1</tt> as with the above example, <tt class="filename">/&lt;real_base_directory&gt;/u/us/user1</tt> is created.</p></dd></dl></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vdexp"></a>Virtual directory expiration</h2></div></div><div></div></div><p>When an application tries to access <span class="emphasis"><em>virtual directory</em></span> in <span class="emphasis"><em>virtual base directory</em></span>, <span class="bold"><b>Autodir</b></span> creates <span class="emphasis"><em>virtual directory</em></span> in it if it does not exist already and mounts the <span class="emphasis"><em>real directory</em></span> on it from <span class="emphasis"><em>real base directory</em></span>. But once this happens and  if this <span class="emphasis"><em>virtual directory</em></span> is not accessed from <span class="emphasis"><em>virtual base directory</em></span> for a specified time period by any application, this directory is removed and accordingly that corresponding <span class="emphasis"><em>real directory</em></span> in <span class="emphasis"><em>real base directory</em></span> is marked for backup.</p><p>The time period to wait for expiration can be given through <a href="#autodir_t_opt">command line option</a> to <span class="bold"><b>Autodir</b></span>.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="backup"></a>Backup support</h2></div></div><div></div></div><p> <span class="bold"><b>Autodir</b></span> supports backup program launching when a <span class="emphasis"><em>virtual directory</em></span>  is removed after a period of inactivity. Removal of <span class="emphasis"><em>virtual directory</em></span> is itself is an assurance that no other application can access the content and modify it.</p><p>Like there is wait duration for expiring <span class="emphasis"><em>virtual directory</em></span>, for backup also <span class="bold"><b>Autodir</b></span> waits some more time, after <span class="emphasis"><em>virtual directory</em></span> expiration, for starting backup. This time period can be configured through <a href="#autodir_w_opt">command line option</a> to <span class="bold"><b>Autodir</b></span>.</p><p>By design, backup programs are expected to operate on <span class="emphasis"><em>real directory</em></span> but not on <span class="emphasis"><em>virtual directory</em></span>. If backup program try to access <span class="emphasis"><em>virtual directory</em></span> <span class="bold"><b>Autodir</b></span> assumes some regular application is in need of that directory and backup program is killed even if the <span class="emphasis"><em>virtual directory</em></span> accessing process is backup program itself.</p><p>A separate backup process for each <span class="emphasis"><em>real directory</em></span> is used. The backup program can be given <a href="#back_esc_str">arguments</a> of <span class="emphasis"><em>real directory</em></span> on which to operate.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Backup support is independent of any particular module being used. It is applicable to all modules with <span class="bold"><b>Autodir</b></span>.</p></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Backup programs should never access <span class="emphasis"><em>virtual directory</em></span> or <span class="emphasis"><em>virtual base directory</em></span>.</p></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>Backup feature is not much useful if <span class="emphasis"><em>virtual directories</em></span> are accessed all the time by applications.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="backupreq"></a>Backup program requirements</h2></div></div><div></div></div><p><span class="bold"><b>Autodir</b></span> demands some extra requirements from backup program being used. The reason for this is that when backup is working on <span class="emphasis"><em>real directory</em></span> and with corresponding expired <span class="emphasis"><em>virtual directory</em></span> and that <span class="emphasis"><em>virtual directory</em></span> is requested again by an application while backup is running, backup is killed. First <tt class="literal">SIGTERM</tt> is sent to gracefully stop it. But if it does not shutdown in time -- one second at this moment; <tt class="literal">SIGKILL</tt> will be sent which is guaranteed to stop the backup.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>When and only when backup stopped, application is given access to the <span class="emphasis"><em>virtual directory</em></span> requested.</div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Whatever backup is used, it should be able to recover from this signal gracefully, not causing unrecoverable side effects.</p></div><p>One more important issue is that the environment under which it is run. All backup programs are run as root user. But at the same time all unnecessary root privileges are taken away using POSIX capabilities. In other words these backup programs can read any file or directory that belongs to any user on the system and nothing more than that. Other than that it is like ordinary user level process.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3476718"></a>Module options</h2></div></div><div></div></div><p>There are two kinds of options that can be passed to <span class="bold"><b>Autodir</b></span>. In the first type, <a href="#aoptions" title="Autodir options">options</a> are for <b class="command">autodir</b> itself and are common irrespective of which module is used. There are other type of options which are specific to the module being used. These options called suboptions and are passed to the module being used differently with main option <tt class="literal">-o</tt>. This is similar to <b class="command">mount</b> command suboptions.</p><p>For example, suboptions to the example module <tt class="literal">autohome</tt> can be passed as,</p><pre class="screen">
-o 'realpath=/tmp/autohome,level=2,noskel'
</pre><p>Here <tt class="literal">realpath</tt>, <tt class="literal">level</tt>, <tt class="literal">noskel</tt> are suboptions for <tt class="literal">autohome</tt> module.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3476821"></a>Autodir requirements</h2></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>Linux kernel equal to or later version of 2.4. These kernel versions support mounting one directory on another directory. At this moment <span class="bold"><b>Autodir</b></span> is not ported to other Unices but this may change in future.</p></li><li><p><span class="bold"><b>Autodir</b></span> requires autofs kernel module based on protocol version 4. But it does not require autofs user level package. Autofs kernel module is pretty standard and almost all distributions include it.</p></li></ul></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="autofs_kmod"></a>Loading autofs kernel module</h2></div></div><div></div></div><p><span class="bold"><b>Autodir</b></span> uses autofs kernel module for its operation. Kernel module <tt class="literal">autofs4</tt> must be loaded before even starting <b class="command">autodir</b> for its proper operation.</p><p>This can be done as root user and using <b class="command">modprobe</b>. But first old autofs module, if it is already loaded must be removed as,</p><pre class="screen">
# rmmod autofs
</pre><p>Now insert <tt class="literal">autofs4</tt> module as,</p><pre class="screen">
# modprobe autofs4
</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Latest versions of <span class="bold"><b>Autodir</b></span> switched to <tt class="literal">autofs4</tt> kernel module from older <tt class="literal">autofs</tt> module.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3417555"></a>Importing user and group accounts</h2></div></div><div></div></div><p>If user and group accounts reside in centralized database these must be imported before starting <span class="bold"><b>Autodir</b></span>. How to do this is out of scope of this HOWTO. But there are number of documents which explain how to do this in clear manner.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3417580"></a>Getting it</h2></div></div><div></div></div><p>At this moment <span class="bold"><b>Autodir</b></span> available in tar, rpm formats. More information can be found at <a href="http://www.intraperson.com/autodir/" target="_top">http://www.intraperson.com/autodir/</a>.</p><p>If source is downloaded, follow these simple steps to install it.</p><div class="itemizedlist"><ul type="disc"><li><p>Unpack the source.</p><p><tt class="literal">$ tar zxvf &lt;tar file name&gt;</tt></p></li><li><p>Move to the expanded directory and execute the following.</p><p><tt class="literal">$ ./configure</tt></p><p><tt class="literal">$ make</tt></p><p><tt class="literal"># make install</tt></p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><tt class="literal">configure</tt> script check for required libraries. If these are not present it will stop from proceeding.</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="homedir"></a>Managing Home directories</h2></div></div><div></div></div><p>This section will explain how to configure <span class="bold"><b>Autodir</b></span> so that user home directories are created on demand. For this purpose <tt class="literal">autohome</tt> module is used which deals with specifics of home directory creation.</p><p>To load <tt class="literal">autohome</tt> module with <span class="bold"><b>Autodir</b></span>, use option <tt class="literal">-m</tt>. For example, <tt class="literal">-m /usr/lib/autodir/autohome.so</tt>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>When an application tries to access home directory, that home directory is used to check if there is any user with user name same as the directory being accessed. If user name exist with this criteria then home directory is created. Otherwise no such file or directory is reported back to application.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><tt class="literal">autohome</tt> does not deal with creating user accounts on local systems or in ldap or in any other database. It only deals with creating home directories once these accounts exist and imported to local system from databases like ldap, NIS.</p></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>It is worth mentioning one limitation with <tt class="literal">autohome</tt> module. It expects that user name and home directory are related to each other. For example, for user <tt class="literal">user1</tt> the home directory should be <tt class="filename">/home/user1</tt> or <tt class="filename">/some/directory/name/user1</tt> but not <tt class="filename">/some/directory/name/userhome1</tt>. This can be supported but it will be burden on system resources as each password entry has to be examined from first to last.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If the existing user password database is such that user home directories are distributed under different base directories, for example <tt class="filename">/home/class1/user1</tt>, <tt class="filename">/home/class2/user2332</tt>, then <tt class="literal">autohome</tt> configuration becomes complicated and it is not recommended.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3469861"></a>Base directories for autohome</h3></div></div><div></div></div><p>Next step in setup is to decide where will be <span class="emphasis"><em>virtual base directory</em></span> and <span class="emphasis"><em>real base directory</em></span> for home directory creation.</p><p>What is <span class="emphasis"><em>virtual base directory</em></span> and what is <span class="emphasis"><em>real base directory</em></span> in the context of <tt class="literal">autohome</tt> module?</p><p>It all depends on how user accounts are created. If an user account created for user name user1 with home directory <tt class="filename">/home/user1</tt> then <tt class="filename">/home</tt> <span class="emphasis"><em>will become virtual base directory</em></span>.</p><p>Then what is <span class="emphasis"><em>real base directory</em></span>? It can be any directory. Only thing that must be kept in mind is, there should be enough space as all actual files are stored here instead of in <span class="emphasis"><em>virtual base directory</em></span>.</p><p>In most server configurations <tt class="filename">/home</tt> is a separate partition mounted on it. But if <tt class="filename">/home</tt> is made <span class="emphasis"><em>virtual base directory</em></span> files are not stored in that directory! The solution is, do not mount partition on <tt class="filename">/home</tt> but instead mount it under somewhere else and make it <span class="emphasis"><em>real base directory</em></span>.</p><p><span class="bold"><b>Autodir</b></span> option <tt class="literal">-d</tt> is used to specify <span class="emphasis"><em>virtual base directory</em></span>. For example <tt class="literal">autodir -d /home</tt> assuming <tt class="filename">/home</tt> is <span class="emphasis"><em>virtual base directory</em></span>.</p><p>It is little tricky to specify <span class="emphasis"><em>real base directory</em></span>. <span class="emphasis"><em>real base directory</em></span> is managed by <tt class="literal">autohome</tt> module so this option must be passed to the module through module suboptions. If the <span class="emphasis"><em>real base directory</em></span> is <tt class="filename">/var/autohome</tt> then it is specified with option <tt class="literal">-o</tt> as <tt class="literal">-o realpath=/var/autohome</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3470068"></a>Directory organization</h3></div></div><div></div></div><p>Please refer to <a href="#dirorg" title="Directory organization under real base directory">directory organization under real base directory</a> for detailed explanation of this topic.</p><p><tt class="literal">autohome</tt> does support this kind of organization. The suboption used to specify directory organization desired, is with <tt class="literal">level</tt> suboption. For example, <tt class="literal">-o level=2</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3470116"></a>Misc suboptions for autohome</h3></div></div><div></div></div><p>Suboption <tt class="literal">skel</tt> can be used if skeleton path is not default value <tt class="filename">/etc/skel</tt> like <tt class="literal"> -o skel=/some/other/dir</tt>.</p><p>Suboption <tt class="literal">noskel</tt> can be used with <tt class="literal">-o</tt> to indicate not to copy skeleton files to home directories when created.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3470169"></a>Summing up with an example</h3></div></div><div></div></div><p>First, import user accounts from centralized database like, for example, ldap.</p><p>Next, <tt class="literal">autofs</tt> kernel module must be loaded into the Linux kernel. This can be done as described in <a href="#autofs_kmod" title="Loading autofs kernel module">loading autofs kernel module section</a>.</p><p>If <tt class="filename">/home</tt> is to be used for home directories then <tt class="filename">/home</tt> will become <span class="emphasis"><em>virtual directory</em></span> and specified to <b class="command">autodir</b> with <tt class="literal">-d /home</tt> option.</p><p>Assuming <tt class="literal">autohome</tt> module is located at <tt class="filename">/usr/lib/autodir/autohome.so</tt>, this module can be loaded with <b class="command">autodir</b> as <tt class="literal">-m /usr/lib/autodir/autohome.so</tt>. Note that full path for module is given.</p><p>Where actually real home directories reside is given with <tt class="literal">realpath</tt> suboption. If it is <tt class="filename">/autohome</tt>, it can be given as <tt class="literal">realpath=/autohome</tt>.</p><p>With all these options <b class="command">autodir</b> can be started as,</p><pre class="screen">
# autodir -d /home 						\
		-m /usr/lib/autodir/autohome.so 		\
		-o 'realpath=/autohome'			 	\
</pre><p>Once <span class="bold"><b>Autodir</b></span> is started, <tt class="filename">/home</tt> directory will be blank in the beginning. Whether <span class="bold"><b>Autodir</b></span> working properly or not can be tested by changing directory to one of the home directories as root user or as the owner of the home directory.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3470352"></a>Managing group directories</h2></div></div><div></div></div><p><tt class="literal">autogroup</tt> module is for creating group directories on demand for common group access. It can be used with Samba, for example, to dynamically create shared directories for group of people.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><tt class="literal">autogroup</tt> module check for requested directory with valid groups from system group database.</p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p><tt class="literal">autogroup</tt> can be used to create home directories as well, provided that there exists user private group for each user. This way all group and home directories can be created at one place with one module. But no skeleton files are copied and the <tt class="literal">autogroup</tt> suboption <tt class="literal">nopriv</tt> should not be used.</p></div><p><tt class="literal">autogroup</tt> configuration is same as <tt class="literal">autohome</tt> module but unlike <tt class="literal">autohome</tt>, <span class="emphasis"><em>virtual base directory</em></span> can be placed anywhere and any name can be given to it. It is not dictated by system accounts.</p><p>The module <tt class="literal">autogroup</tt> can be used with <span class="bold"><b>Autodir</b></span> using option <tt class="literal">-m</tt>. For example, <tt class="literal">-m /usr/lib/autodir/autogroup.so</tt>.</p><p>All suboptions explained in <a href="#homedir" title="Managing Home directories">managing home directories</a> are same for <tt class="literal">autogroup</tt> except <tt class="literal">skel</tt>, <tt class="literal">noskel</tt> as these are meaningless for <tt class="literal">autogroup</tt> module. But there are other suboptions specific for <tt class="literal">autogroup</tt>. These are given below.</p><div class="variablelist"><dl><dt><span class="term"><tt class="literal">nopriv</tt></span></dt><dd><p>Some Linux installations use user private groups. If directories for these groups are not to be created, then use this suboption.</p></dd></dl></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="aoptions"></a>Autodir options</h2></div></div><div></div></div><p>In this section some of the options to <span class="bold"><b>Autodir</b></span> are explained. Backup options are explained in <a href="#backupopts" title="Backup options">backup section</a>.</p><div class="variablelist"><dl><dt><span class="term"><tt class="literal">-d</tt></span></dt><dd><p>For specifying <span class="emphasis"><em>virtual base directory</em></span>. If this path does not exist, it will be created. Absolute path is expected for this option.</p></dd><dt><span class="term"><a name="autodir_t_opt"></a><tt class="literal">-t</tt></span></dt><dd><p>Expiration timeout for <span class="emphasis"><em>virtual directories</em></span>. For more details refer to <a href="#vdexp" title="Virtual directory expiration">virtual directory expiration</a>.</p></dd><dt><span class="term"><tt class="literal">-m</tt></span></dt><dd><p>Module to be used with <span class="bold"><b>Autodir</b></span>. Currently <tt class="literal">autohome</tt> and <tt class="literal">autogroup</tt> are available. Full path to the module expected.</p></dd><dt><span class="term"><tt class="literal">-o</tt></span></dt><dd><p>All suboptions that are to be passed to module are given here. This option passing syntax is similar to <b class="command">mount</b> command with its <tt class="literal">-o</tt> option. See specific module sections for more info.</p></dd><dt><span class="term"><tt class="literal">-f</tt></span></dt><dd><p>Stay foreground and log all messages to the console. For debugging purpose and to see how <span class="bold"><b>Autodir</b></span> works.</p></dd><dt><span class="term"><tt class="literal">-l</tt></span></dt><dd><p>This option expects path name to filename to which <span class="bold"><b>Autodir</b></span> will write its process id.</p></dd><dt><span class="term"><tt class="literal">-h</tt></span></dt><dd><p>Help about all options supported by <span class="bold"><b>Autodir</b></span>.</p></dd><dt><span class="term"><tt class="literal">-v</tt></span></dt><dd><p>Version information about <span class="bold"><b>Autodir</b></span>.</p></dd></dl></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="backupopts"></a>Backup options</h2></div></div><div></div></div><p>These options are passed to <span class="bold"><b>Autodir</b></span> to request backup support.</p><div class="variablelist"><dl><dt><span class="term"><tt class="literal">-b</tt></span></dt><dd><p>This is the main option to specify backup program path and arguments to it. The path given should be absolute path otherwise <span class="bold"><b>Autodir</b></span> does not accept it.</p></dd><dt><span class="term"><a name="autodir_w_opt"></a><tt class="literal">-w</tt></span></dt><dd><p>Whenever a <span class="emphasis"><em>virtual directory</em></span> is not used for a period of time, it is assumed inactive and it is unmounted.  After unmounting directory, whether to launch backup immediately or to wait some more time is decided with this option. It takes arguments in seconds. It is the <span class="emphasis"><em>minimum</em></span> time to wait before starting backup after <span class="emphasis"><em>virtual directory</em></span> expiration. It should not exceed more then one day.</p></dd><dt><span class="term"><tt class="literal">-p</tt></span></dt><dd><p>This is the priority to be given to backup process. <span class="emphasis"><em>This is in the range of 1 to 40 inclusive</em></span>. Lower value mean higher priority and vice versa. Default value is 30.</p></dd><dt><span class="term"><tt class="literal">-c</tt></span></dt><dd><p>This restricts maximum number of backup process at any given time. Default is 150.</p></dd></dl></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>Argument for <tt class="literal">-b</tt> is inclusive of absolute backup program path as well as its own arguments. Therefore it is recommended to use single quotes around this argument</div><p>Option <tt class="literal">-b</tt> takes path to executable file as well as arguments to it. But the arguments to it are interpreted for %x character sequences and replaced with predefined strings as follows.</p><div class="variablelist"><dl><dt><span class="term"><tt class="literal">%N</tt></span></dt><dd><p>Replaced with <span class="emphasis"><em>virtual directory</em></span> name.</p></dd><dt><a name="back_esc_str"></a><span class="term"><tt class="literal">%L</tt></span></dt><dd><p>Replaced with absolute path to <span class="emphasis"><em>real directory</em></span>.</p></dd><dt><span class="term"><tt class="literal">%K</tt></span></dt><dd><p>Replaced with host name.</p></dd><dt><span class="term">Others</span></dt><dd><p>Others are fed to <tt class="literal">strftime</tt>. See man page for <tt class="literal">strftime</tt> for more information.</p></dd></dl></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3418240"></a>Examples</h2></div></div><div></div></div><pre class="screen">
# autodir -d /home 						\
		-m /usr/lib/autodir/autohome.so 		\
		-t 1000						\
		-f 						\
		-o 'realpath=/autohome,level=1,skel=/etc/skel' 	\
		-l /var/run/autodir.pid
</pre><pre class="screen">
# autodir -d /home						\
		-m /usr/lib/autodir/autohome.so			\
		-t 300						\
		-b '/bin/tar cf /tmp/%N%F.tar %L'		\
		-w 600						\
		-o 'realpath=/tmp/autohome,level=2,noskel'	\
		-l /var/run/autodir.pid
</pre><pre class="screen">
# autodir -d /var/abase/ 					\
		-m /usr/lib/autodir/autogroup.so		\
		-t 300						\
		-b '/bin/tar cf /tmp/%N%F.tar %L'		\
		-w 86400					\
		-o 'nopriv,nosetgid,realpath=/var/realbase,level=0' 
</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3418279"></a>RPM specific</h2></div></div><div></div></div><p><span class="bold"><b>Autodir</b></span> can be installed from rpms as,</p><pre class="screen">
# rpm -ivh autodir-0.28-4.i386.rpm
</pre><p>When installed from rpms, two startup scripts are provided namely <tt class="filename">/etc/rc.d/init.d/autohome</tt> and <tt class="filename">/etc/rc.d/init.d/autogroup</tt>. One for starting <span class="bold"><b>Autodir</b></span> with <tt class="literal">autohome</tt> module and another for starting with <tt class="literal">autogroup</tt> module.</p><p>Script configuration files <tt class="filename">/etc/sysconfig/autohome</tt>, <tt class="filename">/etc/sysconfig/autogroup</tt> can be used to specify what options can be passed to <span class="bold"><b>Autodir</b></span>.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="moreinfo"></a>Further Information</h2></div></div><div></div></div><p><span class="bold"><b>Mailing list for autodir </b></span><a href="http://lists.sourceforge.net/mailman/listinfo/intraperson-autodir" target="_top">http://lists.sourceforge.net/mailman/listinfo/intraperson-autodir</a>.</p><p>Official website is at <a href="http://www.intraperson.com/autodir/" target="_top">http://www.intraperson.com/autodir/</a>.</p><p>Autofs mailing list <a href="http://linux.kernel.org/mailman/listinfo/autofs" target="_top">http://linux.kernel.org/mailman/listinfo/autofs</a>.</p><p>Automount HOWTO can be found at <a href="http://www.tldp.org" target="_top">http://www.tldp.org</a></p><p>Autofs Hacking <a href="http://www.goop.org/~jeremy/autofs/" target="_top">http://www.goop.org/~jeremy/autofs</a>.</p></div></div></body></html>