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