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@pve.proxmox.com > https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel > _______________________________________________ pve-devel mailing list pve-devel@pve.proxmox.com https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
