Topics

proper way to do trouble-shooting containing console commands


Weiwu Zhang <weiwu.zhang@...>
 

Hi just made my first troubleshoot guide that instructs the user to type a few commands to find the problem.

I've got a dilemma here:

- if I put the command-to-type in <cmdname> I feel wrong because <cmdname> is for the name of the command, not the full command.

- if I put the command-to-type inside the <codeblock> I feel wrong too since that is included in the <stepresult> but it's not part of the result.

What would you normally do?

Thanks!

--

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE troubleshooting PUBLIC "-//OASIS//DTD DITA Troubleshooting//EN" "troubleshooting.dtd">
<troubleshooting id="troubleshooting_signing">
<title>Troubleshooting Signing</title>
<troublebody>
<condition>
<title>Wrong key used for signing</title>
<p>Error on the singing</p>
</condition>
<troubleSolution>
<cause>
<title>Cause</title>
<p>The signing key doesn't match the certificate.</p>
</cause>
<remedy>
<title>Remedy</title>
<responsibleParty>Token Issuer</responsibleParty>
<steps>
<step>
<cmd>Use <cmdname>openssl ec -in key -pubout</cmdname> command (replace
<codeph>key</codeph> with your actual key file) to generate the
public key from the private key. Run the following command:</cmd>
<stepresult>
<codeblock>read EC key
writing EC key
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwXfiK2ao/T8EDv02rr1a0xZYKkox
v3FGDltKFLsZNIyTUo5RAhFh8RXy8/hqSlozGfd3pOx/70LeGzbWd/ExQg==
-----END PUBLIC KEY-----</codeblock>
</stepresult>
</step>

<step>
<cmd>Use <cmdname>openssl x509 -pubkey -in crt</cmdname> command (replace
<codeph>crt</codeph> with your actual certificate file) to show the
public key in the certificate's subject:</cmd>
<stepresult>
<codeblock>$ -----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwXfiK2ao/T8EDv02rr1a0xZYKkox
v3FGDltKFLsZNIyTUo5RAhFh8RXy8/hqSlozGfd3pOx/70LeGzbWd/ExQg==
-----END PUBLIC KEY-----</codeblock>
</stepresult>
</step>
<step>
<cmd>Check if the public key generated from the private key is the same as
the public key in the certificate's subject. If they are not the same,
your key doesn't match your certificate. Try to obtain the right key /
certificate.</cmd>
</step>
</steps>
</remedy>
</troubleSolution>
</troublebody>
</troubleshooting>


Kristen James Eberlein
 

Use <userinput> for a command that the user should type.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 9/1/2020 6:35 AM, Weiwu Zhang via groups.io wrote:

Hi just made my first troubleshoot guide that instructs the user to type a few commands to find the problem.

I've got a dilemma here:

- if I put the command-to-type in <cmdname> I feel wrong because <cmdname> is for the name of the command, not the full command.

- if I put the command-to-type inside the <codeblock> I feel wrong too since that is included in the <stepresult> but it's not part of the result.

What would you normally do?

Thanks!

--

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE troubleshooting PUBLIC "-//OASIS//DTD DITA Troubleshooting//EN" "troubleshooting.dtd">
<troubleshooting id="troubleshooting_signing">
    <title>Troubleshooting Signing</title>
    <troublebody>
        <condition>
            <title>Wrong key used for signing</title>
            <p>Error on the singing</p>
        </condition>
        <troubleSolution>
            <cause>
                <title>Cause</title>
                <p>The signing key doesn't match the certificate.</p>
            </cause>
            <remedy>
                <title>Remedy</title>
                <responsibleParty>Token Issuer</responsibleParty>
                <steps>
                    <step>
                        <cmd>Use <cmdname>openssl ec -in key -pubout</cmdname> command (replace
                                <codeph>key</codeph> with your actual key file) to generate the
                            public key from the private key. Run the following command:</cmd>
                        <stepresult>
                            <codeblock>read EC key
writing EC key
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwXfiK2ao/T8EDv02rr1a0xZYKkox
v3FGDltKFLsZNIyTUo5RAhFh8RXy8/hqSlozGfd3pOx/70LeGzbWd/ExQg==
-----END PUBLIC KEY-----</codeblock>
                        </stepresult>
                    </step>

                    <step>
                        <cmd>Use <cmdname>openssl x509 -pubkey -in crt</cmdname> command (replace
                                <codeph>crt</codeph> with your actual certificate file) to show the
                            public key in the certificate's subject:</cmd>
                        <stepresult>
                            <codeblock>$ -----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwXfiK2ao/T8EDv02rr1a0xZYKkox
v3FGDltKFLsZNIyTUo5RAhFh8RXy8/hqSlozGfd3pOx/70LeGzbWd/ExQg==
-----END PUBLIC KEY-----</codeblock>
                        </stepresult>
                    </step>
                    <step>
                        <cmd>Check if the public key generated from the private key is the same as
                            the public key in the certificate's subject. If they are not the same,
                            your key doesn't match your certificate. Try to obtain the right key /
                            certificate.</cmd>
                    </step>
                </steps>
            </remedy>
        </troubleSolution>
    </troublebody>
</troubleshooting>




 

Tag anything that a user types with <userinput>.  
Grant

On Tue, Sep 1, 2020 at 4:36 AM Weiwu Zhang via groups.io <weiwu.zhang=alphawallet.com@groups.io> wrote:

Hi just made my first troubleshoot guide that instructs the user to type a
few commands to find the problem.

I've got a dilemma here:

- if I put the command-to-type in <cmdname> I feel wrong because <cmdname>
is for the name of the command, not the full command.

- if I put the command-to-type inside the <codeblock> I feel wrong too
since that is included in the <stepresult> but it's not part of the
result.

What would you normally do?

Thanks!

--

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE troubleshooting PUBLIC "-//OASIS//DTD DITA Troubleshooting//EN" "troubleshooting.dtd">
<troubleshooting id="troubleshooting_signing">
     <title>Troubleshooting Signing</title>
     <troublebody>
         <condition>
             <title>Wrong key used for signing</title>
             <p>Error on the singing</p>
         </condition>
         <troubleSolution>
             <cause>
                 <title>Cause</title>
                 <p>The signing key doesn't match the certificate.</p>
             </cause>
             <remedy>
                 <title>Remedy</title>
                 <responsibleParty>Token Issuer</responsibleParty>
                 <steps>
                     <step>
                         <cmd>Use <cmdname>openssl ec -in key -pubout</cmdname> command (replace
                                 <codeph>key</codeph> with your actual key file) to generate the
                             public key from the private key. Run the following command:</cmd>
                         <stepresult>
                             <codeblock>read EC key
writing EC key
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwXfiK2ao/T8EDv02rr1a0xZYKkox
v3FGDltKFLsZNIyTUo5RAhFh8RXy8/hqSlozGfd3pOx/70LeGzbWd/ExQg==
-----END PUBLIC KEY-----</codeblock>
                         </stepresult>
                     </step>

                     <step>
                         <cmd>Use <cmdname>openssl x509 -pubkey -in crt</cmdname> command (replace
                                 <codeph>crt</codeph> with your actual certificate file) to show the
                             public key in the certificate's subject:</cmd>
                         <stepresult>
                             <codeblock>$
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwXfiK2ao/T8EDv02rr1a0xZYKkox
v3FGDltKFLsZNIyTUo5RAhFh8RXy8/hqSlozGfd3pOx/70LeGzbWd/ExQg==
-----END PUBLIC KEY-----</codeblock>
                         </stepresult>
                     </step>
                     <step>
                         <cmd>Check if the public key generated from the private key is the same as
                             the public key in the certificate's subject. If they are not the same,
                             your key doesn't match your certificate. Try to obtain the right key /
                             certificate.</cmd>
                     </step>
                 </steps>
             </remedy>
         </troubleSolution>
     </troublebody>
</troubleshooting>




danlittman
 

On Tue, Sep 1, 2020 at 03:35 AM, Weiwu Zhang wrote:
<condition>
<title>Wrong key used for signing</title>
<p>Error on the singing</p>
</condition>
Weiwu, just want to point out before you release this error message that the <p> </p> says singing, instead of signing.


Weiwu Zhang
 

On Wed, 2 Sep 2020, danlittman via groups.io wrote:

Weiwu, just want to point out before you release this error message
that the <p> </p> says singing, instead of signing. _._,_._,_
Weiwu here. Thank you! And thank you everyone who proposed the new
element.