[Pkg-iscsi-maintainers] Bug#797860: [RFR] templates://open-iscsi/{open-iscsi.templates}
Justin B Rye
justin.byam.rye at gmail.com
Fri Sep 11 11:47:25 UTC 2015
Christian PERRIER wrote:
> Your review should be sent as an answer to this mail.
> --- open-iscsi.old/debian/open-iscsi.templates 2015-09-03 07:12:44.672751389 +0200
> +++ open-iscsi/debian/open-iscsi.templates 2015-09-11 07:08:21.561599260 +0200
> @@ -1,49 +1,53 @@
> Template: open-iscsi/remove_even_with_active_sessions
> Type: boolean
> +#flag:translate!:6,8
> _Description: Do you want to proceed with removing open-iscsi?
_Description: Proceed with removing open-iscsi?
We don't care how you feel about corporate systems policy, just say
what it is.
> There are currently active iSCSI sessions. If you remove open-iscsi
> now this may lead to data loss and/or hang your system at shutdown.
s/your/the/
> .
> - DO NOT DO THIS IF YOUR ROOT FILESYSTEM IS ON ISCSI!
> + Do not do do this is this system's root filesystem is on iSCSI.
do this if this
> Though I very much understand the will to warn users, we ALWAYS
> discourage using all caps.
And exclamation marks!!1
> Also avoid "your filesystem". Why should it be "mine"? ;-)
(And we usually push "filesystem" towards "file system" in
documentation aimed at random end users; but this is aimed at people
who want a specialist FS setup, so we can expect them to be more
accustomed to the all-one-word form.)
> .
> If you do proceed, open-iscsi will try to unmount all filesystems on
> iSCSI and logout from current sessions. If that fails (because a
> - filesystem is still in use), the kernel will keep open the current
> - iSCSI sessions, but not perform any recovery in case there is an
> - interruption of the network connection (or the target is rebooted
> - etc.).
> + filesystem is still in use), the kernel will keep the current
> + iSCSI sessions opened, but will not perform any recovery in case there is an
> + interruption of the network connection (or if the target is rebooted).
> + .
> + If you really want to remove open-iscsi, you should abort here
> + and stop open-iscsi:
"In case" is a dangerously ambiguous phrase: for many (probably most)
native speakers, "it will do X in case Y" means "it will
unconditionally do X due to the danger of Y". But that doesn't seem
to make sense here... it's probably intended as "it will conditionally
do X if and only if Y". So replace "in case" with plain "if".
> I left the "if you do proceed" as, IIRC, this is meant to emphasize
> that it's probably not a good idea, but I'd like to get Justin's input
> on this.
No problems with the English there; but I'd suggest
If you really intend to remove open-iscsi, you should abort here and
then stop open-iscsi:
to make it clear that (a) we don't care about your hopes and dreams
and (b) you need to abort first and then run "service". I could also
get rid if the "you" by turning it into something like "if it is
really intended that...", but using the pronoun is much clearer. We
can't assume it's "your" computer, but the person we're addressing is
necessarily "you".
> s/open/opened
No, you can't say "keep them opened", it has to be "open" (passim).
> Dropped the "etc." that doesn't seem useful. If there are other
> reasons, then they should be listed.
Besides, it's more of an "or whatever" than an "et cetera".
> .
> - If you really want to remove open-iscsi, it is advisable to abort here
> - and to first stop open-iscsi:
> service open-iscsi stop
> + .
> If that did not clean up everything, manually umount all filesystems
> that are on iSCSI, manually dismantle the storage stack and only then
^,
> logout from all iSCSI sessions:
^
Separable verb, therefore two words - just like "cleanup"!
> + .
> iscsiadm -m node --logoutall=all
> + .
> At that point, it should be safe to remove this package.
>
> Put the untranslatable strings alone and mark them untranslatable
> (hence the "#flag" line in the template's header).
You'd think by now I would remember that this is useful.
> Template: open-iscsi/upgrade_even_with_failed_sessions
> Type: boolean
> _Description: Do you want to proceed with upgrading open-iscsi?
> - There are currently failed iSCSI sessions. Upgrading open-iscsi MAY
> + There are currently failed iSCSI sessions. Upgrading open-iscsi may
> cause data loss.
>
> Drop useless yelling
>
> .
> If you do not proceed, the preinstallation script will be aborted and
> you will have the option to manually recover the iSCSI sessions. (Note
> that aborting an upgrade is problematic if you are dist-upgrading your
> entire system.) You may also recover the iSCSI sessions manually while
> - keeping this prompt open and then choose to proceed. Or you may choose
> + keeping this prompt opened and then choose to proceed. Or you may choose
> to proceed directly, after which iscsid will be restarted and session
> recovery will be attempted once more.
>
> Template: open-iscsi/upgrade_recovery_error
> -Type: note
> +Type: error
>
> That note is rather "error" than "note"
A red background is the standards-compliant way of yelling...
> _Description: iSCSI recovery error on upgrade
> - iscsid was restarted, but couldn't recover all iSCSI sessions. This is
> - bad and could lead to DATA LOSS. Please check your system and kernel
> + The iscsid daemon was restarted, but couldn't recover all iSCSI sessions. This is
> + bad and could lead to data loss. Please check the system and kernel
> logs to determine the cause of the issue.
> .
> - Please DO NOT acknowledge this note until you have fixed the problem
> + Please do not acknowledge this note until you have fixed the problem
> from a separate login shell.
Technically I don't need to fix the problem from a separate login
shell; I could even safely suspend my screen session and fix the
problem from my *current* non-login xterm. But I can't think of a way
of expressing that generically, and besides, I know *I* would do an
open-iscsi upgrade from a VT login.
[...]
> Template: open-iscsi/downgrade_and_break_system
> @@ -51,7 +55,7 @@
> _Description: Do you really want to downgrade open-iscsi?
Why not like the first?
_Description: Proceed with downgrading open-iscsi?
(Though I really hope this isn't corporate systems policy!)
I'm surprised it checks for this - I'm used to the idea that
downgrades being unsupported (and purge-and-reinstall being the safe
alternative) is just the general rule in Debian. In fact I would
assume anybody who tried downgrading something this crucial was crazy,
but it's nice that we're covering this scenario.
> You are trying to downgrade open-iscsi. Because of changes between the
> version you are downgrading to and the version currently installed,
Which is clearer, this or:
You are trying to downgrade open-iscsi. Because of differences between
the version currently installed and the one you are downgrading to,
I think I'll leave it.
> - this downgrade WILL BREAK YOUR SYSTEM.
> + this downgrade will break the system.
> .
> If you really want to downgrade, please follow the following procedure
> instead: umount all iSCSI file systems, log out of all iSCSI sessions,
>
> And again (and s/your/the)
Again s/want to/intend to/
> back up /etc/iscsi, purge open-iscsi and reinstall the older version.
^
Harvard comma.
Meanwhile in the control file:
> Package: open-iscsi
> Architecture: any
> Depends: ${shlibs:Depends}, ${misc:Depends}, udev
> Pre-Depends: debconf | debconf-2.0
> Description: High performance, transport independent iSCSI implementation
This is upstream's description of the project as a whole, mostly
focussing on its kernel side; it doesn't work very well as a summary
of this package. "Implementation" is one of those words (like
"open-source" and "software") that's a waste of space in a synopsis -
everything's an implementation of some idea or other. Since all of
this blurb is immediately repeated in the first line of the long
description I would suggest trimming the synopsis right down to
something that actually says what's in the package:
Description: iSCSI management tools
> Open-iSCSI is a high-performance, transport independent, multi-platform
> implementation of RFC3720 iSCSI
This needs more, if only punctuation! Handily enough there's an
expansion of iSCSI (if not exactly an explanation) in the RFC name, so
we could call it an
implementation of the RFC3720 Internet Small Computer Systems Interface
(iSCSI).
The following explanation suffers from the common problem that the
upstream developers are mostly thinking in terms of the kernel module,
while this packaged software is a normal admin toolkit, with users who
have no special reason to think about the kernelspace/userspace split.
Apparently open-iscsi tries to put more of the control plane into
userspace; but that translates out of developerese as "it provides
more admin tools". Still, I won't try to fix this.
> .
> Open-iSCSI is partitioned into user and kernel parts where the kernel
> portion implements iSCSI data path (i.e. iSCSI Read and iSCSI Write)
> The userspace contains the entire control plane consisting of:
> * Configuration Manager
> * iSCSI Discovery, Login and Logout processing
> * Connection level error processing
> * Nop-In and Nop-Out handling
> * Text processing, iSNS, SLP, Radius et cetera (future)
The http://www.open-iscsi.org/docs/README version has some phrasing
improvements - import those and apply d-l-e house style on top.
Open-iSCSI is partitioned into user and kernel parts, where the kernel
portion implements the iSCSI data path (i.e. iSCSI Read and iSCSI Write).
The userspace contains the entire control plane:
* Configuration Manager;
* iSCSI Discovery;
* Login and Logout processing;
* Connection level error processing;
* Nop-In and Nop-Out handling;
* (in the future) Text processing, iSNS, SLP, Radius, etc.
(The strange capitalisation seems to be part of the standard.)
> .
> The userspace component consists of a daemon, iscsid and a management
> utility, iscsiadm
No, that's one more "userspace" reference than I'm willing to let
through. And I count five executables... so we should avoid implying
that this is an exhaustive list:
This package includes a daemon, iscsid, and a management utility,
iscsiadm.
> Package: open-iscsi-udeb
> # Note: the (virtual) udeb package scsi-modules (provided by different
> # linux kernel udebs) must exist for these architectures - so
> # check that before adding them to this list; the other
> # scsi-(core|common|...)-modules are NOT sufficient!
> Architecture: amd64 arm64 i386 ia64 mips mipsel powerpc s390x ppc64el ppc64 armhf
> Section: debian-installer
> Package-Type: udeb
> Depends: ${shlibs:Depends}, ${misc:Depends}, scsi-modules, libnss-files-udeb
> Description: Configure iSCSI
> Open-iSCSI is a high-performance, transport independent, multi-platform
> implementation of RFC3720 iSCSI.
As above.
> .
> This is the minimal package (udeb) used by debian-installer.
>
> #Package: linux-iscsi-modules-source
> #Architecture: all
> #Depends: ${shlibs:Depends}, ${misc:Depends}, module-assistant, debhelper (>= 4.0.0), bzip2
> #Description: Source Code for the Linux iSCSI Kernel Modules
> # Along with make-kpkg, this package maybe used to build a linux-iscsi-modules
> # package for a kernel-image package.
This looks stale... I'll leave it.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
-------------- next part --------------
diff -ru open-iscsi-2.0.873+git0.3b4b4500.pristine/debian/control open-iscsi-2.0.873+git0.3b4b4500/debian/control
--- open-iscsi-2.0.873+git0.3b4b4500.pristine/debian/control 2015-08-29 09:14:14.000000000 +0100
+++ open-iscsi-2.0.873+git0.3b4b4500/debian/control 2015-09-11 12:14:30.691456168 +0100
@@ -13,21 +13,23 @@
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}, udev
Pre-Depends: debconf | debconf-2.0
-Description: High performance, transport independent iSCSI implementation
+Description: iSCSI management tools
Open-iSCSI is a high-performance, transport independent, multi-platform
- implementation of RFC3720 iSCSI
+ implementation of the RFC3720 Internet Small Computer Systems Interface
+ (iSCSI).
.
- Open-iSCSI is partitioned into user and kernel parts where the kernel
- portion implements iSCSI data path (i.e. iSCSI Read and iSCSI Write)
- The userspace contains the entire control plane consisting of:
- * Configuration Manager
- * iSCSI Discovery, Login and Logout processing
- * Connection level error processing
- * Nop-In and Nop-Out handling
- * Text processing, iSNS, SLP, Radius et cetera (future)
+ Open-iSCSI is partitioned into user and kernel parts, where the kernel
+ portion implements the iSCSI data path (i.e. iSCSI Read and iSCSI Write).
+ The userspace contains the entire control plane:
+ * Configuration Manager;
+ * iSCSI Discovery;
+ * Login and Logout processing;
+ * Connection level error processing;
+ * Nop-In and Nop-Out handling;
+ * (in the future) Text processing, iSNS, SLP, Radius, etc.
.
- The userspace component consists of a daemon, iscsid and a management
- utility, iscsiadm
+ This package includes a daemon, iscsid, and a management utility,
+ iscsiadm.
Package: open-iscsi-udeb
# Note: the (virtual) udeb package scsi-modules (provided by different
@@ -40,7 +42,8 @@
Depends: ${shlibs:Depends}, ${misc:Depends}, scsi-modules, libnss-files-udeb
Description: Configure iSCSI
Open-iSCSI is a high-performance, transport independent, multi-platform
- implementation of RFC3720 iSCSI.
+ implementation of the RFC3720 Internet Small Computer Systems Interface
+ (iSCSI).
.
This is the minimal package (udeb) used by debian-installer.
@@ -50,4 +53,3 @@
#Description: Source Code for the Linux iSCSI Kernel Modules
# Along with make-kpkg, this package maybe used to build a linux-iscsi-modules
# package for a kernel-image package.
-
diff -ru open-iscsi-2.0.873+git0.3b4b4500.pristine/debian/open-iscsi.templates open-iscsi-2.0.873+git0.3b4b4500/debian/open-iscsi.templates
--- open-iscsi-2.0.873+git0.3b4b4500.pristine/debian/open-iscsi.templates 2015-08-29 09:14:14.000000000 +0100
+++ open-iscsi-2.0.873+git0.3b4b4500/debian/open-iscsi.templates 2015-09-11 12:33:52.281669203 +0100
@@ -1,31 +1,35 @@
Template: open-iscsi/remove_even_with_active_sessions
Type: boolean
-_Description: Do you want to proceed with removing open-iscsi?
+#flag:translate!:6,8
+_Description: Proceed with removing open-iscsi?
There are currently active iSCSI sessions. If you remove open-iscsi
- now this may lead to data loss and/or hang your system at shutdown.
+ now this may lead to data loss and/or hang the system at shutdown.
.
- DO NOT DO THIS IF YOUR ROOT FILESYSTEM IS ON ISCSI!
+ Do not do this if this system's root filesystem is on iSCSI.
.
If you do proceed, open-iscsi will try to unmount all filesystems on
- iSCSI and logout from current sessions. If that fails (because a
- filesystem is still in use), the kernel will keep open the current
- iSCSI sessions, but not perform any recovery in case there is an
- interruption of the network connection (or the target is rebooted
- etc.).
+ iSCSI and log out from current sessions. If that fails (because a
+ filesystem is still in use), the kernel will keep the current
+ iSCSI sessions open, but will not perform any recovery if there is an
+ interruption of the network connection (or if the target is rebooted).
+ .
+ If you really intend to remove open-iscsi, you should abort here and
+ then stop open-iscsi:
.
- If you really want to remove open-iscsi, it is advisable to abort here
- and to first stop open-iscsi:
service open-iscsi stop
+ .
If that did not clean up everything, manually umount all filesystems
- that are on iSCSI, manually dismantle the storage stack and only then
- logout from all iSCSI sessions:
+ that are on iSCSI, manually dismantle the storage stack, and only then
+ log out from all iSCSI sessions:
+ .
iscsiadm -m node --logoutall=all
+ .
At that point, it should be safe to remove this package.
Template: open-iscsi/upgrade_even_with_failed_sessions
Type: boolean
-_Description: Do you want to proceed with upgrading open-iscsi?
- There are currently failed iSCSI sessions. Upgrading open-iscsi MAY
+_Description: Proceed with upgrading open-iscsi?
+ There are currently failed iSCSI sessions. Upgrading open-iscsi may
cause data loss.
.
If you do not proceed, the preinstallation script will be aborted and
@@ -37,22 +41,22 @@
recovery will be attempted once more.
Template: open-iscsi/upgrade_recovery_error
-Type: note
+Type: error
_Description: iSCSI recovery error on upgrade
- iscsid was restarted, but couldn't recover all iSCSI sessions. This is
- bad and could lead to DATA LOSS. Please check your system and kernel
+ The iscsid daemon was restarted, but couldn't recover all iSCSI sessions.
+ This is bad and could lead to data loss. Please check the system and kernel
logs to determine the cause of the issue.
.
- Please DO NOT acknowledge this note until you have fixed the problem
+ Please do not acknowledge this note until you have fixed the problem
from a separate login shell.
Template: open-iscsi/downgrade_and_break_system
Type: boolean
-_Description: Do you really want to downgrade open-iscsi?
+_Description: Proceed with downgrading open-iscsi?
You are trying to downgrade open-iscsi. Because of changes between the
version you are downgrading to and the version currently installed,
- this downgrade WILL BREAK YOUR SYSTEM.
+ this downgrade will break the system.
.
- If you really want to downgrade, please follow the following procedure
+ If you really intend to downgrade, please follow the following procedure
instead: umount all iSCSI file systems, log out of all iSCSI sessions,
- back up /etc/iscsi, purge open-iscsi and reinstall the older version.
+ back up /etc/iscsi, purge open-iscsi, and reinstall the older version.
-------------- next part --------------
Template: open-iscsi/remove_even_with_active_sessions
Type: boolean
#flag:translate!:6,8
_Description: Proceed with removing open-iscsi?
There are currently active iSCSI sessions. If you remove open-iscsi
now this may lead to data loss and/or hang the system at shutdown.
.
Do not do this if this system's root filesystem is on iSCSI.
.
If you do proceed, open-iscsi will try to unmount all filesystems on
iSCSI and log out from current sessions. If that fails (because a
filesystem is still in use), the kernel will keep the current
iSCSI sessions open, but will not perform any recovery if there is an
interruption of the network connection (or if the target is rebooted).
.
If you really intend to remove open-iscsi, you should abort here and
then stop open-iscsi:
.
service open-iscsi stop
.
If that did not clean up everything, manually umount all filesystems
that are on iSCSI, manually dismantle the storage stack, and only then
log out from all iSCSI sessions:
.
iscsiadm -m node --logoutall=all
.
At that point, it should be safe to remove this package.
Template: open-iscsi/upgrade_even_with_failed_sessions
Type: boolean
_Description: Proceed with upgrading open-iscsi?
There are currently failed iSCSI sessions. Upgrading open-iscsi may
cause data loss.
.
If you do not proceed, the preinstallation script will be aborted and
you will have the option to manually recover the iSCSI sessions. (Note
that aborting an upgrade is problematic if you are dist-upgrading your
entire system.) You may also recover the iSCSI sessions manually while
keeping this prompt open and then choose to proceed. Or you may choose
to proceed directly, after which iscsid will be restarted and session
recovery will be attempted once more.
Template: open-iscsi/upgrade_recovery_error
Type: error
_Description: iSCSI recovery error on upgrade
The iscsid daemon was restarted, but couldn't recover all iSCSI sessions.
This is bad and could lead to data loss. Please check the system and kernel
logs to determine the cause of the issue.
.
Please do not acknowledge this note until you have fixed the problem
from a separate login shell.
Template: open-iscsi/downgrade_and_break_system
Type: boolean
_Description: Proceed with downgrading open-iscsi?
You are trying to downgrade open-iscsi. Because of changes between the
version you are downgrading to and the version currently installed,
this downgrade will break the system.
.
If you really intend to downgrade, please follow the following procedure
instead: umount all iSCSI file systems, log out of all iSCSI sessions,
back up /etc/iscsi, purge open-iscsi, and reinstall the older version.
-------------- next part --------------
Source: open-iscsi
Section: net
Priority: optional
Maintainer: Debian iSCSI Maintainers <pkg-iscsi-maintainers at lists.alioth.debian.org>
Uploaders: Ritesh Raj Sarraf <rrs at debian.org>, Christian Seiler <christian at iwakd.de>
Build-Depends: debhelper (>= 9), bzip2, bison, flex, autotools-dev, dh-autoreconf, dh-exec, dpkg-dev (>= 1.16.1~), po-debconf, dh-systemd
Standards-Version: 3.9.6
Vcs-Git: git://anonscm.debian.org/pkg-iscsi/open-iscsi.git
Vcs-Browser: http://anonscm.debian.org/gitweb/?p=pkg-iscsi/open-iscsi.git
Homepage: http://www.open-iscsi.org/
Package: open-iscsi
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}, udev
Pre-Depends: debconf | debconf-2.0
Description: iSCSI management tools
Open-iSCSI is a high-performance, transport independent, multi-platform
implementation of the RFC3720 Internet Small Computer Systems Interface
(iSCSI).
.
Open-iSCSI is partitioned into user and kernel parts, where the kernel
portion implements the iSCSI data path (i.e. iSCSI Read and iSCSI Write).
The userspace contains the entire control plane:
* Configuration Manager;
* iSCSI Discovery;
* Login and Logout processing;
* Connection level error processing;
* Nop-In and Nop-Out handling;
* (in the future) Text processing, iSNS, SLP, Radius, etc.
.
This package includes a daemon, iscsid, and a management utility,
iscsiadm.
Package: open-iscsi-udeb
# Note: the (virtual) udeb package scsi-modules (provided by different
# linux kernel udebs) must exist for these architectures - so
# check that before adding them to this list; the other
# scsi-(core|common|...)-modules are NOT sufficient!
Architecture: amd64 arm64 i386 ia64 mips mipsel powerpc s390x ppc64el ppc64 armhf
Section: debian-installer
Package-Type: udeb
Depends: ${shlibs:Depends}, ${misc:Depends}, scsi-modules, libnss-files-udeb
Description: Configure iSCSI
Open-iSCSI is a high-performance, transport independent, multi-platform
implementation of the RFC3720 Internet Small Computer Systems Interface
(iSCSI).
.
This is the minimal package (udeb) used by debian-installer.
#Package: linux-iscsi-modules-source
#Architecture: all
#Depends: ${shlibs:Depends}, ${misc:Depends}, module-assistant, debhelper (>= 4.0.0), bzip2
#Description: Source Code for the Linux iSCSI Kernel Modules
# Along with make-kpkg, this package maybe used to build a linux-iscsi-modules
# package for a kernel-image package.
More information about the Pkg-iscsi-maintainers
mailing list