Commit 11d1612b authored by Stefano Melchior's avatar Stefano Melchior

Added humfsify and uml_mount sgml to create their man pages

parent 13b45f31
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!-- Process this file with docbook-to-man to generate an nroff manual
page: `docbook-to-man manpage.sgml > manpage.1'. You may view
the manual page with: `docbook-to-man manpage.sgml | nroff -man |
less'. A typical entry in a Makefile or Makefile.am is:
manpage.1: manpage.sgml
docbook-to-man $< > $@
-->
<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!ENTITY dhfirstname "<firstname>Stefano</firstname>">
<!ENTITY dhsurname "<surname>Melchior</surname>">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY dhdate "<date>October 26, 2006</date>">
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
allowed: see man(7), man(1). -->
<!ENTITY dhsection "<manvolnum>1</manvolnum>">
<!ENTITY dhemail "<email>stefano.melchior@openlabs.it</email>">
<!ENTITY dhusername "Stefano Melchior">
<!ENTITY dhucpackage "<refentrytitle>HUMFSIFY</refentrytitle>">
<!ENTITY dhpackage "humfsify">
<!ENTITY debian "<productname>Debian GNU/Linux</productname>">
<!ENTITY gnu "<acronym>GNU</acronym>">
]>
<refentry>
<refentryinfo>
<address>
&dhemail;
</address>
<author>
&dhfirstname;
&dhsurname;
</author>
<copyright>
<year>2006</year>
<holder>&dhusername;</holder>
</copyright>
&dhdate;
</refentryinfo>
<refmeta>
&dhucpackage;
&dhsection;
</refmeta>
<refnamediv>
<refname>&dhpackage;</refname>
<refpurpose>convert a directory to the format needed by the UML
humfs file system</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&dhpackage;</command>
<arg>user</arg>
<arg>group</arg>
<arg>size</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>This manual page documents briefly the
<command>&dhpackage;</command> command.</para>
<para>This manual page was written for the &debian; distribution
because the original program does not have a manual page.
Instead, it has documentation in HTML format; see below.</para>
<para><command>&dhpackage;</command> is a Perl script necessary to
convert a directory to a format expected by the UML humfs file system.
</para>
</refsect1>
<refsect1>
<title>HISTORY</title>
<para>UMLFS was born with the idea to substitute the Hostfs
implementation with a proper one for the UML purpose: when you
manage files with Hostfs within UML you need to work with
two different permission layers (the Host one and the UML one),
which have different ideas of ownerships.</para>
<para>This becomes evident when you need to
create a file as a non-root user on UML: you first need to interact
with the UML file system implementation, and then with the host side.</para>
<para>The result of a file creation on a mounted hostfs file system
is not what you expected: you can see that the file permissions refer to
the Host side user rather than the UML creator.</para>
<para>The Host side user is to be intended as the UML instance
launcher, meanwhile the UML side user is the one you used to log in
the UML instance.</para>
<para>You can encounter a more-critical problem when creating a
device node, operation that usually requires root privileges: you
used a common user to launch the UML and, since the operation is
done on the Host, it fails, even if you logged in as root.</para>
<para>Thus you need a set of tools which requires to bypass the
Hostfs permission checks on the Host side: this is done by
separating the file permissions and the ownership from the host's
files. This is the concept behind the HumFs and its &dhpackage;
implementation.</para>
</refsect1>
<refsect1>
<title>ARGUMENTS</title>
<variablelist>
<varlistentry>
<term><option>user</option></term>
<listitem>
<para>This is the user that needs to 'convert' a directory to the UML
file system to use UML. This is the host user who
will be using this filesystem from within UML. It
may be specified as either a user name or a numeric
user id.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>group</option></term>
<listitem>
<para>This is the group which your UML user belongs to.
This may be either a group name or a numeric group id</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>size</option></term>
<listitem>
<para>This is the size of the file system as seen within the
UML instance. It must be expressed in Gigabytes ("G"),
Megabytes ("M"), or KiloBytes ("K").</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>EXAMPLES</title>
<para>Create a directory on the host and mount it with &dhpackage;</para>
<para>host% <command>mkdir your-humfs-dir</command></para>
<para>host% <command>cd humfs-dir</command></para>
<para>Within this directory create a new one where you would like to have
a UML-like hierarchy, i.e. you can loop-mount an UML rootfs</para>
<para>host% <command>mkdir dir-to-be-humsified</command></para>
<para>host# <command>mount -o loop rootfs /mnt</command></para>
<para>host% <command>cp -a /mnt dir-to-be-humsified/data</command></para>
<para>host# <command>&dhpackage; user group 512M</command></para>
<para>Then verify it on UML and mount the humfsified
directory:</para>
<para>UML# <command>mount none /your-uml-host -t humfs -o
.../dir-to-be-humfsified</command></para>
<para>where '/your-uml-mount-point' is the mount point on UML for
the humfsified file system, and .../dir-to-be-humfsified is
the humfsified directory in the example above. The '-t' mount option
specifies that the file system is to be mounted as 'humfs'.</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>The <ulink
url="http://user-mode-linux.sourceforge.net/new/hostfs.html"
type=alternate>HostFs</ulink> usage explanation within the
User-Mode-Linux Web Site</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>&dhpackage; was written by Jeff Dike.</para>
<para>This manual page was written by &dhusername; &dhemail; for
the &debian; system, based on material in the Official User Mode
Linux Web Site.</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!-- Process this file with docbook-to-man to generate an nroff manual
page: `docbook-to-man manpage.sgml > manpage.1'. You may view
the manual page with: `docbook-to-man manpage.sgml | nroff -man |
less'. A typical entry in a Makefile or Makefile.am is:
manpage.1: manpage.sgml
docbook-to-man $< > $@
-->
<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!ENTITY dhfirstname "<firstname>Stefano</firstname>">
<!ENTITY dhsurname "<surname>Melchior</surname>">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY dhdate "<date>November 24, 2006</date>">
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
allowed: see man(7), man(1). -->
<!ENTITY dhsection "<manvolnum>1</manvolnum>">
<!ENTITY dhemail "<email>stefano.melchior@openlabs.it</email>">
<!ENTITY dhusername "Stefano Melchior">
<!ENTITY dhucpackage "<refentrytitle>UML_MOUNT</refentrytitle>">
<!ENTITY dhpackage "uml_mount">
<!ENTITY debian "<productname>Debian GNU/Linux</productname>">
<!ENTITY gnu "<acronym>GNU</acronym>">
]>
<refentry>
<refentryinfo>
<address>
&dhemail;
</address>
<author>
&dhfirstname;
&dhsurname;
</author>
<copyright>
<year>2006</year>
<holder>&dhusername;</holder>
</copyright>
&dhdate;
</refentryinfo>
<refmeta>
&dhucpackage;
&dhsection;
</refmeta>
<refnamediv>
<refname>&dhpackage;</refname>
<refpurpose>allows to mount UMLFS file system using the fuse libraries</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&dhpackage;</command>
<arg>mount-point</arg>
<arg>options</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>This manual page documents briefly the
<command>&dhpackage;</command> command.</para>
<para>This command uses the FUSE (File system in USErspace)
libraries and invokes the FUSE_MOUNT function which expects a mount
point and some parameters as arguments.</para>
<para>This manual page was written for the &debian; distribution
because the original program does not have a manual page. For a
practical example, please refer to the link below.</para>
<para><command>&dhpackage;</command> is used to mount UMLFS file
system.</para>
</refsect1>
<refsect1>
<title>ARGUMENTS</title>
<variablelist>
<varlistentry>
<term><option>mount-point</option></term>
<listitem>
<para>This is the mount point where to mount the UMLFS file system
with.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>[options]</option></term>
<listitem>
<para>These are the other options accepted by the 'fuse_mount'
function.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>General options:</title>
<variablelist>
<varlistentry>
<term><option>-h</option></term>
<listitem>
<para>The "-h" option prints the help.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-V</option></term>
<listitem>
<para>The "-V" option prints the version.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o opt,[opt...]</option></term>
<listitem>
<para>The "-o" option allows to provide further mount (only,
not un-mount) option(s) to the command line.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>FUSE options:</title>
<variablelist>
<varlistentry>
<term><option>-d -o debug</option></term>
<listitem>
<para>The "-d" option enable the debug output. It implies
"-f".</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option></term>
<listitem>
<para>The "-f" option foregrounds the operation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option></term>
<listitem>
<para>The "-s" options disable multi-threaded operation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o allow_other</option></term>
<listitem>
<para>The "-o allow_other" option allows access to other users.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o allow_root</option></term>
<listitem>
<para>The "-o allow_root" option allows access to root.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o nonempty</option></term>
<listitem>
<para>The "-o nonempty" option allows mounts over non-empty
file/dir.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o default_permissions</option></term>
<listitem>
<para>The "-o default_permissions" enables permission checking
by kernel.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o fsname=NAME</option></term>
<listitem>
<para>The "-o fsname=NAME" option sets file system name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o large_read</option></term>
<listitem>
<para>The "-o large_read" option issues large read requests
(2.4 only).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o max_read=N</option></term>
<listitem>
<para>The "-o max_read=N" option sets the maximum size of read
requests.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>The <ulink
url="http://user-mode-linux.sourceforge.net/new/hostfs.html"
type=alternate>HostFs</ulink> usage explanation within the
User-Mode-Linux Web Site</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>&dhpackage; was written by Jeff Dikes.</para>
<para>This manual page was written by &dhusername; &dhemail; for
the &debian; system, based on material in the Official User Mode
Linux Web Site.</para>
</refsect1>
</refentry>
<!--
<varlistentry>
<term><option>-l</option></term>
<para>If the filesystem handles big reads more efficiently,
than 64k reads may come out better. This can be controlled
with the "-l" option</para>
<term><option>-p</option></term>
<para>The "-p" option will turn on permission checking by the
kernel based on file owner/group and permission bits, this is
normally disabled.</para>
<term><option>-u</option></term>
<para>The "-u" option can be used to un-mount a UMLFS file
system.</para>
<term><option>-x</option></term>
<para>The "-x" option to fusermount will allow anyone to have
access to the files.</para>
<term><option>-z</option></term>
<para>The "-z" option can only be used with "-u" when you need
to unmount a file system in fuse-like "lazy mode".</para>
-->
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment