* [pmg-devel] [PATCH pmg-docs 1/5] configuration management: language fix-up
@ 2021-06-15 10:36 Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 2/5] rule-based mail filter: language fixup Dylan Whyte
` (4 more replies)
0 siblings, 5 replies; 6+ messages in thread
From: Dylan Whyte @ 2021-06-15 10:36 UTC (permalink / raw)
To: pmg-devel
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 31881 bytes --]
this fixes wording, spelling, grammar, etc. for the chapter
'configuration management'
Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
---
pmgconfig.adoc | 256 ++++++++++++++++++++++++-------------------------
1 file changed, 128 insertions(+), 128 deletions(-)
diff --git a/pmgconfig.adoc b/pmgconfig.adoc
index 67c1bd8..1ae80c3 100644
--- a/pmgconfig.adoc
+++ b/pmgconfig.adoc
@@ -27,15 +27,15 @@ endif::manvolnum[]
{pmg} is usually configured using the web-based Graphical User
Interface (GUI), but it is also possible to directly edit the
-configuration files, use the REST API over 'https'
+configuration files, using the REST API over 'https'
or the command line tool `pmgsh`.
The command line tool `pmgconfig` is used to simplify some common
-configuration tasks, i.e. to generate cerificates and to rewrite
+configuration tasks, such as generating certificates and rewriting
service configuration files.
NOTE: We use a Postgres database to store mail filter rules and
-statistic data. See chapter xref:chapter_pmgdb[Database Management]
+statistical data. See chapter xref:chapter_pmgdb[Database Management]
for more information.
@@ -45,9 +45,8 @@ Configuration files overview
`/etc/network/interfaces`::
Network setup. We never modify this file directly. Instead, we write
-changes to `/etc/network/interfaces.new`. When you reboot, we rename
-the file to `/etc/network/interfaces`, so the changes are applied
-on the next reboot.
+changes to `/etc/network/interfaces.new`. When you reboot, {pmg} renames
+the file to `/etc/network/interfaces`, thus applying the changes.
`/etc/resolv.conf`::
@@ -56,7 +55,7 @@ to create the FQDN and domain name used in the postfix configuration.
`/etc/hostname`::
-The system's host name. {pmg} uses the hostname to create the FQDN used
+The system's hostname. {pmg} uses the hostname to create the FQDN used
in the postfix configuration.
`/etc/hosts`::
@@ -65,7 +64,8 @@ Static table lookup for hostnames.
`/etc/pmg/pmg.conf`::
-Stores common administration options, i.e. the spam and mail proxy setup.
+Stores common administration options, such as the spam and mail proxy
+configuration.
`/etc/pmg/cluster.conf`::
@@ -120,15 +120,15 @@ Keys and Certificates
`/etc/pmg/pmg-api.pem`::
-Key and certificate (combined) used be the HTTPs server (API).
+Key and certificate (combined) used by the HTTPS server (API).
`/etc/pmg/pmg-authkey.key`::
-Privat key use to generate authentication tickets.
+Private key used to generate authentication tickets.
`/etc/pmg/pmg-authkey.pub`::
-Public key use to verify authentication tickets.
+Public key used to verify authentication tickets.
`/etc/pmg/pmg-csrf.key`::
@@ -147,20 +147,20 @@ Key for DKIM signing mails with selector '<selector>'.
Service Configuration Templates
-------------------------------
-{pmg} uses various services to implement mail filtering, for example
+{pmg} uses various services to implement mail filtering, for example,
the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
-engine and the Apache {spamassassin} project. These services use
-separate configuration files, so we need to rewrite those files when
+engine, and the Apache {spamassassin} project. These services use
+separate configuration files, so we need to rewrite those files when the
configuration is changed.
-We use a template based approach to generate those files. The {tts} is
+We use a template-based approach to generate these files. The {tts} is
a well known, fast and flexible template processing system. You can
find the default templates in `/var/lib/pmg/templates/`. Please do not
-modify them directly, because your modification would get lost on the
+modify these directly, otherwise your modifications will be lost on the
next update. Instead, copy the template you wish to change to
`/etc/pmg/templates/`, then apply your changes there.
-Templates can access any configuration setting, and you can use the
+Templates can access any configuration settings, and you can use the
`pmgconfig dump` command to get a list of all variable names:
----
@@ -173,9 +173,9 @@ pmg.admin.advfilter = 1
...
----
-The same tool is used to force regeneration of all template based
-configuration files. You need to run that after modifying a template,
-or when you directly edit configuration files
+The same tool is used to force the regeneration of all template-based
+configuration files. You need to run the following after modifying a template,
+or when you directly edit configuration files:
----
# pmgconfig sync --restart 1
@@ -192,28 +192,28 @@ synced from the master node to all cluster members.
White- and Blacklists
---------------------
-{pmg} has multiple white- and blacklists. It differentiates between the
-xref:pmgconfig_mailproxy_options[SMTP Whitelist]. The rule-based whitelist
+{pmg} has multiple white- and blacklists. It differentiates between the
+xref:pmgconfig_mailproxy_options[SMTP Whitelist], the rule-based whitelist
and the user whitelist.
-In addition to the whitelists there are 2 separate blacklists. The rule-based
+In addition to the whitelists, there are two separate blacklists: the rule-based
blacklist and the user blacklist.
SMTP Whitelist
~~~~~~~~~~~~~~
The xref:pmgconfig_mailproxy_options[SMTP Whitelist] is responsible for disabling
-greylisting as well as SPF and DNSBL checks. These are done during the SMTP
+greylisting, as well as SPF and DNSBL checks. These are done during the SMTP
dialogue.
Rule-based White-/Blacklist
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The xref:chapter_mailfilter[rule-based white- and blacklists] are predefined
-rules. They work by checking the attached 'Who' objects, containing e.g. a
-domain or a mail address, for a match. If it matches, the assigned action is
-used which by default is 'Accept' for the whitelist rule and 'Block' for the
-blacklist rule. In the default setup the blacklist rule has priority over the
-whitelist rule and spam checks.
+rules. They work by checking the attached 'Who' objects, containing, for
+example, a domain or a mail address for a match. If it matches, the assigned
+action is used, which by default is 'Accept' for the whitelist rule and 'Block'
+for the blacklist rule. In the default setup, the blacklist rule has priority
+over the whitelist rule and spam checks.
User White-/Blacklist
~~~~~~~~~~~~~~~~~~~~~
@@ -221,13 +221,13 @@ User White-/Blacklist
The user white- and blacklist are user specific. Every user can add mail addresses
to their white- and blacklist. When a user adds a mail address to the whitelist,
the result of the spam analysis will be discarded for that recipient. This can
-help the mail being accepted, but it still depends on the other rules what
-happens next. In the default setup this results in the mail being accepted for
+help in the mail being accepted, but what happens next still depends on the
+other rules. In the default setup, this results in the mail being accepted for
this recipient.
-For mail addresses on a user's blacklist the spam score will be increased by 100.
-It still depends on the rule system what happens when a spam score that high is
-encountered. In the default setup it will be recognized as spam and quarantined
+For mail addresses on a user's blacklist, the spam score will be increased by
+100. What happens when a high spam score is encountered still depends on the
+rule system. In the default setup, it will be recognized as spam and quarantined
(spam score of 3 or higher).
[[pmgconfig_systemconfig]]
@@ -241,13 +241,12 @@ ifndef::manvolnum[]
[thumbnail="pmg-gui-network-config.png", big=1]
endif::manvolnum[]
-Normally the network and time is already configured when you visit the
-GUI. The installer asks for those settings and sets up the correct
-values.
+As network and time are configured in the installer, these generally do not
+need to be configured again in the GUI.
The default setup uses a single Ethernet adapter and static IP
assignment. The configuration is stored at '/etc/network/interfaces',
-and the actual network setup is done the standard Debian way using
+and the actual network setup is done the standard Debian way, using the
package 'ifupdown'.
.Example network setup '/etc/network/interfaces'
@@ -282,7 +281,7 @@ ifndef::manvolnum[]
endif::manvolnum[]
-Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
+These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
using the following configuration keys:
include::pmg.admin-conf-opts.adoc[]
@@ -301,7 +300,7 @@ ifndef::manvolnum[]
[thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
endif::manvolnum[]
-Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
+These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
using the following configuration keys:
include::pmg.mail-relaying-conf-opts.adoc[]
@@ -314,7 +313,7 @@ ifndef::manvolnum[]
[thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1]
endif::manvolnum[]
-List of relayed mail domains, i.e. what destination domains this
+A list of relayed mail domains, that is, what destination domains this
system will relay mail to. The system will reject incoming mails to
other domains.
@@ -327,7 +326,7 @@ ifndef::manvolnum[]
[thumbnail="pmg-gui-mailproxy-ports.png", big=1]
endif::manvolnum[]
-Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
+These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
using the following configuration keys:
include::pmg.mail-ports-conf-opts.adoc[]
@@ -341,7 +340,7 @@ ifndef::manvolnum[]
[thumbnail="pmg-gui-mailproxy-options.png", big=1]
endif::manvolnum[]
-Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
+These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
using the following configuration keys:
include::pmg.mail-options-conf-opts.adoc[]
@@ -351,9 +350,9 @@ include::pmg.mail-options-conf-opts.adoc[]
Before and After Queue scanning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Scanning email can happen at two different stages of mail-processing:
+Email scanning can happen at two different stages of mail-processing:
-* Before-queue filtering: During the SMTP Session, after the complete message
+* Before-queue filtering: During the SMTP session, after the complete message
has been received (after the 'DATA' command).
* After-queue filtering: After initially accepting the mail and putting it on
@@ -361,37 +360,37 @@ Scanning email can happen at two different stages of mail-processing:
Before-queue filtering has the advantage that the system can reject a mail (by
sending a permanent reject code '554'), and leave the task of notifying the
-original sender to the other mailserver. This is of particular advantage if
+original sender to the other mail server. This is of particular advantage if
the processed mail is a spam message or contains a virus and has a forged
-sender-address. Sending out a notification in this situation leads so-called
+sender address. Sending out a notification in this situation leads to so-called
'backscatter' mail, which might cause your server to get listed as spamming on
RBLs (Real-time Blackhole List).
After-queue filtering has the advantage of providing faster delivery of
-mails for the sending servers, since queueing mails is much faster than
-analyzing it for spam and viruses.
-
-If a mail is addressed to multiple recipients (e.g. when multiple addresses are
-subscribed to the same mailing list) the situation is more complicated: Your
-mailserver can only reject or accept the mail for all recipients, after having
-received the complete message, while your rule setup might accept the mail for
-part of the recipients and reject it for others. This can be due to a
-complicated rule setup, or if your users use the 'User White- and Blacklist'
-feature.
-
-If the resulting action of the rule system is the same for all recipients {pmg}
-responds accordingly if configured for before queue filtering (sending '554'
+mails for the sending servers, since queuing emails is much faster than
+analyzing them for spam and viruses.
+
+If a mail is addressed to multiple recipients (for example, when multiple
+addresses are subscribed to the same mailing list), the situation is more
+complicated; your mail server can only reject or accept the mail for all
+recipients, after having received the complete message, while your rule setup
+might accept the mail for part of the recipients and reject it for others. This
+can be due to a complicated rule setup, or if your users use the 'User White-
+and Blacklist' feature.
+
+If the resulting action of the rule system is the same for all recipients, {pmg}
+responds accordingly, if configured for before-queue filtering (sending '554'
for a blocked mail and '250' for an accepted or quarantined mail). If some
mailboxes accept the mail and some reject it, the system has to accept the mail.
Whether {pmg} notifies the sender that delivery failed for some recipients by
sending a non-delivery report, depends on the 'ndr_on_block' setting in
-'/etc/pmg/pmg.conf'. If enabled an NDR is sent. Keeping it disabled prevents
+'/etc/pmg/pmg.conf'. If enabled, an NDR is sent. Keeping this disabled prevents
NDRs being sent to the (possibly forged) sender and thus minimizes the chance
-of getting your IP listed on a RBL. However in certain environments it can be
+of getting your IP listed on an RBL. However in certain environments, it can be
unacceptable not to inform the sender about a rejected mail.
-The setting has the same effect if after queue filtering is configured, with
+The setting has the same effect if after-queue filtering is configured, with
the exception that an NDR is always sent out, even if all recipients block the
mail, since the mail already got accepted before being analyzed.
@@ -405,10 +404,10 @@ Greylisting
Greylisting is a technique for preventing unwanted messages from reaching the
resource intensive stages of content analysis (virus detection and spam
-detection): By initially replying with a temporary failure code ('450') to
-each new email, the {pmg} tells the sending server that it should queue the
-mail and retry delivery at a later moment. Since certain kinds of spam get
-sent out by software, which has no provisioning for queueing, these mails are
+detection). By initially replying with a temporary failure code ('450') to
+each new email, {pmg} tells the sending server that it should queue the
+mail and retry delivery at a later point. Since certain kinds of spam get
+sent out by software which has no provisioning for queuing, these mails are
dropped without reaching {pmg} or your mailbox.
The downside of greylisting is the delay introduced by the initial deferral of
@@ -419,24 +418,24 @@ coming from a source for a recipient, which have passed greylisting in the
past are directly passed on: For each email the triple '<sender network,
sender email, recipient email>' is stored in a list, along with the time when
delivery was attempted. If an email fits an already existing triple, the
-timestamp for that triple is updated and the email is accepted for further
+timestamp for that triple is updated, and the email is accepted for further
processing.
-As long as a sender and recipient do communicate frequently there is no delay
+As long as a sender and recipient communicate frequently, there is no delay
introduced by enabling greylisting. A triple is removed after a longer period
-of time, when no mail fitting that triple has been seen. The timeouts in {pmg}
+of time, if no mail fitting that triple has been seen. The timeouts in {pmg}
are:
* 2 days for the retry of the first delivery
-* 36 days for known triples
+* 36 days for a known triple
-Mails with an empty envelope-sender are always delayed.
+Mails with an empty envelope sender are always delayed.
Some email service providers send out emails for one domain from multiple
-servers. To prevent delays due to an email coming in from 2 separate IPs of
-the same provider the triples store a network ('cidr') instead of a single IP.
-For certain large providers the default network size might be too small. You
+servers. To prevent delays due to an email coming in from two separate IPs of
+the same provider, the triples store a network ('cidr') instead of a single IP.
+For certain large providers, the default network size might be too small. You
can configure the netmask applied to an IP for the greylist lookup in
'/etc/pmg/pmg.conf' or in the GUI with the settings 'greylistmask' for IPv4
and 'greylistmask6' for IPv6 respectively.
@@ -451,13 +450,13 @@ ifndef::manvolnum[]
endif::manvolnum[]
You can use {pmg} to send emails to different internal email servers. For
-example you can send emails addressed to domain.com to your first email server,
+example, you can send emails addressed to domain.com to your first email server
and emails addressed to subdomain.domain.com to a second one.
You can add the IP addresses, hostname, transport protocol (smtp/lmtp),
transport ports and mail domains (or just single email addresses) of your
additional email servers. When transport protocol is set to `lmtp`, the option
-'Use MX' is useless and will be automatically set to 'No'.
+'Use MX' is useless and will automatically be set to 'No'.
[[pmgconfig_mailproxy_networks]]
@@ -471,8 +470,8 @@ endif::manvolnum[]
You can add additional internal (trusted) IP networks or hosts. All hosts in
this list are allowed to relay.
-NOTE: Hosts in the same subnet with Proxmox can relay by default and it’s not
-needed to add them in this list.
+NOTE: Hosts in the same subnet as {pmg} can relay by default and don't need to
+be added to this list.
[[pmgconfig_mailproxy_tls]]
@@ -490,24 +489,24 @@ generates a new self signed certificate for you (`/etc/pmg/pmg-tls.pem`).
{pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
-server. Otherwise, messages are sent in the clear.
+server. Otherwise, messages are sent unencrypted.
You can set a different TLS policy per destination. A destination is either a
-remote domain or a next-hop destination as specified in `/etc/pmg/transport`.
+remote domain or a next-hop destination, as specified in `/etc/pmg/transport`.
This can be used if you need to prevent email delivery without
encryption, or to work around a broken 'STARTTLS' ESMTP implementation. See
{postfix_tls_readme} for details on the supported policies.
Enable TLS logging::
-To get additional information about SMTP TLS activity you can enable
-TLS logging. That way information about TLS sessions and used
+To get additional information about SMTP TLS activity, you can enable
+TLS logging. In this case, information about TLS sessions and used
certificates is logged via syslog.
Add TLS received header::
Set this option to include information about the protocol and cipher
-used as well as the client and issuer CommonName into the "Received:"
+used, as well as the client and issuer CommonName into the "Received:"
message header.
Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
@@ -526,13 +525,13 @@ endif::manvolnum[]
DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
cryptographically authenticate a mail as originating from a particular domain.
-Before sending the mail a hash over certain header fields and the body is
+Before sending the mail, a hash over certain header fields and the body is
computed, signed with a private key and added in the `DKIM-Signature` header of
the mail. The 'selector' (a short identifier chosen by you, used to identify
which system and private key were used for signing) is also included in the
`DKIM-Signature` header.
-The verification is done by the receiver: The public key is fetched
+The verification is done by the receiver. The public key is fetched
via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
for verifying the hash. You can publish multiple selectors for your domain,
each used by a system which sends email from your domain, without the need to
@@ -540,10 +539,10 @@ share the private key.
{pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
-Additionally it supports conditionally signing outbound mail if configured.
-It uses one private key and selector per PMG deployment (all nodes in a cluster
-use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is
-used as signing algorithm.
+Additionally, it supports conditionally signing outbound mail, if configured.
+It uses one private key and selector per {pmg} deployment (all nodes in a
+cluster use the same key). The key has a minimal size of 1024 bits and
+rsa-sha256 is used as the signing algorithm.
The headers included in the signature are taken from the list of
`Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
@@ -568,9 +567,10 @@ record which you need to add to all domains signed by {pmg} by clicking on the
Sign all Outgoing Mail::
Controls whether all outbound mail should get signed or only mails from domains
-listed in `/etc/pmg/dkim/domains` if it exists and `/etc/pmg/domains` otherwise.
+listed in `/etc/pmg/dkim/domains`, if it exists and `/etc/pmg/domains`
+otherwise.
-Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
+These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
using the following configuration keys:
include::pmg.admin-dkim-conf-opts.adoc[]
@@ -586,10 +586,10 @@ endif::manvolnum[]
All SMTP checks are disabled for those entries (e.g. Greylisting,
SPF, DNSBL, ...)
-DNSBL checks are done by `postscreen` which works on IP addresses and networks.
+DNSBL checks are done by `postscreen`, which works on IP addresses and networks.
This means it can only make use of the `IP Address` and `IP Network` entries.
-NOTE: If you use a backup MX server (e.g. your ISP offers this service
+NOTE: If you use a backup MX server (for example, your ISP offers this service
for you) you should always add those servers here.
NOTE: To disable DNSBL checks entirely, remove any `DNSBL Sites` entries in
@@ -610,7 +610,7 @@ endif::manvolnum[]
signatures. This makes it harder for spammers to identify one aspect
which they can craft their messages to work around the spam filter.
-Every single email will be analyzed and gets a spam score
+Every single email will be analyzed and have a spam score
assigned. The system attempts to optimize the efficiency of the rules
that are run in terms of minimizing the number of false positives and
false negatives.
@@ -631,7 +631,7 @@ email if it is ham or spam (or virus). Good emails are delivered to
the inbox and spam messages are moved into the spam quarantine.
The system can be configured to send daily reports to inform users
-about the personal spam messages received the last day. The report is
+about personal spam messages received in the last day. The report is
only sent if there are new messages in the quarantine.
Some options are only available in the config file `/etc/pmg/pmg.conf`,
@@ -661,7 +661,7 @@ slightly adjusting the score of a particular rule. Two examples:
* Your system tags many legitimate mails from a partner organization as spam,
because the organization has a policy that each mail has to start with
'Dear madam or sir' (generating 1.9 points through the rule
- 'DEAR_SOMETHING'). By setting the score of this rule to 0 you can disable
+ 'DEAR_SOMETHING'). By setting the score of this rule to 0, you can disable
it completely.
The system logs all the rules which a particular mail hits. Analyzing the logs can
@@ -670,7 +670,7 @@ lead to finding such a pattern in your environment.
You can adjust the score of a rule by creating a new 'Custom Rule Score' entry
in the GUI.
-NOTE: In general it is strongly recommended to not make large changes to the
+NOTE: In general, it is strongly recommended not to make large changes to the
default scores.
@@ -701,7 +701,7 @@ endif::manvolnum[]
Please note that the virus signature database is automatically
updated. You can see the database status in the GUI, and also
-trigger manual updates there.
+trigger manual updates from there.
[[pmgconfig_clamav_quarantine]]
@@ -712,9 +712,9 @@ ifndef::manvolnum[]
[thumbnail="pmg-gui-virusquar-options.png", big=1]
endif::manvolnum[]
-Indentified virus mails are automatically moved to the virus
-quarantine. The administrator can view these mails using the GUI, and
-choose to deliver them in case of false positives. {pmg} does not notify
+Identified virus mails are automatically moved to the virus
+quarantine. The administrator can view these mails from the GUI, and
+choose to deliver them, in case of false positives. {pmg} does not notify
individual users about received virus mails.
Virus quarantine related settings are saved to subsection 'virusquar'
@@ -728,14 +728,14 @@ Custom SpamAssassin configuration
This is only for advanced users. {spamassassin}'s rules and their associated
scores get updated regularly and are trained on a huge corpus, which gets
-classified by experts. In most cases adding a rule for matching a particular
+classified by experts. In most cases, adding a rule for matching a particular
keyword is the wrong approach, leading to many false positives. Usually bad
detection rates are better addressed by properly setting up DNS than by adding
a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
spam-headers - see the {spamassassin_dnsbl}.
-To add or change the Proxmox {spamassassin} configuration please login to the
-console via SSH. Change to the `/etc/mail/spamassassin/` directory. In this
+To add or change the Proxmox {spamassassin} configuration, log in to the
+console via SSH and change to the `/etc/mail/spamassassin/` directory. In this
directory there are several files (`init.pre`, `local.cf`, ...) - do not change
them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
the xref:pmgconfig_template_engine[template engine], while the others can
@@ -752,7 +752,7 @@ to use the correct {spamassassin} syntax, and test it with:
If you run a cluster, the `custom.cf` file is synchronized from the
master node to all cluster members automatically.
-To adjust the score assigned to a particular rule you
+To adjust the score assigned to a particular rule, you
can also use the xref:pmgconfig_spamdetector_customscores[Custom Rule Score]
settings in the GUI.
@@ -774,25 +774,25 @@ treatment of an email. Its input is passed via two CLI arguments:
* the 'queue-file-name' - a filename, which contains the complete email as
rfc822/eml file
-The expected output need to be printed on STDOUT and consists of two lines:
+The expected output needs to be printed to STDOUT and consists of two lines:
* the 'api-version' (currently 'v1') - see above
* one of the following 3 results:
-** 'OK' - email is ok
+** 'OK' - email is OK
** 'VIRUS: <virusdescription>' - email is treated as if it contained a virus
(the virus description is logged and added to the email's headers)
** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
to the email's spamscore
-The check is run with a 5 minute timeout - if it is exceeded the check
+The check is run with a 5 minute timeout - if this is exceeded, the check
executable is killed and the email is treated as OK.
All output written to STDERR by the check is written with priority 'err' to the
journal/mail.log.
-A simple sample script following the API (and yielding a random result) for
-reference:
+Below is a simple sample script following the API (and yielding a random result)
+for reference:
----
#!/bin/sh
@@ -869,7 +869,7 @@ There are four roles:
Administrator::
-Is allowed to manage settings of {pmg}, except some tasks like network
+Is allowed to manage settings of {pmg}, excluding some tasks like network
configuration and upgrading.
Quarantine manager::
@@ -886,17 +886,17 @@ Helpdesk::
Combines permissions of the 'Auditor' and the 'Quarantine Manager' role.
-In addition there is always the 'root' user, which is used to perform special
+In addition, there is always the 'root' user, which is used to perform special
system administrator tasks, such as upgrading a host or changing the network
configuration.
-NOTE: Only pam users are able to login via the webconsole and ssh, which the
-users created with the web interface are not. Those users are created for {pmg}
-administration only.
+NOTE: Only PAM users are able to log in via the web interface and ssh, while the
+users created through the web interface are not. Those users are created for
+{pmg} administration only.
Local user related settings are saved in `/etc/pmg/user.conf`.
-For details of the fields see xref:pmg_user_configuration_file[user.conf]
+For details on the fields, see xref:pmg_user_configuration_file[user.conf]
[[pmgconfig_ldap]]
LDAP/Active Directory
@@ -912,7 +912,7 @@ Creating a profile requires (at least) the following:
* profile name
* protocol (LDAP or LDAPS; LDAPS is recommended)
* at least one server
-* a user and password (if your server does not support anonymous binds)
+* a username and password (if your server does not support anonymous binds)
All other fields should work with the defaults for most setups, but can be
used to customize the queries.
@@ -924,21 +924,21 @@ Bind user
^^^^^^^^^
It is highly recommended that the user which you use for connecting to the
-LDAP server only has the permission to query the server. For LDAP servers
+LDAP server only has permission to query the server. For LDAP servers
(for example OpenLDAP or FreeIPA), the username has to be of a format like
-'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are
-depending on your setup. For Active Directory servers, the format should be
+'uid=username,cn=users,cn=accounts,dc=domain', where the specific fields
+depend on your setup. For Active Directory servers, the format should be
like 'username@domain' or 'domain\username'.
Sync
^^^^
-{pmg} synchronizes the relevant user and group info periodically, so that
-the information is available in a fast manner, even when the LDAP/AD server
-is temporarily not accessible.
+{pmg} synchronizes the relevant user and group information periodically, so that
+the information is quickly available, even when the LDAP/AD server is
+temporarily inaccessible.
After a successful sync, the groups and users should be visible on the web
-interface. After that, you can create rules targeting LDAP users and groups.
+interface. Following this, you can create rules targeting LDAP users and groups.
[[pmgconfig_fetchmail]]
@@ -947,15 +947,15 @@ Fetchmail
[thumbnail="pmg-gui-fetchmail-config.png", big=1]
-Fetchmail is utility for polling and forwarding emails. You can define
+Fetchmail is a utility for polling and forwarding emails. You can define
email accounts, which will then be fetched and forwarded to the email
address you defined.
You have to add an entry for each account/target combination you want to
-fetch and forward. Those will then be regularly polled and forwarded,
+fetch and forward. These will then be regularly polled and forwarded,
according to your configuration.
-The API and web interface offer following configuration options:
+The API and web interface offer the following configuration options:
include::fetchmail.conf.5-opts.adoc[]
--
2.20.1
^ permalink raw reply [flat|nested] 6+ messages in thread
* [pmg-devel] [PATCH pmg-docs 2/5] rule-based mail filter: language fixup
2021-06-15 10:36 [pmg-devel] [PATCH pmg-docs 1/5] configuration management: language fix-up Dylan Whyte
@ 2021-06-15 10:36 ` Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 3/5] Administration: " Dylan Whyte
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Dylan Whyte @ 2021-06-15 10:36 UTC (permalink / raw)
To: pmg-devel
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 8696 bytes --]
general language fixup for the chapter 'rule-based mail filter'
Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
---
pmg-mail-filter.adoc | 95 ++++++++++++++++++++++++--------------------
1 file changed, 51 insertions(+), 44 deletions(-)
diff --git a/pmg-mail-filter.adoc b/pmg-mail-filter.adoc
index fa9d3a0..3aafe4c 100644
--- a/pmg-mail-filter.adoc
+++ b/pmg-mail-filter.adoc
@@ -2,13 +2,13 @@
Rule-Based Mail Filter
======================
-{pmg} ships with a highly configurable mail filter. It’s an easy but
-powerful way to define filter rules by user, domains, time frame,
-content type and resulting action.
+{pmg} ships with a highly configurable mail filter. This provides an
+easy but powerful way to define filter rules by user, domain, time
+frame, content type, and resulting action.
[thumbnail="pmg-gui-mail-filter-rules.png", big=1]
-Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT' and
+Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT', and
'ACTION'), and each category may contain several objects to match
certain criteria:
@@ -48,14 +48,14 @@ Example: Mark email with “SPAM:” in the subject.
Rules are ordered by priority, so rules with higher priority are
executed first. It is also possible to set a processing direction:
-'In':: Rule applies for all incoming emails
+'In':: Rule applies to all incoming emails
-'Out':: Rule applies for all outgoing emails
+'Out':: Rule applies to all outgoing emails
-'In & Out':: Rule applies for both directions
+'In & Out':: Rule applies to both directions
-And you can also disable a rule completely, which is mostly useful for
-testing and debugging. The 'Factory Defaults' button alows you to
+You can also disable a rule completely, which is mostly useful for
+testing and debugging. The 'Factory Defaults' button allows you to
reset the filter rules.
@@ -83,7 +83,7 @@ Block mail. This is a 'final' action.
Quarantine
~~~~~~~~~~
-Move to quarantine (virus mails are moved to the “virus quarantine”,
+Move to quarantine (virus mails are moved to the “virus quarantine”;
other mails are moved to “spam quarantine”). This is also a 'final' action.
@@ -118,14 +118,18 @@ Blind Carbon Copy (BCC)
The BCC object simply sends a copy to another target. It is possible to
send the original unmodified mail, or the processed result. Please
-note that this can be quite different, i.e. when a previous rule
+note that this can be quite different, for instance, when a previous rule
removed attachments.
Header Attributes
~~~~~~~~~~~~~~~~~
-This object is able to add or modify mail header attributes. As with notifications above, you can use xref:rule_system_macros[macros], making this a very powerful object. For example, the 'Modify Spam Level' actions adds detailed information about detected Spam characteristics to the `X-SPAM-LEVEL` header.
+This object is able to add or modify mail header attributes. As with
+Notifications above, you can use xref:rule_system_macros[macros],
+making this a very powerful object. For example, the 'Modify Spam
+Level' actions add detailed information about detected Spam
+characteristics to the `X-SPAM-LEVEL` header.
.'Modify Spam Level' Header Attribute
----
@@ -147,14 +151,14 @@ Remove attachments
~~~~~~~~~~~~~~~~~~
Remove attachments can either remove all attachments, or only those
-matched by the rules 'What' - object. You can also specify the
-replacement text if you want.
+matched by the rule's 'What' - object. You can also specify the
+replacement text, if you want.
-You can optionally move those mails into the attachment quarantine, where
+You can optionally move these mails into the attachment quarantine, where
the original mail with all attachments will be stored. The mail with the
-attachments removed will continue in the rule system.
+attachments removed will continue through the rule system.
-NOTE: The Attachment Quarantine Lifetime is the same as for the Spam Quarantine.
+NOTE: The Attachment Quarantine lifetime is the same as for the Spam Quarantine.
Disclaimer
@@ -168,12 +172,12 @@ its text can be encoded in the mail's character encoding.
[[pmg_mailfilter_who]]
-'Who' - objects
----------------
+'Who' objects
+-------------
[thumbnail="pmg-gui-mail-filter-who-objects.png", big=1]
-This type of objects can be used for the 'TO' and/or 'FROM' category,
+These types of objects can be used for the 'TO' and/or 'FROM' category,
and match the sender or recipient of the email. A single object can
combine multiple items, and the following item types are available:
@@ -197,24 +201,25 @@ LDAP User or Group::
Test if the mail address belongs to a specific LDAP user or group.
-We have two important 'Who' - objects called 'Blacklist' and
+We have two important 'Who' objects called 'Blacklist' and
'Whitelist'. These are used in the default ruleset to globally block
or allow specific senders.
[[pmg_mailfilter_what]]
-'What' - objects
-----------------
+'What' objects
+--------------
[thumbnail="pmg-gui-mail-filter-what-objects.png", big=1]
-'What' - objects are used to classify the mail content. A single
+'What' objects are used to classify the mail's content. A single
object can combine multiple items, and the following item types are
available:
Spam Filter::
-Matches if detected spam level is equal or greater than the configured value.
+Matches if the detected spam level is greater than or equal to the
+configured value.
Virus Filter::
@@ -222,7 +227,7 @@ Matches on infected mails.
Match Field::
-Match specified mail header fields (eg. `Subject:`, `From:`, ...)
+Match specified mail header fields (for example, `Subject:`, `From:`, ...)
Content Type Filter::
@@ -244,13 +249,13 @@ This also matches the filenames for all regular (non-archived) attachments.
[[pmg_mailfilter_when]]
-'When' - objects
-----------------
+'When' objects
+--------------
[thumbnail="pmg-gui-mail-filter-when-objects.png", big=1]
-'When' - objects are use to activate rules at specific daytimes. You
-can compose them of one or more time frame items.
+'When' objects are used to activate rules at specific times of the
+day. You can compose them from one or more time frame items.
The default ruleset defines 'Office Hours', but this is not used by
the default rules.
@@ -260,10 +265,11 @@ the default rules.
Using regular expressions
-------------------------
-A regular expression is a string of characters which tells us which
-string you are looking for. The following is a short introduction in
-the syntax of regular expressions used by some objects. If you are
-familiar with Perl, you already know the syntax.
+A regular expression is a string of characters which represents a list
+of text patterns which you would like to match. The following is a
+short introduction to the syntax of regular expressions used by some
+objects. If you are familiar with Perl, you will already know the
+syntax.
Simple regular expressions
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -285,19 +291,20 @@ The question mark (`?`) indicates that the character immediately
preceding it shows up either zero or one time. `e?mail` would match
either "email" or "mail" but not "e-mail".
-Another metacharacter is the star (`*`). This indicates that the
+Another metacharacter is the asterisk (`*`). This indicates that the
character immediately preceding it may be repeated any number of times,
-including zero. `e*mail` would match either "email" or "mail" or
+including zero. `e*mail` would match "email", "mail", and
"eeemail".
-The plus (`+`) metacharacter does the same as the star (*) excluding
-zero. So `e+mail` does not match "mail".
+The plus (`+`) metacharacter indicates that the character immediately
+preceding it appears one or more times. So `e+mail` does not match
+"mail".
-Metacharacters may be combined. A common combination includes the
-period and star metacharacters (`.*`), with the star immediately following
-the period. This is used to match an arbitrary string of any length,
-including the null string. For example: `.*company.*` matches
-"company@domain.com" or "company@domain.co.uk" or
-"department.company@domain.com".
+Metacharacters can also be combined. A common combination includes the
+period and asterisk metacharacters (`.*`), with the asterisk
+immediately following the period. This is used to match an arbitrary
+string of any length, including the null string. For example:
+`.*company.*` matches "company@domain.com" or "company@domain.co.uk"
+or "department.company@domain.com".
The book xref:Friedl97[] provides a more comprehensive introduction.
--
2.20.1
^ permalink raw reply [flat|nested] 6+ messages in thread
* [pmg-devel] [PATCH pmg-docs 3/5] Administration: language fixup
2021-06-15 10:36 [pmg-devel] [PATCH pmg-docs 1/5] configuration management: language fix-up Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 2/5] rule-based mail filter: language fixup Dylan Whyte
@ 2021-06-15 10:36 ` Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 4/5] Backup and restore: " Dylan Whyte
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Dylan Whyte @ 2021-06-15 10:36 UTC (permalink / raw)
To: pmg-devel
Improve language in the chapter 'Administration'.
Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
---
pmg-administration.adoc | 95 +++++++++++++++++++++--------------------
1 file changed, 49 insertions(+), 46 deletions(-)
diff --git a/pmg-administration.adoc b/pmg-administration.adoc
index b7de198..2eae2ba 100644
--- a/pmg-administration.adoc
+++ b/pmg-administration.adoc
@@ -1,22 +1,22 @@
Administration
==============
-The Administration GUI allows you to do common tasks
-such as updating software packages, managing quarantine, viewing service
-status, and managing mail queues. It also provides server statistics in
-order to verify server health.
+The Administration GUI allows you to carry out common tasks
+such as updating software packages, managing quarantines, viewing the
+status of services, and managing mail queues. It also provides server
+statistics, in order to verify server health.
Server Administration
---------------------
-Server status
-~~~~~~~~~~~~~
+Status
+~~~~~~
[thumbnail="pmg-gui-server-status.png", big=1]
-This page shows server statistics about CPU, memory, disk and network
-usage. You can select the displayed time span on the upper right.
+This page shows statistics about server CPU, memory, disk and network
+usage. You can select the displayed time span from the upper right.
Administrators can open a terminal window using the 'Console'
button. It is also possible to trigger a server 'Restart' or
@@ -28,9 +28,9 @@ Services
[thumbnail="pmg-gui-service-status.png", big=1]
-This panel lists all major services used for mail processing and
+This panel lists all the major services used for mail processing and
cluster synchronization. If necessary, you can start, stop or restart
-them. The 'Syslog' button shows the system log filtered for the
+them. The 'Syslog' button shows the system log, filtered for the
selected service.
Please note that {pmg} uses {systemd} to manage services, so you can
@@ -53,7 +53,7 @@ available updates, and administrators can run an upgrade by pressing
the 'Upgrade' button.
See section xref:pmg_package_repositories[Package Repositories] for
-details abaout available package repositories.
+details about the available package repositories.
Syslog and Tasks
@@ -61,9 +61,13 @@ Syslog and Tasks
[thumbnail="pmg-gui-syslog.png", big=1]
-The syslog page gives you a quick real-time log view. You can use the
+The Syslog page gives you a quick real-time log view. You can use the
xref:pmg_tracking_center[Tracking Center] to search the logs.
+The Tasks page provides a history of the administration tasks that you
+carried out on the server, such as upgrading the system. Each task
+entry provides status information about the task, as well as the
+output.
Quarantine
----------
@@ -76,16 +80,16 @@ Spam
This panel lets you inspect the mail quarantine. Emails can be safely
previewed and if desired, delivered to the original user.
-The email preview on the web interface is very secure as malicious
+The email preview on the web interface is very secure, as malicious
code (attacking your operating system or email client) is removed by
{pmg}.
Users can get access to their personalized quarantine via the daily
-spam report, or by logging in with their LDAP credentials.
+spam report or by logging in with their LDAP credentials.
You can additionally enable user self-service for sending an access link from
the Quarantine Login page.
-To enable this on the Quarantine Login page, edit `/etc/pmg/pmg.conf`, see section
+To enable this on the Quarantine Login page, edit `/etc/pmg/pmg.conf`. See section
xref:pmgconfig_spamdetector_quarantine[Spam Detector Configuration - Quarantine]
for more details about the available settings.
@@ -136,19 +140,19 @@ The result is a list of received mails, including the following data:
[cols="s,5d"]
|====
-|Time | Timestamp of first found syslog entry.
-|From | Envelope 'From' address (the sender).
-|To | The email receiver address.
-|Status | Delivery status.
-|Syslog | The corresponding syslog entries are shown if you double click such
-entry, or if you press the '+' button on the left.
+|Time | Timestamp of first syslog entry found
+|From | Envelope 'From' address (the sender)
+|To | The email receiver address
+|Status | Delivery status
+|Syslog | The corresponding syslog entries are shown if you double
+click such an entry or if you press the '+' button on the left
|====
-You can specify filters, and most importantly you can set
-a 'Start' and 'End' time. By default the start time is set to one hour
-ago. If you still get too many entries, you can try to restrict
+To narrow the search down further, you can specify filters and set
+a 'Start' and 'End' time. By default, the start time is set to the
+last hour. If you still get too many entries, you can try to restrict
the search to a specific sender or receiver address, or search for a
-specific text in the logs ('Filter' entry).
+specific text string in the logs ('Filter' entry).
NOTE: Search is faster if you use a shorter time interval.
@@ -157,25 +161,25 @@ mail proxy, meaning that the proxy receives mails from outside,
processes them and finally sends the result to the receiver.
The first phase is receiving the mail. The proxy may reject the mail
-early, or instead accepts the mail and feeds it into the filter. The filter
-rules can block or accept the mail.
+early or accept the mail and feed it into the filter. The filter
+rules can then block or accept the mail.
In the second phase, accepted mails need to be delivered to the
receiver. This action may also fail or succeed. 'Status'
-combines the result from the first and second phase.
+combines the results from the first and second phase.
[options="header",cols="2s,1d,5d"]
|====
|Status |Phase |Description
-|rejected |1 | Email rejected (e.g. sender IP is listed on a IP blacklist)
+|rejected |1 | Email rejected (for example, the sender IP is listed on an IP blacklist)
|greylisted |1 | Email temporarily rejected by greylisting
-|queued/deferred |1 | Internal Email was queued, still trying to deliver
-|queued/bounced |1 | Internal Email was queued but not accepted by the target email server (for example user unknown)
-|queued/delivered |1 | Internal Email was queued and delivered
+|queued/deferred |1 | Internal email was queued, still trying to deliver
+|queued/bounced |1 | Internal email was queued but not accepted by the target email server (for example, user unknown)
+|queued/delivered |1 | Internal email was queued and delivered
|quarantine |1 | Email was moved to quarantine
|blocked |1 | Email was blocked by filter rules
|accepted/deferred |2 | Email accepted, still trying to deliver
-|accepted/bounced |2 | Email accepted but not accepted by the target email server (for example user unknown)
+|accepted/bounced |2 | Email accepted, but not accepted by the target email server (for example, user unknown)
|accepted/delivered |2 | Email accepted and delivered
|====
@@ -186,17 +190,16 @@ Postfix Queue Administration
[thumbnail="pmg-gui-queue-admin-summary.png", big=1]
Mail-queues are one of the central concepts of the SMTP protocol. Once a
-mailserver accepts a mail for further processing it saves it to a queue.
+mail server accepts a mail for further processing it saves it to a queue.
After the mail is either relayed to another system, stored locally
or discarded, it is deleted from the local mail-queue.
If immediate processing is not possible, for example because a downstream
-mailserver is not reachable, the mail remains on the queue for later
+mail server is not reachable, the mail remains on the queue for later
processing.
The 'Queue Administration' panel provides a summary about the current state
of the postfix mail-queue, similar to the 'qshape (1)' command-line utility.
-
It shows domains for which mails were not delivered, and how long they have
been queued.
@@ -215,20 +218,20 @@ Delete all currently queued mail, for example if the queue contains only spam.
Clear the recipient verification cache.
-A sudden increase of queued mails should be checked out closely. It can
-indicate issues connecting to downstream servers.
-This can also mean that one of the servers for which you relay emails sends
-spam itself.
+A sudden increase in queued mails should be closely inspected. This
+increase can indicate issues connecting to downstream servers or that
+one of the servers for which you relay emails sends spam itself.
Deferred Mail
~~~~~~~~~~~~~
[thumbnail="pmg-gui-queue-admin-deferred.png"]
-In the 'Deferred Mail' tab you can examine each deferred email separately.
-Besides providing the contact information about sender and receiver you can
-also check the reason for an email being still queued.
+In the 'Deferred Mail' tab, you can examine each deferred email
+separately. In addition to providing contact information about the
+sender and receiver, you can also check the reason for which an email
+remains queued.
-You can view the complete headers and filter by sender or receiver of queued up
-mails.
+You can view the complete headers and filter by sender or receiver of
+queued emails.
-Here you can also flush or delete each deferred email independently.
+Here, you can also flush or delete each deferred email independently.
--
2.20.1
^ permalink raw reply [flat|nested] 6+ messages in thread
* [pmg-devel] [PATCH pmg-docs 4/5] Backup and restore: language fixup
2021-06-15 10:36 [pmg-devel] [PATCH pmg-docs 1/5] configuration management: language fix-up Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 2/5] rule-based mail filter: language fixup Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 3/5] Administration: " Dylan Whyte
@ 2021-06-15 10:36 ` Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 5/5] Cluster manager: laguage fixup Dylan Whyte
2021-06-15 12:11 ` [pmg-devel] applied-series: [PATCH pmg-docs 1/5] configuration management: language fix-up Stoiko Ivanov
4 siblings, 0 replies; 6+ messages in thread
From: Dylan Whyte @ 2021-06-15 10:36 UTC (permalink / raw)
To: pmg-devel
Language fixup for the chapter "Backup and Restore".
Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
---
pmgbackup.adoc | 47 ++++++++++++++++++++++++-----------------------
1 file changed, 24 insertions(+), 23 deletions(-)
diff --git a/pmgbackup.adoc b/pmgbackup.adoc
index be492ca..6589ecc 100644
--- a/pmgbackup.adoc
+++ b/pmgbackup.adoc
@@ -28,12 +28,13 @@ ifndef::manvolnum[]
[thumbnail="pmg-gui-backup.png", big=1]
endif::manvolnum[]
-{pmg} includes the ability to backup and restore the
+{pmg} includes the ability to back up and restore the
configuration. This includes the complete config from `/etc/pmg/`, the
-mail filter rules and the statistic database.
+mail filter rules, and the statistic database.
-NOTE: The backup does not include the network setup, and also no mail
-data from the postfix queue or the spam or virus quarantine.
+NOTE: The backup does not include the network setup, nor does it
+contain mail data from the postfix queue or the spam and virus
+quarantines.
Backups can be created locally or stored on a
https://www.proxmox.com/en/proxmox-backup-server[Proxmox Backup Server]
@@ -66,7 +67,7 @@ pmg-backup_2018_01_04_5A4E0436.tgz 21514
----
Restores are also possible using the GUI or command line, and you can
-select what parts you want to restore:
+select which parts you want to restore:
System Configuration::
@@ -101,10 +102,10 @@ restore finished
Proxmox Backup Server
---------------------
-In order to backup your {pmg} configuration on a Proxmox Backup Server you
-need configure the instance as backup 'remote'. You can then directly create
-and restore backups, as well as create a scheduled 'backup job' to run
-regular backups.
+In order to back up your {pmg} configuration on a Proxmox Backup
+Server, you first need to configure the instance as a backup 'remote'.
+You can then directly create and restore backups, as well as create a
+scheduled 'backup job' to run regular backups.
[[pmgbackup_pbs_remotes]]
Remotes
@@ -131,9 +132,9 @@ Retype new password: ******
The fingerprint is optional, if the certificate of the Proxmox Backup Server
remote is signed by a CA trusted by {pmg}.
-Additionally you can configure `prune-settings` for each remote, giving you
-flexible control about how many backups should be stored on the Proxmox Backup
-Server over a period of time.
+Additionally, you can configure `prune-settings` for each remote, giving you
+flexible control over how many backups should be stored on the Proxmox Backup
+Server over a specific period of time.
.Setting the prune options for the Proxmox Backup Server remote with id 'archive'.
----
@@ -143,11 +144,11 @@ Server over a period of time.
If prune settings are configured, the backup-group of {pmg} is pruned
automatically after each successful backup.
-The `notify` and `include-statistics` setting of a remote define the defaults
+The `notify` and `include-statistics` settings of a remote define the defaults
for notifications and whether to include the statistic database in backups.
They are also used for xref:pmgbackup_pbs_schedule[scheduled backups].
-The public settings are stored in `/etc/pmg/pbs/pbs.conf`, sensitive settings,
+The public settings are stored in `/etc/pmg/pbs/pbs.conf`. Sensitive settings,
like passwords are stored in individual files named after the remote inside
`/etc/pmg/pbs/`:
@@ -172,7 +173,7 @@ ifndef::manvolnum[]
[thumbnail="pmg-gui-pbs-backup.png", big=1]
endif::manvolnum[]
-With a configured remote you can create backups using the GUI or the
+With a configured remote, you can create backups using the GUI or the
`proxmox-backup backup` subcommand of the `pmgbackup` CLI tool.
.Creating a new backup on the Proxmox Backup Server remote with id 'archive'.
@@ -192,10 +193,10 @@ starting prune of host/pmg
prune finished
----
-For restoring you can optionally select a particular backup-snapshot to return
+For restoring, you can optionally select a particular backup-snapshot to return
to the state of configuration and rules at that time.
-On the commandline you can get first a list of available backup snapshots using
+From the command line, you can get a list of available backup snapshots using
the `proxmox-backup list` subcommand:
.Listing available backups from the Proxmox Backup Server remote with id 'archive'.
@@ -218,15 +219,15 @@ starting restore of host/pmg/2020-11-16T14:03:04Z from backup
restore finished
----
-You can remove a particular snapshot by using the `forget` sub command, this
-allows the Proxmox Backup Server to pick it up during garbage collection.
+You can remove a particular snapshot by using the `forget` subcommand. This
+allows the Proxmox Backup Server to remove it during garbage collection.
----
# pmgbackup proxmox-backup forget archive pmg 2020-11-16T14:03:04Z
----
-TIP: You can configure and access all backup related functionality on both,
-the web interface and the command line interface.
+TIP: You can configure and access all backup-related functionality on
+both the web interface and the command line interface.
[[pmgbackup_pbs_schedule]]
Scheduled Backups
@@ -241,9 +242,9 @@ delay of 15 minutes each day:
----
The randomized delay can help to prevent load-peaks on the backup server, if
-you have multiple backups, which all should start around the same time.
+you have multiple backups which should all start around the same time.
-The schedules are `systemd.timer` units. See the `systemd.time(7)` man page for
+The schedules are `systemd.timer` units. See the `systemd.time(7)` man page for
details on the time specification used.
--
2.20.1
^ permalink raw reply [flat|nested] 6+ messages in thread
* [pmg-devel] [PATCH pmg-docs 5/5] Cluster manager: laguage fixup
2021-06-15 10:36 [pmg-devel] [PATCH pmg-docs 1/5] configuration management: language fix-up Dylan Whyte
` (2 preceding siblings ...)
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 4/5] Backup and restore: " Dylan Whyte
@ 2021-06-15 10:36 ` Dylan Whyte
2021-06-15 12:11 ` [pmg-devel] applied-series: [PATCH pmg-docs 1/5] configuration management: language fix-up Stoiko Ivanov
4 siblings, 0 replies; 6+ messages in thread
From: Dylan Whyte @ 2021-06-15 10:36 UTC (permalink / raw)
To: pmg-devel
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 11820 bytes --]
general language fixup for the chapter 'Cluster Management'
Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
---
pmgcm.adoc | 109 +++++++++++++++++++++++++++--------------------------
1 file changed, 56 insertions(+), 53 deletions(-)
diff --git a/pmgcm.adoc b/pmgcm.adoc
index ec850f7..2e93d3a 100644
--- a/pmgcm.adoc
+++ b/pmgcm.adoc
@@ -25,13 +25,13 @@ Cluster Management
:pmg-toplevel:
endif::manvolnum[]
-We are living in a world where email becomes more and more important -
-failures in email systems are just not acceptable. To meet these
-requirements we developed the Proxmox HA (High Availability) Cluster.
+We are living in a world where email is becoming more and more important -
+failures in email systems are not acceptable. To meet these
+requirements, we developed the Proxmox HA (High Availability) Cluster.
-The {pmg} HA Cluster consists of a master and several slave nodes
-(minimum one slave node). Configuration is done on the master. Configuration
-and data is synchronized to all cluster nodes over a VPN tunnel. This
+The {pmg} HA Cluster consists of a master node and several slave nodes
+(minimum one slave node). Configuration is done on the master,
+and data is synchronized to all cluster nodes via a VPN tunnel. This
provides the following advantages:
* centralized configuration management
@@ -45,17 +45,17 @@ provides the following advantages:
We use a unique application level clustering scheme, which provides
extremely good performance. Special considerations were taken to make
management as easy as possible. A complete cluster setup is done within
-minutes, and nodes automatically reintegrate after temporary failures
+minutes, and nodes automatically reintegrate after temporary failures,
without any operator interaction.
image::images/Proxmox_HA_cluster_final_1024.png[]
-Hardware requirements
+Hardware Requirements
---------------------
There are no special hardware requirements, although it is highly
-recommended to use fast and reliable server with redundant disks on
+recommended to use fast and reliable server hardware, with redundant disks on
all cluster nodes (Hardware RAID with BBU and write cache enabled).
The HA Cluster can also run in virtualized environments.
@@ -69,20 +69,20 @@ for a cluster, each cluster node needs to have a valid
subscription. All nodes must have the same subscription level.
-Load balancing
+Load Balancing
--------------
It is usually advisable to distribute mail traffic among all cluster
nodes. Please note that this is not always required, because it is
also reasonable to use only one node to handle SMTP traffic. The
-second node is used as quarantine host, and only provides the web
+second node can then be used as a quarantine host, that only provides the web
interface to the user quarantine.
The normal mail delivery process looks up DNS Mail Exchange (`MX`)
records to determine the destination host. An `MX` record tells the
sending system where to deliver mail for a certain domain. It is also
-possible to have several `MX` records for a single domain, they can have
-different priorities. For example, our `MX` record looks like that:
+possible to have several `MX` records for a single domain, each of which can
+have different priorities. For example, our `MX` record looks like this:
----
# dig -t mx proxmox.com
@@ -96,7 +96,7 @@ mail.proxmox.com. 22879 IN A 213.129.239.114
Notice that there is a single `MX` record for the domain
`proxmox.com`, pointing to `mail.proxmox.com`. The `dig` command
-automatically puts out the corresponding address record if it
+automatically outputs the corresponding address record, if it
exists. In our case it points to `213.129.239.114`. The priority of
our `MX` record is set to 10 (preferred default value).
@@ -104,10 +104,10 @@ our `MX` record is set to 10 (preferred default value).
Hot standby with backup `MX` records
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Many people do not want to install two redundant mail proxies, instead
-they use the mail proxy of their ISP as fallback. This is simply done
-by adding an additional `MX` Record with a lower priority (higher
-number). With the example above this looks like that:
+Many people do not want to install two redundant mail proxies. Instead
+they use the mail proxy of their ISP as a fallback. This can be done
+by adding an additional `MX` record with a lower priority (higher
+number). Continuing from the example above, this would look like:
----
proxmox.com. 22879 IN MX 100 mail.provider.tld.
@@ -116,16 +116,16 @@ proxmox.com. 22879 IN MX 100 mail.provider.tld.
In such a setup, your provider must accept mails for your domain and
forward them to you. Please note that this is not advisable, because
spam detection needs to be done by the backup `MX` server as well, and
-external servers provided by ISPs usually don't.
+external servers provided by ISPs usually don't do this.
However, you will never lose mails with such a setup, because the sending Mail
Transport Agent (MTA) will simply deliver the mail to the backup
-server (mail.provider.tld) if the primary server (mail.proxmox.com) is
+server (mail.provider.tld), if the primary server (mail.proxmox.com) is
not available.
NOTE: Any reasonable mail server retries mail delivery if the target
-server is not available, and {pmg} stores mail and retries delivery
-for up to one week. So you will not lose mails if your mail server is
+server is not available. {pmg} stores mail and retries delivery
+for up to one week. Thus, you will not lose emails if your mail server is
down, even if you run a single server setup.
@@ -137,15 +137,16 @@ ISPs do not use advanced spam prevention techniques, or do not filter
spam at all. It is often better to run a second server yourself to
avoid lower spam detection rates.
-It’s quite simple to set up a high performance load balanced
-mail cluster using `MX` records. You need to define two `MX` records
-with the same priority. Here is a complete example to make it clearer.
+It’s quite simple to set up a high-performance, load-balanced
+mail cluster using `MX` records. You just need to define two `MX`
+records with the same priority. The rest of this section will provide
+a complete example.
-First, you need to have at least 2 working {pmg} servers
-(mail1.example.com and mail2.example.com) configured as cluster (see
-section xref:pmg_cluster_administration[Cluster administration]
-below), each having its own IP address. Let us assume the following
-DNS address records:
+First, you need to have at least two working {pmg} servers
+(mail1.example.com and mail2.example.com), configured as a cluster (see
+section xref:pmg_cluster_administration[Cluster Administration]
+below), with each having its own IP address. Let us assume the
+following DNS address records:
----
mail1.example.com. 22879 IN A 1.2.3.4
@@ -153,7 +154,7 @@ mail2.example.com. 22879 IN A 1.2.3.5
----
It is always a good idea to add reverse lookup entries (PTR
-records) for those hosts. Many email systems nowadays reject mails
+records) for those hosts, as many email systems nowadays reject mails
from hosts without valid PTR records. Then you need to define your `MX`
records:
@@ -162,8 +163,9 @@ example.com. 22879 IN MX 10 mail1.example.com.
example.com. 22879 IN MX 10 mail2.example.com.
----
-This is all you need. You will receive mails on both hosts, load-balanced using
-round-robin scheduling. If one host fails the other one is used.
+This is all you need. Following this, you will receive mail on both
+hosts, load-balanced using round-robin scheduling. If one host fails,
+the other one is used.
Other ways
@@ -172,7 +174,7 @@ Other ways
Multiple address records
^^^^^^^^^^^^^^^^^^^^^^^^
-Using several DNS `MX` records is sometimes tedious if you have many
+Using several DNS `MX` records can be tedious, if you have many
domains. It is also possible to use one `MX` record per domain, but
multiple address records:
@@ -191,14 +193,14 @@ using DNAT. See your firewall manual for more details.
[[pmg_cluster_administration]]
-Cluster administration
+Cluster Administration
----------------------
-Cluster administration can be done in the GUI or by using the command
+Cluster administration can be done from the GUI or by using the command
line utility `pmgcm`. The CLI tool is a bit more verbose, so we suggest
to use that if you run into any problems.
-NOTE: Always setup the IP configuration before adding a node to the
+NOTE: Always set up the IP configuration, before adding a node to the
cluster. IP address, network mask, gateway address and hostname can’t
be changed later.
@@ -226,8 +228,8 @@ NOTE: The node where you run the cluster create command will be the
Show Cluster Status
~~~~~~~~~~~~~~~~~~~
-The GUI shows the status of all cluster nodes, and it is also possible
-to use the command line tool:
+The GUI shows the status of all cluster nodes. You can also view this
+using the command line tool:
----
pmgcm status
@@ -254,28 +256,29 @@ the master.
pmgcm join <master_ip>
----
-You need to enter the root password of the master host when asked for
+You need to enter the root password of the master host, when asked for
a password. When joining a cluster using the GUI, you also need to
-enter the 'fingerprint' of the master node. You can get that information
+enter the 'fingerprint' of the master node. You can get this information
by pressing the `Add` button on the master node.
-CAUTION: Node initialization deletes all existing databases, stops and
-then restarts all services accessing the database. So do not add nodes
-which are already active and receive mails.
+CAUTION: Node initialization deletes all existing databases, stops all
+services accessing the database and then restarts them. Therefore, do
+not add nodes which are already active and receive mail.
-Also, joining a cluster can take several minutes, because the new node
-needs to synchronize all data from the master (although this is done
-in the background).
+Also note that joining a cluster can take several minutes, because the
+new node needs to synchronize all data from the master (although this
+is done in the background).
-NOTE: If you join a new node, existing quarantined items from the other nodes are not synchronized to the new node.
+NOTE: If you join a new node, existing quarantined items from the
+other nodes are not synchronized to the new node.
Deleting Nodes
~~~~~~~~~~~~~~
-Please detach nodes from the cluster network before removing them
-from the cluster configuration. Then run the following command on
-the master node:
+Please detach nodes from the cluster network, before removing them
+from the cluster configuration. Only then you should run the following
+command on the master node:
----
pmgcm delete <cid>
@@ -288,7 +291,7 @@ Disaster Recovery
~~~~~~~~~~~~~~~~~
It is highly recommended to use redundant disks on all cluster nodes
-(RAID). So in almost any circumstances you just need to replace the
+(RAID). So in almost any circumstance, you just need to replace the
damaged hardware or disk. {pmg} uses an asynchronous
clustering algorithm, so you just need to reboot the repaired node,
and everything will work again transparently.
@@ -332,7 +335,7 @@ pmgcm sync --master_ip <master_ip>
Total Cluster Failure
^^^^^^^^^^^^^^^^^^^^^
-* restore backup (Cluster and node information is not restored, you
+* restore backup (Cluster and node information is not restored; you
have to recreate master and nodes)
* tell it to become master
--
2.20.1
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [pmg-devel] applied-series: [PATCH pmg-docs 1/5] configuration management: language fix-up
2021-06-15 10:36 [pmg-devel] [PATCH pmg-docs 1/5] configuration management: language fix-up Dylan Whyte
` (3 preceding siblings ...)
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 5/5] Cluster manager: laguage fixup Dylan Whyte
@ 2021-06-15 12:11 ` Stoiko Ivanov
4 siblings, 0 replies; 6+ messages in thread
From: Stoiko Ivanov @ 2021-06-15 12:11 UTC (permalink / raw)
To: Dylan Whyte; +Cc: pmg-devel
applied the series. huge thanks for the effort!
On Tue, 15 Jun 2021 12:36:01 +0200
Dylan Whyte <d.whyte@proxmox.com> wrote:
> this fixes wording, spelling, grammar, etc. for the chapter
> 'configuration management'
>
> Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
> ---
> pmgconfig.adoc | 256 ++++++++++++++++++++++++-------------------------
> 1 file changed, 128 insertions(+), 128 deletions(-)
>
> diff --git a/pmgconfig.adoc b/pmgconfig.adoc
> index 67c1bd8..1ae80c3 100644
> --- a/pmgconfig.adoc
> +++ b/pmgconfig.adoc
> @@ -27,15 +27,15 @@ endif::manvolnum[]
>
> {pmg} is usually configured using the web-based Graphical User
> Interface (GUI), but it is also possible to directly edit the
> -configuration files, use the REST API over 'https'
> +configuration files, using the REST API over 'https'
> or the command line tool `pmgsh`.
>
> The command line tool `pmgconfig` is used to simplify some common
> -configuration tasks, i.e. to generate cerificates and to rewrite
> +configuration tasks, such as generating certificates and rewriting
> service configuration files.
>
> NOTE: We use a Postgres database to store mail filter rules and
> -statistic data. See chapter xref:chapter_pmgdb[Database Management]
> +statistical data. See chapter xref:chapter_pmgdb[Database Management]
> for more information.
>
>
> @@ -45,9 +45,8 @@ Configuration files overview
> `/etc/network/interfaces`::
>
> Network setup. We never modify this file directly. Instead, we write
> -changes to `/etc/network/interfaces.new`. When you reboot, we rename
> -the file to `/etc/network/interfaces`, so the changes are applied
> -on the next reboot.
> +changes to `/etc/network/interfaces.new`. When you reboot, {pmg} renames
> +the file to `/etc/network/interfaces`, thus applying the changes.
>
> `/etc/resolv.conf`::
>
> @@ -56,7 +55,7 @@ to create the FQDN and domain name used in the postfix configuration.
>
> `/etc/hostname`::
>
> -The system's host name. {pmg} uses the hostname to create the FQDN used
> +The system's hostname. {pmg} uses the hostname to create the FQDN used
> in the postfix configuration.
>
> `/etc/hosts`::
> @@ -65,7 +64,8 @@ Static table lookup for hostnames.
>
> `/etc/pmg/pmg.conf`::
>
> -Stores common administration options, i.e. the spam and mail proxy setup.
> +Stores common administration options, such as the spam and mail proxy
> +configuration.
>
> `/etc/pmg/cluster.conf`::
>
> @@ -120,15 +120,15 @@ Keys and Certificates
>
> `/etc/pmg/pmg-api.pem`::
>
> -Key and certificate (combined) used be the HTTPs server (API).
> +Key and certificate (combined) used by the HTTPS server (API).
>
> `/etc/pmg/pmg-authkey.key`::
>
> -Privat key use to generate authentication tickets.
> +Private key used to generate authentication tickets.
>
> `/etc/pmg/pmg-authkey.pub`::
>
> -Public key use to verify authentication tickets.
> +Public key used to verify authentication tickets.
>
> `/etc/pmg/pmg-csrf.key`::
>
> @@ -147,20 +147,20 @@ Key for DKIM signing mails with selector '<selector>'.
> Service Configuration Templates
> -------------------------------
>
> -{pmg} uses various services to implement mail filtering, for example
> +{pmg} uses various services to implement mail filtering, for example,
> the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
> -engine and the Apache {spamassassin} project. These services use
> -separate configuration files, so we need to rewrite those files when
> +engine, and the Apache {spamassassin} project. These services use
> +separate configuration files, so we need to rewrite those files when the
> configuration is changed.
>
> -We use a template based approach to generate those files. The {tts} is
> +We use a template-based approach to generate these files. The {tts} is
> a well known, fast and flexible template processing system. You can
> find the default templates in `/var/lib/pmg/templates/`. Please do not
> -modify them directly, because your modification would get lost on the
> +modify these directly, otherwise your modifications will be lost on the
> next update. Instead, copy the template you wish to change to
> `/etc/pmg/templates/`, then apply your changes there.
>
> -Templates can access any configuration setting, and you can use the
> +Templates can access any configuration settings, and you can use the
> `pmgconfig dump` command to get a list of all variable names:
>
> ----
> @@ -173,9 +173,9 @@ pmg.admin.advfilter = 1
> ...
> ----
>
> -The same tool is used to force regeneration of all template based
> -configuration files. You need to run that after modifying a template,
> -or when you directly edit configuration files
> +The same tool is used to force the regeneration of all template-based
> +configuration files. You need to run the following after modifying a template,
> +or when you directly edit configuration files:
>
> ----
> # pmgconfig sync --restart 1
> @@ -192,28 +192,28 @@ synced from the master node to all cluster members.
> White- and Blacklists
> ---------------------
>
> -{pmg} has multiple white- and blacklists. It differentiates between the
> -xref:pmgconfig_mailproxy_options[SMTP Whitelist]. The rule-based whitelist
> +{pmg} has multiple white- and blacklists. It differentiates between the
> +xref:pmgconfig_mailproxy_options[SMTP Whitelist], the rule-based whitelist
> and the user whitelist.
> -In addition to the whitelists there are 2 separate blacklists. The rule-based
> +In addition to the whitelists, there are two separate blacklists: the rule-based
> blacklist and the user blacklist.
>
> SMTP Whitelist
> ~~~~~~~~~~~~~~
>
> The xref:pmgconfig_mailproxy_options[SMTP Whitelist] is responsible for disabling
> -greylisting as well as SPF and DNSBL checks. These are done during the SMTP
> +greylisting, as well as SPF and DNSBL checks. These are done during the SMTP
> dialogue.
>
> Rule-based White-/Blacklist
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> The xref:chapter_mailfilter[rule-based white- and blacklists] are predefined
> -rules. They work by checking the attached 'Who' objects, containing e.g. a
> -domain or a mail address, for a match. If it matches, the assigned action is
> -used which by default is 'Accept' for the whitelist rule and 'Block' for the
> -blacklist rule. In the default setup the blacklist rule has priority over the
> -whitelist rule and spam checks.
> +rules. They work by checking the attached 'Who' objects, containing, for
> +example, a domain or a mail address for a match. If it matches, the assigned
> +action is used, which by default is 'Accept' for the whitelist rule and 'Block'
> +for the blacklist rule. In the default setup, the blacklist rule has priority
> +over the whitelist rule and spam checks.
>
> User White-/Blacklist
> ~~~~~~~~~~~~~~~~~~~~~
> @@ -221,13 +221,13 @@ User White-/Blacklist
> The user white- and blacklist are user specific. Every user can add mail addresses
> to their white- and blacklist. When a user adds a mail address to the whitelist,
> the result of the spam analysis will be discarded for that recipient. This can
> -help the mail being accepted, but it still depends on the other rules what
> -happens next. In the default setup this results in the mail being accepted for
> +help in the mail being accepted, but what happens next still depends on the
> +other rules. In the default setup, this results in the mail being accepted for
> this recipient.
>
> -For mail addresses on a user's blacklist the spam score will be increased by 100.
> -It still depends on the rule system what happens when a spam score that high is
> -encountered. In the default setup it will be recognized as spam and quarantined
> +For mail addresses on a user's blacklist, the spam score will be increased by
> +100. What happens when a high spam score is encountered still depends on the
> +rule system. In the default setup, it will be recognized as spam and quarantined
> (spam score of 3 or higher).
>
> [[pmgconfig_systemconfig]]
> @@ -241,13 +241,12 @@ ifndef::manvolnum[]
> [thumbnail="pmg-gui-network-config.png", big=1]
> endif::manvolnum[]
>
> -Normally the network and time is already configured when you visit the
> -GUI. The installer asks for those settings and sets up the correct
> -values.
> +As network and time are configured in the installer, these generally do not
> +need to be configured again in the GUI.
>
> The default setup uses a single Ethernet adapter and static IP
> assignment. The configuration is stored at '/etc/network/interfaces',
> -and the actual network setup is done the standard Debian way using
> +and the actual network setup is done the standard Debian way, using the
> package 'ifupdown'.
>
> .Example network setup '/etc/network/interfaces'
> @@ -282,7 +281,7 @@ ifndef::manvolnum[]
> endif::manvolnum[]
>
>
> -Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
> +These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
> using the following configuration keys:
>
> include::pmg.admin-conf-opts.adoc[]
> @@ -301,7 +300,7 @@ ifndef::manvolnum[]
> [thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
> endif::manvolnum[]
>
> -Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
> +These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
> using the following configuration keys:
>
> include::pmg.mail-relaying-conf-opts.adoc[]
> @@ -314,7 +313,7 @@ ifndef::manvolnum[]
> [thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1]
> endif::manvolnum[]
>
> -List of relayed mail domains, i.e. what destination domains this
> +A list of relayed mail domains, that is, what destination domains this
> system will relay mail to. The system will reject incoming mails to
> other domains.
>
> @@ -327,7 +326,7 @@ ifndef::manvolnum[]
> [thumbnail="pmg-gui-mailproxy-ports.png", big=1]
> endif::manvolnum[]
>
> -Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
> +These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
> using the following configuration keys:
>
> include::pmg.mail-ports-conf-opts.adoc[]
> @@ -341,7 +340,7 @@ ifndef::manvolnum[]
> [thumbnail="pmg-gui-mailproxy-options.png", big=1]
> endif::manvolnum[]
>
> -Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
> +These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
> using the following configuration keys:
>
> include::pmg.mail-options-conf-opts.adoc[]
> @@ -351,9 +350,9 @@ include::pmg.mail-options-conf-opts.adoc[]
> Before and After Queue scanning
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -Scanning email can happen at two different stages of mail-processing:
> +Email scanning can happen at two different stages of mail-processing:
>
> -* Before-queue filtering: During the SMTP Session, after the complete message
> +* Before-queue filtering: During the SMTP session, after the complete message
> has been received (after the 'DATA' command).
>
> * After-queue filtering: After initially accepting the mail and putting it on
> @@ -361,37 +360,37 @@ Scanning email can happen at two different stages of mail-processing:
>
> Before-queue filtering has the advantage that the system can reject a mail (by
> sending a permanent reject code '554'), and leave the task of notifying the
> -original sender to the other mailserver. This is of particular advantage if
> +original sender to the other mail server. This is of particular advantage if
> the processed mail is a spam message or contains a virus and has a forged
> -sender-address. Sending out a notification in this situation leads so-called
> +sender address. Sending out a notification in this situation leads to so-called
> 'backscatter' mail, which might cause your server to get listed as spamming on
> RBLs (Real-time Blackhole List).
>
> After-queue filtering has the advantage of providing faster delivery of
> -mails for the sending servers, since queueing mails is much faster than
> -analyzing it for spam and viruses.
> -
> -If a mail is addressed to multiple recipients (e.g. when multiple addresses are
> -subscribed to the same mailing list) the situation is more complicated: Your
> -mailserver can only reject or accept the mail for all recipients, after having
> -received the complete message, while your rule setup might accept the mail for
> -part of the recipients and reject it for others. This can be due to a
> -complicated rule setup, or if your users use the 'User White- and Blacklist'
> -feature.
> -
> -If the resulting action of the rule system is the same for all recipients {pmg}
> -responds accordingly if configured for before queue filtering (sending '554'
> +mails for the sending servers, since queuing emails is much faster than
> +analyzing them for spam and viruses.
> +
> +If a mail is addressed to multiple recipients (for example, when multiple
> +addresses are subscribed to the same mailing list), the situation is more
> +complicated; your mail server can only reject or accept the mail for all
> +recipients, after having received the complete message, while your rule setup
> +might accept the mail for part of the recipients and reject it for others. This
> +can be due to a complicated rule setup, or if your users use the 'User White-
> +and Blacklist' feature.
> +
> +If the resulting action of the rule system is the same for all recipients, {pmg}
> +responds accordingly, if configured for before-queue filtering (sending '554'
> for a blocked mail and '250' for an accepted or quarantined mail). If some
> mailboxes accept the mail and some reject it, the system has to accept the mail.
>
> Whether {pmg} notifies the sender that delivery failed for some recipients by
> sending a non-delivery report, depends on the 'ndr_on_block' setting in
> -'/etc/pmg/pmg.conf'. If enabled an NDR is sent. Keeping it disabled prevents
> +'/etc/pmg/pmg.conf'. If enabled, an NDR is sent. Keeping this disabled prevents
> NDRs being sent to the (possibly forged) sender and thus minimizes the chance
> -of getting your IP listed on a RBL. However in certain environments it can be
> +of getting your IP listed on an RBL. However in certain environments, it can be
> unacceptable not to inform the sender about a rejected mail.
>
> -The setting has the same effect if after queue filtering is configured, with
> +The setting has the same effect if after-queue filtering is configured, with
> the exception that an NDR is always sent out, even if all recipients block the
> mail, since the mail already got accepted before being analyzed.
>
> @@ -405,10 +404,10 @@ Greylisting
>
> Greylisting is a technique for preventing unwanted messages from reaching the
> resource intensive stages of content analysis (virus detection and spam
> -detection): By initially replying with a temporary failure code ('450') to
> -each new email, the {pmg} tells the sending server that it should queue the
> -mail and retry delivery at a later moment. Since certain kinds of spam get
> -sent out by software, which has no provisioning for queueing, these mails are
> +detection). By initially replying with a temporary failure code ('450') to
> +each new email, {pmg} tells the sending server that it should queue the
> +mail and retry delivery at a later point. Since certain kinds of spam get
> +sent out by software which has no provisioning for queuing, these mails are
> dropped without reaching {pmg} or your mailbox.
>
> The downside of greylisting is the delay introduced by the initial deferral of
> @@ -419,24 +418,24 @@ coming from a source for a recipient, which have passed greylisting in the
> past are directly passed on: For each email the triple '<sender network,
> sender email, recipient email>' is stored in a list, along with the time when
> delivery was attempted. If an email fits an already existing triple, the
> -timestamp for that triple is updated and the email is accepted for further
> +timestamp for that triple is updated, and the email is accepted for further
> processing.
>
> -As long as a sender and recipient do communicate frequently there is no delay
> +As long as a sender and recipient communicate frequently, there is no delay
> introduced by enabling greylisting. A triple is removed after a longer period
> -of time, when no mail fitting that triple has been seen. The timeouts in {pmg}
> +of time, if no mail fitting that triple has been seen. The timeouts in {pmg}
> are:
>
> * 2 days for the retry of the first delivery
>
> -* 36 days for known triples
> +* 36 days for a known triple
>
> -Mails with an empty envelope-sender are always delayed.
> +Mails with an empty envelope sender are always delayed.
>
> Some email service providers send out emails for one domain from multiple
> -servers. To prevent delays due to an email coming in from 2 separate IPs of
> -the same provider the triples store a network ('cidr') instead of a single IP.
> -For certain large providers the default network size might be too small. You
> +servers. To prevent delays due to an email coming in from two separate IPs of
> +the same provider, the triples store a network ('cidr') instead of a single IP.
> +For certain large providers, the default network size might be too small. You
> can configure the netmask applied to an IP for the greylist lookup in
> '/etc/pmg/pmg.conf' or in the GUI with the settings 'greylistmask' for IPv4
> and 'greylistmask6' for IPv6 respectively.
> @@ -451,13 +450,13 @@ ifndef::manvolnum[]
> endif::manvolnum[]
>
> You can use {pmg} to send emails to different internal email servers. For
> -example you can send emails addressed to domain.com to your first email server,
> +example, you can send emails addressed to domain.com to your first email server
> and emails addressed to subdomain.domain.com to a second one.
>
> You can add the IP addresses, hostname, transport protocol (smtp/lmtp),
> transport ports and mail domains (or just single email addresses) of your
> additional email servers. When transport protocol is set to `lmtp`, the option
> -'Use MX' is useless and will be automatically set to 'No'.
> +'Use MX' is useless and will automatically be set to 'No'.
>
>
> [[pmgconfig_mailproxy_networks]]
> @@ -471,8 +470,8 @@ endif::manvolnum[]
> You can add additional internal (trusted) IP networks or hosts. All hosts in
> this list are allowed to relay.
>
> -NOTE: Hosts in the same subnet with Proxmox can relay by default and it’s not
> -needed to add them in this list.
> +NOTE: Hosts in the same subnet as {pmg} can relay by default and don't need to
> +be added to this list.
>
>
> [[pmgconfig_mailproxy_tls]]
> @@ -490,24 +489,24 @@ generates a new self signed certificate for you (`/etc/pmg/pmg-tls.pem`).
>
> {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
> encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
> -server. Otherwise, messages are sent in the clear.
> +server. Otherwise, messages are sent unencrypted.
>
> You can set a different TLS policy per destination. A destination is either a
> -remote domain or a next-hop destination as specified in `/etc/pmg/transport`.
> +remote domain or a next-hop destination, as specified in `/etc/pmg/transport`.
> This can be used if you need to prevent email delivery without
> encryption, or to work around a broken 'STARTTLS' ESMTP implementation. See
> {postfix_tls_readme} for details on the supported policies.
>
> Enable TLS logging::
>
> -To get additional information about SMTP TLS activity you can enable
> -TLS logging. That way information about TLS sessions and used
> +To get additional information about SMTP TLS activity, you can enable
> +TLS logging. In this case, information about TLS sessions and used
> certificates is logged via syslog.
>
> Add TLS received header::
>
> Set this option to include information about the protocol and cipher
> -used as well as the client and issuer CommonName into the "Received:"
> +used, as well as the client and issuer CommonName into the "Received:"
> message header.
>
> Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
> @@ -526,13 +525,13 @@ endif::manvolnum[]
>
> DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
> cryptographically authenticate a mail as originating from a particular domain.
> -Before sending the mail a hash over certain header fields and the body is
> +Before sending the mail, a hash over certain header fields and the body is
> computed, signed with a private key and added in the `DKIM-Signature` header of
> the mail. The 'selector' (a short identifier chosen by you, used to identify
> which system and private key were used for signing) is also included in the
> `DKIM-Signature` header.
>
> -The verification is done by the receiver: The public key is fetched
> +The verification is done by the receiver. The public key is fetched
> via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
> for verifying the hash. You can publish multiple selectors for your domain,
> each used by a system which sends email from your domain, without the need to
> @@ -540,10 +539,10 @@ share the private key.
>
> {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
>
> -Additionally it supports conditionally signing outbound mail if configured.
> -It uses one private key and selector per PMG deployment (all nodes in a cluster
> -use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is
> -used as signing algorithm.
> +Additionally, it supports conditionally signing outbound mail, if configured.
> +It uses one private key and selector per {pmg} deployment (all nodes in a
> +cluster use the same key). The key has a minimal size of 1024 bits and
> +rsa-sha256 is used as the signing algorithm.
>
> The headers included in the signature are taken from the list of
> `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
> @@ -568,9 +567,10 @@ record which you need to add to all domains signed by {pmg} by clicking on the
> Sign all Outgoing Mail::
>
> Controls whether all outbound mail should get signed or only mails from domains
> -listed in `/etc/pmg/dkim/domains` if it exists and `/etc/pmg/domains` otherwise.
> +listed in `/etc/pmg/dkim/domains`, if it exists and `/etc/pmg/domains`
> +otherwise.
>
> -Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
> +These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
> using the following configuration keys:
>
> include::pmg.admin-dkim-conf-opts.adoc[]
> @@ -586,10 +586,10 @@ endif::manvolnum[]
> All SMTP checks are disabled for those entries (e.g. Greylisting,
> SPF, DNSBL, ...)
>
> -DNSBL checks are done by `postscreen` which works on IP addresses and networks.
> +DNSBL checks are done by `postscreen`, which works on IP addresses and networks.
> This means it can only make use of the `IP Address` and `IP Network` entries.
>
> -NOTE: If you use a backup MX server (e.g. your ISP offers this service
> +NOTE: If you use a backup MX server (for example, your ISP offers this service
> for you) you should always add those servers here.
>
> NOTE: To disable DNSBL checks entirely, remove any `DNSBL Sites` entries in
> @@ -610,7 +610,7 @@ endif::manvolnum[]
> signatures. This makes it harder for spammers to identify one aspect
> which they can craft their messages to work around the spam filter.
>
> -Every single email will be analyzed and gets a spam score
> +Every single email will be analyzed and have a spam score
> assigned. The system attempts to optimize the efficiency of the rules
> that are run in terms of minimizing the number of false positives and
> false negatives.
> @@ -631,7 +631,7 @@ email if it is ham or spam (or virus). Good emails are delivered to
> the inbox and spam messages are moved into the spam quarantine.
>
> The system can be configured to send daily reports to inform users
> -about the personal spam messages received the last day. The report is
> +about personal spam messages received in the last day. The report is
> only sent if there are new messages in the quarantine.
>
> Some options are only available in the config file `/etc/pmg/pmg.conf`,
> @@ -661,7 +661,7 @@ slightly adjusting the score of a particular rule. Two examples:
> * Your system tags many legitimate mails from a partner organization as spam,
> because the organization has a policy that each mail has to start with
> 'Dear madam or sir' (generating 1.9 points through the rule
> - 'DEAR_SOMETHING'). By setting the score of this rule to 0 you can disable
> + 'DEAR_SOMETHING'). By setting the score of this rule to 0, you can disable
> it completely.
>
> The system logs all the rules which a particular mail hits. Analyzing the logs can
> @@ -670,7 +670,7 @@ lead to finding such a pattern in your environment.
> You can adjust the score of a rule by creating a new 'Custom Rule Score' entry
> in the GUI.
>
> -NOTE: In general it is strongly recommended to not make large changes to the
> +NOTE: In general, it is strongly recommended not to make large changes to the
> default scores.
>
>
> @@ -701,7 +701,7 @@ endif::manvolnum[]
>
> Please note that the virus signature database is automatically
> updated. You can see the database status in the GUI, and also
> -trigger manual updates there.
> +trigger manual updates from there.
>
>
> [[pmgconfig_clamav_quarantine]]
> @@ -712,9 +712,9 @@ ifndef::manvolnum[]
> [thumbnail="pmg-gui-virusquar-options.png", big=1]
> endif::manvolnum[]
>
> -Indentified virus mails are automatically moved to the virus
> -quarantine. The administrator can view these mails using the GUI, and
> -choose to deliver them in case of false positives. {pmg} does not notify
> +Identified virus mails are automatically moved to the virus
> +quarantine. The administrator can view these mails from the GUI, and
> +choose to deliver them, in case of false positives. {pmg} does not notify
> individual users about received virus mails.
>
> Virus quarantine related settings are saved to subsection 'virusquar'
> @@ -728,14 +728,14 @@ Custom SpamAssassin configuration
>
> This is only for advanced users. {spamassassin}'s rules and their associated
> scores get updated regularly and are trained on a huge corpus, which gets
> -classified by experts. In most cases adding a rule for matching a particular
> +classified by experts. In most cases, adding a rule for matching a particular
> keyword is the wrong approach, leading to many false positives. Usually bad
> detection rates are better addressed by properly setting up DNS than by adding
> a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
> spam-headers - see the {spamassassin_dnsbl}.
>
> -To add or change the Proxmox {spamassassin} configuration please login to the
> -console via SSH. Change to the `/etc/mail/spamassassin/` directory. In this
> +To add or change the Proxmox {spamassassin} configuration, log in to the
> +console via SSH and change to the `/etc/mail/spamassassin/` directory. In this
> directory there are several files (`init.pre`, `local.cf`, ...) - do not change
> them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
> the xref:pmgconfig_template_engine[template engine], while the others can
> @@ -752,7 +752,7 @@ to use the correct {spamassassin} syntax, and test it with:
> If you run a cluster, the `custom.cf` file is synchronized from the
> master node to all cluster members automatically.
>
> -To adjust the score assigned to a particular rule you
> +To adjust the score assigned to a particular rule, you
> can also use the xref:pmgconfig_spamdetector_customscores[Custom Rule Score]
> settings in the GUI.
>
> @@ -774,25 +774,25 @@ treatment of an email. Its input is passed via two CLI arguments:
> * the 'queue-file-name' - a filename, which contains the complete email as
> rfc822/eml file
>
> -The expected output need to be printed on STDOUT and consists of two lines:
> +The expected output needs to be printed to STDOUT and consists of two lines:
>
> * the 'api-version' (currently 'v1') - see above
>
> * one of the following 3 results:
> -** 'OK' - email is ok
> +** 'OK' - email is OK
> ** 'VIRUS: <virusdescription>' - email is treated as if it contained a virus
> (the virus description is logged and added to the email's headers)
> ** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
> to the email's spamscore
>
> -The check is run with a 5 minute timeout - if it is exceeded the check
> +The check is run with a 5 minute timeout - if this is exceeded, the check
> executable is killed and the email is treated as OK.
>
> All output written to STDERR by the check is written with priority 'err' to the
> journal/mail.log.
>
> -A simple sample script following the API (and yielding a random result) for
> -reference:
> +Below is a simple sample script following the API (and yielding a random result)
> +for reference:
>
> ----
> #!/bin/sh
> @@ -869,7 +869,7 @@ There are four roles:
>
> Administrator::
>
> -Is allowed to manage settings of {pmg}, except some tasks like network
> +Is allowed to manage settings of {pmg}, excluding some tasks like network
> configuration and upgrading.
>
> Quarantine manager::
> @@ -886,17 +886,17 @@ Helpdesk::
>
> Combines permissions of the 'Auditor' and the 'Quarantine Manager' role.
>
> -In addition there is always the 'root' user, which is used to perform special
> +In addition, there is always the 'root' user, which is used to perform special
> system administrator tasks, such as upgrading a host or changing the network
> configuration.
>
> -NOTE: Only pam users are able to login via the webconsole and ssh, which the
> -users created with the web interface are not. Those users are created for {pmg}
> -administration only.
> +NOTE: Only PAM users are able to log in via the web interface and ssh, while the
> +users created through the web interface are not. Those users are created for
> +{pmg} administration only.
>
> Local user related settings are saved in `/etc/pmg/user.conf`.
>
> -For details of the fields see xref:pmg_user_configuration_file[user.conf]
> +For details on the fields, see xref:pmg_user_configuration_file[user.conf]
>
> [[pmgconfig_ldap]]
> LDAP/Active Directory
> @@ -912,7 +912,7 @@ Creating a profile requires (at least) the following:
> * profile name
> * protocol (LDAP or LDAPS; LDAPS is recommended)
> * at least one server
> -* a user and password (if your server does not support anonymous binds)
> +* a username and password (if your server does not support anonymous binds)
>
> All other fields should work with the defaults for most setups, but can be
> used to customize the queries.
> @@ -924,21 +924,21 @@ Bind user
> ^^^^^^^^^
>
> It is highly recommended that the user which you use for connecting to the
> -LDAP server only has the permission to query the server. For LDAP servers
> +LDAP server only has permission to query the server. For LDAP servers
> (for example OpenLDAP or FreeIPA), the username has to be of a format like
> -'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are
> -depending on your setup. For Active Directory servers, the format should be
> +'uid=username,cn=users,cn=accounts,dc=domain', where the specific fields
> +depend on your setup. For Active Directory servers, the format should be
> like 'username@domain' or 'domain\username'.
>
> Sync
> ^^^^
>
> -{pmg} synchronizes the relevant user and group info periodically, so that
> -the information is available in a fast manner, even when the LDAP/AD server
> -is temporarily not accessible.
> +{pmg} synchronizes the relevant user and group information periodically, so that
> +the information is quickly available, even when the LDAP/AD server is
> +temporarily inaccessible.
>
> After a successful sync, the groups and users should be visible on the web
> -interface. After that, you can create rules targeting LDAP users and groups.
> +interface. Following this, you can create rules targeting LDAP users and groups.
>
>
> [[pmgconfig_fetchmail]]
> @@ -947,15 +947,15 @@ Fetchmail
>
> [thumbnail="pmg-gui-fetchmail-config.png", big=1]
>
> -Fetchmail is utility for polling and forwarding emails. You can define
> +Fetchmail is a utility for polling and forwarding emails. You can define
> email accounts, which will then be fetched and forwarded to the email
> address you defined.
>
> You have to add an entry for each account/target combination you want to
> -fetch and forward. Those will then be regularly polled and forwarded,
> +fetch and forward. These will then be regularly polled and forwarded,
> according to your configuration.
>
> -The API and web interface offer following configuration options:
> +The API and web interface offer the following configuration options:
>
> include::fetchmail.conf.5-opts.adoc[]
>
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2021-06-15 12:12 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-15 10:36 [pmg-devel] [PATCH pmg-docs 1/5] configuration management: language fix-up Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 2/5] rule-based mail filter: language fixup Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 3/5] Administration: " Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 4/5] Backup and restore: " Dylan Whyte
2021-06-15 10:36 ` [pmg-devel] [PATCH pmg-docs 5/5] Cluster manager: laguage fixup Dylan Whyte
2021-06-15 12:11 ` [pmg-devel] applied-series: [PATCH pmg-docs 1/5] configuration management: language fix-up Stoiko Ivanov
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox