django-private-files 1.0.0 documentation¶
This application provides utilities for controlling access to static files based on
conditions you can specify within your Django application.
It provides a PrivatedFileField model field and appropriate signals for monitoring access to static content.
The basic goal is that you should be able to specify permissions for each PrivateFileField instance in
one method (or callable) and leave the rest to django-private-files.
Additionally you should be able to switch server (eg. from nginx to lighttpd) without hassle and remove
this application from your project without changes to your database.
It supports the following methods for limiting access to files:
- Basic - files are served with Python (not recommended for production if you have another choice)
- Nginx (X-Accel-Redirect) - you can specify protected locations within your nginx configuration file
- xsendfile - Apache (with mod_xsendfile), lighttpd and cherokee (not tested yet)
It’s currently been tested with Django (1.9, 1.10, 1.11 and 2.0), Apache and Nginx. It should work with older versions of django. Cherokee and lighttpd use the same mechanism as Apache mod_xsendfile, so it should work, but it’s not been tested or documented.
Contents:
Installation¶
Install from PyPI with easy_install or pip:
pip install django-private-files
or download the source and do:
python setup.py install
or if you want to hack on the code symlink to it in your site-packages:
python setup.py develop
In your settings.py INSTALLED_APPS add private_files.
In your urls.py add the private_files application urls:
from django.conf.urls.defaults import patterns, include, url
# Uncomment the next two lines to enable the admin:
from django.contrib import admin
admin.autodiscover()
urlpatterns = patterns('',
# Examples:
url(r'^private_files/', include('private_files.urls')),
# Uncomment the admin/doc line below to enable admin documentation:
# url(r'^admin/doc/', include('django.contrib.admindocs.urls')),
# Uncomment the next line to enable the admin:
url(r'^admin/', include(admin.site.urls)),
)
Usage¶
Limiting Access to Static Files¶
To protect a static file that you have reference to in the database you need
to use the PrivateFileField model field. For example:
from django.db import models
from private_files import PrivateFileField
class FileSubmission(models.Model):
description = models.CharField("description", max_length = 200)
uploaded_file = PrivateFileField("file", upload_to = 'uploads')
By default it will check if the user is authenticated and let them download the file as an attachment.
If you want to do more complex checks for the permission to download the file you
need to pass your own callable to the condition parameter:
from django.db import models
from django.contrib.auth.models import User
from private_files import PrivateFileField
def is_owner(request, instance):
return (not request.user.is_anonymous()) and request.user.is_authenticated and
instance.owner.pk == request.user.pk
class FileSubmission(models.Model):
description = models.CharField("description", max_length = 200)
owner = models.ForeignKey(User)
uploaded_file = PrivateFileField("file", upload_to = 'uploads', condition = is_owner)
This would check if the user requesting the file is the same user referenced in the owner field and
serve the file if it’s true, otherwise it will throw PermissionDenied.
condition should return True if the request user should be able to download the file and False otherwise.
Another optional parameter is attachment. It allows you to control wether the content-disposition header is sent or not.
By default it is True, meaning the user will always be prompted to download the file by the browser.
Monitoring Access to Static Files¶
By using django-private-files you can monitor when a file is requested for download.
By hooking to the pre_download signal. This fires when a user is granted access to a file
and right before the server starts streaming the file to the user. The following is a simple
example of using the signal to provide a download counter:
from django.db import models
from django.contrib.auth.models import User
from private_files import PrivateFileField, pre_download
class CountedDownloads(models.Model):
description = models.CharField("description", max_length = 200)
downloadable = PrivateFileField("file", upload_to = 'downloadables')
downloads = models.PositiveIntegerField("downloads total", default = 0)
def handle_pre_download(instance, field_name, request, **kwargs):
instance.downloads += 1
instance.save()
pre_download.connect(handle_pre_download, sender = CountedDownloads)
Server configurations¶
All of the bellow examples assume that:
MEDIA_ROOTis set to/media/psf/Home/Projects/django-private-files/testproject/static/MEDIA_URLis set to/media/- Protected files are stored in two subfolders
uploadsanddownloadables- Other static files stored in
MEDIA_ROOTshould be freely downloadable
Apache¶
If you serve your static content with Apache and have mod_xsendfile you can set PRIVATE_DOWNLOAD_HANDLER to 'private_files.handlers.x_sendfile'. Turn
XSendFile on and deny access to the directory where you store your protected files (the value of upload_to appended to MEDIA_ROOT).
Here’s an exmple of a vhost configuration with mod_xsendfile and mod_wsgi:
<VirtualHost *:80>
ServerName django.test
XSendFile on
alias /adminmedia/ /media/psf/Home/Projects/django-private-files/testproject/static/
alias /media/ /home/vasil/src/django-trunk/django/contrib/admin/media/
WSGIDaemonProcess django-test user=vasil group=users threads=1 processes=5
WSGIProcessGroup django-test
WSGIScriptAlias / /media/psf/Home/Projects/django-private-files/testproject/django.wsgi
<Directory /media/psf/Home/Projects/django-private-files/testproject>
Order deny,allow
Allow from all
</Directory>
<Directory /media/psf/Home/Projects/django-private-files/testproject/static/uploads>
Order deny,allow
Deny from all
</Directory>
<Directory /media/psf/Home/Projects/django-private-files/testproject/static/downloadables>
Order deny,allow
Deny from all
</Directory>
<Directory /home/vasil/src/django-trunk/django/contrib/admin>
Order deny,allow
Allow from all
</Directory>
ErrorLog /var/log/httpd/test.err.log
</VirtualHost>
Nginx¶
When using Nginx PRIVATE_DOWNLOAD_HANDLER needs to be set to 'private_files.handlers.x_accel_redirect'.
Use the internal directive like in this example:
http {
include mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
server {
listen 80;
server_name django.test;
location /uploads/{
internal;
root /media/psf/Home/Projects/django-private-files/testproject/static;
}
location /downloadables/{
internal;
root /media/psf/Home/Projects/django-private-files/testproject/static;
}
location /media/{
alias /media/psf/Home/Projects/django-private-files/testproject/static/;
}
location /media/uploads/ {
deny all;
}
location /media/downloadables/ {
deny all;
}
location / {
fastcgi_pass localhost:3033;
fastcgi_param PATH_INFO $fastcgi_script_name;
include fastcgi.conf;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
}
}