Add -k flag and https to 2 examples #933

mellybess · 2015-12-17T22:07:26Z

In a recent customer question (in Front, so no thread available 😦) @davideg @brainstarr and I found that the example commands were missing a -k flag, and needed to be via https. The steps we documented for the customer are here.

I'm not sure if this needs to be updated for each example on the page, but I can test that if needed.

I also removed a version number from a link to the Enterprise docs so that it redirects to the latest version.

/cc @github/api, @github/docs-platform, and @github/copy

pengwynn · 2015-12-17T22:23:01Z

content/v3/enterprise/management_console.md

@@ -69,7 +69,7 @@ For a list of the available settings, see [the `/setup/api/settings` endpoint](#
 ### Example

 ``` command-line
-$ curl -L -X POST 'http://<em>hostname</em>:<em>admin_port</em>/setup/api/start' -F license=@<em>/path/to/github-enterprise.ghl</em> -F "password=<em>your-amazing-password</em>" -F settings=&lt;<em>/path/to/settings.json</em>
+$ curl -L -X -k POST 'https://<em>hostname</em>:<em>admin_port</em>/setup/api/start' -F license=@<em>/path/to/github-enterprise.ghl</em> -F "password=<em>your-amazing-password</em>" -F settings=&lt;<em>/path/to/settings.json</em>


I think the flag order might matter here since POST is an argument to -X. Should this be -X POST -k ...?

jacobbednarz · 2015-12-17T22:37:24Z

content/v3/enterprise/management_console.md

@@ -69,7 +69,7 @@ For a list of the available settings, see [the `/setup/api/settings` endpoint](#
 ### Example

 ``` command-line
-$ curl -L -X POST 'http://<em>hostname</em>:<em>admin_port</em>/setup/api/start' -F license=@<em>/path/to/github-enterprise.ghl</em> -F "password=<em>your-amazing-password</em>" -F settings=&lt;<em>/path/to/settings.json</em>
+$ curl -L -X POST -k 'https://<em>hostname</em>:<em>admin_port</em>/setup/api/start' -F license=@<em>/path/to/github-enterprise.ghl</em> -F "password=<em>your-amazing-password</em>" -F settings=&lt;<em>/path/to/settings.json</em>


Is allowing insecure connections something you'd want to promote via documentation? Passing in the -k flag will ignore any SSL warnings (such as mismatching certificates) and allow the connection to proceed anyway which has some potential security concerns. Personally, if I was sending my GitHub license or credentials across the wire I'd definitely like to ensure the host I am connecting to is who I intend it to be. However, on the flip side of that, I do realise a lot of places that setup on their internal network won't bother with valid certificates so ¯\_(ツ)_/¯.

@jacobbednarz GitHub Enterprise provides a self-signed certificate. For many, I assume the lack of -k blocks these admins from using curl to work with the API.

Enterprise customers should configure a proper certificate though and that is strongly recommended. I would be in favor of not adding -k and only add a comment for using it if absolutely necessary. Always adding as a blanket solution is not a good idea.

👍 I think adding a comment explaining the -k option is the right approach.

gjtorikian · 2015-12-17T23:08:13Z

I'm not sure if this needs to be updated for each example on the page, but I can test that if needed.

I just tested it; looks like curl to HTTP will not work. I used the maintenance settings check as it's one of the few GET requests on there.

I did not pass -k, but I don't really know the intricacies of the cert dance. It's interesting to note also that this was pointed out to need to be HTTPS but we didn't change it. 😓

If you could change the other examples to https that would be great! I am not sure if they need -k or not but verifying that would be cool. 👍

davideg · 2015-12-22T21:31:48Z

content/v3/enterprise/management_console.md

@@ -47,6 +47,8 @@ When using this endpoint, your Enterprise instance must have a password set. Thi
 1. If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
 2. If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password parameter.

+You may also need to use the `-k` flag, as GitHub Enterprise uses a self-signed certificate before you [enable your own SSL certificate](https://help.github.com/enterprise/admin/guides/installation/dns-hostname-subdomain-isolation-and-ssl/#ssl).


I would make it clear that the -k flag applies to using curl.

mellybess · 2015-12-23T21:56:19Z

I've added a note about needing the -k flag and updated http to https in the examples.

@pengwynn @github/docs-platform @github/copy is this 👍 to merge?

s/sicne/since/

davideg · 2015-12-23T23:01:17Z

content/v3/enterprise/management_console.md

@@ -47,6 +47,8 @@ When using this endpoint, your Enterprise instance must have a password set. Thi
 1. If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
 2. If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password parameter.

+You may also need to add the `-k` flag when using `curl`, since GitHub Enterprise uses a self-signed certificate before you [add your own SSL certificate](https://help.github.com/enterprise/admin/guides/installation/dns-hostname-subdomain-isolation-and-ssl/#ssl).


@mellybess I would add a small bit about what the -k flag does or at least add a link to http://curl.haxx.se/docs/manpage.html#-k (not sure if linking out to external pages in these docs is cool or not).

Also since this tip applies when using any self-signed certificate it could apply to all endpoints. I'm wondering if it would make sense to move it up towards the top of the document after the tip section.

Add -k flag and https to 2 examples

Add -k flag and https to 2 examples

3aa3220

pengwynn reviewed Dec 17, 2015
View reviewed changes

reorder -k for new key and uploading a license

1bfd074

jacobbednarz reviewed Dec 17, 2015
View reviewed changes

add note about -k flag, remove from examples

b931827

davideg reviewed Dec 22, 2015
View reviewed changes

mellybess added 2 commits December 22, 2015 14:00

add curl caveat and update language

4a91f27

update all examples to https

b5a405c

fix typo

7055fe3

s/sicne/since/

davideg reviewed Dec 23, 2015
View reviewed changes

add link re: -k flag and move note to tip section

08af3ae

pengwynn added a commit that referenced this pull request Jan 4, 2016

Merge pull request #933 from github/management-console-update

309e10b

Add -k flag and https to 2 examples

pengwynn merged commit 309e10b into master Jan 4, 2016

pengwynn deleted the management-console-update branch January 4, 2016 18:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add -k flag and https to 2 examples #933

Add -k flag and https to 2 examples #933

Uh oh!

mellybess commented Dec 17, 2015

Uh oh!

pengwynn Dec 17, 2015

Uh oh!

jacobbednarz Dec 17, 2015

Uh oh!

gjtorikian Dec 17, 2015

Uh oh!

jacobbednarz Dec 17, 2015

Uh oh!

dbussink Dec 18, 2015

Uh oh!

davideg Dec 18, 2015

Uh oh!

gjtorikian commented Dec 17, 2015

Uh oh!

davideg Dec 22, 2015

Uh oh!

mellybess commented Dec 23, 2015

Uh oh!

davideg Dec 23, 2015

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Add -k flag and https to 2 examples #933

Add -k flag and https to 2 examples #933

Uh oh!

Conversation

mellybess commented Dec 17, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gjtorikian commented Dec 17, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mellybess commented Dec 23, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.