Include the man pages so they can be reached via the CLI

[Ghwomb]

I searched the roadmap and could not find anything about it. So I try a post here!

Can't you include the man pages with the releases? It would help a lot if I can just type man zfs, for example, to read the information about the commands. I know there is links to the man pages in the GUI, but why not include it in the release? I assume the size would not increase so much and the security implications is probably negative. That meaning it would help people keep their systems secure by providing up to date information.

 

[cyberjock]

No. The man pages were removed to fit on a 2gb USB stick. The expectation is that you'd use the gui. Using the CLI is not a good idea because you are bypassing the freenas config.

Sent from my DROID BIONIC using Tapatalk

 

[Ghwomb]

Thanks for the answer.

 

[Michael Wulff Nielsen]

I would love to have a script that downloaded the man pages. Many of us have larger at USB sticks and as an old unix guy I find the shell is faster for some things

Also since I access my freenas system via ssh when I am away from home, it would be great to have man pages. But I understand why they shouldn't be included in default install.

 

[cyberjock]

Not gonna happen as the partitions are too small to add the manpages. That's why they were removed to start with. :P

Sent from my DROID BIONIC using Tapatalk

 

[Michael Wulff Nielsen]

Right, I'll just fix it on my install... Thinking symlinks and putting the man pages on my pool *Rumages through the box of unix toools*

 

[N00b]

@Michael : I am a CPA with zero hours of computer training and I love the CLI :) I can imagine what a unix guy must be missing :-D

I installed the man pages in a jail, following the following steps:

1. Created a standard jail and checked version of FreeBSD in jail.
uname -a

Code:

FreeBSD fnmpgs 9.1-STABLE FreeBSD 9.1-STABLE #0 r+16f6355: Tue Aug 27 00:38:40 PDT 2013     root@build.ixsystems.com:/tank/home/jkh/src/freenas/os-base/amd64/tank/home/jkh/src/freenas/FreeBSD/src/sys/FREENAS.amd64  amd64

2. Downloaded source in the jail.

Code:

svn checkout svn://svn.freebsd.org/base/stable/9.1 /usr/src

3. Made manpages

Code:

cd /usr/src
make all-man maninstall

4. Created a custom alias/ function "man" that chroots into the jail directory tree and runs the "man" command. I use bash as my shell

Code:

man ()
{
    sudo chroot ${jailhome}/${jailname}/ man $@
}

where
$jailhome is path to jail dataset
$jailname is the name of the jail

5. Added chroot to "sudo all no password" list for convenience.

Code:

# chroot command added to enable easy reading of man pages.
user ALL=(ALL) NOPASSWD: /usr/sbin/chroot

BTW, the jail doesn't even have to be running. It is just where the associated programs and man-page sources are.

If there are more people who want this we can request a custom plugin that can install the corresponding manpages into a jail or dataset :) with just a few additions to standard aliases.

Edit: Updated original post sent while on vacation with specific commands after looking up the jail history.

 

[fracai]

It wouldn't even have to be a plugin; just a tarball of the manpages and the alias / shell script that looks wherever you unpack the archive.

 

[N00b]

It wouldn't even have to be a plugin; just a tarball of the manpages and the alias / shell script that looks wherever you unpack the archive.

I tried that earlier but I couldn't get it to work. I think you need installation of program "man" with it's dependencies. When I tried copying program 'man' from jail to /usr/bin on host or symlinking it in jail I got an error message associated with "groff" (printer ASCII not found or something if I remember correctly). Would be very happy to learn how to do it though if you can shed more light on the process. Right now my script (function to be precise) is very simple :

Code:

sudo chroot ${jailhome}/${jailname}/ man $@

and use it exactly in the normal way : man <command>

 

[fracai]

Here's a tarball of the man pages and required dependencies. Basically, I installed the man pages like you did in a jail, then made a clone of the jail dataset, set up the chroot alias to that clone, and started renaming and deleting files. When the output of man broke, I'd put back the file. I'm sure there are still a few that could be removed, but the majority of what's left is taken up by the actual man pages.

man.tbz2

Untare that and point the chroot alias to the directory.

 

[Dennis Jensen]

Hey fracai if you still have that man.tbz2 tarball I would really appreciate getting a current version -- I am just starting in FreeNAS and the only Man Pages I have found are the Man Pages for FreeBSD -- could really use a set of Man Pages for FreeNAS -- that is unless the FreeNAS Man Pages are simply the FreeBSD Man Pages

 

[Ghwomb]

-- could really use a set of Man Pages for FreeNAS -- that is unless the FreeNAS Man Pages are simply the FreeBSD Man Pages

I'm pretty sure the man pages for FreeBSD is the same. Just make sure you use the correct version: if you use FreeNAS 9.10 the correct man pages are for FreeBSD 10.3

 

[Dennis Jensen]

Okay ? I thought (or I was hoping) that since FreeNAS adds things to the build and uses a sort-of stripped down version of FreeBSD that it would have items within the build that are not covered by the FreeBSD Man Pages (because it does have things not covered by the FreeBSD Man Pages) and thus would have a sort of addendum to the FreeBSD Man Pages that covered the FreeNAS specific stuff

 

[Ghwomb]

Okay ? I thought (or I was hoping) that since FreeNAS adds things to the build and uses a sort-of stripped down version of FreeBSD that it would have items within the build that are not covered by the FreeBSD Man Pages (because it does have things not covered by the FreeBSD Man Pages) and thus would have a sort of addendum to the FreeBSD Man Pages that covered the FreeNAS specific stuff

I think the additions are the GUI-administration stuff, and the GUI is covered in the FreeNAS Handbook.
But I might be wrong. Which FreeNAS CLI-utilities is not covered by FreeBSD man pages?

 

[Dennis Jensen]

Okay you asked :) Now mind you I am not sure if these are FreeNAS specific all I know is that I cannot find them in the FreeBSD online Man pages (dang it removed my formatting)

Code:

gui-boot.tar/
    boot/
        boot0
        boot0iso
        cdboot
        defaults/loader.conf ..................... reference located
        device.hints
        grub/grub.cfg
        kernel/
            cyclic.ko
            dtmalloc.ko
            dtnfscl.ko
            dtnfsclient.ko
            dtrace_test.ko
            dtraceall.ko
            fasttrap.ko
            fbt.ko
            geom_ccd.ko
            geom_mountver.ko
            geom_shsec.ko
            geom_zero.ko
            ipmi_linux.ko
            kgssapi_krb5.kko
            kgssapi.ko
            krpc.ko
            libiconv.ko
            libmchain.ko
            linker.hints
            lockstat.ko
            nfs_common.ko
            nfsclient.ko
            nfslock.ko
            opensolaris.ko
            profile.ko
            prototype.ko
            sdt.ko
            smbfs.ko
            systrace_freebsd32.ko  (okay probably a bsd file but could not find it in the Man pages)
            systrace_linux32.ko
            systrace.ko
            t3_tom.ko
            t4_tom.ko
            t4fw_cfg.ko
            t5fw_cfg.ko
            toecore.ko
            uff.ko
        loader.help .................................... reference located
        loader.rc ........................................ reference located
        loader.rc.local
        mbr
        menu-commands.4th
        menu.rc
        modules/
            arcsas.ko
            geom_raid5.ko
            linker.hints
            vboxdrv.kko
            vboxnetadp.ko
            vboxnetflt.ko
        pmbr
        pmbr-datadisk
        screen.4th
        shortcuts.4th
        support.4th
        userboot.so
        zfs/zpool.cache
gut-install-environment.tar
    bin/
        [
        csh
    conf/default/etc/
        amd.map
        avatar.conf
        csh.cshrc
        csh.login
        csh.logout
        ddb.conf

-------< Okay that is as far as I have gotten in searching the FreeBSD Online Man Pages ... I still have quite a few more files I need to check but that should give an idea of the ones that I cannot find any documentation for. Now some of them appear to be related to things that are documented but if those things do not reference them I consider that to be questionable (and prefer to error on the side of caution) for example the amd.map seems to be related to (amd -- automatically mount file systems) but the documentation for amd does not specifically reference that file of explain it in any way leaving it a dangerous unknown and there are a few others like this in the above list -- however there are some where the file IS referenced within a different file's documentation and I at least know that it is related to the file and/or needed by that file

Note when I do get this documentation completed I plan to share it with the community as I have noticed that I am not the only one that is looking for a document like this.

 

[Ghwomb]

I guess I don't understand. I picked some random stuff from the list above and the loader stuff seems to be covered in loader.conf and loader; ddb is a part of the FreeBSD system see ddb(4) and ddb(8). But I guess that does not mean every .conf-file should have its own man page.

 

[Dennis Jensen]

Okay ?? First I apologize for "default/loader.conf ; loader.help; and loader.rc must have overlooked those some how -- however I did not say I could not find "ddb" what I cannot find is a reference for ddb.conf as neither ddb(4) nor ddb(8) make reference to this specific file and while I can assume (which is a bad thing to do) it is associated with either ddb(4) and/or ddb(8) I would much rather find verification what is and is not part of Oh and just to be clear I am not saying that every *.conf file should have its own Man Page but if the file is not referenced anywhere how do you know what it is and is not associated with specifically. For instance this ddb.conf might only be associated with ddb(8) and not with ddb(4) or vice-versa but there is no way to tell as it does not show up in the Files section of either -- granted ddb(8) does not even have a File section while ddb(4) does. Oh and in this vein the files associated with geom(8) and geom(4) are different and even with that there are a few geom_* files that are not referenced within geom(4) like the others seem to be and of course geom(8)'s format for the file names is totally different than what I have found so far within the build files

To be clear I am using the following URL

https://www.freebsd.org/cgi/man.cgi

Using the following criterion/parameters -- that is when the interface does not change them on me and I forget to double check

* Man [ All Sections ] [ FreeBSD 10.3-RELEASE and Ports ] [ default ] Architecture

Oh and thanks for taking the time to look at this it is appreciated

 

[fracai]

Hey fracai if you still have that man.tbz2 tarball I would really appreciate getting a current version -- I am just starting in FreeNAS and the only Man Pages I have found are the Man Pages for FreeBSD -- could really use a set of Man Pages for FreeNAS -- that is unless the FreeNAS Man Pages are simply the FreeBSD Man Pages

Now that FreeNAS base includes the man pages and jails will include pages for anything you install I haven't had a need to keep that tarball updated. Though it sounds like you're getting this sorted otherwise.

 

[Dennis Jensen]

Okay well thanks for replying -- will be trying to look into the source code for the files that I could not find on FreeBSD but once I get this spreadsheet completed -- ?? where would I post it for others to have access to it if they wanted it ??

 

[Ghwomb]

Oh and thanks for taking the time to look at this it is appreciated

Perhaps you should ask the FreeBSD Documentation Project, or check their archive about what you are searching for. Because I guess I just don't get it. The kernel modules seems to be covered in kldfind and deeper information about different modules is probably better to search for on google or the mailing list archives. I rarely edit .conf-files myself and the way I use them is to put the switches i use regurarly in them so I don't have to type them all the time. For example instead of using mount.nfs with a bunch of switches I just put it in my fstab. So I don't need a lot of documentation about the .conf-files since the switches are already covered by the man pages.

I hope you find what you are searching for!