Re: [RFR] templates://slapos.tool.format/{templates}
Christian PERRIER wrote:
> Your review should be sent as an answer to this mail.
[...]
> Template: slapformat/master_url
> Type: string
> -_Description: The HTTP or HTTPS URL where the master node can be reached:
> +_Description: Master node URL:
Just in case the admin is configuring a dozen services at once:
_Description: SlapOS master node URL:
(And I insert the word in a few other places below.)
> Maybe we could add an extended description saying something like
>
> Please enter the URL where the master node can be reached. This can
> be either an HTTP or HTTPS URL.
> .
> If you use an HTTPS URL, you must put the
> corresponding key and certificate respectively in
> /etc/slapos/ssl/slapos.key and /etc/slapos/ssl/slapos.crt.
> These files should be readable by the root user only.
>
> And thus get rid of the note that follows.
Is it really necessary for both files to be secret? Usually it's only
keys that need to be secret and the SSL .crt is mode 0644. That would
make it simpler to rephrase it like this:
If you use an HTTPS URL for the SlapOS master node, the corresponding
certificate must be placed in /etc/slapos/ssl/slapos.crt, and the key
in /etc/slapos/ssl/slapos.key, readable only to root.
> Template: slapformat/master_url_with_ssl_note
> Type: note
> -_Description: Note about HTTPS master URL
> - As you entered an HTTPS URL for the master node, you *must* put the
> +_Description: Master node key and certificate mandatory
> + As you entered an HTTPS URL for the master node, you must put the
> corresponding key and certificate respectively in
> /etc/slapos/ssl/slapos.key and /etc/slapos/ssl/slapos.crt.
> .
> - Also, make sure that the key is only readable by root user!
> + These files should be readable by the root user only.
You used an HTTPS URL for the SlapOS master node, so the corresponding
certificate must be placed in /etc/slapos/ssl/slapos.crt, and the key
in /etc/slapos/ssl/slapos.key, readable only to root.
> Template: slapformat/computer_id
> Type: string
> -_Description: ID to uniquely identifies this computer on the master:
> +_Description: ID on the master:
> + Please enter a unique identifier for this computer on the master node.
>
> Let's use an extended description
Why even mention the master here? If this is a client node, surely we
can just say:
_Description: SlapOS client ID:
Please specify a unique identifier for this SlapOS node.
(At least the package description talks about clients.)
> Template: slapformat/partition_amount
> Type: string
> -_Description: The number of partition available on this computer:
> +_Description: Number of Computer Partitions on this computer:
> A Computer Partition (CP) is an instance of a Software Release
> (SR). You can now define how many instances will be available on this
> computer.
>
> I used case for CP as this seems to be how it's meant to be.
Apparently... except:
> Note that the Software Releases will be stored in
> /var/lib/slapos/software/, whereas the Computer Partition will be
> stored in /var/lib/slapos/instance/.
If a CP *is* (an instance of) an SR, how are they stored in different
places?
> @@ -29,15 +30,14 @@
> Template: slapformat/ipv4_local_network
> Type: string
> _Description: Local IPv4 network to be used for Computer Partitions:
> - Each Computer Partition (CP) must a local IPv4 took from the network
> - given here in CIDR notation.
> + Each Computer Partition (CP) must use specific IPv4 settings. Please
> + enter these settings here, in CIDR notation.
>
> Maybe my rewrite doesn't make it clear this should be an IPv4
> *network* address.
Is it asking for a single public network, or for a whole set of
specific IP settings for Computer Partitions?
The trouble with network addresses is that everybody who hasn't been
specifically taught this jargon naturally expects "network address" to
mean "host address on the network". It's safer to avoid the term
(either as below or by saying "network base address"). Also, give the
canonical example (or should it be 10.0.0.0/24?)
Every Computer Partition must have an address on the same IPv4 network.
Please specify a network in CIDR notation (e.g.: 192.0.2.0/24).
> Template: slapformat/bridge_note
> Type: note
> +_Description: Network configuration note
> + Before using slapformat script, you must set up a network bridge
^the
> + to be used by the Computer Partitions and enable IPv6.
, and ensure IPv6 is enabled.
> .
> - You can find examples of setting it up in
> + You can find more information in
> /usr/share/doc/slapformat/README.Debian.
>
> Tentative rewrite of this note...even though I consider it abusive..:-)
(#626091)
In the control file:
> -Description: Prepare a client for deploying a SaaS system with SLAPos
> +Description: utility to prepare SLAPos SaaS clients
Everything else seems to capitalise it as SlapOS, not SLAPos. And
you've lost both uses of the word "deployment", which was a subtle
hint to the context of cloud-hosted business applications. Maybe we
could say:
Description: SaaS client deployment utility for SlapOS
> + The Slapformat utility should be used before Slapgrid in order to prepare
> + SLAPos clients. It generates a preparation report and sends needed
> + information to the SlapOS server.
>
> It's unclear to me whether this is the report that's sent to the server...
Is Slapgrid an executable that's run after slapformat? I thought it
was more a matter of slapformat being a tool to prepare a SlapOS
client for use as a grid instance... or something. Almost every
aspect of SlapOS is unclear to me, but then again the cloud *is* made
of fog. Guessing slightly and being strategically ambiguous:
This package provides a tool to prepare a SlapOS client before running
Slapgrid. It generates a report and sends the information to the
configured SlapOS server.
.
SlapOS systems are SaaS (Software as a Service) solutions.
(Such a sibilant sentence.)
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru slapformat.old/control slapformat.new/control
--- slapformat.old/control 2011-05-04 20:50:15.825256435 +0100
+++ slapformat.new/control 2011-05-09 11:16:19.369254562 +0100
@@ -21,10 +21,9 @@
bridge-utils,
uml-utilities
Breaks: ${python:Breaks}
-Description: Prepare a client for deploying a SaaS system with SLAPos
- Slapformat is supposed to be ran before Slapgrid in order to prepare
- a SLAPos client. At the end a report is generated and information are
- sent to configured SlapOS server.
+Description: SaaS client deployment utility for SlapOS
+ This package provides a tool to prepare a SlapOS client before running
+ Slapgrid. It generates a report and sends the information to the
+ configured SlapOS server.
.
- SLAPos provides support for deploying a SaaS (Software as a Service)
- system.
+ SlapOS systems are SaaS (Software as a Service) solutions.
diff -ru slapformat.old/templates slapformat.new/templates
--- slapformat.old/templates 2011-05-04 20:50:14.453258850 +0100
+++ slapformat.new/templates 2011-05-09 11:14:25.344925711 +0100
@@ -1,23 +1,22 @@
Template: slapformat/master_url
Type: string
-_Description: The HTTP or HTTPS URL where the master node can be reached:
+_Description: SlapOS master node URL:
Template: slapformat/master_url_with_ssl_note
Type: note
-_Description: Note about HTTPS master URL
- As you entered an HTTPS URL for the master node, you *must* put the
- corresponding key and certificate respectively in
- /etc/slapos/ssl/slapos.key and /etc/slapos/ssl/slapos.crt.
- .
- Also, make sure that the key is only readable by root user!
+_Description: Master node key and certificate mandatory
+ You used an HTTPS URL for the SlapOS master node, so the corresponding
+ certificate must be placed in /etc/slapos/ssl/slapos.crt, and the key
+ in /etc/slapos/ssl/slapos.key, readable only to root.
Template: slapformat/computer_id
Type: string
-_Description: ID to uniquely identifies this computer on the master:
+_Description: SlapOS client ID:
+ Please specify a unique identifier for this SlapOS node.
Template: slapformat/partition_amount
Type: string
-_Description: The number of partition available on this computer:
+_Description: Number of Computer Partitions on this computer:
A Computer Partition (CP) is an instance of a Software Release
(SR). You can now define how many instances will be available on this
computer.
@@ -29,15 +28,14 @@
Template: slapformat/ipv4_local_network
Type: string
_Description: Local IPv4 network to be used for Computer Partitions:
- Each Computer Partition (CP) must a local IPv4 took from the network
- given here in CIDR notation.
+ Every Computer Partition must have an address on the same IPv4 network.
+ Please specify a network in CIDR notation (e.g.: 192.0.2.0/24).
Template: slapformat/bridge_note
Type: note
-_Description: Note about network configuration
- Before actually using slapformat script, you *must* set up a bridge
- that will be used by the Computer Partitions and IPv6 must be
- enabled (in most cases, it is already enabled by default though).
+_Description: Network configuration note
+ Before using the slapformat script, you must set up a network bridge
+ to be used by the Computer Partitions, and ensure IPv6 is enabled.
.
- You can find examples of setting it up in
+ You can find more information in
/usr/share/doc/slapformat/README.Debian.
Template: slapformat/master_url
Type: string
_Description: SlapOS master node URL:
Template: slapformat/master_url_with_ssl_note
Type: note
_Description: Master node key and certificate mandatory
You used an HTTPS URL for the SlapOS master node, so the corresponding
certificate must be placed in /etc/slapos/ssl/slapos.crt, and the key
in /etc/slapos/ssl/slapos.key, readable only to root.
Template: slapformat/computer_id
Type: string
_Description: SlapOS client ID:
Please specify a unique identifier for this SlapOS node.
Template: slapformat/partition_amount
Type: string
_Description: Number of Computer Partitions on this computer:
A Computer Partition (CP) is an instance of a Software Release
(SR). You can now define how many instances will be available on this
computer.
.
Note that the Software Releases will be stored in
/var/lib/slapos/software/, whereas the Computer Partition will be
stored in /var/lib/slapos/instance/.
Template: slapformat/ipv4_local_network
Type: string
_Description: Local IPv4 network to be used for Computer Partitions:
Every Computer Partition must have an address on the same IPv4 network.
Please specify a network in CIDR notation (e.g.: 192.0.2.0/24).
Template: slapformat/bridge_note
Type: note
_Description: Network configuration note
Before using the slapformat script, you must set up a network bridge
to be used by the Computer Partitions, and ensure IPv6 is enabled.
.
You can find more information in
/usr/share/doc/slapformat/README.Debian.
Source: slapos.tool.format
Maintainer: Arnaud Fontaine <arnau@debian.org>
Uploaders: Python Applications Packaging Team <python-apps-team@lists.alioth.debian.org>
Section: net
Priority: optional
Build-Depends: python-setuptools (>= 0.6b3),
python (>= 2.6.6-3~),
python2.6,
debhelper (>= 7.4.3)
Build-Depends-Indep: po-debconf
Standards-Version: 3.9.2
X-Python-Version: 2.6
Homepage: http://www.slapos.org
Vcs-Svn: svn://svn.debian.org/python-apps/packages/slapos.tool.format/trunk/
Vcs-Browser: http://svn.debian.org/viewsvn/python-apps/packages/slapos.tool.format/trunk/
Package: slapformat
Architecture: all
Depends: ${misc:Depends},
${python:Depends},
bridge-utils,
uml-utilities
Breaks: ${python:Breaks}
Description: SaaS client deployment utility for SlapOS
This package provides a tool to prepare a SlapOS client before running
Slapgrid. It generates a report and sends the information to the
configured SlapOS server.
.
SlapOS systems are SaaS (Software as a Service) solutions.
Reply to: