diff options
| author | Lennart Poettering <lennart@poettering.net> | 2004-03-24 22:21:34 +0000 |
|---|---|---|
| committer | Lennart Poettering <lennart@poettering.net> | 2004-03-24 22:21:34 +0000 |
| commit | 217d61819a64e38384e632ca2f8b4daa0447d986 (patch) | |
| tree | 31e744d8c90443afd5df19cec1d402c369975bc0 | |
| parent | c174f20109543c0a0bc999369784a8ee52f7141c (diff) | |
documentation update
git-svn-id: file:///home/lennart/svn/public/mod_mime_xattr/trunk@4 f01872de-66d6-0310-9185-fc3b30f50adc
| -rw-r--r-- | NOTICE | 2 | ||||
| -rw-r--r-- | doc/README.html.in | 291 | ||||
| -rw-r--r-- | doc/style.css | 32 |
3 files changed, 130 insertions, 195 deletions
@@ -1 +1 @@ -This software was developed by Lennart Poettering, 2004 +This software has been developed by Lennart Poettering diff --git a/doc/README.html.in b/doc/README.html.in index 7e97387..d35de67 100644 --- a/doc/README.html.in +++ b/doc/README.html.in @@ -3,14 +3,14 @@ <html xmlns="http://www.w3.org/1999/xhtml"> <head> -<title>ifplugd @PACKAGE_VERSION@</title> +<title>mod_mime_xattr @PACKAGE_VERSION@</title> <link rel="stylesheet" type="text/css" href="style.css" /> </head> <body> -<h1><a name="top">ifplugd @PACKAGE_VERSION@</a></h1> +<h1><a name="top">mod_mime_xattr @PACKAGE_VERSION@</a></h1> -<p><i>Copyright 2002-2004 Lennart Poettering <@PACKAGE_BUGREPORT@></i></p> +<p><i>Copyright 2004 Lennart Poettering <@PACKAGE_BUGREPORT@></i></p> <ul class="toc"> <li><a href="#license">License</a></li> @@ -26,7 +26,7 @@ <h2><a name="license">License</a></h2> -<p>Copyright 2004 Lennart Poettering +<p>Copyright 2004 Lennart Poettering</p> <p>Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may @@ -42,241 +42,144 @@ permissions and limitations under the License.</p> <h2><a name="news">News</a></h2> -<div class="news-date">Mon July 7 2003: </div> <p class="news-text"><a -href="@PACKAGE_URL@ifplugd-0.14.tar.gz">Version -0.14</a> released, changes include: autoconf usage, new dependency <a -href="http://0pointer.de/lennart/projects/libdaemon/"><tt>libdaemon</tt></a>, wireless LAN support, support for -suspending/resuming, many fixes</p> +<div class="news-date">Wed Mar 24 2004: </div> <p class="news-text"><a +href="@PACKAGE_URL@mod_mime_xattr.tar.gz">Version +0.1</a> released</p> <h2><a name="overview">Overview</a></h2> -<p><tt>ifplugd</tt> is a Linux daemon which will automatically -configure your ethernet device when a cable is plugged in and -automatically unconfigure it if the cable is pulled. This is useful on -laptops with onboard network adapters, since it will only configure -the interface when a cable is really connected.</p> +<p><tt>mod_mime_xattr</tt> is a module for the <a +href="http://httpd.apache.org/">Apache HTTPD</a> 1.3 which may be used to +set a range of MIME properties of files served from a document tree with +extended attributes (EAs) as supported by the underlying file +system. The current version of <tt>mod_mime_xattr</tt> has support for +Linux style EAs which are supported by Linux 2.4 with the <a +href="http://acl.bestbits.at/">ACL/EA patches</a> applied and vanilla +Linux 2.6. The following attributes may be used:</p> -<p><tt>ifplugd</tt> ifplugd interfaces with your distribution's native network - configuration utilities.</p> +<ul> + <li><tt>user.mime-type</tt>: set the mime type of a file + explicitly. This attribute is compatible with the <a +href="http://www.freedesktop.org/Standards/shared-mime-info-spec">shared +MIME database specification</a> as published by <a href="http://www.freedesktop.org/">freedesktop.org</a></li> + <li><tt>user.charset</tt>: set the charset used in a file</li> + <li><tt>user.encoding</tt>: set the mime encoding of a file (e.g. <tt>gzip</tt>)</li> + <li><tt>user.apache-handler</tt>: set the apache handler of a file explicitly</li> +</ul> + + +<h2><a name="status">Status</a></h2> + +<p>Version @PACKAGE_VERSION@ is stable and more or less feature complete.</p> + +<h2><a name="documentation">Documentation</a></h2> + +<h3>Configuration</h3> -<p>Some features:</p> +<p>Enable the module by adding a new <tt>LoadModule</tt> to the Apache configuration files:</p> + +<pre> +LoadModule config_log_module /usr/lib/apache/1.3/mod_log_config.so +LoadModule mime_module /usr/lib/apache/1.3/mod_mime.so +<b>LoadModule mime_xattr_module /usr/lib/apache/1.3/mod_mime_xattr.so</b> +LoadModule negotiation_module /usr/lib/apache/1.3/mod_negotiation.so +</pre> + +<p>If you add the new line before <tt>mod_mime</tt>, the latter will +overwrite the MIME type settings <tt>mod_mime_xattr</tt> +detected. Thus the extension of a file is more important than the EA <tt>user.mime-type</tt>. If specified in the opposite +order (which is recommended), the values set in the EAs take +precedence.</p> + +<p>When enabled in the Apache configuration files, +<tt>mod_mime_xattr</tt> introduces two new directory dependent +configuration directives:</p> <ul> - <li>Uses your distribution's native <tt>ifup</tt>/<tt>ifdown</tt> programs.</li> + <li><tt>XAttrMimeType [On/Off]</tt>; Enable or disable the use of the <tt>user.mime-type</tt>, <tt>user.charset</tt> and <tt>user.encoding</tt> EAs.</li> + <li><tt>XAttrHandler [On/Off]</tt>; Enable or disable the use of the <tt>user.apache-handler</tt> EA</li> +</ul> - <li>May beep when the cable is unplugged, plugged, the interface - configuration succeeded or failed.</li> +<p>A simple usage example:</p> - <li>Supports the Linux <tt>SIOCETHTOOL</tt> (newer, aka <tt>ethtool</tt> API), <tt>SIOCGMIIREG</tt> - (older, aka <tt>mii-diag</tt>/<tt>mii-tool</tt> API) and SIOCDEVPRIVATE (oldest, aka - <tt>mii-tool</tt> API) <tt>ioctl()</tt>s for getting link status.</li> +<pre>... +<Directory /var/www> + XAttrMimeType On + XAttrHandler On +</Directory> +... +</pre> - <li>Syslog support</li> +<h2>Usage</h2> - <li>Small program - the binary is just 19 KB (plus 11 KB for <tt>libdaemon</tt>).</li> - - <li>Multiple ethernet interface support</li> +<p>You may get/set an extended attribute for a file with the Linux command line utilities <tt>getfattr</tt>/<tt>setfattr</tt>:</p> - <li>Can be configured to ignore short "unplugged" periods - (-d option) or short "plugged" periods(<tt>-u</tt> - option)</li> +<pre>setfattr -n "user.mime-type" -v "text/html" foo.file</pre> - <li>Support for wireless networking. Whenever an association to an -AP is detected the network is configured. Have a look on <a -href="http://0pointer.de/lennart/projects/waproamd/"><tt>waproamd</tt></a> -if you need a facility to configure WEP keys before AP associations succeed.</li> +<p>The file <tt>foo.file</tt> will be served as HTML now. For more information consult the concerning man pages.</p> - <li>Compatibility mode for network devices which do not support cable detection (<tt>-F</tt> option)</li> -</ul> - -<h2><a name="status">Status</a></h2> +<p>If used with symbolic links, <tt>mod_mime_xattr</tt> will first +check if an EA is set for the symlink itself, and second for the file +the link points to. The <tt>user.charset</tt> EA is only used when the +<tt>user.mime-type</tt> EA is set as well.</p> -<p>Version @PACKAGE_VERSION@ is stable and has all the sensible features its users could think of.</p> - -<h2><a name="documentation">Documentation</a></h2> +<h2>CGI and PHP scripts</h2> -<p>Have a look on the man pages <a href="@PACKAGE_URL@ifplugd.8.xml"><tt>ifplugd(8)</tt></a>, <a href="@PACKAGE_URL@ifplugstatus.8.xml"><tt>ifplugstatus(8)</tt></a>, <a href="@PACKAGE_URL@ifplugd.conf.5.xml"><tt>ifplugd.conf(5)</tt></a>. (An XSLT capable browser is required)</p> +<p>You may use the <tt>user.apache-handler</tt> EA to mark a file as CGI script:</p> -<h3>Configuration</h3> +<pre>setfattr -n "user.apache-handler" -v "cgi-script" foo.html</pre> -<p>Edit <tt>/etc/ifplugd/ifplugd.conf</tt> for configuration -changes. This file is a bourne shell script sourced by the init script -and used to start <tt>ifplugd</tt> with appropriate arguments. You may specify more than -one ethernet interface in <tt>INTERFACES</tt>. For each interface a -seperate instance of <tt>ifplugd</tt> is spawned. The arguments specified in -<tt>ARGS</tt> are append to <tt>ifplugd</tt>'s command line. Have a look on -<tt>ifplugd -h</tt> or <tt>man ifplugd</tt> for further information -about the available options.</p> - -<p>The network interface which is controlled by <tt>ifplugd</tt> -should not be configured automatically by your distribution's network -subsystem, since <tt>ifplugd</tt> will do this for you if needed.</p> - -<p>On Debian systems, any interfaces named in ifplugd's -<tt>INTERFACES</tt> environment variable should not also be listed in -an "auto" stanza in <tt>/etc/network/interfaces</tt>.</p> - -<h3>Troubleshooting</h3> - -<p>When you are using the hotplug subsystem (Debian package -<tt>hotplug</tt>) you may notice that the network device is configured -even when it is not listed on an <tt>auto</tt> line in -<tt>/etc/network/interface</tt>. This may be due to <tt>hotplug</tt> -being configured to <tt>ifup</tt> the network interface when it -becomes available. This was the default behavior in the Debian -<tt>hotplug</tt> package prior to release <tt>0.0.20030117-1</tt>, for -example. To prevent this you should either upgrade your -<tt>hotplug</tt> package or comment out the <tt>ifup</tt> call in -<tt>/etc/hotplug/net.agent</tt>.</p> - -<p>When using <tt>ifplugd</tt> together with APM (and probably ACPI) -suspends, strange things may happen: some network devices fail to -detect the network cable for a short period of time before and after -the suspend. When using the <tt>-f</tt> switch, this will be treated -as "no link beat", thus the network is shutdown after a -timeout. During this timeout the machine changes to suspended -state. When it is resumed again, the timeout period will have expired -and so the network is deconfigured, however, as the next cable -detection succeeds, the network is configured again immediately. To -fix this problem, <tt>ifplugd</tt> should be disabled before the APM -suspend and enabled back after the suspend. This may be done by using -<tt>apmd</tt> and adding a script to -<tt>/etc/apm/{suspend,resume}.d</tt> which simply calls -<tt>/etc/init.d/ifplugd suspend</tt>, resp. <tt>/etc/init.d/ifplugd -resume</tt>. It might even be a good idea to shut down the network -completely during suspend, this may be achieved by calling -<tt>/etc/init.d/ifplugd stop</tt> and <tt>/etc/init.d/ifplugd -start</tt> in the appropriate places. I strongly urge the packagers of -this software for the Linux distributions to add such scripts to their -packages.</p> - -<h3>FAQ</h3> - -<ol> - <li><p><b>Q:</b> I want to use <tt>ifplugd</tt> with my PCMCIA device, but <tt>ifplugd</tt> quits - when it doesn't find <tt>eth0</tt>, when I have not inserted the - card. What can I do?</p> - - <p><b>A:</b> Use the <tt>-f</tt> switch. This is not very clean however, - since modprobe is called on each cable detection query of <tt>ifplugd</tt> to - load a module for the network device. This is suboptimal. You should - probably run <tt>ifplugd</tt> only when the card is really inserted.</p> - </li> - - <li><p><b>Q:</b> I am using the <tt>-f</tt> switch, but the kernel logs are getting filled - with messages like "<tt>modprobe: modprobe: Can't locate module - eth0</tt>". What can I do?</p> - - <p><b>A:</b> Make sure you have a line like <tt>alias eth0 off</tt> in your <tt>/etc/modules.conf</tt></p> - </li> - - <li><p><b>Q:</b> When the cable is unplugged and the interface shut down it is - still available with <tt>ifconfig</tt> and markes as UP. Why this?</p> - - <p><b>A:</b> <tt>ifplugd</tt> cannot detect the link beat with a shut down interface on - certain (most as of kernel 2.4.19) network drivers. Thus <tt>ifplugd</tt> - enables the interface before querying the link status. This may - be switched off with -a flag. You might want to use it if you - have a sane network driver (e.g. <tt>eepro100</tt>). The subdirectory - <tt>patches/</tt> in the <tt>ifplugd</tt> distribution includes a patch for the - 8139too 0.9.26 driver, which makes the driver compatible with - -a. Don't ask me how to apply this patch. If you don't know, you - won't need it.</p></li> - - <li><p><b>Q:</b> Does it work with anything else than plain ethernet or wireless LAN?</p> - - <p><b>A:</b> Certainly not, since the <tt>MII</tt> and -<tt>ETHTOOL</tt> <tt>ioctl()</tt>s and the wireless extension don't -exist on - other network device types.</p></li> - - <li><p><b>Q:</b> I have a Realtek 8139 based network card. Everytime <tt>ifplugd</tt> - starts on bootup my machine freezes. What can I do?</p> - - <p><b>A:</b> This is a bug in the <tt>8139too</tt> driver 0.9.25 (at least) shipped - with Linux 2.4.19, please upgrade to <tt>8139too</tt> 0.9.26 (Linux 2.4.20 - or seperately at <a href="http://www.sourceforge.net/projects/gkernel/">http://www.sourceforge.net/projects/gkernel/</a>).</p></li> - - - <li><p><b>Q:</b> There are already <tt>laptop-net</tt>'s <tt>ifd</tt> and <tt>miid</tt>, why did you write - your own daemon?</p> +<p>This will force the execution of <tt>foo.html</tt> as CGI program, +regardless of the name of the file which identifies it as an HTML +file.</p> - <p><b>A:</b> <tt>laptop-net</tt> was too integrated with its profile -system and didn't work on my hardware when I had a look on it. It -seemed easier to me to write a simple but feature complete replacement -than using laptop-net without most of the special features disabled. I -didn't know about <tt>miid</tt> when I wrote - <tt>ifplugd</tt>, but in any case <tt>ifplugd</tt> is much better -than <tt>miid</tt>. For a - comparison of <tt>miid</tt> and <tt>ifplugd</tt>, have a look on +<p>If you have <a href="http://www.php.net/">PHP</a> configured in +your Apache web server you may mark a file as PHP script regardless of +its name:</p> - <a href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=162763&repeatmerged=yes">http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=162763&repeatmerged=yes</a></p></li> -</ol> +<pre>setfattr -n "user.mime-type" -v "application/x-httpd-php" bar.html</pre> +<p><b>Think twice</b> before enabling <tt>mod_mime_xattr</tt> for document +trees you do not trust because a rogue user may mark his files as +executable CGI or PHP scripts with the technique described above.</p> <h2><a name="requirements">Requirements</a></h2> -<p>A newer Linux Kernel (I think 2.2 is good enough, alltough I tested it -only with 2.4) with a compatible device driver and -ethernet card. Most modern cards and drivers are compatible, like mine -which works with the <tt>8139too</tt> driver.</p> +<p>A current release of Apache 1.3 with <tt>apxs</tt>, the development +headers and libraries installed. You need to install <tt>libattr</tt> +and its development package.</p> -<p><tt>ifplugd</tt> was developed and tested on Debian GNU/Linux -"testing" from July 2003, it should work on most other Linux -distributions (and maybe Unix versions) since it uses GNU autoconf and -GNU libtool for source code configuration and shared library -management.</p> +<p>A port to other EA APIs has not been done yet. It should be fairly +easy to do, however. Feel free to send me patches!</p> -<p>The machine used was a Medion 9580-F laptop with a Realtek 8139 -network card and a PRISM1 PCMCIA wireless LAN card.</p> +<p><tt>mod_mime_xattr</tt> was developed and tested on Debian GNU/Linux +"testing" from March 2004, it should work on most other Linux +distributions since it uses GNU autoconf source code configuration.</p> -<p><tt>ifplugd</tt> needs <a -href="http://0pointer.de/lennart/projects/libdaemon/"><tt>libdaemon</tt></a>.</p> - <h2><a name="installation">Installation</a></h2> <p>As this package is made with the GNU autotools you should run <tt>./configure</tt> inside the distribution directory for configuring the source tree. After that you should run <tt>make</tt> for compilation and <tt>make install</tt> (as root) for installation of -<tt>ifplugd</tt>.</p> - -<p>The installation scripts create an init script in -<tt>${sysconfdir}/init.d/ifplugd</tt>, however no <tt>/etc/rc?.d/</tt> links are created -for it.</p> - -<p>Extensive installation instructions for <tt>ifplugd</tt> are available at <a href="http://www.acmc.uq.edu.au/~gbe/linux/installation_of_ifplugd.html">Geoff Ericksson's web site</a>.</p> +<tt>mod_mime_xattr</tt>.</p> <h2><a name="acks">Acknowledgements</a></h2> -<p>For the developers of <tt>mii-diag</tt>, <tt>ethtool</tt> and <tt>laptop-net</tt>, since I looked -on their source codes for learning how to use the link beat ioctls.</p> - -<p>Oliver Kurth for packaging <tt>ifplugd</tt> for Debian and <tt>ifplugd</tt>'s -manpage</p> - -<p>Thomas Hood, Asgeir Nilsen, Sean Reifschneider, R. Steve McKown, David Mitchell, Norbert Preining, Herbert Graeber for patches</p> - -<p>Frederic Lepied for integrating <tt>ifplugd</tt> into Mandrake Linux</p> +<p>None so far</p> <h2><a name="download">Download</a></h2> <p>The newest release is always available from <a href="@PACKAGE_URL@">@PACKAGE_URL@</a></p> -<p>The current release is <a href="@PACKAGE_URL@ifplugd-@PACKAGE_VERSION@.tar.gz">@PACKAGE_VERSION@</a></p> - -<p>Get <tt>ifplugd</tt>'s development sources from the <a href="http://subversion.tigris.org/">Subversion</a> <a href="https://seth.intheinter.net:8081/svn/ifplugd/">repository</a>.</p> - -<p>You may find an up to date Debian package of <tt>ifplugd</tt> on the <a href="http://packages.debian.org/ifplugd">Debian package repository</a>.</p> - -<p>Packages for Mandrake Linux may be found in the Cooker distribution; Gentoo packages are available as well; <a href="http://packman.links2linux.de/">SuSE packages</a> are available courtesy of Herbert Graeber.</p> +<p>The current release is <a href="@PACKAGE_URL@mod_mime_xattr-@PACKAGE_VERSION@.tar.gz">@PACKAGE_VERSION@</a></p> -<p>If you want to be notified whenever I release a new version of this software use the subscription feature of <a href="http://freshmeat.net/projects/ifplugd/">Freshmeat</a>.</p> +<p>Get <tt>mod_mime_xattr</tt>'s development sources from the <a href="http://subversion.tigris.org/">Subversion</a> <a href="https://seth.intheinter.net:8081/svn/mod_mime_xattr/">repository</a>.</p> -<p><b>New!</b> There is a joint <tt>ifplugd</tt> and <tt>waproamd</tt> <a href="https://seth.intheinter.net/mailman/listinfo/ifplugd-discuss">mailing list</a> available.</p> +<p>If you want to be notified whenever I release a new version of this software use the subscription feature of <a href="http://freshmeat.net/projects/mod_mime_xattr/">Freshmeat</a>.</p> <hr/> -<address class="grey">Lennart Poettering <@PACKAGE_BUGREPORT@>, February 2004</address> +<address class="grey">Lennart Poettering <@PACKAGE_BUGREPORT@>, March 2004</address> <div class="grey"><i>$Id$</i></div> </body> diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 0000000..3499640 --- /dev/null +++ b/doc/style.css @@ -0,0 +1,32 @@ +/* $Id$ */ + +/*** + + Copyright 2004 Lennart Poettering + + Licensed under the Apache License, Version 2.0 (the "License"); you + may not use this file except in compliance with the License. You + may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied. See the License for the specific language governing + permissions and limitations under the License. + +***/ + +body { color: black; background-color: white; margin: 0.5cm; } +a:link, a:visited { color: #900000; } +p { margin-left: 0.5cm; margin-right: 0.5cm; } +div.news-date { margin-left: 0.5cm; font-size: 80%; color: #4f0000; } +p.news-text { margin-left: 1cm; } +h1 { color: #00009F; } +h2 { color: #00009F; } +h3 { color: #00004F; margin-left: 0.5cm; } +ul { margin-left: .5cm; } +ol { margin-left: .5cm; } +pre { margin-left: .5cm; background-color: #f0f0f0; padding: 0.4cm;} +.grey { color: #afafaf; } |