[libvirt] [PATCH 0/6] Additional iSCSI/chap changes
These patches address a couple of issues I ran into while doing extra testing on the iSCSI chap authentication patches: https://www.redhat.com/archives/libvir-list/2013-July/msg01378.html The first 2 or 3 patches should be candidiates to be put into rhel7.0 as updates/fixes to issues. The last 3 patches update the documentation to show how to use secrets, pools, and iSCIS devices in the domain. John Ferlan (6): virsh: Print cephx and iscsi usage qemu_conf: Fix broken logic for adding passthrough iscsi lun Report secret usage error message similarly docs: Update the formatdomain disk examples docs: Update formatsecrets to include more examples of each type docs: Update iSCSI storage pool example docs/formatdomain.html.in | 57 +++++++++++-- docs/formatsecret.html.in | 156 +++++++++++++++++++++++++++++++++--- docs/formatstorage.html.in | 5 +- src/qemu/qemu_command.c | 28 +++++-- src/qemu/qemu_conf.c | 2 +- src/storage/storage_backend_iscsi.c | 28 +++++-- src/storage/storage_backend_rbd.c | 35 ++++++-- tools/virsh-secret.c | 17 ++-- 8 files changed, 278 insertions(+), 50 deletions(-) -- 1.8.3.1
When using virsh secret-list - if the secret types are cephx or iscsi, then allow fetch/print of the usage information. Prior to the change the following would print: UUID Usage ----------------------------------------------------------- 1b40a534-8301-45d5-b1aa-11894ebb1735 Unused a5ba3efe-6adf-4a6a-b243-f010a043e314 Unused Afterwards: UUID Usage ----------------------------------------------------------- 1b40a534-8301-45d5-b1aa-11894ebb1735 ceph ceph_example a5ba3efe-6adf-4a6a-b243-f010a043e314 iscsi libvirtiscsi --- tools/virsh-secret.c | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/tools/virsh-secret.c b/tools/virsh-secret.c index 9d34c1a..30027fe 100644 --- a/tools/virsh-secret.c +++ b/tools/virsh-secret.c @@ -38,6 +38,7 @@ #include "virfile.h" #include "virutil.h" #include "virxml.h" +#include "conf/secret_conf.h" static virSecretPtr vshCommandOptSecret(vshControl *ctl, const vshCmd *cmd, const char **name) @@ -536,23 +537,19 @@ cmdSecretList(vshControl *ctl, const vshCmd *cmd ATTRIBUTE_UNUSED) for (i = 0; i < list->nsecrets; i++) { virSecretPtr sec = list->secrets[i]; - const char *usageType = NULL; - - switch (virSecretGetUsageType(sec)) { - case VIR_SECRET_USAGE_TYPE_VOLUME: - usageType = _("Volume"); - break; - } - + int usageType = virSecretGetUsageType(sec); + const char *usageStr = virSecretUsageTypeTypeToString(usageType); char uuid[VIR_UUID_STRING_BUFLEN]; + if (virSecretGetUUIDString(list->secrets[i], uuid) < 0) { vshError(ctl, "%s", _("Failed to get uuid of secret")); goto cleanup; } - if (usageType) { + if (usageType > VIR_SECRET_USAGE_TYPE_NONE && + usageType < VIR_SECRET_USAGE_TYPE_LAST) { vshPrint(ctl, "%-36s %s %s\n", - uuid, usageType, + uuid, usageStr, virSecretGetUsageID(sec)); } else { vshPrint(ctl, "%-36s %s\n", -- 1.8.3.1
On 08/08/2013 02:43 AM, John Ferlan wrote:
When using virsh secret-list - if the secret types are cephx or iscsi, then allow fetch/print of the usage information. Prior to the change the following would print:
UUID Usage ----------------------------------------------------------- 1b40a534-8301-45d5-b1aa-11894ebb1735 Unused a5ba3efe-6adf-4a6a-b243-f010a043e314 Unused
Afterwards:
UUID Usage ----------------------------------------------------------- 1b40a534-8301-45d5-b1aa-11894ebb1735 ceph ceph_example a5ba3efe-6adf-4a6a-b243-f010a043e314 iscsi libvirtiscsi --- tools/virsh-secret.c | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-)
ACK
diff --git a/tools/virsh-secret.c b/tools/virsh-secret.c index 9d34c1a..30027fe 100644 --- a/tools/virsh-secret.c +++ b/tools/virsh-secret.c @@ -38,6 +38,7 @@ #include "virfile.h" #include "virutil.h" #include "virxml.h" +#include "conf/secret_conf.h"
static virSecretPtr vshCommandOptSecret(vshControl *ctl, const vshCmd *cmd, const char **name) @@ -536,23 +537,19 @@ cmdSecretList(vshControl *ctl, const vshCmd *cmd ATTRIBUTE_UNUSED)
for (i = 0; i < list->nsecrets; i++) { virSecretPtr sec = list->secrets[i]; - const char *usageType = NULL; - - switch (virSecretGetUsageType(sec)) { - case VIR_SECRET_USAGE_TYPE_VOLUME: - usageType = _("Volume"); - break; - } - + int usageType = virSecretGetUsageType(sec); + const char *usageStr = virSecretUsageTypeTypeToString(usageType); char uuid[VIR_UUID_STRING_BUFLEN]; + if (virSecretGetUUIDString(list->secrets[i], uuid) < 0) { vshError(ctl, "%s", _("Failed to get uuid of secret")); goto cleanup; }
- if (usageType) { + if (usageType > VIR_SECRET_USAGE_TYPE_NONE &&
+ usageType < VIR_SECRET_USAGE_TYPE_LAST) {
This condition seems redundant.
vshPrint(ctl, "%-36s %s %s\n", - uuid, usageType, + uuid, usageStr, virSecretGetUsageID(sec)); } else { vshPrint(ctl, "%-36s %s\n",
Jan
On 08/16/2013 09:46 AM, Ján Tomko wrote:
On 08/08/2013 02:43 AM, John Ferlan wrote: ...
diff --git a/tools/virsh-secret.c b/tools/virsh-secret.c index 9d34c1a..30027fe 100644 --- a/tools/virsh-secret.c +++ b/tools/virsh-secret.c ... + int usageType = virSecretGetUsageType(sec); + const char *usageStr = virSecretUsageTypeTypeToString(usageType); char uuid[VIR_UUID_STRING_BUFLEN]; + if (virSecretGetUUIDString(list->secrets[i], uuid) < 0) { vshError(ctl, "%s", _("Failed to get uuid of secret")); goto cleanup; }
- if (usageType) { + if (usageType > VIR_SECRET_USAGE_TYPE_NONE &&
+ usageType < VIR_SECRET_USAGE_TYPE_LAST) {
This condition seems redundant.
Hmm. right. Don't think the range check is necessary at all since NONE is zero, then "if (usageType) {" should be sufficient. I've removed the extraneous check. John
Following XML would fail : <disk type='network' device='lun'> <driver name='qemu' type='raw'/> <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi/1'> <host name='example.com' port='3260'/> </source> <target dev='sda' bus='scsi'/> </disk> With the message: error: Failed to start domain iscsilun error: Unable to get device ID 'iqn.2013-07.com.example:iscsi/1': No such file or directory Cause was commit id '1f49b05a' which added 'virDomainDiskSourceIsBlockType' --- src/qemu/qemu_conf.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/qemu/qemu_conf.c b/src/qemu/qemu_conf.c index 18e926c..86ed9ed 100644 --- a/src/qemu/qemu_conf.c +++ b/src/qemu/qemu_conf.c @@ -1065,7 +1065,7 @@ qemuSetUnprivSGIO(virDomainDeviceDefPtr dev) disk = dev->data.disk; if (disk->device != VIR_DOMAIN_DISK_DEVICE_LUN || - virDomainDiskSourceIsBlockType(disk)) + !virDomainDiskSourceIsBlockType(disk)) return 0; path = disk->src; -- 1.8.3.1
On 08/08/2013 02:43 AM, John Ferlan wrote:
Following XML would fail :
<disk type='network' device='lun'> <driver name='qemu' type='raw'/> <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi/1'> <host name='example.com' port='3260'/> </source> <target dev='sda' bus='scsi'/> </disk>
With the message:
error: Failed to start domain iscsilun error: Unable to get device ID 'iqn.2013-07.com.example:iscsi/1': No such file or directory
Cause was commit id '1f49b05a' which added 'virDomainDiskSourceIsBlockType' --- src/qemu/qemu_conf.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
ACK Jan
On 08/16/2013 09:46 AM, Ján Tomko wrote:
On 08/08/2013 02:43 AM, John Ferlan wrote:
Following XML would fail :
<disk type='network' device='lun'> <driver name='qemu' type='raw'/> <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi/1'> <host name='example.com' port='3260'/> </source> <target dev='sda' bus='scsi'/> </disk>
With the message:
error: Failed to start domain iscsilun error: Unable to get device ID 'iqn.2013-07.com.example:iscsi/1': No such file or directory
Cause was commit id '1f49b05a' which added 'virDomainDiskSourceIsBlockType' --- src/qemu/qemu_conf.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
ACK
Jan
I adjusted the checkin to credit Osier as the author of the fix - see comment 8 from bz 957295 which is where I sourced the change. John
Each of the modules handled reporting error messages from the secret fetching slightly differently with respect to the error. Provide a similar message for each error case and provide as much data as possible. --- src/qemu/qemu_command.c | 28 ++++++++++++++++++++++------ src/storage/storage_backend_iscsi.c | 28 ++++++++++++++++++++++------ src/storage/storage_backend_rbd.c | 35 ++++++++++++++++++++++++++++------- 3 files changed, 72 insertions(+), 19 deletions(-) diff --git a/src/qemu/qemu_command.c b/src/qemu/qemu_command.c index b811e1d..24e891b 100644 --- a/src/qemu/qemu_command.c +++ b/src/qemu/qemu_command.c @@ -3043,18 +3043,34 @@ qemuGetSecretString(virConnectPtr conn, } if (!sec) { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("%s username '%s' specified but secret not found"), - scheme, username); + if (diskSecretType == VIR_DOMAIN_DISK_SECRET_TYPE_UUID) { + virReportError(VIR_ERR_NO_SECRET, + _("%s username '%s' specified but secret for " + "uuid '%s' not found"), + scheme, username, uuid); + } else { + virReportError(VIR_ERR_NO_SECRET, + _("%s username '%s' specified but secret for " + "usage value '%s' not found"), + scheme, username, usage); + } goto cleanup; } secret = (char *)conn->secretDriver->secretGetValue(sec, &secret_size, 0, VIR_SECRET_GET_VALUE_INTERNAL_CALL); if (!secret) { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("could not get value of the secret for username %s"), - username); + if (diskSecretType == VIR_DOMAIN_DISK_SECRET_TYPE_UUID) { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get value of the secret for " + "username '%s' using uuid '%s'"), + username, uuid); + } else { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get value of the secret for " + "username '%s' using usage value '%s'"), + username, usage); + } goto cleanup; } diff --git a/src/storage/storage_backend_iscsi.c b/src/storage/storage_backend_iscsi.c index ee8dd2e..55bf544 100644 --- a/src/storage/storage_backend_iscsi.c +++ b/src/storage/storage_backend_iscsi.c @@ -732,15 +732,31 @@ virStorageBackendISCSISetAuth(const char *portal, conn->secretDriver->secretGetValue(secret, &secret_size, 0, VIR_SECRET_GET_VALUE_INTERNAL_CALL); if (!secret_value) { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("could not get the value of the secret " - "for username %s"), chap.username); + if (chap.secret.uuidUsable) { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username %s using uuid '%s'"), + chap.username, chap.secret.uuid); + } else { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username %s using usage value '%s'"), + chap.username, chap.secret.usage); + } goto cleanup; } } else { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("username '%s' specified but secret not found"), - chap.username); + if (chap.secret.uuidUsable) { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "uuid '%s' not found"), + chap.username, chap.secret.uuid); + } else { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "usage value '%s' not found"), + chap.username, chap.secret.usage); + } goto cleanup; } diff --git a/src/storage/storage_backend_rbd.c b/src/storage/storage_backend_rbd.c index e3340f6..9c6d179 100644 --- a/src/storage/storage_backend_rbd.c +++ b/src/storage/storage_backend_rbd.c @@ -91,19 +91,40 @@ static int virStorageBackendRBDOpenRADOSConn(virStorageBackendRBDStatePtr *ptr, } if (secret == NULL) { - virReportError(VIR_ERR_NO_SECRET, "%s", - _("failed to find the secret")); + if (pool->def->source.auth.cephx.secret.uuidUsable) { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "uuid '%s' not found"), + pool->def->source.auth.cephx.username, + pool->def->source.auth.cephx.secret.uuid); + } else { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "usage value '%s' not found"), + pool->def->source.auth.cephx.username, + pool->def->source.auth.cephx.secret.usage); + } goto cleanup; } - secret_value = conn->secretDriver->secretGetValue(secret, &secret_value_size, 0, + secret_value = conn->secretDriver->secretGetValue(secret, + &secret_value_size, 0, VIR_SECRET_GET_VALUE_INTERNAL_CALL); if (!secret_value) { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("could not get the value of the secret " - "for username %s"), - pool->def->source.auth.cephx.username); + if (pool->def->source.auth.cephx.secret.uuidUsable) { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username '%s' using uuid '%s'"), + pool->def->source.auth.cephx.username, + pool->def->source.auth.cephx.secret.uuid); + } else { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username '%s' using usage value '%s'"), + pool->def->source.auth.cephx.username, + pool->def->source.auth.cephx.secret.usage); + } goto cleanup; } -- 1.8.3.1
On 08/08/2013 02:43 AM, John Ferlan wrote:
Each of the modules handled reporting error messages from the secret fetching slightly differently with respect to the error. Provide a similar message for each error case and provide as much data as possible. --- src/qemu/qemu_command.c | 28 ++++++++++++++++++++++------ src/storage/storage_backend_iscsi.c | 28 ++++++++++++++++++++++------ src/storage/storage_backend_rbd.c | 35 ++++++++++++++++++++++++++++------- 3 files changed, 72 insertions(+), 19 deletions(-)
...
diff --git a/src/storage/storage_backend_iscsi.c b/src/storage/storage_backend_iscsi.c index ee8dd2e..55bf544 100644 --- a/src/storage/storage_backend_iscsi.c +++ b/src/storage/storage_backend_iscsi.c @@ -732,15 +732,31 @@ virStorageBackendISCSISetAuth(const char *portal, conn->secretDriver->secretGetValue(secret, &secret_size, 0, VIR_SECRET_GET_VALUE_INTERNAL_CALL); if (!secret_value) { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("could not get the value of the secret " - "for username %s"), chap.username); + if (chap.secret.uuidUsable) { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username %s using uuid '%s'"), + chap.username, chap.secret.uuid); + } else { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username %s using usage value '%s'"), + chap.username, chap.secret.usage);
This looks to me like the username plays a part in getting the secret value, but I'm not sure how to rephrase it while still keeping the username there.
+ } goto cleanup; } } else { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("username '%s' specified but secret not found"), - chap.username); + if (chap.secret.uuidUsable) { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "uuid '%s' not found"), + chap.username, chap.secret.uuid); + } else { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "usage value '%s' not found"), + chap.username, chap.secret.usage); + } goto cleanup;
With VIR_ERR_NO_SECRET, this says "secret not found" twice: error: Secret not found: username 'nahasapeemapetilon' specified but the secret for usage value 'pwagmattasquarmsettport' not found But that's minor. Maybe "... but no secret matches usage '%s'"?
}
diff --git a/src/storage/storage_backend_rbd.c b/src/storage/storage_backend_rbd.c index e3340f6..9c6d179 100644 --- a/src/storage/storage_backend_rbd.c +++ b/src/storage/storage_backend_rbd.c
...
- secret_value = conn->secretDriver->secretGetValue(secret, &secret_value_size, 0, + secret_value = conn->secretDriver->secretGetValue(secret, + &secret_value_size, 0, VIR_SECRET_GET_VALUE_INTERNAL_CALL);
Unrelated whitespace change. ACK if you separate it from the rest of the patch. Jan
On 08/16/2013 12:34 PM, Ján Tomko wrote:
On 08/08/2013 02:43 AM, John Ferlan wrote:
VIR_SECRET_GET_VALUE_INTERNAL_CALL); if (!secret_value) { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("could not get the value of the secret " - "for username %s"), chap.username); + if (chap.secret.uuidUsable) { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username %s using uuid '%s'"), + chap.username, chap.secret.uuid); + } else { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username %s using usage value '%s'"), + chap.username, chap.secret.usage);
This looks to me like the username plays a part in getting the secret value, but I'm not sure how to rephrase it while still keeping the username there.
This error is a failure to find the secret value (e.g. call to 'secretGetValue' to the secret driver) given the "secret key" (virSecretPtr) which was obtained by using either the UUID or Usage value. The username is mainly for convenience in the error message since it's not used by the secret driver. The username would be passed to whatever the code is authenticating to along with the secret value pulled from the secret driver. I suppose username could be removed from the message, but it just seemed easier to reference the username as well since it's part of the xml that would use the secret.
+ } goto cleanup; } } else { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("username '%s' specified but secret not found"), - chap.username); + if (chap.secret.uuidUsable) { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "uuid '%s' not found"), + chap.username, chap.secret.uuid); + } else { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "usage value '%s' not found"), + chap.username, chap.secret.usage); + } goto cleanup;
With VIR_ERR_NO_SECRET, this says "secret not found" twice: error: Secret not found: username 'nahasapeemapetilon' specified but the secret for usage value 'pwagmattasquarmsettport' not found
But that's minor. Maybe "... but no secret matches usage '%s'"?
This error message is the inability to find the "secret key" (virSecretPtr) given either a UUID or Usage value (the output of that virsh secret-list). Is the following more appropriate? change _("%s username '%s' specified but secret for " "uuid '%s' not found") to be: _("no secret matches uuid '%s'") and _("%s username '%s' specified but secret for " "usage value '%s' not found"), to be: _("no secret matches usage value '%s'")
}
diff --git a/src/storage/storage_backend_rbd.c b/src/storage/storage_backend_rbd.c index e3340f6..9c6d179 100644 --- a/src/storage/storage_backend_rbd.c +++ b/src/storage/storage_backend_rbd.c
...
- secret_value = conn->secretDriver->secretGetValue(secret, &secret_value_size, 0, + secret_value = conn->secretDriver->secretGetValue(secret, + &secret_value_size, 0, VIR_SECRET_GET_VALUE_INTERNAL_CALL);
I removed this since it's unrelated - that's just my desire to have 80 column displays. John
On 08/19/2013 11:09 PM, John Ferlan wrote:
On 08/16/2013 12:34 PM, Ján Tomko wrote:
On 08/08/2013 02:43 AM, John Ferlan wrote:
VIR_SECRET_GET_VALUE_INTERNAL_CALL); if (!secret_value) { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("could not get the value of the secret " - "for username %s"), chap.username); + if (chap.secret.uuidUsable) { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username %s using uuid '%s'"), + chap.username, chap.secret.uuid); + } else { + virReportError(VIR_ERR_INTERNAL_ERROR, + _("could not get the value of the secret " + "for username %s using usage value '%s'"), + chap.username, chap.secret.usage);
This looks to me like the username plays a part in getting the secret value, but I'm not sure how to rephrase it while still keeping the username there.
This error is a failure to find the secret value (e.g. call to 'secretGetValue' to the secret driver) given the "secret key" (virSecretPtr) which was obtained by using either the UUID or Usage value.
The username is mainly for convenience in the error message since it's not used by the secret driver. The username would be passed to whatever the code is authenticating to along with the secret value pulled from the secret driver.
I suppose username could be removed from the message, but it just seemed easier to reference the username as well since it's part of the xml that would use the secret.
Usually we don't print the surrounding elements. Maybe the username was a part of the error message to avoid separate errors for uuid and usage? But I'm fine either way, the only condition for my ACK was that you remove the unrelated whitespace change.
+ } goto cleanup; } } else { - virReportError(VIR_ERR_INTERNAL_ERROR, - _("username '%s' specified but secret not found"), - chap.username); + if (chap.secret.uuidUsable) { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "uuid '%s' not found"), + chap.username, chap.secret.uuid); + } else { + virReportError(VIR_ERR_NO_SECRET, + _("username '%s' specified but the secret for " + "usage value '%s' not found"), + chap.username, chap.secret.usage); + } goto cleanup;
With VIR_ERR_NO_SECRET, this says "secret not found" twice: error: Secret not found: username 'nahasapeemapetilon' specified but the secret for usage value 'pwagmattasquarmsettport' not found
But that's minor. Maybe "... but no secret matches usage '%s'"?
This error message is the inability to find the "secret key" (virSecretPtr) given either a UUID or Usage value (the output of that virsh secret-list).
Is the following more appropriate?
change
_("%s username '%s' specified but secret for " "uuid '%s' not found")
to be:
_("no secret matches uuid '%s'")
and
_("%s username '%s' specified but secret for " "usage value '%s' not found"),
to be:
_("no secret matches usage value '%s'")
Personally, I like the shorter versions more. But all three versions are fine.
}
diff --git a/src/storage/storage_backend_rbd.c b/src/storage/storage_backend_rbd.c index e3340f6..9c6d179 100644 --- a/src/storage/storage_backend_rbd.c +++ b/src/storage/storage_backend_rbd.c
...
- secret_value = conn->secretDriver->secretGetValue(secret, &secret_value_size, 0, + secret_value = conn->secretDriver->secretGetValue(secret, + &secret_value_size, 0, VIR_SECRET_GET_VALUE_INTERNAL_CALL);
I removed this since it's unrelated - that's just my desire to have 80 column displays.
Feel free to push it separately under the trivial rule, but it doesn't really remove any lines longer than 80 columns :) Jan
Add more iSCSI examples including having a secret attached. There are 4 new examples one for each way to have an iSCSI - a network disk using virtio, a passthrough network lun using scsi, a volume disk using "mode='host'", and a volume disk using "mode='direct'" --- docs/formatdomain.html.in | 57 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 49 insertions(+), 8 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index dd22b6d..01253ef 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1514,6 +1514,42 @@ <source pool='blk-pool0' volume='blk-pool0-vol0'/> <target dev='hda' bus='ide'/> </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/2'> + <host name='example.com' port='3260'/> + <source> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='network' device='lun'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/1'> + <host name='example.com' port='3260'/> + <source> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='sda' bus='scsi'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> </devices> ...</pre> @@ -1602,15 +1638,20 @@ specifies the name of storage pool (managed by libvirt) where the disk source resides, and attribute <code>volume</code> specifies the name of storage volume (managed by libvirt) used as the disk source. For a - "volume" type disk, if the underlying storage pool is "iscsi", attribute - <code>mode</code> (<span class="since">since 1.1.1</span>) can be used - to indicate how to represent the LUN as the disk source. The value - "host" indicates to use the LUN's path as it shows up on host, e.g. - /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1). - The value "direct" indicates to use the storage pool's - <code>source</code> element <code>host</code> attribute as the - disk source for the libiscsi URI, e.g. + "volume" <code>type</code> disk, if the underlying storage pool is + "iscsi", then use the output of the value from the "Name" column of + the <code>virsh vol-list [pool-name]</code> command for the + <code>volume</code> attribute field. Use the attribute + <code>mode</code> (<span class="since">since 1.1.1</span>) to + indicate how to represent the LUN as the disk source. + Using "direct" as the <code>mode</code> value indicates to use the + storage pool's <code>source</code> element <code>host</code> + attribute as the disk source to generate the libiscsi URI, e.g. file=iscsi://demo.org:6000/iqn.1992-01.com.example/1. + Using "host" as the <code>mode</code> value indicates to use the + LUN's path as it shows up on host, e.g. + /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1). + If <code>mode</code> is not specified, the default is to use "host". <span class="since">Since 0.0.3; <code>type='dir'</code> since 0.7.5; <code>type='network'</code> since 0.8.7; <code>protocol='iscsi'</code> since 1.0.4; -- 1.8.3.1
On 08/08/2013 02:43 AM, John Ferlan wrote:
Add more iSCSI examples including having a secret attached. There are 4 new examples one for each way to have an iSCSI - a network disk using virtio, ^ Missing punctuation.
a passthrough network lun using scsi, a volume disk using "mode='host'", and a volume disk using "mode='direct'" --- docs/formatdomain.html.in | 57 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 49 insertions(+), 8 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index dd22b6d..01253ef 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1514,6 +1514,42 @@ <source pool='blk-pool0' volume='blk-pool0-vol0'/> <target dev='hda' bus='ide'/> </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/2'> + <host name='example.com' port='3260'/> + <source> ^ Missing slash.
+ <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='network' device='lun'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/1'> + <host name='example.com' port='3260'/> + <source> ^ Here too.
+ <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='sda' bus='scsi'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> </devices> ...</pre>
@@ -1602,15 +1638,20 @@ specifies the name of storage pool (managed by libvirt) where the disk source resides, and attribute <code>volume</code> specifies the name of storage volume (managed by libvirt) used as the disk source. For a - "volume" type disk, if the underlying storage pool is "iscsi", attribute - <code>mode</code> (<span class="since">since 1.1.1</span>) can be used - to indicate how to represent the LUN as the disk source. The value - "host" indicates to use the LUN's path as it shows up on host, e.g. - /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1). - The value "direct" indicates to use the storage pool's - <code>source</code> element <code>host</code> attribute as the - disk source for the libiscsi URI, e.g. + "volume" <code>type</code> disk, if the underlying storage pool is + "iscsi", then use the output of the value from the "Name" column of + the <code>virsh vol-list [pool-name]</code> command for the + <code>volume</code> attribute field.
Isn't this true for all storage pools and mentioned just a few sentences earlier?
Use the attribute + <code>mode</code> (<span class="since">since 1.1.1</span>) to + indicate how to represent the LUN as the disk source. + Using "direct" as the <code>mode</code> value indicates to use the + storage pool's <code>source</code> element <code>host</code> + attribute as the disk source to generate the libiscsi URI, e.g. file=iscsi://demo.org:6000/iqn.1992-01.com.example/1. + Using "host" as the <code>mode</code> value indicates to use the + LUN's path as it shows up on host, e.g. + /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1).
It would be nicer if the URI and the path were for the same disk.
+ If <code>mode</code> is not specified, the default is to use "host". <span class="since">Since 0.0.3; <code>type='dir'</code> since 0.7.5; <code>type='network'</code> since 0.8.7; <code>protocol='iscsi'</code> since 1.0.4;
ACK with the "Name" column reference removed. Jan
On 08/16/2013 11:17 AM, Ján Tomko wrote:
On 08/08/2013 02:43 AM, John Ferlan wrote:
Add more iSCSI examples including having a secret attached. There are 4 new examples one for each way to have an iSCSI - a network disk using virtio, ^ Missing punctuation.
a passthrough network lun using scsi, a volume disk using "mode='host'", and a volume disk using "mode='direct'" --- docs/formatdomain.html.in | 57 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 49 insertions(+), 8 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index dd22b6d..01253ef 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1514,6 +1514,42 @@ <source pool='blk-pool0' volume='blk-pool0-vol0'/> <target dev='hda' bus='ide'/> </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/2'> + <host name='example.com' port='3260'/> + <source> ^ Missing slash.
+ <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='network' device='lun'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/1'> + <host name='example.com' port='3260'/> + <source> ^ Here too.
+ <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='sda' bus='scsi'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> </devices> ...</pre>
@@ -1602,15 +1638,20 @@ specifies the name of storage pool (managed by libvirt) where the disk source resides, and attribute <code>volume</code> specifies the name of storage volume (managed by libvirt) used as the disk source. For a - "volume" type disk, if the underlying storage pool is "iscsi", attribute - <code>mode</code> (<span class="since">since 1.1.1</span>) can be used - to indicate how to represent the LUN as the disk source. The value - "host" indicates to use the LUN's path as it shows up on host, e.g. - /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1). - The value "direct" indicates to use the storage pool's - <code>source</code> element <code>host</code> attribute as the - disk source for the libiscsi URI, e.g. + "volume" <code>type</code> disk, if the underlying storage pool is + "iscsi", then use the output of the value from the "Name" column of + the <code>virsh vol-list [pool-name]</code> command for the + <code>volume</code> attribute field.
Isn't this true for all storage pools and mentioned just a few sentences earlier?
Use the attribute + <code>mode</code> (<span class="since">since 1.1.1</span>) to + indicate how to represent the LUN as the disk source. + Using "direct" as the <code>mode</code> value indicates to use the + storage pool's <code>source</code> element <code>host</code> + attribute as the disk source to generate the libiscsi URI, e.g. file=iscsi://demo.org:6000/iqn.1992-01.com.example/1. + Using "host" as the <code>mode</code> value indicates to use the + LUN's path as it shows up on host, e.g. + /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1).
It would be nicer if the URI and the path were for the same disk.
+ If <code>mode</code> is not specified, the default is to use "host". <span class="since">Since 0.0.3; <code>type='dir'</code> since 0.7.5; <code>type='network'</code> since 0.8.7; <code>protocol='iscsi'</code> since 1.0.4;
ACK with the "Name" column reference removed.
Jan
That whole source paragraph is quite confusing with the various ways to represent the source xml. It's made more confusing because an iSCSI volume can either be represented as something from a pool via the "pool" element or directly via the "protocol" element. In essence, there's 4 ways to represent an iSCSI volume (thus the 4 new examples). The point of the "Name" column was to give a hint as to which value to provide for that specific option. For example, the on my system I get the following: # virsh vol-list iscsi-pool Name Path ----------------------------------------- unit:0:0:1 /dev/disk/by-path/ip-192.168.122.1:3260-iscsi-iqn.2013-07.localhost:iscsi-pool-lun-1 unit:0:0:2 /dev/disk/by-path/ip-192.168.122.1:3260-iscsi-iqn.2013-07.localhost:iscsi-pool-lun-2 So the comment in that section was to use "unit:0:0:1" or "unit:0:0:2" rather than anything else when using the "pool" attribute. I've updated the description quite a bit to perhaps and hopefully clear things up a bit more. I attached a patch based on top of trunk from just a bit ago... I also changed the examples to be based on what's running now on my test system (although I changed the ipaddr to be example.com to look better). John
On 20/08/13 05:21, John Ferlan wrote:
From e31f3596893302ee1f96d2eb0cf4e006294c528c Mon Sep 17 00:00:00 2001 From: John Ferlan<jferlan@redhat.com> Date: Wed, 7 Aug 2013 09:05:43 -0400 Subject: [PATCH 4/7] docs: Update the formatdomain disk examples
Add more iSCSI examples including having a secret attached. There are 4 new examples one for each way to have an iSCSI - a network disk using virtio, a passthrough network lun using scsi, a volume disk using "mode='host'", and a volume disk using "mode='direct'" --- docs/formatdomain.html.in | 164 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 121 insertions(+), 43 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 4a927cc..5450be0 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1518,6 +1518,42 @@ <source pool='blk-pool0' volume='blk-pool0-vol0'/> <target dev='hda' bus='ide'/> </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/2'> + <host name='example.com' port='3260'/> + </source> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='network' device='lun'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/1'> + <host name='example.com' port='3260'/> + </source> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='sda' bus='scsi'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> </devices> ...</pre>
@@ -1525,7 +1561,7 @@ <dt><code>disk</code></dt> <dd>The <code>disk</code> element is the main container for describing disks. The <code>type</code> attribute is either "file", - "block", "dir", or "network" + "block", "dir", "network", or "volume" and refers to the underlying source for the disk. The optional <code>device</code> attribute indicates how the disk is to be exposed to the guest OS. Possible values for this attribute are @@ -1575,57 +1611,96 @@ "network" attribute since 0.8.7; "snapshot" since 0.9.5</span></dd> <dt><code>source</code></dt> - <dd>If the disk <code>type</code> is "file", then - the <code>file</code> attribute specifies the fully-qualified - path to the file holding the disk. If the disk - <code>type</code> is "block", then the <code>dev</code> - attribute specifies the path to the host device to serve as - the disk. With "file", "block", and "volume", one or more optional + <dd>Representation of the disk <code>source</code> depends on the + <code>disk type</code> attribute value as follows:
disk <code>type</code>
+ <dl> + <dt><code>type='file'</code>
if you are 2 spaces as the indention......
+ <span class="since">Since 0.0.3</span></dt> + <dd> + The <code>file</code> attribute specifies the fully-qualified
Then you will have enough spaces to indent lines like this with 2 spaces too.
+ path to the file holding the disk. + </dd> + <dt><code>type='block'</code> + <span class="since">Since 0.0.3</span></dt> + <dd> + The <code>dev</code> attribute specifies the path to the + host device to serve as the disk. + </dd> + <dt><code>type='dir'</code> + <span class="since">Since 0.7.5</span></dt> + <dd> + The <code>dir</code> attribute specifies the fully-qualified path + to the directory to use as the disk. + </dd> + <dt><code>type='network'</code> + <span class="since">Since 0.8.7</span></dt> + <dd> + The <code>protocol</code> attribute specifies the protocol to + access to the requested image. Possible values are "nbd", + "iscsi", "rbd", "sheepdog" or "gluster". If the + <code>protocol</code> attribute is "rbd", "sheepdog" or + "gluster", an additional attribute <code>name</code> is + mandatory to specify which volume/image will be used. For "nbd", + the <code>name</code> attribute is optional. For "iscsi" + (<span class="since">since 1.0.4</span>), the <code>name</code> + attribute may include a logical unit number, separated from the + target's name by a slash (e.g., + <code>iqn.2013-07.com.example:iscsi-pool/1</code>). If not + specified, the default LUN is zero. + </dd> + <dt><code>type='volume'</code> + <span class="since">Since 1.0.5</span></dt> + <dd> + The underlying disk source is represented by attributes + <code>pool</code> and <code>volume</code>. Attribute + <code>pool</code> specifies the name of storage pool (managed + by libvirt) where the disk source resides. Attribute + <code>volume</code> specifies the name of storage volume (managed + by libvirt) used as the disk source. + + <p> + If the underlying storage pool is "iscsi", then use the output + of the value from the "Name" column of the <code>virsh vol-list + [pool-name]</code> command for the <code>volume</code> attribute + field.
It sounds like it only works when the storage pool is "iscsi". one can use "virsh vol-list" to find out the volume name for any type of storage pool.
Use the attribute <code>mode</code> + (<span class="since">since 1.1.1</span>) to indicate how to + represent the LUN as the disk source. Valid values are + "direct" and "host". If <code>mode</code> is not specified, + the default is to use "host". + + Using "direct" as the <code>mode</code> value indicates to use + the storage pool's <code>source</code> element <code>host</code>
Do we want a link to the storage pool document here?
+ attribute as the disk source to generate the libiscsi URI (e.g. + 'file=iscsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/1'). + + Using "host" as the <code>mode</code> value indicates to use the + LUN's path as it shows up on host (e.g. + 'file=/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.example:iscsi-pool-lun-1'). + </p> + </dd> + </dl> + With "file", "block", and "volume", one or more optional sub-elements <code>seclabel</code>, <a href="#seclabel">described below</a> (and <span class="since">since 0.9.9</span>), can be used to override the domain security labeling policy for just that source file. (NB, for "volume" type disk, <code>seclabel</code> is only valid when the specified storage volume is of 'file' or - 'block' type). If the disk <code>type</code> is "dir", then the - <code>dir</code> attribute specifies the fully-qualified path - to the directory to use as the disk. If the disk <code>type</code> - is "network", then the <code>protocol</code> attribute specifies - the protocol to access to the requested image; possible values - are "nbd", "iscsi", "rbd", "sheepdog" or "gluster". If the - <code>protocol</code> attribute is "rbd", "sheepdog" or "gluster", an - additional attribute <code>name</code> is mandatory to specify which - volume/image will be used; for "nbd" it is optional. For "iscsi", - the <code>name</code> attribute may include a logical unit number, - separated from the target's name by a slash (for example, - <code>iqn.1992-01.com.example/1</code>); the default LUN is zero. + 'block' type). + <p> When the disk <code>type</code> is "network", the <code>source</code> may have zero or more <code>host</code> sub-elements used to - specify the hosts to connect. If the disk <code>type</code> is - "volume", the underlying disk source is represented by attributes - <code>pool</code> and <code>volume</code>. Attribute <code>pool</code> - specifies the name of storage pool (managed by libvirt) where the disk - source resides, and attribute <code>volume</code> specifies the name of - storage volume (managed by libvirt) used as the disk source. For a - "volume" type disk, if the underlying storage pool is "iscsi", attribute - <code>mode</code> (<span class="since">since 1.1.1</span>) can be used - to indicate how to represent the LUN as the disk source. The value - "host" indicates to use the LUN's path as it shows up on host, e.g. - /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1). - The value "direct" indicates to use the storage pool's - <code>source</code> element <code>host</code> attribute as the - disk source for the libiscsi URI, e.g. - file=iscsi://demo.org:6000/iqn.1992-01.com.example/1. - <span class="since">Since 0.0.3; <code>type='dir'</code> since - 0.7.5; <code>type='network'</code> since - 0.8.7; <code>protocol='iscsi'</code> since 1.0.4; - <code>type='volume'</code> since 1.0.5;</span><br/> + specify the hosts to connect. + </p> + <p> For a "file" or "volume" disk type which represents a cdrom or floppy (the <code>device</code> attribute), it is possible to define policy what to do with the disk if the source file is not accessible. (NB, <code>startupPolicy</code> is not valid for "volume" disk unless the specified storage volume is of "file" type). This is done by the - <code>startupPolicy</code> attribute (<span class="since">Since 0.9.7</span>), + <code>startupPolicy</code> attribute + (<span class="since">Since 0.9.7</span>), accepting these values: + </p> <table class="top_table"> <tr> <td> mandatory </td> @@ -1641,10 +1716,13 @@ <td> drop if missing at any start attempt </td> </tr> </table> - <span class="since">Since 1.1.2</span> the <code>startupPolicy</code> is extended - to support hard disks besides cdrom and floppy. On guest cold bootup, if a certain disk - is not accessible or its disk chain is broken, with startupPolicy 'optional' the guest - will drop this disk. This feature doesn't support migration currently. + <p> + <span class="since">Since 1.1.2</span> the <code>startupPolicy</code> + is extended to support hard disks besides cdrom and floppy. On guest + cold bootup, if a certain disk is not accessible or its disk chain is + broken, with startupPolicy 'optional' the guest will drop this disk. + This feature doesn't support migration currently. + </p> </dd> <dt><code>mirror</code></dt> <dd> -- 1.8.3.1
Except the indentions and the small nits, it looks quite nice overrall, much more readable than before. Osier
On 08/20/2013 03:43 AM, Osier Yang wrote:
On 20/08/13 05:21, John Ferlan wrote:
From e31f3596893302ee1f96d2eb0cf4e006294c528c Mon Sep 17 00:00:00 2001 From: John Ferlan <jferlan@redhat.com> Date: Wed, 7 Aug 2013 09:05:43 -0400 Subject: [PATCH 4/7] docs: Update the formatdomain disk examples
Add more iSCSI examples including having a secret attached. There are 4 new examples one for each way to have an iSCSI - a network disk using virtio, a passthrough network lun using scsi, a volume disk using "mode='host'", and a volume disk using "mode='direct'" --- docs/formatdomain.html.in | 164 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 121 insertions(+), 43 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 4a927cc..5450be0 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1518,6 +1518,42 @@ <source pool='blk-pool0' volume='blk-pool0-vol0'/> <target dev='hda' bus='ide'/> </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/2'> + <host name='example.com' port='3260'/> + </source> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='network' device='lun'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/1'> + <host name='example.com' port='3260'/> + </source> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='sda' bus='scsi'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> </devices> ...</pre>
@@ -1525,7 +1561,7 @@ <dt><code>disk</code></dt> <dd>The <code>disk</code> element is the main container for describing disks. The <code>type</code> attribute is either "file", - "block", "dir", or "network" + "block", "dir", "network", or "volume" and refers to the underlying source for the disk. The optional <code>device</code> attribute indicates how the disk is to be exposed to the guest OS. Possible values for this attribute are @@ -1575,57 +1611,96 @@ "network" attribute since 0.8.7; "snapshot" since 0.9.5</span></dd> <dt><code>source</code></dt> - <dd>If the disk <code>type</code> is "file", then - the <code>file</code> attribute specifies the fully-qualified - path to the file holding the disk. If the disk - <code>type</code> is "block", then the <code>dev</code> - attribute specifies the path to the host device to serve as - the disk. With "file", "block", and "volume", one or more optional + <dd>Representation of the disk <code>source</code> depends on the + <code>disk type</code> attribute value as follows:
disk <code>type</code>
Changed
+ <dl> + <dt><code>type='file'</code>
if you are 2 spaces as the indention......
+ <span class="since">Since 0.0.3</span></dt> + <dd> + The <code>file</code> attribute specifies the fully-qualified
Then you will have enough spaces to indent lines like this with 2 spaces too.
Oh right... Rather than indent more I kept the 2 spaces as the indent, but moved back the <dt> elements since everything under <dl> was at 4 spaces.
+ path to the file holding the disk. + </dd> + <dt><code>type='block'</code> + <span class="since">Since 0.0.3</span></dt> + <dd> + The <code>dev</code> attribute specifies the path to the + host device to serve as the disk. + </dd> + <dt><code>type='dir'</code> + <span class="since">Since 0.7.5</span></dt> + <dd> + The <code>dir</code> attribute specifies the fully-qualified path + to the directory to use as the disk. + </dd> + <dt><code>type='network'</code> + <span class="since">Since 0.8.7</span></dt> + <dd> + The <code>protocol</code> attribute specifies the protocol to + access to the requested image. Possible values are "nbd", + "iscsi", "rbd", "sheepdog" or "gluster". If the + <code>protocol</code> attribute is "rbd", "sheepdog" or + "gluster", an additional attribute <code>name</code> is + mandatory to specify which volume/image will be used. For "nbd", + the <code>name</code> attribute is optional. For "iscsi" + (<span class="since">since 1.0.4</span>), the <code>name</code> + attribute may include a logical unit number, separated from the + target's name by a slash (e.g., + <code>iqn.2013-07.com.example:iscsi-pool/1</code>). If not + specified, the default LUN is zero. + </dd> + <dt><code>type='volume'</code> + <span class="since">Since 1.0.5</span></dt> + <dd> + The underlying disk source is represented by attributes + <code>pool</code> and <code>volume</code>. Attribute + <code>pool</code> specifies the name of storage pool (managed + by libvirt) where the disk source resides. Attribute + <code>volume</code> specifies the name of storage volume (managed + by libvirt) used as the disk source. + + <p> + If the underlying storage pool is "iscsi", then use the output + of the value from the "Name" column of the <code>virsh vol-list + [pool-name]</code> command for the <code>volume</code> attribute + field.
It sounds like it only works when the storage pool is "iscsi". one can use "virsh vol-list" to find out the volume name for any type of storage pool.
Ah - so that's a bit of myopia trying to write something down about iscsi that had a more general purpose. Since I was only configuring iscsi I wasn't thinking about others - here's what I have now: The underlying disk source is represented by attributes <code>pool</code> and <code>volume</code>. Attribute <code>pool</code> specifies the name of the <a href="formatstorage.html">storage pool</a> (managed by libvirt) where the disk source resides. Attribute <code>volume</code> specifies the name of storage volume (managed by libvirt) used as the disk source. The value for the <code>volume</code> attribute will be the output from the "Name" column of a <code>virsh vol-list [pool-name]</code> command.
Use the attribute <code>mode</code> + (<span class="since">since 1.1.1</span>) to indicate how to + represent the LUN as the disk source. Valid values are + "direct" and "host". If <code>mode</code> is not specified, + the default is to use "host". + + Using "direct" as the <code>mode</code> value indicates to use + the storage pool's <code>source</code> element <code>host</code>
Do we want a link to the storage pool document here?
Done.
+ attribute as the disk source to generate the libiscsi URI (e.g. + 'file=iscsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/1'). + + Using "host" as the <code>mode</code> value indicates to use the + LUN's path as it shows up on host (e.g. + 'file=/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.example:iscsi-pool-lun-1'). + </p> + </dd> + </dl> + With "file", "block", and "volume", one or more optional sub-elements <code>seclabel</code>, <a href="#seclabel">described below</a> (and <span class="since">since 0.9.9</span>), can be used to override the domain security labeling policy for just that source file. (NB, for "volume" type disk, <code>seclabel</code> is only valid when the specified storage volume is of 'file' or - 'block' type). If the disk <code>type</code> is "dir", then the - <code>dir</code> attribute specifies the fully-qualified path - to the directory to use as the disk. If the disk <code>type</code> - is "network", then the <code>protocol</code> attribute specifies - the protocol to access to the requested image; possible values - are "nbd", "iscsi", "rbd", "sheepdog" or "gluster". If the - <code>protocol</code> attribute is "rbd", "sheepdog" or "gluster", an - additional attribute <code>name</code> is mandatory to specify which - volume/image will be used; for "nbd" it is optional. For "iscsi", - the <code>name</code> attribute may include a logical unit number, - separated from the target's name by a slash (for example, - <code>iqn.1992-01.com.example/1</code>); the default LUN is zero. + 'block' type). + <p> When the disk <code>type</code> is "network", the <code>source</code> may have zero or more <code>host</code> sub-elements used to - specify the hosts to connect. If the disk <code>type</code> is - "volume", the underlying disk source is represented by attributes - <code>pool</code> and <code>volume</code>. Attribute <code>pool</code> - specifies the name of storage pool (managed by libvirt) where the disk - source resides, and attribute <code>volume</code> specifies the name of - storage volume (managed by libvirt) used as the disk source. For a - "volume" type disk, if the underlying storage pool is "iscsi", attribute - <code>mode</code> (<span class="since">since 1.1.1</span>) can be used - to indicate how to represent the LUN as the disk source. The value - "host" indicates to use the LUN's path as it shows up on host, e.g. - /dev/disk/by-path/ip-10.11.12.9:3260-iscsi-iqn.2013-06.fc:iscsi.iscsi0-lun-1). - The value "direct" indicates to use the storage pool's - <code>source</code> element <code>host</code> attribute as the - disk source for the libiscsi URI, e.g. - file=iscsi://demo.org:6000/iqn.1992-01.com.example/1. - <span class="since">Since 0.0.3; <code>type='dir'</code> since - 0.7.5; <code>type='network'</code> since - 0.8.7; <code>protocol='iscsi'</code> since 1.0.4; - <code>type='volume'</code> since 1.0.5;</span><br/> + specify the hosts to connect. + </p> + <p> For a "file" or "volume" disk type which represents a cdrom or floppy (the <code>device</code> attribute), it is possible to define policy what to do with the disk if the source file is not accessible. (NB, <code>startupPolicy</code> is not valid for "volume" disk unless the specified storage volume is of "file" type). This is done by the - <code>startupPolicy</code> attribute (<span class="since">Since 0.9.7</span>), + <code>startupPolicy</code> attribute + (<span class="since">Since 0.9.7</span>), accepting these values: + </p> <table class="top_table"> <tr> <td> mandatory </td> @@ -1641,10 +1716,13 @@ <td> drop if missing at any start attempt </td> </tr> </table> - <span class="since">Since 1.1.2</span> the <code>startupPolicy</code> is extended - to support hard disks besides cdrom and floppy. On guest cold bootup, if a certain disk - is not accessible or its disk chain is broken, with startupPolicy 'optional' the guest - will drop this disk. This feature doesn't support migration currently. + <p> + <span class="since">Since 1.1.2</span> the <code>startupPolicy</code> + is extended to support hard disks besides cdrom and floppy. On guest + cold bootup, if a certain disk is not accessible or its disk chain is + broken, with startupPolicy 'optional' the guest will drop this disk. + This feature doesn't support migration currently. + </p> </dd> <dt><code>mirror</code></dt> <dd> -- 1.8.3.1
Except the indentions and the small nits, it looks quite nice overrall, much more readable than before.
Thanks - the 'disk' section could use some adjustments too I think - maybe in another patch :-) John
On 20/08/13 21:10, John Ferlan wrote:
On 08/20/2013 03:43 AM, Osier Yang wrote:
On 20/08/13 05:21, John Ferlan wrote:
From e31f3596893302ee1f96d2eb0cf4e006294c528c Mon Sep 17 00:00:00 2001 From: John Ferlan <jferlan@redhat.com> Date: Wed, 7 Aug 2013 09:05:43 -0400 Subject: [PATCH 4/7] docs: Update the formatdomain disk examples
Add more iSCSI examples including having a secret attached. There are 4 new examples one for each way to have an iSCSI - a network disk using virtio, a passthrough network lun using scsi, a volume disk using "mode='host'", and a volume disk using "mode='direct'" --- docs/formatdomain.html.in | 164 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 121 insertions(+), 43 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 4a927cc..5450be0 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1518,6 +1518,42 @@ <source pool='blk-pool0' volume='blk-pool0-vol0'/> <target dev='hda' bus='ide'/> </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/2'> + <host name='example.com' port='3260'/> + </source> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='network' device='lun'> + <driver name='qemu' type='raw'/> + <source protocol='iscsi' name='iqn.2013-06.com.example:iscsi/1'> + <host name='example.com' port='3260'/> + </source> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='sda' bus='scsi'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='volume' device='disk'> + <driver name='qemu' type='raw'/> + <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/> + <auth username='myuser'> + <secret type='chap' usage='libvirtiscsi'/> + </auth> + <target dev='vda' bus='virtio'/> + </disk> </devices> ...</pre>
@@ -1525,7 +1561,7 @@ <dt><code>disk</code></dt> <dd>The <code>disk</code> element is the main container for describing disks. The <code>type</code> attribute is either "file", - "block", "dir", or "network" + "block", "dir", "network", or "volume" and refers to the underlying source for the disk. The optional <code>device</code> attribute indicates how the disk is to be exposed to the guest OS. Possible values for this attribute are @@ -1575,57 +1611,96 @@ "network" attribute since 0.8.7; "snapshot" since 0.9.5</span></dd> <dt><code>source</code></dt> - <dd>If the disk <code>type</code> is "file", then - the <code>file</code> attribute specifies the fully-qualified - path to the file holding the disk. If the disk - <code>type</code> is "block", then the <code>dev</code> - attribute specifies the path to the host device to serve as - the disk. With "file", "block", and "volume", one or more optional + <dd>Representation of the disk <code>source</code> depends on the + <code>disk type</code> attribute value as follows: disk <code>type</code>
Changed
+ <dl> + <dt><code>type='file'</code> if you are 2 spaces as the indention......
+ <span class="since">Since 0.0.3</span></dt> + <dd> + The <code>file</code> attribute specifies the fully-qualified Then you will have enough spaces to indent lines like this with 2 spaces too.
Oh right... Rather than indent more I kept the 2 spaces as the indent, but moved back the <dt> elements since everything under <dl> was at 4 spaces.
+ path to the file holding the disk. + </dd> + <dt><code>type='block'</code> + <span class="since">Since 0.0.3</span></dt> + <dd> + The <code>dev</code> attribute specifies the path to the + host device to serve as the disk. + </dd> + <dt><code>type='dir'</code> + <span class="since">Since 0.7.5</span></dt> + <dd> + The <code>dir</code> attribute specifies the fully-qualified path + to the directory to use as the disk. + </dd> + <dt><code>type='network'</code> + <span class="since">Since 0.8.7</span></dt> + <dd> + The <code>protocol</code> attribute specifies the protocol to + access to the requested image. Possible values are "nbd", + "iscsi", "rbd", "sheepdog" or "gluster". If the + <code>protocol</code> attribute is "rbd", "sheepdog" or + "gluster", an additional attribute <code>name</code> is + mandatory to specify which volume/image will be used. For "nbd", + the <code>name</code> attribute is optional. For "iscsi" + (<span class="since">since 1.0.4</span>), the <code>name</code> + attribute may include a logical unit number, separated from the + target's name by a slash (e.g., + <code>iqn.2013-07.com.example:iscsi-pool/1</code>). If not + specified, the default LUN is zero. + </dd> + <dt><code>type='volume'</code> + <span class="since">Since 1.0.5</span></dt> + <dd> + The underlying disk source is represented by attributes + <code>pool</code> and <code>volume</code>. Attribute + <code>pool</code> specifies the name of storage pool (managed + by libvirt) where the disk source resides. Attribute + <code>volume</code> specifies the name of storage volume (managed + by libvirt) used as the disk source. + + <p> + If the underlying storage pool is "iscsi", then use the output + of the value from the "Name" column of the <code>virsh vol-list + [pool-name]</code> command for the <code>volume</code> attribute + field. It sounds like it only works when the storage pool is "iscsi". one can use "virsh vol-list" to find out the volume name for any type of storage pool.
Ah - so that's a bit of myopia trying to write something down about iscsi that had a more general purpose. Since I was only configuring iscsi I wasn't thinking about others - here's what I have now:
The underlying disk source is represented by attributes <code>pool</code> and <code>volume</code>. Attribute <code>pool</code> specifies the name of the <a href="formatstorage.html">storage pool</a> (managed by libvirt) where the disk source resides. Attribute <code>volume</code> specifies the name of storage volume (managed by libvirt) used as the disk source. The value for the <code>volume</code> attribute will be the output from the "Name" column of a <code>virsh vol-list [pool-name]</code> command.
ACK for the changes. Osier
Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret. --- docs/formatsecret.html.in | 156 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 145 insertions(+), 11 deletions(-) diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in index 3e306b5..7dd0927 100644 --- a/docs/formatsecret.html.in +++ b/docs/formatsecret.html.in @@ -46,18 +46,51 @@ </dd> </dl> - <h3>Usage type "volume"</h3> + <h3><a name="VolumeUsageType">Usage type "volume"</a></h3> <p> This secret is associated with a volume, and it is safe to delete the secret after the volume is deleted. The <code><usage type='volume'></code> element must contain a single <code>volume</code> element that specifies the key of the volume - this secret is associated with. + this secret is associated with. For example, create a demo-secret.xml + file as follows: </p> - <h3>Usage type "ceph"</h3> + <pre> + <secret ephemeral='no' private='yes'> + <description>LUKS passphrase for the main hard drive of our mail server</description> + <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> + <usage type='volume'> + <volume>/var/lib/libvirt/images/mail.img</volume> + </usage> + </secret> + </pre> + + <p> + Define the secret and set the pass phrase as follows: + </p> + <pre> + # virsh secret-define demo-secret.xml + Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created + # + # MYSECRET=`printf %s "open seseme" | base64` + # virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET + Secret value set + # + </pre> + + <p> + The volume can then be used in the XML for a disk volume + <a href="formatstorageencryption.html">encryption</a> as follows: + </p> + <pre> + <encryption format='qcow'> + <secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/> + </encryption> + </pre> + <h3><a name="CephUsageType">Usage type "ceph"</a></h3> <p> This secret is associated with a Ceph RBD (rados block device). The <code><usage type='ceph'></code> element must contain @@ -66,10 +99,57 @@ this usage name via the <code><auth></code> element of a <a href="formatdomain.html#elementsDisks">disk device</a> or a <a href="formatstorage.html">storage pool (rbd)</a>. - <span class="since">Since 0.9.7</span>. + <span class="since">Since 0.9.7</span>. The following is an example + of the steps to be taken. First create a ceph-secret.xml file: + </p> + + <pre> + <secret ephemeral='no' private='yes'> + <description>CEPH passphrase example</description> + <auth type='ceph' username='myname'/> + <usage type='ceph'> + <name>ceph_example</name> + </usage> + </secret> + </pre> + + <p> + Next, use <code>virsh secret-define ceph-secret.xml</code> to define + the secret and <code>virsh secret-set-value</code> using the generated + UUID value and a base64 generated secret value in order to define the + chosen secret pass phrase. </p> + <pre> + # virsh secret-define ceph-secret.xml + Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created + # + # virsh secret-list + UUID Usage + ----------------------------------------------------------- + 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example + # + # CEPHPHRASE=`printf %s "pass phrase" | base64` + # virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE + Secret value set - <h3>Usage type "iscsi"</h3> + # + </pre> + + <p> + The ceph secret can then be used by UUID or by the + usage name via the <code><auth></code> element in a + domain's <code><disk></code> element as follows: + </p> + <pre> + <source protocol='rbd' name='pool/image'> + <host name='mon1.example.org' port='6321'/> + </source> + <auth username='myname'> + <secret type='ceph' usage='ceph_example'/> + </auth> + </pre> + + <h3><a name="iSCSIUsageType">Usage type "iscsi"</a></h3> <p> This secret is associated with an iSCSI target for CHAP authentication. @@ -82,14 +162,68 @@ <span class="since">Since 1.0.4</span>. </p> - <h2><a name="example">Example</a></h2> - + <p> + The following is an example of the XML that may be used to generate + a secret for iSCSI CHAP authentication. First define an iscsi-secret.xml + file to describe the secret. Replace the <code>username</code> field + with the username used in your iSCSI authentication configuration file. + The description field should contain configuration specific data. + The <code>target</code> name may be any name of your choosing to + be used as the <code>usage</code> when used in the pool or disk XML + description. + </p> <pre> <secret ephemeral='no' private='yes'> - <description>LUKS passphrase for the main hard drive of our mail server</description> - <usage type='volume'> - <volume>/var/lib/libvirt/images/mail.img</volume> + <description>iSCSI passphrase for the iSCSI example.com server</description> + <auth type='chap' username='myuser'/> + <usage type='iscsi'> + <target>libvirtiscsi</target> </usage> - </secret></pre> + </secret> + </pre> + + <p> + Next, use <code>virsh secret-define iscsi-secret.xml</code> to define + the secret and <code>virsh secret-set-value</code> using the generated + UUID value and a base64 generated secret value in order to define the + chosen secret pass phrase. The pass phrase must match the password + used in the iSCSI authentication configuration file. + </p> + <pre> + # virsh secret-define secret.xml + Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created + + # virsh secret-list + UUID Usage + ----------------------------------------------------------- + c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi + + # MYSECRET=`printf %s "redhat" | base64` + # virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET + Secret value set + # + </pre> + + <p> + The iSCSI secret can then be used by UUID or by the + usage name via the <code><auth></code> element in a + domain's <code><disk></code> element as follows: + </p> + <pre> + <auth username='libvirt'> + <secret type='iscsi' usage='libvirtiscsi'/> + </auth> + </pre> + + <p> + The iSCSI secret can then be used by UUID or by the + usage name via the <code><auth></code> element in a + storage pool <code><source></code> element as follows: + </p> + <pre> + <auth type='chap' username='libvirt'> + <secret usage='libvirtiscsi'/> + </auth> + </pre> </body> </html> -- 1.8.3.1
On 08/08/2013 02:43 AM, John Ferlan wrote:
Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret. --- docs/formatsecret.html.in | 156 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 145 insertions(+), 11 deletions(-)
ACK
diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in index 3e306b5..7dd0927 100644 --- a/docs/formatsecret.html.in +++ b/docs/formatsecret.html.in @@ -46,18 +46,51 @@ </dd> </dl>
- <h3>Usage type "volume"</h3> + <h3><a name="VolumeUsageType">Usage type "volume"</a></h3>
<p> This secret is associated with a volume, and it is safe to delete the secret after the volume is deleted. The <code><usage type='volume'></code> element must contain a single <code>volume</code> element that specifies the key of the volume - this secret is associated with. + this secret is associated with. For example, create a demo-secret.xml + file as follows: </p>
- <h3>Usage type "ceph"</h3> + <pre> + <secret ephemeral='no' private='yes'> + <description>LUKS passphrase for the main hard drive of our mail server</description>
I don't think qcow encryption supports LUKS or that using it for a mail server would be a good idea. How about: <description>super secret name of my first puppy</description>
+ <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> + <usage type='volume'> + <volume>/var/lib/libvirt/images/mail.img</volume> + </usage> + </secret> + </pre> +
Jan
On 08/16/2013 11:58 AM, Ján Tomko wrote:
On 08/08/2013 02:43 AM, John Ferlan wrote:
Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret. --- docs/formatsecret.html.in | 156 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 145 insertions(+), 11 deletions(-)
ACK
diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in index 3e306b5..7dd0927 100644 --- a/docs/formatsecret.html.in +++ b/docs/formatsecret.html.in @@ -46,18 +46,51 @@ </dd> </dl>
- <h3>Usage type "volume"</h3> + <h3><a name="VolumeUsageType">Usage type "volume"</a></h3>
<p> This secret is associated with a volume, and it is safe to delete the secret after the volume is deleted. The <code><usage type='volume'></code> element must contain a single <code>volume</code> element that specifies the key of the volume - this secret is associated with. + this secret is associated with. For example, create a demo-secret.xml + file as follows: </p>
- <h3>Usage type "ceph"</h3> + <pre> + <secret ephemeral='no' private='yes'> + <description>LUKS passphrase for the main hard drive of our mail server</description>
I don't think qcow encryption supports LUKS or that using it for a mail server would be a good idea. How about: <description>super secret name of my first puppy</description>
+ <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> + <usage type='volume'> + <volume>/var/lib/libvirt/images/mail.img</volume> + </usage> + </secret> + </pre>
Fair enough - I've changed it to: + <pre> + <secret ephemeral='no' private='yes'> + <description>Super secret name of my first puppy</description> + <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> + <usage type='volume'> + <volume>/var/lib/libvirt/images/puppyname.img</volume> + </usage> + </secret> + </pre> John
On 08/08/13 08:43, John Ferlan wrote:
Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret. --- docs/formatsecret.html.in | 156 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 145 insertions(+), 11 deletions(-)
diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in index 3e306b5..7dd0927 100644 --- a/docs/formatsecret.html.in +++ b/docs/formatsecret.html.in @@ -46,18 +46,51 @@ </dd> </dl>
- <h3>Usage type "volume"</h3> + <h3><a name="VolumeUsageType">Usage type "volume"</a></h3>
<p> This secret is associated with a volume, and it is safe to delete the secret after the volume is deleted. The <code><usage type='volume'></code> element must contain a single <code>volume</code> element that specifies the key of the volume - this secret is associated with. + this secret is associated with. For example, create a demo-secret.xml
Given the way you names the xml file for other secret types in this context, this should be volume-secret.xml
+ file as follows: </p>
- <h3>Usage type "ceph"</h3> + <pre> + <secret ephemeral='no' private='yes'> + <description>LUKS passphrase for the main hard drive of our mail server</description> + <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> + <usage type='volume'> + <volume>/var/lib/libvirt/images/mail.img</volume> + </usage> + </secret> + </pre> + + <p> + Define the secret and set the pass phrase as follows: + </p> + <pre> + # virsh secret-define demo-secret.xml + Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created + # + # MYSECRET=`printf %s "open seseme" | base64` + # virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET + Secret value set + # + </pre> + + <p> + The volume can then be used in the XML for a disk volume
s/volume can/volume secret/, or s/volume can/volume type secret/, I prefer the latter one, since both of "volume" and "secret" are general terms in libvirt. And s/disk volume/storage volume/,
+ <a href="formatstorageencryption.html">encryption</a> as follows: + </p> + <pre> + <encryption format='qcow'> + <secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/> + </encryption> + </pre>
+ <h3><a name="CephUsageType">Usage type "ceph"</a></h3> <p> This secret is associated with a Ceph RBD (rados block device). The <code><usage type='ceph'></code> element must contain @@ -66,10 +99,57 @@ this usage name via the <code><auth></code> element of a <a href="formatdomain.html#elementsDisks">disk device</a> or a <a href="formatstorage.html">storage pool (rbd)</a>. - <span class="since">Since 0.9.7</span>. + <span class="since">Since 0.9.7</span>. The following is an example + of the steps to be taken. First create a ceph-secret.xml file: + </p> + + <pre> + <secret ephemeral='no' private='yes'> + <description>CEPH passphrase example</description> + <auth type='ceph' username='myname'/> + <usage type='ceph'> + <name>ceph_example</name> + </usage> + </secret> + </pre> + + <p> + Next, use <code>virsh secret-define ceph-secret.xml</code> to define + the secret and <code>virsh secret-set-value</code> using the generated + UUID value and a base64 generated secret value in order to define the + chosen secret pass phrase. </p> + <pre> + # virsh secret-define ceph-secret.xml + Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created + # + # virsh secret-list + UUID Usage + ----------------------------------------------------------- + 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example + # + # CEPHPHRASE=`printf %s "pass phrase" | base64` + # virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE + Secret value set
- <h3>Usage type "iscsi"</h3> + # + </pre> + + <p> + The ceph secret can then be used by UUID or by the + usage name via the <code><auth></code> element in a + domain's <code><disk></code> element as follows: + </p> + <pre> + <source protocol='rbd' name='pool/image'> + <host name='mon1.example.org' port='6321'/> + </source> + <auth username='myname'> + <secret type='ceph' usage='ceph_example'/> + </auth> + </pre> +
Given that you created example for storage pool chap auth. Here we should have example for storage pool ceph auth too.
+ <h3><a name="iSCSIUsageType">Usage type "iscsi"</a></h3>
<p> This secret is associated with an iSCSI target for CHAP authentication. @@ -82,14 +162,68 @@ <span class="since">Since 1.0.4</span>. </p>
- <h2><a name="example">Example</a></h2> - + <p> + The following is an example of the XML that may be used to generate + a secret for iSCSI CHAP authentication. First define an iscsi-secret.xml + file to describe the secret. Replace the <code>username</code> field + with the username used in your iSCSI authentication configuration file. + The description field should contain configuration specific data. + The <code>target</code> name may be any name of your choosing to + be used as the <code>usage</code> when used in the pool or disk XML + description. + </p> <pre> <secret ephemeral='no' private='yes'> - <description>LUKS passphrase for the main hard drive of our mail server</description> - <usage type='volume'> - <volume>/var/lib/libvirt/images/mail.img</volume> + <description>iSCSI passphrase for the iSCSI example.com server</description> + <auth type='chap' username='myuser'/> + <usage type='iscsi'> + <target>libvirtiscsi</target> </usage> - </secret></pre> + </secret> + </pre> + + <p> + Next, use <code>virsh secret-define iscsi-secret.xml</code> to define + the secret and <code>virsh secret-set-value</code> using the generated + UUID value and a base64 generated secret value in order to define the + chosen secret pass phrase. The pass phrase must match the password + used in the iSCSI authentication configuration file.
Add an example for "iSCSI authentication configuration file"?
+ </p> + <pre> + # virsh secret-define secret.xml + Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created + + # virsh secret-list + UUID Usage + ----------------------------------------------------------- + c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi + + # MYSECRET=`printf %s "redhat" | base64` + # virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET + Secret value set + # + </pre> + + <p> + The iSCSI secret can then be used by UUID or by the
[1]
+ usage name via the <code><auth></code> element in a + domain's <code><disk></code> element as follows: + </p> + <pre> + <auth username='libvirt'> + <secret type='iscsi' usage='libvirtiscsi'/> + </auth> + </pre> + + <p> + The iSCSI secret can then be used by UUID or by the
Duplicate with [1], could be more compact I think.
+ usage name via the <code><auth></code> element in a + storage pool <code><source></code> element as follows: + </p> + <pre> + <auth type='chap' username='libvirt'> + <secret usage='libvirtiscsi'/> + </auth> + </pre> </body> </html>
On 08/20/2013 02:09 AM, Osier Yang wrote:
On 08/08/13 08:43, John Ferlan wrote:
Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret. --- docs/formatsecret.html.in | 156 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 145 insertions(+), 11 deletions(-)
diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in index 3e306b5..7dd0927 100644 --- a/docs/formatsecret.html.in +++ b/docs/formatsecret.html.in @@ -46,18 +46,51 @@ </dd> </dl> - <h3>Usage type "volume"</h3> + <h3><a name="VolumeUsageType">Usage type "volume"</a></h3> <p> This secret is associated with a volume, and it is safe to delete the secret after the volume is deleted. The <code><usage type='volume'></code> element must contain a single <code>volume</code> element that specifies the key of the volume - this secret is associated with. + this secret is associated with. For example, create a demo-secret.xml
Given the way you names the xml file for other secret types in this context, this should be volume-secret.xml
Done
+ file as follows: </p> - <h3>Usage type "ceph"</h3> + <pre> + <secret ephemeral='no' private='yes'> + <description>LUKS passphrase for the main hard drive of our mail server</description> + <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> + <usage type='volume'> + <volume>/var/lib/libvirt/images/mail.img</volume> + </usage> + </secret> + </pre> + + <p> + Define the secret and set the pass phrase as follows: + </p> + <pre> + # virsh secret-define demo-secret.xml + Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created + # + # MYSECRET=`printf %s "open seseme" | base64` + # virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET + Secret value set + # + </pre> + + <p> + The volume can then be used in the XML for a disk volume
s/volume can/volume secret/, or s/volume can/volume type secret/, I prefer the latter one, since both of "volume" and "secret" are general terms in libvirt.
And s/disk volume/storage volume/,
I went with 'volume type secret' and 'storage volume'
+ <a href="formatstorageencryption.html">encryption</a> as follows: + </p> + <pre> + <encryption format='qcow'> + <secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/> + </encryption> + </pre> + <h3><a name="CephUsageType">Usage type "ceph"</a></h3> <p> This secret is associated with a Ceph RBD (rados block device). The <code><usage type='ceph'></code> element must contain @@ -66,10 +99,57 @@ this usage name via the <code><auth></code> element of a <a href="formatdomain.html#elementsDisks">disk device</a> or a <a href="formatstorage.html">storage pool (rbd)</a>. - <span class="since">Since 0.9.7</span>. + <span class="since">Since 0.9.7</span>. The following is an example + of the steps to be taken. First create a ceph-secret.xml file: + </p> + + <pre> + <secret ephemeral='no' private='yes'> + <description>CEPH passphrase example</description> + <auth type='ceph' username='myname'/> + <usage type='ceph'> + <name>ceph_example</name> + </usage> + </secret> + </pre> + + <p> + Next, use <code>virsh secret-define ceph-secret.xml</code> to define + the secret and <code>virsh secret-set-value</code> using the generated + UUID value and a base64 generated secret value in order to define the + chosen secret pass phrase. </p> + <pre> + # virsh secret-define ceph-secret.xml + Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created + # + # virsh secret-list + UUID Usage + ----------------------------------------------------------- + 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example + # + # CEPHPHRASE=`printf %s "pass phrase" | base64` + # virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE + Secret value set - <h3>Usage type "iscsi"</h3> + # + </pre> + + <p> + The ceph secret can then be used by UUID or by the + usage name via the <code><auth></code> element in a + domain's <code><disk></code> element as follows: + </p> + <pre> + <source protocol='rbd' name='pool/image'> + <host name='mon1.example.org' port='6321'/> + </source> + <auth username='myname'> + <secret type='ceph' usage='ceph_example'/> + </auth> + </pre> +
Given that you created example for storage pool chap auth. Here we should have example for storage pool ceph auth too.
OK, done. The following was added (see your comment [1] below to understand my grammar usage) <p> As well as the <code><auth></code> element in a <a href="formatstorage.html">storage pool (rbd)</a> <code><source></code> element as follows: </p> <pre> <auth type='ceph' username='myname'> <secret usage='ceph_example'/> </auth> </pre>
+ <h3><a name="iSCSIUsageType">Usage type "iscsi"</a></h3> <p> This secret is associated with an iSCSI target for CHAP authentication. @@ -82,14 +162,68 @@ <span class="since">Since 1.0.4</span>. </p> - <h2><a name="example">Example</a></h2> - + <p> + The following is an example of the XML that may be used to generate + a secret for iSCSI CHAP authentication. First define an iscsi-secret.xml + file to describe the secret. Replace the <code>username</code> field + with the username used in your iSCSI authentication configuration file. + The description field should contain configuration specific data. + The <code>target</code> name may be any name of your choosing to + be used as the <code>usage</code> when used in the pool or disk XML + description. + </p> <pre> <secret ephemeral='no' private='yes'> - <description>LUKS passphrase for the main hard drive of our mail server</description> - <usage type='volume'> - <volume>/var/lib/libvirt/images/mail.img</volume> + <description>iSCSI passphrase for the iSCSI example.com server</description> + <auth type='chap' username='myuser'/> + <usage type='iscsi'> + <target>libvirtiscsi</target> </usage> - </secret></pre> + </secret> + </pre> + + <p> + Next, use <code>virsh secret-define iscsi-secret.xml</code> to define + the secret and <code>virsh secret-set-value</code> using the generated + UUID value and a base64 generated secret value in order to define the + chosen secret pass phrase. The pass phrase must match the password + used in the iSCSI authentication configuration file.
Add an example for "iSCSI authentication configuration file"?
This is where I wasn't "as sure" we should be documenting what an iSCSI authentication configuration looks like, but for completeness I suppose I can see your point. Here's what I have: ... <span class="since">Since 1.0.4</span>. The following is an example of the XML that may be used to generate a secret for iSCSI CHAP authentication. Assume the following sample entry in an iSCSI authentication file: </p> <pre> <target iqn.2013-07.com.example:iscsi-pool> backing-store /home/tgtd/iscsi-pool/disk1 backing-store /home/tgtd/iscsi-pool/disk2 incominguser myname mysecret </target> </pre> <p> Define an iscsi-secret.xml file to describe the secret. Use the <code>incominguser</code> username used in your iSCSI authentication configuration file as the value for the <code>username</code> attribute. The <code>description</code> attribute should contain configuration specific data. The <code>target</code> name may be any name of your choosing to be used as the <code>usage</code> when used in the pool or disk XML description. </p> <pre> <secret ephemeral='no' private='yes'> <description>Passphrase for the iSCSI example.com server</description> <auth type='chap' username='myname'/> <usage type='iscsi'> <target>libvirtiscsi</target> </usage> </secret> </pre>
+ </p> + <pre> + # virsh secret-define secret.xml + Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created + + # virsh secret-list + UUID Usage + ----------------------------------------------------------- + c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi + + # MYSECRET=`printf %s "redhat" | base64`
NOTE: Changed "redhat" to "mysecret" to match the iSCSI authentication example
+ # virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET + Secret value set + # + </pre> + + <p> + The iSCSI secret can then be used by UUID or by the
[1]
NOTE: Added direct link for "<disk>" (both here and above)
+ usage name via the <code><auth></code> element in a + domain's <code><disk></code> element as follows: + </p> + <pre> + <auth username='libvirt'> + <secret type='iscsi' usage='libvirtiscsi'/> + </auth> + </pre> + + <p> + The iSCSI secret can then be used by UUID or by the
Duplicate with [1], could be more compact I think.
Replaced "The iSCSI secret can then be used by UUID or by the usage name via" with "As well as" John
+ usage name via the <code><auth></code> element in a + storage pool <code><source></code> element as follows: + </p> + <pre> + <auth type='chap' username='libvirt'> + <secret usage='libvirtiscsi'/> + </auth> + </pre> </body> </html>
Update the iSCSI storage pool example to include the secret --- docs/formatstorage.html.in | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in index f4d561f..278f89b 100644 --- a/docs/formatstorage.html.in +++ b/docs/formatstorage.html.in @@ -480,7 +480,10 @@ <name>virtimages</name> <source> <host name="iscsi.example.com"/> - <device path="demo-target"/> + <device path="iqn.2013-06.com.example:iscsi-pool"/> + <auth type='chap' username='myuser'> + <secret usage='libvirtiscsi'/> + </auth> </source> <target> <path>/dev/disk/by-path</path> -- 1.8.3.1
On 08/08/2013 02:43 AM, John Ferlan wrote:
Update the iSCSI storage pool example to include the secret --- docs/formatstorage.html.in | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
ACK Jan
On 08/07/2013 08:43 PM, John Ferlan wrote:
These patches address a couple of issues I ran into while doing extra testing on the iSCSI chap authentication patches:
https://www.redhat.com/archives/libvir-list/2013-July/msg01378.html
The first 2 or 3 patches should be candidiates to be put into rhel7.0 as updates/fixes to issues. The last 3 patches update the documentation to show how to use secrets, pools, and iSCIS devices in the domain.
John Ferlan (6): virsh: Print cephx and iscsi usage qemu_conf: Fix broken logic for adding passthrough iscsi lun Report secret usage error message similarly docs: Update the formatdomain disk examples docs: Update formatsecrets to include more examples of each type docs: Update iSCSI storage pool example
docs/formatdomain.html.in | 57 +++++++++++-- docs/formatsecret.html.in | 156 +++++++++++++++++++++++++++++++++--- docs/formatstorage.html.in | 5 +- src/qemu/qemu_command.c | 28 +++++-- src/qemu/qemu_conf.c | 2 +- src/storage/storage_backend_iscsi.c | 28 +++++-- src/storage/storage_backend_rbd.c | 35 ++++++-- tools/virsh-secret.c | 17 ++-- 8 files changed, 278 insertions(+), 50 deletions(-)
I have pushed the series now. Thanks for the reviews, John
participants (3)
-
John Ferlan -
Ján Tomko -
Osier Yang