AMule Project FAQ - User contributions [en]

AMuleWeb PHP

2006-10-17T19:53:32Z

87.69.41.166:

<h1>aMuleWeb PHP manual</h1> ''by Froenchenko Leonid lfroen@gmail.com [[User:Lfroen|Lfroen]]''

<font color=red>This page is in unfinished state. Information may be missing, inaccurate, misspelled or all of them</font>

=== Introduction ===

[[aMuleWeb]] is an add-on program, used together with [[aMule]] and serves as webserver, allowing user to control aMule through browser interface. aMuleWeb works very similar to regular and wide-known webservers such as Apache[http://www.apache.org] - set of HTML pages stored on server side (called "template"). Those pages contains embedded server-side script, which is running when user requests the page. Resulting page is returned to user.

The scripting language, [[aMuleWeb]] using is very similar to widely known "PHP", developed and distributed by Zend company [http://www.zend.com]. Since aMuleWeb implementation is differ from original PHP, I will call it "aMuleWeb PHP" for reader convenience. "The PHP" language, will be referred as "real PHP" or just "PHP" to make difference between the two.

=== Conventions ===
Language elements, reserved words are marked bold: '''keyword'''. Things that are not part of syntax, but are reserved or predefined marked bold italic: '''''special_var''. Languge limitations marked like:
*Making cofee not supported

=== Interaction with PHP and webserver ===
Similarly to real PHP, script is embedded into regular HTML pages using <?php ?> marks. Page must have .php extension in order to be searched for script. Note, that markups can not be nested, i.e. placing <html> marks inside of <?php ?> will result in syntax error.

=== Core language constructs ===
aMuleWeb PHP have same basic language elements as real PHP version 5. Several things supported or implemented differently:
OO constructs (classes) may pass syntax check, but they are not supported in any way.
'''include''' construct is parse-time directive (in contrary to PHP, where you can do it in run-time and check result of "include" operation)
There's no '''list''' at all.

==== Variables ====
There's scalar (referred as $var) and array (referred as @var) variables. Similarly to real PHP all variables are local, unless defined otherwise.
Variables, marked as '''global''' must be declated ''before'' this definition. Example:

$a = 1;

function foo()
{
global $a;
}

References to variable and to array members are fully supported:
$a = &$b;
$c = &$c[5];

*Reference of variable by name like $$var is not supported.
*Integer variables are 64-bit unsigned integers
*Variable substitution inside of "" is not supported.

==== Operators ====
All PHP operators supported. Implicit type conversion is supported too, as common in scripting languages. This way 1 + "2" = 3.
*Prefix and postfix ++ and -- are not distinguished (prefix form used)
*Using operator + for array mean "join" in real PHP. Here array is interpreted as integer equal to number of elements.

==== Subroutines ====
'''function''' construct is fully supported. In contrary to regular PHP function must be defined prior calling. It is error to do otherwise. Functions can be recursive, thou.
Real PHP allows to omit parameters for function calls (default parameters). aMuleWeb PHP does not support this conventions, which mean that all parameters must be present when function is called. This is not an error, and parameters will receive predefined values when omit: 0 for numbers, "" (empty string) for strings.
Parameters can be references or arrays with usual meaning.
*Function can not return reference.

=== Library ===
PHP language is known to have huge library of useful subroutines. Those subroutines are used to perform various tasks, varying from simple string manipulation to complex databases and OS binding. aMuleWeb PHP on the other hand, have very limited library.
There's several reasons behind this fact. First of all, it is out of question to completely re-create PHP library, given it's size and complexity. Second, and most important, it's not really needed. aMuleWeb PHP is built to serve very specific application, and used to create very specific kind of pages. It will not be used to create e-commerce site or webmail. List below summarize supported functions:

*var_dump($var): [http://www.zend.com/manual/function.var-dump.php var_dump()]
*strlen($string):[http://www.zend.com/manual/function.strlen.php strlen()]
*usort($var): [http://www.zend.com/manual/function.usort.php usort()]
*isset($var): [http://www.zend.com/manual/function.isset.php isset()]

==== Predefined global variables ====
Similarly to real PHP, there's set of special, or predefined variables, which have special meaning. Those variables may indicate input received from user, or they may control script execution. Those variables have same name as in real PHP, but functionality may be limited.

'''''$_SESSION''''': Hash of values that survive between engine invocation per session. Some of it's values are predefined by webserver itself.
$_SESSION["guest_login"]: set when password supplied belongs to low-right user
$_SESSION["login_error"]: set when bad password supplied.
$_SESSION["auto_refresh"]: always set; indicate time to autorefresh (in seconds). Can be used in http-equiv:
<?php
if ( $_SESSION["auto_refresh"] > 0 ) {
echo "<meta http-equiv=\"refresh\" content=\"", $_SESSION["auto_refresh"], '">';
}
?>

'''''$HTTP_GET_VARS''''': Hash of values passed from browser on GET or POST method.

=== aMule binding ===
The whole purpose of [[aMuleWeb]] control [[aMule]]. aMuleWeb PHP provide library functions for convinient access to underlying aMule datastructure for both queries and actions.

'''''amule_load_vars''''': Query [[aMule]] datastructure. Result is returned as array of hashes, where each hash represent item in [[aMule]] datastructure (upload, download, client, item in search result). Following are possible category names:
# 'downloads'
# 'uploads'
# 'searchresult'
# 'shared'
# 'servers'
# 'stats_graph'
# 'stats_tree'

$var = amule_load_vars($name_of_variable)
foreach ($var as $i) {
}

'''''amule_get_categories'''': return list of valid categories
$cat_list = amule_get_categories();

'''''amule_get_options'''': return options and their values. Options are returned in form of hash, where keys are categories and values are hashes of name-value for each option.
'''''amule_set_options($opt_values_hash)'''': set [[aMule]] options. Receives hash in form returned by '''''amule_get_options''''

'''''amule_do_server_cmd'''':
'''''amule_do_add_server_cmd'''':
'''''amule_do_download_cmd'''':
'''''amule_do_shared_cmd'''':
'''''amule_do_reload_shared_cmd'''':
'''''amule_do_search_download_cmd'''':
'''''amule_do_search_start_cmd'''':
'''''amule_do_ed2k_download_cmd'''':
'''''amule_get_log'''': query log from [[aMule]]
$log = amule_get_log();
echo "My log:", $log;
'''''amule_get_serverinfo'''':

=== Authentication ===
Real PHP have wide range of authentication and session management possibilities. In aMuleWeb PHP, status is different. Both authentication and session management are not part of scripting language. Instead, they are implemented as part of in webserver itself, and running invisibly for script engine.

=== Errors and debugging ===
As in any other language, aMuleWeb PHP have 3 types of errors: compile-time, run-time and logic errors. All error messages produced by engine are printed to terminal. This effectively means, that [[aMuleWeb]] should be started manually from terminal (and not automatically by [[aMule]]) in order to see those messages. Alghouth engine perform some effort to recover from syntax errors, it's known to crash in some corner-cases. Beware.
*Compile-time errors means error in script syntax as misspelled names, missing ";" or mismatched (). In this case, error message from parser is printed and execution is not performed.
*Run-time errors like division by zero, incorrect or missing parameters etc. When encountered, appropriate message is printed, and execution aborted in point of problem.
*Logic errors: everything is OK, but result is different from expected. Since aMuleWeb PHP offers no debugger, the only way to trace program is to add '''var_dump()''' in suspicious places;

It is possible to compile aMuleWeb PHP engine standalone. This compilation mode is used to debug '''engine itself'''. Since aMule binding is not possible in this case, it have little use for template debugging.

AMuleWeb PHP

2006-10-17T19:53:07Z

87.69.41.166:

<h1>aMuleWeb PHP manual</h1> ''by Froenchenko Leonid lfroen@gmail.com [[User:Lfroen|Lfroen]]''

<font color=red>This page is in unfinished state. Information may be missing, inaccurate, missmelled or all of them</font>

=== Introduction ===

[[aMuleWeb]] is an add-on program, used together with [[aMule]] and serves as webserver, allowing user to control aMule through browser interface. aMuleWeb works very similar to regular and wide-known webservers such as Apache[http://www.apache.org] - set of HTML pages stored on server side (called "template"). Those pages contains embedded server-side script, which is running when user requests the page. Resulting page is returned to user.

The scripting language, [[aMuleWeb]] using is very similar to widely known "PHP", developed and distributed by Zend company [http://www.zend.com]. Since aMuleWeb implementation is differ from original PHP, I will call it "aMuleWeb PHP" for reader convenience. "The PHP" language, will be referred as "real PHP" or just "PHP" to make difference between the two.

=== Conventions ===
Language elements, reserved words are marked bold: '''keyword'''. Things that are not part of syntax, but are reserved or predefined marked bold italic: '''''special_var''. Languge limitations marked like:
*Making cofee not supported

=== Interaction with PHP and webserver ===
Similarly to real PHP, script is embedded into regular HTML pages using <?php ?> marks. Page must have .php extension in order to be searched for script. Note, that markups can not be nested, i.e. placing <html> marks inside of <?php ?> will result in syntax error.

=== Core language constructs ===
aMuleWeb PHP have same basic language elements as real PHP version 5. Several things supported or implemented differently:
OO constructs (classes) may pass syntax check, but they are not supported in any way.
'''include''' construct is parse-time directive (in contrary to PHP, where you can do it in run-time and check result of "include" operation)
There's no '''list''' at all.

==== Variables ====
There's scalar (referred as $var) and array (referred as @var) variables. Similarly to real PHP all variables are local, unless defined otherwise.
Variables, marked as '''global''' must be declated ''before'' this definition. Example:

$a = 1;

function foo()
{
global $a;
}

References to variable and to array members are fully supported:
$a = &$b;
$c = &$c[5];

*Reference of variable by name like $$var is not supported.
*Integer variables are 64-bit unsigned integers
*Variable substitution inside of "" is not supported.

==== Operators ====
All PHP operators supported. Implicit type conversion is supported too, as common in scripting languages. This way 1 + "2" = 3.
*Prefix and postfix ++ and -- are not distinguished (prefix form used)
*Using operator + for array mean "join" in real PHP. Here array is interpreted as integer equal to number of elements.

==== Subroutines ====
'''function''' construct is fully supported. In contrary to regular PHP function must be defined prior calling. It is error to do otherwise. Functions can be recursive, thou.
Real PHP allows to omit parameters for function calls (default parameters). aMuleWeb PHP does not support this conventions, which mean that all parameters must be present when function is called. This is not an error, and parameters will receive predefined values when omit: 0 for numbers, "" (empty string) for strings.
Parameters can be references or arrays with usual meaning.
*Function can not return reference.

=== Library ===
PHP language is known to have huge library of useful subroutines. Those subroutines are used to perform various tasks, varying from simple string manipulation to complex databases and OS binding. aMuleWeb PHP on the other hand, have very limited library.
There's several reasons behind this fact. First of all, it is out of question to completely re-create PHP library, given it's size and complexity. Second, and most important, it's not really needed. aMuleWeb PHP is built to serve very specific application, and used to create very specific kind of pages. It will not be used to create e-commerce site or webmail. List below summarize supported functions:

*var_dump($var): [http://www.zend.com/manual/function.var-dump.php var_dump()]
*strlen($string):[http://www.zend.com/manual/function.strlen.php strlen()]
*usort($var): [http://www.zend.com/manual/function.usort.php usort()]
*isset($var): [http://www.zend.com/manual/function.isset.php isset()]

==== Predefined global variables ====
Similarly to real PHP, there's set of special, or predefined variables, which have special meaning. Those variables may indicate input received from user, or they may control script execution. Those variables have same name as in real PHP, but functionality may be limited.

'''''$_SESSION''''': Hash of values that survive between engine invocation per session. Some of it's values are predefined by webserver itself.
$_SESSION["guest_login"]: set when password supplied belongs to low-right user
$_SESSION["login_error"]: set when bad password supplied.
$_SESSION["auto_refresh"]: always set; indicate time to autorefresh (in seconds). Can be used in http-equiv:
<?php
if ( $_SESSION["auto_refresh"] > 0 ) {
echo "<meta http-equiv=\"refresh\" content=\"", $_SESSION["auto_refresh"], '">';
}
?>

'''''$HTTP_GET_VARS''''': Hash of values passed from browser on GET or POST method.

=== aMule binding ===
The whole purpose of [[aMuleWeb]] control [[aMule]]. aMuleWeb PHP provide library functions for convinient access to underlying aMule datastructure for both queries and actions.

'''''amule_load_vars''''': Query [[aMule]] datastructure. Result is returned as array of hashes, where each hash represent item in [[aMule]] datastructure (upload, download, client, item in search result). Following are possible category names:
# 'downloads'
# 'uploads'
# 'searchresult'
# 'shared'
# 'servers'
# 'stats_graph'
# 'stats_tree'

$var = amule_load_vars($name_of_variable)
foreach ($var as $i) {
}

'''''amule_get_categories'''': return list of valid categories
$cat_list = amule_get_categories();

'''''amule_get_options'''': return options and their values. Options are returned in form of hash, where keys are categories and values are hashes of name-value for each option.
'''''amule_set_options($opt_values_hash)'''': set [[aMule]] options. Receives hash in form returned by '''''amule_get_options''''

'''''amule_do_server_cmd'''':
'''''amule_do_add_server_cmd'''':
'''''amule_do_download_cmd'''':
'''''amule_do_shared_cmd'''':
'''''amule_do_reload_shared_cmd'''':
'''''amule_do_search_download_cmd'''':
'''''amule_do_search_start_cmd'''':
'''''amule_do_ed2k_download_cmd'''':
'''''amule_get_log'''': query log from [[aMule]]
$log = amule_get_log();
echo "My log:", $log;
'''''amule_get_serverinfo'''':

=== Authentication ===
Real PHP have wide range of authentication and session management possibilities. In aMuleWeb PHP, status is different. Both authentication and session management are not part of scripting language. Instead, they are implemented as part of in webserver itself, and running invisibly for script engine.

=== Errors and debugging ===
As in any other language, aMuleWeb PHP have 3 types of errors: compile-time, run-time and logic errors. All error messages produced by engine are printed to terminal. This effectively means, that [[aMuleWeb]] should be started manually from terminal (and not automatically by [[aMule]]) in order to see those messages. Alghouth engine perform some effort to recover from syntax errors, it's known to crash in some corner-cases. Beware.
*Compile-time errors means error in script syntax as misspelled names, missing ";" or mismatched (). In this case, error message from parser is printed and execution is not performed.
*Run-time errors like division by zero, incorrect or missing parameters etc. When encountered, appropriate message is printed, and execution aborted in point of problem.
*Logic errors: everything is OK, but result is different from expected. Since aMuleWeb PHP offers no debugger, the only way to trace program is to add '''var_dump()''' in suspicious places;

It is possible to compile aMuleWeb PHP engine standalone. This compilation mode is used to debug '''engine itself'''. Since aMule binding is not possible in this case, it have little use for template debugging.

AMuleWeb

2006-10-17T19:52:30Z

87.69.41.166:

== Description ==

aMuleWeb is a utility that listens for [http://www.w3.org/MarkUp HTTP] connections at port 4711 (by default, although it can be changed through '''Preferences''') and allows remote users to control [[aMule]] using just a web browser.

[[aMule]] itself doesn't support listening to [http://www.w3.org/MarkUp HTTP] connections, so the external utility aMuleWeb is used. This utility listens for remote connections, and once the link between aMuleWeb and the remote user is established, it connects to the [[aMule]] main program using the [[External Connections]] mechanism.

== Compiling aMuleWeb ==

[[Compile]] [[aMule]] normally, just add ''--enable-amuleweb'' when running ''configure''.

== Setting up aMuleWeb with [[aMule]] ==

=== aMuleWeb with [[aMule]] 2.0.0 or later ===

*For users running the monotlithic [[aMule]] application:
**Go to "Preferences"->"Remote Controls" (in [[aMule]]) and...
***Enable "Accept External Connections".
***Enable "Use TCP ports instead of unix local sockets" (This option doesn't exist since version 2.1.0)
***Enter a password for [[External Connections]]. If you don't do this, aMuleWeb will not communicate with [[aMule]].
::'''NOTE:''' When you change your aMuleWeb and [[External Connections]] ports here, make sure to restart [[aMule]].

*For users running the [[aMule|aMule daemon]]:
**Shutdown [[aMule|aMuled]] if it is still running.
**Run ''amuleweb -w'' to generate ''~/.aMule/remote.conf'' and edit it for these options. It previously were on ''~/.aMule/amule.conf'', but the lines are still on this file, so edit both if in doubt.
***''[ExternalConnect]'' <- Section header
***''AcceptExternalConnections=1'' <-- To enable [[aMule]] listening for [[External Connections]].
***''ECUseTCPPort=1'' <-- To use the [http://www.faqs.org/faqs/internet/tcp-ip/resource-list TCP] port. Very important since [http://www.unix.org Unix] sockets are disabled.
***''ECPassword=ca3c365274907c6fd527068788e14639'' <-- To find the MD5 string for your password, do:
:::''$ echo -n yourpasswordhere | md5sum | cut -d ' ' -f 1''
:::''ca3c365274907c6fd527068788e14639''
**If you get ''FATAL ERROR: Cannot find template: default'' it's because you didn't run ''make install''. If you don't want to install aMule, copy the ''src/webserver/default/'' directory into ''~/.aMule/webserver/'' (create it if needed). If you want any other template (probably ''php-default''), copy it too. Then go back to the previous step.
**Restart [[aMule|aMule]]

'''NOTE:''' Every password must be md5sum,also webserver one/s. aMule embedded webserver works without remote.conf,you just need to edit ''amule.conf''. A good trick if you have somewhere an X server is to configure amule using the GUI and then copy the ''amule.conf'' configuration file where you want to run the daemon.

Thanks to [[User:Stefanero|Stefanero]], from who I shamelessly stole a lot from his tutorial.

'''NOTE:''' aMuleWeb uses cookies to hold session id. Make sure that cookies are enabled in your browser.

=== aMuleWeb with [[aMule]] pre-2.0.0 final ===

Please check [[Webserver-old|this page]] for archived instructions (educational purposes!).

== Running aMuleWeb ==
There's 2 options for activating aMuleWeb.
*First, and preffered, is to enable aMuleWeb activation on aMule preferences. This option works for amuled as well. When started, aMule will attempt to execute '''amuleweb''' command, asuming it's in the search path. Upon exit, aMuleWeb will be automatically terminated.
*Second options is to run aMuleWeb manually, using '''''amuleweb''''' command on a terminal.

Once aMuleWeb is running, open a web browser and connect to:

''http://host:port''

where ''host'' stands for your host's name (try with ''localhost'') and port stands for the aMuleWeb port ('''NOT''' the [[External Connections]] port).

For example: ''http://localhost:4711''

''Shakraw''

== Standard ports ==

The ports can be set to anything, but this are the most used (the standard ones):

*[[External Connections]]: 4712
*amuleweb: 4711

Make sure you do not confuse with what each of them is.

== Template (skin) location ==

aMuleWeb looks for its files in a number of places:
*In your home directory: ''$HOME/.aMule/webserver/''[skin name]''/''
*And at it's install location, in this order (by default, ''/usr/local/share/amule/webserver'' if you compiled [[aMule]], or ''/usr/share/amule/webserver'' if you installed it from a package).

Default template name is 'default'.

If, '''after installing''' [[aMule]], aMuleWeb refuses to run because of not being able to load template:
*Please report this situation to us, and then
*Create the directories ''webserver/default'' in the ''.aMule'' subdirectory of your home directory, and copy the contents of the ''src/webserver'' directory there from the [[aMule]] tarball (I mean to ''$HOME/.aMule/webserver/default'').

'''[[User:GonoszTopi|GonoszTopi]]'''

== How to start [[aMuled|aMule Daemon]] and aMuleWeb with your computer ==

The best way to start both the processes aMule Daemon and aMuleWeb with your server is to add a shell script ''/etc/init.d/amule'' like this:

PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
DAEMON=/usr/bin/amuled
WEB=/usr/bin/amuleweb
NAME=amuled
DESC=amuled
RUNAMULE=no
USER=youramuleuser

test -x $DAEMON || exit 0

# Include amule defaults if available
if [ -f /etc/default/amule ] ; then
. /etc/default/amule
fi

if [ "$RUNAMULE" != "yes" ];then
echo "Amule not to be started. Edit /etc/default/amule first."
exit 1
fi

set -e

case "$1" in
start)
echo -n "Starting $DESC: "
su $USER -c "$DAEMON -f"
sleep 20
su $USER -c "$WEB --quiet &"
echo "$NAME."
;;
stop)
echo -n "Stopping $DESC: "
killall --quiet --ignore-case $WEB
killall --quiet --ignore-case $DAEMON
echo "$NAME."
;;
restart|force-reload)
echo -n "Restarting $DESC: "
killall --quiet --ignore-case $WEB
killall --quiet --ignore-case $DAEMON
sleep 1
su $USER -c "$DAEMON -f"
sleep 20
su $USER -c "$WEB --quiet &"
echo "$NAME."
;;
*)
N=/etc/init.d/$NAME
echo "Usage: $N {start|stop|restart|force-reload}" >&2
exit 1
;;
esac

exit 0

Then just set that script to be run at start up. On [[Debian]] this would be doen with the following command:

update-rc.d amule defaults

Then, for the deamons to start you just have to create a file ''/etc/default/amule'' which contains a single line:

RUNAMULE=yes

That's it!

== Template language and development ==
Simply put, aMuleWeb templates are ordinary HTML files. In order to make them "interactive", server-side language is embedded inside. This language is scaled down dialect of PHP. More detailed information can be found on [[aMuleWeb_PHP]].

== Where to report problems and questions? ==

For Problems or Questions just report on http://forum.amule.org forum or join [[IRC]] channel [irc://irc.freenode.net/amule #amule] at [irc://irc.freenode.net irc.freenode.net]

== Other sources of information ==

Read the aMuleWeb man page, which is available in English, French, German, Hungarian and Spanish.

For further information read the [[FAQ_webserver|aMuleWeb FAQ]].