Frequently Asked Questions
From Aquila Homepage
Basic Functions
How do I set a MOTD?
First create a file with the desired MOTD, I will call it motd.txt. Place the file into the configuration directory. Then we create the trigger that will contain the text:
!triggeradd motd file motd.txt
Then we tell the hub that we want to show that on login to all users:
!ruleadd motd login "Show this to all users on login"
If we want we can also add a command to the hub to show the motd on request:
!ruleadd motd command motd "This shows the message of the day"
If you did this correctly, the command !rulelist should return the following output:
Trigger motd dumps file motd.txt (Hits 0) Rule 0 type login, cap None Rule 1 type command motd, cap None
The hub will regularly check if the file has been updated. If it has, it will reload the contents.
How do I minimize bandwidth usage of the hub?
First of all, don't expect miracles, Aquila will not allow you to host 10000 users on 256kbit. Never. Aquila aims to supply the best possible service to as much users as possible. It will not sacrifice functionality to host more users. That said, Aquila does allow you to customize the service you wish to offer.
First of all, you can reduce bandwidth by limiting the information send to users about other users. You can do this with the tag settings:
tag.maxdesclength tag.maxemaillength
These can all be set to 0 without affecting how your hub works.
The following settings can also be set to 0 but this will obviously affect functionality:
tag.maxsharelength tag.maxspeedlength
I advise against it.
You can also filter out the tag. If you do, you must set the tag.dropontagtoolong setting to 0 or you will kick all your users. This might also affect OP clients that check all users on join.
tag.maxtaglength tag.dropontagtoolong
All these settings do NOT affect OPs. OPs get the full MyINFO of each user when the user joins. However, they do get the cleaned versions when the OPs themselves join.
The other means of saving bandwidth are through the rate settings:
rate.myinfo This controls the rate at which users can send MyINFO updates. rate.activesearch This controls the rate at which active users can search the hub. rate.passivesearch This controls the rate at which passive users can search the hub. rate.results_in This controls the rate at which a user can receive passive search results. Keep this period identical to your passive search period. rate.results_out This controls the rate at which a user can send passive search results.
By default these are at normal values. Some hub owners choose to severly limit their passive users. You can limit how many passive search results a user can receive. If you set this, make sure rate.passivesearch.period is identical to rate.results_in.period. Then you can tightly control how many results a user can get per search. You can limit rate.results_out too, but is of less importance: the setting does not affect outgoing bandwidth.
What is RSS and how do I use it?
RSS is a way for a website to publish site updates. For example, Slashdot uses RSS to publish a list of all their latest articles (Slashdot RSS).
Aquila is able to check the RSS feeds for updates and post these updates to user-specified target. For example for slashdot you would use:
!rssadd slashdot 300 http://rss.slashdot.org/Slashdot/slashdot
This command would create a feed called slashdot with an update period of 300 seconds (5min). The command would result in the following output:
<Wintermute> Feed information slashdot Title: Slashdot Link: http://slashdot.org/ Description: News for nerds, stuff that matters Example node: title: Seeing Color in the Night link: http://rss.slashdot.org/~r/Slashdot/slashdot/~3/104522667/article.pl description: Roland Piquepaille writes "In 'Things that show color in the night,' the Boston Globe reports that a company named Tenebraex is helping color blind people to travel. But it's also developing goggles to help soldiers and physicians to see all colors at night, and not only the green color of current night vision systems. These goggles, which should become available this summer, will be sold for about $6,000 to the Army. But as states one of the founders of the company, with monochrome night vision, 'blood is the same color as water.' So these expensive night vision devices might be more targeted to Army physicians than to regular soldiers." <p><a href="http://rss.slashdot.org/~a/Slashdot/slashdot?a=8A8bQ1"><img src=" border="0"></img></a></p><img src=" height="1" width="1"/> dc:creator: ScuttleMonkey dc:date: 2007-03-26T18:17:00+00:00 dc:subject: technology slash:department: less-green-for-more-green slash:section: hardware slash:comments: 28 slash:hit_parade: 28,27,17,11,4,0,0 feedburner:origLink: http://hardware.slashdot.org/article.pl?sid=07/03/26/1735238&from=rss
Offcourse, the exact output depends on which site you use and when you execute the command.
Now we can use this information to choose which of the node elements we wish to display to our users. In this case, we can choose from: title, link, description, dc:creator, dc:date, dc:subject, slash:department, slash:section, slash:comments, slash:hit_parade, feedburner:origLink. That is quite a lot of information and it makes our display look messy, so we decide to select only a few important fields. We do this with the rssselect command:
!rssselect slashdot title,link,dc:date
Resulting in:
<Wintermute> Adding title Adding link Adding dc:date Updating feed now...
If we now display the feed we get:
!rss slashdot <Wintermute> Slashdot - News for nerds, stuff that matters RIAA Says Accused Students Are Settling http://rss.slashdot.org/~r/Slashdot/slashdot/~3/104378558/article.pl 2007-03-26T01:34:00+00:00 MS Trying To Spur Vista Sales With Discounts http://rss.slashdot.org/~r/Slashdot/slashdot/~3/104389612/article.pl 2007-03-26T02:54:00+00:00 How Small a PC Is Too Small? http://rss.slashdot.org/~r/Slashdot/slashdot/~3/104405429/article.pl 2007-03-26T05:15:00+00:00 ...
Another important factor in feed display is the the rss.maxlength settings which limits the maximum length a single element can be. Elements that are truncated have three dots appended:
Example:
Diebold Sues Massachusetts for "Wrongful Purchase" elBart0 writes "Diebold has decided to sue the commonwealth of Massachusetts for choosing a competitor to provide voting machines for the disabled. Diebold wants to force the state to stop using the machines immediately, despite the upcoming municipal elec... http://rss.slashdot.org/~r/Slashdot/slashdot/~3/104510507/article.pl
Now, the second RSS configuration command is rsstarget. We can use this command to select where the output of the RSS feed goes. By default it goes to main chat, but with this command we can send the output to a user, a chatroom or a user with a certain collection of rights.
<Wintermute> Usage: rsstarget <feed> user <target> | rights <rights> | main user <target>: send feed output to user right <rights>: send feed output to all user with <rights>
For example, the following command would send the output of the RSS feed to the #OpChat chatroom.
!rsstarget slashdot user #OpChat
If you wish to see which feeds are configured on your hub, use rsslist:
!rsslist <Wintermute> Feed: fark (Updated 00:01:00) Fark.com - It's not news, it's Fark. Target rights: fark Link: http://www.fark.com/fark.rss Last modified: Mon, 26 Mar 2007 19:10:19 GMT Next update: 00:00:09 Includes: title link Feed: slashdot (Updated 00:02:00) Slashdot - News for nerds, stuff that matters Target rights: slashdot Link: http://rss.slashdot.org/Slashdot/slashdot Last modified: Mon, 26 Mar 2007 19:03:40 GMT Next update: 00:00:45 Includes: title description link
To see the contents of the feeds, use rss.
!rss
<Wintermute> Usage: rss <feed>
Available feeds:
fark (Fark.com - It's not news, it's Fark.)
slashdot (Slashdot - News for nerds, stuff that matters)
As a last configuration element, rss.silent will allow you to discard feed update errors.
On the forum there is a feeds.lua LUA script that will allow you to create feeds to which users can subscribe if they wish.
If you want to create your own RSS feeds, you can find a lot of software online. Many content management systems (website software) include a RSS support. Examples are Joomla! and Mambo. If you do not use any of those packages, I have no doubt you can find some standalone packages that can provide you with RSS functionality.
Advanced features
What exactly do the --enable-testcoverage and --enable-useprofile options do?
These options allow you to build a highly optimized binary for your hub. It does require some work and time though. First, configure and build the hub with --enable-testcoverage
./configure --enable-testcoverage make
Do NOT install this build.
Copy the configuration files from your normal configuration dir into the src directory of the distribution. Run the hub from there.
cp /path/to/configfir/*.conf src/ cd src ./aquila
Note: You might need to disable daemontools.
svc -d /service/aquila/
Let the hub run under normal load for a few days. Then use !shutdown to stop the hub. Copy back your config files and start the hub as you always do:
cd /path/to/aquila-src/src cp *.conf /path/to/configfir/
Note: If you run daemontools:
svc -u /service/aquila/
The hub should now have generated profiler information files. Go back to the root of the aquila distribution and reconfigure with --enable-useprofile
cd /path/to/aquila-src/src ./configure --enable-useprofile rm src/*.o src/aquila make install
Your new and improved, highly optimized aquila should now be installed. Some important points:
- You MUST run the hub from the source directory so it generates the appropriate files there.
- The longer you run the hub with --enable-testcoverage, the better the optimization will be.
- This is an ADVANCED feature. If this is not enough for you to succesfully build an optimized version, do NOT come and ask me for help.
How do I add a language to the hub?
To add support for you language, download a version that supports i18n and install it. Then go the po directory and create a new (empty) po file for your language:
cd po msginit --locale=<language and country code>
Replace <language and country code> by the language and country code in the form lc_CC. (For example Dutch = nl_NL, US English = en_US, Hungarian = hu_HU, ...). Now edit that file using any text editor. You can find the valid language and country codes in the Appendix A and B of the Gettext manual.
IMPORTANT: make sure that all words starting with % are not changed and stay in the same order. If you really have to change them, be sure you know what you are doing! You can find some relevant information here .
To test you translation, add your language code to the LINGUAS file and do:
make update-po make install
To prevent problems with character set conversions, I would advise you to use the windows-1252 character set whenever possible.
Troubleshooting
The hub doesn't support more than 1024 users! How can I remove this limit?
This isn't hard. Just do
ulimit -n 10240
if you want to allow 10240 users.
You must repeat this every time you start the hub and it will only work for the current shell! It might be useful to create a small script to start the hub.
The hub doesn't have lua support! It doesn't know !luaload!
You need to install lua on your system and make sure the configure script detects it correctly. The exact commands depend on your linux distribution.
Gentoo
Install lua with:
emerge -a \=lua-5.0.2
Then just build the hub with
./configure make install
Lua should work now.
Debian / Ubuntu
First do:
apt-get install liblua50 liblua50-dev liblualib50 liblualib50-dev
To install lua. Then configure the hubsoft with:
./configure --with-lua-includes=/usr/include/lua50/ --with-lua-libraries=/usr/lib/ --with-lua-suffix=50
I get Permission denied errors when saving my configuration.
Go to your hubs configuration directory and make very sure that the user aquila is running as has write permissions to the configuration files. The best way is to make sure the config files are owned by that user.
The following assumes you followed my recommendations and created a user and group called aquila for the hub. You must run these commands as root.
chown aquila:aquila *.conf chmod u+rw,o-rw *.conf
Can I turn off "WARNING: Your client uses IP **.***.***.**, while you have IP 192.168.*.*" ?
Yes, assign yourself the locallan right.
!userrights <your nick> +locallan
Only unregistered users and OPs can join my hub, but registered users are refused because the hub is full!
Change your configuration of userlimit.registered and userlimit.op. They should not be identical or too close together. userlimit.op specifies the number of users from userlimit.registered that are reserved for OPs!
Daemontools acts weird. The hub doesn't restart and it gives all kinds of errors.
Clean your configuration directory. For recent (0.1.9) aqdtinstall scripts, this is /home/aquila/service, for older that is just /home/aquila/
It should contain nothing that isn't absolutely necessary. It cannot contain ANY executable files except the run scripts. It should look a bit like:
total 60 4 drwxr-xr-x 5 root root 4096 Oct 8 18:21 . 4 drwxr-xr-x 4 root root 4096 Dec 21 2005 .. 4 -rw-r--r-- 1 aquila aquila 1929 Oct 8 18:18 accounts.conf 4 -rw-r----- 1 aquila aquila 6 Oct 5 23:26 aquila.pid 4 -rw-r--r-- 1 aquila aquila 42 Oct 8 18:18 chatroom.conf 0 -rw-r--r-- 1 aquila aquila 0 Oct 8 18:18 clientbanlist.conf 4 -rw-r--r-- 1 aquila aquila 132 Oct 8 18:18 hardban.conf 4 -rw-r--r-- 1 aquila aquila 2394 Oct 8 18:18 hub.conf 4 drwxr-xr-x 4 root root 4096 Dec 9 2005 log 4 -rw-r--r-- 1 aquila aquila 24 Oct 8 18:18 lua.conf 4 drwxr-xr-x 2 root root 4096 Sep 8 13:49 luascripts 4 -rw-r--r-- 1 aquila aquila 736 Oct 5 23:33 motd.txt 0 -rw-r--r-- 1 aquila aquila 0 Sep 22 02:29 nickban.conf 4 -rwxr--r-- 1 root root 105 Dec 9 2005 run 4 -rw-r--r-- 1 aquila aquila 276 Oct 8 18:18 softban.conf 4 drwxr-xr-x 2 root root 4096 Oct 5 23:26 supervise 4 -rw-r--r-- 1 aquila aquila 174 Oct 8 18:18 trigger.conf
Make sure any lua scripts you have installed are NOT executable. Uploading and editing these files from windows machines could very easily corrupt these files permissions, so keep Windows away from your files! The supervise directory should look like this:
total 12 4 drwxr-xr-x 2 root root 4096 Oct 5 23:26 . 4 drwxr-xr-x 5 root root 4096 Oct 8 18:21 .. 0 prw------- 1 root root 0 Oct 4 11:58 control 0 -rw------- 1 root root 0 Dec 9 2005 lock 0 prw------- 1 root root 0 Dec 9 2005 ok 4 -rw-r--r-- 1 root root 18 Oct 5 23:26 status
If you have a directory called supervice delete it. It was a typo in an old aqdtinstall script.
The log directory should look like this:
total 20 4 drwxr-xr-x 4 root root 4096 Dec 9 2005 . 4 drwxr-xr-x 5 root root 4096 Oct 8 18:21 .. 4 drwxr-xr-x 2 aquila aquila 4096 Aug 17 05:34 main 4 -rwxr--r-- 1 root root 59 Dec 9 2005 run 4 drwxr-xr-x 2 root root 4096 Sep 7 15:51 supervise
The log/supervise directory is identical to the other supervise directory. The main dir looks something like this:
total 95916
4 drwxr-xr-x 2 aquila aquila 4096 Aug 17 05:34 .
4 drwxr-xr-x 4 root root 4096 Dec 9 2005 ..
9780 -rwxr--r-- 1 aquila aquila 9998063 Aug 12 14:32 @4000000044ddca563b263834.s
9780 -rwxr--r-- 1 aquila aquila 9998157 Aug 13 04:30 @4000000044de8ec40c15ae6c.s
9780 -rwxr--r-- 1 aquila aquila 9998127 Aug 13 18:25 @4000000044df529d18912964.s
9780 -rwxr--r-- 1 aquila aquila 9998043 Aug 14 08:25 @4000000044e01765016333a4.s
9780 -rwxr--r-- 1 aquila aquila 9998174 Aug 14 22:11 @4000000044e0d90638ba83ac.s
9780 -rwxr--r-- 1 aquila aquila 9998205 Aug 15 11:56 @4000000044e19a541a5497cc.s
9780 -rwxr--r-- 1 aquila aquila 9998140 Aug 16 01:49 @4000000044e25dae3199ea04.s
9780 -rwxr--r-- 1 aquila aquila 9998287 Aug 16 15:38 @4000000044e31fe328e300bc.s
9780 -rwxr--r-- 1 aquila aquila 9998271 Aug 17 05:34 @4000000044e3e3b217f92b3c.s
7888 -rw-r--r-- 1 aquila aquila 8064918 Oct 5 23:26 current
0 -rw------- 1 aquila aquila 0 Dec 9 2005 lock
0 -rw-r--r-- 1 aquila aquila 0 Apr 20 22:06 state
You can restore all the ownerships and permissions with the following commands:
touch aquila.pid lua.conf clientbanlist.conf hub.conf softban.conf hardban.conf trigger.conf account.conf chatroom.conf chown -R aquila:aquila *.conf aquila.pid log/main chmod -R og-w, u+w . chmod +X run log/run
Sometimes, when I try to login into an Aquila, it disconnects me without any message.
If your download bandwith is saturated, your client may not answer in time and Aquila will disconnect you. This can happen when you startup your client and you have many hubs on auto-login. Downloading all the nicklists will saturate your bw and some hubs will fail to connect. Just press reconnect and you should get in fine.
These timeouts are part of the flooding protection and cannot be turned off.
Build problems
GCC cannot create executables
checking for gcc... gcc checking for C compiler default output file name... configure: error: C compiler cannot create executables
This means you do not have a complete gcc build environment installed.
If you are using Ubuntu, the solution is simple:
apt-get install build-essential
If you've used other kind of hubsoftware
General notes about commands
Never forget to use quotation marks when your command parameter contains more than one word. If you forget the quotation marks, Aquila will remove the unnecessary spaces, so this may result your broadcast message will be reformatted or some parameters are not processed properly.
Proper commands:
!massall "This is my mass-message" != hubname "Very Good Hub"
Improper commands:
!massall This is my mass-message != hubname Very Good Hub
Kicking and banning
When kicking, it's recommended to define a custom UserCommand for the kick command. If you use the built-in right-click "Kick user(s)" function of your client, the users won't get the reason when they reconnect. This is a limitation of the NMDC protocol, Aquila don't want to workaround this. If you use your own UserCommand, that will help your users to find out why they were kicked.
