diff options
27 files changed, 265 insertions, 257 deletions
diff --git a/docs/build/doctrees/api.doctree b/docs/build/doctrees/api.doctree Binary files differindex 2516311..4821784 100644 --- a/docs/build/doctrees/api.doctree +++ b/docs/build/doctrees/api.doctree diff --git a/docs/build/doctrees/architecture.doctree b/docs/build/doctrees/architecture.doctree Binary files differindex ca0afd1..09810c7 100644 --- a/docs/build/doctrees/architecture.doctree +++ b/docs/build/doctrees/architecture.doctree diff --git a/docs/build/doctrees/environment.pickle b/docs/build/doctrees/environment.pickle Binary files differindex 23e328c..8d02379 100644 --- a/docs/build/doctrees/environment.pickle +++ b/docs/build/doctrees/environment.pickle diff --git a/docs/build/doctrees/man.doctree b/docs/build/doctrees/man.doctree Binary files differindex a6ca5c2..da00d7c 100644 --- a/docs/build/doctrees/man.doctree +++ b/docs/build/doctrees/man.doctree diff --git a/docs/build/html/_images/autodep_arch1.png b/docs/build/html/_images/autodep_arch1.png Binary files differnew file mode 100644 index 0000000..d0bfee9 --- /dev/null +++ b/docs/build/html/_images/autodep_arch1.png diff --git a/docs/build/html/_modules/index.html b/docs/build/html/_modules/index.html index cc23e30..8141709 100644 --- a/docs/build/html/_modules/index.html +++ b/docs/build/html/_modules/index.html @@ -86,7 +86,7 @@ </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/_modules/logfs/fstracer.html b/docs/build/html/_modules/logfs/fstracer.html index 0abbd94..83a2ef6 100644 --- a/docs/build/html/_modules/logfs/fstracer.html +++ b/docs/build/html/_modules/logfs/fstracer.html @@ -327,7 +327,7 @@ </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/_modules/package_utils/portage_log_parser.html b/docs/build/html/_modules/package_utils/portage_log_parser.html index a468842..2c9e94b 100644 --- a/docs/build/html/_modules/package_utils/portage_log_parser.html +++ b/docs/build/html/_modules/package_utils/portage_log_parser.html @@ -170,7 +170,7 @@ </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/_modules/package_utils/portage_misc_functions.html b/docs/build/html/_modules/package_utils/portage_misc_functions.html index 034ad24..13fddfe 100644 --- a/docs/build/html/_modules/package_utils/portage_misc_functions.html +++ b/docs/build/html/_modules/package_utils/portage_misc_functions.html @@ -188,7 +188,7 @@ </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/_modules/package_utils/portage_utils.html b/docs/build/html/_modules/package_utils/portage_utils.html index f7eba53..b0e63db 100644 --- a/docs/build/html/_modules/package_utils/portage_utils.html +++ b/docs/build/html/_modules/package_utils/portage_utils.html @@ -158,7 +158,7 @@ </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/_sources/api.txt b/docs/build/html/_sources/api.txt index 1397732..502db1e 100644 --- a/docs/build/html/_sources/api.txt +++ b/docs/build/html/_sources/api.txt @@ -11,7 +11,7 @@ logfs.fstracer package_utils ================================ -This package contains modules which works with the Portage system +This package contains modules which work with the Portage system .. automodule:: package_utils.portage_log_parser :members: diff --git a/docs/build/html/_sources/architecture.txt b/docs/build/html/_sources/architecture.txt index 59b55f8..2caec16 100644 --- a/docs/build/html/_sources/architecture.txt +++ b/docs/build/html/_sources/architecture.txt @@ -13,66 +13,71 @@ Format of network messages -------------------------- -1. Format of messages to file access registrar:: +1. Format of messages to the File Access Registrar:: <time of event: sec since 1970> <event type: open, read, write> <name of file> <building stage: stagename or unknown> <result:OK,ERR/errno,ASKING,DENIED> -2. Format of answer for ASKING packet from registrar:: +2. Format of answer for ASKING packet from File Access Registrar:: <ALLOW | DENY> *Notes:* * All sockets are SOCK_SEQPACKET -* All fields are delimited with character with code 0 +* All fields are delimited with character \0 -How Hooklib approach works? -=========================== +How does the Hooklib approach work? +=================================== -The main idea of Hooklib approach is to load a dynamic library-hooker -**before** any other library(including the C runtime, libc.so). -So, the functions, such as open, read and write, executed from this library -instead of libc.so. +The main idea behind the Hooklib approach is to load a dynamic library-hook +**before** any other library(including the C runtime). +So, the calls to functions such as open, read and write, are intercepted +using this library, instead of executing the ones in *libc*. -Hooklib module modifies Linux's dynamic linker behavior changing LD_PRELOAD -environment variable(see +Hooklib module modifies Linux's dynamic linker behavior, changing LD_PRELOAD +environment variable (see `man 8 ld-linux <http://linux.die.net/man/8/ld-linux>`_ for details). -Module protects LD_PRELOAD variable from further changes by program. +This module also protects LD_PRELOAD variable from further changes by executing +program. -When hooklib module loads, it connects to file access registrar via Unix domain -sockets. If program forks or creates a new thread, another copy of library -loads. +When Hooklib is loaded, it connects to the File Access Registrar via Unix domain +sockets. If a program forks or creates a new thread, another copy of the library +loads to register events from this new process/thread. -When program do open(...), read(...), write(...), library send an information -about a call to registrar. Registar can block or allow an event. If registrer -allows an event then the original function is called. Else error -"file not found" is returned. +When a program calls open(...), read(...), write(...), Hooklib sends a message +about a call to the File Access Registrar. The Registar can then block +or allow this event. If Registrar responds to the previous query with +an ALLOW packet, then the original function is called. Otherwise, the function +is not called and a "File not Found" error is returned instead. -How Fusefs approach works? -========================== +How does the Fusefs approach work? +================================== -The main idea if Fusefs approach is to create a loggable filesystem in userspace -and chroot a program into it. +The main idea of the Fusefs approach is to create a loggable filesystem in userspace +and jail a program into it, using a chroot. -Before program is launched registrar prepare mounts. It usually do: +Before the program is launched, The File Access Registrar prepare the mounts. +It would usually take the following steps: 1. mount -o bind / /mnt/rootfs/ -2. mount /dev/, /dev/pts, /dev/shm, /proc/, /sys/ same way +2. mount /dev, /dev/pts, /dev/shm, /proc/, /sys/ binding them to /mnt/rootfs 3. mount /lib64/, /lib32/, /var/tmp/portage/ same way to increase performance at cost of accuracy -4. launch fuse over /mnt/rootfs/ +4. launch FUSE over /mnt/rootfs/ -Fuse module blocks all external access to /mnt/rootfs while program runs. - -Fuse module also asks the registrar about event allowness. +Fuse module blocks all external access to /mnt/rootfs while the program runs. +The FUSE module will also ask the File Access Registrar to check whether access to +files inside the chroot are allowed or denied. As with the Hooklib approach, if +access to a file is denied, a "File not Found" error is returned. *Notes:* -* Checking for allowness takes a much time +* Checking for permission to access a file with the File Access Registrar, takes a +lot of time under this approach. Futher analysis of file access events ===================================== @@ -90,6 +95,6 @@ unuseful packages. Rules of heuristics ------------------- -1. *Package is not useful if all files are .desktop or .xml or .m4*. +1. *Package is not useful if all files are .desktop, .xml or .m4*. Aclocal util tries to read all .m4 files in /usr/share/aclocal directory. - Files ending on .desktop and .xml often readed on postrm phase.
\ No newline at end of file + Files ending on .desktop and .xml are often read in the postrm phase.
\ No newline at end of file diff --git a/docs/build/html/_sources/man.txt b/docs/build/html/_sources/man.txt index b49fb54..bf5ad86 100644 --- a/docs/build/html/_sources/man.txt +++ b/docs/build/html/_sources/man.txt @@ -10,10 +10,10 @@ SYNOPSIS DESCRIPTION =========== -Auto dependency builder is a tool for analysis files accessed during -building a package. It also can be used for runtime dependencies analysis. +Auto dependency (autodep) builder is a tool for the analysis of accessed files during +the build of a package. It also can be used for runtime dependencies analysis. -The tool can block an access to files of defined packages. +The tool can trace, log and block access to files of given packages. OPTIONS ======= @@ -22,78 +22,78 @@ OPTIONS .. cmdoption:: --help, -h - show this help message and exit + Show this help message and exit. .. cmdoption:: -b, --block - strict mode: deny all access to non-dependency packages + strict mode: Deny all access to files from non-dependency packages. .. cmdoption:: --blockpkgs=PACKAGES - block an access to files from this packages + Block access to files from this packages. .. cmdoption:: -f, --files - show accessed files and not founded files + Show all files, accessed and missing (not found). .. cmdoption:: -v, --verbose - show non-important packages, show unknown package and unknown stage + Show non-important packages, unknown packages and unknown building stages. .. cmdoption:: --nocolor, -C - don't output color + Don't colorize output .. cmdoption:: --hooklib - use ld_preload logging approach(default) + Use LD_PRELOAD logging approach (default). .. cmdoption:: --fusefs - use fuse logging approach(slow, but reliable) + Use FUSE logging approach (slow, but reliable). HOOKLIB VS FUSEFS ================= +------------------------------------------------+-------------+---------------+ -| | Hooklib | Fusefs | +| | Hooklib | FuseFS | +================================================+=============+===============+ | Who can use this approach? | **Any user**| Only root | +------------------------------------------------+-------------+---------------+ -| Is approach allows blocking an access to files?| **YES** | **YES** | +| Does approach allows to block access to files? | **YES** | **YES** | +------------------------------------------------+-------------+---------------+ -| Is overhead in performance big? | **NO** | YES [#f1]_ | +| Is the overhead in performance noticeable? | **NO** | YES [#f1]_ | +------------------------------------------------+-------------+---------------+ | What events are logged? | Most [#f2]_| **ALL** | +------------------------------------------------+-------------+---------------+ -| When is it recomended to use an approach? | For analysis| For analysis | +| When is it recomended to use an approach? | Analysis | Analysis | | | of | of *runtime* | | | *buildtime* | dependencies | | | dependencies| | +------------------------------------------------+-------------+---------------+ -| Is any pre-requirements for using an approach? | **NO** | FUSE must be | -| | | enabled in | +| Are there any pre-requirements | **NO** | FUSE must be | +| for using an approach? | | enabled in | | | | kernel | +------------------------------------------------+-------------+---------------+ .. rubric:: Notes -.. [#f1] Fuse file system is slower than normal one. Program reads many files +.. [#f1] FUSE filesystems are slower than a normal one. A Program accesses many files while launching, so this will take more time than usual. -.. [#f2] Loading of dynamic libraries and direct syscalls will not be logged. +.. [#f2] Loading of Dynamic libraries and direct syscalls will not be logged. Examples ======== -Get the potential dependencies of a xchat package: ------------------------------------------------------ -autodep emerge xchat +Get the potential dependencies for net-irc/xchat: +------------------------------------------------- +autodep emerge net-irc/xchat -Get the potential dependencies of a xchat package, blocking x11-misc/util-macros package: --------------------------------------------------------------------------------------------- -autodep emerge --block x11-misc/util-macros emerge xchat +Get the potential dependencies for net-irc/xchat, blocking files from x11-misc/util-macros package: +--------------------------------------------------------------------------------------------------- +autodep emerge --block x11-misc/util-macros emerge net-irc/xchat -Get the potential dependencies of a xchat package, and show files accessed: ------------------------------------------------------------------------------- -autodep --files emerge xchat +Get the potential dependencies for net-irc/xchat package, and show accessed files: +---------------------------------------------------------------------------------- +autodep --files emerge net-irc/xchat -Get the runtime dependencies of a xchat and show files accessed: -------------------------------------------------------------------- +Get the runtime dependencies of a xchat and show accessed files: +---------------------------------------------------------------- autodep --fusefs --files xchat diff --git a/docs/build/html/api.html b/docs/build/html/api.html index bec16d7..e485aa5 100644 --- a/docs/build/html/api.html +++ b/docs/build/html/api.html @@ -56,7 +56,7 @@ handling dependency logic.</p> <p>It can be used to launch a program and get all file events</p> <dl class="function"> <dt id="logfs.fstracer.getfsevents"> -<tt class="descclassname">logfs.fstracer.</tt><tt class="descname">getfsevents</tt><big>(</big><em>prog_name</em>, <em>arguments</em>, <em>approach='hooklib'</em>, <em>filterproc=<function defaultfilter at 0x1b2bc80></em><big>)</big><a class="reference internal" href="_modules/logfs/fstracer.html#getfsevents"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#logfs.fstracer.getfsevents" title="Permalink to this definition">¶</a></dt> +<tt class="descclassname">logfs.fstracer.</tt><tt class="descname">getfsevents</tt><big>(</big><em>prog_name</em>, <em>arguments</em>, <em>approach='hooklib'</em>, <em>filterproc=<function defaultfilter at 0x1dcb938></em><big>)</big><a class="reference internal" href="_modules/logfs/fstracer.html#getfsevents"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#logfs.fstracer.getfsevents" title="Permalink to this definition">¶</a></dt> <dd><p>Launches a program and gets file access events</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> @@ -90,7 +90,7 @@ Stage can be <em>‘unknown’</em></p> </div> <div class="section" id="package-utils"> <h2>package_utils<a class="headerlink" href="#package-utils" title="Permalink to this headline">¶</a></h2> -<p>This package contains modules which works with the Portage system</p> +<p>This package contains modules which work with the Portage system</p> <span class="target" id="module-package_utils.portage_log_parser"></span><dl class="function"> <dt id="package_utils.portage_log_parser.get_list_of_merged_packages"> <tt class="descclassname">package_utils.portage_log_parser.</tt><tt class="descname">get_list_of_merged_packages</tt><big>(</big><em>starttime=0</em>, <em>endtime=-1</em><big>)</big><a class="reference internal" href="_modules/package_utils/portage_log_parser.html#get_list_of_merged_packages"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#package_utils.portage_log_parser.get_list_of_merged_packages" title="Permalink to this definition">¶</a></dt> @@ -329,7 +329,7 @@ list)</td> </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/architecture.html b/docs/build/html/architecture.html index f827cff..855b3ab 100644 --- a/docs/build/html/architecture.html +++ b/docs/build/html/architecture.html @@ -57,12 +57,12 @@ <h2>How it works?<a class="headerlink" href="#how-it-works" title="Permalink to this headline">¶</a></h2> <div class="section" id="scheme"> <h3>Scheme<a class="headerlink" href="#scheme" title="Permalink to this headline">¶</a></h3> -<img alt="_images/autodep_arch.png" src="_images/autodep_arch.png" /> +<img alt="_images/autodep_arch1.png" src="_images/autodep_arch1.png" /> </div> <div class="section" id="format-of-network-messages"> <h3>Format of network messages<a class="headerlink" href="#format-of-network-messages" title="Permalink to this headline">¶</a></h3> <ol class="arabic"> -<li><p class="first">Format of messages to file access registrar:</p> +<li><p class="first">Format of messages to the File Access Registrar:</p> <div class="highlight-python"><pre><time of event: sec since 1970> <event type: open, read, write> <name of file> @@ -70,7 +70,7 @@ <result:OK,ERR/errno,ASKING,DENIED></pre> </div> </li> -<li><p class="first">Format of answer for ASKING packet from registrar:</p> +<li><p class="first">Format of answer for ASKING packet from File Access Registrar:</p> <div class="highlight-python"><pre><ALLOW | DENY></pre> </div> </li> @@ -78,46 +78,52 @@ <p><em>Notes:</em></p> <ul class="simple"> <li>All sockets are SOCK_SEQPACKET</li> -<li>All fields are delimited with character with code 0</li> +<li>All fields are delimited with character 0</li> </ul> </div> </div> -<div class="section" id="how-hooklib-approach-works"> -<h2>How Hooklib approach works?<a class="headerlink" href="#how-hooklib-approach-works" title="Permalink to this headline">¶</a></h2> -<p>The main idea of Hooklib approach is to load a dynamic library-hooker -<strong>before</strong> any other library(including the C runtime, libc.so). -So, the functions, such as open, read and write, executed from this library -instead of libc.so.</p> -<p>Hooklib module modifies Linux’s dynamic linker behavior changing LD_PRELOAD -environment variable(see +<div class="section" id="how-does-the-hooklib-approach-work"> +<h2>How does the Hooklib approach work?<a class="headerlink" href="#how-does-the-hooklib-approach-work" title="Permalink to this headline">¶</a></h2> +<p>The main idea behind the Hooklib approach is to load a dynamic library-hook +<strong>before</strong> any other library(including the C runtime). +So, the calls to functions such as open, read and write, are intercepted +using this library, instead of executing the ones in <em>libc</em>.</p> +<p>Hooklib module modifies Linux’s dynamic linker behavior, changing LD_PRELOAD +environment variable (see <a class="reference external" href="http://linux.die.net/man/8/ld-linux">man 8 ld-linux</a> for details). -Module protects LD_PRELOAD variable from further changes by program.</p> -<p>When hooklib module loads, it connects to file access registrar via Unix domain -sockets. If program forks or creates a new thread, another copy of library -loads.</p> -<p>When program do open(...), read(...), write(...), library send an information -about a call to registrar. Registar can block or allow an event. If registrer -allows an event then the original function is called. Else error -“file not found” is returned.</p> +This module also protects LD_PRELOAD variable from further changes by executing +program.</p> +<p>When Hooklib is loaded, it connects to the File Access Registrar via Unix domain +sockets. If a program forks or creates a new thread, another copy of the library +loads to register events from this new process/thread.</p> +<p>When a program calls open(...), read(...), write(...), Hooklib sends a message +about a call to the File Access Registrar. The Registar can then block +or allow this event. If Registrar responds to the previous query with +an ALLOW packet, then the original function is called. Otherwise, the function +is not called and a “File not Found” error is returned instead.</p> </div> -<div class="section" id="how-fusefs-approach-works"> -<h2>How Fusefs approach works?<a class="headerlink" href="#how-fusefs-approach-works" title="Permalink to this headline">¶</a></h2> -<p>The main idea if Fusefs approach is to create a loggable filesystem in userspace -and chroot a program into it.</p> -<p>Before program is launched registrar prepare mounts. It usually do:</p> +<div class="section" id="how-does-the-fusefs-approach-work"> +<h2>How does the Fusefs approach work?<a class="headerlink" href="#how-does-the-fusefs-approach-work" title="Permalink to this headline">¶</a></h2> +<p>The main idea of the Fusefs approach is to create a loggable filesystem in userspace +and jail a program into it, using a chroot.</p> +<p>Before the program is launched, The File Access Registrar prepare the mounts. +It would usually take the following steps:</p> <ol class="arabic simple"> <li>mount -o bind / /mnt/rootfs/</li> -<li>mount /dev/, /dev/pts, /dev/shm, /proc/, /sys/ same way</li> +<li>mount /dev, /dev/pts, /dev/shm, /proc/, /sys/ binding them to /mnt/rootfs</li> <li>mount /lib64/, /lib32/, /var/tmp/portage/ same way to increase performance at cost of accuracy</li> -<li>launch fuse over /mnt/rootfs/</li> +<li>launch FUSE over /mnt/rootfs/</li> </ol> -<p>Fuse module blocks all external access to /mnt/rootfs while program runs.</p> -<p>Fuse module also asks the registrar about event allowness.</p> +<p>Fuse module blocks all external access to /mnt/rootfs while the program runs. +The FUSE module will also ask the File Access Registrar to check whether access to +files inside the chroot are allowed or denied. As with the Hooklib approach, if +access to a file is denied, a “File not Found” error is returned.</p> <p><em>Notes:</em></p> <ul class="simple"> -<li>Checking for allowness takes a much time</li> +<li>Checking for permission to access a file with the File Access Registrar, takes a</li> </ul> +<p>lot of time under this approach.</p> </div> <div class="section" id="futher-analysis-of-file-access-events"> <h2>Futher analysis of file access events<a class="headerlink" href="#futher-analysis-of-file-access-events" title="Permalink to this headline">¶</a></h2> @@ -131,9 +137,9 @@ unuseful packages.</p> <div class="section" id="rules-of-heuristics"> <h3>Rules of heuristics<a class="headerlink" href="#rules-of-heuristics" title="Permalink to this headline">¶</a></h3> <ol class="arabic simple"> -<li><em>Package is not useful if all files are .desktop or .xml or .m4</em>. +<li><em>Package is not useful if all files are .desktop, .xml or .m4</em>. Aclocal util tries to read all .m4 files in /usr/share/aclocal directory. -Files ending on .desktop and .xml often readed on postrm phase.</li> +Files ending on .desktop and .xml are often read in the postrm phase.</li> </ol> </div> </div> @@ -153,8 +159,8 @@ Files ending on .desktop and .xml often readed on postrm phase.</li> <li><a class="reference internal" href="#format-of-network-messages">Format of network messages</a></li> </ul> </li> -<li><a class="reference internal" href="#how-hooklib-approach-works">How Hooklib approach works?</a></li> -<li><a class="reference internal" href="#how-fusefs-approach-works">How Fusefs approach works?</a></li> +<li><a class="reference internal" href="#how-does-the-hooklib-approach-work">How does the Hooklib approach work?</a></li> +<li><a class="reference internal" href="#how-does-the-fusefs-approach-work">How does the Fusefs approach work?</a></li> <li><a class="reference internal" href="#futher-analysis-of-file-access-events">Futher analysis of file access events</a><ul> <li><a class="reference internal" href="#rules-of-heuristics">Rules of heuristics</a></li> </ul> @@ -211,7 +217,7 @@ Files ending on .desktop and .xml often readed on postrm phase.</li> </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Jul 25, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/genindex.html b/docs/build/html/genindex.html index 3afc1ac..1889b59 100644 --- a/docs/build/html/genindex.html +++ b/docs/build/html/genindex.html @@ -200,7 +200,7 @@ </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/index.html b/docs/build/html/index.html index 95f586e..85fe72a 100644 --- a/docs/build/html/index.html +++ b/docs/build/html/index.html @@ -66,8 +66,8 @@ </li> <li class="toctree-l1"><a class="reference internal" href="architecture.html">Internals</a><ul> <li class="toctree-l2"><a class="reference internal" href="architecture.html#how-it-works">How it works?</a></li> -<li class="toctree-l2"><a class="reference internal" href="architecture.html#how-hooklib-approach-works">How Hooklib approach works?</a></li> -<li class="toctree-l2"><a class="reference internal" href="architecture.html#how-fusefs-approach-works">How Fusefs approach works?</a></li> +<li class="toctree-l2"><a class="reference internal" href="architecture.html#how-does-the-hooklib-approach-work">How does the Hooklib approach work?</a></li> +<li class="toctree-l2"><a class="reference internal" href="architecture.html#how-does-the-fusefs-approach-work">How does the Fusefs approach work?</a></li> <li class="toctree-l2"><a class="reference internal" href="architecture.html#futher-analysis-of-file-access-events">Futher analysis of file access events</a></li> </ul> </li> @@ -136,7 +136,7 @@ </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/man.html b/docs/build/html/man.html index 734bd1f..2560335 100644 --- a/docs/build/html/man.html +++ b/docs/build/html/man.html @@ -51,58 +51,58 @@ </div> <div class="section" id="description"> <h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> -<p>Auto dependency builder is a tool for analysis files accessed during -building a package. It also can be used for runtime dependencies analysis.</p> -<p>The tool can block an access to files of defined packages.</p> +<p>Auto dependency (autodep) builder is a tool for the analysis of accessed files during +the build of a package. It also can be used for runtime dependencies analysis.</p> +<p>The tool can trace, log and block access to files of given packages.</p> </div> <div class="section" id="options"> <h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2> <dl class="cmdoption"> <dt id="cmdoption-autodep--help"> <tt class="descname">--help</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-h</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-autodep--help" title="Permalink to this definition">¶</a></dt> -<dd><p>show this help message and exit</p> +<dd><p>Show this help message and exit.</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-autodep-b"> <tt class="descname">-b</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--block</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-autodep-b" title="Permalink to this definition">¶</a></dt> -<dd><p>strict mode: deny all access to non-dependency packages</p> +<dd><p>strict mode: Deny all access to files from non-dependency packages.</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-autodep--blockpkgs"> <tt class="descname">--blockpkgs</tt><tt class="descclassname">=PACKAGES</tt><a class="headerlink" href="#cmdoption-autodep--blockpkgs" title="Permalink to this definition">¶</a></dt> -<dd><p>block an access to files from this packages</p> +<dd><p>Block access to files from this packages.</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-autodep-f"> <tt class="descname">-f</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--files</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-autodep-f" title="Permalink to this definition">¶</a></dt> -<dd><p>show accessed files and not founded files</p> +<dd><p>Show all files, accessed and missing (not found).</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-autodep-v"> <tt class="descname">-v</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--verbose</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-autodep-v" title="Permalink to this definition">¶</a></dt> -<dd><p>show non-important packages, show unknown package and unknown stage</p> +<dd><p>Show non-important packages, unknown packages and unknown building stages.</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-autodep--nocolor"> <tt class="descname">--nocolor</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-C</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-autodep--nocolor" title="Permalink to this definition">¶</a></dt> -<dd><p>don’t output color</p> +<dd><p>Don’t colorize output</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-autodep--hooklib"> <tt class="descname">--hooklib</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-autodep--hooklib" title="Permalink to this definition">¶</a></dt> -<dd><p>use ld_preload logging approach(default)</p> +<dd><p>Use LD_PRELOAD logging approach (default).</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-autodep--fusefs"> <tt class="descname">--fusefs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-autodep--fusefs" title="Permalink to this definition">¶</a></dt> -<dd><p>use fuse logging approach(slow, but reliable)</p> +<dd><p>Use FUSE logging approach (slow, but reliable).</p> </dd></dl> </div> @@ -117,7 +117,7 @@ building a package. It also can be used for runtime dependencies analysis.</p> <thead valign="bottom"> <tr><th class="head"> </th> <th class="head">Hooklib</th> -<th class="head">Fusefs</th> +<th class="head">FuseFS</th> </tr> </thead> <tbody valign="top"> @@ -125,11 +125,11 @@ building a package. It also can be used for runtime dependencies analysis.</p> <td><strong>Any user</strong></td> <td>Only root</td> </tr> -<tr><td>Is approach allows blocking an access to files?</td> +<tr><td>Does approach allows to block access to files?</td> <td><strong>YES</strong></td> <td><strong>YES</strong></td> </tr> -<tr><td>Is overhead in performance big?</td> +<tr><td>Is the overhead in performance noticeable?</td> <td><strong>NO</strong></td> <td>YES <a class="footnote-reference" href="#f1" id="id1">[1]</a></td> </tr> @@ -138,15 +138,16 @@ building a package. It also can be used for runtime dependencies analysis.</p> <td><strong>ALL</strong></td> </tr> <tr><td>When is it recomended to use an approach?</td> -<td>For analysis +<td>Analysis of <em>buildtime</em> dependencies</td> -<td>For analysis +<td>Analysis of <em>runtime</em> dependencies</td> </tr> -<tr><td>Is any pre-requirements for using an approach?</td> +<tr><td>Are there any pre-requirements +for using an approach?</td> <td><strong>NO</strong></td> <td>FUSE must be enabled in @@ -158,33 +159,33 @@ kernel</td> <table class="docutils footnote" frame="void" id="f1" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Fuse file system is slower than normal one. Program reads many files +<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>FUSE filesystems are slower than a normal one. A Program accesses many files while launching, so this will take more time than usual.</td></tr> </tbody> </table> <table class="docutils footnote" frame="void" id="f2" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Loading of dynamic libraries and direct syscalls will not be logged.</td></tr> +<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Loading of Dynamic libraries and direct syscalls will not be logged.</td></tr> </tbody> </table> </div> <div class="section" id="examples"> <h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2> -<div class="section" id="get-the-potential-dependencies-of-a-xchat-package"> -<h3>Get the potential dependencies of a xchat package:<a class="headerlink" href="#get-the-potential-dependencies-of-a-xchat-package" title="Permalink to this headline">¶</a></h3> -<p>autodep emerge xchat</p> +<div class="section" id="get-the-potential-dependencies-for-net-irc-xchat"> +<h3>Get the potential dependencies for net-irc/xchat:<a class="headerlink" href="#get-the-potential-dependencies-for-net-irc-xchat" title="Permalink to this headline">¶</a></h3> +<p>autodep emerge net-irc/xchat</p> </div> -<div class="section" id="get-the-potential-dependencies-of-a-xchat-package-blocking-x11-misc-util-macros-package"> -<h3>Get the potential dependencies of a xchat package, blocking x11-misc/util-macros package:<a class="headerlink" href="#get-the-potential-dependencies-of-a-xchat-package-blocking-x11-misc-util-macros-package" title="Permalink to this headline">¶</a></h3> -<p>autodep emerge –block x11-misc/util-macros emerge xchat</p> +<div class="section" id="get-the-potential-dependencies-for-net-irc-xchat-blocking-files-from-x11-misc-util-macros-package"> +<h3>Get the potential dependencies for net-irc/xchat, blocking files from x11-misc/util-macros package:<a class="headerlink" href="#get-the-potential-dependencies-for-net-irc-xchat-blocking-files-from-x11-misc-util-macros-package" title="Permalink to this headline">¶</a></h3> +<p>autodep emerge –block x11-misc/util-macros emerge net-irc/xchat</p> </div> -<div class="section" id="get-the-potential-dependencies-of-a-xchat-package-and-show-files-accessed"> -<h3>Get the potential dependencies of a xchat package, and show files accessed:<a class="headerlink" href="#get-the-potential-dependencies-of-a-xchat-package-and-show-files-accessed" title="Permalink to this headline">¶</a></h3> -<p>autodep –files emerge xchat</p> +<div class="section" id="get-the-potential-dependencies-for-net-irc-xchat-package-and-show-accessed-files"> +<h3>Get the potential dependencies for net-irc/xchat package, and show accessed files:<a class="headerlink" href="#get-the-potential-dependencies-for-net-irc-xchat-package-and-show-accessed-files" title="Permalink to this headline">¶</a></h3> +<p>autodep –files emerge net-irc/xchat</p> </div> -<div class="section" id="get-the-runtime-dependencies-of-a-xchat-and-show-files-accessed"> -<h3>Get the runtime dependencies of a xchat and show files accessed:<a class="headerlink" href="#get-the-runtime-dependencies-of-a-xchat-and-show-files-accessed" title="Permalink to this headline">¶</a></h3> +<div class="section" id="get-the-runtime-dependencies-of-a-xchat-and-show-accessed-files"> +<h3>Get the runtime dependencies of a xchat and show accessed files:<a class="headerlink" href="#get-the-runtime-dependencies-of-a-xchat-and-show-accessed-files" title="Permalink to this headline">¶</a></h3> <p>autodep –fusefs –files xchat</p> </div> </div> @@ -204,10 +205,10 @@ while launching, so this will take more time than usual.</td></tr> <li><a class="reference internal" href="#options">OPTIONS</a></li> <li><a class="reference internal" href="#hooklib-vs-fusefs">HOOKLIB VS FUSEFS</a></li> <li><a class="reference internal" href="#examples">Examples</a><ul> -<li><a class="reference internal" href="#get-the-potential-dependencies-of-a-xchat-package">Get the potential dependencies of a xchat package:</a></li> -<li><a class="reference internal" href="#get-the-potential-dependencies-of-a-xchat-package-blocking-x11-misc-util-macros-package">Get the potential dependencies of a xchat package, blocking x11-misc/util-macros package:</a></li> -<li><a class="reference internal" href="#get-the-potential-dependencies-of-a-xchat-package-and-show-files-accessed">Get the potential dependencies of a xchat package, and show files accessed:</a></li> -<li><a class="reference internal" href="#get-the-runtime-dependencies-of-a-xchat-and-show-files-accessed">Get the runtime dependencies of a xchat and show files accessed:</a></li> +<li><a class="reference internal" href="#get-the-potential-dependencies-for-net-irc-xchat">Get the potential dependencies for net-irc/xchat:</a></li> +<li><a class="reference internal" href="#get-the-potential-dependencies-for-net-irc-xchat-blocking-files-from-x11-misc-util-macros-package">Get the potential dependencies for net-irc/xchat, blocking files from x11-misc/util-macros package:</a></li> +<li><a class="reference internal" href="#get-the-potential-dependencies-for-net-irc-xchat-package-and-show-accessed-files">Get the potential dependencies for net-irc/xchat package, and show accessed files:</a></li> +<li><a class="reference internal" href="#get-the-runtime-dependencies-of-a-xchat-and-show-accessed-files">Get the runtime dependencies of a xchat and show accessed files:</a></li> </ul> </li> </ul> @@ -250,7 +251,7 @@ while launching, so this will take more time than usual.</td></tr> </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 03, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/objects.inv b/docs/build/html/objects.inv Binary files differindex 72db0bb..a96802c 100644 --- a/docs/build/html/objects.inv +++ b/docs/build/html/objects.inv diff --git a/docs/build/html/py-modindex.html b/docs/build/html/py-modindex.html index e197fdc..e6d78e4 100644 --- a/docs/build/html/py-modindex.html +++ b/docs/build/html/py-modindex.html @@ -132,7 +132,7 @@ </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/search.html b/docs/build/html/search.html index 14597c1..5ecd73c 100644 --- a/docs/build/html/search.html +++ b/docs/build/html/search.html @@ -96,7 +96,7 @@ </div> <div class="footer"> © Copyright 2011, Alexander Bersenev. - Last updated on Aug 04, 2011. + Last updated on Aug 20, 2011. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7. </div> </body> diff --git a/docs/build/html/searchindex.js b/docs/build/html/searchindex.js index fa12b7a..a593094 100644 --- a/docs/build/html/searchindex.js +++ b/docs/build/html/searchindex.js @@ -1 +1 @@ -Search.setIndex({objects:{"":{"-v":[4,0,1],"-f":[4,0,1],"-C":[2,0,1],"-b":[4,0,1],"--hooklib":[4,0,1],"--fusefs":[4,0,1],"--blockpkgs":[4,0,1],"--nocolor":[4,0,1],"--help":[4,0,1]},"package_utils.portage_misc_functions":{portage_api:[1,4,1]},"package_utils.portage_log_parser":{get_list_of_merged_packages:[1,3,1]},logfs:{fstracer:[1,1,1]},"package_utils.portage_utils":{getfilesbypackage:[1,3,1],getpackagesbyfiles:[1,3,1],get_all_packages_files:[1,3,1]},"logfs.fstracer":{getfsevents:[1,3,1]},"package_utils.portage_misc_functions.portage_api":{get_dep:[1,2,1],get_system_packages_list:[1,2,1],get_best_visible_pkg:[1,2,1],get_deps:[1,2,1],get_merge_list:[1,2,1],parse_emerge_args:[1,2,1]},package_utils:{portage_misc_functions:[1,1,1],portage_utils:[1,1,1],portage_log_parser:[1,1,1]}},terms:{all:[1,2,3,4],code:3,chain:1,mnt:3,prog_nam:1,showfsev:2,depend:[1,2,3,4],send:3,ebuild:2,program:[1,2,3,4],under:2,sourc:1,string:1,fals:1,util:[2,3,4],candid:1,veri:1,hooker:3,tri:3,level:1,list:[1,3],mount:3,defaultfilt:1,slower:[2,4],direct:[2,4],second:1,cost:3,pass:1,further:3,index:2,what:[2,4],compar:3,access:[0,1,2,3,4],version:1,"new":3,modifi:3,sinc:[1,3],search:[1,2],action:1,chang:3,via:3,packagenam:1,modul:[1,2,3],filenam:1,unix:3,api:[0,1],heurist:3,instal:[0,1,2,3],get_dep:1,from:[1,2,3,4],memori:1,two:1,call:[1,3],usr:3,type:[1,3],more:[2,4],ld_preload:[2,3,4],endtim:1,getfilesbypackag:1,must:[1,2,4],lib32:3,err:3,package_util:[0,1],prepar:3,registar:3,dev:3,can:[1,2,3,4],"0x1dbdb90":[],root:[2,4],registr:3,share:3,indic:[0,2],high:1,unreli:1,portage_log_pars:1,chroot:3,end:[1,3],anoth:3,write:[1,3],how:[0,3],answer:3,instead:[1,3],simpl:3,map:3,alwai:1,after:3,befor:3,blockpkg:[2,4],mai:1,man:3,syscal:[2,4],bind:3,element:1,inform:[1,3],environ:3,allow:[1,2,3,4],rdepend:1,origin:3,help:[2,4],over:3,rootf:3,dynam:[2,3,4],paramet:1,get_best_visible_pkg:1,cowsai:2,main:3,sock_seqpacket:3,"return":[1,3],thei:1,handl:1,auto:[2,4],"0x19e7b18":[],introduct:[0,2],name:[1,3],mode:[2,4],each:1,found:[1,2,3,4],domain:3,idea:3,logf:[0,1],connect:3,todo:2,event:[0,1,2,3,4],variabl:3,network:3,content:0,got:3,lib64:3,believ:3,dictionari:1,ask:3,bash:[1,2],thread:3,launch:[1,2,3,4],get_list_of_merged_packag:1,filter:1,registrar:3,getfsev:1,first:1,oper:1,misc:[2,4],open:[1,3],gpl:2,start:1,unknown:[1,2,3,4],licens:2,system:[1,2,3,4],messag:[2,3,4],scheme:3,low:1,option:[1,2,4],tool:[2,4],copi:3,postrm:3,pars:1,than:[2,4],portage_util:1,get_merge_list:1,charact:3,bridg:1,pre:[2,4],"function":[1,3],linker:3,argument:1,raw:1,tabl:[0,2],packag:[1,2,3,4],accuraci:3,note:[2,3,4],also:[1,2,3,4],build:[2,3,4],which:1,analysi:[0,2,3,4],loggabl:3,normal:[2,4],who:[2,4],most:[2,4],buildtim:[2,4],hooklib:[0,1,2,3,4],phase:3,"class":1,don:[2,4],portage_misc_funct:1,deni:[2,3,4],runtim:[2,3,4],hungri:1,show:[2,4],verbos:[2,4],pkg:1,find:1,xml:3,current:1,onli:[2,4],slow:[2,4],activ:2,dep_typ:1,should:1,parse_emerge_arg:1,analys:3,unus:3,variou:1,get:[1,2,4],increas:3,requir:[2,4],enabl:[2,4],contain:1,userspac:3,shm:3,kernel:[2,4],set:1,packet:3,see:3,sec:3,result:3,arg:1,fail:1,best:1,statu:[0,2],between:1,"import":[2,4],approach:[0,1,2,3,4],kei:1,get_all_packages_fil:1,xchat:[2,4],both:1,fstracer:[0,1],delimit:3,logic:1,futher:[0,3],mani:[2,4],lsof:2,load:[2,3,4],color:[2,4],overview:[0,2],linux:3,reciev:3,fusef:[0,1,2,3,4],empti:1,implicit:[1,3],much:3,recomend:[2,4],protect:3,ani:[1,2,3,4],look:1,stagenam:3,gnu:2,servic:1,defin:[2,4],"while":[2,3,4],behavior:3,error:3,non:[2,4],synopsi:4,develop:2,perform:[2,3,4],make:2,belong:1,same:3,read:[1,2,3,4],document:0,fuse:[2,3,4],user:[2,4],extern:3,portag:[1,3],macro:[2,4],builder:[2,4],exampl:[0,1,2,4],command:[2,4],thi:[1,2,3,4],filesystem:3,usual:[2,3,4],execut:3,cut:3,"0x1b2bc80":1,desktop:3,els:3,take:[1,2,3,4],filterproc:1,format:3,libc:3,big:[2,4],recurs:1,success:1,nocolor:[2,4],output:[2,4],page:2,often:3,intern:[0,1,3],successfulli:1,librari:[2,3,4],tmp:3,autodep:[0,2,4],exit:[2,4],overlai:2,proc:3,run:[0,2,3],starttim:1,x11:[2,4],portage_api:1,stage:[1,2,3,4],about:3,socket:3,block:[1,2,3,4],merg:1,log:[1,2,4],wai:3,errno:3,strict:[2,4],includ:3,"var":3,overhead:[2,4],fork:3,unexpect:3,tupl:1,atom:1,"true":1,"default":[1,2,4],creat:3,dure:[2,4],parser:1,doesn:1,file:[0,1,2,3,4],work:[0,1,3],check:3,emergearg:1,acloc:3,when:[2,3,4],detail:3,field:3,other:3,getpackagesbyfil:1,get_system_packages_list:1,releas:2,directori:3,reliabl:[2,4],descript:4,rule:3,depth:1,emerg:[1,2,4],potenti:[2,4],time:[1,2,3,4],profil:3},objtypes:{"0":"std:option","1":"py:module","2":"py:method","3":"py:function","4":"py:class"},titles:["Autodep’s documentation","API","Introduction","Internals","USER COMMANDS"],objnames:{"0":"option","1":"Python module","2":"Python method","3":"Python function","4":"Python class"},filenames:["index","api","intro","architecture","man"]})
\ No newline at end of file +Search.setIndex({objects:{"":{"-v":[4,0,1],"-f":[4,0,1],"-C":[2,0,1],"-b":[4,0,1],"--hooklib":[4,0,1],"--fusefs":[4,0,1],"--blockpkgs":[4,0,1],"--nocolor":[4,0,1],"--help":[4,0,1]},"logfs.fstracer":{getfsevents:[1,3,1]},"package_utils.portage_log_parser":{get_list_of_merged_packages:[1,3,1]},logfs:{fstracer:[1,1,1]},"package_utils.portage_utils":{getfilesbypackage:[1,3,1],getpackagesbyfiles:[1,3,1],get_all_packages_files:[1,3,1]},"package_utils.portage_misc_functions":{portage_api:[1,4,1]},"package_utils.portage_misc_functions.portage_api":{get_dep:[1,2,1],get_system_packages_list:[1,2,1],get_best_visible_pkg:[1,2,1],get_deps:[1,2,1],get_merge_list:[1,2,1],parse_emerge_args:[1,2,1]},package_utils:{portage_misc_functions:[1,1,1],portage_utils:[1,1,1],portage_log_parser:[1,1,1]}},terms:{all:[1,2,3,4],code:[],chain:1,queri:3,mnt:3,follow:3,prog_nam:1,showfsev:2,depend:[1,2,3,4],send:3,ebuild:2,program:[1,2,3,4],under:[2,3],sourc:1,string:1,fals:1,util:[2,3,4],candid:1,veri:1,hooker:[],tri:3,level:1,list:[1,3],mount:3,defaultfilt:1,slower:[2,4],direct:[2,4],second:1,cost:3,pass:1,further:3,index:2,what:[2,4],compar:3,access:[0,1,2,3,4],version:1,"new":3,net:4,intercept:3,modifi:3,sinc:[1,3],search:[1,2],action:1,chang:3,via:3,packagenam:1,modul:[1,2,3],filenam:1,unix:3,api:[0,1],heurist:3,instal:[0,1,2,3],get_dep:1,from:[1,2,3,4],would:3,memori:1,regist:3,two:1,call:[1,3],usr:3,type:[1,3],more:[2,4],ld_preload:[2,3,4],notic:4,endtim:1,getfilesbypackag:1,must:[1,2,4],lib32:3,err:3,package_util:[0,1],prepar:3,registar:3,dev:3,can:[1,2,3,4],"0x1dbdb90":[],root:[2,4],process:3,registr:[],share:3,indic:[0,2],high:1,unreli:1,portage_log_pars:1,chroot:3,end:[1,3],anoth:3,write:[1,3],how:[0,3],answer:3,instead:[1,3],simpl:3,map:3,alwai:1,after:3,befor:3,blockpkg:[2,4],mai:1,man:3,syscal:[2,4],bind:3,element:1,inform:1,environ:3,allow:[1,2,3,4],rdepend:1,origin:3,help:[2,4],over:3,rootf:3,dynam:[2,3,4],paramet:1,get_best_visible_pkg:1,cowsai:2,main:3,them:3,"return":[1,3],thei:1,handl:1,auto:[2,4],"0x19e7b18":[],introduct:[0,2],name:[1,3],"0x1dcb938":1,mode:[2,4],each:1,found:[1,2,3,4],domain:3,idea:3,logf:[0,1],connect:3,todo:2,event:[0,1,2,3,4],variabl:3,network:3,miss:4,content:0,got:3,lib64:3,insid:3,believ:3,dictionari:1,ask:3,bash:[1,2],thread:3,launch:[1,2,3,4],get_list_of_merged_packag:1,filter:1,registrar:3,getfsev:1,first:1,oper:1,misc:[2,4],hook:3,open:[1,3],gpl:2,given:4,start:1,unknown:[1,2,3,4],licens:2,system:[1,2,3],messag:[2,3,4],scheme:3,low:1,option:[1,2,4],tool:[2,4],copi:3,postrm:3,pars:1,than:[2,4],portage_util:1,get_merge_list:1,charact:3,bridg:1,pre:[2,4],"function":[1,3],linker:3,argument:1,raw:1,tabl:[0,2],packag:[1,2,3,4],accuraci:3,note:[2,3,4],also:[1,2,3,4],build:[2,3,4],which:1,jail:3,analysi:[0,2,3,4],loggabl:3,trace:4,normal:[2,4],who:[2,4],most:[2,4],buildtim:[2,4],hooklib:[0,1,2,3,4],phase:3,"class":1,don:[2,4],portage_misc_funct:1,doe:[0,3,4],deni:[2,3,4],runtim:[2,3,4],hungri:1,show:[2,4],verbos:[2,4],pkg:1,permiss:3,find:1,xml:3,current:1,onli:[2,4],slow:[2,4],activ:2,dep_typ:1,should:1,parse_emerge_arg:1,analys:3,unus:3,variou:1,get:[1,2,4],increas:3,requir:[2,4],enabl:[2,4],"default":[1,2,4],contain:1,userspac:3,shm:3,respond:3,kernel:[2,4],set:1,packet:3,see:3,sec:3,result:3,arg:1,fail:1,best:1,statu:[0,2],behind:3,between:1,"import":[2,4],irc:4,approach:[0,1,2,3,4],kei:1,get_all_packages_fil:1,xchat:[2,4],both:1,protect:3,delimit:3,logic:1,futher:[0,3],mani:[2,4],lsof:2,load:[2,3,4],color:[2,4],overview:[0,2],linux:3,reciev:3,fusef:[0,1,2,3,4],empti:1,implicit:[1,3],much:[],recomend:[2,4],fstracer:[0,1],ani:[1,2,3,4],look:1,stagenam:3,gnu:2,servic:1,defin:2,"while":[2,3,4],behavior:3,error:3,non:[2,4],sock_seqpacket:3,synopsi:4,develop:2,perform:[2,3,4],make:2,belong:1,same:3,read:[1,2,3],document:0,fuse:[2,3,4],user:[2,4],extern:3,portag:[1,3],macro:[2,4],builder:[2,4],exampl:[0,1,2,4],command:[2,4],thi:[1,2,3,4],filesystem:[3,4],usual:[2,3,4],execut:3,cut:3,"0x1b2bc80":[],desktop:3,els:[],take:[1,2,3,4],filterproc:1,format:3,libc:3,big:2,recurs:1,success:1,nocolor:[2,4],output:[2,4],page:2,often:3,intern:[0,1,3],successfulli:1,librari:[2,3,4],tmp:3,autodep:[0,2,4],exit:[2,4],overlai:2,proc:3,previou:3,run:[0,2,3],step:3,starttim:1,x11:[2,4],portage_api:1,stage:[1,2,3,4],about:3,socket:3,block:[1,2,3,4],merg:1,log:[1,2,4],wai:3,errno:3,strict:[2,4],includ:3,lot:3,"var":3,overhead:[2,4],fork:3,unexpect:3,tupl:1,atom:1,"true":1,whether:3,otherwis:3,creat:3,dure:[2,4],parser:1,doesn:1,file:[0,1,2,3,4],work:[0,1,3],check:3,emergearg:1,acloc:3,when:[2,3,4],detail:3,field:3,other:3,getpackagesbyfil:1,get_system_packages_list:1,releas:2,directori:3,reliabl:[2,4],descript:4,rule:3,depth:1,emerg:[1,2,4],potenti:[2,4],time:[1,2,3,4],profil:3},objtypes:{"0":"std:option","1":"py:module","2":"py:method","3":"py:function","4":"py:class"},titles:["Autodep’s documentation","API","Introduction","Internals","USER COMMANDS"],objnames:{"0":"option","1":"Python module","2":"Python method","3":"Python function","4":"Python class"},filenames:["index","api","intro","architecture","man"]})
\ No newline at end of file diff --git a/docs/build/man/autodep.1 b/docs/build/man/autodep.1 index b338c58..202dd11 100644 --- a/docs/build/man/autodep.1 +++ b/docs/build/man/autodep.1 @@ -1,4 +1,4 @@ -.TH "AUTODEP" "1" "August 04, 2011" "0.1" "Autodep" +.TH "AUTODEP" "1" "August 20, 2011" "0.1" "Autodep" .SH NAME autodep \- auto dependency builder for Gentoo . @@ -35,58 +35,50 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] \fBautodep\fP [options] <command> .SH DESCRIPTION .sp -Auto dependency builder is a tool for analysis files accessed during -building a package. It also can be used for runtime dependencies analysis. +Auto dependency (autodep) builder is a tool for the analysis of accessed files during +the build of a package. It also can be used for runtime dependencies analysis. .sp -The tool can block an access to files of defined packages. +The tool can trace, log and block access to files of given packages. .SH OPTIONS .INDENT 0.0 .TP .B \-\-help, \-h -.sp -show this help message and exit +Show this help message and exit. .UNINDENT .INDENT 0.0 .TP .B \-b, \-\-block -.sp -strict mode: deny all access to non\-dependency packages +strict mode: Deny all access to files from non\-dependency packages. .UNINDENT .INDENT 0.0 .TP .B \-\-blockpkgs=PACKAGES -.sp -block an access to files from this packages +Block access to files from this packages. .UNINDENT .INDENT 0.0 .TP .B \-f, \-\-files -.sp -show accessed files and not founded files +Show all files, accessed and missing (not found). .UNINDENT .INDENT 0.0 .TP .B \-v, \-\-verbose -.sp -show non\-important packages, show unknown package and unknown stage +Show non\-important packages, unknown packages and unknown building stages. .UNINDENT .INDENT 0.0 .TP .B \-\-nocolor, \-C -.sp -don\(aqt output color +Don\(aqt colorize output .UNINDENT .INDENT 0.0 .TP .B \-\-hooklib -. -use ld_preload logging approach(default) +Use LD_PRELOAD logging approach (default). .UNINDENT .INDENT 0.0 .TP .B \-\-fusefs -. -use fuse logging approach(slow, but reliable) +Use FUSE logging approach (slow, but reliable). .UNINDENT .SH HOOKLIB VS FUSEFS .TS @@ -97,7 +89,7 @@ T{ T} T{ Hooklib T} T{ -Fusefs +FuseFS T} _ T{ @@ -109,7 +101,7 @@ Only root T} _ T{ -Is approach allows blocking an access to files? +Does approach allows to block access to files? T} T{ \fBYES\fP T} T{ @@ -117,7 +109,7 @@ T} T{ T} _ T{ -Is overhead in performance big? +Is the overhead in performance noticeable? T} T{ \fBNO\fP T} T{ @@ -135,18 +127,19 @@ _ T{ When is it recomended to use an approach? T} T{ -For analysis +Analysis of \fIbuildtime\fP dependencies T} T{ -For analysis +Analysis of \fIruntime\fP dependencies T} _ T{ -Is any pre\-requirements for using an approach? +Are there any pre\-requirements +for using an approach? T} T{ \fBNO\fP T} T{ @@ -158,23 +151,21 @@ _ .TE Notes .IP [1] 5 -. -Fuse file system is slower than normal one. Program reads many files +FUSE filesystems are slower than a normal one. A Program accesses many files while launching, so this will take more time than usual. .IP [2] 5 -. -Loading of dynamic libraries and direct syscalls will not be logged. +Loading of Dynamic libraries and direct syscalls will not be logged. .SH EXAMPLES -.SS Get the potential dependencies of a xchat package: +.SS Get the potential dependencies for net\-irc/xchat: .sp -autodep emerge xchat -.SS Get the potential dependencies of a xchat package, blocking x11\-misc/util\-macros package: +autodep emerge net\-irc/xchat +.SS Get the potential dependencies for net\-irc/xchat, blocking files from x11\-misc/util\-macros package: .sp -autodep emerge \-\-block x11\-misc/util\-macros emerge xchat -.SS Get the potential dependencies of a xchat package, and show files accessed: +autodep emerge \-\-block x11\-misc/util\-macros emerge net\-irc/xchat +.SS Get the potential dependencies for net\-irc/xchat package, and show accessed files: .sp -autodep \-\-files emerge xchat -.SS Get the runtime dependencies of a xchat and show files accessed: +autodep \-\-files emerge net\-irc/xchat +.SS Get the runtime dependencies of a xchat and show accessed files: .sp autodep \-\-fusefs \-\-files xchat .SH AUTHOR diff --git a/docs/source/api.rst b/docs/source/api.rst index 1397732..502db1e 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -11,7 +11,7 @@ logfs.fstracer package_utils ================================ -This package contains modules which works with the Portage system +This package contains modules which work with the Portage system .. automodule:: package_utils.portage_log_parser :members: diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index 59b55f8..2caec16 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -13,66 +13,71 @@ Format of network messages -------------------------- -1. Format of messages to file access registrar:: +1. Format of messages to the File Access Registrar:: <time of event: sec since 1970> <event type: open, read, write> <name of file> <building stage: stagename or unknown> <result:OK,ERR/errno,ASKING,DENIED> -2. Format of answer for ASKING packet from registrar:: +2. Format of answer for ASKING packet from File Access Registrar:: <ALLOW | DENY> *Notes:* * All sockets are SOCK_SEQPACKET -* All fields are delimited with character with code 0 +* All fields are delimited with character \0 -How Hooklib approach works? -=========================== +How does the Hooklib approach work? +=================================== -The main idea of Hooklib approach is to load a dynamic library-hooker -**before** any other library(including the C runtime, libc.so). -So, the functions, such as open, read and write, executed from this library -instead of libc.so. +The main idea behind the Hooklib approach is to load a dynamic library-hook +**before** any other library(including the C runtime). +So, the calls to functions such as open, read and write, are intercepted +using this library, instead of executing the ones in *libc*. -Hooklib module modifies Linux's dynamic linker behavior changing LD_PRELOAD -environment variable(see +Hooklib module modifies Linux's dynamic linker behavior, changing LD_PRELOAD +environment variable (see `man 8 ld-linux <http://linux.die.net/man/8/ld-linux>`_ for details). -Module protects LD_PRELOAD variable from further changes by program. +This module also protects LD_PRELOAD variable from further changes by executing +program. -When hooklib module loads, it connects to file access registrar via Unix domain -sockets. If program forks or creates a new thread, another copy of library -loads. +When Hooklib is loaded, it connects to the File Access Registrar via Unix domain +sockets. If a program forks or creates a new thread, another copy of the library +loads to register events from this new process/thread. -When program do open(...), read(...), write(...), library send an information -about a call to registrar. Registar can block or allow an event. If registrer -allows an event then the original function is called. Else error -"file not found" is returned. +When a program calls open(...), read(...), write(...), Hooklib sends a message +about a call to the File Access Registrar. The Registar can then block +or allow this event. If Registrar responds to the previous query with +an ALLOW packet, then the original function is called. Otherwise, the function +is not called and a "File not Found" error is returned instead. -How Fusefs approach works? -========================== +How does the Fusefs approach work? +================================== -The main idea if Fusefs approach is to create a loggable filesystem in userspace -and chroot a program into it. +The main idea of the Fusefs approach is to create a loggable filesystem in userspace +and jail a program into it, using a chroot. -Before program is launched registrar prepare mounts. It usually do: +Before the program is launched, The File Access Registrar prepare the mounts. +It would usually take the following steps: 1. mount -o bind / /mnt/rootfs/ -2. mount /dev/, /dev/pts, /dev/shm, /proc/, /sys/ same way +2. mount /dev, /dev/pts, /dev/shm, /proc/, /sys/ binding them to /mnt/rootfs 3. mount /lib64/, /lib32/, /var/tmp/portage/ same way to increase performance at cost of accuracy -4. launch fuse over /mnt/rootfs/ +4. launch FUSE over /mnt/rootfs/ -Fuse module blocks all external access to /mnt/rootfs while program runs. - -Fuse module also asks the registrar about event allowness. +Fuse module blocks all external access to /mnt/rootfs while the program runs. +The FUSE module will also ask the File Access Registrar to check whether access to +files inside the chroot are allowed or denied. As with the Hooklib approach, if +access to a file is denied, a "File not Found" error is returned. *Notes:* -* Checking for allowness takes a much time +* Checking for permission to access a file with the File Access Registrar, takes a +lot of time under this approach. Futher analysis of file access events ===================================== @@ -90,6 +95,6 @@ unuseful packages. Rules of heuristics ------------------- -1. *Package is not useful if all files are .desktop or .xml or .m4*. +1. *Package is not useful if all files are .desktop, .xml or .m4*. Aclocal util tries to read all .m4 files in /usr/share/aclocal directory. - Files ending on .desktop and .xml often readed on postrm phase.
\ No newline at end of file + Files ending on .desktop and .xml are often read in the postrm phase.
\ No newline at end of file diff --git a/docs/source/man.rst b/docs/source/man.rst index b49fb54..bf5ad86 100644 --- a/docs/source/man.rst +++ b/docs/source/man.rst @@ -10,10 +10,10 @@ SYNOPSIS DESCRIPTION =========== -Auto dependency builder is a tool for analysis files accessed during -building a package. It also can be used for runtime dependencies analysis. +Auto dependency (autodep) builder is a tool for the analysis of accessed files during +the build of a package. It also can be used for runtime dependencies analysis. -The tool can block an access to files of defined packages. +The tool can trace, log and block access to files of given packages. OPTIONS ======= @@ -22,78 +22,78 @@ OPTIONS .. cmdoption:: --help, -h - show this help message and exit + Show this help message and exit. .. cmdoption:: -b, --block - strict mode: deny all access to non-dependency packages + strict mode: Deny all access to files from non-dependency packages. .. cmdoption:: --blockpkgs=PACKAGES - block an access to files from this packages + Block access to files from this packages. .. cmdoption:: -f, --files - show accessed files and not founded files + Show all files, accessed and missing (not found). .. cmdoption:: -v, --verbose - show non-important packages, show unknown package and unknown stage + Show non-important packages, unknown packages and unknown building stages. .. cmdoption:: --nocolor, -C - don't output color + Don't colorize output .. cmdoption:: --hooklib - use ld_preload logging approach(default) + Use LD_PRELOAD logging approach (default). .. cmdoption:: --fusefs - use fuse logging approach(slow, but reliable) + Use FUSE logging approach (slow, but reliable). HOOKLIB VS FUSEFS ================= +------------------------------------------------+-------------+---------------+ -| | Hooklib | Fusefs | +| | Hooklib | FuseFS | +================================================+=============+===============+ | Who can use this approach? | **Any user**| Only root | +------------------------------------------------+-------------+---------------+ -| Is approach allows blocking an access to files?| **YES** | **YES** | +| Does approach allows to block access to files? | **YES** | **YES** | +------------------------------------------------+-------------+---------------+ -| Is overhead in performance big? | **NO** | YES [#f1]_ | +| Is the overhead in performance noticeable? | **NO** | YES [#f1]_ | +------------------------------------------------+-------------+---------------+ | What events are logged? | Most [#f2]_| **ALL** | +------------------------------------------------+-------------+---------------+ -| When is it recomended to use an approach? | For analysis| For analysis | +| When is it recomended to use an approach? | Analysis | Analysis | | | of | of *runtime* | | | *buildtime* | dependencies | | | dependencies| | +------------------------------------------------+-------------+---------------+ -| Is any pre-requirements for using an approach? | **NO** | FUSE must be | -| | | enabled in | +| Are there any pre-requirements | **NO** | FUSE must be | +| for using an approach? | | enabled in | | | | kernel | +------------------------------------------------+-------------+---------------+ .. rubric:: Notes -.. [#f1] Fuse file system is slower than normal one. Program reads many files +.. [#f1] FUSE filesystems are slower than a normal one. A Program accesses many files while launching, so this will take more time than usual. -.. [#f2] Loading of dynamic libraries and direct syscalls will not be logged. +.. [#f2] Loading of Dynamic libraries and direct syscalls will not be logged. Examples ======== -Get the potential dependencies of a xchat package: ------------------------------------------------------ -autodep emerge xchat +Get the potential dependencies for net-irc/xchat: +------------------------------------------------- +autodep emerge net-irc/xchat -Get the potential dependencies of a xchat package, blocking x11-misc/util-macros package: --------------------------------------------------------------------------------------------- -autodep emerge --block x11-misc/util-macros emerge xchat +Get the potential dependencies for net-irc/xchat, blocking files from x11-misc/util-macros package: +--------------------------------------------------------------------------------------------------- +autodep emerge --block x11-misc/util-macros emerge net-irc/xchat -Get the potential dependencies of a xchat package, and show files accessed: ------------------------------------------------------------------------------- -autodep --files emerge xchat +Get the potential dependencies for net-irc/xchat package, and show accessed files: +---------------------------------------------------------------------------------- +autodep --files emerge net-irc/xchat -Get the runtime dependencies of a xchat and show files accessed: -------------------------------------------------------------------- +Get the runtime dependencies of a xchat and show accessed files: +---------------------------------------------------------------- autodep --fusefs --files xchat diff --git a/src/autodep/autodep b/src/autodep/autodep index 1152180..f202d0d 100755 --- a/src/autodep/autodep +++ b/src/autodep/autodep @@ -19,26 +19,26 @@ def parse_args(): args_parser=optparse.OptionParser("%prog [options] <command>") args_parser.add_option("-b","--block",action="store_true", dest="strict_block", default="", - help="strict mode: deny all access to non-dependency packages") + help="strict mode: Deny all access to files from non-dependency packages.") args_parser.add_option("--blockpkgs",action="store", type="string", dest="packages", default="", - help="block an access to files from this packages") + help="Block access to files from these packages.") args_parser.add_option("-f","--files", action="store_true", dest="show_files", - default=False, help="show all accessed files and not founded files") + default=False, help="Show all files, accessed and missing ( not founded).") args_parser.add_option("-v","--verbose", action="store_true", dest="verbose", - default=False, help="show non-important packages, " - "show unknown package and unknown stage") + default=False, help="Show non-important packages, " + "unknown package and unknown stage") args_parser.add_option("-n","--numfiles",action="store", type="string", dest="numfiles", default=10, - help="maximum number of files from each package to show(default is 10)") + help="Maximum number of files from each package to show (default is 10)") args_parser.add_option("-C","--nocolor",action="store_true", dest="nocolor", - default=False, help="don't output color") + default=False, help="Don't colorize output") args_parser.add_option("--hooklib",action="store_const", dest="approach", - const="hooklib", help="use ld_preload logging approach(default)") + const="hooklib", help="Use ld_preload logging approach (default)") args_parser.add_option("--fusefs",action="store_const", dest="approach", - const="fusefs", help="use fuse logging approach(slow, but reliable)") + const="fusefs", help="Use FUSE logging approach (slow, but reliable)") args_parser.set_defaults(approach="hooklib") args_parser.epilog="Example: %s -blockpkgs lsof,cowsay emerge bash" % ( |
