diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 256 |
1 files changed, 67 insertions, 189 deletions
@@ -1,233 +1,111 @@ -Puppet module for managing an Apache web server -=============================================== +Leap Platform +============================= -This module tries to manage apache on different distros in a similar manner. a -few additional directories have to be created as well some configuration files -have to be deployed to fit this schema. +[](https://jenkins.leap.se/job/platform_develop/) -! Upgrade Notices ! +The LEAP Platform is set of complementary packages and server recipes to automate the maintenance of LEAP services in a hardened Debian environment. Its goal is to make it as painless as possible for sysadmins to deploy and maintain a service provider's infrastructure for secure communication. These recipes define an abstract service provider. It is a set of Puppet modules designed to work together to provide to sysadmins everything they need to manage a service provider infrastructure that provides secure communication services. - * The $ssl_cipher_suite has been evaluated from the `cert` module in the - past, but is now a hardcoded default for the sake of reducing dependency - to other modules. If you were using the `cert` module before, you should - pass this parameter when declaring the apache class ! +Getting started +============================= - * this module now only works with puppet 2.7 or newer +It is highly recommended that you start by reading the overview of the [LEAP Platform](https://leap.se/docs/platform) and then begin with the [Quick Start tutorial](https://leap.se/en/docs/platform/tutorials/quick-start) to walk through a test environment setup to get familiar with how things work before deploying to live servers. - * this module now uses parameterized classes, if you were using global - variables before, you need to change the class declarations in your manifests +An offline copy of this documentation is contained in the `doc` subdirectory. For more current updates to the documentation, visit the website. - * this module now requires the stdlib module +Requirements +------------------ - * this module no longer requires the common module +For testing a virtual deployment simulated on your computer, you will need a fairly recent computer x86_64 with hardware virtualization features (AMD-V or VT-x) and plenty of RAM. If you follow the "Quick Start" documentation we will walk you through using Vagrant to setup a test deployment. - * if using the munin module, you need a version of the munin module that is - at or newer than commit 77e0a70999a8c4c20ee8d9eb521b927c525ac653 (Feb 28, 2013) +For a live deployment of the platform, the number of servers that is required depends on your needs and which services you want to deploy. At the moment, the LEAP Platform supports servers with a base Debian Wheezy installation. - * if using munin, you will need to have the perl module installed +Troubleshooting +============================= - * you must change your modules/site-apache to modules/site_apache +If you have a problem, we are interested in fixing it! - * the $apache_no_default_site variable is no longer supported, you should - switch to passing the parameter "no_default_site => true" to the apache class +If you have a problem, be sure to have a look at the [Known Issues](https://leap.se/docs/platform/known-issues) to see if your issue is detailed there. - * the $use_munin variable is no longer supported, you should switch to - passing the parameter 'manage_munin' to the apache class +If not, the best way for us to solve your problem is if you provide to us the complete log of what you did, and the output that was produced. Please don't cut out what appears to be useless information and only include the error that you received, instead copy and paste the complete log so that we can better determine the overall situation. If you can run the same command that produced the error with a raised verbosity level (such as -v2), that provides us with more useful debugging information. - * the $use_shorewall variable is no longer supported, you should switch to - passing the parameter 'manage_shorewall' to the apache class +To capture the log, you can copy from the console, or run `leap --log FILE` or edit Leapfile to include `@log = '/tmp/leap.log'`. - * if you were using apache::vhost::file, or apache::vhost::template, there is a - wrapper called apache::vhost now that takes a $vhost_mode (either the default - 'template', or 'file), although you can continue to use the longer defines +Visit https://leap.se/en/docs/get-involved/communication for details on how to contact the developers. - * Previously, apache::config::file resources would require the source to be a - full source specification, this is no longer needed, so please change any: +Known issues +============ - source => "puppet:///modules/site-apache/blah" +The following issues are known to exist in 0.5.2 and later: - to be: +CouchDB Sync +------------ +You can't deploy new couchdb nodes after one or more have been deployed. Make *sure* that you configure and deploy all your couchdb nodes when first creating your provider. The problem is that we dont not have a clean way of adding couch nodes after initial creation of the databases, so any nodes added after result in improperly synchronized data. See Bug [#5601](https://leap.se/code/issues/5601) for more information. - source => "modules/site-apache/blah" +User setup and ssh +------------------ +. if you aren't using a single ssh key, but have different ones, you will need to define the following at the top of your ~/.ssh/config: + HostName <ip address> + IdentityFile <path to identity file> -Requirements ------------- + (see: https://leap.se/code/issues/2946 and https://leap.se/code/issues/3002) - * puppet 2.7 or newer - * stdlib module - * templatewlv module - * facter >= 2.2 - because we check for $::operatingsystemmajrelease on multiple places. - In Debian wheezy, facter needs to get upgraded from wheezy-backports. - The facter version of Debian jessie is new enough. +. If the ssh host key changes, you need to run node init again (see: https://leap.se/en/docs/platform/guide#Working.with.SSH) -Usage -===== +. At the moment, only ECDSA ssh host keys are supported. If you get the following error: `= FAILED ssh-keyscan: no hostkey alg (must be missing an ecdsa public host key)` then you should confirm that you have the following line defined in your server's **/etc/ssh/sshd_config**: `HostKey /etc/ssh/ssh_host_ecdsa_key`. If that file doesn't exist, run `ssh-keygen -t ecdsa -f /etc/ssh/ssh_host_ecdsa_key -N ""` in order to create it. If you made a change to your sshd_config, then you need to run `/etc/init.d/ssh restart` (see: https://leap.se/code/issues/2373) -Installing Apache ------------------ +. To remove an admin's access to your servers, please remove the directory for that user under the `users/` subdirectory in your provider directory and then remove that user's ssh keys from files/ssh/authorized_keys. When finished you *must* run a `leap deploy` to update that information on the servers. -To install Apache, simply include the 'apache' class in your manifests: +. At the moment, it is only possible to add an admin who will have access to all LEAP servers (see: https://leap.se/code/issues/2280) - include apache +. leap add-user --self allows only one key - if you run that command twice with different keys, you will just replace the key with the second key. To add a second key, add it manually to files/ssh/authorized_keys (see: https://leap.se/code/issues/866) -This will give you a basic managed setup. You can pass a couple parameters to the -class to have the module do some things for you: - * manage_shorewall: If you have the shorewall module installed and are using - it then rules will be automatically defined for you to let traffic come from - the exterior into the web server via port 80, and also 443 if you're using - the apache::ssl class. (Default: false) +Deploying +--------- - * manage_munin: If you have the munin module installed and are using it, then - some apache graphs will be configured for you. (Default: false) +. If you have any errors during a run, please try to deploy again as this often solves non-deterministic issues that were not uncovered in our testing. Please re-deploy with `leap -v2 deploy` to get more verbose logs and capture the complete output to provide to us for debugging. - * no_default_site: If you do not want the 0-default.conf and - 0-default_ssl.conf virtualhosts automatically created in your node - configuration. (Default: false) +. If when deploying your debian mirror fails for some reason, network anomoly or the mirror itself is out of date, then platform deployment will not succeed properly. Check the mirror is up and try to deploy again when it is resolved (see: https://leap.se/code/issues/1091) - * ssl: If you want to install Apache SSL support enabled, just pass this - parameter (Default: false) +. Deployment gives 'error: in `%`: too few arguments (ArgumentError)' - this is because you attempted to do a deploy before initializing a node, please initialize the node first and then do a deploy afterwards (see: https://leap.se/code/issues/2550) -For example: +. This release has no ability to custom configure apt sources or proxies (see: https://leap.se/code/issues/1971) - class { 'apache': - manage_shorewall => true, - manage_munin => true, - no_default_site => true, - ssl => true - } +. When running a deploy at a verbosity level of 2 and above, you will notice puppet deprecation warnings, these are known and we are working on fixing them -You can install the ITK worker model to enforce stronger, per-user security: +Special Environments +-------------------- - include apache::itk +. When deploying to OpenStack release "nova" or newer, you will need to do an initial deploy, then when it has finished run `leap facts update` and then deploy again (see: https://leap.se/code/issues/3020) -On CentOS you can include 'apache::itk_plus' to get that mode. Not currently -implemented for other operating systems +leap-mx +------- -You can combine SSL support and the ITK worker model by including both classes. +. see https://github.com/leapcode/leap_mx#070 for issues regarding leap_mx -Configuring Apache ------------------- +Contributing +============ + +In order to validate the syntax and style guide compliance +before you commit, see https://github.com/pixelated-project/puppet-git-hooks#installation + + +Changes +========= + +Read CHANGES.md or run `git log`. -To deploy a configuration files to the conf.d or include.d directory under -Apache's config directory, you can use the following: +Authors and Credits +=================== - apache::config::file { 'filename': - content => 'Alias /thisApplication /usr/share/thisApplication/htdocs', - } +See contributors: -by default this will deploy a conf.d global configuration file called 'filename' -with that content. + git shortlog -es --all -You can pass the parameter 'type => include' to add includes for vhosts +Copyright/License +================= -To manage users in an htpasswd file: - - apache::htpasswd_user { "joe@$domain": - ensure => present, # default: present - site => "$domain", # default: 'absent' - will use $name - username => 'joe', # default: 'absent' - will use $name - password => "pass", - password_iscrypted => false, # default: false - will sha1 hash the value - path => 'absent' # default: 'absent' - /var/www/htpasswds/${site} - } - -This will place an encrypted version of "pass" for user joe into -/var/www/htpasswds/${site} - -You will need to make sure that ${site} exists before this is done, see the -apache::vhost class below for how this is done. - -VirtualHost files ------------------ - -vhosts can be added with the apache::vhost define. - -You can ship a flat file containing the configuration, or a template. That is -controlled by the 'vhost_mode' parameter, which can be either 'file', or -'template' (default). - -Unless specified, the source will be automatically pulled from -modules/site_apache/{templates,files}/vhosts.d, searched in this order: - - "puppet:///modules/site_apache/vhosts.d/${::fqdn}/${name}.conf", - "puppet:///modules/site_apache/vhosts.d/{$apache::cluster_node}/${name}.conf", - "puppet:///modules/site_apache/vhosts.d/${::operatingsystem}.${::operatingsystemmajrelease}/${name}.conf", - "puppet:///modules/site_apache/vhosts.d/${::operatingsystem}/${name}.conf", - "puppet:///modules/site_apache/vhosts.d/${name}.conf", - -otherwise you can pass a 'content' parameter to configure a template location that -it should be pulled from, or a 'vhost_source' parameter to specify the file source. - -For example: - -This would deploy a the vhost for $domain, pulled from a file from the sources -listed above: - - apache::vhost { "$domain": vhost_mode => 'file' } - - apache::vhost { "$domain": - vhost_mode => 'file', - vhost_source => 'modules/site_configs/vhosts.d/${name}.conf" - } - -There are multiple other additional configurables that you can pass to each -vhost definition: - -* logmode: - - default: Do normal logging to CustomLog and ErrorLog - - nologs: Send every logging to /dev/null - - anonym: Don't log ips for CustomLog, send ErrorLog to /dev/null - - semianonym: Don't log ips for CustomLog, log normal ErrorLog - -* run_mode: controls in which mode the vhost should be run, there are different setups - possible: - - normal: (*default*) run vhost with the current active worker (default: prefork) don't - setup anything special - - itk: run vhost with the mpm_itk module (Incompatibility: cannot be used in combination - with 'proxy-itk' & 'static-itk' mode) - - proxy-itk: run vhost with a dual prefork/itk setup, where prefork just proxies all the - requests for the itk setup, that listens only on the loobpack device. - (Incompatibility: cannot be used in combination with the itk setup.) - - static-itk: run vhost with a dual prefork/itk setup, where prefork serves all the static - content and proxies the dynamic calls to the itk setup, that listens only on - the loobpack device (Incompatibility: cannot be used in combination with - 'itk' mode) - -* mod_security: Whether we use mod_security or not (will include mod_security module) - - false: (*default*) don't activate mod_security - - true: activate mod_security - -For templates, you can pass various parameters that will automatically configure -the template accordingly (such as php_options and php_settings). Please see -manifests/vhost/template.pp for the full list. - -There are various pre-made vhost configurations that use good defaults that you can use: - -- apache::vhost::gitweb - sets up a gitweb vhost -- apache::vhost::modperl - uses modperl, with optional fastcgi -- apache::vhost::passenger - setup passenger -- apache::vhost::proxy - setup a proxy vhost -- apache::vhost::redirect - vhost to redirect hosts -- apache::vhost::static - a static vhost -- apache::vhost::webdav - for managing webdave accessible targets - -Additionally, for php sites, there are several handy pre-made vhost configurations: - -- apache::vhost::php::drupal -- apache::vhost::php::gallery2 -- apache::vhost::php::global_exec_bin_dir -- apache::vhost::php::joomla -- apache::vhost::php::mediawiki -- apache::vhost::php::safe_mode_bin -- apache::vhost::php::silverstripe -- apache::vhost::php::simplemachine -- apache::vhost::php::spip -- apache::vhost::php::standard -- apache::vhost::php::typo3 -- apache::vhost::php::webapp -- apache::vhost::php::wordpress +Read LICENSE |