.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) .\" Copyright (c) 2001, 2002 Colin Watson. .\" .\" You may distribute under the terms of the GNU General Public .\" License as specified in the file docs/COPYING.GPLv2 that comes with the .\" man-db distribution. .\" .\" Thu Sep 21 19:22:47 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk) .\" .BS 1 "Miscellaneous" .BS 2 "Modes of operation" .lp The \*M utilities can operate in many different modes, allowing varying degrees of freedom, functionality and security. No mode requires that the manual page hierarchies be writable. .lp .ip "(1) Default mode" .b man is setuid to the user MAN_OWNER which is \(oqman\(cq by default and is changeable via options to .b configure . .b mandb , if run by the superuser or MAN_OWNER, creates globally accessible index databases owned by MAN_OWNER. Once the databases are created, .b man will update entries in them if it finds newly installed manual pages (if the .b \-\-update flag is used) or delete entries if manual pages are removed. In this mode it is possible for a malicious .b man user to deliberately lock a database as a writer, thus denying read access to other users. .br If cat directories exist and have the correct permissions, .b man will take care of producing cat files. These will be owned by MAN_OWNER. The default permissions of both cat files and databases are 0644. .ip "(2) No man database updates" This mode also requires .b man to be setuid, but is favoured where databases must be shared in an environment unfriendly to kernel locking procedures, eg. NFS. It also prevents possible .q "denial of service" attacks by malicious .b man users as .b man never opens the databases as a writer in this mode. To replace the functionality lost by disallowing .b man write access to the databases, .b mandb should be rerun whenever new manual pages are installed. Otherwise, .b man will not be able to use the database to find and display the newly added manual pages, and will have to use the filesystem instead. Each index database may be owned by an arbitrary user who will have subsequent write access to the database. Cat files are created in the same way as for mode (1) above. .br To use the \*M utilities in this mode, give the option \(oq\-\-disable\-automatic\-update\(cq to .b configure . .ip "(3) No man database updates or cat production" .b man is installed not setuid. This mode of operation probably offers the highest level of security but it requires higher levels of maintenance than other modes due to the restrictions imposed upon .b man . Each database is owned by an arbitrary user as in mode (2). Each cat hierarchy is also owned by an arbitrary user who is responsible for creating cat files using .b catman whenever new manual files are installed. .b man will be completely passive in its action, i.e. no index databases will be written to and no cat files are ever produced. .br To use the \*M utilities in this mode, supply the options \(oq\-\-disable\-cache\-owner \-\-disable\-setuid \-\-disable\-automatic\-update \-\-disable\-cats\(cq to .b configure , or build \*M as in mode (1) and install the binaries without the setuid bit set. .ip "(4) Wide open" .b man is installed not setuid. This mode is similar in operation to the majority of vendor supplied, non setuid, cat file supporting manual pager suites. It is not recommended. The databases are owned by an arbitrary user who maintains them using .b mandb . .b man does not update the databases. Cat files are produced and stored in world writable cat directories and have world write access themselves. .br To use the \*M utilities in this mode, supply the options \(oq\-\-disable\-cache\-owner \-\-disable\-setuid \-\-disable\-automatic\-update\(cq to .b configure , edit .i include/manconfig.h and change the definition of CATMODE from 0644 to 0666. .lp Other variations can also be used. In fact it is possible for .b man to actually create index databases, usually the job of .b mandb , for users' private manual page hierarchies. This is enabled by giving the option \(oq\-\-enable\-automatic\-create\(cq to .b configure . .lp In summary, .i include/manconfig.h contains definitions for .bu CATMODE .bu DBMODE .lp the setuid installation and operation of .b man is modified by supplying either of the following options to .b configure : .bu \-\-enable\-setuid .bu \-\-disable\-setuid .lp and other aspects of .b man 's behaviour are controlled by the following options to .b configure : .bu \-\-enable\-automatic\-create .bu \-\-disable\-automatic\-update .bu \-\-disable\-cats .BS 2 "NFS root squash" .lp If .b man is installed setuid to an arbitrary user and is run by root, instead of gaining the effective user id of the setuid user, .b man is run with both uid and euid as root. This is neccesary due to infelicities with the .b POSIX setuid() function call: All users except root may change to and from the effective (setuid) user, however once root has setuid(user), there is no way back. .lp A side effect of this is that .b NFS mounted cat hierarchies or databases will be unwritable if the following conditions exist: .bu man/catman/mandb is run by root .bu The NFS mount has the root squash flag set .lp To get around this problem, the root user must first attain the ID of the cat hierarchy or database owner before running .b man/catman/mandb whenever the databases need updating or cat files are to be produced. .BS 2 "NLS message catalogues" .lp \*M has built in support for native language message catalogues. That is, it can issue messages in the locale of the user's choice. This will only occur if the locale's translation has been written. Before undertaking a translation, please contact the Translation Project (https://translationproject.org/) who are coordinating such activities. .BS 2 "Credits" .lp The authors would like to thank the following people for their time, effort, support, ideas and code which went into \*M: .(l Markus Armbruster Lionel Cons & colleages Carl Edman Caleb Epstein Lars Fenneberg Zoltan Hidvegi Nils Magnus Daniel Quinlan Fabrizio Polacco Gordon Sadler Colin Phipps Paul Slootman Jose Rodriguez Eirik Fuller Matej Vela Clint Adams Jeremy C. Reed Erik Andersen Giuseppe Sacco David Weinehall Ralph Corderoy Yuri Kozlov Henning Makholm Lars Wirzenius Nicolas Fran\(,cois Ivan Shmakov Peter Breitenlohner Robert Luberda Chusslove Illich .)l and all those translators listed in the .b man/THANKS file.