[qmail] / qmail-getpw.9

.TH qmail-getpw 8
.SH NAME
qmail-getpw \- give addresses to users
.SH SYNOPSIS
.B qmail-getpw
.I local
.SH DESCRIPTION
In
.BR qmail ,
each user controls a vast array of local addresses.
.B qmail-getpw
finds the user that controls a particular address,
.IR local .
It prints six pieces of information,
each terminated by NUL:
.IR user ;
.IR uid ;
.IR gid ;
.IR homedir ;
.IR dash ;
and
.IR ext .
The user's account name is
.IR user ;
the user's uid and gid in decimal are
.I uid
and
.IR gid ;
the user's home directory is
.IR homedir ;
and messages to
.I local
will be handled by
.IR homedir\fB/.qmail\fIdashext .

In case of trouble,
.B qmail-getpw
exits nonzero without printing anything.

.B WARNING:
The operating system's
.B getpwnam
function, which is at the heart of
.BR qmail-getpw ,
is inherently unreliable.
.SH "RULES"
.B qmail-getpw
considers an account in
.B /etc/passwd
to be a user if
(1) the account has a nonzero uid,
(2) the account's home directory exists (and is visible to
.BR qmail-getpw ),
and
(3) the account owns its home directory.
.B qmail-getpw
ignores account names containing uppercase letters.
.B qmail-getpw
also assumes that all account names are shorter than 32 characters.

.B qmail-getpw
gives each user
control over the basic
.I user
address and
all addresses of the form
.IR user\fBBREAK\fIanything .
When
.I local
is
.IR user ,
.I dash
and
.I ext
are both empty.
When
.I local
is
.IR user\fBBREAK\fIanything ,
.I dash
is a hyphen and
.I ext
is
.IR anything .
.I user
may appear in any combination of uppercase and lowercase letters
at the front of
.IR local .

A catch-all user,
.BR alias ,
controls all other addresses.
In this case
.I ext
is
.I local
and
.I dash
is a hyphen.

You can override all of
.BR qmail-getpw 's
decisions with the
.B qmail-users
mechanism, which is reliable, highly configurable, and much faster than
.BR qmail-getpw .
.SH "SEE ALSO"
qmail-users(5),
qmail-lspawn(8)
Commit	Line	Data
2117e02e MW	1	.TH qmail-getpw 8
	2	.SH NAME
	3	qmail-getpw \- give addresses to users
	4	.SH SYNOPSIS
	5	.B qmail-getpw
	6	.I local
	7	.SH DESCRIPTION
	8	In
	9	.BR qmail ,
	10	each user controls a vast array of local addresses.
	11	.B qmail-getpw
	12	finds the user that controls a particular address,
	13	.IR local .
	14	It prints six pieces of information,
	15	each terminated by NUL:
	16	.IR user ;
	17	.IR uid ;
	18	.IR gid ;
	19	.IR homedir ;
	20	.IR dash ;
	21	and
	22	.IR ext .
	23	The user's account name is
	24	.IR user ;
	25	the user's uid and gid in decimal are
	26	.I uid
	27	and
	28	.IR gid ;
	29	the user's home directory is
	30	.IR homedir ;
	31	and messages to
	32	.I local
	33	will be handled by
	34	.IR homedir\fB/.qmail\fIdashext .
	35
	36	In case of trouble,
	37	.B qmail-getpw
	38	exits nonzero without printing anything.
	39
	40	.B WARNING:
	41	The operating system's
	42	.B getpwnam
	43	function, which is at the heart of
	44	.BR qmail-getpw ,
	45	is inherently unreliable.
	46	.SH "RULES"
	47	.B qmail-getpw
	48	considers an account in
	49	.B /etc/passwd
	50	to be a user if
	51	(1) the account has a nonzero uid,
	52	(2) the account's home directory exists (and is visible to
	53	.BR qmail-getpw ),
	54	and
	55	(3) the account owns its home directory.
	56	.B qmail-getpw
	57	ignores account names containing uppercase letters.
	58	.B qmail-getpw
	59	also assumes that all account names are shorter than 32 characters.
	60
	61	.B qmail-getpw
	62	gives each user
	63	control over the basic
	64	.I user
65	address and
66	all addresses of the form
67	.IR user\fBBREAK\fIanything .
68	When
69	.I local
70	is
71	.IR user ,
72	.I dash
73	and
74	.I ext
75	are both empty.
76	When
77	.I local
78	is
79	.IR user\fBBREAK\fIanything ,
80	.I dash
81	is a hyphen and
82	.I ext
83	is
84	.IR anything .
85	.I user
86	may appear in any combination of uppercase and lowercase letters
87	at the front of
88	.IR local .
89
90	A catch-all user,
91	.BR alias ,
92	controls all other addresses.
93	In this case
94	.I ext
95	is
96	.I local
97	and
98	.I dash
99	is a hyphen.
100
101	You can override all of
102	.BR qmail-getpw 's
103	decisions with the
104	.B qmail-users
105	mechanism, which is reliable, highly configurable, and much faster than
106	.BR qmail-getpw .
107	.SH "SEE ALSO"
108	qmail-users(5),
109	qmail-lspawn(8)