Bug 158483 - hal documentation ranges between incorrect and non-existent
Summary: hal documentation ranges between incorrect and non-existent
Keywords:
Status: CLOSED RAWHIDE
Alias: None
Product: Fedora
Classification: Fedora
Component: hal
Version: rawhide
Hardware: All
OS: Linux
medium
medium
Target Milestone: ---
Assignee: David Zeuthen
QA Contact:
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2005-05-22 21:04 UTC by Michal Jaegermann
Modified: 2013-03-06 03:43 UTC (History)
1 user (show)

Fixed In Version: 0.5.2-2
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2005-05-24 18:15:35 UTC
Type: ---
Embargoed:


Attachments (Terms of Use)
Proposed changes (4.14 KB, text/plain)
2005-05-22 22:20 UTC, David Zeuthen
no flags Details

Description Michal Jaegermann 2005-05-22 21:04:16 UTC
Description of problem:

Typing 'rpm -qd hal' one gets 

/usr/share/doc/hal-0.5.2/conf/storage-non-fixed.fdi
/usr/share/doc/hal-0.5.2/conf/storage-policy-examples.fdi
/usr/share/doc/hal-0.5.2/conf/storage-skip-all.fdi
/usr/share/man/man8/fstab-sync.8.gz

and that is it.  This manpage claims 
"By default, the /usr/share/hal/fdi/90defaultpolicy/storage-policy.fdi
file specifies the policy".  Such file does not exist.  This is followed
by "Device information files are processed for every hal device object in
the /usr/share/hal/fdi/ directory in alphabetical order including directories"
and judging from observed results this is really not the case either.

There are files in 'information', 'policy' and 'preprobe' subdirectories but
how this is processed and which formats are valid is also not that clear.
One may try to guess from three examples in /usr/share/doc/hal-0.5.2/conf/
but hard to say if guesses are valid and if one does modifications where
they should be located and why.

Version-Release number of selected component (if applicable):
hal-0.5.2-1

Comment 1 David Zeuthen 2005-05-22 21:24:10 UTC
I think that replacing

 /usr/share/hal/fdi/90defaultpolicy/storage-policy.fdi

with

 /usr/share/hal/fdi/policy/10osvendor/10-storage-policy.fdi

would fix the problem. I'll make a patch for that to go out with the next
release. I do agree with the sentiment that this is too complex to configure
(and there are not enough docs), we plan on changing that for FC5 (our original
target was FC4 but things got in the way).




Comment 2 David Zeuthen 2005-05-22 22:20:05 UTC
Created attachment 114695 [details]
Proposed changes

Here's the suggested change (please ignore that /usr/local is being as
--prefix, that will change when I run it through Rawhide). Michal, does this
work better for you?

Comment 3 David Zeuthen 2005-05-22 22:23:30 UTC
(btw, you might want to use less(1) to read it instead of using the browser)

Comment 4 Michal Jaegermann 2005-05-22 22:51:34 UTC
Something is not right in locations from an attachment to comment #2.

By default, the 
.B /usr/local/share/hal/fdi/policy/10osvendor/10-storage-policy.fdi
file specifies the policy

This cannot be correct with this "local" for sure.

... Instead, system- or site-specific rules can be put in
the
.B /usr/local/etc/hal/fdi/policy/
directory as separate files.

Indeed "/usr/local/etc/hal/fdi/policy/"?  If yes, then maybe the package
should own this directory?  My guess was that this actually will be
"/usr/share/hal/fdi/policy/20thirdparty" but this is only a guess.

And that location:

A number of sample policy files for various uses should
be available in the 
.B /usr/local/share/doc/hal-0.5.2/conf
directory.

is definitely not right too.  Effects of an automatic edit while
compiling a test package?

If you will hardwire a version into that document then you need to
make sure that changes will be correctly reflected.  Not difficult
but it needs some attention.


Comment 5 David Zeuthen 2005-05-22 22:55:44 UTC
Oh, what I meant in comment 2 was that you should disregard /usr/local. So, in
the final version it will be

 /usr/local/etc   -> /etc
 /usr/local/share -> /usr/share

etc. This is because fstab-sync.8 is generated from fstab-sync.8.in which
substitutes $prefix, $datadir, $localstatedir, $sysconfdir as appropriate.

Comment 6 Michal Jaegermann 2005-05-23 03:59:14 UTC
> /usr/local/etc   -> /etc

There are files in subdirectories of /usr/share/hal/fdi/{policy,information},
at least currently, and none below /etc/hal/fdi/.  The best guess is
that "local" policies go into /usr/share/hal/fdi/policy/20thirdparty/.
In an absence of an updated documentation it is really hard to know if
this guess can be possibly right.  An order in which files from
/usr/share/hal/fdi/ and /etc/hal/fdi/ will be used is also far from clear.

What for are files in /usr/share/hal/fdi/information/ is a bit of mystery;
and the same goes for a 'preprobe' subdirectories.

Comment 7 Michal Jaegermann 2005-05-23 20:46:03 UTC
Experiments while running more "hal friendly" kernel, i.e. 2.6.11-1.1340_FC4,
indicate that adding policy files to /usr/share/hal/fdi/policy/20thirdparty/
indeed has at least some effects.  It would be nice to know which locations are
"correct" and in which order they are processed.

Comment 8 David Zeuthen 2005-05-24 18:15:35 UTC
Quoting from the fstab-sync man page included in release 0.5.2-2 

 "By  default,  the  /usr/share/hal/fdi/policy/10osvendor/10-storage-pol-
 icy.fdi file specifies the policy - this file should never be edited by
 the system administrator as it might get updated by the OS  vendor  for
 security updates. Instead, system- or site-specific rules can be put in
 the /etc/hal/fdi/policy/ directory as separate files."

you're supposed to put these in /etc/hal/fdi/policy. 

I think that it is implied here that system- and site-specific rules are
processed after the ones supplied with the OS.



Note You need to log in before you can comment on or make changes to this bug.