mirrors/maddy
1
0
Fork 0
mirror of https://github.com/foxcpp/maddy.git synced 2025-04-03 13:17:35 +03:00
Code Issues Projects Releases Packages Wiki Activity

Style and grammar update to Markdown files

Browse source 
This commit majorly updates all Markdown documents by attempting to maintain a consistent (80 columns per line) formatting and addresses some display bugs in other Markdown renderers due to improper use of Markdown - GitHub is a little broken. But it also addresses grammar and even makes semantical changes to some paragraphs.

Notably, in README.md, section "System authentication helper binaries" had relatively severe changes.

To future contributors: if trying to maintain any kind of wrapping standard, I suggest using special extensions, like Rewrap for VSCode.
This commit is contained in:
Hexawolf 2019-10-21 22:07:21 +03:00 • committed by fox.cpp
parent 10e173fdb6
commit 5031797192
6 changed files with 115 additions and 86 deletions
Download patch file Download diff file Expand all files Collapse all files

49
.github/CODE_OF_CONDUCT.md vendored
View file

@ -1,33 +1,52 @@
# Code of Merit
**1.** The project creators, lead developers, core team, constitute the managing members of the project and have final say in every decision of the project, technical or otherwise, including overruling previous decisions. There are no limitations to this decisional power.
**1.** The project creators, lead developers, core team, constitute the managing
members of the project and have final say in every decision of the project,
technical or otherwise, including overruling previous decisions. There are no
limitations to this decisional power.
**2.** Contributions are an expected result of your membership on the project. Don’t expect others to do your work or help you with your work forever.
**2.** Contributions are an expected result of your membership on the project.
Don’t expect others to do your work or help you with your work forever.
**3.** All members have the same opportunities to seek any challenge they want within the project.
**3.** All members have the same opportunities to seek any challenge they want
within the project.
**4.** Authority or position in the project will be proportional to the accrued contribution. Seniority must be earned.
**4.** Authority or position in the project will be proportional to the accrued
contribution. Seniority must be earned.
**5.** Software is evolutive: the better implementations must supersede lesser implementations. Technical advantage is the primary evaluation metric.
**5.** Software is evolutive: the better implementations must supersede lesser
implementations. Technical advantage is the primary evaluation metric.
**6.** This is a space for technical prowess; topics outside of the project will not be tolerated.
**6.** This is a space for technical prowess; topics outside of the project will
not be tolerated.
**7.** Non technical conflicts will be discussed in a separate space. Disruption of the project will not be allowed.
**7.** Non technical conflicts will be discussed in a separate space. Disruption
of the project will not be allowed.
**8.** Individual characteristics, including but not limited to, body, sex, sexual preference, race, language, religion, nationality, or political preferences are irrelevant in the scope of the project and will not be taken into account concerning your value or that of your contribution to the project.
**8.** Individual characteristics, including but not limited to, body, sex,
sexual preference, race, language, religion, nationality, or political
preferences are irrelevant in the scope of the project and will not be taken
into account concerning your value or that of your contribution to the project.
**9.** Discuss or debate the idea, not the person.
**10.** There is no room for ambiguity: Ambiguity will be met with questioning; further ambiguity will be met with silence. It is the responsibility of the originator to provide requested context.
**10.** There is no room for ambiguity: Ambiguity will be met with questioning;
further ambiguity will be met with silence. It is the responsibility of the
originator to provide requested context.
**11.** If something is illegal outside the scope of the project, it is illegal in the scope of the project. This Code of Merit does not take precedence over governing law.
**11.** If something is illegal outside the scope of the project, it is illegal
in the scope of the project. This Code of Merit does not take precedence over
governing law.
**12.** This Code of Merit governs the technical procedures of the project not the activities outside of it.
**12.** This Code of Merit governs the technical procedures of the project not
the activities outside of it.
**13.** Participation on the project equates to agreement of this Code of Merit.
**14.** No objectives beyond the stated objectives of this project are relevant to the project. Any intent to deviate the project from its original purpose of existence will constitute grounds for remedial action which may include expulsion from the project.
This document is the Code of Merit (<strike>`http://code-of-merit.org`</strike>), version 1.0.
**14.** No objectives beyond the stated objectives of this project are relevant
to the project. Any intent to deviate the project from its original purpose of
existence will constitute grounds for remedial action which may include
expulsion from the project.
This document is the Code of Merit
(<strike>`http://code-of-merit.org`</strike>), version 1.0.

3
.github/CONTRIBUTING.md vendored
View file

@ -6,7 +6,8 @@ better.
## Reporting bugs
**Issue tracker is meant to be used only if you have a problem or a feature
request. If you just have some questions about maddy - prefer to use the [IRC channel](https://webchat.freenode.net/?channels=%23%23maddy).**
request. If you just have some questions about maddy - prefer to use the
[IRC channel](https://webchat.freenode.net/?channels=%23%23maddy).**
- Provide log files, preferably with 'debug' directive set.
- Provide the exact steps to reproduce the issue.

3
.github/ISSUE_TEMPLATE/bug-report.md vendored
View file

@ -19,7 +19,8 @@ Use a service like hastebin.com or attach a file if it is big
# Configuration file
Located in /etc/maddy/maddy.conf by default, don't forget to remove DB passwords and other security-related stuff.
Located in /etc/maddy/maddy.conf by default, don't forget to remove DB passwords
and other security-related stuff.
# Environment information

3
.github/ISSUE_TEMPLATE/feature-request.md vendored
View file

@ -16,6 +16,7 @@ Note alternatives you considered and why they are not useful.
# Your idea for a solution
How your solution would work in general?
Note that some overly complicated solutions may be rejected because maddy is meant to be simple.
Note that some overly complicated solutions may be rejected because maddy is
meant to be simple.
- [ ] I'm willing to help with the implementation

48
HACKING.md
View file

@ -1,31 +1,31 @@
## Design goals
- **Make it easy to deploy**
Minimal configuration changes should be required to get typical mail server
running. Though, it is important to avoid making guesses for "zero
configuration". Wrong guess is worse than no guess.
- **Make it easy to deploy.**
Minimal configuration changes should be required to get a typical mail server
running. Though, it is important to avoid making guesses for a
"zero-configuration". A wrong guess is worse than no guess.
- **Provide 80% of needed components**
- **Provide 80% of needed components.**
E-mail has evolved into a huge mess. With a single package to do one thing, it
quickly turns into maintenance nightmare. Put all stuff mail server typically
needs into a single package. Though, leave controversial or highly opinionated
stuff out, don't force people to do things our way (see next point).
quickly turns into a maintenance nightmare. Put all stuff mail server
typically needs into a single package. Though, leave controversial or highly
opinionated stuff out, don't force people to do things our way
(see next point).
- **Interoperate with existing software**
- **Interoperate with existing software.**
Implement (de-facto) standard protocols not only for clients but also for
various server-side helper software (content filters, etc).
- **Be secure but interoperable**
- **Be secure but interoperable.**
Verify DKIM signatures by default, use DMRAC policies by default, etc. This
makes default setup as secure as possible while maintaining reasonable
interoperability. Users can configure maddy to be more strict at cost of
interoperability.
interoperability. Though, users can configure maddy to be stricter.
- **Acheive flexibility through composability**
Allow to connect components in arbitrary ways instead of restricting users to
- **Achieve flexibility through composability.**
Allow connecting components in arbitrary ways instead of restricting users to
predefined templates.
- **Use Go concurrency features to full extent**
- **Use Go concurrency features to a full extent.**
Do as much I/O as possible in parallel to minimize latencies. It is silly to
not do so when it is possible.
@ -38,7 +38,7 @@ user documentation to understand how things work from the user perspective as
well.
- User documentation: [maddy.conf(5)](maddy.conf.5.scd)
- Design rationale: [Comments on design (Wiki)](https://github.com/foxcpp/maddy/wiki/Dev:-Comments-on-design)
- Design rationale: [Comments on design (Wiki)][1]
There are components called "modules". They are represented by objects
implementing the module.Module interface. Each module gets its unique name.
@ -76,15 +76,15 @@ that upstream. Unique names requirement helps a lot here.
"Semantical names" idea explained above is not applied when modules instances
are defined "inline" (in place they are used in). These instances have no
instance names and are not added to the global map so they can not be accessed
by modules other than one that used ConfigFromNode on corresponding config
by modules other than one that used ConfigFromNode on the corresponding config
block. All arguments after the module name in an inline definition represent
"inline arguments". They are passed to the module instance directly and not
used anyhow by other code (i.e. they are not guaranteed to be unique).
### A word on error logging
Shortly put, it is module responsibility to log errors it generated since it is
assumed it can provide all useful details about possible causes.
Shortly put, it is a module's responsibility to log errors it generated since it
is assumed it can provide all useful details about possible causes.
Modules should not log errors received from other modules. However, it is
fine to log decisions made based on these errors.
@ -92,9 +92,11 @@ fine to log decisions made based on these errors.
This does not apply to "debug log", anything can be logged using it if it is
considered useful for troubleshooting.
Here is the example: remote module logs all errors received from remote server
and passes them to the caller. queue module only logs whether delivery to
certain recipient is permanently failed or it will be retried. When used
Here is the example: remote module logs all errors received from the remote
server and passes them to the caller. Queue module only logs whether delivery to
the certain recipient is permanently failed or it will be retried. When used
together, remote module will provide logs about concrete errors happened and
queue module will provide information about tries made and scheduled to be made
in future.
in the future.
[1]: https://github.com/foxcpp/maddy/wiki/Dev:-Comments-on-design

95
README.md
View file

@ -4,10 +4,11 @@
Simple, fast, secure all-in-one mail server.
**⚠️ Disclaimer: maddy is in early development, many planned features are missing and bugs are waiting to eat your messages**
**⚠️ Disclaimer: maddy is in early development, many planned features are
missing and bugs are waiting to eat your messages**
Join [##maddy on irc.freenode.net](https://webchat.freenode.net/##maddy), if you have
any questions or just want to talk about maddy.
Join [##maddy on irc.freenode.net](https://webchat.freenode.net/##maddy), if you
have any questions or just want to talk about maddy.
## Table of contents
@ -32,7 +33,8 @@ any questions or just want to talk about maddy.
- [MTA-STS](https://www.hardenize.com/blog/mta-sts) support
- DNS sanity checks for incoming deliveries
- Built-in [DKIM](https://blog.returnpath.com/how-to-explain-dkim-in-plain-english-2/) verification support
- [Subaddressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) (aka plus-addressing) support
- [Subaddressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)
(aka plus-addressing) support
Planned features:
- Built-in [DKIM](https://blog.returnpath.com/how-to-explain-dkim-in-plain-english-2/) signing
@ -46,7 +48,8 @@ Planned features:
## Installation
Pre-built binaries for releases are available [here](https://github.com/foxcpp/maddy/releases).
Pre-built binaries for releases are available
[here](https://github.com/foxcpp/maddy/releases).
## Building from source
@ -66,20 +69,22 @@ Pre-built binaries for releases are available [here](https://github.com/foxcpp/m
- C compiler (**optional**, set CGO_ENABLED env. variable to 0 to disable)
Required for SQLite3-based storage (default configuration) and PAM authentication.
SQLite3 support can be disabled using nosqlite3 build tag:
Required for SQLite3-based storage (default configuration) and PAM
authentication. SQLite3 support can be disabled using nosqlite3 build tag:
```
GO111MODULE=on go get github.com/foxcpp/maddy/cmd/maddy@master -tags 'nosqlite3'
```
- libpam (**optional**, not needed by default)
Used for PAM auth helper binary or direct PAM use, later is disabled by default
and can be enabled using 'libpam' build tag (e.g. `go get ... -tags 'libpam nosqlite3'`)
Used for PAM auth helper binary or direct PAM use, later is disabled by
default and can be enabled using 'libpam' build tag
(e.g. `go get ... -tags 'libpam nosqlite3'`)
**Note:** Main executable built with CGO_ENABLED=0 does not depend on any system library
and can be moved freely between systems. Executable built without libpam but with CGO_ENABLED=1 (default)
depends only on libc. Executable built with libpam depends on system libpam, obviously.
**Note:** Main executable built with CGO_ENABLED=0 does not depend on any system
library and can be moved freely between systems. Executable built without libpam
but with CGO_ENABLED=1 (default) depends only on libc. Executable built with
libpam depends on system libpam, obviously.
### Building
@ -88,7 +93,7 @@ First, make sure Go Modules support is enabled:
export GO111MODULE=on
```
Command to build latest commit from master branch:
Command to build latest commit from the master branch:
```
go get github.com/foxcpp/maddy/cmd/maddy@master
```
@ -105,17 +110,17 @@ $HOME/go/bin).
## Quick start
You need to make sure configuration is placed in /etc/maddy/maddy.conf
(copy maddy.conf from this repo) and also /var/lib/maddy and /run/maddy exist
and writable.
You need to make sure configuration is placed in /etc/maddy/maddy.conf (copy
maddy.conf from this repo) and also /var/lib/maddy and /run/maddy exist and
writable.
Then, simply run the executable:
```
maddy
```
You can specify custom locations for all directories and config file, so
here is no need to mess with directories in your system:
You can specify custom locations for all directories and config file, so here is
no need to mess with directories in your system:
```
maddy -config /maddy.conf -state /state -runtime /tmp
```
@ -123,14 +128,14 @@ maddy will create specified directories for you.
### systemd unit
Alternatively, you can use the systemd unit file from [dist/](dist) directory in this repo.
It will automatically set-up user account and directories. Additionally, it
will apply strict sandbox to maddy to ensure additional security.
Alternatively, you can use the systemd unit file from [dist/](dist) directory in
this repo. It will automatically set-up user account and directories.
Additionally, it will apply strict sandbox to maddy to ensure additional
security.
You need a relatively new systemd version (235+) both of these things to work
properly. Otherwise, you still have to manually create a user account and
the state + runtime directories with read-write permissions for
the maddy user.
properly. Otherwise, you still have to manually create a user account and the
state + runtime directories with read-write permissions for the maddy user.
## Configuration
@ -149,7 +154,8 @@ You need to change the following directives to your values:
With that configuration you will get the following:
- SQLite-based storage for messages
- Authentication using SQLite-based virtual users DB (see [maddyctl utility](#maddyctl-utility))
- Authentication using SQLite-based virtual users DB
(see [maddyctl utility](#maddyctl-utility))
- SMTP endpoint for incoming messages on 25 port.
- SMTP Submission endpoint for messages from your users, on both 587 (STARTTLS)
and 465 (TLS) ports.
@ -172,10 +178,11 @@ $(local_domains) = example.com example.org
```
admin@example.com and admin@example.org will refer to the same mailbox.
If you want to make them separate - add `auth_perdomain` and `storage_perdomain` directives
below.
If you want to make them separate - add `auth_perdomain` and `storage_perdomain`
directives below.
Note that it will require users to specify full address as username when logging in.
Note that it will require users to specify the full address as a username when
logging in.
## maddyctl utility
@ -206,8 +213,8 @@ If that's not the case, provide `-config` and/or `-state` arguments
### PostgreSQL instead of SQLite
If you want to use PostgreSQL instead of SQLite 3 (e.g. you want better access concurrency), here is
what you need to do:
If you want to use PostgreSQL instead of SQLite 3 (e.g. you want better access
concurrency), here is what you need to do:
1. Install, configure and start PostgreSQL server
@ -245,24 +252,22 @@ the [project wiki](https://github.com/foxcpp/maddy/wiki).
## System authentication helper binaries
By default maddy is running as a unprivileged user, meaning it can't read
By default maddy is running as an unprivileged user, meaning it can't read
system account passwords. There are two options:
- Run maddy as a privileged user instead (not recommended)
This way you can use maddy without messing with helper binaries, but that
will also give maddy a little bit too many permissions.
##### Run maddy as a privileged user instead (not recommended):
This way you can use maddy without messing with helper binaries, but that also
gives maddy too many permissions.
- Let maddy start privileged (setuid) helper binary to perform authentication
##### Let maddy start a privileged helper binary to perform authentication:
Compile [cmd/maddy-pam-helper](cmd/maddy-pam-helper) and/or
[cmd/maddy-shadow-helper](cmd/maddy-shadow-helper).
Put them into `/usr/lib/maddy` and make them setuid root (there are also other
more restrictive options, check README in the executable directories).
Add `use_helper` to `pam` or `shadow` configuration block in your config.
Modify systemd unit to use less strict sandbox and disable DynamicUser.
1. Compile [cmd/maddy-pam-helper](cmd/maddy-pam-helper) and/or
[cmd/maddy-shadow-helper](cmd/maddy-shadow-helper).
2. Put them into `/usr/lib/maddy` and make them setuid root (there are also
other more restrictive options, check README in the executable directories).
3. Add `use_helper` to `pam` or `shadow` configuration block in your config.
4. Modify systemd unit to use less strict sandbox and disable DynamicUser.
## Contributing
@ -270,4 +275,4 @@ See [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
## License
MIT. Just do whatever you want.
The code is under MIT license. See [LICENSE](LICENSE) for more information.