Add a new HAL FAQ which explains how to work with the Freedesktop Hardware

Abstraction Layer (i.e. volume auto-mounting, troubleshooting, etc.).  Link
this new FAQ into the navibar, and replace our old auto-mounting question
with a link to this new FAQ.

While in our general FAQ, clean up the question on gnome-keyring.

Reviewed by:	mezz and ahze
This commit is contained in:
Joe Marcus Clarke 2008-03-30 18:35:28 +00:00
parent 394603450d
commit 2c63f2088e
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/www/; revision=31778
4 changed files with 341 additions and 96 deletions

View file

@ -1,4 +1,4 @@
# $FreeBSD: www/en/gnome/docs/Makefile,v 1.24 2007/10/25 16:56:36 marcus Exp $
# $FreeBSD: www/en/gnome/docs/Makefile,v 1.25 2008/03/24 05:14:07 marcus Exp $
.if exists(../Makefile.conf)
.include "../Makefile.conf"
@ -24,5 +24,6 @@ DOCS+= bugging.sgml
DOCS+= volunteer.sgml
DOCS+= develfaq.sgml
DOCS+= example-Makefile.sgml
DOCS+= halfaq.sgml
.include "${WEB_PREFIX}/share/mk/web.site.mk"

View file

@ -1,6 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
<!ENTITY base CDATA "../..">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/faq2.sgml,v 1.135 2008/03/29 22:55:03 marcus Exp $">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/faq2.sgml,v 1.136 2008/03/29 23:59:54 marcus Exp $">
<!ENTITY title "FreeBSD GNOME Project: GNOME &gnomever; FAQ">
<!ENTITY email "freebsd-gnome">
<!ENTITY % navinclude.gnome "INCLUDE">
@ -672,7 +672,8 @@ device atapicam
</pre>
<p>Finally, if you are running GNOME 2.16 or later, you
must have <a href="#q19">HAL running</a>, or you will
must have <a href="&base;/gnome/docs/halfaq.html">
HAL running</a>, or you will
only be able to burn to an ISO image file.</p>
<p>To figure out which CD/DVD drive you will be using, run the
@ -781,95 +782,10 @@ Type=Application
<p><b>How do I mount my removable media in
Nautilus?</b></p>
<!-- A19 -->
<p>As of GNOME 2.16, FreeBSD supports <a
href="http://www.freedesktop.org/wiki/Software_2fhal">HAL</a>,
a component from the <a
href="http://www.freedesktop.org/wiki/">FreeDesktop</a>
project. HAL provides seamless hardware integration with
modern UNIX desktop environment such as GNOME. This
means auto-mounting of hardware is as easy as starting a
few daemons at boot time, and making sure
<tt>sysutils/gnome-volume-manager</tt> is installed. If
you installed <tt>x11/gnome2</tt> you already have
<tt>gnome-volume-manager</tt> installed.</p>
<p>The daemons that must be started prior to logging into
GNOME are, <b>dbus</b> and <b>hald</b> in that order. To do
this, add the following to <tt>/etc/rc.conf</tt>, and
reboot:</p>
<pre>
dbus_enable="YES"
hald_enable="YES"
</pre>
<p>These services are automatically started if <a
href="#full-gnome">all GNOME features</a> are enabled.</p>
<p><b>Note:</b> your user account must be a member of the
<em>operator</em> group for automatic mounting to work.
To add yourself to the operator group, execute the
following command as root:</p>
<pre>
# pw group mod operator -m &lt;username&gt;
</pre>
<p>For example, to add the user <em>marcus</em> to the
operator group, use the following command:</p>
<pre>
# pw group mod operator -m marcus
</pre>
<p>That's it! You should now see your USB key drives and
CD-ROMs magically appear on your desktop. However, if
you are having problems with auto-mounting or HAL in
general, you should collect the following (in addition
to other <a
href="&base;/gnome/docs/bugging.html">troubleshooting</a>
information):</p>
<ol>
<li>Output of <tt>lshal</tt></li>
<li>Output of <tt>sysctl -b kern.geom.conftxt</tt></li>
<li>Contents of <tt>/etc/fstab</tt></li>
<li>Output of <tt>mount</tt></li>
<li>Full <tt>dmesg</tt> output</li>
<li>Stop hald, then run it manually using
<tt>/usr/local/sbin/hald --daemon=no --verbose=yes</tt>
and provide the output</li>
<li>If using GNOME, and a volume is not mounting
properly, include the output of <tt>gnome-mount --block
--no-ui --verbose --hal-udi &lt;Device UDI&gt;</tt>
(&lt;Device UDI&gt; is the Unique Device Identifier
obtained from the output of <tt>lshal</tt> for the
device that is not mounting properly)</li>
</ol>
<p>You can also mount fixed storage media such as FAT or
NTFS partitions (maybe you are dual booting) using HAL.
For this to work you must must edit
<tt>/usr/local/etc/PolicyKit/privilege.d/hal-storage-fixed-mount.privilege</tt>
and add your username to the <em>Allow</em> list:</p>
<pre>
[Policy]
Allow=uid:&lt;username&gt;
</pre>
<p>For example, to allow the user <em>marcus</em> to mount
fixed storage media, add the following to
<tt>hal-storage-fixed-mount.privilege</tt>:</p>
<pre>
[Policy]
Allow=uid:marcus
</pre>
<p>Gary Dunn also provides a <a
href="http://www.aloha.com/~knowtree/howto/gnomeSMBmount.html">
very detailed how-to</a> for user-mounting SMB volumes.</p>
<p>As of GNOME 2.12, the way auto-mounting works has
changed substantially. The full details are spelled out
in our <a href="&base;/gnome/docs/halfaq.html">HAL
FAQ</a>.</p>
</li>
<!-- Q20 -->
<li style="padding-bottom: 0.5em"><a name="q20"></a>
@ -1159,9 +1075,10 @@ gtk-key-theme-name = "Emacs"
<p><b>Why do I need confirm access to my keyring
every time Nautilus tries to open an external share?</b></p>
<!-- A27 -->
<p>You did not mount the <tt>procfs</tt> file system. Which is off
by default in recent releases of FreeBSD. Consider adding
the following line to your <tt>/etc/fstab</tt> file:</p>
<p>You did not mount the <tt>procfs</tt> file system.
Procfs is not mounted by default in recent releases of FreeBSD.
Consider adding the following line to your <tt>/etc/fstab</tt>
file:</p>
<pre>
proc /proc procfs rw 0 0

326
en/gnome/docs/halfaq.sgml Normal file
View file

@ -0,0 +1,326 @@
<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
<!ENTITY base CDATA "../../">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "FreeBSD GNOME Project: Hardware Abstraction Layer (HAL) FAQ">
<!ENTITY % navinclude.gnome "INCLUDE">
]>
<html>
&header;
<em>"You're in luck, Dave. Turns out I CAN let you do that."</em>
<h2>Contents</h2>
<ol>
<li> <a href="#q1">How do I use hal on FreeBSD?</a></li>
<li> <a href="#q2">How do I prevent hal from probing a
device?</a></li>
<li> <a href="#q3">How do I mount media using hal?</a></li>
<li> <a href="#q4">How do I troubleshoot problems with
hal?</a></li>
</ol>
<h2>Full Text</h2>
<ol>
<!-- Q1 -->
<li style="padding-bottom: 0.5em"><a name="q1"></a>
<p><b>How do I use hal on FreeBSD?</b></p>
<!-- A1 -->
<p>The only thing you need to do in order to use hal is to
start the HAL daemon, <tt>hald</tt>. To do this, add the
following to <tt>/etc/rc.conf</tt>:</p>
<pre>
dbus_enable="YES"
hald_enable="YES"
</pre>
<p><b>NOTE:</b> GNOME users can opt to add
<tt>gnome_enable="YES"</tt> to <tt>/etc/rc.conf</tt> instead
of the lines above. This will start all GNOME-related
services including Avahi and GDM.</p>
<p>Then you must either reboot, or run:</p>
<pre>
# /usr/local/etc/rc.d/dbus start
# /usr/local/etc/rc.d/hald start
</pre>
<p>Once <tt>hald</tt> is running, hal-aware application will
automatically start to communicate with it over D-BUS. To
confirm that hald is running correctly, execute
<tt>lshal</tt> from the command line. This provides you
with a list of devices attached to the system. <b>Note:</b>
<tt>lshal</tt> must be run from within a D-BUS enabled
session (e.g. GNOME or KDE).</p>
</li>
<!-- Q2 -->
<li style="padding-bottom: 0.5em"><a name="q2"></a>
<p><b>How do I prevent hal from probing a device?</b></p>
<!-- A2 -->
<p>Sometimes, when hal probes a device, this can cause the
system to hang, panic, or otherwise behave badly. By
using device information files (.fdi files), you can tell
hal to ignore such devices. These files are in XML
format, and should be created under
<tt>/usr/local/share/hal/fdi/preprobe/20thirdparty</tt>.
For example, to tell hal to ignore USB uhci controller 0,
create a file
<tt>/usr/local/share/hal/fdi/preprobe/20thirdparty/10-ignore-uhci0.fdi</tt>
with the following contents:</p>
<pre>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;deviceinfo version="0.2"&gt;
&lt;device&gt;
&gt;match key="freebsd.driver" string="uhci"&gt;
&lt;match key="freebsd.unit" int="0"&gt;
&lt;merge key="info.ignore" type="bool"&gt;true&lt;/merge&gt;
&lt;/match&gt;
&lt;/match&gt;
&lt;/device&gt;
&lt;/deviceinfo&gt;
</pre>
<p>Using this same technique, you can also merge (or change)
other hal device properties. Use the <tt>lshal</tt>
command to get a list of all available device properties.
You can also look at the system-provided .fdi files under
<tt>/usr/local/share/hal/fdi/preprobe/10osvendor</tt> for
more examples.</p>
<p>All .fdi files in this <tt>20thirdparty</tt> directory
are loaded in alphabetical order, so name your files
accordingly. The convention is to start the files with a
number. The lower the number, the earlier the file will
be loaded.</p>
</li>
<!-- Q3 -->
<li style="padding-bottom: 0.5em"><a name="q3"></a>
<p><b>How do I mount media using hal?</b></p>
<!-- A3 -->
<p>Understand that having hal alone does not mean media will
get automatically mounted. Hal simply serves as a broker for
requests to mount certain devices. Some other software needs
to make this request. As of GNOME 2.22, this is Nautilus.
KDE and XFCE have their own components to mount hal
volumes.</p>
<p><b>NOTE:</b> Volumes that you wish to manage using
hal should <em>NOT</em> be listed in <tt>/etc/fstab</tt>.
This is especially true for CD devices and floppy disk
devices.</p>
<p>If you are a GNOME user be aware that prior to GNOME
2.22, <tt>gnome-volume-manager</tt> was responsible for
asking hal to mount volumes. Since this responsibility
has moved to Nautilus, it is vital to change
<tt>gnome-volume-manager's</tt> configuration so that it
will no longer attempt to mount volumes.</p>
<p><b>NOTE:</b> This step is only required if you are a
GNOME user that upgraded to 2.22 from a previous version
of GNOME. If this is not the case, then skip to Step
1.</p>
<p><b><font color="#FF0000">CAVEAT:</font></b> If you are
using glabel (GEOM labels), volume labels <em>MUST NOT</em>
contain spaces. This will break hal's volume parsing
code, and could lead to crashes.</p>
<p>From within your GNOME session, run the following
commands:</p>
<pre>
% gconftool-2 -s --type bool /desktop/gnome/volume_manager/automount_drives false
% gconftool-2 -s --type bool /desktop/gnome/volume_manager/automount_media false
% gconftool-2 -s --type bool /desktop/gnome/volume_manager/autobrowse false
% gconftool-2 -s --type bool /desktop/gnome/volume_manager/autoplay_cda false
% gconftool-2 -s --type bool /desktop/gnome/volume_manager/autoplay_dvd false
% gconftool-2 -s --type bool /desktop/gnome/volume_manager/autoplay_vcd false
% gconftool-2 -s --type bool /desktop/gnome/volume_manager/autoprinter false
</pre>
<p>Then restart GNOME.</p>
<p><b>Step 1:</b> All users MUST have <tt>procfs</tt> mounted
on <tt>/proc</tt>. Hal uses an application called PolicyKit
to authorize users to perform mount tasks, and PolicyKit
relies heavily on <tt>/proc</tt> entries. If <tt>/proc</tt>
is not mounted, volume mounting will not work. To mount
<tt>/proc</tt>, add the following to
<tt>/etc/fstab</tt>:</p>
<pre>
proc /proc procfs rw 0 0
</pre>
<p>Then run the following command:</p>
<pre>
# mount /proc
</pre>
<p><b>Step 2:</b> In order to mount volumes using hal, you
must be authorized. This authorization is carried out by
ConsoleKit and PolicyKit. If you are a GNOME user, and you
use GDM to login to GNOME, then you do not need to make any
additional configuration changes in order to mount removable
media. If you are not a GNOME user, or you start GNOME
without using GDM, then you will need to edit
<tt>/usr/local/etc/PolicyKit/PolicyKit.conf</tt>, and add
the <tt>org.freedesktop.hal.storage.mount-removable</tt>
action to your username. For example, if your username is
"marcus," you would add the following lines:</p>
<pre>
&lt;match action="org.freedesktop.hal.storage.mount-removable"&gt;
&lt;match user="marcus"&gt;
&lt;return result="yes"/&gt;
&lt;/match&gt;
&lt;/match&gt;
</pre>
<p><b>NOTE:</b> All config lines in this file <em>MUST</em> be
between the opening and closing <tt>&lt;config&gt;</tt>
tags:</p>
<pre>
&lt;config version="0.1"&gt;
&lt;!-- New configuration lines go here. --&gt;
&lt;/config&gt;
</pre>
<p>If you use GDM to login to GNOME, GDM will add a ConsoleKit
record for the session. If this session is active, then you
will be allowed to mount removable media without any
additional PolicyKit configuration. You can confirm if
ConsoleKit is working correctly by running the command,
<tt>ck-list-sessions</tt>. The <tt>active</tt> property must be
<tt>TRUE</tt> for auto-mounting to work.</p>
<p>By default, PolicyKit allows root to do everything, and all
users in the "wheel" group are allowed to authenticate for
admin tasks with their own password. To get a list of all
available actions, use the <tt>polkit-action(1)</tt>
command. For more information on the directives available
for <tt>PolicyKit.conf</tt>, see the
<tt>PolicyKit.conf(5)</tt> man page.</p>
<p><b>Step 4:</b> If you have fixed volumes you wish to mount,
you must also authorize yourself for the
<tt>org.freedesktop.hal.storage.mount-fixed</tt> action.
<b>Note:</b> This step is applicable to <em>ALL</em> users
including GNOME users using GDM. This is done just like the
removable action above. For example, to allow user "marcus"
to mount fixed volumes, add the following to
<tt>PolicyKit.conf</tt>:</p>
<pre>
&lt;match action="org.freedesktop.hal.storage.mount-fixed"&gt;
&lt;match user="marcus"&gt;
&lt;return result="yes"/&gt;
&lt;/match&gt;
&lt;/match&gt;
</pre>
<p><b>Step 5:</b> While not really part of hal volume
management, you may also be able to have volumes listed in
<tt>/etc/fstab</tt> automatically mounted. In GNOME, for
example, Nautilus will mount volumes listed in
<tt>/etc/fstab</tt> provided the following conditions are
met:</p>
<ol>
<li>The <tt>vfs.usermount</tt> sysctl is set to <tt>1</tt>.</li>
<li>The user requesting the mount owns the mount point.</li>
<li>The user requesting the mount is in the "operator"
group.</li>
</ol>
<p>for example, say you had the following listed in
<tt>/etc/fstab</tt>:</p>
<pre>
/dev/ad0s1 /win/c msdosfs rw,noauto 0
0
</pre>
<p>If you want Nautilus to mount this volume as the user
"marcus", do the following:</p>
<pre>
# sysctl vfs.usermount=1
# chown marcus /win/c
# pw group mod operator -m marcus
</pre>
<p>Then, when the user marcus logs into GNOME, <tt>/win/c</tt>
will be automatically mounted on the desktop.</p>
</li>
<!-- Q4 -->
<li style="padding-bottom: 0.5em"><a name="q4"></a>
<p><b>How do I troubleshoot problems with hal?</b></p>
<!-- A4 -->
<p>If you run into problems with hal, you must first collect
the <a
href="http://www.freebsd.org/gnome/docs/bugging.html">general
troubleshooting information</a> required by the FreeBSD
GNOME Team. You should also provide a detailed description
of the problem, and the output of <tt>lshal</tt> (assuming
<tt>hald</tt> is starting). Remember, <tt>lshal</tt>
<em>MUST</em> be run under a D-BUS enabled session. If you
cannot login to GNOME, KDE, or XFCE, run <tt>lshal</tt>
within <tt>dbus-launch</tt>:</p>
<pre>
% dbus-launch lshal
</pre>
<p>You should also provide the verbose output from
<tt>hald</tt> when it is performing the problematic task.
To get this, first stop <tt>hald</tt>, then run it
manually:</p>
<pre>
# /usr/local/etc/rc.d/hald stop
# /usr/local/sbin/hald --daemon=no --verbose=yes
</pre>
<p>Capture all of the output on the screen.</p>
<p>If you are having problems with hal detecting volumes or
media, or having problems with mounting volumes through hal,
obtain the following additional information. All of this
needs to be collected with the problem device attached to
the system.</p>
<ol>
<li>Output of <tt>sysctl -b kern.geom.conftxt</tt></li>
<li>Contents of <tt>/etc/fstab</tt></li>
<li>Output of the <tt>mount</tt> command</li>
<li>Full <tt>dmesg</tt> output</li>
<li>If using GNOME, and a volume is not mounting properly,
include the output of <tt>gnome-mount --block --no-ui
--verbose --hal-udi &lt;Device UDI&gt;</tt> (&lt;Device
UDI&gt; is the Unique Device Identifier obtained from the
output of <tt>lshal</tt> for the device that is not
mounting properly)</li>
</ol>
<p>Additionally, if you are a GDM user, please provide the
output of <tt>ck-list-sessions</tt>.</p>
<p>Finally, remember that if you are using glabel, and the
label has a space in the name that will break hal. Labels
must <em>NOT</em> contain spaces.</p>
</li>
</ol>
&footer;
</body>
</html>

View file

@ -1,4 +1,4 @@
<!-- $FreeBSD: www/share/sgml/navibar.ent,v 1.17 2008/03/24 05:15:41 marcus Exp $ -->
<!-- $FreeBSD: www/share/sgml/navibar.ent,v 1.18 2008/03/24 19:26:25 marcus Exp $ -->
<!ENTITY % navinclude.about "IGNORE">
<![ %navinclude.about; [
@ -125,6 +125,7 @@
<li><a href="&base;/gnome/index.html">Documentation</a>
<ul>
<li><a href="&base;/gnome/docs/faq2.html">FAQ</a></li>
<li><a href="&base;/gnome/docs/halfaq.html">HAL FAQ</a></li>
<li><a href="&base;/gnome/docs/faq222.html">2.20 to 2.22 Upgrade FAQ</a></li>
<li><a href="&base;/gnome/docs/develfaq.html">Development Branch FAQ</a></li>
<li><a href="&base;/gnome/docs/porting.html">Creating Ports</a></li>