Hide Forgot
Description of problem: In targets.conf(5), the following may be found: <target <IQN>> Defines a the start of a target definition. IQN is an ISCSI Qualified Name such as "iqn.2001-04.com.example:storage1". See "ISCSI" on Wikipedia for more information on IQNs. Within this block should be target-level directives, as documented below. The target definition ends with "</target>" There are several things wrong with this. 1. There is no URI given to access the explicit resource. 2. There is no guarantee that the resource on Wikipedia will remain the same, or useful. Indeed, the relevant page on Wikipedia currently notes that the article has "multiple issues", and any number of remedies might be applied to resolve that...not all of which beneficial to those coming by way of this manpage. 3. The manpage (a system-local resource) of a configuration file refers the reader to a remote, online resource for information crucial to understanding the syntax said configuration file. Remote online resources are not always available (or even relevant to our software versions), which is why we refer to system-local manpages in the first place. Version-Release number of selected component (if applicable): 6.4 How reproducible: Checked twice, observed twice. Steps to Reproduce: 1. yum install scsi-target-utils 2. man 5 targets.conf 3. Read... Actual results: Referred to Wikipedia. Expected results: Find needed information germain to the syntax of targets.conf, or at least a reference to further documentation installable on the system that can be expected to remain of the similar quality as the present system resources. Additional info:
Created attachment 909082 [details] targets.conf.5 wikipedia replaced by short example and RFCs
Hi, Michael and Andy, is the replacement satisfable for you? Just copied a text from RFC 3720 + mentioning RFC 3720 and 3721 in the text. Regards Jan
<target <IQN>> Defines a the start of a target definition. IQN is an ISCSI Qualified Name such as "iqn.2001-04.com.example:storage1". The name consists of: - The string "iqn." - A date code, in yyyy-mm format - A dot "." - The reversed domain name of the naming authority (person or organization) creating this iSCSI name - An optional, colon (:) prefixed, string within the character set and length boundaries that the owner of the domain name deems appropriate The iSCSI Qualified Name is documented in RFC 3720 and RFC 3721. Within this block should be target-level directives, as documented below. The target definition ends with "</target>"
Very nice! Absolutely satisfactory.
Thanks Michael for acknowledgement. It is always pleasant to have an agreement. Andy, still need you ACK for the patch.
ping Andy
Nominated for 6.8 RPL by QE.
I've tested scsi-target-utils-1.0.24-18.el6.x86_64 and "See "ISCSI" on Wikipedia for more information on IQNs." message is removed. Is this change enough? It is not what have been suggested on comment#4. The man page says: <target <IQN>> Defines a the start of a target definition. IQN is an ISCSI Qualified Name such as "iqn.2001-04.com.example:storage1". Within this block should be target-level directives, as documented below. The target definition ends with "</target>" ################################## Previously (scsi-target-utils-1.0.24-16.el6.x86_64) it said: <target <IQN>> Defines a the start of a target definition. IQN is an ISCSI Qualified Name such as "iqn.2001-04.com.example:storage1". See "ISCSI" on Wikipedia for more information on IQNs. Within this block should be target-level directives, as documented below. The target definition ends with "</target>"
My opinion is the details of the iqn format really is not strictly required to configure tgt, so we should keep it short and just omit the Wikipedia reference to resolve this bz.
I filed this bug because I was looking into setting up iscsi, and the documentation was frustrating and lacking. Even the referenced Wikipedia page didn't include the necessary information, and I had to look further afield. If you don't want to supply the information about how IQNs are defined within, then provide a stable reference for such. As it turns out, one such stable reference is RFC3720. So perhaps cite that, *not* Wikipedia. A professional, enterprise product that's supposed to have a minimum of a ten-year support cycle should have documentation reasonably guaranteed to be available during that period. It should also have a reasonably complete set of system documentation. This part of why I called out the importance of system-local references in the first place. Meanwhile, I'm not sure how you're supposed to configure tgtd without an iqn, and so it would seem appropriate to at least reference that. Jan put together a simple patch over a year and a half ago, that solved the problem cleanly and concisely. It got sat on for eighteen months waiting for an ack, and now the simple, clear and informative documentation patch is recommended against in favor of making the documentation even less informative and useful than it was. Pardon me if I sound a little irritated; I still remember how much time I spent trying to find the relevant information at the time, without a reliable web of references to draw from.
Since the problem described in this bug report should be resolved in a recent advisory, it has been closed with a resolution of ERRATA. For information on the advisory, and where to find the updated files, follow the link below. If the solution does not work for you, open a new bug report. https://rhn.redhat.com/errata/RHBA-2016-0731.html