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