comments and doc errors installing Puppet Dashboard on CentOS 6.2

[Jo Rhett]

Documentation bugs:

1. Wrong location for example passenger configuration file at http://docs.puppetlabs.com/dashboard/manual/1.2/bootstrapping.html

Once Passenger is enabled, copy Dashboard’s example vhost from ext/dashboard-vhost.conf

The file is actually in ext/passenger/dashboard-vhost.conf

2. Rake commands are run as root

Absolutely none of the rake commands need to be run as root, however the documentation shows most of them being run as root (hash prompt). In some cases, running the commands as root will cause file permissions to be wrong. And in general, never do anything as root you don't have to.

Packaging issues (on EL6):

A. The documented rake command to generate certs fails because /usr/share/puppet-dashboard/certs doesn't exist, and /usr/share/puppet-dashboard is owned by root.  I would either include the certs directory with the proper ownership, or have puppet-dashboard own the base directory.  Or at least update the documentation to mention you need to create these by hand.

B. Installation creates a default database.yml file for you, but not a default settings.yml (consistency?)

C. The shell is set to /sbin/nologin, but it's favorable to simply become the dashboard user and run the rake commands as that user.  I would make this clearer in the docs or provide a default shell.

D. dashboard-vhost.conf - the default SSL has no auth, and sets "AllowOverride None", which differs from the settings in the non-SSL version.

E. dashboard-vhost.conf -- The security issues for allowing direct access to report and upload are not documented.  The comments in the file indicate that /reports/upload comes from the master (ie 127.0.0.1 would work if they are the same host) but this URL is actually called from each client directly, so that option won't work at all. The example should have a network IP and mask, and the comment shouldn't say "master"

Documentation improvements:

I would suspect a decent number of people will want to run their dashboard on the same server as the puppet master.  If so, rather than running the rake tasks to generate certs, it's simpler to copy the certs from $ssldir, or point directly at those files from here. I would document this idea.

Second, I believe that the proper apache configuration/security settings are a bit more obtuse than most users are prepared for. I would suggest that you ship a working apache configuration with tight security that only requires that they replace the local network mask, nodename, etc.  I know apache configuration quite well, and it was a bit of a struggle to get it working for HTTP submissions of reports, but HTTPS authentication of users accessing the console.

-- 

Jo Rhett

Net Consonance : net philanthropy to improve open source and internet projects.

[Nick Fagerlund]

Hey, Jo!

Thanks a bunch for the detailed feedback. I'm in the process of going through this and improving the pages in question, and I hope to have updated versions posted sometime next week. A few of these look like they might be code or packaging issues; I'll be talking to the relevant teams about those.

N
(Puppet Labs docs team)

[Nick Fagerlund]

Hey, Jo,

The release team is going to take a look at the packaging issue you noticed, and will be taking a look at improving the example vhosts, too. I've made most of the docs changes you suggested, too.

On Thursday, June 14, 2012 7:23:44 AM UTC-7, Jo wrote:

I would suspect a decent number of people will want to run their dashboard on the same server as the puppet master.  If so, rather than running the rake tasks to generate certs, it's simpler to copy the certs from $ssldir, or point directly at those files from here. I would document this idea.

I don't think this is actually simpler! The recommended approach to just copy-and-paste four static commands; this would require pasting about as many commands, as well as finding the raw cert files, making sure to tell the private key and cert apart (since they have the same filename), and probably editing the settings.yml file. And we can't recommend that anyone re-use the puppet master's OWN cert for any other service, because that cert gives an app the power to impersonate the master for any purpose.

E. dashboard-vhost.conf -- The security issues for allowing direct access to report and upload are not documented.  The comments in the file indicate that /reports/upload comes from the master (ie 127.0.0.1 would work if they are the same host) but this URL is actually called from each client directly, so that option won't work at all. The example should have a network IP and mask, and the comment shouldn't say "master"

.../reports/upload should indeed be coming from only the master, unless you're running a masterless site with puppet apply, in which case yes, they would be coming from all nodes. But nodes running puppet agent do not know how to submit reports to the dashboard; only the master and puppet apply can do that.
 

[Jo Rhett]

On Jun 18, 2012, at 3:50 PM, Nick Fagerlund wrote:

I would suspect a decent number of people will want to run their dashboard on the same server as the puppet master.  If so, rather than running the rake tasks to generate certs, it's simpler to copy the certs from $ssldir, or point directly at those files from here. I would document this idea.

I don't think this is actually simpler! The recommended approach to just copy-and-paste four static commands; this would require pasting about as many commands, as well as finding the raw cert files, making sure to tell the private key and cert apart (since they have the same filename), and probably editing the settings.yml file.

Simpler to add more DNS entries and all the other infrastructure involved in having a host in your network?  That's not so here.  Typing those four commands saved me at least an hour of work up front, and many more later.

Even in the simplest home network, you'll have to modify DNS for the new host entry, modify apache for the additional vhost, etc.  In no form, no matter how simple your infrastructure is, are there less steps in creating a new host.

Finally, the default name is "dashboard". That is totally unusable -- we have like 12 different dashboards here. Telling people to go to https://puppet/ to see how puppet is running makes sense to people. Telling them to go to https://dashboard/ is guaranteed confusion.  So it requires a rename in most bigger-than-a-few-people sites.  Granted that if you're big enough to run the puppetmaster on a different host then you have all that infrastructure anyway, but I've done some much bigger sites and never hit the point where that worked better.

And we can't recommend that anyone re-use the puppet master's OWN cert for any other service, because that cert gives an app the power to impersonate the master for any purpose.

Be good for you to document this.

E. dashboard-vhost.conf -- The security issues for allowing direct access to report and upload are not documented.  The comments in the file indicate that /reports/upload comes from the master (ie 127.0.0.1 would work if they are the same host) but this URL is actually called from each client directly, so that option won't work at all. The example should have a network IP and mask, and the comment shouldn't say "master"

.../reports/upload should indeed be coming from only the master, unless you're running a masterless site with puppet apply, in which case yes, they would be coming from all nodes. But nodes running puppet agent do not know how to submit reports to the dashboard; only the master and puppet apply can do that.

This is another case where the recommends for the reporturl on your reports page differ for your expectations in the example configuration file.  If you are going to use 127.0.0.1 in the vhost configuration then you need to use 127.0.0.1 in the reporturl.  But these two examples never mention each other, and have different expectations.