Solaris Admin Series, part 7. Previous: Shells on Solaris 10 and 11: sh, ksh88, ksh93, bash, csh and Setting the Default Shell. Related: part 3, Solaris Filesystem Layout Tour, and part 5, Solaris First-Day Commands. Next up: the PATH problem, /usr/bin vs /usr/xpg4/bin vs /usr/sfw/bin vs /usr/gnu/bin.
The man pages are the most accurate Solaris documentation you have, because they ship with the exact release and SRU you are running. They are also where Solaris 10 and Solaris 11.4 quietly part ways: 11.4 renumbered several manual sections, swapped the keyword index for a full-text search, and changed how the search path is built. This post covers how to read, search and index man pages on both releases, how to get missing pages installed, and how to find the right Oracle documentation library when the man page is not enough.
Applies to: both Solaris 10 and Solaris 11 (11.4), SPARC and x86. The headline differences: Solaris 11.4 renamed sections 1M to 8, 4 to 5, 5 to 7 and 7 to 4; it adds man -K full-text search and keeps its index current through the svc:/application/man-index:default SMF service. Solaris 10 uses the classic windex database that you rebuild by hand with catman -w.
Prerequisites
- A shell on a Solaris 10 or Solaris 11.4 system (global zone or non-global zone both work).
- root or a role with the Software Installation profile if you need to install missing man page packages or rebuild the system index.
- Basic familiarity with the filesystem layout from part 3, since man pages live under
/usr/share/manand friends.
Manual sections: Solaris 10 vs Solaris 11.4
Solaris inherited System V section numbering, which never matched Linux or BSD. Oracle Solaris 11.4 moved to the numbering most other Unix systems use. Every reference you read from before 11.4 (blogs, MOS notes, old runbooks, Solaris 11.3 docs) uses the old numbers, so you need both in your head.
| Content | Solaris 10 / 11.3 and earlier | Solaris 11.4 |
|---|---|---|
| User commands | 1 | 1 |
| System administration commands | 1M (e.g. zfs(1M)) | 8 (e.g. zfs(8)) |
| System calls | 2 | 2 |
| Library functions | 3, 3C, 3SOCKET, 3LIB, … | 3, 3C, 3SOCKET, 3LIB, … |
| File formats | 4 (e.g. vfstab(4)) | 5 (e.g. vfstab(5)) |
Standards, environments, macros, misc (smf, attributes, filesystem) | 5 | 7 |
Device and network interfaces (drivers, ip, zfs ioctl, STREAMS modules) | 7, 7D, 7I, 7M, 7P, 7FS | 4, 4D, 4I, 4M, 4P, 4FS |
| DDI/DKI driver interfaces | 9, 9E, 9F, 9S | 9, 9E, 9F, 9S |
The 11.4 man command is forgiving: if it finds nothing in the section you asked for and that section was an old name, it retries with the new name. So man -s 1m zfs still works on 11.4. The reverse is not true: man -s 8 zfs on Solaris 10 finds nothing.
Reading man pages
Choosing a section
# Solaris 10
$ man -s 1M mount # mount(1M), the admin command
$ man -s 2 mount # mount(2), the system call
$ man -s 4 vfstab # file format
# Solaris 11.4
$ man -s 8 mount
$ man -s 5 vfstab
$ man mount.8 # name.section form also works on 11.4
$ man -s 1m mount # old section name, falls through to section 8Without -s, man shows the first match in search order, which for mount is often the user-command or system-call page, not the one you wanted. Use -l to list every match, then -a to read them all in turn:
$ man -l mount
mount (8) -M /usr/share/man
mount (2) -M /usr/share/man
$ man -a passwd # passwd(1), then passwd(5) (passwd(4) on Solaris 10)Sample output from Solaris 11.4; on Solaris 10 the first line reads mount (1m).
Hierarchical names for SMF services on 11.4
Solaris 11.4 adds man pages for SMF services named after the FMRI and lets you abbreviate them from the right, the same way svcadm accepts abbreviated FMRIs:
$ man system/name-service/switch
$ man name-service/switch
$ man -s 8s switchPaging, plain text and printing
On Solaris 10 the default pager is more -s; on 11.4 it is less -ins. Set PAGER to override either. To save a page as plain text without the overstrike formatting, pipe it through col -b:
$ PAGER=less man -s 1M zfs # Solaris 10, nicer paging
$ man -s 8 zpool | col -x -b > /var/tmp/zpool.txt # plain text copy
$ man -t -s 8 zpool > /var/tmp/zpool.ps # PostScript (11.4 uses groff)Debugging what man is doing
man -d prints the sections and directories it searches. Use it when a page you know is installed will not show up:
$ man -d zfs 2>&1 | headSearching: man -k, man -f and man -K
| Task | Solaris 10 | Solaris 11.4 |
|---|---|---|
| Keyword search in NAME lines | man -k or apropos (needs windex) | man -k or apropos |
| Which page describes this file or command | man -f or whatis | man -f or whatis |
| Full-text search of whole pages | Not available | man -K, optionally limited to one section of the page |
| Index location | /usr/share/man/windex (one per man directory) | Index files under /usr/share/man and /usr/gnu/share/man |
| Index kept current by | You, with catman -w | SMF service application/man-index, restarted automatically by package installs |
# both releases
$ man -k snapshot
$ whatis vfstab
# Solaris 11.4 full-text search
$ man -K zfs create # pages mentioning "zfs" or "create"
$ man -K "zfs create" "storage pool" # quoted phrases
$ man -K examples: "zfs create" # only inside the EXAMPLES section
$ man -K see also: zfs # only inside SEE ALSOman -K examples: is one of the most useful tricks on 11.4: it finds real worked examples across the whole manual.
Building and repairing the index
Solaris 10: catman -w
On Solaris 10, man -k, man -f, apropos and whatis read the windex file. A fresh install often has none, so the first man -k fails. Build it as root:
# /usr/bin/catman -w
# ls -l /usr/share/man/windex
-rw-r--r-- 1 root root 1203574 Nov 1 14:02 /usr/share/man/windex
# index an extra tree too
# catman -w -M /usr/sfw/share/man
# catman -w -M /opt/csw/share/mancatman without -w pre-formats every page into cat* directories, which takes a long time and is rarely worth it today. Re-run catman -w after you add patches or packages that deliver new man pages, because nothing does it for you.
Solaris 11.4: the man-index service
On 11.4 packages tag their man pages with restart_fmri=svc:/application/man-index:default, so the index rebuilds whenever pkg installs or updates pages. If searches miss pages you know exist, check the service and restart it:
$ svcs man-index
STATE STIME FMRI
online Oct_30 svc:/application/man-index:default
# svcadm restart application/man-index
# svcs -x man-index # if it went to maintenance, read the log it names
# or build by hand (also covers a custom tree)
# catman -w
# catman -w -M /opt/local/share/mancatman -w fails with a “writing is not allowed” error if a target directory is read-only, for example a shared read-only /usr in a non-global zone. Index those trees from the global zone.
MANPATH and third-party man pages
The two releases build the search path differently, which is why man finds a GNU or third-party page on one box and not the other.
- Solaris 10: if
MANPATHis unset, only/usr/share/manis searched. Pages for Sun Freeware (/usr/sfw/share/man), OpenCSW (/opt/csw/share/man) or your own tools are invisible until you add them. - Solaris 11.4: if
MANPATHis unset,manderives the search path fromPATH(for example/usr/gnu/binmaps to/usr/gnu/share/man). SettingMANPATHturns that off, so a hard-codedMANPATHcopied from an old Solaris 10 profile hides pages on 11.4.
# Solaris 10, in ~/.profile or /etc/profile
MANPATH=/usr/share/man:/usr/sfw/share/man:/opt/csw/share/man:/usr/local/man
export MANPATH
# Solaris 11.4: usually best left unset; check what man will search
$ unset MANPATH
$ man -d ls 2>&1 | grep -i pathEach man directory can carry a man.cf file with a MANSECTS= line that sets the default section search order for that tree, for example MANSECTS=8,1,2,3,5,7,4,9 to prefer admin pages. You can also embed sections in MANPATH itself: MANPATH=/usr/share/man,1m,1.
Missing man pages: installing them
Solaris 10 (SVR4 packages)
Man pages come from the SUNWman package, plus per-product packages such as the Sun Freeware ones. Minimal installs (Core or Reduced Networking metaclusters) leave them out.
$ pkginfo SUNWman
ERROR: information for "SUNWman" was not found
# mount the Solaris 10 1/13 media, then
# pkgadd -d /cdrom/cdrom0/Solaris_10/Product SUNWman
# catman -w
# which package owns a page?
$ pkgchk -l -p /usr/share/man/man1m/zfs.1m | grep -i packageSolaris 11.4 (IPS)
IPS controls man page delivery with the doc.man facet. If an Automated Installer manifest or a minimal image set facet.doc.man=false, every package installs without its pages. Check the facet and the manual package, then fix whichever is off:
$ pkg facet | grep -i doc
facet.doc.man False local
# pkg change-facet facet.doc.man=true # reinstalls pages for all packages; preview with -nv first
# pkg list -af system/manual
# pkg install system/manual
# which package owns a page?
$ pkg search -l /usr/share/man/man8/zfs.8Sample output; on a default install the facet line is usually absent, which means man pages are included. pkg change-facet may create a new boot environment on some images; run it with -nv first to see what it will do.
The Oracle documentation library
Man pages tell you what a command accepts; the administration guides tell you how the pieces fit together. Use the library that matches your release, because procedures changed a lot between them:
| Release | Library | Notes |
|---|---|---|
| Solaris 11.4 | Oracle Solaris 11.4 documentation | Admin guides for ZFS, SMF, zones, networking, security, IPS |
| Solaris 11.4 man pages | Oracle Solaris 11.4 Reference Library | Every man section online, with the new 1/2/3/4/5/7/8/9 numbering |
| Solaris 11.3 | Oracle Solaris 11.3 Information Library | For 11.3 systems still in Extended Support; old section numbers |
| Solaris 10 1/13 | Oracle Solaris 10 1/13 Information Library | The final Solaris 10 update; man pages in 1M/4/5/7 style |
| Solaris 10 (all updates) | Solaris 10 Operating System docs | Older update-specific guides and release notes |
Tips for working with the library:
- Match the docs to the release from
/etc/releaseandpkg info entire(see part 5). An 11.4 procedure run on 11.3 can fail on options that did not exist yet. - Search engines love old Sun pages under
docs.oracle.com/cd/E19. Those are usually Solaris 10 or earlier; check the URL before you paste commands into an 11.4 box. - The 11.4 “What’s New” and per-SRU release notes explain behavior changes that never make it into man pages.
- For patch and SRU specifics, My Oracle Support (MOS) is the authority; it needs a support contract.
- Many systems have no internet access. Keep a local copy of the guides you rely on, or point people at
man -K examples:, which works offline.
Verification
# Solaris 10
$ ls -l /usr/share/man/windex # exists and is recent
$ man -k zpool | head -3 # returns lines, no "windex not found" error
$ man -s 1M zfs | head -5
# Solaris 11.4
$ svcs -H -o state man-index # online
$ man -k zpool | head -3
$ man -K examples: "zpool create" | head -3
$ man -s 8 zfs | head -5Troubleshooting and gotchas
/usr/share/man/windex: No such file or directoryon Solaris 10. The index was never built. Runcatman -was root.No manual entry for zfs in section(s) 1mon 11.4 even though the fallback exists. The page itself is missing, not the section. Checkfacet.doc.manandpkg search -l.- Runbooks say
man vfstab(4)but 11.4 shows nothing in section 4. File formats moved to section 5 and section 4 is now devices. Useman vfstaborman -s 5 vfstab. - GNU tool pages missing on 11.4. Someone set
MANPATHin a profile. Unset it, or add/usr/gnu/share/man. - Garbage like
_^HN_^HA_^HM_^HEin saved text. You captured overstrike formatting. Pipe throughcol -x -b. - Man page and running command disagree. Pages update with packages, but a stale
cat*preformatted copy from an oldcatmanrun can win. Remove thecat*directories or regenerate them. man-indexin maintenance on 11.4. Read the log fromsvcs -L man-index; a full or read-only/usris the usual cause. Fix it, thensvcadm clear man-index.- Non-global zones. Sparse-root zones on Solaris 10 share
/usrread-only from the global zone, so build the index in the global zone. Solaris 11 zones have their own image and their ownman-indexservice.
What’s next in the Solaris Admin Series
Next we untangle the Solaris PATH: why /usr/bin, /usr/xpg4/bin, /usr/sfw/bin and /usr/gnu/bin hold different versions of the same commands, and how to set PATH so scripts behave the same on both releases. Catch up with part 6, Shells on Solaris 10 and 11, and part 3, Solaris Filesystem Layout Tour.
Official references: man(1) and catman(8) in the Oracle Solaris 11.4 Reference Library, and man(1) and catman(1M) in the Oracle Solaris 10 1/13 Information Library.