diff --git a/mkapachepw.1 b/mkapachepw.1 index 5962754..131543c 100644 --- a/mkapachepw.1 +++ b/mkapachepw.1 @@ -4,7 +4,7 @@ mkapachepw \- Apache webserver user and group file management utility for Unix-like systems. .SH SYNOPSIS -mkapachepw [-sGUguIicqOohv] +mkapachepw.py [-sGUguIicqOohv] .SH DESCRIPTION \fCmkapachepw\fP is a utility program for creating and maintaining @@ -13,8 +13,8 @@ managed in separate files. These files are then combined into single, production files for use by the Apache webserver. In this manner, different departments of an organization can independently manage -their own user and group information in separate files. The webmaster -then uses \fCmkapachepw\fP to combine them on the production system. +their own user and group information. The webmaster then uses +\fCmkapachepw\fP to combine them on the production system. \fCmkapachepw\fP has a number of useful features, including: @@ -59,7 +59,7 @@ .SH OPTIONS .TP .B -s -suppress inclusion system user and group information +suppress inclusion of system user and group information By default, \fCmkapachepw\fP includes the users and groups found in the underlying operating system (starting with the specified @@ -68,10 +68,10 @@ being included in the final output files. .TP -.B -G +groupname -groupname +GID -GID ... +.B -G \'+groupname -groupname +GID -GID ...\' enumerated list of groups to include/exclude .TP -.B -U +username -username +UID -UID ... +.B -U \'+username -username +UID -UID ...\' enumerated list of users to include/exclude By default, \fCmkapachepw\fP reads in @@ -110,16 +110,17 @@ include a group or user. After all, the program reads in every single system group/user and all the groups/users found in any included files. Why bother explicitly naming an entry to include? As -explained below, it is possible to specify a starting GID or UID for -inclusion from the OS databases. Say the starting UID is 100 (the -default), but user \fCbob\fP has a UID of 99. While \fCmkapachepw\fP -would initially read this entry in, it would not place it into the -output Apache user file because this user's UID is below the starting -value. By explicitly providing the argument \fC+bob\fP, this user -will be included in the output despite not satisfying the starting UID -test. In other words, the \fC-G\fP and \fC-U\fP options are the final -arbiters of what actually makes it into the output group and user -files, regardless of other conditions that may be in effect. +explained below, it is possible to specify a starting GID or UID when +processing the OS group and user databases. Say the starting UID is +100 (the default), but user \fCbob\fP has a UID of 99. While +\fCmkapachepw\fP would initially read this entry in, it would not +place it into the output Apache user file because this user's UID is +below the starting value. By explicitly providing the argument +\fC+bob\fP, this user will be included in the output despite not +satisfying the starting UID test. In other words, the \fC-G\fP and +\fC-U\fP options are the final arbiters of what actually makes it into +the output group and user files, regardless of other conditions that +may be in effect. There is another reason why you might explicitly enumerate a user to be included in the output user file. By default, \fCmkapachepw\fP @@ -174,10 +175,11 @@ This would include .B all -the system users whose UID was 100 or greater in the user output file. -It would then produce a group output file whose only entries would be -the groups \fCadmins\fP, \fCwebmasters\fP (regardless whether they -were found in the OS group database or in the included file +the system users whose UID was 100 or greater in the user output file +(the default action, since no options modifying user processing are +specified). It would produce a group output file whose only entries +would be the groups \fCadmins\fP, \fCwebmasters\fP (regardless whether +they were found in the OS group database or in the included file \fCmygroups.inc\fP), and the group whose GID was 4433. @@ -209,12 +211,13 @@ Any files you request to be included will be processed .B after \fCmkapachepw\fP reads the OS group and user databases. This means -that, if one of your included files has a group/user name that is -the same as one of the system groups/user, you will get a "collision". -Unless you prohibit collisions (see the \fC-c\fP option below), this means -the entry from the included file will supercede the OS entry. Say, for -example, you have user named \fCmary\fP both in your OS and in one -of your included files. Then, the password specified for \fCmary\fP in the +that, if one of your included files has a group/user name that is the +same as one of the system groups/user, you will get a "collision". +Unless you prohibit collisions (see the \fC-c\fP option below), this +means the entry from the included file will supercede the OS entry +(though you will be warned about the collision). Say, for example, +you have user named \fCmary\fP both in your OS and in one of your +included files. Then, the password specified for \fCmary\fP in the .B included file will end up in the final Apache user access control file, not the password found in the OS user database. @@ -275,65 +278,76 @@ .TP .B -v -print detailed version information. +print detailed program version information .SH EXAMPLES -Output files will contain only system groups and users whose GIDs/UIDs are 100 or higher: +.P .ft C \" Courier .nf - mkapachepw.py +mkapachepw.py .fi - - -Output files will contain system groups and user whose GIDs/UIDs are 100 or higher, and -all the groups found in \fCgroups.inc\fP. If any of the groups in this included -file has the same name as a system group, the program will emit an error and halt, -writing no output: - .ft \" revert +.IP +Output files will contain only system groups and users whose GIDs/UIDs +are 100 or higher. +.P + + .ft C \" Courier .nf - mkapachepw.py -c -I groups.inc +mkapachepw.py -c -I groups.inc .fi .ft \" revert +.IP +Output files will contain system groups and user whose GIDs/UIDs are +100 or higher, and all the groups found in \fCgroups.inc\fP. If any +of the groups in this included file has the same name as a system +group, the program will emit an error and halt, writing no output. +.P -The output files will contain all system groups and users whose GIDs/UIDs are -100 or higher +.ft C \" Courier +.nf +mkapachepw.py -G "-wheel -bin" -U "-root -bin" +.fi +.ft \" revert + +.IP +The output files will contain all system groups and users whose +GIDs/UIDs are 100 or higher .B except -the groups \fCwheel\fP and \fCbin\fP and the users \fCroot\fP and \fCbin\fP, -which will not appear in the final group and user files respectively: +the groups \fCwheel\fP and \fCbin\fP and the users \fCroot\fP and +\fCbin\fP, which will not appear in the final group and user files +respectively. +.P .ft C \" Courier .nf - mkapachepw.py -G "-wheel -bin" -U "-root -bin" +mkapachepw.py -s -I mygroups.inc -i myusers.inc .fi .ft \" revert +.IP Only the entries in the included files will be processed. No system -groups or users will be present in the final output: +groups or users will be present in the final output. +.P .ft C \" Courier .nf - mkapachepw.py -s -I mygroups.inc -i myusers.inc +mkapachepw.py -g 100001 -u 100001 -I ... -i ... -G ... -U ... .fi .ft \" revert +.IP .B Nothing -is included by default. Only the entries explicitly enumerated by -the \fC-G\fP and \fC-U\fP options will be included from both the -system and included file entries: - -.ft C \" Courier -.nf - mkapachepw.py -g 100001 -u 100001 -I ... -i ... -G ... -U ... -.fi -.ft \" revert - +is included by default. Only the entries explicitly enumerated by the +\fC-G\fP and \fC-U\fP options will be included from both the system +and included file entries. +.P .SH EXIT CODES .ft C \" Courier @@ -352,7 +366,8 @@ 3 Cannot open output file - 4 Included file attempted to redefine existing user or group + 4 Included file attempted to redefine existing user or group, + and collisions are currently forbidden via the -c option .fi .ft \" revert @@ -385,7 +400,7 @@ .SH COPYRIGHT AND LICENSING \fCmkapachepw\fP is Copyright (c) \*(CP TundraWare Inc. For terms of use, see -the mkapachepw-license.txt file in the program distribution. If you +the \fCmkapachepw-license.txt\fP file in the program distribution. If you install \fCmkapachepw\fP on a FreeBSD system using the 'ports' mechanism, you will also find this file in /usr/local/share/doc/mkapachepw. @@ -405,7 +420,7 @@ .ft \" revert .SH DOCUMENT REVISION INFORMATION -$Id: mkapachepw.1,v 1.105 2005/04/12 10:05:36 toor Exp $ +$Id: mkapachepw.1,v 1.106 2005/04/12 18:39:25 toor Exp $