Mailing List Archive: Apache: Docs

A review of SSL docs WAS Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD

Index | Next | Previous | View Threaded

DRuggeri at primary

Apr 4, 2012, 4:20 PM

Post #1 of 5 (139 views)
Permalink

A review of SSL docs WAS Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD

On 4/4/2012 8:39 AM, Rich Bowen wrote:
> Here's what I'd like to see happen, personally.
>
> * A review of the existing SSL sub-tree
> (http://httpd.apache.org/docs/trunk/ssl/) for both content and
> structure, and a recommendation of how it could be better structures
> (ie, a T.O.C. for that subtree)
> * Prose for the various "chapters" in that section.

I have reviewed these docs, Rich, and have some notes to provide. I'd
like if other folks would have a look, too, so we can maybe get things
in good shape sooner rather than later. I'm ready to move on a few
things but would like to get consensus on two things below...

http://httpd.apache.org/docs/trunk/ssl/ssl_howto.html - The examples are
still valid in today's world. I'm not sure if this particular doc is the
place.... but having SSL proxy examples would also be helpful since all
of those directives actually come from mod_ssl (and there are pointers
in the proxy doco to mod_ssl). Thoughts?

http://httpd.apache.org/docs/trunk/ssl/ssl_intro.html - No rubbish here.
I think this document is outstanding.

http://httpd.apache.org/docs/trunk/ssl/ssl_compat.html - This document
may no longer be relevant. There have been so many changes since
creation that I think this doc could be scrapped or repurposed to
discuss integration issues only. Some examples would include notes about
older browsers and supported levels of crypto, the emergence of TLS1.1,
SNI and compatible browsers, OCSP, etc. I'm willing to take a whack at
it and will write a bug to make myself do it in the coming days if the
list agrees.

http://httpd.apache.org/docs/trunk/ssl/ssl_faq.html - Could use a
general refreshing... most of the content isn't bad, but it could stand
to be reorganized. Does anyone else kind of feel like this kind of
document would be better served as a wiki article?

By the way, great job on these docs. SSL is a tough topic and I think
there is more than enough content here to get someone going and keep
them going for a while. It reads like an expert wrote it for fledgeling
server admin and I'm not sure I agree with a lot of the assertions made
about the content recently.

--
Daniel Ruggeri

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

mads at toftum

Apr 4, 2012, 4:42 PM

Post #2 of 5 (131 views)
Permalink

Re: A review of SSL docs WAS Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

On Wed, Apr 04, 2012 at 06:20:48PM -0500, Daniel Ruggeri wrote:
> I have reviewed these docs, Rich, and have some notes to provide. I'd
> like if other folks would have a look, too, so we can maybe get things
> in good shape sooner rather than later. I'm ready to move on a few
> things but would like to get consensus on two things below...
>
> http://httpd.apache.org/docs/trunk/ssl/ssl_howto.html - The examples are
> still valid in today's world. I'm not sure if this particular doc is the
> place.... but having SSL proxy examples would also be helpful since all
> of those directives actually come from mod_ssl (and there are pointers
> in the proxy doco to mod_ssl). Thoughts?

I think this would be a good place for a proxy example. Looking for 2
seconds, I think the logging section could do with some more work.
>
> http://httpd.apache.org/docs/trunk/ssl/ssl_intro.html - No rubbish here.
> I think this document is outstanding.
>
+1

> http://httpd.apache.org/docs/trunk/ssl/ssl_compat.html - This document
> may no longer be relevant. There have been so many changes since
> creation that I think this doc could be scrapped or repurposed to
> discuss integration issues only. Some examples would include notes about
> older browsers and supported levels of crypto, the emergence of TLS1.1,
> SNI and compatible browsers, OCSP, etc. I'm willing to take a whack at
> it and will write a bug to make myself do it in the coming days if the
> list agrees.

What's there now is ancient and could be dropped.
>
> http://httpd.apache.org/docs/trunk/ssl/ssl_faq.html - Could use a
> general refreshing... most of the content isn't bad, but it could stand
> to be reorganized. Does anyone else kind of feel like this kind of
> document would be better served as a wiki article?
>
Given the complexity of SSL in general, I prefer we keep the faq where
it is rather than abandon it on the wiki. But +1 to a cleanup.
>
>
> By the way, great job on these docs. SSL is a tough topic and I think
> there is more than enough content here to get someone going and keep
> them going for a while. It reads like an expert wrote it for fledgeling
> server admin and I'm not sure I agree with a lot of the assertions made
> about the content recently.
>
Agreed 100%. Most of the credit goes to Ralf S Engelschall who wrote
mod_ssl and most of the docs in question. Little has happened to them
since then. I think some of the assertions come from people who don't
appreciate his style of writing - much of his original mod_rewrite
documentation got butchered on a similar background.

vh

Mads Toftum
--
http://soulfood.dk

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

rbowen at rcbowen

Apr 5, 2012, 6:08 AM

Post #3 of 5 (126 views)
Permalink

Re: A review of SSL docs WAS Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

On Apr 4, 2012, at 7:20 PM, Daniel Ruggeri wrote:

> http://httpd.apache.org/docs/trunk/ssl/ssl_howto.html - The examples are
> still valid in today's world. I'm not sure if this particular doc is the
> place.... but having SSL proxy examples would also be helpful since all
> of those directives actually come from mod_ssl (and there are pointers
> in the proxy doco to mod_ssl). Thoughts?

Yes, that would be awesome.

> http://httpd.apache.org/docs/trunk/ssl/ssl_intro.html - No rubbish here.
> I think this document is outstanding.

Excellent.

> http://httpd.apache.org/docs/trunk/ssl/ssl_compat.html - This document
> may no longer be relevant. There have been so many changes since
> creation that I think this doc could be scrapped or repurposed to
> discuss integration issues only. Some examples would include notes about
> older browsers and supported levels of crypto, the emergence of TLS1.1,
> SNI and compatible browsers, OCSP, etc. I'm willing to take a whack at
> it and will write a bug to make myself do it in the coming days if the
> list agrees.
>
> http://httpd.apache.org/docs/trunk/ssl/ssl_faq.html - Could use a
> general refreshing... most of the content isn't bad, but it could stand
> to be reorganized. Does anyone else kind of feel like this kind of
> document would be better served as a wiki article?

I don't much care where the doc is, as long as everything is interlinked so that someone doesn't have to go hunting for it. Having it in the doc, rather than in the wiki, has the advantage that it's there on an installed system and accessible without going out to the network.

> By the way, great job on these docs. SSL is a tough topic and I think
> there is more than enough content here to get someone going and keep
> them going for a while. It reads like an expert wrote it for fledgeling
> server admin and I'm not sure I agree with a lot of the assertions made
> about the content recently.

Those comments come entirely from my ignorance of the topic. My apologies.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache

rbowen at rcbowen

Apr 6, 2012, 6:31 AM

Post #4 of 5 (123 views)
Permalink

Re: A review of SSL docs WAS Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

On Apr 4, 2012, at 7:42 PM, Mads Toftum wrote:

> I think some of the assertions come from people who don't
> appreciate his style of writing - much of his original mod_rewrite
> documentation got butchered on a similar background.

Yep. Our users are just begging for the good old days when the documentation started with a warning that they were about to be dreadfully confused, and then proceeded to call them silly for wanting it to do useful things. Ah, nostalgia.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache

i.galic at brainsware

Apr 10, 2012, 6:29 AM

Post #5 of 5 (116 views)
Permalink

Re: A review of SSL docs WAS Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

----- Original Message -----
>
>
>
> On Apr 4, 2012, at 7:42 PM, Mads Toftum wrote:
>
>
> I think some of the assertions come from people who don't
> appreciate his style of writing - much of his original mod_rewrite
> documentation got butchered on a similar background.
>
>
>
> Yep. Our users are just begging for the good old days when the
> documentation started with a warning that they were about to be
> dreadfully confused, and then proceeded to call them silly for
> wanting it to do useful things. Ah, nostalgia.

Judging from the feedback on on Sander's poll, as well as
from recent experience on #httpd, people expect our docs to
be so bad or useless that they don't even bother looking,
and just ask for a howto.

Now, I'm not a big fan of howtos, or rather, for what generally
passes as howtos. But it would be really nice if our docs
covered the basic use-cases.

Much of that is already happening. One of the things were
I see room for improvement is

http://httpd.apache.org/docs/current/

The separation of topics is good, but they are sorted
alphabetically, which is not very useful.

A glaringly obvious gap is a soft-intro.

*) I'm an aspiring systems administrator, I've never run
a web server. Where do I start?

*) I know what a web server is, but I've never touched
Apache httpd, how do I get started?

*) I'm a PHP/Perl/Ruby/Python hacker. What do I need to
do to setup an environment like my admins will be running

oh, and maybe, fitting to the subject line:

*) How do I actually secure my site with HTTPS?

> --
> Rich Bowen
> rbowen [at] rcbowen :: @rbowen
> rbowen [at] apache

That's all folks o/~

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads