Fork: 0
tundra / mkapachepw
Browse code
Formatting and general cleanup.
master
1 parent a508b7a commit afe140f4d54de724c6e05c56c7dc6adae58b7625
@toor toor authored on 12 Apr 2005
Patch
Unified Split
Showing 1 changed file
View
212
■■■■■
 mkapachepw.1
.SH NAME
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
Apache webserver user and group access control files. Its primary
value is that it allows large numbers of user and group entries to be
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:
 
.IP \(bu 4
 
.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
starting GID and UID - see the \fC-g\fP and \fC-u\fP options below). This
command line option prevents any system users or groups from
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
.B all
It is probably not immediately obvious why you would ever explicitly
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
does
.ft \" revert
 
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.
 
 
.TP
 
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.
 
print help information
 
.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:
 
.ft C \" Courier
.nf
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
 
.ft C \" Courier
.nf
mkapachepw.py -c -I groups.inc
.fi
.ft \" revert
 
 
The output files will contain all system groups and users whose GIDs/UIDs are
100 or higher
.P
 
.ft C \" Courier
.nf
mkapachepw.py
.fi
.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
.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
 
.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:
 
.ft C \" Courier
.nf
mkapachepw.py -G "-wheel -bin" -U "-root -bin"
.fi
.ft \" revert
 
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 -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:
 
.ft C \" Courier
.nf
mkapachepw.py -s -I mygroups.inc -i myusers.inc
.fi
.ft \" revert
 
groups or users will be present in the final output.
.P
 
.ft C \" Courier
.nf
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
.nf
- Attempt to include/exclude a non-existent GID, UID, or name
 
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
 
 
None known as of this release.
 
.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.
 
\fCmkapachepw\fP is free for individual, non-commerical, personal
.fi
.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 $