Ice

From Mumble Wiki
Revision as of 15:16, 13 April 2010 by KaszpiR (Talk | contribs)

Jump to: navigation, search

Murmur supports remote scripting using ZeroC Ice, a RPC mechanism. There are bindings for C++, Java, .NET, Python, PHP and Ruby, and this is supported on all our platforms (Win32, Linux and OSX). Ice also works over a network, meaning you can create a web application that interfaces with a Murmur process running on another machine.

All hosters note: local ICE connections have now been secured, without having to use Glacier, in Murmur 1.2.2. Simply use the icescret= parameter in your murmur.ini. Here is the latest murmur.ini needed to use icesecret. Note you must also have Murmur 1.2.2 or greater as well.

Getting ready to use Ice

To enable Ice in your murmur.ini configuration file first comment out

dbus=session

to disable dbus and add

ice="tcp -h 127.0.0.1 -p 6502"

to enable Ice for localhost on port 6502.

To check if Ice in fact does listen, type

netstat -apn | grep 6502

End User Howtos

Note that after you have ICE set up on your machine, you can install a web interface. Mumb1e Admin Plugin or MumPI are webinterfaces that requires minimal server configuration and be easy to use.

How to setup Ice for PHP with Apache on Linux (general)

If your Linux distribution offers a binary packet for Ice with php (usually the name contains Ice and php) you can skip everything but naming the Murmur.ice slicer file in the php.ini (see below). If there is no prepared package you'll have to try to find binaries for your system or compile Ice yourself and add the extension to php and tell php where to find the Murmur.ice file.

To add the IcePHP extension to php, first check that the file IcePHP.so for linux is in your php extensions folder specified in your php.ini as

extension_dir = /usr/lib/php5/extensions

If it is not, get the correspoding files from ZeroCs downloads page.

Then either in your php.ini file or in your /etc/php.d or /etc/php5/conf.d folder in ice.ini, add the line

extension=IcePHP.so

At least the linux rpms will do this automatically, so check that you're not doing it a second time.

Second, you have to tell the PHP parser where to find the slice (Specification Language for Ice) file. Add

ice.slice = /path/to/Murmur.ice

to your php.ini or other config file (ice.ini).

Troubleshooting

If you encounter problems, check your apache log.

If it tells you the php extension was compiled on an older api, you have to compile the IcePHP.so from source.

Download Ice-3.3.0.tar.gz from ZeroCs downloads page, untar, cd, cd into php, as written in the INSTALL file export ICE_HOME environment variable pointing to your ice install dir. If you installed it with an rpm, type

export ICE_HOME=/usr

then make, and in the lib folder, there'll be your IcePHP.so file.


One common error is

PHP Warning:  PHP Startup: skipping dictionary ::Murmur::UserInfoMap - unsupported key type in Unknown on line 0

This is caused because the .ice is slightly incompatible with older versions of php-ice - edit the Murmur.ice file and find the following lines

/** User information map.
* Older versions of ice-php can't handle enums as keys. If you are using one of these, replace 'UserInfo' with 'byte'.
*/

and perform the substitution mentioned.

How to setup Ice for PHP with Apache on Debian

These are example scripts. Use at your own risk.

This guide is for debian 5.0 (lenny) -upgraded to date 06.04.2009-

I assume you already have a working apache2 and php environment.


Prerequisites

First we need some essentials to aquire these execute the following in a root shell

apt-get update

apt-get install mumble-server icecpp libzeroc-ice32 php-zeroc-ice lzma

These are namely the Mumble server himself (mumble-server), ZeroC Ice himself (icecpp), the ZeroC-Ice C++ runtime Library (libzeroc-ice32), the Ice PHP extension (php-zeroc-ice) and the lzma extractor. Be aware that this installs a older server version WITHOUT Ice support. We will fix this later on.

Additionally we need the current Murmur, thats what the Mumble server is called, release.

Go to http://mumble.sourceforge.net/ and download the latest stable Static Linux Server. I suggest your home directory for that.

cd ~
wget http://switch.dl.sourceforge.net/sourceforge/mumble/murmur-static_x86-1.1.8.tar.lzma
unlzma -v murmur-static_x86-1.1.8.tar.lzma
tar xfv murmur-static_x86-1.1.8.tar


Step 1 - Murmur Setup

OPTIONAL: To run Murmur at every startup change the config value in /etc/default/mumble-server acordingly with a editor of your choice.

Now open the file /etc/mumble-server.ini

vim /etc/mumble-server.ini

OR

nano -w /etc/mumble-server.ini 

Uncomemnt the line that starts with dbus=

#dbus=system

Create a new line and paste

ice="tcp -h 127.0.0.1 -p 6502"

Murmur now knows that he should listen for Ice requests.


Step 2 - Manual update Murmur

First of all why did we installed a old version first to replace it now?

It's easy, we have much less to do. Anyway there is a downside.

When the package is updated in the repository you will probably break your Ice support. But i think thats the best way and you can easily fix that just with replacing the murmurd binary again.

You alread extracted the Static Linux Server to your home directory. Now we need some files from there.

First replace the repository binary with the manually downloaded one.

cd ~/murmur-static_x86-1.1.8
chmod +x ./murmur.x86
cp murmur.x86 /usr/sbin/murmurd

Now copy the Ice specification for murmur.

cp Murmur.ice /var/lib/mumble-server/Murmur.ice


Step 3 - PHP Setup Now we need to tell the PHP-Ice Extension where the Ice specification file can be found. You should already have a file /etc/php5/conf.d/IcePHP.ini from your PHP module install. Open it with a editor.

vim /etc/php5/conf.d/IcePHP.ini

OR

nano -w /etc/php5/conf.d/IcePHP.ini

Paste the folowing in a new line at the end of the file

ice.slice = /var/lib/mumble-server/Murmur.ice

Step 4 - Reload and Check

Everything needed should be done now let us populate your new settings.

Restart your apache2.

/etc/init.d/apache2 restart

And start your Mumble server

/etc/init.d/mumble-server start

Now we will take a look in the mumble-server log to see if everything is fine.

tail -n10 /var/log/mumble-server/mumble-server.log

If you find a line similar to the following

...
<W>2009-04-06 13:37:11.316 MurmurIce: Endpoint "tcp -h 127.0.0.1 -p 6502" running
...

everything is fine and you can now comunicate to Murmur over the IcePHP extension.

Again be aware of that you can break your Ice support when the package gets an update in the repository!

--xenonR 13:02, 06 April 2009 (UTC)

How to setup Ice for PHP with Apache on Windows

These are example scripts. Use at your own risk. These scripts are not intended for production machines. These are examples of what Ice can do. Note that if you already have a web server installed on the server you can adapt this guide to use it instead of installing Apache.

First install Apache. Install it to C:\apache\.

Now install PHP. Tell PHP to install to C:\PHP5\. In the installer on the "Web Server Setup" window select Apache 2.2.x Module. When you get to "Select Apache Configuration Directory" put C:\apache\conf\. Proceed through the installer. Install the defaults, you do not need to install the extensions for PHP.

Now download and install Ice-x.x.x-VC60.msi. Go to C:\Ice-3.3.1-VC60\bin\ and copy

bzip2.dll 
ice33.dll 
iceutil33.dll 
msvcp60.dll 
msvcrt.dll 
php_ice.dll 
slice33.dll 
stlport_vc646.dll 

to C:\apache\bin . Now open C:\PHP5\php.ini and add the following two lines to the bottom of the file:

extension=php_ice.dll
ice.slice=C:\PHP5\Murmur.ice

Now save and exit php.ini.

After you have done all that, download Murmur.ice, icedemo.php, and weblist.php (Click the links, and on the Sourceforge page right click on "(download)" and select "Save Link As...".) Put Murmur.ice in C:\PHP5. Put icedemo.php and weblist.php in C:\apache\htdocs.

Double click the Apache icon in the system tray and select "Restart".

You now need at least one running Murmur server. Go to C:\Program Files\Mumble and double click murmur.exe and the server will start.

You should now be able to go to http://<your IP or Domain>/icedemo.php (or weblist.php). Make SURE that you have icedemo.php protected so that only YOU can access it. If you do not want to use icedemo.php, here is a list of other web interfaces you can use.

Using different ice.slice on same host

Sometimes you run two servers of mumble on the same host and you cannot load two slices with different mumble versions on the same time. The solution is to use ICE profiles, that will require extra files and unfortunately modification of scripts that run the default profile. Description on Debian etch with apache2, PHP as fcgid and cli.

Creating profiles

  • Lets create profile directory (as root/superuser user), I have created mine at
/etc/php5/ice/
  • Then create directories per profile (it will make life easier later)
/etc/php5/ice/murmur.1.1.x
/etc/php5/ice/murmur.1.2.x
  • To each of the corresponding directory I have placed the Murmur.ice file provided with the installs. You will notice that later upgrades will just consit of copying new files (instead of renaming).
  • time to make profiles.ini file that ICE will use:
vi /etc/php5/ice/profiles.ini
  • Insert there below code:
[Murmur11x]
slice=/etc/php5/ice/murmur.1.1.x/Murmur.ice

[Murmur12x]
slice=/etc/php5/ice/murmur.1.2.x/Murmur.ice
  • This way you got two profiles, first (Murmur11x) is loading slice file for older murmur setups, and the other (Murmurm12x) loads newer slices. Below example of directory structure:
/etc/php5/ice
|-- murmur.1.1.x
|   `-- Murmur.ice
|-- murmur.1.2.x
|   `-- Murmur.ice
`-- profiles.ini

IcePHP.ini

  • Now time to alter /etc/php5/cgi/conf.d/IcePHP.ini, so it will look like this
extension = IcePHP.so
ice.profiles=/etc/php5/ice/profiles.ini
  • Notice that we are adding ice.profile setting, so that ice knows where to search for profiles.
  • Default profile is named __default__ and you better avoid to make it.
  • I got no idea about setting up default ice.slice entry (experience told me to force editing php files anyway, read below)

Changing PHP scripts

  • Next alter the source code of the php scripts you use. It consists of just altering the one function that tells ICE to load profile. By default the function is ran without paramter, and it looks like below:
Ice_loadProfile();
  • Now we will tell that function to load specific profile that it was designed for. Below example modifications to load different profiles for given ice profile:

for older mumble:

Ice_loadProfile('Murmur11x'); // load profile for scripts that talk with murmur 1.1.x

or for new mumble:

Ice_loadProfile('Murmur12x'); // load profile for scripts that talk with murmur 1.2.x
  • Notice that single quotes are required.

Checking out if it works

  • Remember to restart apache (your configuration may require it)
  • See php/apache error logs when something goes wrong.
  • If you get erro like unknown operation getUsers invoked on proxy of type ::Murmur::Server then it means you use old Murmur.ice file. This happens whne you try to connect using Murmur.ice from version 1.1.x to Murmur server 1.2.x, which require Murmur.ice 1.2.x. Update Murmur.ice on web server and restart it and then it should work.

Further steps

  • I suggest you do the same with /etc/php5/cli/conf.d file and scripts that you run from console (crontab)
  • Altering php.ini error_reporting is advised to disable generating massive amount of warning messages:
error_reporting = E_ALL & ~E_NOTICE & ~E_WARNING

Developing for the Murmur Ice interface

How to use Ice differs from language to language. The parameters and method names will remain the same, but the syntax will naturally be different. Murmur will, by default, open up an adapter on port 6502 (or 10000 for homedir installs), which has a single accessible object named "Meta". This is the Meta server, and from it you can retrieve adapters for any configured server.

There's an example included in the source; have a look at icedemo.php.

The ice interface is fully documented, and you can browse the generated documentation.

Using Glacier2

Glacier2 is a Ice routing and firewall utility, and allows you to securely run the server on one machine and murmur on another. Note that if both server and client are on a secure LAN, you can just use iptables to protect the Ice port, which is a lot easier than setting up Glacier2.

The examples here assume that 1.2.3.4 is the public IP address of the server running Murmur. We're going to use the username "magic" with the password "pink".

Configuring Glacier2

Create a config file called config.glacier2 and put the following in it:

 Glacier2.Client.Endpoints=tcp -h 1.2.3.4 -p 4063
 Glacier2.SessionTimeout=60
 Glacier2.CryptPasswords=passwords.txt

Your endpoint host should be the public IP that you are running Glacier on. If you don't specify a client via -h, then Glacier will bind to all listening interfaces.

Then, create a password hash using the OpenSSL utility.

 openssl passwd pink

this will spit out a hash, which looks something like CTThafhdv9Lz2

Create a file called passwords.txt containing:

 magic CTThafhdv9Lz2

Start glacier2 as this:

 glacier2router --Ice.Config=config.glacier2

You will need to have Ice installed - http://zeroc.com/download.html glacier2router is a binary that is located in <location_of_Ice_installation>/bin/glacier2router.exe.

Configuring Murmur

There's nothing to do in murmur. Seriously. Leave the default setting of binding to 127.0.0.1 alone.

Configuring Client (PHP)

This is where it starts getting slightly ugly. Note that this requires Ice >= 3.3.1, as Ice 3.3.0 has a bug in it which prevents this from working. The following is the adaptation necessary to weblist.php to get it to work:

try {
  $router = $ICE->stringToProxy("Glacier2/router:tcp -p 4063 -h 1.2.3.4");
  $router = $router->ice_uncheckedCast("::Glacier2::Router")->ice_router(null);
  $session = $router->createSession("magic", "pink");
  $base = $ICE->stringToProxy("Meta:tcp -h 127.0.0.1 -p 6502")->ice_router($router);
  $meta = $base->ice_checkedCast("::Murmur::Meta")->ice_router($router);

  ...

For each object you get a proxy to (including the return from $meta->getServer), you need to add ->ice_router($router)

Configuring Client (Ruby)

There is a set of classes for easily working with Ice directly and through Glacier available at GitHub. However, if you want to do it manually, it's not too hard.

glacierHost = "yourhost.com"
glacierPort = 1234
user = "glacieruser"
pass = "glacierpass"
server_id = 1

prx = ic.stringToProxy("Glacier2/router:tcp -h #{glacierHost} -p #{glacierPort}")
router = ::Glacier2::RouterPrx::uncheckedCast(prx).ice_router(nil)
router.createSession(user, pass)
meta = Murmur::MetaPrx::checkedCast(ic.stringToProxy("Meta:tcp -h #{host} -p #{port}")).ice_router(router)
server = meta.getServer(server_id).ice_router(router)

For each object you get a proxy to (including the return from Murmur::MetaPrx::getServer), you need to add #ice_router(router)

Compiling Ice

On some platforms there are no officially supported binaries available. In that case you will either have to change your platform or compile Ice yourself.

Building Ice on Redhat/CentOS machines

1. Download and unpack ICE

 wget http://www.zeroc.com/download/Ice/3.3/Ice-3.3.1.tar.gz
 tar -xzf Ice-3.3.1.tar.gz

2. Compile the ICE CPP bindings (these are required for all other bindings) You will need mcpp-devel from the Zeroc website installed to compile. http://www.zeroc.com/download.html - Ctrl-F and look for "mcpp-devel". There is a big package of various Ice RPMs to download. You will install a few dependencies, along with the mcpp-devel package.

 cd Ice-3.3.1/cpp
 make

(wait 20 minutes)

 sudo make install

3. Compile and install the Ice bindings for your preferred language. For example, to install Ruby bindings:

 cd ../rb
 make
 sudo make install

4. Export the paths for your newly-installed libraries. These will be different for each language - check the INSTALL or README files in each language's subdirectory for exact instructions.

For Ruby:

 export RUBYLIB=/opt/Ice-3.3.1/ruby:$RUBYLIB
 export LD_LIBRARY_PATH=/opt/Ice-3.3.1/lib:LD_LIBRARY_PATH

If you don't want to always have to keep running those export lines, also add them to your ~/.bashrc:

 export RUBYLIB=/opt/Ice-3.3.1/ruby:$RUBYLIB
 export LD_LIBRARY_PATH=/opt/Ice-3.3.1/lib:LD_LIBRARY_PATH

4. At this point, Ice should be available to your language (in this case, Ruby):

 $ irb
 irb(main):001:0> require 'Ice'
 => true

5. Generate the Slice file for your language.

To generate it for ruby, we use the slice2rb program, which is in the Ice/cpp/bin directory. Similar binaries for your language of choice will be there, too.

 wget -O Murmur.ice "http://mumble.git.sourceforge.net/git/gitweb.cgi?p=mumble/mumble;a=blob_plain;f=src/murmur/Murmur.ice;hb=HEAD"
 ../cpp/bin/slice2rb Murmur.ice
 cp Murmur.rb #{MANAGER_ROOT}/vendor/ice

Congrats! Ice should be set up and fully functional.