Enabling Markdown on your apache webserver - update 3

Last time on "Enabling Markdown on your apache webserver":

• I created a perl CGI handler to render Markdown into HTML
• I updated (rewrote) the CGI handler to use ruby and the redcarpet gem.

And now, the exciting conclusion....

I've updated my CGI handler yet again with a few new features and I've posted it on my GitHub account, in the docs-on-clearance repo (get 'em cheap while they're all marked down! yuk yuk yuk). The new features are:

1. Included an Apache config snippet that you can just drop into an include directory.

2. The rendered HTML now has a stylesheet! And not just any stylesheet - a cool responsive Bootstrap stylesheet loaded from a CDN! Yes, it's mostly the plain default one with some margins, but it looks a lot better.

3. I enabled table-of-contents links for all header sections so you can have URI fragments that point directly to sections of your document. I consider this unfinished as the fragments are of the form #toc_2 - which isn't very useful. I believe the latest versions of the gem have GitHub style toc fragments, but that's not what is in the ubuntu package repos.

4. I've added support for caching the rendered HTML with memcached. This is more like a nice-to-have, but since we're going to use this full-time for internal documentation at $WORK, I figured I should make the extra effort. Of course, I chose poorly an outdated gem to implement this with, but it's ship now, fix later. Updating to Dalli or something on the ToDo list.

tl;dr - see the docs-on-clearance repo for the code.

As always, I welcome comments, suggestions and pull requests.

Enabling Markdown on your apache webserver - redux

In a previous post I enabled previewing of Markdown formatted documents using the Text::Markdown perl module. However simple that module was to implement, it only implemented daringfireball markdown. Things at $WORK have ramped up the adoption of Markdown and the atrophied standard is not enough. So, I've had to find another renderer.

Started by looking at how GitHub renders markdown and found they use the Redcarpet gem. The examples in the documentation combined with the ruby-redcarpet Ubuntu package make this a pretty simple exercise in upgrading my Markdown renderer:

1. Install the Redcarpet gem:



apt-get install ruby-redcarpet



2. Replace ye olde Markdown.cgi with new hotness Markdown.cgi



#!/usr/bin/ruby
require 'redcarpet'
print "Content-type: text/html\n\n"
markdown = Redcarpet::Markdown.new(
    Redcarpet::Render::HTML,
    :autolink => true,
    :fenced_code_blocks => true,
)
puts markdown.render(File.read(ENV['PATH_TRANSLATED']))



3. Start your browser, surf the docs!

UPDATE: I've updated my renderer for Markdown.

Enabling Markdown on your apache webserver

At $WORK, we're toying with moving all documentation with Markdown and git. To do that I needed to be able to render it locally to preview before pushing to GitHub, Bitbucket or another yet-to-be-determined repository. This setup was rather quick, easy and painless. Here's the steps:

1. Install Text::Markdown as your converter. The perl-Text-Markdown RPM was in the repoforge repository:

sudo yum install perl-Text-Markdown

2. The package comes with a script that does all the heavy lifting. It just needs to be slightly tweaked to make it run as a CGI.

$ cp -p /usr/bin/Markdown.pl $CGIBIN/Markdown.cgi
$ cd $CGIBIN
$ vi Markdown.cgi
$ diff -U0 /usr/bin/Markdown.pl Markdown.cgi
--- /usr/bin/Markdown.pl        2011-02-10 11:50:20.000000000 -0500
+++ Markdown.cgi        2012-10-26 12:08:53.000000000 -0400
@@ -147 +147,2 @@
-print main(@ARGV) unless caller();
+print "Content-type: text/html\n\n";
+print main($ENV{PATH_TRANSLATED}) unless caller();

3. Configure an apache handler to hand all Markdown-formatted files to your action.

Action markdown /cgi-bin/Markdown.cgi
AddHandler markdown .md

4. Gracefully restart apache

sudo apachectl graceful

Tips: This is for private previewing. Don't put this on your public webserver. If you do, you're asking for the wrath of the ancient CGI deities to descend upon your server and sunder it to ashes. If I was doing this for a public facing site, I'd use something that caches the opcode for the script (most likely in another programming language as well), caches the rendered page in memcache, etc. etc. You've been warned.

UPDATE: I've updated my renderer for Markdown.

Building RPMs cleanly

I recently found this script recently to build a solr rpm and I love how it simply solves so many problems with RPM packaging with a few defines. Here's my slightly modified version for building an apache package, which leaves the SOURCES directory untouched and keeps a log of the build so you can go back and review it later:

#!/bin/sh -x
rm -rf BUILD RPMS SRPMS tmp || true
mkdir -p BUILD RPMS SRPMS tmp

rpmbuild -bb --define="_topdir $PWD" --define="_tmppath $PWD/tmp" apache.spec 2>&1 | tee apache-build.txt

Log housekeeping with python

This week I was able to finally finish some python code I've been writing for $WORK - a script to rotate webserver logs directly to S3. This task was similar to something I'd done a long, LONG time ago (14 years since the first rev!) in a programming language far, far away. I had a much bigger chip on my shoulder then -  site analytics really isn't done with log parsing anymore, so I skipped the whole test for open filehandles and email notifications. Anywhere, here it is - enjoy!

https://github.com/dialt0ne/rotate-to-s3

Kudos to Justin for critiquing my python.

Self-signing a certificate... quickly

I've been using SSL/TLS certs for a long, long time - I've even had to re-issue my personal CA cert after it expired after 5 years. However, every time I've issued a self signed cert for an internal site, openssl prompted me interactively for the Country, State, Locality, etc. etc. blah, blah, blah. The lack of automation was exceptionally annoying. I knew the defaults could be customized so that only the Common Name would have to be entered, but that wasn't enough. The openssl req manual page has a non-working example of a config file that shouldn't prompt (Sample configuration containing all field values) but it doesn't work. After spending considerable time trying to craft a custom, template openssl.cnf file today, I finally found a blog post that mentions the -subj argument that completes the certificate request without any prompting. The only prompting now done is for the rsa command if you're encrypting your keyfile. And of course, this can be automated with the -passin arg, if needed. Here is a full example:

# FQDN of SSL/TLS site
CN="fhqwhgads.example.com"

# preflight
C="US"
ST="New York"
L="New York"
O="Example.com Inc."
OU="Systems Team"
emailAddress="devnull@example.com"

# create a private key
openssl genrsa -out ${CN}.key 2048
# create a certificate request
openssl req \
 -new \
 -subj "/C=$C/ST=$ST/L=$L/O=$O/OU=$OU/CN=$CN/emailAddress=$emailAddress" \
 -key ${CN}.key \
 -out ${CN}.csr
# create cert
openssl x509 -req -days 3650 -in ${CN}.csr -signkey ${CN}.key -out ${CN}.crt

#
# optional - encrypt key
#
# move key
mv ${CN}.key ${CN}.key.plain
# encrypt key
# (add '-passin pass:password' or '-passin file:pathname' for no prompting)
# see openssl(1) manpage
openssl rsa -des3 -in ${CN}.key.plain -out ${CN}.key.crypt
# rename key
mv ${CN}.key.crypt ${CN}.key
# clean up
rm ${CN}.key.plain

Disabling TRACE and TRACK methods

After reading a blog post about how to disable TRACE and TRACK for compliance, I've taken an extra step - limit HTTP requests to only "the big three":

        RewriteEngine On
        RewriteCond %{REQUEST_METHOD} !^(GET|HEAD|POST)
        RewriteRule .* - [F]

It's possible you might want to add "OPTIONS" to that list or "DELETE|PUT" to be RESTful, but as with most implementations, YMMV.

Restricting directory in Apache per logged in user

There's some great apache voodoo going on in this blog post. I'm going to basically be doing the same thing for a site I'm working on - which means no more editing custom basic auth blocks within the apache config - just create the user in LDAP and let the front-end developer create the matching directory with FTP.

My code snippet looks like this:

RewriteEngine On
# are they asking for a URL with thier username
RewriteCond %{REMOTE_USER} ^(.*)
RewriteCond %1:$1 !^([^:]+):\1$
# if not, send them there
RewriteRule /ldap-test/([^/]+) /ldap-test/%{REMOTE_USER}/ [R,L]

# is the directory there
RewriteCond /var/www/html/ldap-test/%{REMOTE_USER} !-d
# if not, send them off
RewriteRule /.* http://sorry.example.com/ [R,L]

Apache LDAP Configuration

Examples on how to authenticate a url served by Apache 2.2.x the OpenLDAP way and the Active Directory way

LoadModule authz_ldap_module modules/mod_authz_ldap.so

<IfModule mod_authz_ldap.c>

LDAPSharedCacheSize 500000

LDAPCacheEntries 1024

LDAPCacheTTL 600

LDAPOpCacheEntries 1024

LDAPOpCacheTTL 600

LDAPTrustedMode SSL

LDAPVerifyServerCert Off

<Location /ldap-status>

SetHandler ldap-status

</Location>

<Location /openldap-protected>

Order deny,allow

Allow from all

AuthType Basic

AuthName "authentication required"

AuthBasicProvider ldap

AuthzLDAPAuthoritative on

#

# OpenLDAP way

#

AuthLDAPURL "ldaps://openldapserver.example.com/ou=people,dc=example,dc=com?uid?sub?(objectClass=*)"

AuthLDAPBindDN "cn=Manager,dc=example,dc=com"

AuthLDAPBindPassword "s3cr3tp@55w0rd"

Require valid-user

</Location>

<Location /activedirectory-protected>

Order deny,allow

Allow from all

AuthType Basic

AuthName "authentication required"

AuthBasicProvider ldap

AuthzLDAPAuthoritative on

#

# Active Diretory way

#

AuthLDAPURL "ldaps://activedirectoryserver.example.com:3269/DC=example,DC=com?sAMAccountName?sub?(objectClass=*)"

AuthLDAPBindDN "ldap@example.com"

AuthLDAPBindPassword "s3cr3tp@55w0rd"

Require valid-user

</Location>

</IfModule>