pwfilter.8

.\" This file is licensed under the CC\[hy]BY\[hy]SA license.
.\" See the AUTHORS and LICENSE files for more information.
.Dd September 4, 2015
.Dt PWFILTER 8
.Os \" Current operating system.
.
.Sh NAME
.Nm pwfilter
.Nd filter passwd, shadow, or group files by UIDs/GIDs
.
.Sh SYNOPSIS
.Nm
.Op Fl h
.Op Fl V
|
.Ar ID ...
|
.Op Fl a Ar ID
.Op Fl e Ar ID ...
.Op Fl E Ar ID ID
.Op Fl f Ar filename Op Ar filename
.Op Fl i Ar ID ...
.Op Fl I Ar ID ID
.Ar ...
.
.Sh DESCRIPTION
.Nm
filters passwd, shadow, or group files according to ID. These can be individual
IDs or ranges \[em] include or exclude. The full line from the appropriate
file will be output for each matching ID.
.Sh COMMANDS
.Nm
provides three nearly identical modes of operation.
.Cm pwfilter ,
.Cm shdwfilter ,
and
.Cm grpfilter .
.Pp
All three share the same options, arguments, and features \[em] with a few
caveats for
.Cm shdwfilter
.Pq no piped input, requires two arguments for Fl Fl file
which are explained in the relevant portions of this manual.
.
.Sh Options
.Bl -tag -width Ds
.It Fl a , Fl Fl at\-and\-above Ar ID
Include IDs above and including this number.
.It Fl e , Fl Fl exclude Ar ID ...
Exclude these specific ID(s).
.It Fl E , Fl Fl exclude\-range Ar ID ID
Exclude this range of IDs.
.It Fl f , Fl Fl file Ar filename Op Ar filename
File to parse rather than system default.
.Cm shdwfilter
requires both
.Ar passwd
and
.Ar shadow .
.It Fl h , Fl Fl help
Print a summary of
.Nm Ap s
command\[hy]line options and then exit.
.It Fl i , Fl Fl include Ar ID ...
Include these Specific ID(s).
.It Fl I , Fl Fl range Ar ID ID
Include this range of IDs.
.It Fl V , Fl Fl version
Print the version number and exit.
.El
.
.Sh FILTERING LOGIC
The order in which options are defined does not matter. Rather, each option type
has a fixed priority. All IDs are excluded by default. Thus, running
.Nm
with no arguments will result in no output. Exclude wins over include, and
specific IDs always win over ranges. Thus, in descending order of priority:
.Pp
.Bl -dash -compact -offset 4n
.It
exclude ID
.Pq Fl e
.It
include ID
.Pq Fl i
.It
exclude range
.Pq Fl E
.It
include range
.Pq Fl I
.It
include at\-and\-above
.Pq Fl a
.It
exclude all
.Pq default
.El
.
.Sh EXIT STATUS
.Nm
exits 0 on success and 1 if an error occurs.
.
.Sh EXAMPLES
.Pp
Shorthand syntax, without any options. Users 210, 1000, and 1027.
.Dl pwfilter 210 1000 1027
.Pp
Groups with a GID of 100 or 1000 <= GID <= 9999.
.Dl grpfilter \-\-include 100 \-\-range 1000 9999
.Pp
Users from local.passwd with a UID >= 10000.
.Dl pwfilter \-\-file local.passwd \-\-at\-and\-above 10000
.Pp
UIDs 0\-999 from piped input.
.Dl cat local.passwd | pwfilter \-\-range 0 999
.Pp
This is a contrived example, but it shows how the cascading works. The result
will be the shadow entries of UIDs 100\-110, 125, 140\-144, and 146\-150.
.Dl shdwfilter \-\-range 100 150 \-\-exclude-range 110 140 \-\-include 125 \-\-exclude 145
.Pp
Over SSH, in conjunction with a local group file.
.Dl ssh me@box Qo grpfilter \-\-range 1000 9999 \-\-include 100 Qc > new.group
.Dl grpfilter \-\-range 0 999 \-\-exclude 100 \-\-at\-and\-above 10000 >> new.group
.Dl grpck -s new.group
.
.Sh CORNER CASES
When both piped input and the
.Fl Fl file
option are provided, the piped input is ignored and the
.Fl Fl file
argument is read and parsed.
.Pp
.Cm shdwfilter
cannot accept piped input since it needs to parse two files
.Pq Ar passwd , shadow
.
.Sh BUGS
.Pp Piping into
.Nm
will not work on the rare platforms which do not provide the very common \[em]
yet surprisingly non\[hy]POSIX \[em] /dev/stdin.
.Pp
The piped input detection may not work correctly in some specific SSH
situations. If you encounter this, try using the
.Fl Fl file
option; it should then ignore any phantom piped input.
.Pp
In very uncommon configurations, it is possible to have UIDs that are higher
than the 32-bit math limit of some shells \[em] e.g. mksh on a 64-bit Debian
machine. In such situations, please refer to the PORTABILITY file and consider
using another shell.
.
.Sh SEE ALSO
For the purposes of validating and sorting the output of
.Nm ,
the use of
.Xr grpck 8
and
.Xr pwck 8
is
.Em highly
recommended.
.Pp
The
.Nm
repository is available at
.Lk https://github.com/aqw/pwfilter
Bug reports, patches, and (constructive) input are always welcome.
.Sh AUTHOR
.Nm
was created by
.An Alex Waite
.Mt alex@waite.eu .
See the AUTHORS file for more information.
.
.Sh COPYRIGHT
.Nm
is released under the
.Qq ISC License.
See the LICENSE file for more information.