\title Apt-Cacher-NG filesystem emulator documentation

\cfg{man-identity}{acngfs}{8}{Juni 2008}{acngfs}{Eduard Bloch}
\cfg{man-filename}{acngfs.8}
\cfg{man-mindepth}{1}

\A{manpage} acngfs \cw{man} page


\H{manpage-name} NAME

\cw{acngfs} \u2013{\u2212{-}} Virtual file system for use with apt-cacher-ng

\H{manpage-synopsis} SYNOPSIS

\c acngfs BaseURL ProxyHost [CachePath] MountPoint [-o FUSE Mount Options]

\H{manpage-description} DESCRIPTION

acngfs is a FUSE based filesystem which represents files downloadable via
HTTP as part of a local filesystem. It has been developed for very specific
purposes and is not intended to be a general purpose HTTP filesystem.

The main use case for \e{acngfs} is a situation where:

\b The files must not be stored on extra space on the user's system (e.g. because of insufficient disk space to make a temporary copy of downloaded files)

\b Local programs (e.g. apt, dpkg) need to read the packages from a local filesystem

\b When reading, certain files might need to be fetched in background (or updated) and this process needs to be triggered somehow

\b Network latency and speed are not relevant, e.g. accessing apt-cacher-ng via localhost connection

\b The proxy service can work efficiently with many requests for small data ranges (apt-cacher-ng, for example)

\b Pattern matching on paths is sufficient to distinguish file and directory names

If the apt-cacher-ng instance happens to run on the same system as acngfs or
its cache repository is mounted via fast remote file system, this cache
repository can be optionally specified as alternative source path. In this
cache, acngfs will attempt to read files directly from this filesystem where
possible, reducing network latency and avoiding additional load of apt-cacher-ng server.
The directory levels of BaseURL and CachePath should match.

\H{manpage-examples} EXAMPLES

Typical use may be to let apt/dpkg use package file like they are present on the local filesystem so there is no need to download them.
In sources.list, the source appears as a file:/ type URL, like: 

\c{deb file:/var/local/acngfs_debian unstable main contrib}

and the filesystem backend is prepared with a command like:

\c{/usr/lib/apt-cacher-ng/acngfs http://ftp.uni-kl.de/debian cacheBox:3142 /var/local/acngfs_debian -o allow_root}

or for a locally installed apt-cacher-ng with common Debian cache repository stored in /var/cache/apt-cacher-ng/debrep:

\c{/usr/lib/apt-cacher-ng/acngfs http://ftp.uni-kl.de/debian localhost:3142 /var/cache/apt-cacher-ng/debrep /var/local/acngfs_debian -o allow_root}

\H{manpage-options} OPTIONS

The command-line options supported by \c{acngfs} are:

\dt \cw{BaseURL}

\dd Remote mirror to be used as real source, like
\cw{http://ftp2.de.debian.org/debian}. NOTE: the mirror subdirectory part (like
\cw{debian}) should be added either to \cw{BaseURL} or to the path in
sources.list, not to both.

\dt \cw{ProxyURL}

\dd Complete or simplified host and port specification of the proxy server, \cw{http://localhost:3142}.

\dt \cw{CachePath}

\dd Optional hint, a directory path pointing to the internal cache subdirectory of apt-cacher-ng where it stores data downloaded from \cw{BaseURL}. For more details see \cw{apt-cacher-ng} manual, chapter "Advanced configuration".

\dt \cw{mountpoint}

\dd Directory representing the URL in the local filesytem.

\dt \cw{--help}

\dd Print a help summary and additional FUSE application options

\dt \cw{FuseOptions}

\dd Various options for the FUSE subsystem to control filesystem behaviour. See --help output and FUSE documentation for more details.

\H{manpage-files}FILES

\dt \cw{/usr/lib/apt-cacher-ng/acngfs}

\dd Executable binary documented in this manual page

\H{manpage-notes} NOTES

Permissions of the files are important when using mounting when
sharing data with other users (including root!). To mount as user and let root
use the package management tools (apt, dpkg), one may need to use FUSE options like in the following example:

\c{acngfs http://ftp.uni-kl.de/debian http://localhost:3142 /mnt/misc -o allow_root}

See FUSE documentation for details about file permissions representation.

\H{manpage-bugs} BUGS

Software is still experimental, use at your own risk!

There are natural limitations on capabilities of the FS: no directory browsing
is allowed (only blind descending), permissions of files are inherited from the
mount point as well as other properties of the filesystem.

Should be used with apt-cacher-ng version 0.2pre2 or newer; otherwise it could
flood log files with many requests from small file chunks.

\H{manpage-more-information} SEE ALSO

\cw{apt-cacher-ng}(8), \cw{fusermount}(1)

For more information on Apt-Cacher NG, read the User Manual which can be found
either in the doc/pdf directory of the software source package or installed in
the documentation directory of apt-cacher-ng by your distribution.

\versionid Eduard Bloch, Sun, 07 Aug 2011 00:38:54 +0200
