Mumble-Django DocumentationRelease 2.4

Michael "Svedrin" Ziegler

Jul 01, 2017

Contents

1 Documentation index 11.1 Mumble-Django: A Mumble web interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1.1 Murmur configuration, user registration and more . . . . . . . . . . . . . . . . . . . . . . . 11.1.2 Download, Source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.1.3 Demo installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.1.4 Prerequisites, Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.1.5 Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.1.6 Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.1.7 Further documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.1.8 Get involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.1.9 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.2 Mumble-Django: Ein Web-Interface für Mumble . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.2.1 Murmur-Konfiguration, Registrierung und mehr . . . . . . . . . . . . . . . . . . . . . . . . 131.2.2 Download, Quellcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.2.3 Demo-Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.2.4 Voraussetzungen und Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.2.5 Bekannte Probleme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.2.6 Kontakt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.2.7 Weitere Dokumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.2.8 Helfen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.2.9 Lizenz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.3 API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.3.1 Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.3.2 mmobjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.3.3 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.3.4 Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.3.5 MCTL: Mumble Control adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.3.6 djextdirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.3.7 Channel Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2 Indices and tables 27

Python Module Index 29

i

ii

CHAPTER 1

Documentation index

Mumble-Django: A Mumble web interface

See also:

Diese Dokumentation gibt’s auch auf Deutsch: Mumble-Django: Ein Web-Interface für Mumble

See also:

Programmers might want to take a look at the API Documentation

See also:

This documentation is also available as a PDF file.

See also:

There is a video tutorial showing the installation.

Murmur configuration, user registration and more

Mumble is a low-latency, high quality voice chat program for gaming. It features noise suppression, automatic gaincontrol and low latency audio with support for multiple audio standards. Mumble includes an in-game overlay com-patible with most open-source and commercial 3D applications.

The Mumble project focuses its development of Mumble itself and does not provide a web administration system.Mumble-Django is such a system, based on Python and Django and licensed as Free Software under the GPL.

Unlike to other existing web interfaces, Mumble-Django strictly uses the interfaces Mumble provides and fully sup-ports all features Mumble has to offer. As a Django project, extending it or using it in other Django projects is veryeasy, so Mumble-Django is only at the beginning of its potential when you initially install it.

1

Mumble-Django Documentation, Release 2.4

Features

• Exclusively uses DBus/Ice to connect to the server - in no circumstance will Mumble-Django try to accessMurmur’s Database directly.

• Compatible with both Murmur 1.1.8 and 1.2.0 – default is 1.2.0

• can connect to both Murmur 1.1.8 and Murmur 1.2.0 at the same time, if using DBus for 1.1.8 and Ice for 1.2.0

• Legacy support for Murmur 1.1.4 (Debian Lenny)

• Public channel list for each configured server (view the demo)

• every channel is a link that will connect you directly to that channel

• when clicking on a user name, you get a few details about this user

• the links apply the user name to registered users, so you can use them and still will be named correctly

• empty subchannels will be hidden to keep the list clear (much like Mumble itself does)

• Create and delete Mumur instances on as many Murmur installations as you want, they just need to be on theSystem DBus / ICE

• Recognizes Cell phone browsers and serves them with a special, light-weight version of the channel viewer page(view the Demo)

• Fully supports the Channel Viewer Protocol

• Can be used as a data source for Murmur-Manager’s channel viewer (view the Demo)

• Ships with a Munin plugin that graphs the user count for each registered server (view the Demo)

• Edit the following configuration details in the Admin Interface for a Murmur instance:

• Server Registration Name (which is also the name of the root channel)

• Server Address (can be a domain name too, the “host” field will be set to the according IP automatically)

• Server Port

• Website URL (will show up in the global Server List)

• Welcome Message

• Server Password

• Superuser Password

• Max Users

• Bandwith

• SSL Cert and Key

• Murmur instances can be started/stopped directly from the web interface

• User registration

• Registered Django users can register an account on every configured Murmur instance, so they can join with +A

• Murmur Accounts can be managed in the Admin Interface

• for security, Users’ passwords are not saved in the models (the field only exists for Model compatibility, save()empties it)

• grant/revoke users’ membership in the admin group on the root channel

• “manage.py syncdb” recognizes existing Murmur instances and players and puts them into the DB

2 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

• Admin Interface for server admins to configure basic settings

• User manager for server admins: add/delete registrations, grant/revoke admin, change password (screenshot)

• handling user textures

• an Ice connector to allow simple switching between DBus and Ice

• Main template is a single file: if you don’t like the look-and-feel, just change index.htm

• Full Django API compatibility: To extend mumble-django, you only need to work with the models, they willhandle everything in their save() methods

• Complete support of all options (like configuring channel/player name regexes)

• Generates valid XHTML transitional (apart from HTML in the channel/user descriptions :) )

• Extensibility: Being a standard Django project and using standard Django Models, you can extend Mumble-Django easily and build a complete website around it.

Installation of Mumble-Django

Prerequisites

In order to install Mumble-Django, you will need the following software. The Installation section will describe thesetup in greater detail.

• Murmur :)

• A web server that supports WSGI or FastCGI. The recommended option is Apache2 with mod_wsgi, how toconfigure this is described under Web Server setup. (Note that the web server is the very last thing to configure,it is just listed here because you will need one.)

• Python (at least 2.5)

• Django (at least 1.2.3)

• django-registration

• Python modules:

• PIL: Python Imaging Library (for user textures)

• simplejson (for the user manager)

• qrencode (only if you want QR Codes to be shown for your servers)

• If using DBus (for Murmur older than 1.1.8):

• DBus and python-dbus

• Currently, all your Murmur servers must be on the System Dbus in order to be reachable by thisapplication (in my setup, Murmur doesn’t run under the same user as the web server, so I can’t usea session dbus).

• Murmur and mumble-django need to run on the same machine as DBus does not support inter-machine connectivity.

• If using Ice (recommended):

• python-zeroc-ice

1.1. Mumble-Django: A Mumble web interface 3

Mumble-Django Documentation, Release 2.4

• If you are using Ubuntu Hardy (8.04), you will likely experience issues with Ice as python-zeroc-iceis incompatible to Python 2.5 in Hardy. I have prepared fixed Packages in my PPA on Launchpad,please consider updating to these packages if you intend to use Ice on Hardy. If you want to knowmore, please see issue 64.

Debian and Ubuntu Packages

• I am packaging Mumble-Django for Debian. To watch the status of the packages, check out Debian’s packagetracker.

• If packages are available for the Debian version you are using, just type apt-get install mumble-django to installthem.

• The packages have the mumble-server package as a dependency, so make sure the installation of that packagedoesn’t break anything if you’re using Murmur static. If it does, you should go for the manual installation.

• Ubuntu has included my Debian packages in Lucid Lynx, so if you are using this or any later Ubuntu version,Apt will be able to install MD as well.

Warning: The packages included in Ubuntu have an error in their configuration file. This is becauseUbuntu chose to ignore my update request and Lucid still ships with v1.1, which needs the slice version tobe configured in settings.py, but failed to do so. The variable SLICE_VERSION needs to be changed to(1, 2, 2) in /etc/mumble-django/settings.py before Mumble-Django will work.

Manual Installation

• First of all, decide if you want to use Ice or DBus. On most installations, you will want to use Ice.

• You need these packages: libapache2-mod-wsgi python-imaging python-simplejson mercurial

• If you want to use DBus: python-dbus

• If you want to use Ice: python-zeroc-ice

So for using Ice, type apt-get install libapache2-mod-wsgi python-imaging python-simplejson mercurialpython-zeroc-ice.

• Django is required in Version 1.2.3. To find out which version is packaged in your distribution, type apt-cacheshow python-django | grep Version. If that version is too old, you need to install Django using easy_installdjango, otherwise you should install it using apt-get install python-django.

Note: If you receive the error easy_install: Command not found, you need to install the python-setuptools package.

• The installation of django-registration depends on how you installed Django itself. If you used easy_install,type easy_install django_registration, otherwise use apt-get install python-django-registration.

• Murmur needs to be reachable over DBus or Ice. If you need further info on that, see:

• Connecting Murmur to DBus

• Making Murmur available via Ice

• Choose where to install mumble-django to. I recommend /srv/mumble-django.

• Go to the path where you want mumble-django to be installed, and then use Mercurial to retrieve it:

4 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

• cd /srv

• hg clone http://bitbucket.org/Svedrin/mumble-django

• cd mumble-django

• hg update stable

• chown -R www-data:www-data /srv/mumble-django

• If you intend to use Ice, make sure the path to the Slice file configured in pyweb/settings.py (SLICE variable)points to the correct Murmur.ice file for your Murmur installation.

Note: This step will not be necessary from Murmur 1.2.3 on, because in that version Murmur introduces a wayto retrieve the correct slice directly from it. You can find out if your system supports this by running pythonmanage.py getslice.

• Run python manage.py syncdb to create the database.

• When asked if you would like to create an admin user, answer yes. You will need this user to log in to the adminsystem. (If you want to do this later on, run python manage.py createsuperuser.)

• Mumble-Django will now try to find already existing server instances. If for some reason this does not work,you can safely skip it by not specifying a service string when prompted, and later repeat the process by runningpython manage.py syncdb again.

• Now, the basic setup is complete. You can test Mumble-Django by running python manage.py runserver0.0.0.0:8000 and pointing your web browser to http://<your.address.example.com>:8000/.

• You should run python manage.py checkenv now. This script will check your environment for a few commonmistakes. If any of the tests fails, you should fix the error you get before you continue.

• In order to run Mumble-Django on a production webserver like Apache2, you can follow the Web Server setuppage.

Other distributions

Of course, Mumble-Django does not only run on Debian, but on all distros that can somehow handle the prerequisites.You just need to figure out how to install the Webserver, PIL and SimpleJSON; the rest of the Manual Installationhowto should work for any other distro as well.

Running Mumble 1.1.x and 1.2.x simultaneously

Beginning from 1.2.0, the Mumble project has started deprecating DBus and migrating to ZeroC Ice. As Ice onlysupports connecting to Murmur servers that have the same version, connecting to both 1.1.x and 1.2.x servers requiresyou to use DBus for 1.1.x, and Ice for 1.2.x servers.

That way, you will still be able to administer both versions from the same installation of Mumble-Django withoutlosing any functionality.

Connecting Murmur to DBus

If you are unfamiliar with DBus and don’t know how to connect Murmur to the system DBus, you should read on.

1.1. Mumble-Django: A Mumble web interface 5

Mumble-Django Documentation, Release 2.4

Configuring Murmur

The first thing you need to do is edit murmur.ini, and find these lines:

# Murmur defaults to not using D-Bus. If you wish to use dbus, which is one of the# RPC methods available in murmur, please specify so here.##dbus=session

# Alternate service name. Only use if you are running distinct# murmurd processes connected to the same D-Bus daemon.#dbusservice=net.sourceforge.mumble.murmur

You need the dbus setting to be set to “system”, the dbusservice only needs to be changed if this is not the onlyMurmurd process that you want to be reachable over DBus. If this is not the case for you, leave this setting alone!

So after you’re done, the section should look like this:

# Murmur defaults to not using D-Bus. If you wish to use dbus, which is one of the# RPC methods available in murmur, please specify so here.#dbus=system

# Alternate service name. Only use if you are running distinct# murmurd processes connected to the same D-Bus daemon.#dbusservice=net.sourceforge.mumble.murmur

Restarting Murmur

The next step is to restart murmur, so it applies the new configuration. How to do that depends on the way you installedMurmur.

• If you installed it via apt on Debian, run /etc/init.d/mumble-server restart.

• If you installed it yourself from the static package, type killall murmur.x86 to kill the running daemon, and./murmur.x86 to start it up again.

Checking if it works

After you restarted Murmur, check murmur.log to see if it is able to connect to DBus. If you installed using apt, the logwill be located at /var/log/mumble-server/mumble-server.log, otherwise it will be murmur.log in whatever directoryyou unpacked murmur to.

You want to see a message like this:

<W>2009-03-26 12:25:01.038 DBus registration succeeded

If you see this message, Murmur registered on the DBus and is now reachable - you’re done! :)

Troubleshooting DBus

If you get DBus error messages in Murmur’s logfile, you need to do a bit more work.

6 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

Failed to connect to D-Bus system

If you get an error message like this, it means you don’t have the DBus daemon installed or running:

<W>2009-03-26 12:24:34.994 Failed to connect to D-Bus system

In this case, install and start the DBus daemon. How to do that depends on your distribution, on Debian it works likethis:

apt-get install dbus/etc/init.d/dbus restart

After you installed DBus, this message should disappear, but most likely you will get another error message:

Failed to register on DBus

If you get this error message, it means that DBus is installed and running, yet access is denied to Murmur:

<W>2009-03-26 12:38:16.692 Failed to register on DBus: org.freedesktop.DBus.Error.AccessDeniedConnection ”:1.1” is not allowed to own the service “net.sourceforge.mumble.murmur” due to securitypolicies in the configuration file

This can be fixed by configuring DBus to allow the user under wich Murmur runs to own the name“net.sourceforge.mumble.murmur”. To do that, place a file named murmur.conf in the directory /etc/dbus-1/system.d,and put the following XML into it:

<!DOCTYPE busconfig PUBLIC"-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN""http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">

<busconfig><policy user="mumble-server">

<allow own="net.sourceforge.mumble.murmur"/></policy><policy context="default">

<allow send_destination="net.sourceforge.mumble.murmur"/><allow receive_sender="net.sourceforge.mumble.murmur"/>

</policy></busconfig>

Note that on the first policy tag, you need to set the correct user name in line 5! Otherwise, Murmur will still bedenied access!

After you put the configuration file in place, restart DBus by running /etc/init.d/dbus restart and repeat the steps from“Restarting Murmur”. Once Murmur successfully connects to DBus, you’re all set.

Making Murmur available via Ice

To make Murmur reachable via Ice, all you need to do is edit murmur.ini and restart Murmur.

Configuring Murmur

The first thing you need to do is edit murmur.ini, and find these lines:

1.1. Mumble-Django: A Mumble web interface 7

Mumble-Django Documentation, Release 2.4

# If you want to use ZeroC Ice to communicate with Murmur, you need# to specify the endpoint to use. Since there is no authentication# with ICE, you should only use it if you trust all the users who have# shell access to your machine.# Please see the ICE documentation on how to specify endpoints.#ice="tcp -h 127.0.0.1 -p 6502"

First of all, uncomment the last line:

# If you want to use ZeroC Ice to communicate with Murmur, you need# to specify the endpoint to use. Since there is no authentication# with ICE, you should only use it if you trust all the users who have# shell access to your machine.# Please see the ICE documentation on how to specify endpoints.ice="tcp -h 127.0.0.1 -p 6502"

Next, look for the following section:

# Note that if this is uncommented and with empty content,# access will be denied.

#icesecretread=icesecretwrite=

And make sure the last line either sets a secret, or is commented. If you are the only user of the machine that Murmuris running on, the recommended way is to comment the last line, thereby disabling the Ice secret:

# Note that if this is uncommented and with empty content,# access will be denied.

#icesecretread=#icesecretwrite=

Restarting Murmur

The next step is to restart murmur, so it applies the new configuration. How to do that depends on the way you installedMurmur.

• If you installed it via apt on Debian, run /etc/init.d/mumble-server restart.

• If you installed it yourself from the static package, type killall murmur.x86 to kill the running daemon, and./murmur.x86 to start it up again.

Web Server setup

In order to run Django on a production web server, you need to configure a few things. I have found using mod_wsgiwith an Apache2 web server to be most convenient, because it does not interfere with other scripting laguages (asmod_python does, as far as I know), and you do not need to handle server processes as you would when usingFastCGI.

If you want to use Lighttpd, you should have a look at the lighttpd section at the end of this page.

Note: Before you start, please do check that the db directory (in which the database file mumble-django.db3 islocated) is writable for your web server’s user! That usually means changing the owner to a user like www-data orhttpd.

8 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

The directory needs to be writable because sqlite requires Apache to be able to create a new file along the databasefile.

Apache2

To configure your apache2 server to use Django with WSGI, you need to install mod_wsgi (for Debian: apt-get installlibapache2-mod-wsgi) and create an Apache2 VHost that uses the WSGI config shipped with Mumble-Django.

The WSGI config

The WSGI config file is a simple python script, that is shipped as mumble-django.wsgi. Normally you do not need tochange anything in it because it detects the needed paths automatically.

The Apache VirtualHost config

There are two possible ways how to run Mumble-Django. You can either set up a dedicated VirtualHost for onlyMumble-Django to run (e.g., a subdomain), or install it to share an existing VirtualHost. The recommended way issetting up a dedicated VirtualHost.

Dedicated VirtualHost

I am using the following config on my server (you can find this file shipped with Mumble-Django asetc/apache2/dedicated_vhost.conf):

<VirtualHost *:80>ServerName example.comServerAlias www.example.com

Alias /static/admin/ /usr/share/pyshared/django/contrib/admin/→˓media/

Alias /static/ /srv/mumble-django/htdocs/Alias /mumble/media/ /srv/mumble-django/pyweb/mumble/media/

WSGIScriptAlias / /srv/mumble-django/mumble-django.wsgiWSGIDaemonProcess mumble-django threads=25WSGIProcessGroup mumble-djangoWSGIScriptReloading Off

</VirtualHost>

In Debian, you would put this in a file under /etc/apache2/sites-available, e.g. /etc/apache2/sites-available/mumble-django.

You will need to reconfigure most of these paths. The “media” alias needs to point at where django keeps itsAdmin media, the path I use is correct if you use the python-django package from Debian Sid. If you installedDjango yourself using setup.py, it will reside somewhere in your site-packages directory, e.g. “/usr/lib/python2.4/site-packages/django/contrib/admin/media”.

As you see, the /static/ alias needs to point to the htdocs directory from the archive, and the WSGIScriptAlias needsto point to the WSGI script.

1.1. Mumble-Django: A Mumble web interface 9

Mumble-Django Documentation, Release 2.4

Hint: Note the trailing slashes at the paths in the Alias directives. These are required!

Shared VirtualHost

If you want Mumble-Django to share another VirtualHost, you will need to merge the configuration from above withthe other VirtualHost. Have a look at the file etc/apache2/shared_vhost.conf that is shipped with Mumble-Django foran example how to do that.

Hint: Don’t forget to change the MUMBLE_DJANGO_URL setting in pyweb/settings.py!

Reloading the server

When you created this config file, enable it by running a2ensite mumble-django and run /etc/init.d/apache2 reloadto enable the VHost. Then you can reach Mumble-Django by pointing your web browser to http://example.com orhttp://www.example.com.

lighttpd

If you want to use Mumble-Django with lighttpd, you will have to set up FastCGI and configure your lighttpd toconnect to it. An example config file which also explains how that can be done is shipped as etc/lighttpd/lighttpd.conf.

Troubleshooting

Unable to open Database file

If you get that error, it means that Apache does not have sufficient access rights for the directory Mumble-Django hasbeen installed in, and therefore can’t open the database file. This is not an issue of the Database file itself, but you needto fix the permissions of the directory you installed MD in, usually by changing the owner to www-data or grantingchmod a+rx.

Trying to write to readonly database

This message means that Apache has been able to open the database file for reading, but not for writing. As for thedirectory, this is usually fixed by changing the owner of mumble-django.db3 to www-data or granting chmod a+w. Thelatter one is a serious security issue and therefore discouraged, the recommended way is setting the owner correctly.

401 Invalid Request

If you get an error along the lines of “Your browser sent a request this server could not understand”, please check ifyour web server has mod_reqtimeout enabled and disable it, as it has been known to cause problems sometimes. OnDebian/Ubuntu systems, running a2dismod reqtimeout and /etc/init.d/apache2 restart will fix this issue.

10 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

Python Egg Cache

Some users experienced problems with this config, as the WSGI handler didn’t load for them, and they got this errormessage in the logs:

The following error occurred while trying to extract file(s) to the Python eggcache:

[Errno 13] Permission denied: '/root/.python-eggs'

To fix this, you need to point the egg cache directory somewhere else. To do that, uncommenting the following line inmumble-django.wsgi should suffice:

os.environ['PYTHON_EGG_CACHE'] = '/tmp/pyeggs'

This will tell Python to create its egg cache in /tmp, and it has full write access there. Now reload the web server, andeverything should be fine.

Debian/Ubuntu: mumble-server-web

On Debian, if you installed Mumble-Server-Web, you won’t see the main Mumble-Django web interface that youexpect. This is because Mumble-Server-Web includes an Alias named “/mumble” in the Apache2 configuration,which overrides the URL used by Mumble-Django.

To get rid of this, uninstall Mumble-Server-Web; Mumble-Django will be able to do everything these scripts provideanyway. :)

mod_python

Problems have been reported when using mod_wsgi while mod_python is loaded, because it prevents the page fromloading. If that is the case, you can either remove mod_python from the server setup (or use it instead of mod_wsgi),or switch to FastCGI.

Unable to connect to WSGI daemon process ‘mumble-django’

This problem seems to occur when the WSGI daemon is unable to write its sockfile, because then it silently terminatesand Apache can’t connect.

To resolve this, add the following line to your Apache config in the Server config context (that is, outside any<VirtualHost> directive):

WSGISocketPrefix /tmp/wsgi

Download, Source code

You can find zip or gz packages for all versions on the Downloads page. As Mumble-Django is written in Python,there is no destinction between source and binary packages.

The latest development version is always available in the tip package.

1.1. Mumble-Django: A Mumble web interface 11

Mumble-Django Documentation, Release 2.4

Demo installation

The demo installation is running here: http://demo.mumble-django.org/mumble-django/

This installation is based on Debian Testing.

Prerequisites, Installation

Please see the Installation of Mumble-Django page for more information about what’s needed and how to installMumble-Django.

Known Issues

For a list of known bugs, please see the Issues page. If you find a bug or would like to request a feature, this is also theplace to go. Please feel free to open a ticket whenever you like!

Contact

If you need help (or anything else), you can contact me via IRC (Svedrin in #mumble on Freenode) or Jabber(ich@svedr.in).

You might want to follow me on Twitter, and I always use the #mumbledjango hashtag for tweets concerning theproject. This way, you can easily get the latest news!

Further documentation

SourceArchive.com seems to generate an API documentation using DoxyGen, which can be found under http://mumble-django.sourcearchive.com/versions/main.html.

Get involved

There are several ways you can help in the development of mumble-django:

• Write or maintain a Translation.

• Test new versions before they are released.

• Submit bug reports if you find an error.

• If you miss a feature and you can add it, submit a patch.

• Help maintaining the documentation in the Wiki.

• If you want to join the team, just contact Svedrin on Freenode. Help is always welcome :)

• make a donation

License

This app is licensed under the GPL v2 or later.

12 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

Mumble-Django: Ein Web-Interface für Mumble

See also:

This documentation in English: Mumble-Django: A Mumble web interface

See also:

Programmierer sollten sich die API Documentation ansehen.

See also:

Diese Dokumentation gibts auch im PDF-Format.

See also:

Auf YouTube gibts eine Videoanleitung für die Installation.

Murmur-Konfiguration, Registrierung und mehr

Mumble ist ein hochqualitatives Sprach- und Chatprogramm mit geringer Latenz. Es unterstützt Rauschunterdrück-ung, automatische Verstärkungsregelung und Audioübertragung in mehreren Audio-Standards. Als einziges VoIP-Produkt seiner Art steht Mumble unter einer freien Lizenz.

Das Mumble-Projekt konzentriert sich jedoch auf die Entwicklung von Mumble selbst und bietet daher keine Web-Administrations-Lösung an. Mumble-Django ist eine solche Lösung, die auf Python und Django basiert, und ihrerseitsunter einer freien Lizenz steht.

Im Vergleich mit anderen existierenden Webinterfaces überzeugt Mumble-Django durch seine strikte Einhaltung derSchnittstellen von Mumble und seinen vollständigen Funktionsumfang. Als Django-Projekt bietet es weiterhin einhohes Potenzial für Erweiterungen und kann einfach in andere Django-Projekte integriert werden.

Features

• Benutzt ausschließlich DBus/Ice um zum Server zu verbinden - in keinem Fall wird Mumble-Django versuchen,direkt auf Murmurs Datenbank zuzugreifen

• Kompatibel mit Murmur 1.1.8 und 1.2.0 – Standardeinstellung ist 1.2.0

• Kann sowohl Murmur 1.1.8 als auch 1.2.0 mit einer einzigen Installation verwalten, wenn DBus für 1.1.8 undIce für 1.2.0 benutzt wird

• Abwärtskompatibel zu Murmur 1.1.4

• Erstellt automatisch eine Channel-Liste für jeden konfigurierten Server (Demo)

• Jeder Channel ist verlinkt, mit einem Klick joinst du direkt in diesen Channel

• Ein Klick auf einen Benutzernamen zeigt nähere Infos zu diesem Benutzer an

• Wenn du im Webinterface eingeloggt bist, wird dein Benutzername in die Links übernommen

• leere Subchannels werden ausgeblendet um die Liste übersichtlich zu halten (etwa so wie in Mumble selbst)

• Erkennt Handy-Browser und liefert diesen eine speziell zugeschnittene Version der Seite (Demo)

• Unterstützt das Channel-Viewer-Protocol

• Kann als Datenquelle für den Channel-Viewer von Murmur-Manager dienen (Demo)

• Das mitgelieferte Munin-Plugin zeichnet einen Graphen über die Anzahl der Benutzer auf jedem Server (Demo)

• Verwaltet so viele Murmur-Installationen wie du willst, sie müssen nur über DBus oder Ice erreichbar sein

1.2. Mumble-Django: Ein Web-Interface für Mumble 13

Mumble-Django Documentation, Release 2.4

• Das [[Admin_Interface_de|Admin-Interface]] konfiguriert folgende Parameter:

• Registrierungsname (der Name mit dem der Server im Browser auftaucht, auch der Name des Root-Channels)

• Server-Adresse (kann sowohl eine IP-Adresse als auch ein Hostname sein)

• Server-Port

• URL der Webseite, die im Browser auftaucht

• Willkommensnachricht

• Server-Passwort

• Superuser-Passwort

• Anzahl Benutzer (Slots)

• Bandbreite

• SSL-Zertifikat and Key

• Die einzelnen Murmur-Instanzen können gestartet und gestoppt werden

• Benutzer-Registrierung

• In Django registrierte Benutzer können sich auf den Murmur-Servern Accounts erstellen und mit +A joinen

• Accounts können im Admin-Interface verwaltet werden

• zur Sicherheit werden die Passwörter der Benutzer nicht gespeichert (das Feld existiert nur um mit Django-Models kompatibel zu sein)

• Benutzer können im Admin-Interface zur //admin//-Gruppe hinzugefügt / aus ihr entfernt werden

• “manage.py syncdb” erkennt existierende Murmur-Instanzen und Benutzer und trägt diese in die DB ein

• Admin Interface für Mitglieder der admin-Gruppe

• Benutzerverwaltung für Serveradmins: erstellt/löscht Registrierungen, vergibt Adminrechte, ändert Benutzer-passwörter (Screenshot)

• Benutzertexturen einstellen

• Connector-Module um einfach zwischen DBus und Ice umzuschalten

• Das Template ist eine einzige Datei: Wenn’s dir nicht gefällt, ändere einfach die index.htm

• Vollständig kompatibel mit Djangos Datenbank-API: Die Kommunikation mit Murmur erfolgt komplett inner-halb der Models

• Alle Konfigurations-Optionen von Murmur werden unterstützt

• Erzeugt valides XHTML transitional (abgesehen von HTML in den Kanal-/Benutzer- Beschreibungen :) )

• Erweiterbar: Mumble-Django ist ein normales Django-Projekt und benutzt ausschließlich die Standard-Modelsvon Django, du kannst es daher wie jede andere Django-App einbinden und es sogar zu einer kompletten Web-seite erweitern.

Installation von Mumble-Django

Voraussetzungen

Damit Mumble-Django funktioniert wirst du die folgende Software brauchen. Wie man die einzelnen Pakete aufsetztwird im Abschnitt Installation näher beschrieben.

14 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

• Murmur :)

• Ein Webserver mit Unterstützung für WSGI oder FastCGI. Empfohlen wird Apache2 mit mod_wsgi, wie mandas konfiguriert steht auf der Seite Web-Server-Konfiguration. (Der Webserver wird übrigens als letztes konfig-uriert, er steht hier nur dabei weil du einen brauchen wirst.)

• Python (mindestens Version 2.5)

• Django (mindestens Version 1.2.3)

• django-registration

• Python-Module:

• PIL: Python Imaging Library (benötigt für Benutzertexturen)

• simplejson (benötigt für die Benutzerverwaltung)

• qrencode (nur wenn du QR-Codes für den Server anzeigen willst)

• Wenn du DBus benutzt (für Murmur älter als 1.1.8):

• DBus and python-dbus

• alle Murmur-Installationen müssen über den System-Bus erreichbar sein.

• Murmur und mumble-django müssen auf demselben Rechner laufen, da DBus keine Verbindungenüber ein Netzwerk unterstützt.

• Wenn du Ice benutzt (empfohlen):

• python-zeroc-ice

• Wenn du Ubuntu Hardy (8.04) benutzt wirst du wahrscheinlich auf Probleme mit Ice stoßen, weildas python-zeroc-ice-Paket aus Hardy mit Python 2.5 nicht kompatibel ist. Ich habe kompatiblePakete in meinem PPA auf Launchpad bereitgestellt, bitte überlege auf diese Pakete zu aktualisierenwenn du Ice benutzen willst. Wenn du mehr wissen willst, sieh dir bitte den Thread zu issue 64 an.

Debian- bzw. Ubuntu-Pakete

• Ich paketiere Mumble-Django für Debian. Den Status der Pakete kannst du auf Debians Paket-Tracker verfol-gen.

• Wenn es für deine Debian-Version Pakete gibt, kannst du sie einfach per apt-get install mumble-django instal-lieren.

• Die Pakete haben mumble-server als Abhängigkeit, wenn du vorhast Murmur Static zu verwenden (beispiel-sweise weil du eine neuere Version benutzen willst als die die paketiert ist) kann das Probleme machen. Indiesem Fall solltest du die manuelle Installation durchführen.

• Ubuntu hat meine Debian-Pakete in Lucid Lynx hinzugefügt, wenn du diese oder eine neuere Ubuntu-Versionbenutzt kannst du also auch Apt benutzen.

Warning: Die Pakete die Ubuntu Lucid ausliefert haben einen Fehler in der Konfigurationsdatei. Diesliegt daran dass Ubuntu meine Update-Anfrage ignoriert hat und Mumble-Django v1.1 ausliefert, beiwelchem die Slice-Version in settings.py festgelegt werden muss, aber dies nicht getan hat. Die VariableSLICE_VERSION muss auf (1, 2, 2) geändert werden damit Mumble-Django funktioniert.

1.2. Mumble-Django: Ein Web-Interface für Mumble 15

Mumble-Django Documentation, Release 2.4

Manuelle Installation

• Zuerst einmal musst du überlegen ob du DBus oder Ice benutzen willst. Normalerweise solltest du dich für Iceentscheiden.

• Du benötigst folgende Pakete: libapache2-mod-wsgi python-imaging python-simplejson mercurial

• Wenn du DBus benutzen willst: python-dbus

• Wenn du Ice benutzen willst: python-zeroc-ice

Für Ice also: apt-get install libapache2-mod-wsgi python-imaging python-simplejson mercurial python-zeroc-ice

• Django wird mindestens in Version 1.2.3 benötigt. Auf einem Debian-System kannst du die paketierte Versionmit dem Befehl apt-cache show python-django | grep Version herausfinden. Ist diese zu alt, musst du Djangomit dem Befehl easy_install django installieren, ansonsten solltest du apt-get install python-django benutzen.

Note: Erhältst du den Fehler easy_install: Command not found, musst du das Paket python-setuptools installieren.

• Die Installation von Django-Registration hängt davon ab, wie du Django selbst installiert hast. Hast du apt be-nutzt, so lautet der Befehl apt-get install python-django-registration, ansonsten easy_install django-registration.

• Murmur muss über DBus oder Ice erreichbar sein. Wenn du dazu weitere Infos brauchst, siehe:

• Connecting Murmur to DBus

• Making Murmur available via Ice

• Überlege dir wohin du Mumble-Django installieren willst. Ich empfehle /srv/mumble-django.

• Wechsle per cd ins Zielverzeichnis und benutze dann Mercurial um Mumble-Django herunterzuladen:

• cd /srv

• hg clone http://bitbucket.org/Svedrin/mumble-django

• cd mumble-django

• hg update stable

• chown -R www-data:www-data /srv/mumble-django

• Falls du Ice benutzen willst, sieh in pyweb/settings.py nach ob der dort eingetragene Pfad zur Slice-Datei(SLICE) korrekt ist und zur Datei Murmur.ice in deiner Murmur-Installation zeigt.

Note: Dieser Schritt wird ab Murmur 1.2.3 aufwärts nicht mehr nötig sein, weil Murmur in dieser Version eineMethode einführt mit der Mumble-Django das Slice direkt von Murmur holen kann. Du kannst rausfinden obdein System diese Methode unterstützt, indem du den Befehl python manage.py getslice benutzt.

• Starte python manage.py syncdb um die Datenbank zu erzeugen.

• Du wirst irgendwann gefragt ob du einen Admin anlegen möchtest. Antworte hier yes, denn diesen Benutzerwirst du brauchen um dich an der Admin-Konsole anzumelden. (Falls du das später nochmal machen willst,kannst du den Befehl python manage.py createsuperuser benutzen.)

• Mumble-Django wird dann versuchen, bereits existierende Server-Instanzen zu finden. Wenn das aus irgen-deinem Grund nicht funktioniert kannst du das problemlos überspringen, und es später wiederholen indem dupython manage.py syncdb erneut ausführst.

16 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

• Damit ist die Basisinstallation abgeschlossen. Du kannst Mumble-Django jetzt testen, indem du python man-age.py runserver 0.0.0.0:8000 ausführst und im Browser die Adresse http://<dein-server.example.com>:8000/aufrufst.

• Du solltest jetzt python manage.py checkenv ausführen. Dieses Script prüft dein Setup und findet einige Fehler,die häufig gemacht werden. Wenn einer der Tests fehlschlägt solltest du den Fehler erst beheben, bevor duweiter machst.

• Wenn du Mumble-Django auf einem Webserver wie Apache2 laufen lassen willst, sieh dir die Seite Web-Server-Konfiguration an. Dort gibt es weitere Informationen, wie man Apache mit WSGI konfiguriert.

Andere Distributionen

Mumble-Django funktioniert natürlich nicht nur auf Debian, sondern auf allen Distributionen die irgendwie die Vo-raussetzungen erfüllen. Du musst nur rausfinden wie auf deiner Distro die Pakete heißen die ich unter Debian per Aptinstalliere, der Rest des Howtos für Debian sollte auch auf allen anderen Distros funktionieren.

Murmur 1.1.x und 1.2.x gleichzeitig verwalten

Mit Version 1.2.0 hat das Mumble-Projekt aufgehört DBus zu unterstützen und begonnen zu ZeroC Ice zu migrieren.Da Ice nur Verbindungen zu Murmur-Servern unterstützt die dieselbe Version haben, musst du um gleichzeitig 1.1.x-Server und 1.2.x-Server verwalten zu können beide Methoden kombinieren. Konfiguriere dazu den 1.1.x-Server überDBus, und den 1.2.x-Server über Ice.

Dadurch wird die Inkompatibilität umgangen ohne dass man auf Features verzichten müsste, da bis Murmur 1.1.8 dasDBus- und das Ice-Interface nahezu identisch sind.

Web-Server-Konfiguration

Um Django auf einem Webserver wie Apache2 laufen zu lassen, müssen einige Dinge konfiguriert werden. Ichempfehle Apache2 mit mod_wsgi, da dies nicht mit anderen Scriptsprachen interferiert und man sich nicht um Server-prozesse kümmern muss wie bei FastCGI.

Wenn du Lighttpd benutzen willst, solltest du dir die Lighttpd-Sektion am Ende dieser Seite ansehen.

Note: Bevor du anfängst, prüfe bitte ob das Verzeichnis db (in dem die Datenbankdatei mumble-django.db3 liegt)für den Benutzer des Webservers schreibbar ist! Das bedeutet im Normalfall dass du den Besitzer der Datei aufwww-data oder httpd setzen musst.

Es ist wichtig dass das Verzeichnis schreibbar sein muss, Apache muss darin für sqlite eine weitere Datei zusätzlichzur Datenbank anlegen dürfen.

Apache2

Für WSGI muss zuerst mod_wsgi installiert werden (Debian: apt-get install libapache2-mod-wsgi) und eine VHost-Konfiguration erstellt werden, die das WSGI-Script einbindet welches bei Mumble-Django beiliegt.

Das WSGI-Script

Das WSGI-Script ist ein einfaches Python-Script, welches bei Mumble-Django als mumble-django.wsgi beiliegt. Nor-malerweise brauchst du hier gar nichts ändern, weil es alle Pfade die es braucht automatisch erkennt.

1.2. Mumble-Django: Ein Web-Interface für Mumble 17

Mumble-Django Documentation, Release 2.4

Die Apache-VirtualHost-Config

Es gibt zwei Möglichkeiten, Mumble-Django in Apache zu integrieren. Du kannst entweder einen kompletten Virtual-Host für Mumble-Django erstellen (z.b. als Subdomain), oder du kannst es in einen bereits existierenden VirtualHostintegrieren. Die empfohlene Variante ist aber ein eigener VirtualHost.

Eigener VirtualHost

Ich benutze folgende Config auf meinem Server (diese Datei liegt Mumble-Django auch bei unteretc/apache2/dedicated_vhost.conf):

<VirtualHost *:80>ServerName example.comServerAlias www.example.com

Alias /static/admin/ /usr/share/pyshared/django/contrib/admin/→˓media/

Alias /static/ /srv/mumble-django/htdocs/Alias /mumble/media/ /srv/mumble-django/pyweb/mumble/media/

WSGIScriptAlias / /srv/mumble-django/mumble-django.wsgiWSGIDaemonProcess mumble-django threads=25WSGIProcessGroup mumble-djangoWSGIScriptReloading Off

</VirtualHost>

In Debian würde man diese Config in einer Datei unter /etc/apache2/sites-available speichern, beispielsweise/etc/apache2/sites-available/mumble-django.

Du wirst hier die meisten Pfade anpassen müssen. Der Alias “media” muss auf das Verzeichnis zeigen in dem Djangodie Dateien für die Admin-Konsole speichert. Der voreingestellte Pfad stimmt für Debian Sid, wenn du Django überApt installiert hast. Wenn du Django über python setup.py install installiert hast, musst du einen der letzten beidenPfade nehmen, abhängig von der Python-Version.

Der Alias “/static/” muss auf Mumble-Djangos htdocs-Verzeichnis zeigen, der WSGIScriptAlias muss auf das WSGI-Script zeigen.

Hint: Die Slashes am Ende der Pfade werden gebraucht!

Existierenden VHost mitbenutzen

Wenn du Mumble-Django in einen existierenden VirtualHost integrieren willst, musst du die obige Config mit der desanderen VHost zusammenführen. Für ein Beispiel wie das aussieht sieh dir die Datei etc/apache2/shared_vhost.confan, die mit Mumble-Django auch mitgeliefert wird.

Hint: Vergiss nicht die Einstellung MUMBLE_DJANGO_URL in pyweb/settings.py anzupassen!

18 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

Die Apache-Konfiguration neu laden

Nachdem du die Datei erstellt hast, füge sie der Server-Konfiguration hinzu indem du a2ensite mumble-django aus-führst, und lade die Serverkonfiguration per /etc/init.d/apache2 reload neu. Dann kannst du Mumble-Django erreichen,indem du example.com oder www.example.com ansurfst.

lighttpd

Um Mumble-Django mit Lighttpd zu benutzen, musst du FastCGI aufsetzen und deinen Lighty so konfigurieren dasser darauf verbinden kann. Eine Beispiel-Config für Lighty mit einigen Erklärungen wie das geht liegt bei Mumble-Django bei, unter etc/lighttpd/lighttpd.conf.

Fehlerbehebung

Unable to open Database file

Dieser Fehler bedeutet dass Apache nicht die Zugriffsrechte hat die er benötigt um die Datenbankdatei öffnen zukönnen. Dieses Problem liegt allerdings nicht an der Datei selbst, sondern die Berechtigungen des Verzeichnisses indem du Mumble-Django installiert hat sind falsch und müssen korrigiert werden. Dazu musst du normalerweise denBesitzer des Verzeichnisses auf www-data setzen, oder chmod a+rx setzen.

Trying to write to readonly database

Das bedeutet dass Apache die Datenbankdatei zwar zum Lesen öffnen konnte, aber nicht zum Schreiben. Wie beimVerzeichnis auch kannst du das normalerweise beheben indem du den Besitzer der Datei mumble-django.db3 aufwww-data setzt, oder chmod a+w setzt. Letzteres ist allerdings eine ernste Sicherheitslücke, daher ist der empfohleneWeg den Besitzer richtig zu setzen.

401 Invalid Request

Wenn du im Browser einen Fehler ähnlich wie “Your Browser sent a request this server could not understand”bekommst, sieh bitte nach ob dein Webserver das Modul mod_reqtimeout geladen hat und deaktiviere es gegebe-nenfalls, weil es gelegentlich dieses Problem verursacht. Auf Debian/Ubuntu-Systemen geht dies mit den Befehlena2dismod reqtimeout und /etc/init.d/apache2 restart.

Python Egg Cache

Manche Benutzer hatten Probleme mit dieser Konfiguration, weil der WSGI-Handler nicht startete und im Logfilefolgende Nachricht erschien:

The following error occurred while trying to extract file(s) to the Python eggcache:

[Errno 13] Permission denied: '/root/.python-eggs'

Um das zu beheben, reicht es den Egg-Cache von Python in ein anderes Verzeichnis zu legen. Entferne dazu dasKommentar-Zeichen vor folgender Zeile in mumble-django.wsgi:

os.environ['PYTHON_EGG_CACHE'] = '/tmp/pyeggs'

1.2. Mumble-Django: Ein Web-Interface für Mumble 19

Mumble-Django Documentation, Release 2.4

Damit legt Python seinen Egg-Cache in /tmp an. Lade nun die Server-Konfiguration neu, und es sollte funktionieren.

Debian: mumble-server-web

Wenn du in Debian das Paket mumble-server-web installiert hast, wird die Hauptseite von Mumble-Django nichterscheinen, weil mumble-server-web einen Alias namens “/mumble” in die Apache-Konfiguration einfügt und damiteine URL von Mumble-Django überschreibt. Um das aufzulösen deinstalliere einfach mumble-server-web, Mumble-Django bietet sowieso alle Funktionen dieser Scripts.

mod_python

mod_python macht manchmal Probleme, weil es in irgendeiner Weise verhindert dass die Seite lädt. Wenn das derFall ist kannst du entweder mod_python deinstallieren (oder anstelle von mod_wsgi benutzen), oder auf FastCGIumsteigen.

Unable to connect to WSGI daemon process ‘mumble-django’

Dieses Problem tritt auf wenn der WSGI-Prozess sein Socket nicht erstellen kann, weil er sich dann einfach beendetund Apache nicht verbinden kann.

Um das zu beheben, füge die folgende Zeile deiner Apache-Config im Server-Context hinzu (also außerhalb einer<VirtualHost>-Direktive):

WSGISocketPrefix /tmp/wsgi

Download, Quellcode

Du findest Zip- und GZ-Pakete für alle Versionen auf der Download-Seite. Da Mumble-Django in Python geschriebenist, sind Binär- und Quellcodepakete identisch.

Die neueste Entwicklerversion ist immer im tip-Paket zu finden.

Demo-Installation

Eine Demo von Mumble-Django findest du hier: http://demo.mumble-django.org/mumble-django/

Diese Installation basiert auf Debian Testing.

Voraussetzungen und Installation

Dies wird auf der Seite Installation von Mumble-Django näher beschrieben.

Bekannte Probleme

Eine Liste bekannter Probleme gibt’s im Bugtracker, auf der Seite Issues. Falls du einen Bug findest oder ein Featurevorschlagen möchtest, ist das der richtige Ort. Bitte scheue dich nicht, dort ein Ticket zu eröffnen!

20 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

Kontakt

Für Hilfe (oder alles andere) kannst du mich gern im IRC (Svedrin in #mumble in Freenode) oder über Jabber(ich@svedr.in) ansprechen.

Du möchtest mir vielleicht auf Twitter folgen; ich nutze immer den Hashtag #mumbledjango für Tweets die das Projektbetreffen. Auf diese Weise kannst du sehr einfach über Neuigkeiten informiert werden.

Weitere Dokumentation

SourceArchive.com generiert eine API-Doku mittels DoxyGen, diese findest du unter http://mumble-django.sourcearchive.com/versions/main.html.

Helfen

Es gibt verschiedene Möglichkeiten wie du bei der Entwicklung von Mumble-Django helfen kannst:

• Schreibe oder überarbeite eine Übersetzung.

• Teste neue Versionen bevor sie veröffentlicht werden.

• Sende Fehlerberichte wenn du einen Fehler findest.

• Wenn dir eine Funktionalität fehlt und du sie programmieren kannst, sende einen Patch.

• Hilf mit die Dokumentation im Wiki aktuell zu halten.

• Wenn du über längere Zeit an MD mitarbeiten willst, sprich einfach Svedrin in Freenode an. Hilfe ist immerwillkommen. :)

• Du kannst auch etwas spenden

Lizenz

Mumble-Django ist Freie Software unter der GPL Version 2 oder neuer.

API Documentation

This part of the documentation describes the way Mumble-Django works. This information is generally only useful ifyou wish to extend Mumble-Django in some way or another - or if you are just curious, of course :)

Mumble-Django consists of two major parts:

1. The core Mumble application, that implements all the features

2. a Django project around the core app, that wraps up the Mumble app in a project ready to be installed on a webserver.

This documentation will mostly deal with the Mumble application, and covers the following sections:

Models

Models keep data and do stuff with it.

1.3. API Documentation 21

Mumble-Django Documentation, Release 2.4

MumbleServer

The MumbleServer model represents a server installation.

Mumble

Represents a server instance.

MumbleUser

Represents a user account on a server instance.

mmobjects

mmobjects are used to represent several data structures Murmur uses.

mmChannel

mmPlayer

mmACL

Views

Forms

MCTL: Mumble Control adapters

Mumble-Django abstracts the DBus and Ice interfaces Murmur offers through a series of Control objects.

djextdirect

Ext.Direct is an RPC framework included in ExtJS. It is being used by Mumble-Django for communications betweenthe web site and the server.

Provider

FormProvider

Client

Channel Viewer

Mumble-Django includes a Channel Viewer which has been written completely in JavaScript using ExtJS components.That way, it can be embedded seemlessly in a website (that is, without using iframe fakery) and load its content in thebackground using AJAX.

The source code for the channel viewer can be found here: http://bitbucket.org/Svedrin/mumble-django/src/tip/pyweb/mumble/media/js/channelviewer.js

22 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

Inclusion via iframe

Although the channel viewer protocol is designed to allow the channel viewer to be included directly on the website, people tend to find it easier to include the channel viewer via an iframe. In order to make this easier, Mumble-Django can also output a page that contains only the viewer. This page can be retrieved using http://demo.mumble-django.org/mumble-django/mumble/embed/<server_id> as the iframe’s target URL. Thatis, if http://demo.mumble-django.org/mumble-django/mumble/1 is the URL where you see yourserver’s detail page, http://demo.mumble-django.org/mumble-django/mumble/embed/1 will giveyou the channel viewer only.

Channel Viewer Protocol

The channel viewer expects to get its data in a JSON format which has been standardized as the ChannelViewer Protocol. This protocol is implemented by Mumble-Django, and can be queried using an URL likehttp://demo.mumble-django.org/mumble-django/mumble/1.json. That is, if http://demo.mumble-django.org/mumble-django/mumble/1 is the URL where you see your server’s detail page, sim-ply append .json or .xml to retrieve the data in the standardized format.

This format is parseable not only by Mumble-Django’s channel viewer, but indeed by all channel viewers which arecompatible to the Channel Viewer Protocol.

Usage examples

The following code can be used to render the channel viewer into the document’s body (that is, it will be the onlycontent the page contains):

Ext.QuickTips.init();viewer = new Ext.ux.MumbleChannelViewer({

renderTo: Ext.getBody(),idleInterval: 5,source_url: "http://example.com/mumble/1.json",imageurl: "http://example.com/img"});

Of course, the channel viewer can be embedded like any other ExtJS component, e.g. in a tab panel:

Ext.QuickTips.init();tabpanel = new Ext.TabPanel({

renderTo: Ext.getBody(),activeTab: 0,items: [{

xtype: "mumblechannelviewer",title: "Channels!",source_url: "http://example.com/mumble/1.json",imageurl: "http://example.com/img"

}, {title: "Infoez!",html: "Another tab"

}]});

1.3. API Documentation 23

Mumble-Django Documentation, Release 2.4

Demo

The channel viewer can be seen in action at http://viewer.shotgunfun.de/. You can enter arbitrary URLs to be queried,that way you can test this component against any Channel Viewer Protocol source you wish.

Example URLs are:

• http://shotgunfun.de/mumble/1.json (Default, Mumble-Django)

• http://mvbackend.natenom.name/mumblereader/mumble.php?port=64738 (mumblereader)

Resources

The channel viewer displays various icons; most notably the Mumble, Channel and User icons, but also those for theuser flags. In order to work, you need to pass the URL where those images are served in the imageurl config option.The images need to be in PNG format, and the following images are currently being used:

• authenticated

• channel

• comment_seen

• deafened_self

• deafened_server

• mumble.16x16

• muted_self

• muted_server

• muted_suppressed

• priority_speaker

• recording

• talking_off

• talking_on

Class definition

class Ext.ux.MumbleChannelViewer(config)Inherits from: Ext.tree.TreePanel

xtype: mumblechannelviewer

Arguments

• source_url (string) – The URL to query for channel/user information. Needs to pointto a channel viewer protocol compliant JSON resource.

• imageurl (string) – The URL where images for the user flags can be found.

• refreshInterval (int) – The interval in milliseconds at which the channel viewershould automatically reload its data. (Default: 30000, 0 to start with auto-refresh disabled)

• idleInterval (int) – A user is considered talking if their idlesecs param is lessthan or equal to the value given here. (Default: 2)

24 Chapter 1. Documentation index

Mumble-Django Documentation, Release 2.4

• enableDD (bool) – If true, Drag&Drop will be enabled to allow channels and players tobe moved around by the user.

Events

In addition to the standard events raised by a TreePanel, the channel viewer can raise these events if enableDD is setto true:

moveUser(Ext.tree.TreePanel this, Object userdata, Object chandata)Fired when a user has been moved to a new channel.

moveChannel(Ext.tree.TreePanel this, Object movedchandata, Object targetchandata)Fired when a channel has been moved to a new parent channel.

The data objects passed to the events conform to the channel viewer protocol.

See also:

This documentation is also available as a PDF file.

1.3. API Documentation 25

Mumble-Django Documentation, Release 2.4

26 Chapter 1. Documentation index

CHAPTER 2

Indices and tables

• genindex

• modindex

• search

27

Mumble-Django Documentation, Release 2.4

28 Chapter 2. Indices and tables

Python Module Index

ddjextdirect, 22

fforms, 22

mMCTL, 22mmobjects, 22models, 21

vviews, 22

29

Mumble-Django Documentation, Release 2.4

30 Python Module Index

Index

Ddjextdirect (module), 22

EExt.ux.MumbleChannelViewer() (class), 24

Fforms (module), 22

MMCTL (module), 22mmobjects (module), 22models (module), 21moveChannel() (built-in function), 25moveUser() (built-in function), 25

Vviews (module), 22

31