Skip to content

Commit cfa47a3

Browse files
omar-poloomar-polo
committed
improve table-sqlite.5
various warnings reported by mandoc -Tlint; better structure for EXAMPLE; move FILES before EXAMPLE as per usual ordering and sort FILES.
1 parent f752dad commit cfa47a3

File tree

2 files changed

+101
-92
lines changed

2 files changed

+101
-92
lines changed

‎README.md‎

Lines changed: 47 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@ databases with one or more tables.
3333
If the table is used for authentication, the password should be
3434
encrypted using the
3535
crypt(3)
36-
function. Such passwords can be generated using the
36+
function.
37+
Such passwords can be generated using the
3738
encrypt(1)
3839
utility or
3940
smtpctl(8)
@@ -54,55 +55,72 @@ The following configuration options are available:
5455
**query\_alias**
5556
*SQL statement*
5657

57-
> This is used to provide a query to look up aliases. The question mark
58-
> is replaced with the appropriate data. For alias it is the left hand side of
59-
> the SMTP address. This expects one VARCHAR to be returned with the user name
60-
> the alias resolves to.
58+
> This is used to provide a query to look up aliases.
59+
> The question mark is replaced with the appropriate data.
60+
> For alias it is the left hand side of the SMTP address.
61+
> This expects one VARCHAR to be returned with the user name the alias
62+
> resolves to.
6163
6264
**query\_credentials**
6365
*SQL statement*
6466

65-
> This is used to provide a query for looking up user credentials. The question
66-
> mark is replaced with the appropriate data. For credentials it is the left
67-
> hand side of the SMTP address. The query expects that there are two VARCHARS
68-
> returned, one with a user name and one with a password in
67+
> This is used to provide a query for looking up user credentials.
68+
> The question mark is replaced with the appropriate data.
69+
> For credentials it is the left hand side of the SMTP address.
70+
> The query expects that there are two VARCHARS returned, one with a user
71+
> name and one with a password in
6972
> crypt(3)
7073
> format.
7174
7275
**query\_domain**
7376
*SQL statement*
7477

75-
> This is used to provide a query for looking up a domain. The question mark
76-
> is replaced with the appropriate data. For the domain it would be the
77-
> right hand side of the SMTP address. This expects one VARCHAR to be returned
78-
> with a matching domain name.
78+
> This is used to provide a query for looking up a domain.
79+
> The question mark is replaced with the appropriate data.
80+
> For the domain it would be the right hand side of the SMTP address.
81+
> This expects one VARCHAR to be returned with a matching domain name.
7982
8083
**query\_mailaddrmap**
8184
*SQL statement*
8285

83-
> This is used to provide a query for looking up a senders. The question mark
84-
> is replaced with the appropriate data. This expects one VARCHAR to be returned
85-
> with the address the sender is allowed to send mails from.
86+
> This is used to provide a query for looking up a senders.
87+
> The question mark is replaced with the appropriate data.
88+
> This expects one VARCHAR to be returned with the address the sender is
89+
> allowed to send mails from.
8690
8791
A generic SQL statement would be something like:
8892

8993
query_ SELECT value FROM table WHERE key=?;
9094

95+
# FILES
96+
97+
*/etc/mail/smtp.sqlite*
98+
99+
> Suggested
100+
> sqlite3(1)
101+
> database file.
102+
103+
*/etc/mail/sqlite.conf*
104+
105+
> Default
106+
> table-sqlite(8)
107+
> configuration file.
108+
91109
# EXAMPLES
92110

93111
Example based on the OpenSMTPD FAQ: Building a Mail Server
94112
The filtering part is excluded in this example.
95-
96113
The configuration below is for a medium-size mail server which handles
97114
multiple domains with multiple virtual users and is based on several
98-
assumptions. One is that a single system user named vmail is used for all
99-
virtual users. This user needs to be created:
115+
assumptions.
116+
One is that a single system user named vmail is used for all virtual users.
117+
This user needs to be created:
100118

101119
# useradd -g =uid -c "Virtual Mail" -d /var/vmail -s /sbin/nologin vmail
102120
# mkdir /var/vmail
103121
# chown vmail:vmail /var/vmail
104122

105-
*sqlite schema*
123+
The sqlite schema is:
106124

107125
CREATE TABLE virtuals (
108126
id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -118,6 +136,9 @@ virtual users. This user needs to be created:
118136
id INTEGER PRIMARY KEY AUTOINCREMENT,
119137
domain VARCHAR(255) NOT NULL
120138
);
139+
140+
Which can be populated as follows:
141+
121142
INSERT INTO domains VALUES (1, "example.com");
122143
INSERT INTO domains VALUES (2, "example.net");
123144
INSERT INTO domains VALUES (3, "example.org");
@@ -134,14 +155,19 @@ virtual users. This user needs to be created:
134155
INSERT INTO credentials VALUES (1, "[email protected]", "$2b$08$ANGFKBL.BnDLL0bUl7I6aumTCLRJSQluSQLuueWRG.xceworWrUIu");
135156
INSERT INTO credentials VALUES (2, "[email protected]", "$2b$08$AkHdB37kaj2NEoTcISHSYOCEBA5vyW1RcD8H1HG.XX0P/G1KIYwii");
136157

158+
The
137159
*/etc/mail/sqlite.conf*
160+
file then specifies the following queries:
138161

139162
dbpath /etc/mail/smtp.sqlite
140163
query_alias SELECT destination FROM virtuals WHERE email=?;
141164
query_credentials SELECT email, password FROM credentials WHERE email=?;
142165
query_domain SELECT domain FROM domains WHERE domain=?;
143166

144-
*/etc/mail/smtpd.conf*
167+
And the following configuration for
168+
smtpd(8)
169+
in
170+
*/etc/mail/smtpd.conf*:
145171

146172
table domains sqlite:/etc/mail/sqlite.conf
147173
table virtuals sqlite:/etc/mail/sqlite.conf
@@ -150,20 +176,6 @@ virtual users. This user needs to be created:
150176
listen on egress port 587 tls-require pki mail.example.com auth <credentials>
151177
accept from any for domain <domains> virtual <virtuals> deliver to mbox
152178

153-
# FILES
154-
155-
*/etc/mail/sqlite.conf*
156-
157-
> Default
158-
> table-sqlite(8)
159-
> configuration file.
160-
161-
*/etc/mail/smtp.sqlite*
162-
163-
> Suggested
164-
> sqlite3(1)
165-
> database file.
166-
167179
# TODO
168180

169181
Documenting the following query options:

‎table-sqlite.5‎

Lines changed: 54 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -46,16 +46,14 @@ databases with one or more tables.
4646
If the table is used for authentication, the password should be
4747
encrypted using the
4848
.Xr crypt 3
49-
function. Such passwords can be generated using the
49+
function.
50+
Such passwords can be generated using the
5051
.Xr encrypt 1
5152
utility or
5253
.Xr smtpctl 8
5354
encrypt command.
54-
5555
.Sh SQLITE TABLE CONFIG FILE
56-
5756
The following configuration options are available:
58-
.Pp
5957
.Bl -tag -width Ds
6058
.It Xo
6159
.Ic dbpath
@@ -66,71 +64,75 @@ For example:
6664
.Bd -literal -offset indent
6765
dbpath /etc/mail/smtp.sqlite
6866
.Ed
69-
.Pp
70-
7167
.It Xo
7268
.Ic query_alias
7369
.Ar SQL statement
7470
.Xc
75-
This is used to provide a query to look up aliases. The question mark
76-
is replaced with the appropriate data. For alias it is the left hand side of
77-
the SMTP address. This expects one VARCHAR to be returned with the user name
78-
the alias resolves to.
79-
.Pp
80-
71+
This is used to provide a query to look up aliases.
72+
The question mark is replaced with the appropriate data.
73+
For alias it is the left hand side of the SMTP address.
74+
This expects one VARCHAR to be returned with the user name the alias
75+
resolves to.
8176
.It Xo
8277
.Ic query_credentials
8378
.Ar SQL statement
8479
.Xc
85-
This is used to provide a query for looking up user credentials. The question
86-
mark is replaced with the appropriate data. For credentials it is the left
87-
hand side of the SMTP address. The query expects that there are two VARCHARS
88-
returned, one with a user name and one with a password in
80+
This is used to provide a query for looking up user credentials.
81+
The question mark is replaced with the appropriate data.
82+
For credentials it is the left hand side of the SMTP address.
83+
The query expects that there are two VARCHARS returned, one with a user
84+
name and one with a password in
8985
.Xr crypt 3
9086
format.
91-
.Pp
92-
9387
.It Xo
9488
.Ic query_domain
9589
.Ar SQL statement
9690
.Xc
97-
This is used to provide a query for looking up a domain. The question mark
98-
is replaced with the appropriate data. For the domain it would be the
99-
right hand side of the SMTP address. This expects one VARCHAR to be returned
100-
with a matching domain name.
101-
.Pp
102-
91+
This is used to provide a query for looking up a domain.
92+
The question mark is replaced with the appropriate data.
93+
For the domain it would be the right hand side of the SMTP address.
94+
This expects one VARCHAR to be returned with a matching domain name.
10395
.It Xo
10496
.Ic query_mailaddrmap
10597
.Ar SQL statement
10698
.Xc
107-
This is used to provide a query for looking up a senders. The question mark
108-
is replaced with the appropriate data. This expects one VARCHAR to be returned
109-
with the address the sender is allowed to send mails from.
99+
This is used to provide a query for looking up a senders.
100+
The question mark is replaced with the appropriate data.
101+
This expects one VARCHAR to be returned with the address the sender is
102+
allowed to send mails from.
110103
.El
111-
104+
.Pp
112105
A generic SQL statement would be something like:
113106
.Bd -literal -offset indent
114107
query_ SELECT value FROM table WHERE key=?;
115108
.Ed
116-
109+
.Sh FILES
110+
.Bl -tag -width "/etc/mail/sqlite.conf" -compact
111+
.It Pa /etc/mail/smtp.sqlite
112+
Suggested
113+
.Xr sqlite3 1
114+
database file.
115+
.It Pa /etc/mail/sqlite.conf
116+
Default
117+
.Xr table-sqlite 8
118+
configuration file.
119+
.El
117120
.Sh EXAMPLES
118121
Example based on the OpenSMTPD FAQ: Building a Mail Server
119122
The filtering part is excluded in this example.
120-
121123
The configuration below is for a medium-size mail server which handles
122124
multiple domains with multiple virtual users and is based on several
123-
assumptions. One is that a single system user named vmail is used for all
124-
virtual users. This user needs to be created:
125-
126-
.Bd -literal
125+
assumptions.
126+
One is that a single system user named vmail is used for all virtual users.
127+
This user needs to be created:
128+
.Bd -literal -offset indent
127129
# useradd -g =uid -c "Virtual Mail" -d /var/vmail -s /sbin/nologin vmail
128130
# mkdir /var/vmail
129131
# chown vmail:vmail /var/vmail
130132
.Ed
131-
132-
.Ic Pa sqlite schema
133-
.Bd -literal -compact
133+
.Pp
134+
The sqlite schema is:
135+
.Bd -literal -offset indent
134136
CREATE TABLE virtuals (
135137
id INTEGER PRIMARY KEY AUTOINCREMENT,
136138
email VARCHAR(255) NOT NULL,
@@ -145,6 +147,10 @@ CREATE TABLE domains (
145147
id INTEGER PRIMARY KEY AUTOINCREMENT,
146148
domain VARCHAR(255) NOT NULL
147149
);
150+
.Ed
151+
.Pp
152+
Which can be populated as follows:
153+
.Bd -literal -offset indent
148154
INSERT INTO domains VALUES (1, "example.com");
149155
INSERT INTO domains VALUES (2, "example.net");
150156
INSERT INTO domains VALUES (3, "example.org");
@@ -161,37 +167,29 @@ INSERT INTO virtuals VALUES (8, "[email protected]", "vmail");
161167
INSERT INTO credentials VALUES (1, "[email protected]", "$2b$08$ANGFKBL.BnDLL0bUl7I6aumTCLRJSQluSQLuueWRG.xceworWrUIu");
162168
INSERT INTO credentials VALUES (2, "[email protected]", "$2b$08$AkHdB37kaj2NEoTcISHSYOCEBA5vyW1RcD8H1HG.XX0P/G1KIYwii");
163169
.Ed
164-
165-
.Ic Pa /etc/mail/sqlite.conf
166-
.Bd -literal -compact
170+
.Pp
171+
The
172+
.Pa /etc/mail/sqlite.conf
173+
file then specifies the following queries:
174+
.Bd -literal -offset indent
167175
dbpath /etc/mail/smtp.sqlite
168176
query_alias SELECT destination FROM virtuals WHERE email=?;
169177
query_credentials SELECT email, password FROM credentials WHERE email=?;
170178
query_domain SELECT domain FROM domains WHERE domain=?;
171179
.Ed
172-
173-
.Ic Pa /etc/mail/smtpd.conf
174-
.Bd -literal -compact
180+
.Pp
181+
And the following configuration for
182+
.Xr smtpd 8
183+
in
184+
.Pa /etc/mail/smtpd.conf :
185+
.Bd -literal -offset indent
175186
table domains sqlite:/etc/mail/sqlite.conf
176187
table virtuals sqlite:/etc/mail/sqlite.conf
177188
table credentials sqlite:/etc/mail/sqlite.conf
178189
listen on egress port 25 tls pki mail.example.com
179190
listen on egress port 587 tls-require pki mail.example.com auth <credentials>
180191
accept from any for domain <domains> virtual <virtuals> deliver to mbox
181192
.Ed
182-
183-
.Sh FILES
184-
.Bl -tag -width "/etc/mail/sqlite.conf" -compact
185-
.It Pa /etc/mail/sqlite.conf
186-
Default
187-
.Xr table-sqlite 8
188-
configuration file.
189-
.It Pa /etc/mail/smtp.sqlite
190-
Suggested
191-
.Xr sqlite3 1
192-
database file.
193-
.El
194-
195193
.Sh TODO
196194
Documenting the following query options:
197195
.Bd -literal -offset indent -compact
@@ -201,7 +199,6 @@ Documenting the following query options:
201199
.Ic query_mailaddr
202200
.Ic query_addrname
203201
.Ed
204-
205202
.Sh SEE ALSO
206203
.Xr encrypt 1 ,
207204
.Xr crypt 3 ,

0 commit comments

Comments
 (0)