Difference between revisions of "Ice"

From Mumble Wiki
Jump to: navigation, search
m (ICE moved to Ice: It's Ice not ICE)
(Section: rework debian 5 server setup)
Line 48: Line 48:
 
The ice interface is fully documented, and you can browse the [http://mumble.sourceforge.net/slice generated documentation].
 
The ice interface is fully documented, and you can browse the [http://mumble.sourceforge.net/slice generated documentation].
  
= How to set up a Debian web server and use the ICE php scripts =
+
= How to set up a Debian web server to work with ZeroC-Ice =
  
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.
+
These are example scripts. Use at your own risk.
  
'''This guide is for debian lenny (upgraded to date 25.10.2008)'''
+
'''This guide is for debian 5.0 (lenny) -upgraded to date 06.04.2009-'''
  
'''1st STEP: DOWNLOAD, UNPACK, SET Static Linux Mumble Server: 1.1.6 (Stable)'''
+
I assume you already have a working apache2 and php environment.
  
download:
 
  
wget http://downloads.sourceforge.net/mumble/murmur-static_x86-1.1.6.tar.bz2
+
'''Prerequisites'''
  
install bzip2:
+
First we need some essentials to aquire these execute the following in a root shell
  
  apt-get install bzip2
+
apt-get update
 +
 +
  apt-get install mumble-server libzeroc-ice32 php-zeroc-ice lzma
  
unpack:
+
These are namely the Mumble server himself (mumble-server), 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.
  
tar -jxvf murmur-static_x86-1.1.6.tar.bz2
+
Additionally we need the current Murmur, thats what the Mumble server is called, release.
  
go to murmur folder:
+
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
  
cd murmur-static_x86-1.1.6
 
  
enable ice (disable dbus):
+
''' Step 1 - Murmur Setup'''
  
nano murmur.ini
+
OPTIONAL: To run Murmur at every startup change the config value in /etc/default/mumble-server acordingly with a editor of your choice.
  
uncomment: #ice="tcp -h 127.0.0.1 -p 6502" >>> ice="tcp -h 127.0.0.1 -p 6502" (dbus=session >>> #dbus=session)
+
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.
  
save it by Ctrl+O
 
close it by Ctrl+X
 
  
make murmur.x86 executable:
+
''' Step 2 - Manual update Murmur '''
  
chmod +x ./murmur.x86
+
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.
  
'''2nd STEP: INSTALL Apache/PHP5 (maybe some steps are not necessary, but I did these)'''
+
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.
copied from: http://www.howtoforge.com/perfect_setup_debian_etch_p6
 
  
1. install Apache:
+
You alread extracted the Static Linux Server to your home directory. Now we need some files from there.
  
  apt-get install apache2 apache2-doc apache2-mpm-prefork apache2-utils libexpat1 ssl-cert
+
First replace the repository binary with the manually downloaded one.
 
+
  cd ~/murmur-static_x86-1.1.8
 
+
chmod +x ./murmur.x86
2. install PHP5:
+
cp murmur.x86 /usr/sbin/murmurd
 
+
Now copy the Ice specification for murmur.
You will be asked the following question:
+
  cp Murmur.ice /var/lib/mumble-server/Murmur.ice
 
 
Continue installing libc-client without Maildir support? <-- Yes
 
 
 
  apt-get install libapache2-mod-php5 php5 php5-common php5-curl php5-dev php5-gd php5-idn php-pear php5-imagick php5-imap php5-json php5-mcrypt php5-memcache php5-mhash php5-ming php5-mysql php5-ps php5-pspell php5-recode php5-snmp php5-sqlite php5-tidy php5-xmlrpc php5-xsl
 
  
Next we edit /etc/apache2/mods-available/dir.conf:
 
  
  nano /etc/apache2/mods-available/dir.conf
+
''' 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
 +
  
and change the DirectoryIndex line:
+
''' Step 4 - Relaod and Check '''
  
<IfModule mod_dir.c>
+
Everything needed should be done now let us populate your new settings.
DirectoryIndex index.html index.htm index.shtml index.cgi index.php index.php3 index.pl index.xhtml
 
</IfModule>
 
 
 
Edit /etc/apache2/ports.conf and add Listen 443:
 
 
 
nano /etc/apache2/ports.conf
 
 
 
 
 
Listen 80
 
Listen 443
 
 
 
Now we have to enable some Apache modules (SSL, rewrite, suexec, and include):
 
 
 
a2enmod ssl
 
a2enmod rewrite
 
a2enmod suexec
 
a2enmod include
 
 
 
Reload the Apache configuration:
 
 
 
/etc/init.d/apache2 force-reload
 
 
 
 
 
'''3rd STEP: INSTALL ZeroC ICE'''
 
 
 
apt-get install zeroc-ice
 
 
 
You will be asked to install zeroc-ice32 <-- Yes
 
 
 
(It should install php-zeroc-ice too)
 
 
 
Edit php.ini file:
 
 
 
nano /etc/php5/apache2/php.ini
 
 
 
add somewhere: ice.slice = /path/to/Murmur.ice
 
 
 
Restart Apache:
 
  
 +
Restart your apache2.
 
  /etc/init.d/apache2 restart
 
  /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.
  
'''4th STEP: COPY php files to DocumentRoot of webserver (default: /var/www)'''
+
''' Again be aware of that you can break your Ice support when the package gets an update in the repository! '''
 
 
copy "icedemo.php" and "weblist.php" from murmur folder to /var/www
 
 
 
 
 
'''5th STEP: Start murmur'''
 
 
 
run server from murmur folder:
 
 
 
./murmur.x86
 
  
--[[User:reDnout|reDnout]] 22:37, 25 October 2008 (UTC)
+
--[[User:xenonR|xenonR]] 13:02, 06 April 2009 (UTC)
  
 
= How to set up a Windows web server and use the ICE php scripts =
 
= How to set up a Windows web server and use the ICE php scripts =

Revision as of 12:04, 6 April 2009

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.

Getting ready to use ICE

You can download ICE directly from ZeroC. If you installed a binary version of Murmur, it already includes the necessary components for running ICE, but you might need additional tools to develop with it.

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

Apache and PHP

If you want to use ICE from PHP, you'll have to 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, or php_ice.dll for windows 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.

Using ICE

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.

How to set up a Debian web server to work with ZeroC-Ice

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 libzeroc-ice32 php-zeroc-ice lzma

These are namely the Mumble server himself (mumble-server), 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 - Relaod 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 set up a Windows web server and use the ICE php scripts

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.

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 install ICE. Go to C:\Ice-3.3.0-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).

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

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 password.txt containing:

 magic CTThafhdv9Lz2

Start glacier2 as this:

 glacier2router --Ice.Config=config.glacier2

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)