#50322 CLI - dscontainer needs a man page
Opened 2 months ago by mreynolds. Modified 2 months ago

Issue Description

There was a new CLI tool added dscontainer, there should be a man page for this tool.


I thought that this would be generated automatically given it uses argparse as well? I wonder if I missed something ... (I'm on PTO this week, so if urgent, you may need to check it).

Metadata Update from @firstyear:
- Custom field origin adjusted to None
- Custom field reviewstatus adjusted to None

2 months ago

With @vashirov we were discussing we should move dscontainer from /usr/sbin to /var/libexec/dirsrv as this is not a user executable per-se as admins won't want to run this while doing common admin tasks. Then, I guess we wouldn't need a manpage and self-documentation would be enough, right?

Small correction: to/usr/libexec/dirsrv/.

I thought that this would be generated automatically given it uses argparse as well? I wonder if I missed something ... (I'm on PTO this week, so if urgent, you may need to check it).

I think you need to add dscontainer to the data files man page list (setup.py):

    data_files=[
        ('/usr/sbin/', [
            'cli/dsctl',
            'cli/dsconf',
            'cli/dscreate',
            'cli/dsidm',
            'cli/dscontainer',
            ]),
        ('/usr/share/man/man8', [
            'man/dsctl.8',
            'man/dsconf.8',
            'man/dscreate.8',
            'man/dsidm.8',
            ]),
    ],

But there is discussion now on whether we should move the tool and not do a man page. IHMO it "is" a user executable, so I feel it should have a man page, but I'll let @firstyear reply with this thoughts...

@vashirov Thanks for the correction.

@mreynolds dscontainer should be run only as an entry point of a container, AFAICT. It may be potentially dangerous (yes, I understand there is --runit, but still) when running on a standard server by deliberately writing into /data - by my experience this is a very common custom data folder out in the wild; in container this should be safe enough due to more-or-less clean environment.

One thing I don't like about /usr/libexec/dirsrv solution is it is basically saying "unsupported". But I don't know better place for the utility for now.

And having a manpage for it is ok with me any way, but we should make sure the manpage states evidently what the util would do to the machine.

In case of Fedora Packaging Guidelines the docs say:

Libexecdir (aka, /usr/libexec on Fedora systems) should only be used as the directory for executable programs that are designed primarily to be run by other programs rather than by users.

In our case the container binary (docker, podman) is the one executing dscontainer. (Of course you can ENTRYPOINT /bin/bash and run dscontainer manually, but that is definitely not a production way to use.)

Of course, it would be interesting to see what is the case with other distros' guidelines to find a common solution.

In case of Fedora Packaging Guidelines the docs say:

Libexecdir (aka, /usr/libexec on Fedora systems) should only be used as the directory for executable programs that are designed primarily to be run by other programs rather than by users.

In our case the container binary (docker, podman) is the one executing dscontainer. (Of course you can ENTRYPOINT /bin/bash and run dscontainer manually, but that is definitely not a production way to use.)
Of course, it would be interesting to see what is the case with other distros' guidelines to find a common solution.

Oh okay, I see. Disregard my comments.

It's not really meant for a person to run, so the move is okay by me.

Metadata Update from @mreynolds:
- Issue assigned to firstyear
- Issue set to the milestone: 1.4.0

2 months ago

Hmmmm I'm a bit concerned about the right way to do this. We currently use configure.ac for this for the selinux/systemd helpers for libexec, but setup.py in lib389 is not templated by --configure args, so platforms may not be able to adjust the location via --configure. Ideas on how to approach this?

Login to comment on this ticket.

Metadata