Bug 1275128 - Reorg sections on examples with new additions
Reorg sections on examples with new additions
Status: CLOSED CURRENTRELEASE
Product: Red Hat Satellite 6
Classification: Red Hat
Component: Docs API Guide (Show other bugs)
6.1.2
Unspecified Unspecified
medium Severity medium (vote)
: Beta
: 6.2
Assigned To: David O'Brien
Russell Dickenson
:
: 1280172 (view as bug list)
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2015-10-25 22:36 EDT by David O'Brien
Modified: 2016-04-27 20:06 EDT (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2016-04-27 20:06:50 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description David O'Brien 2015-10-25 22:36:55 EDT
Description of problem:

Several bugs about examples were addressed in this release and need to reorg the example section a bit to keep it coherent.

"Chapt 4: Examples" is messy atm and needs fixing.



Expected results:

All the examples for a particular approach (Python, Curl, etc) should be in the same section.

Additional info:

Need to clean up some file names, terminology, tags, and general phraseology along the way.


Document URL: 

Section Number and Name: 

Describe the issue: 

Suggestions for improvement: 

Additional information:
Comment 4 David O'Brien 2015-11-02 01:03:49 EST
This is done for async and will be ready for QA after I merge bz1209202
Comment 5 David O'Brien 2015-11-04 23:42:46 EST
This was partly done and reviewed as part of 1209202, but there's more to do so I'm going to leave it open. Unlikely to get more done for async; I'll see how time goes.
Comment 9 David O'Brien 2015-12-17 01:11:30 EST
modified:   en-US/Example_Curl_Upload.xml

s/50.000/50,000/ when referring to byte size in "Complete Example of Uploading Content"

Etherpad updated with start of revised ToC.
Comment 15 Andrew Dahms 2016-02-11 00:17:40 EST
Assigning Russell as the QA contact.
Comment 16 David O'Brien 2016-02-11 21:11:24 EST
Note that Chapt 4 is actually chapter 3 now, due to work on some other bugs.
Comment 17 David O'Brien 2016-02-11 21:14:23 EST
Red Hat Satellite uses HTTPS ⁠[1] over SSL, which provides a degree of encryption and identity verification when communicating with a Red Hat Satellite Server.

Isn't this an option, rather than a blanket statement? You can turn off SSL whenever you like.
Comment 18 David O'Brien 2016-02-11 21:19:42 EST
Procedure 2.1. Obtaining a Certificate
Step 2: # grep -r "SSLCertificateFile" /etc/httpd/conf.d but then there is a note that says "The default location of self-signed certificates is usually /var/www/html/pub/katello-server-ca.crt." Why include this seemingly conflicting info?


Also, at the end of the section: "This imports the certificate into the Network Security Services (NSS) database, which means you can omit the --cacert option for each request."

Example request using and not using --cacert option?
Comment 19 David O'Brien 2016-02-11 21:22:58 EST
Section 2.1 Using SSL Authentication
Use   the following command to permanently include the certificate in the curl CA store: 

# certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "Red Hat   Satellite" -i /path/to/ca-cert-file 

Shouldn't that read something like "to include the certificate in the CA store that curl can access"? Does curl have a CA store?
Comment 20 Adam Price 2016-02-15 16:58:04 EST
(In reply to David O'Brien from comment #17)
> Red Hat Satellite uses HTTPS ⁠[1] over SSL, which provides a degree of
> encryption and identity verification when communicating with a Red Hat
> Satellite Server.
> 
> Isn't this an option, rather than a blanket statement? You can turn off SSL
> whenever you like.

Non-SSL communications are not supported by Satellite 6.
Comment 21 David O'Brien 2016-02-15 18:08:07 EST
(In reply to Adam Price from comment #20)
> (In reply to David O'Brien from comment #17)
> > Red Hat Satellite uses HTTPS ⁠[1] over SSL, which provides a degree of
> > encryption and identity verification when communicating with a Red Hat
> > Satellite Server.
> > 
> > Isn't this an option, rather than a blanket statement? You can turn off SSL
> > whenever you like.
> 
> Non-SSL communications are not supported by Satellite 6.

Hi Adam

I know I'm being pedantic now, but is that "not supported (by RH)" or "doesn't work"?

I ask because ⁠section "3.2.1. Creating Objects Using Ruby" is followed by a warning:
"This script does not use SSL communication for interacting with the REST API and is provided here only as a demonstration."

thanks
Comment 22 David O'Brien 2016-02-15 20:12:03 EST
Comment 18 and Comment 19 are still need-info.
Comment 23 Adam Price 2016-02-16 11:02:27 EST
(In reply to David O'Brien from comment #21)
> (In reply to Adam Price from comment #20)
> > (In reply to David O'Brien from comment #17)
> > > Red Hat Satellite uses HTTPS ⁠[1] over SSL, which provides a degree of
> > > encryption and identity verification when communicating with a Red Hat
> > > Satellite Server.
> > > 
> > > Isn't this an option, rather than a blanket statement? You can turn off SSL
> > > whenever you like.
> > 
> > Non-SSL communications are not supported by Satellite 6.
> 
> Hi Adam
> 
> I know I'm being pedantic now, but is that "not supported (by RH)" or
> "doesn't work"?
> 
> I ask because ⁠section "3.2.1. Creating Objects Using Ruby" is followed by a
> warning:
> "This script does not use SSL communication for interacting with the REST
> API and is provided here only as a demonstration."
> 
> thanks

It looks like in your draft the text reads 'This script does not use SSL verification...' for both the python and ruby scripts. So SSL is still being used for communication, it's just that the scripts aren't verifying the server. It isn't possible to write a script against Satellite's API that does not use SSL.
Comment 24 Adam Price 2016-02-16 11:11:39 EST
(In reply to David O'Brien from comment #18)
> Procedure 2.1. Obtaining a Certificate
> Step 2: # grep -r "SSLCertificateFile" /etc/httpd/conf.d but then there is a
> note that says "The default location of self-signed certificates is usually
> /var/www/html/pub/katello-server-ca.crt." Why include this seemingly
> conflicting info?
> 
> 
> Also, at the end of the section: "This imports the certificate into the
> Network Security Services (NSS) database, which means you can omit the
> --cacert option for each request."
> 
> Example request using and not using --cacert option?

I think it would make more sense to instruct the user to curl/wget a cert for the Satellite they're trying to communicate with from http://satellite.server.com/pub/katello-server-ca.crt rather than mentioning odd ways to get at the cert from multiple locations.
Comment 25 Adam Price 2016-02-16 11:41:56 EST
(In reply to David O'Brien from comment #19)
> Section 2.1 Using SSL Authentication
> Use   the following command to permanently include the certificate in the
> curl CA store: 
> 
> # certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "Red Hat   Satellite" -i
> /path/to/ca-cert-file 
> 
> Shouldn't that read something like "to include the certificate in the CA
> store that curl can access"? Does curl have a CA store?

Yes, you're correct. That is not a CA-store owned by curl, but rather it is one that curl can access to verify hosts that lives in your $HOME. I tried this myself just to double-check that I could then curl without needing the -k option afterwards.

# create a new DB if you don't already have one
$ certutil -N -d sql:$HOME/.pki/nssdb

$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "Red Hat Satellite" -i /path/to/ca-cert

$ curl -X GET -u admin:changeme https://satellite6.example.com/api/v2/hosts
{
  "total": 2,
  ...,
  "results": [
    ...
  ]
}

success!
Comment 27 David O'Brien 2016-02-19 00:07:13 EST
*** Bug 1280172 has been marked as a duplicate of this bug. ***
Comment 29 David O'Brien 2016-02-21 23:01:24 EST
Russell,
I'm going to take Comment #25 out of here and raise it separately to avoid making this branch any more complex than it is.

Comment #28 fixed and added to MR.
Comment 31 David O'Brien 2016-03-07 18:09:40 EST
Thanks Russell.
Comment 32 Andrew Dahms 2016-04-27 20:06:50 EDT
This content is now live on the Customer Portal.

Closing.

Note You need to log in before you can comment on or make changes to this bug.