[pve-devel] [PATCH] Revision of the pvesr documentation

Thomas Lamprecht t.lamprecht at proxmox.com
Wed Feb 19 09:40:41 CET 2020


Wolfgang, a v2 for this would be appreciated, in case Aaron's review mail got a bit
buried at your side.

On 11/22/19 3:52 PM, Aaron Lauterer wrote:
> Some hints from my side inline.
> 
> Rephrasing some passages trying to make it easier to read and understand.
> 
> Did some sentence splitting an smaller corrections as well.
> 
> Please check if the rephrased sections are still correct from a technical POV.
> 
> 
> On 11/15/19 9:51 AM, Wolfgang Link wrote:
>> Improvement of grammar and punctuation.
>> Clarify the HA limitations.
>> Remove future tense in some sentences.
>> It is not good to use it in technical/scientific papers.
>> Rewrite some sentences to improve understanding.
>> ---
>>   pvesr.adoc | 108 ++++++++++++++++++++++++++---------------------------
>>   1 file changed, 54 insertions(+), 54 deletions(-)
>>
>> diff --git a/pvesr.adoc b/pvesr.adoc
>> index 83ab268..7934a84 100644
>> --- a/pvesr.adoc
>> +++ b/pvesr.adoc
>> @@ -31,34 +31,34 @@ local storage and reduces migration time.
>>   It replicates guest volumes to another node so that all data is available
>>   without using shared storage. Replication uses snapshots to minimize traffic
>>   sent over the network. Therefore, new data is sent only incrementally after
>> -an initial full sync. In the case of a node failure, your guest data is
>> +the initial full sync. In the case of a node failure, your guest data is
>>   still available on the replicated node.
>>   -The replication will be done automatically in configurable intervals.
>> -The minimum replication interval is one minute and the maximal interval is
>> +The replication is done automatically in configurable intervals.
>> +The minimum replication interval is one minute, and the maximal interval is
>>   once a week. The format used to specify those intervals is a subset of
>>   `systemd` calendar events, see
>>   xref:pvesr_schedule_time_format[Schedule Format] section:
>>   -Every guest can be replicated to multiple target nodes, but a guest cannot
>> -get replicated twice to the same target node.
>> +The storage replication can replicate a guest to multiple target nodes,
>> +but a guest cannot get replicated twice to the same target node.
> 
> It is possible to replicate a guest to multiple target nodes, but not twice to the same target node.
> 
>>     Each replications bandwidth can be limited, to avoid overloading a storage
>>   or server.
>>   -Virtual guest with active replication cannot currently use online migration.
>> -Offline migration is supported in general. If you migrate to a node where
>> -the guests data is already replicated only the changes since the last
>> -synchronisation (so called `delta`) must be sent, this reduces the required
>> -time significantly. In this case the replication direction will also switch
>> -nodes automatically after the migration finished.
>> +Virtual guests with active replication cannot currently use online migration.
>> +The migration offline is supported in general. If you migrate to a node where
>> +the guest's data is already replicated only the changes since the last
>> +synchronization (so called `delta`) must be sent, this reduces the required
>> +time significantly. In this case, the replication direction has switched
>> +the nodes automatically after the migration finished.
> 
> Guests with replication enabled can currently only be migrated offline. Only changes since the last replication (so called `deltas`) need to be transferred if the guest is migrated to a node to which it already is replicated. This reduces the time needed significantly. The replication direction is switched automatically if you migrate a guest to the replication target node.
> 
>>     For example: VM100 is currently on `nodeA` and gets replicated to `nodeB`.
>>   You migrate it to `nodeB`, so now it gets automatically replicated back from
>>   `nodeB` to `nodeA`.
>>     If you migrate to a node where the guest is not replicated, the whole disk
>> -data must send over. After the migration the replication job continues to
>> +data must send over. After the migration, the replication job continues to
>>   replicate this guest to the configured nodes.
>>     [IMPORTANT]
>> @@ -66,8 +66,8 @@ replicate this guest to the configured nodes.
>>   High-Availability is allowed in combination with storage replication, but it
>>   has the following implications:
>>   -* redistributing services after a more preferred node comes online will lead
>> -  to errors.
>> +* consider the live migration is currently not yet supported,
>> +  a migration error occurs when a more preferred node goes online
> 
> * live migration of replicated guests if not yet supported
>   - If a preferred node is configured the try to live migrate the guest to it, after it is back online, will fail.
> 
>>     * recovery works, but there may be some data loss between the last synced
>>     time and the time a node failed.
>> @@ -98,24 +98,25 @@ Such a calendar event uses the following format:
>>   [day(s)] [[start-time(s)][/repetition-time(s)]]
>>   ----
>>   -This allows you to configure a set of days on which the job should run.
>> -You can also set one or more start times, it tells the replication scheduler
>> +This format allows you to configure a set of days on which the job should run.
>> +You can also set one or more start times. It tells the replication scheduler
>>   the moments in time when a job should start.
>> -With this information we could create a job which runs every workday at 10
>> +With this information, we could create a job which runs every workday at 10
> 
> s/could/can/
> 
>>   PM: `'mon,tue,wed,thu,fri 22'` which could be abbreviated to: `'mon..fri
>>   22'`, most reasonable schedules can be written quite intuitive this way.
>>   -NOTE: Hours are set in 24h format.
>> +NOTE: Hours are formatted in 24-hour format.
>>   -To allow easier and shorter configuration one or more repetition times can
>> -be set. They indicate that on the start-time(s) itself and the start-time(s)
>> -plus all multiples of the repetition value replications will be done.  If
>> +To allow a convenient and shorter configuration,
>> +one or more repeat times per guest can be set.
>> +They indicate that on the start-time(s) itself and the start-time(s)
>> +plus, all multiples of the repetition value replications are done.  If
> 
> They indicate that replications are done on the start-time(s) itself and the start-time(s) plus all multiples of the repetition value.
> 
>>   you want to start replication at 8 AM and repeat it every 15 minutes until
>>   9 AM you would use: `'8:00/15'`
>>     Here you see also that if no hour separation (`:`) is used the value gets
> 
> s/also//
> 
>> -interpreted as minute. If such a separation is used the value on the left
>> -denotes the hour(s) and the value on the right denotes the minute(s).
>> +interpreted as minute. If such a separation has used the value on the left
> 
> s/has/is/  s/used/used,/
> 
>> +denotes the hour(s), and the value on the right denotes the minute(s).
>>   Further, you can use `*` to match all possible values.
>>     To get additional ideas look at
>> @@ -127,13 +128,13 @@ Detailed Specification
>>   days:: Days are specified with an abbreviated English version: `sun, mon,
>>   tue, wed, thu, fri and sat`. You may use multiple days as a comma-separated
>>   list. A range of days can also be set by specifying the start and end day
>> -separated by ``..'', for example `mon..fri`. Those formats can be also
>> +separated by ``..'', for example `mon..fri`. Those formats can also be
> 
> s/Those/These/   s/also//
> 
>>   mixed. If omitted `'*'` is assumed.
>>     time-format:: A time format consists of hours and minutes interval lists.
>> -Hours and minutes are separated by `':'`. Both, hour and minute, can be list
>> +Hours and minutes are separated by `':'`. Both hour and minute can be a list
> 
> # I would keep the commas here
> 
>>   and ranges of values, using the same format as days.
>> -First come hours then minutes, hours can be omitted if not needed, in this
>> +First, come hours then minutes, hours can be omitted if not needed, in this
> 
> First are hours, then minutes. Hours can be omitted if not needed. In this ...
> 
>>   case `'*'` is assumed for the value of hours.
>>   The valid range for values is `0-23` for hours and `0-59` for minutes.
>>   @@ -160,38 +161,37 @@ Examples:
>>   Error Handling
>>   --------------
>>   -If a replication job encounters problems it will be placed in error state.
>> -In this state the configured replication intervals get suspended
>> -temporarily. Then we retry the failed replication in a 30 minute interval,
>> -once this succeeds the original schedule gets activated again.
>> +If a replication job encounters problems, it placed in an error state.
> 
> s/it/it is/
> 
>> +In this state, the configured replication intervals get suspended
>> +temporarily. Then we retry the failed replication in a 30 minute interval.
> 
> The failed replication is repeatedly tried again in a 30 minute interval.
> 
>> +Once this succeeds, the original schedule gets activated again.
>>     Possible issues
>>   ~~~~~~~~~~~~~~~
>>   -This represents only the most common issues possible, depending on your
>> -setup there may be also another cause.
>> +Here are only the most common issues possible, depending on your
>> +setup, there may also be another cause.
> 
> Some of the most common issues are in the following list. Depending on you setup there may be another cause.
> 
>>     * Network is not working.
>>     * No free space left on the replication target storage.
>>   -* Storage with same storage ID available on target node
>> +* Storage with same storage ID available on the target node
>>   -NOTE: You can always use the replication log to get hints about a problems
>> -cause.
>> +NOTE: You can always use the replication log to get hints about problems cause.
> 
> s/about problems/about a problems/
> 
>>     Migrating a guest in case of Error
>>   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   // FIXME: move this to better fitting chapter (sysadmin ?) and only link to
>>   // it here
>>   -In the case of a grave error a virtual guest may get stuck on a failed
>> +In the case of a grave error, a virtual guest may get stuck on a failed
>>   node. You then need to move it manually to a working node again.
>>     Example
>>   ~~~~~~~
>>   -Lets assume that you have two guests (VM 100 and CT 200) running on node A
>> +Let's assume that you have two guests (VM 100 and CT 200) running on node A
>>   and replicate to node B.
>>   Node A failed and can not get back online. Now you have to migrate the guest
>>   to Node B manually.
>> @@ -204,15 +204,15 @@ to Node B manually.
>>   # pvecm status
>>   ----
>>   -- If you have no quorum we strongly advise to fix this first and make the
>> -  node operable again. Only if this is not possible at the moment you may
>> +- If you have no quorum, we strongly advise to fix this first and make the
>> +  node operable again. Only if this is not possible at the moment, you may
> 
> s/operable/operational/
> 
>>     use the following command to enforce quorum on the current node:
>>   +
>>   ----
>>   # pvecm expected 1
>>   ----
>>   -WARNING: If expected votes are set avoid changes which affect the cluster
>> +WARNING: If expected votes are set, avoid changes which affect the cluster
> 
> Avoid changes which affect the cluster if `expected votes` are set
> 
>>   (for example adding/removing nodes, storages, virtual guests)  at all costs.
>>   Only use it to get vital guests up and running again or to resolve the quorum
>>   issue itself.
>> @@ -238,48 +238,48 @@ Managing Jobs
>>     [thumbnail="screenshot/gui-qemu-add-replication-job.png"]
>>   -You can use the web GUI to create, modify and remove replication jobs
>> -easily. Additionally the command line interface (CLI) tool `pvesr` can be
>> +You can use the web GUI to create, modify, and remove replication jobs
>> +easily. Additionally, the command line interface (CLI) tool `pvesr` can be
>>   used to do this.
>>     You can find the replication panel on all levels (datacenter, node, virtual
>> -guest) in the web GUI. They differ in what jobs get shown: all, only node
>> -specific or only guest specific jobs.
>> +guest) in the web GUI. They differ in what jobs get shown:
> 
> s/what/which/
> 
>> +all, only node-specific or only guest specific jobs.
> 
> all, node- or guest-specific jobs.
>>   -Once adding a new job you need to specify the virtual guest (if not already
>> +Once adding a new job you, need to specify the virtual guest (if not already
>>   selected) and the target node. The replication
> 
> When adding a new job, you need to specify the guest if not already selected as well as the target node.
> 
>>   xref:pvesr_schedule_time_format[schedule] can be set if the default of `all
>> -15 minutes` is not desired. You may also impose rate limiting on a
>> -replication job, this can help to keep the storage load acceptable.
>> +15 minutes` is not desired. You may also impose a rate-limiting on a replication
> 
> s/also// s/rate-limiting/rate-limit/
> 
>> +job. The a rate-limiting can help to keep the storage load acceptable.
> 
> The rate limit can help to keep the load on the storage acceptable.
> 
>>   -A replication job is identified by an cluster-wide unique ID. This ID is
>> -composed of the VMID in addition to an job number.
>> +A replication job is identified by a cluster-wide unique ID. This ID is
>> +composed of the VMID in addition to a job number.
>>   This ID must only be specified manually if the CLI tool is used.
>>       Command Line Interface Examples
>>   -------------------------------
>>   -Create a replication job which will run every 5 minutes with limited bandwidth of
>> -10 mbps (megabytes per second) for the guest with guest ID 100.
>> +Create a replication job which runs every 5 minutes with limited the bandwidth
> 
> s/limited the/a limited/
> 
>> +of 10 Mbps (megabytes per second) for the guest with guest ID 100.
> 
> s/guest ID/ID/
> 
>>     ----
>>   # pvesr create-local-job 100-0 pve1 --schedule "*/5" --rate 10
>>   ----
>>   -Disable an active job with ID `100-0`
>> +Disable an active job with ID `100-0`.
>>     ----
>>   # pvesr disable 100-0
>>   ----
>>   -Enable a deactivated job with ID `100-0`
>> +Enable a deactivated job with ID `100-0`.
>>     ----
>>   # pvesr enable 100-0
>>   ----
>>   -Change the schedule interval of the job with ID `100-0` to once a hour
>> +Change the schedule interval of the job with ID `100-0` to once per hour.
>>     ----
>>   # pvesr update 100-0 --schedule '*/00'
>>
> 
> _______________________________________________
> pve-devel mailing list
> pve-devel at pve.proxmox.com
> https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
> 





More information about the pve-devel mailing list