diff --git a/doc/markdown/apache-deploy.md b/doc/markdown/apache-deploy.md new file mode 100644 index 0000000..3da2192 --- /dev/null +++ b/doc/markdown/apache-deploy.md @@ -0,0 +1,180 @@ +## Deploying Apache as front end for Openstack Swift in Fedora/RHEL + +NOTE: This guide is for manual deployment. A shell script to automate the following +is present in extras/apache-deploy. + +### Architecture +Swift can be configured to work both using an integral web front-end and +using a full-fledged Web Server such as the Apache2 (HTTPD) web server. The +integral web front-end is a wsgi mini "Web Server" which opens up its own +socket and serves http requests directly. The incoming requests accepted +by the integral web front-end are then forwarded to a wsgi application +(the core swift) for further handling, possibly via wsgi middleware +sub-components. + + client<-->'integral web front-end'<-->middleware<-->'core swift' + +To gain full advantage of Apache2, Swift can alternatively be configured to +work as a request processor of the Apache2 server. This alternative deployment +scenario uses mod_wsgi of Apache2 to forward requests to the swift wsgi +application and middleware. + + client<-->'Apache2 with mod_wsgi'<-->middleware<-->'core swift' + +The integral web front-end offers simplicity and requires minimal config. +It is also the web front-end most commonly used with Swift. Additionally, the +integral web front-end includes support for receiving chunked transfer +encoding from a client, presently not supported by Apache2 in the operation +mode described here. + +### Steps + +Installing Apache with mod_wsgi module: + + yum install httpd mod_wsgi + +Create a directory for Apache wsgi files: + + mkdir /var/www/swift + +Create a wsgi file for each service under /var/www/swift + +#### /var/www/swift/proxy-server.wsgi + from swift.common.wsgi import init_request_processor + application, conf, logger, log_name = \ + init_request_processor('/etc/swift/proxy-server.conf','proxy-server') + +#### /var/www/swift/account-server.wsgi + from swift.common.wsgi import init_request_processor + application, conf, logger, log_name = \ + init_request_processor('/etc/swift/account-server.conf','account-server') + +#### /var/www/swift/container-server.wsgi + from swift.common.wsgi import init_request_processor + application, conf, logger, log_name = \ + init_request_processor('/etc/swift/container-server.conf','container-server') + +#### /var/www/swift/object-server.wsgi + from swift.common.wsgi import init_request_processor + application, conf, logger, log_name = \ + init_request_processor('/etc/swift/object-server.conf','object-server') + + +Create */etc/httpd/conf.d/swift_wsgi.conf* configuration file that will define +port and Virtual Host per each local service. + + WSGISocketPrefix /var/run/wsgi + + #Proxy Service + Listen 8080 + + ServerName proxy-server + LimitRequestBody 5368709122 + WSGIDaemonProcess proxy-server processes=5 threads=1 user=swift + WSGIProcessGroup proxy-server + WSGIScriptAlias / /var/www/swift/proxy-server.wsgi + LimitRequestFields 200 + ErrorLog /var/log/httpd/proxy-server.log + LogLevel debug + CustomLog /var/log/httpd/proxy.log combined + + + #Object Service + Listen 6010 + + ServerName object-server + WSGIDaemonProcess object-server processes=5 threads=1 user=swift + WSGIProcessGroup object-server + WSGIScriptAlias / /var/www/swift/object-server.wsgi + LimitRequestFields 200 + ErrorLog /var/log/httpd/object-server.log + LogLevel debug + CustomLog /var/log/httpd/access.log combined + + + #Container Service + Listen 6011 + + ServerName container-server + WSGIDaemonProcess container-server processes=5 threads=1 user=swift + WSGIProcessGroup container-server + WSGIScriptAlias / /var/www/swift/container-server.wsgi + LimitRequestFields 200 + ErrorLog /var/log/httpd/container-server.log + LogLevel debug + CustomLog /var/log/httpd/access.log combined + + + #Account Service + Listen 6012 + + ServerName account-server + WSGIDaemonProcess account-server processes=5 threads=1 user=swift + WSGIProcessGroup account-server + WSGIScriptAlias / /var/www/swift/account-server.wsgi + LimitRequestFields 200 + ErrorLog /var/log/httpd/account-server.log + LogLevel debug + CustomLog /var/log/httpd/access.log combined + + +(Re)Start Apache server: + + service httpd stop + service httpd start + +### Troubleshooting + +* Make sure you have set SElinux to Permissive or Disabled by editing + */etc/sysconfig/selinux*. You will need to reboot your system for the + changed value to take effect. On restart, you can confirm this by running: + + getenforce + +* Make sure conf files in /etc/swift are accessible by swift user: + + chown swift:swift /etc/swift/* + +* Make sure the directory */var/lib/swift* exists should you see the following + error in /var/log/httpd/error_log + + [Fri Oct 20 02:05:25.617290 2013] [:alert] [pid 3491] (2)No such file or + directory: mod_wsgi (pid=3491): Unable to change working directory to + '/var/lib/swift' + +* Make sure the port numbers in */etc/httpd/conf.d/swift_wsgi.conf* and + */etc/swift/*conf* files are same. + +* For errors in logs like the following: + + 13)Permission denied: mod_wsgi (pid=26962): Unable to connect to WSGI + daemon process '' on '/etc/httpd/logs/wsgi.26957.0.1.sock' + after multiple attempts. + + Refer: https://code.google.com/p/modwsgi/wiki/ConfigurationIssues#Location_Of_UNIX_Sockets + +* If your swift deployment uses some authentication mechanism that uses + HTTP_AUTHORIZATION variable, you need to turn on WSGIPassAuthorization as + described here: + + https://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization + +#### Issue with gluster-swift +Unlike vanilla swift that runs as *swift* user, gluster-swift runs all four +swift servers as *root* user. + +But mod_wsgi does not allow invoking wsgi applications as root: +https://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIDaemonProcess + +A workaround is to mount gluster volume as root beforehand: + + mount -t glusterfs localhost:myvolume /mnt/gluster-object/myvolume + + +### More information + +* There is a Ubuntu specific guide to deploy Apache with Openstack Swift here: + http://docs.openstack.org/developer/swift/apache_deployment_guide.html + +* Example apache configuration from swift source can be found here: + https://github.com/openstack/swift/tree/master/examples diff --git a/extras/apache-deploy/conf/account-server.wsgi b/extras/apache-deploy/conf/account-server.wsgi new file mode 100644 index 0000000..10a22b9 --- /dev/null +++ b/extras/apache-deploy/conf/account-server.wsgi @@ -0,0 +1,3 @@ +from swift.common.wsgi import init_request_processor +application, conf, logger, log_name = \ + init_request_processor('/etc/swift/account-server.conf','account-server') diff --git a/extras/apache-deploy/conf/container-server.wsgi b/extras/apache-deploy/conf/container-server.wsgi new file mode 100644 index 0000000..9f3a1b5 --- /dev/null +++ b/extras/apache-deploy/conf/container-server.wsgi @@ -0,0 +1,3 @@ +from swift.common.wsgi import init_request_processor +application, conf, logger, log_name = \ + init_request_processor('/etc/swift/container-server.conf','container-server') diff --git a/extras/apache-deploy/conf/object-server.wsgi b/extras/apache-deploy/conf/object-server.wsgi new file mode 100644 index 0000000..7ea74a5 --- /dev/null +++ b/extras/apache-deploy/conf/object-server.wsgi @@ -0,0 +1,3 @@ +from swift.common.wsgi import init_request_processor +application, conf, logger, log_name = \ + init_request_processor('/etc/swift/object-server.conf','object-server') diff --git a/extras/apache-deploy/conf/proxy-server.wsgi b/extras/apache-deploy/conf/proxy-server.wsgi new file mode 100644 index 0000000..598aaaa --- /dev/null +++ b/extras/apache-deploy/conf/proxy-server.wsgi @@ -0,0 +1,3 @@ +from swift.common.wsgi import init_request_processor +application, conf, logger, log_name = \ + init_request_processor('/etc/swift/proxy-server.conf','proxy-server') diff --git a/extras/apache-deploy/conf/swift_wsgi.conf b/extras/apache-deploy/conf/swift_wsgi.conf new file mode 100644 index 0000000..16e8169 --- /dev/null +++ b/extras/apache-deploy/conf/swift_wsgi.conf @@ -0,0 +1,54 @@ +WSGISocketPrefix /var/run/wsgi + +#Proxy Service +Listen 8080 + + ServerName proxy-server + LimitRequestBody 5368709122 + WSGIDaemonProcess proxy-server processes=5 threads=1 user=swift + WSGIProcessGroup proxy-server + WSGIScriptAlias / /var/www/swift/proxy-server.wsgi + LimitRequestFields 200 + ErrorLog /var/log/httpd/proxy-server.log + LogLevel debug + CustomLog /var/log/httpd/proxy.log combined + + +#Object Service +Listen 6010 + + ServerName object-server + WSGIDaemonProcess object-server processes=5 threads=1 user=swift + WSGIProcessGroup object-server + WSGIScriptAlias / /var/www/swift/object-server.wsgi + LimitRequestFields 200 + ErrorLog /var/log/httpd/object-server.log + LogLevel debug + CustomLog /var/log/httpd/access.log combined + + +#Container Service +Listen 6011 + + ServerName container-server + WSGIDaemonProcess container-server processes=5 threads=1 user=swift + WSGIProcessGroup container-server + WSGIScriptAlias / /var/www/swift/container-server.wsgi + LimitRequestFields 200 + ErrorLog /var/log/httpd/container-server.log + LogLevel debug + CustomLog /var/log/httpd/access.log combined + + +#Account Service +Listen 6012 + + ServerName account-server + WSGIDaemonProcess account-server processes=5 threads=1 user=swift + WSGIProcessGroup account-server + WSGIScriptAlias / /var/www/swift/account-server.wsgi + LimitRequestFields 200 + ErrorLog /var/log/httpd/account-server.log + LogLevel debug + CustomLog /var/log/httpd/access.log combined + diff --git a/extras/apache-deploy/install.sh b/extras/apache-deploy/install.sh new file mode 100755 index 0000000..aa24250 --- /dev/null +++ b/extras/apache-deploy/install.sh @@ -0,0 +1,44 @@ +#!/bin/sh -x + +# For Fedora/RHEL ONLY + +if [ $EUID -ne 0 ]; then + echo "This script must be run as root" + exit 1 +fi + +# Stop Apache and Swift services if running +swift-init main stop +service httpd stop + +# Install Apache and mod_wsgi +yum install httpd mod_wsgi + +# Create a directory for Apache wsgi files +mkdir -p /var/www/swift + +# Create a directory for swift which it'll use as home +mkdir -p /var/lib/swift + +# Copy wsgi files for each of the four swift services +cp ./conf/*wsgi /var/www/swift/ + +# Copy swift httpd config file +cp ./conf/swift_wsgi.conf /etc/httpd/conf.d/ + +# Change owner of conf files to swift +chown swift:swift /etc/swift/* + +# Check if SElinux is set to permissive/disabled +selinux_mode=$(getenforce) +if [ $selinux_mode == "Enforcing" ]; then + echo "SElinux is set to Enforcing. Change it to Permissive or Disabled \ +by editing /etc/sysconfig/selinux" + echo "You will need to reboot your system for the changed value to take \ +effect." + exit 1 +fi + +echo "Successfully configured Apache as frontend for Swift." +echo "Make sure GlusterFS volume is mounted at /mnt/gluster-object/ \ +before starting httpd" diff --git a/extras/apache-deploy/uninstall.sh b/extras/apache-deploy/uninstall.sh new file mode 100755 index 0000000..e5841bc --- /dev/null +++ b/extras/apache-deploy/uninstall.sh @@ -0,0 +1,19 @@ +#!/bin/sh -x + +# For Fedora/RHEL ONLY + +if [ $EUID -ne 0 ]; then + echo "This script must be run as root" + exit 1 +fi + +# Stop Apache service +service httpd stop + +# Remove swift wsgi files +rm -rf /var/www/swift + +# Remove swift httpd config file +rm -f /etc/httpd/conf.d/swift_wsgi.conf + +echo -e "DONE.\nYou can now restart Swift."