Project

General

Profile

Bug #10725

missing man pages for ceph-create-keys, ceph-disk-*

Added by Ken Dreyer about 5 years ago. Updated over 4 years ago.

Status:
Resolved
Priority:
High
Assignee:
Category:
documentation
Target version:
-
% Done:

30%

Source:
other
Tags:
Backport:
hammer
Regression:
No
Severity:
3 - minor
Reviewed:
Affected Versions:
ceph-qa-suite:
Pull request ID:
Crash signature:

Description

The following four commands lack man pages:
/usr/sbin/ceph-create-keys
/usr/sbin/ceph-disk-udev
/usr/sbin/ceph-disk-activate
/usr/sbin/ceph-disk-prepare


Related issues

Copied to Ceph - Backport #11862: missing man pages for ceph-create-keys, ceph-disk-* Resolved 02/03/2015

Associated revisions

Revision 27cee2f1 (diff)
Added by Kefu Chai almost 5 years ago

doc: add ceph-create-keys.8

Fixes: #10725
Signed-off-by: Kefu Chai <>

Revision a97566ad (diff)
Added by Kefu Chai almost 5 years ago

doc: add ceph-create-keys.rst to dist tarball

Fixes: #10725
Signed-off-by: Kefu Chai <>

Revision f04c8829 (diff)
Added by Kefu Chai almost 5 years ago

man/create-create-keys: minor fixes

to address the comments on https://github.com/ceph/ceph/pull/4846

Fixes: #10725
Signed-off-by: Kefu Chai <>

Revision 19305b89 (diff)
Added by Kefu Chai almost 5 years ago

doc: add ceph-create-keys.8

Fixes: #10725
Signed-off-by: Kefu Chai <>
(cherry picked from commit 27cee2f1f46a9f47cda9dfeb56ff1259e982960c)

Conflicts:
doc/man/8/ceph-create-keys.rst
Includes fixes from https://github.com/ceph/ceph/pull/4855

History

#1 Updated by Samuel Just about 5 years ago

  • Priority changed from Normal to High

#2 Updated by Loic Dachary about 5 years ago

see also #2975

#3 Updated by Ken Dreyer almost 5 years ago

  • Backport changed from firefly to firefly,hammer

#4 Updated by Kefu Chai almost 5 years ago

  • Assignee set to Kefu Chai

#5 Updated by Kefu Chai almost 5 years ago

  • Status changed from New to In Progress
  • % Done changed from 0 to 20

Ken, i am not sure we should document the ceph-disk-{udev,activate,prepare}. they are called by our udev rules. so, IMHO, they are just internals of ceph, instead of the interface to our user. what do you think?

#7 Updated by Ken Dreyer almost 5 years ago

Kefu Chai wrote:

Ken, i am not sure we should document the ceph-disk-{udev,activate,prepare}. they are called by our udev rules. so, IMHO, they are just internals of ceph, instead of the interface to our user. what do you think?

Would it make sense to move them out of the user's $PATH, in that case, so users do not try to run them?

For example, ceph-osd-prestart.sh is in /usr/libexec/ceph. Should we put these utilities there as well?

#8 Updated by Kefu Chai almost 5 years ago

Ken Dreyer wrote:

Kefu Chai wrote:

Ken, i am not sure we should document the ceph-disk-{udev,activate,prepare}. they are called by our udev rules. so, IMHO, they are just internals of ceph, instead of the interface to our user. what do you think?

Would it make sense to move them out of the user's $PATH, in that case, so users do not try to run them?

For example, ceph-osd-prestart.sh is in /usr/libexec/ceph. Should we put these utilities there as well?

maybe we should put them into /usr/share/ceph ? since they are architecture independent files. see http://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA .

and /usr/libexec is for architecture dependent binaries, see https://www.linuxbase.org/betaspecs/fhs/fhs.html#usrlibexec

#9 Updated by Ken Dreyer almost 5 years ago

The FHS reference says /usr/share is for "data files", which I took to mean pictures, etc. However I see that some programs do put scripts into /usr/share (for example, the "createrepo" program does this.)

I've asked for clarification on fedora-devel. https://lists.fedoraproject.org/pipermail/devel/2015-April/210080.html

#10 Updated by Kefu Chai almost 5 years ago

Ken, i think the crux is architecture dependent versus architecture independent. the stuff in /usr/share is something that can be shared among different architectures, e,g, x86 and amd64. so from the maintainer's POV, if a upstream package supports multi-arch, he/she might want to consider separating the package into smaller pieces. one of the criteria might be architecture dependent or independent.

and the files (including scripts) from the data package should go to /usr/share. and the binary will go to their own places, see https://wiki.debian.org/Multiarch/LibraryPathOverview . sorry, Ken. i am more familiar with deb packaging than rpm packaging. so i am using the examples from the debian/ubuntu world. but i guess the idea also applies to rpm packaging.

let's look at some real-world examples,

  • https://packages.debian.org/sid/all/debootstrap/filelist : (debootstrap is a tool to create a Debian base system, so one is able to chroot into it. we can tell that it put shell scripts into /usr/share)
    $ head /usr/share/debootstrap/scripts/sid
    mirror_style release
    download_style apt
    finddebs_style from-indices
    variants - buildd fakechroot minbase scratchbox
    keyring /usr/share/keyrings/debian-archive-keyring.gpg
    
    if doing_variant fakechroot; then
            test "$FAKECHROOT" = "true" || error 1 FAKECHROOTREQ "This variant requires fakechroot environment to be started" 
    fi
    
  • https://packages.debian.org/sid/all/quilt/filelist? quilt is a tool to manage a set of patches.
    $ file /usr/share/quilt/delete
    /usr/share/quilt/delete: Bourne-Again shell script, ASCII text executable
    

#11 Updated by Kefu Chai almost 5 years ago

  • Status changed from In Progress to Resolved
  • Backport changed from firefly,hammer to hammer
  • Regression set to No

Ken, i created a new ticket (#11623) to address the FHS compliance issue, and consider this ticket done.

#12 Updated by Nathan Cutler almost 5 years ago

  • Status changed from Resolved to Pending Backport
  • % Done changed from 20 to 90

#13 Updated by Nathan Cutler almost 5 years ago

  • % Done changed from 90 to 30

Now I see this is for four manpages, not just one.

#14 Updated by Nathan Cutler almost 5 years ago

  • Description updated (diff)

#15 Updated by Nathan Cutler almost 5 years ago

  • Description updated (diff)

#16 Updated by Kefu Chai over 4 years ago

  • Status changed from Pending Backport to Resolved

backport merged, consider it done.

Also available in: Atom PDF