code.grnet.gr Git - pithos/blob - docs/source/adminguide.rst

   1 Administrator Guide
   2 ===================
   3
   4 Simple Setup
   5 ------------
   6
   7 Assuming a clean debian squeeze (stable) installation, use the following steps to run the software.
   8
   9 Install packages::
  10
  11   apt-get install git python-django python-setuptools python-sphinx
  12   apt-get install apache2 libapache2-mod-wsgi
  13
  14 Get the source::
  15
  16   cd /
  17   git clone https://code.grnet.gr/git/pithos
  18
  19 Setup the files (choose where to store data in ``settings.py``)::
  20
  21   cd /pithos/pithos
  22   cp settings.py.dist settings.py
  23   cd /pithos
  24   python setup.py build_sphinx
  25
  26 Edit ``/etc/apache2/sites-available/pithos`` (change the ``ServerName`` directive)::
  27
  28   <VirtualHost *:80>
  29         ServerAdmin webmaster@pithos.dev.grnet.gr
  30         ServerName pithos.dev.grnet.gr
  31
  32         DocumentRoot /var/www/pithos_web_client
  33         <Directory />
  34                 Options FollowSymLinks
  35                 AllowOverride None
  36         </Directory>
  37         <Directory /var/www/>
  38                 Options Indexes FollowSymLinks MultiViews
  39                 AllowOverride None
  40                 Order allow,deny
  41                 allow from all
  42         </Directory>
  43
  44         Alias /docs "/pithos/docs/build/html"
  45         <Directory /pithos/docs/build/html/>
  46                 Order allow,deny
  47                 Allow from all
  48         </Directory>
  49
  50         RewriteEngine On
  51         RewriteRule ^/v(.*) /api/v$1 [PT]
  52         RewriteRule ^/public(.*) /api/public$1 [PT]
  53
  54         <Directory /pithos/pithos/wsgi/>
  55                 Order allow,deny
  56                 Allow from all
  57         </Directory>
  58         WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
  59
  60         # WSGIDaemonProcess pithos
  61         # WSGIProcessGroup pithos
  62
  63         ErrorLog ${APACHE_LOG_DIR}/pithos.error.log
  64
  65         # Possible values include: debug, info, notice, warn, error, crit,
  66         # alert, emerg.
  67         LogLevel warn
  68
  69         CustomLog ${APACHE_LOG_DIR}/pithos.access.log combined
  70
  71   </VirtualHost>
  72
  73 Edit ``/etc/apache2/sites-available/pithos-ssl`` (assuming files in ``/etc/ssl/private/pithos.dev.key`` and ``/etc/ssl/certs/pithos.dev.crt`` - change the ``ServerName`` directive)::
  74
  75   <IfModule mod_ssl.c>
  76   <VirtualHost _default_:443>
  77         ServerAdmin webmaster@pithos.dev.grnet.gr
  78         ServerName pithos.dev.grnet.gr
  79
  80         DocumentRoot /var/www/pithos_web_client
  81         <Directory />
  82                 Options FollowSymLinks
  83                 AllowOverride None
  84         </Directory>
  85         <Directory /var/www/>
  86                 Options Indexes FollowSymLinks MultiViews
  87                 AllowOverride None
  88                 Order allow,deny
  89                 allow from all
  90         </Directory>
  91
  92         Alias /docs "/pithos/docs/build/html"
  93         <Directory /pithos/docs/build/html/>
  94                 Order allow,deny
  95                 Allow from all
  96         </Directory>
  97
  98         RewriteEngine On
  99         RewriteRule ^/v(.*) /api/v$1 [PT]
 100         RewriteRule ^/public(.*) /api/public$1 [PT]
 101
 102         <Directory /pithos/pithos/wsgi/>
 103                 Order allow,deny
 104                 Allow from all
 105         </Directory>
 106         WSGIScriptAlias /api /pithos/pithos/wsgi/pithos.wsgi
 107
 108         ErrorLog ${APACHE_LOG_DIR}/pithos-ssl.error.log
 109
 110         # Possible values include: debug, info, notice, warn, error, crit,
 111         # alert, emerg.
 112         LogLevel warn
 113
 114         CustomLog ${APACHE_LOG_DIR}/pithos-ssl.access.log combined
 115
 116         #   SSL Engine Switch:
 117         #   Enable/Disable SSL for this virtual host.
 118         SSLEngine on
 119
 120         #   A self-signed (snakeoil) certificate can be created by installing
 121         #   the ssl-cert package. See
 122         #   /usr/share/doc/apache2.2-common/README.Debian.gz for more info.
 123         #   If both key and certificate are stored in the same file, only the
 124         #   SSLCertificateFile directive is needed.
 125         SSLCertificateFile    /etc/ssl/certs/pithos.dev.crt
 126         SSLCertificateKeyFile /etc/ssl/private/pithos.dev.key
 127
 128         #   Server Certificate Chain:
 129         #   Point SSLCertificateChainFile at a file containing the
 130         #   concatenation of PEM encoded CA certificates which form the
 131         #   certificate chain for the server certificate. Alternatively
 132         #   the referenced file can be the same as SSLCertificateFile
 133         #   when the CA certificates are directly appended to the server
 134         #   certificate for convinience.
 135         #SSLCertificateChainFile /etc/apache2/ssl.crt/server-ca.crt
 136
 137         #   Certificate Authority (CA):
 138         #   Set the CA certificate verification path where to find CA
 139         #   certificates for client authentication or alternatively one
 140         #   huge file containing all of them (file must be PEM encoded)
 141         #   Note: Inside SSLCACertificatePath you need hash symlinks
 142         #         to point to the certificate files. Use the provided
 143         #         Makefile to update the hash symlinks after changes.
 144         #SSLCACertificatePath /etc/ssl/certs/
 145         #SSLCACertificateFile /etc/apache2/ssl.crt/ca-bundle.crt
 146
 147         #   Certificate Revocation Lists (CRL):
 148         #   Set the CA revocation path where to find CA CRLs for client
 149         #   authentication or alternatively one huge file containing all
 150         #   of them (file must be PEM encoded)
 151         #   Note: Inside SSLCARevocationPath you need hash symlinks
 152         #         to point to the certificate files. Use the provided
 153         #         Makefile to update the hash symlinks after changes.
 154         #SSLCARevocationPath /etc/apache2/ssl.crl/
 155         #SSLCARevocationFile /etc/apache2/ssl.crl/ca-bundle.crl
 156
 157         #   Client Authentication (Type):
 158         #   Client certificate verification type and depth.  Types are
 159         #   none, optional, require and optional_no_ca.  Depth is a
 160         #   number which specifies how deeply to verify the certificate
 161         #   issuer chain before deciding the certificate is not valid.
 162         #SSLVerifyClient require
 163         #SSLVerifyDepth  10
 164
 165         #   Access Control:
 166         #   With SSLRequire you can do per-directory access control based
 167         #   on arbitrary complex boolean expressions containing server
 168         #   variable checks and other lookup directives.  The syntax is a
 169         #   mixture between C and Perl.  See the mod_ssl documentation
 170         #   for more details.
 171         #<Location />
 172         #SSLRequire (    %{SSL_CIPHER} !~ m/^(EXP|NULL)/ \
 173         #            and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
 174         #            and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
 175         #            and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
 176         #            and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20       ) \
 177         #           or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/
 178         #</Location>
 179
 180         #   SSL Engine Options:
 181         #   Set various options for the SSL engine.
 182         #   o FakeBasicAuth:
 183         #     Translate the client X.509 into a Basic Authorisation.  This means that
 184         #     the standard Auth/DBMAuth methods can be used for access control.  The
 185         #     user name is the `one line' version of the client's X.509 certificate.
 186         #     Note that no password is obtained from the user. Every entry in the user
 187         #     file needs this password: `xxj31ZMTZzkVA'.
 188         #   o ExportCertData:
 189         #     This exports two additional environment variables: SSL_CLIENT_CERT and
 190         #     SSL_SERVER_CERT. These contain the PEM-encoded certificates of the
 191         #     server (always existing) and the client (only existing when client
 192         #     authentication is used). This can be used to import the certificates
 193         #     into CGI scripts.
 194         #   o StdEnvVars:
 195         #     This exports the standard SSL/TLS related `SSL_*' environment variables.
 196         #     Per default this exportation is switched off for performance reasons,
 197         #     because the extraction step is an expensive operation and is usually
 198         #     useless for serving static content. So one usually enables the
 199         #     exportation for CGI and SSI requests only.
 200         #   o StrictRequire:
 201         #     This denies access when "SSLRequireSSL" or "SSLRequire" applied even
 202         #     under a "Satisfy any" situation, i.e. when it applies access is denied
 203         #     and no other module can change it.
 204         #   o OptRenegotiate:
 205         #     This enables optimized SSL connection renegotiation handling when SSL
 206         #     directives are used in per-directory context.
 207         #SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire
 208         <FilesMatch "\.(cgi|shtml|phtml|php)$">
 209                 SSLOptions +StdEnvVars
 210         </FilesMatch>
 211         <Directory /usr/lib/cgi-bin>
 212                 SSLOptions +StdEnvVars
 213         </Directory>
 214
 215         #   SSL Protocol Adjustments:
 216         #   The safe and default but still SSL/TLS standard compliant shutdown
 217         #   approach is that mod_ssl sends the close notify alert but doesn't wait for
 218         #   the close notify alert from client. When you need a different shutdown
 219         #   approach you can use one of the following variables:
 220         #   o ssl-unclean-shutdown:
 221         #     This forces an unclean shutdown when the connection is closed, i.e. no
 222         #     SSL close notify alert is send or allowed to received.  This violates
 223         #     the SSL/TLS standard but is needed for some brain-dead browsers. Use
 224         #     this when you receive I/O errors because of the standard approach where
 225         #     mod_ssl sends the close notify alert.
 226         #   o ssl-accurate-shutdown:
 227         #     This forces an accurate shutdown when the connection is closed, i.e. a
 228         #     SSL close notify alert is send and mod_ssl waits for the close notify
 229         #     alert of the client. This is 100% SSL/TLS standard compliant, but in
 230         #     practice often causes hanging connections with brain-dead browsers. Use
 231         #     this only for browsers where you know that their SSL implementation
 232         #     works correctly.
 233         #   Notice: Most problems of broken clients are also related to the HTTP
 234         #   keep-alive facility, so you usually additionally want to disable
 235         #   keep-alive for those clients, too. Use variable "nokeepalive" for this.
 236         #   Similarly, one has to force some clients to use HTTP/1.0 to workaround
 237         #   their broken HTTP/1.1 implementation. Use variables "downgrade-1.0" and
 238         #   "force-response-1.0" for this.
 239         BrowserMatch "MSIE [2-6]" \
 240                 nokeepalive ssl-unclean-shutdown \
 241                 downgrade-1.0 force-response-1.0
 242         # MSIE 7 and newer should be able to use keepalive
 243         BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown
 244
 245   </VirtualHost>
 246   </IfModule>
 247
 248 Configure and run apache::
 249
 250   a2enmod ssl
 251   a2enmod rewrite
 252   a2dissite default
 253   a2ensite pithos
 254   a2ensite pithos-ssl
 255   mkdir /var/www/pithos
 256   mkdir /var/www/pithos_web_client
 257   /etc/init.d/apache2 restart
 258
 259 Useful alias to add in ``~/.bashrc``::
 260
 261   alias pithos-sync='cd /pithos && git pull && python setup.py build_sphinx'
 262
 263 MySQL Setup
 264 -----------
 265
 266 If using MySQL instead of SQLite for the database engine, consider the following.
 267
 268 Server side::
 269
 270   apt-get install mysql-server
 271
 272 Edit ``/etc/mysql/my.cnf`` to allow network connections and restart the server.
 273
 274 Create database and user::
 275
 276   CREATE DATABASE pithos;
 277   GRANT ALL ON pithos.* TO pithos@localhost IDENTIFIED BY 'password';
 278   GRANT ALL ON pithos.* TO pithos@'%' IDENTIFIED BY 'password';
 279
 280 Client side::
 281
 282   apt-get install mysql-client
 283
 284 It helps to create a ``~/.my.cnf`` file, for automatically connecting to the server::
 285
 286   [client]
 287   user = pithos
 288   password = 'password'
 289   host = pithos-storage.dev.grnet.gr
 290
 291   [mysql]
 292   database = pithos