[pmg-devel] applied-series: [PATCH pmg-docs 1/4] service daemons: language fixup

[Stoiko Ivanov <s.ivanov@proxmox.com>]

Huge Thanks for taking the time to improve the docs!!

applied all 4 patches.

the improvments for pmgproxy.adoc and pmg-ssl-certificate.adoc
should at some point also be carried over to pve-docs (where they were
orignally taken from)

thinking about it - we might consider eventually adding a dedicated
repository for shared documentation and then use that in all products
(maybe with some sed preprocessing)




On Tue, 13 Jul 2021 17:54:03 +0200
Dylan Whyte <d.whyte@proxmox.com> wrote:

> Very minor language updates to the "Important Service Daemons" section
> of the docs
> 
> Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
> ---
>  pmg-smtp-filter.adoc |  8 ++++----
>  pmgdaemon.adoc       |  2 +-
>  pmgmirror.adoc       |  2 +-
>  pmgpolicy.adoc       |  4 ++--
>  pmgproxy.adoc        | 41 +++++++++++++++++++++--------------------
>  pmgtunnel.adoc       |  6 +++---
>  6 files changed, 32 insertions(+), 31 deletions(-)
> 
> diff --git a/pmg-smtp-filter.adoc b/pmg-smtp-filter.adoc
> index 153178e..58033e4 100644
> --- a/pmg-smtp-filter.adoc
> +++ b/pmg-smtp-filter.adoc
> @@ -23,14 +23,14 @@ pmg-smtp-filter - Proxmox SMTP Filter Daemon
>  ============================================
>  endif::manvolnum[]
>  
> -This is the Proxmox SMTP filter daemon, which does the actual spam
> -filtering using the SpamAssassin and the rule database. It listens on
> +The Proxmox SMTP Filter Daemon does the actual spam
> +filtering, using {spamassassin} and the rule database. It listens on
>  127.0.0.1:10023 and 127.0.0.1:10024. The daemon listens to a local
> -address only, so you cannot access it from outside.
> +address only, so you cannot access it from the outside.
>  
>  With our postfix configuration, incoming mails are sent to
>  127.0.0.1:10024. Outgoing (trusted) mails are sent to
> -127.0.0.1:10023. After filtering, mails are reinjected into postfix at
> +127.0.0.1:10023. After filtering, mails are resent to Postfix at
>  127.0.0.1:10025.
>  
>  
> diff --git a/pmgdaemon.adoc b/pmgdaemon.adoc
> index a809c02..4e9e03b 100644
> --- a/pmgdaemon.adoc
> +++ b/pmgdaemon.adoc
> @@ -27,7 +27,7 @@ This daemon exposes the whole {pmg} API on `127.0.0.1:85`. It runs as
>  `root` and has permission to do all privileged operations.
>  
>  NOTE: The daemon listens to a local address only, so you cannot access
> -it from outside. The `pmgproxy` daemon exposes the API to the outside
> +it from the outside. The `pmgproxy` daemon exposes the API to the outside
>  world.
>  
>  
> diff --git a/pmgmirror.adoc b/pmgmirror.adoc
> index 2f2c12d..80d69c3 100644
> --- a/pmgmirror.adoc
> +++ b/pmgmirror.adoc
> @@ -23,7 +23,7 @@ pmgmirror - Database Mirror Daemon
>  ==================================
>  endif::manvolnum[]
>  
> -{pmg} uses an application specific asynchronous replication
> +{pmg} uses an application-specific, asynchronous replication
>  algorithm to replicate the database to all cluster nodes.
>  
>  The daemon uses the ssh tunnel provided by 'pmgtunnel' to access
> diff --git a/pmgpolicy.adoc b/pmgpolicy.adoc
> index 813ed9e..1dbc0fb 100644
> --- a/pmgpolicy.adoc
> +++ b/pmgpolicy.adoc
> @@ -25,8 +25,8 @@ endif::manvolnum[]
>  
>  This daemon implements the Postfix SMTP access policy delegation
>  protocol on `127.0.0.1:10022`. It listens to a local address
> -only, so you cannot access it from outside. We configure Postfix to
> -use this service for greylisting and as SPF policy server.
> +only, so you cannot access it from the outside. We configure Postfix to
> +use this service for greylisting and as an SPF policy server.
>  
>  
>  ifdef::manvolnum[]
> diff --git a/pmgproxy.adoc b/pmgproxy.adoc
> index d5c1112..6e48fba 100644
> --- a/pmgproxy.adoc
> +++ b/pmgproxy.adoc
> @@ -23,12 +23,12 @@ pmgproxy - Proxmox Mail Gateway API Proxy Daemon
>  ================================================
>  endif::manvolnum[]
>  
> -This daemon exposes the whole {pmg} API on TCP port 8006 using
> +This daemon exposes the whole {pmg} API on TCP port 8006, using
>  HTTPS. It runs as user `www-data` and has very limited permissions.
>  Operations requiring more permissions are forwarded to the local
>  `pmgdaemon`.
>  
> -Requests targeted for other nodes are automatically forwarded to those
> +Requests targeted at other nodes are automatically forwarded to those
>  nodes. This means that you can manage your whole cluster by connecting
>  to a single {pmg} node.
>  
> @@ -76,18 +76,18 @@ By default the `pmgproxy` daemon listens on the wildcard address and accepts
>  connections from both IPv4 and IPv6 clients.
>  
>  
> -By setting `LISTEN_IP` in `/etc/default/pmgproxy` you can control to which IP
> -address the `pmgproxy` daemon binds. The IP-address needs to be configured on
> +By setting `LISTEN_IP` in `/etc/default/pmgproxy`, you can control which IP
> +address the `pmgproxy` daemon binds to. The IP-address needs to be configured on
>  the system.
>  
>  Setting the `sysctl` `net.ipv6.bindv6only` to the non-default `1` will cause
> -the daemons to only accept connection from IPv6 clients, while  usually also
> -causing lots of other issues. If you set this configuration we recommend to
> -either remove the `sysctl` setting, or set the `LISTEN_IP` to `0.0.0.0` (which
> -will only allow IPv4 clients).
> +the daemons to only accept connections from IPv6 clients, while usually also
> +causing lots of other issues. If you set this configuration, we recommend either
> +removing the `sysctl` setting, or setting the `LISTEN_IP` to `0.0.0.0` (which
> +will allow only IPv4 clients).
>  
> -`LISTEN_IP` can be used to only to restricting the socket to an internal
> -interface and thus have less exposure to the public internet, for example:
> +`LISTEN_IP` can be used to restrict the socket to an internal
> +interface, thus leaving less exposure to the public internet, for example:
>  
>  ----
>  LISTEN_IP="192.0.2.1"
> @@ -107,8 +107,8 @@ LISTEN_IP="fe80::c463:8cff:feb9:6a4e%vmbr0"
>  ----
>  
>  WARNING: The nodes in a cluster need access to `pmgproxy` for communication,
> -possibly on different sub-nets. It is **not recommended** to set `LISTEN_IP` on
> -clustered systems.
> +possibly across different subnets. It is **not recommended** to set `LISTEN_IP`
> +on clustered systems.
>  
>  To apply the change you need to either reboot your node or fully restart the
>  `pmgproxy` service:
> @@ -118,24 +118,24 @@ systemctl restart pmgproxy.service
>  ----
>  
>  NOTE: Unlike `reload`, a `restart` of the pmgproxy service can interrupt some
> -long-running worker processes, for example a running console.So, please use a
> -maintenance window to bring this change in effect.
> +long-running worker processes, for example, a running console. Therefore, you
> +should set a maintenance window to bring this change into effect.
>  
>  
>  SSL Cipher Suite
>  ----------------
>  
> -You can define the cipher list in `/etc/default/pmgproxy`, for example
> +You can define the cipher list in `/etc/default/pmgproxy`, for example:
>  
>   CIPHERS="ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
>  
> -Above is the default. See the `ciphers(1)` man page from the `openssl`
> +The above is the default. See the `ciphers(1)` man page from the `openssl`
>  package for a list of all available options.
>  
> -The first of these ciphers, available to both the client and the `pmgproxy`,
> +The first of these ciphers that is available to both the client and `pmgproxy`
>  will be used.
>  
> -Additionally you can allow the client to choose the cipher from the list above
> +Additionally, you can allow the client to choose the cipher from the list above,
>  by disabling the HONOR_CIPHER_ORDER option in `/etc/default/pmgproxy`:
>  
>   HONOR_CIPHER_ORDER=0
> @@ -146,7 +146,7 @@ Diffie-Hellman Parameters
>  
>  You can define the used Diffie-Hellman parameters in
>  `/etc/default/pmgproxy` by setting `DHPARAMS` to the path of a file
> -containing DH parameters in PEM format, for example
> +containing DH parameters in PEM format, for example:
>  
>   DHPARAMS="/path/to/dhparams.pem"
>  
> @@ -160,7 +160,8 @@ COMPRESSION
>  -----------
>  
>  By default `pmgproxy` uses gzip HTTP-level compression for compressible
> -content if the client supports it. This can be disabled in `/etc/default/pmgproxy`
> +content, if the client supports it. This can be disabled in
> +`/etc/default/pmgproxy`
>  
>   COMPRESSION=0
>  
> diff --git a/pmgtunnel.adoc b/pmgtunnel.adoc
> index 6847c69..792043e 100644
> --- a/pmgtunnel.adoc
> +++ b/pmgtunnel.adoc
> @@ -23,10 +23,10 @@ pmgtunnel - Cluster Tunnel Daemon
>  =================================
>  endif::manvolnum[]
>  
> -This daemon creates a ssh tunnel to the postgres database in other
> +This daemon creates an ssh tunnel to the Postgres databases on other
>  cluster nodes (port 5432). The tunnel is used to synchronize the
> -database using an application specific asynchronous replication
> -algorythm.
> +database, using an application-specific, asynchronous replication
> +algorithm.
>  
>  ifdef::manvolnum[]
>  include::pmg-copyright.adoc[]