Manual
From Aquila Homepage
Contents
|
Aquila Installation
Getting Aquila
You can download Aquila from the Download page.
Aquila Requirements
You will need zlib if you wish to use ZLine. ZLib is installed on most linux distributions so this should not be a problem. In the unlikely event that you do not have zlib installed, please check out your distributions homepage on how to install it.
If you wish to use LUA scripting, make sure you have LUA 5.0.x installed. If lua is not installed, Aquila will be built without scripting support. Aquila does NOT support LUA 5.1 or later. Please consult the FAQ on how to install Lua.
Aquila can make use of epoll. This may not be always available: you will need a recent glibc and a recent 2.6 linux kernel.
Compiling Aquila
First, unpack the archive.
tar zxvf aquila-<version>.tgz
Aquila has a few switches in its configuration script that can be useful, so take some time to check the output from
configure --help
The default settings should be fine for most users.
./configure
When this completes succesfully, we can continue to build and install the binaries.
make make install
Please note that the make install should be run as root.
Congratulations, the first part is done and you now have installed Aquila on your system.
Running Aquila
After building and installing the binaries, we need to prepare the environment for the hub.
First, we need to create a directory for the hub to run in. All configuration files of the hub will be saved in this directory. The hub should be started in this directory.
mkdir <directory> cd <directory>
Replace <directory> with the directory you wish to run Aquila in. Be sure to take a look at the Recommendations below.
Then we need to initialize the password file with an account for the hub owner.
aqpasswd accounts.conf <owner> <passwd>
Replace <owner> with the nick of the hub owner and <passwd> with his password.
You can now start the hub if you like.
aquila -d -r
Most likely however you will run into problems unless you are running the hub as root. The default DC port is port 411. By default, any port below 1024 cannot be used except by root. To circumvent this problem, you can create a hub.conf file with the following line:
nmdc.listenport <port>
where you replace <port> with the port you want the hub to listen on.
Now start the hub (if you already started it, kill it first!):
aquila -d -r
and log in. Type the following line in the main chat:
!save
This will make the hub create all the missing configuration files and fill them with default values.
Congratulations! You Aquila DC hub is ready to be used.
Recommendations
Since Release 0.1.7, the distributions contains a script called aqdtinstall This will install daemontools and set up an aquila as specified below.
I advise you to create a new account with its own home directory to run aquila in. This will add some protection in case Aquila has any vurnabilities in it.
For a Gentoo system the commands would be:
groupadd aquila useradd -g aquila -m -d /home/aquila -s /bin/false aquila passwd -l aquila
This will create a group and user called aquila with homedirectory /home/aquila. The account will be locked so it cannot be used to log in. To start aquila, you would do as root:
su aquila cd /home/aquila aquila -d -r exit
This will provide a safe execution environment for your hub.
I also suggest you run Aquila under daemontools. These tools will automatically start your hub when you boot your machine and restart it if it should crash. It will also handle things like running the hub under a different user.
As a shortcut, use the aqdtinstall script in the tools directory. It will do the above for you.
Should you really want to support port 411, please consider using iptables to redirect any connection on port 411 to the port you have configured you hub on. The necessary rules would be:
iptables -t nat -A PREROUTING -m tcp -p tcp --dport 411 -j REDIRECT --to-ports <port>
This method is a lot safer than running it as root.
Aquila Usage
Aquila Commands
All Aquila commands can be typed into main chat or in a pm window to the Hub Security bot. The hub will send any answer to the window you typed the command in. Aquila commands must be prefixed with a + or a !, it doesn't matter which.
Most commands can be entered without arguments to see which arguments they take (this will not work for commands that do not need arguments). In these help strings, arguments are between < and >, optional arguments have [ and ] around them, a | symbol means or and ... means you can specify any number of arguments.
If you need to enter a string, you can just type it in. The hub will concatenate it if possible. If you are not sure or there are other arguments after the string, you need to enclose the string in double quotes ("). If you do not use quotes, the hub will remove any unnecessary spaces.
Generic User Commands
This section deals with generic commands that are available to all users. These are simple commands that make life a bit easier in the hub.
The help command shows you a list of commands you can use and a short Help string. If you specify a name after the command, it will only show you the help string of the command with that name.
The myip command will show you your IP address as it is seen by the hub. This is very useful for configuring clients for active mode.
The passwd command or pwgen command can be used by registered users to change their password. pwgen will generate a random password for you. Users with user management capabilities can use this command to change the password of other users too.
The report command can be used by any user to send a report about another user or about a problem. The report will end up where the config value reporttarget directs it. If this value is not set, a message is send to the user that reporting is disabled.
Operator Commands
This section deals with the commands available to operators. These are the traditional kick and ban commands.
There is only one kick command. It will kick a user and ban them temporarily for the configured amount of time (see kickautobanlength).
If you add _ban_ to the kick message, Aquila will add an indefinate ip and nick ban too. You also use timed bans. If you append a time to the _ban_ string, Aquila will make it a timed ban. This can be disabled and limited, see the configuration section for details.
There are two main groups of ban commands. Normal ban commands that work by specifying the nick and those that work solely on IPs.
You can ban and unban IPs with the commands banip and unbanip. These accept IPs or nicks as the argument.
Aquila supports CIDR based IP Range banning. Any kick or ban related command that takes an IP as argument, you can enter an IP Range. IP Ranges are expressed as x.x.x.x/l or x.x.x.x:y.y.y.y . Emaples are 192.168.0.1/24 or 10.0.0.1:255.255.0.0
You can ban and unban users by nick with the commands ban, bannick and unban. The bannick command will only ban a user by nick, not by IP. The ban command will add both ban types. bannick and unban can be used on users which are not online, ban cannot. They only accept nicks as arguments.
There is one last ban type (hard ipban) that is only available to the hub owner. The hard ipban bans an IP in such a way even a registered user is affected by it (up to and including the hub owner, so be careful!).
To view if a nick or IP is banned, user the banlist command.
Lastly, there is the zombie command it will gag a user without him knowing it. (The user still gets to see his own chat messages).
User Management
Rights
Rights are at the base of the Aquila authentication and authorization mechanism. A user has a group, but the group is nothing more than an easy way of assigning basic rights to a user.
Rights determine which commands you get to see when you do help and which commands you can use. They control if you need to share, if you have a key, if you can kick, ban, hardban and so on.
Name Meaning chat Allows the user to chat in main window. search Allows user to search the hub for files pmop Allows the user to send private messages to OPs only. pm Allows the user to send private messages to anyone. dl Allows user to download files. share Allows users to circumvent the share requirements. key Awards the user the much desired "key". kick Allows the user to kick other users. ban Allows the user to ban other users. config Allows the user to edit the configuration of the hub. say Allows the user to use the "say" command. user Allows the user to add new users. group Allows the user to add new groups. inherit Allows the user to award rights they posses to users or groups. hardban Allows the user to hardban IPs. A hardban is a bit like firewalling the IP. tag This users does not need a tag to get in the hub. sharehide This will hide the share of the user. His share will show 0 bytes. shareblock This right will only work for active users. It will block all download attempts but the user can still download himself. spam This will take away the charicter limitations when posting chat messages. nosrchlimit Users with this right are not subject to search limitations.
The following aren't really rights, they are just easy shortcuts to a collection of rights.
Name Meaning default Default capabilities: chat, pmop, dl and search. reg Default REG capabilities: chat, search, pm, dl. vip Default VIP capabilities: chat, search, pm, dl, share, spam. kvip Default KVIP capabilities: chat, search, pm, dl, share, kick, spam. op Default OP capabilities: chat, search, pm, dl, share, key, kick, ban, spam. cheef Default CHEEF capabilities: chat, search, pm, dl, share, key, kick, ban, user, spam. admin Default ADMIN capabilities: chat, search, pm, dl, share, key, kick, ban, user, group, spam. owner Everything. All powerful. Mostly, capable of hardbanning.
You can always see which rights users have with the userinfo command.
To assign individual rights you need the inherit right, without it you cannot assign rights or create groups. Even when you do have that right, you cannot assign any right you do not have yourself (except if you have the owner right).
Group Management
As mentioned before, a group is nothing more than a convenient way to control the default rights of a user. If a user is assigned to a group, he gains all the rights of that group. If the rights of a group are changed, this will affect the rights of all users in that group (from their next login). You cannot delete a group that still has users in it, so don't forget to delete them first.
You can change the rights of a group with the grouprights command. If you want to add a right, just add the name or +name. To remove it use -name.
You need the inherit and group right for this.
Group management is controlled by the commands
groupadd Add a user group. groupdel Delete a user group. grouplist List all groups with their rights. grouprights Edit the rights of a user group.
User Management
User accounts are a way to allow certain users more rights than others. Users get their rights from the group they've been assigned. They can also be granted extra rights on an individual basis.
There are a few commands that control user management.
useradd Add a user. userdel Delete a user. usergroup Assigns a user to a new group. userinfo Show information of user. userlist List all users of a user group. userrights Edit the extra rights of a user.
To create a user you need the user right. You cannot add a user to a group that has more rights than you have and you cannot assign a user extra rights (rights that are not by default in their group) unless you have the inherit right.
Client Management
Aquila supports client banning for those who wish to ban certain clients from their hubs.
clientban Ban a client. clientbanlist List client bans. clientunban Unban a client.
Configuration Management
Generic Configuration
You can change and control all configuration settings with the following commands:
confighelp Show configuration value help strings. configset Set configuration values. (You can use = as alias for this command) configshow Show configuration.
Use configset to change variables and configshow to view them. confighelp will give you a complete list of help variables and a short help string that explains them.
If you wish to use spaces in arguments, do not forget to put them inside double quotes. Examples:
!= nmdc.extraports "2000 3000 4000" != hubdescription "This is a long hubdescription"
Hub Configuration
These control various aspects of how the hub behaves.
autosaveinterval This is how often the hub saves all its settings and bans. If you set this to 0, it will disable the autosave. hub.allowcloning Allow multiple users from the same IP address. hubaddress A hostname (or IP address) where your machine will be reachable. hubdescription Description of the hub. hubname Name of your hub hubowner Owner of the hub. hubsecurity.desc Description of the Hub Security bot. hubsecurity.nick Name of the Hub Security bot. redirect Redirection target. This controls where users are sent if they are refused by the hub. kickbanredirect Redirection target. This controls where users are sent if they are kicked or if they are refused by the hub because they are banned. reporttarget User to send reports to (from the "report" command. Can be a chatroom. hub.sysreporttarget User to send hub error messages to. Can be a chatroom. user.defaultrights This are the rights assigned to any unregistered user.
NMDC Configuration
These are the configuration values for all NMDC protocol specific settings.
nmdc.listenaddress The ipaddress on your system the hub should listen on. You can specify only 1. Configure this as 0.0.0.0 to listen to all addresses. nmdc.listenport The main port of the hub. This is the one reported to anyone asking. nmdc.extraports Any other ports to listen on. A space or comma seperated list. nmdc.defaultbanmessage This message is always sent to all banned users. Leave blank if you do not wish to send a message. nmdc.maxchatlength Users without the spam right cannot send messages longer than this length, this includes the nick! nmdc.maxsearchlength Users without the spam right cannot do searches longer than this length. nmdc.maxsrlength Users without the spam right cannot send searchresults longer than this length. nmdc.researchinterval A search cannot be repeated within this interval. nmdc.researchmaxcount This is the number of searches the hub will remmember. They will not be remembered longer than the nmdc.researchperiod. nmdc.researchperiod Researches are only send to users that have joined within this period.
Researches are a special Aquila feature. All searches that are repeated in the last nmdc.researchinterval are just dropped. All searches that repeated within the nmdc.researchperiod are send only to the users that have joined since the previous search. The hub will remember only a limited number of searches, you can configure this with nmdc.researchmaxcount.
Buffering configuration
These controls are sensitive. Be sure you understand very well what they do. A bad settings here could mean that users can't get in your hub, that your hub will crash because it runs out of memory and so on.
Aquila stores data for users that cannot read it all immediatly. This has the advantage that data isn't lost but Aquila cannot solve the problems of users that are just too slow and cannot keep up. At a certain point, Aquila must decide that a user is using too much resources and must drop him. These settings control when Aquila decides to drop a user. The decision is based on the memory used to buffer for the user and the time the user is allowed to buffer data.
- hub.buffersoftlimit As soon as the user has more unread data then the soft limit, the user is considered to be in "overflow" (see below).
- hub.bufferhardlimit As soon as a user has more unread data then the hard limit, all new data will be dropped.
- hub.buffertotallimit This is the total amount of memory Aquila is allowed to use for buffering.
- hub.timeoutbuffering The user is disconnected if he buffers longer than this time. (In milliseconds)
- hub.timeoutoverflow If the user goes in "overflow" then he is disconnected after this time. (In milliseconds)
Keep the hub.timeoutbuffering fair. If you raise it too high, the user will start lagging too much to be useful, if you set this too low, temporary network congestion can disconnect users unnecessarily. Keep the hub.timeoutoverflow lower than the buffering timeout. User that go in overflow are getting their second chance to quickly read out their data.
The hub.buffertotallimit is the total memory Aquila is allowed to use for buffering. Make sure this is smaller than your physical memory. If you see aquila is causing the system to start using its swapspace, this setting is too high. The other settings control when a user goes into overflow and when to start dropping data per user. Make sure these considerably smaller than your hub.buffertotallimit since these settings will control how many users are allowed to buffer. If the hub.buffertotallimit is reached, users will get "Hub is Busy" errors.
Do not make the mistake of trying to disconnect as few users as possible. It will be better for your hub to timely disconnect users that cannot keep up. It will ensure that your buffering memory is used for users that deserve to stay in the hub, it will prevent good users from getting "Hub is busy" messages and it make the hub respond better. It may take a little longer, but if your users can all keep up, you should be able to hold more of them.
As a last point, consider this: users that buffer too much, will respond slowly to searches, download requests and chat (with a max delay of hub.timeoutbuffering+hub.timeoutoverflow. In the mean time, they can still download from others.
User configuration
User Sections
These control the different requirements users must meet to be allowed in your hub. User are split into three major sections for this purpose. You have
- unregistered users (users withough an account)
- registered users (all users that have an account)
- op users (all users that have an account and a key)
All requirements exist seperatly for each section of users. Note that this may not always be relevant. All users with the tag right are automatically immume for slot and hub rules, all user with the share right are immume for share requirements. All users with the owner right are immume for all requirements.
Be carefull with these settings. It is entirely possible to create configurations which are impossible to satisfy.
Note: The registered users setting includes the op users setting (ops are registered too!). This means if you configure 50 registered users and 10 ops, you can have 10 ops and 40 registered usesrs that are not ops.
Note: I use section here to avoid confusion with the account groups above.
Requirements
userlimit
First, we have the userlimit. This controls how many users we let into the hub. This requirement is a bit of an exception for two reasons.
- A user cannot control it. If the hub is full, it is full. Though luck.
- The registered users section includes the op users section.
There can never be more unregistered users in the hub than userlimit.unregistered. There can never be more than userlimit.registered registered users in the hub, of which there are at least userlimit.op operators.
hub rules
The hub will enfore the following hub rules per user:
- hub.*.max: Maximum number of hubs.
- hub.*.min: Minimum hubs for Operators.
slot rules
The hub will enforce slot rules per user. There are three requirements:
- slot.*.max: Maximum numbers of slots.
- slot.*.min: Minimum number of slots.
- slot.*.ratio: This is the ratio of hubs / slot. (A ratio of 2 would allow the user to have 2 hubs/slot)
share rules
sharemin.*: Minimum share requirement (measured in bytes).
To set the minimum sharesize, you can use the following units:
b bytes k kilobytes m megabytes g gigabytes t terabytes p petabytes
So, setting the sharesize to 15g would set it to 15 gigabytes. (this works from release 0.1.8-pre2 onwards)
Kick Configuration
There are two variables that control the use of the _ban_ string in the kick command. These are KickNoBanMayBan and KickMaxBanTime. KickNoBanMayBan controls whether users that do not have the ban right can use _ban_ when kicking, KickMaxBanTime controls the maximum ban time those users can use. These settings do not affect users that do have the ban right.
A third variable that controls kicking is the kickautobanlength. It specifies the length of the automatic temporary ban after a kick.
The last variable is the kickbanredirect setting, this controls where kicked and banned users are redirected.
Chat Rooms
Chat Rooms are rooms in which groups of users can chat. All things said in a Chat room are only sent to the users in that chat room. Chat rooms have a few options that control how they behave. Private chat rooms cannot be joined at will. The only way to get in is to be autojoined. Public chat rooms can be joined by sending them a private message. Autojoin chat rooms auto join users when they log in. This is the only way to get into a private chat room. Autojoin can be controlled with a few options. You can autojoin all registered users or all users with a certain set of rights.
These chat room commands are available:
chatroomadd Add a chat room. chatroomdel Remove a chat room. chatroomlist Lists available chat rooms.
The chatroomlist command will also show how many users are in each Chat room.
An excellent example of an autojoin chat room that requires the key right is the OpChat.
Triggers
Overview
Triggers are a way to execute external commands, paste external sources or text to users when logging in or when executing a command. There are two parts in creating these. First you create the content of the trigger, then you control when the trigger is activated by adding a rule.
An excellent example of a file trigger that has a login rule is the MOTD (Message of the Day).
All trigger and rule commands require the config right.
Triggers
These display or execute the contents of the trigger. The contents can come from a file, from an external command (not yet implemented) or you can specify it at creation time. Note that the hub will detect any changes to the contents of these trigger files if you make changes in them.
Trigger control commands are:
triggeradd Add a trigger. triggerdel Delete a trigger. triggerlist List triggers.
Rules
Rule control, when the content of a trigger is displayed to a user. There are two ways currently implemented: at login or by a command. For both modes you can specify minimal rights that a user needs to have before the rule applies. There is no limit to the number of rules that can apply to a command.
The rule commands are:
Typing any of these in the chat, or PM window will give you the correct command syntax to use. Below is an example for adding a trigger. In this case, we will add the MOTD to appear on login:
!triggeradd motd text "then motd text..what you want it to say"
"motd" is the text file name, "text" is to tell Aquila that this is a text file. You MUST use Speech marks (") when writing what you want the motd to say, as above.
Next, we need to add the rule for this trigger. In this case, it will appear on login:
!ruleadd motd login all
Yet again, "motd" is the trigger name, and "login" tells Aquila that this will appear on user login. "all" sets it to appear for all user groups - (everyone who logs in will see the motd). This can also be set to other usergroups only, such as "ops". This is Manditory.
Adding a hub trigger command is quite the same, but with some differences:
!triggeradd network text "then what you want your file to say here"
You MUST use Speech marks (") when writing what you want the trigger to say, as above.
Then to add the rule for this trigger:
!ruleadd network command network "Shows such and such"
You MUST use Speech marks (") when writing what you want the help to say, as above.
The first "network" is the triggername. The "command" tells Aquila that this is a command. The second "network" is the actual trigger to be typed, but you dont need to add a prefix here, Hence there is no ! or +
You will find the rest of the syntax when you type !triggeradd or !ruleadd in your hub.
Rate controls
Rate controls are ways to control how often certain events are allowed to happen. They are controlled with token buckets. There are several seperate areas that have rate controls. See token buckets for information on what exactly the fields mean.
User rate controls
There is a rate control for almost every command that can be send by the user to the hub. There are still a few missing, they will be added when deemed usefull. I will only discuss some of the more relevant ones here. See the description of the configuration variables for more information on the others. The most important ones are the chat, the myinfo and the search rate controls. They will have the most severe effect on your bandwidth and they are you first line of defense against spammers. All messages that are send above the approved rate are just dropped.
rate.chat This controls the rate at which users can send chat message to the hub. rate.connect This controls the rate at which new users are allowed in the hub. rate.download This controls the rate at which users can send download requests. rate.getinfo This controls the rate at which users can send getinfos to the hub. rate.getnicklist This controls the rate at which users can ask for nick list refreshes. rate.myinfo This controls the rate at which users can send MyINFO updates. rate.search This controls the rate at which users can search the hub. rate.results_in This controls the rate at which a user can receive passive search results. rate.results_out This controls the rate at which a user can send passive search results. rate.warnings This controls the rate at which a user will receive warnings of various kind.
Cache rate controls
These control how often the hub flushes the different parts of its cache.
cache.activesearch This is how often searches are send to the active users. cache.activeresearch This is how often researches are send to the active users. cache.chat This controls how often chat messages are flushed to the users. cache.join This controls how often new user joins and quits are send to the users. cache.passivesearch This is how often searches are send to the passive users. cache.passiveresearch This is how often researches are send to the passive users. cache.pm This is how often private messages are send to the user. cache.quit This is how often quit messages are send to the user (removed in 0.1.8-pre3). cache.results This is how often the hub will send on passive search results. cache.update This is how often the queue of MyINFO updates is sent to the users. cache.updateop This is the same as cache.update, but for everyone with a key.
Tag settings
These variables control some restrictions you can add to the MyINFO fields of your users. Please note that the versions send to your operators are not affected.
tag.maxdesclength Maximum Length of the users description field. tag.maxemaillength Maximum length of the users email address field. tag.maxsharelength Maximum length of the users sharesize field. tag.maxspeedlength Maximum length of the users speed field. tag.maxtaglength Maximum length of the users tag field.
Hublist settings
These variables control the hublist registration.
hublist.interval The hublist update is send every interval seconds. hublist.lists This is a space or comma seperated list of hublists to register at. hublist.silent If you set it to 1, the hublist registration errors won't be broadcasted to you every time the hub registers to the list.
The hublist command forces the hub to register at the hublists.
Chatlog settings
This variable controls the chatlog.
chatlog.lines The number of chatlines to remember. Each chatmessages is considered 1 line.
The chatlog command allows you to see the chat log.
IP Logging
This variable controls the IP Logging the hub performs.
iplog.length This is the number of IPs the hub remembers of users that actually have joined the hub. Banned and redirected users are not included in this list.
The iplog command returns a list of all logged IPs.
Statistics
Aquila supports a large number of statistics. A lot of them might seem cryptic and they probably are.
uptime Show uptime. statbot Command returns info for the statbot. statbuffer Show buffer stats. statbw Show bandwidth stats. statcache Show cache stats. statcpu Show CPU usage stats. statuser Show logged in user counts. statnmdc Show a lot of nmdc protocol counters.
