diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ASTYLE | 1 | ||||
| -rw-r--r-- | docs/C++CASTING | 111 | ||||
| -rw-r--r-- | docs/CMakeLists.txt | 6 | ||||
| -rw-r--r-- | docs/CODING | 239 | ||||
| -rw-r--r-- | docs/Changes | 5 | ||||
| -rw-r--r-- | docs/EVENTS | 35 | ||||
| -rw-r--r-- | docs/FAQ | 10 | ||||
| -rw-r--r-- | docs/INSTALL | 16 | ||||
| -rw-r--r-- | docs/INSTALL.fr | 18 | ||||
| -rw-r--r-- | docs/LANGUAGE | 2 | ||||
| -rw-r--r-- | docs/MODULES | 6 | ||||
| -rw-r--r-- | docs/MySQL.md | 24 | ||||
| -rw-r--r-- | docs/NEWS | 7 | ||||
| -rw-r--r-- | docs/README | 6 | ||||
| -rw-r--r-- | docs/REDIS | 160 | ||||
| -rw-r--r-- | docs/REST.md | 245 | ||||
| -rw-r--r-- | docs/SQLite.md | 43 | ||||
| -rw-r--r-- | docs/TOOLS | 24 | ||||
| -rw-r--r-- | docs/WIN32.txt | 4 | ||||
| -rw-r--r-- | docs/XMLRPC/xmlrpc.php | 1 |
20 files changed, 342 insertions, 621 deletions
diff --git a/docs/ASTYLE b/docs/ASTYLE deleted file mode 100644 index be8cf2325..000000000 --- a/docs/ASTYLE +++ /dev/null @@ -1 +0,0 @@ -astyle --style=java --indent=tab --brackets=break-closing --indent-switches --indent-cases --brackets=break diff --git a/docs/C++CASTING b/docs/C++CASTING deleted file mode 100644 index e1beb8f06..000000000 --- a/docs/C++CASTING +++ /dev/null @@ -1,111 +0,0 @@ -C++-style Casting -================= - -In C, you can cast in one of two ways: - -(type)var -type(var) - -The problem with C-style casting is that it allows a programmer to get away -with too much, and is also not designed to handle C++ classes. - -C++ has 4 types of casting in addition to allowing C-style casting. They are: - -static_cast -const_cast -dynamic_cast -reinterpret_cast - -The syntax is usually *_cast<type>(var). - -static_cast ------------ - -From my experience, this cast is closest to C-style casting for non-pointer -types as well as between some (but not all) pointer types. This type of cast, -like C-style casting, is performed at compile-time. static_cast can also do -a downcast of a derived class to a base class, but only if the base class is -not a virtual base class. Sometimes the result of this cast can become -undefined. static_cast is a bit more strict that C-style casting, though. It -disallows certain class conversions that would've been allowed with a C-style -cast. static_cast also doesn't allow you to cast to an incomplete type. In -these cases, I would try either dynamic_cast or reinterpret_cast. - -const_cast ----------- - -This cast is mainly to add or remove const-ness or volatile-ness from a -variable. This is safer than using a C-style cast to change the const-ness -of a variable. In most cases if you try to use one of the other casts and it -complains about const-ness, you will want to either use this cast instead or -wrap the other cast around this cast. An example: - -const int *a; -static_cast<void *>(a); <-- This will fail. - -To remedy the above, you would might try this: - -const int *a; -const_cast<void *>(a); <-- But this will still fail. - -The real solution is this: - -const int *a; -static_cast<void *>(const_cast<int *>(a)); - -It is not recommended to use const_cast on the this variable within a member -function of a class that is declared const. Instead you should use the mutable -keyword on the variable in the class's definition. - -dynamic_cast ------------- - -This cast can only be used on pointers or references to classes. It can cast a -derived class to a base class, a derived class to another derived class -(provided that both are children of the same base class), or a base class to a -derived class. You can also use this to cast a class to void *. This cast is -done at run-time as opposed to the other casts, and relies on C++'s RTTI to be -enabled. It is meant to be used on polymorphic classes, so use static_cast on -non-polymorphic classes. - -derived-to-base conversions are actually done statically, so you use either -dynamic_cast or static_cast on them, regardless of if the classes are -polymorphic or not. - -derived-to-derived or base-to-derived conversions, however, rely on run-time -type information, and this cast is used on those classes that are polymorphic. -This is safer than C-style casting in that an invalid pointer conversion will -return a NULL pointer, and an invalid reference conversion will throw a -Bad_cast exception. - -Note that in Anope we prefer if Anope::debug_cast is used. -This uses dynamic_cast (and checks for a NULL pointer return) on debug builds -and static_cast on release builds, to speed up the program because of dynamic_cast's -reliance on RTTI. - -reinterpret_cast ----------------- - -This cast I would use only as a last resort if static_cast isn't allowed on a -conversion. It allows for conversions between two unrelated types, such as -going from char * to int *. It can also be used to convert a pointer to an -integral type and vica versa. The sites I've read mention how the result is -non-portable, which I assume means the resulting object code is non-portable, -so since the code is compiled on many systems anyways, I don't see this as -being a huge issue. It is recommended to only use this if necessary, though. - -Links -===== - -The following links are web sites I've used to get this information, and might -describe some of the above a bit better than I have. :P - -http://www.acm.org/crossroads/xrds3-1/ovp3-1.html -http://www.cplusplus.com/doc/tutorial/typecasting.html -http://www.codeguru.com/forum/showthread.php?t=312456 -http://www.cs.umd.edu/class/sum2003/cmsc311/Notes/BitOp/cast.html -http://msdn.microsoft.com/en-us/library/5f6c9f8h(VS.80).aspx -http://en.wikibooks.org/wiki/C%2B%2B_Programming/Type_Casting -http://www.informit.com/guides/content.aspx?g=cplusplus&seqNum=134 - --- CyberBotX, Nov 23, 2008 diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 082b1da0e..7e135d207 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -6,10 +6,10 @@ if(WIN32) if(IN_SOURCE) # Add README.txt to list of files for CPack to ignore add_to_cpack_ignored_files("README.txt$" TRUE) - endif(IN_SOURCE) - set(DOCS Changes Changes.conf DEFCON FAQ INSTALL LANGUAGE MODULES NEWS ${CMAKE_CURRENT_BINARY_DIR}/README.txt WIN32.txt) + endif() + set(DOCS Changes Changes.conf DEFCON FAQ INSTALL LANGUAGE MODULES MySQL.md NEWS ${CMAKE_CURRENT_BINARY_DIR}/README.txt SQLite.md WIN32.txt) install(FILES ${DOCS} DESTINATION ${DOC_DIR} ) set_directory_properties(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${CMAKE_CURRENT_BINARY_DIR}/README.txt") -endif(WIN32) +endif() diff --git a/docs/CODING b/docs/CODING deleted file mode 100644 index 7dbd5afb3..000000000 --- a/docs/CODING +++ /dev/null @@ -1,239 +0,0 @@ -Originally pulled from: http://www.inspircd.org/wiki/Coding_Guidelines - ---- - -InspIRCd Coding Guidelines - -The following are a set of guidelines for writing patches to InspIRCd, or for -creating modules for distribution with the official package. These guidelines -were written a time after InspIRCd development started, and so not all code -yet follows these. This will be rectified with time. - - -1. Comments - - * Multi Line - Multiple line comments should follow the C-style comment, for example: - /* - * This is a multiple line comment, huzzah.. - */ - - * Single Line - Single line comments should also be in the C style, for example: - /* This is a boring one-line comment */ - - * Doxygen commenting - If you wish your comment to show in doxygen, the comment should be directly - above the item you are documenting (a class, function, enum, etc) and the - first line should be "/**". For example: - /** This is a doxygen multiline comment. - * Description of thingymebob here. - */ - - The first line after the "**" is used as the short description of the item - (up to the full stop) and everything afterwards as the detailed description. - - -2. Indentation - - Tabs. Tabs. ONLY TABS. Use a single tab for each level of indentation, - for example: - int main() - { - <tab>if (condition) - <tab>{ - <tab><tab>code - <tab>} - } - - -3. Separation - - Always put a space in between a keyword like if/while and the condition, - for example: - if (foo == bar) - NOT - if(foo == bar) - - -4. Braces - - Always put braces opening and closing blocks on separate lines, see the - identation example. For example, place braces like this: - if (apples == "green") - { - cout << "Apples are green" << endl; - } - - and not: - if (apples == "green") { - cout << "Apples are green" << endl; - } - - The one exception to this is if you are declaring a class method which is - only one line long, in that case the following is acceptable in most cases: - class foo : public bar - { - foo() { } - getrandomfoo() { return rand(); } - }; - - -5. Templates - - Where possible, use templates rather than #defines. Avoid use of RTTI. - - -6. Structs - - Structs should be declared in the following fashion: - struct BodyPartBasket - { - int arms; - int legs; - int scrotalsacs; - }; - and not like this: - typedef struct - { - int arms; - int legs; - int scrotalsacs; - } BodyPartBasket; - - The second way is not required in C++ to be able to do this: - BodyPartBasket mybasket; - - Plus, placing the name at the bottom of the declaration makes readability - more difficult (as you have to scroll down to the bottom of the struct to - find its name). (where possible, call them classes rather than structs.) - - -7. Variable naming - - Class and struct names should be in camel case with a leading capital letter, - for example "MyBagOfBones" and not "my_bag_of_bones" or "mybagofbones". - Variable names can be in either camel case with a leading capital letter or - alternatively all lower case, so long as the same naming convention is - adhered to throughout the class. No classes or variables should be named in - capitals unless this makes sense for the name (for example "class DNS"). - Constants and enum values should always be completely in CAPITALS and - underscores may be used, for example: - enum DecayState - { - DECAYED_MOULDY = 0, - DECAYED_SMELLY = 1, - DECAYED_MAGGOTS = 2 - }; - All value names in an enum should be started with the same text which should - be related in some way to the enum's use. For example "DNS_CNAME, DNS_A, - DNS_AAAA". - - -8. Use of references - - Wherever possible, when dealing with any complex class, pass a const reference - rather than a copy of the class. For example: - MyThingy::MyThingy(const std::string &thingyvalue) - { - } - Of course, if you intended to change the string you can just omit the 'const'. - - -9. Use of char pointers - - Whenever you use char pointers (char*, char**) try to use const equivalents. - This is much safer and avoids ugly and dangerous casts. For example: - MyThingy::Thingify(const char* const* wotsits) - { - } - If it is possible without performance loss, consider avoiding char pointers - altogether and using std::string instead. - - -10. Use of STL - - For more information on use of STL in InspIRCd, please see the separate - STL FAQ. - - -11. Making copies of data - - Never ever make a copy of a piece of data unless it is absolutely necessary. - For example, don't use strlcpy() to make a copy of the const char* string - returned by std::string::c_str(), if the change can be done to the std::string - itself. The same goes for unnecessary variable assignments, especially those - which assign large classes. - - -12. namespace std - - Avoid the following: - using namespace std; - It might take a bit more typing, but things work better if you don't set - (then later assume) the namespace -- specify it explicitly when you want to - use it. - - -13. Linefeeds - - Unix linefeeds only please. We do not like to see our screens covered in ^M. - - -14. Portability - - Always make sure your code is portable to all supported operating systems, - remember of course that as of 1.1.8 this includes windows. Don't write code - that only works on windows, or only works on Linux. Test your code on all - platforms or ask for help from other developers who have the platforms you - want to test on. - - * new() and delete(), malloc() and free() - Apart from the fact that using malloc() and free() is bad practice in C++ - code, you must never use malloc() or free() in InspIRCd, within its modules - or within the core. This is because if you use malloc() or free() in windows, - the memory is claimed from the program's local heap. - In windows, each shared object (module, dll) has its own heap, which is - protected from other dlls and executables. To get around this issue and - allow more posix-like memory access from other dlls in the program (other - modules), InspIRCd overrides the operators new and delete to ensure that - memory allocated by them comes from the windows global heap. If you use - malloc() and free() for this, the ircd will segfault when another module - tries to access the memory you have allocated! - - * strdup() - As with malloc(), above, strdup() should be avoided. Where strdup() is - absolutely necessary, use strnewdup() which is our strdup() implementation - that calls operator new instead of using malloc(). - char arrays allocated by strnewdup() should be deleted with operator delete[]. - - * CoreExport and DllImport - Prefix all types you want to import or export to other modules with CoreExport - and DllImport macros. These do nothing in POSIX operating systems, however - in windows these are expanded to the instructions __declspec(dllimport) and - __declspec(dllexport) respectively depending on where they are used and how. - - -15. External Dependencies - - If a module is compiled as standard, or the code is part of the core, you must - not use any dependencies that are not available as standard on all supported - operating systems beyond libstdc++, libc, and whatever else is currently - required to build the core. Modules which use nonstandard dependencies belong - in the modules/extra directory. - - -16. Profiling and Performance - - It is one thing to assume that code performs bad, it is another thing to prove - that it actually is. A lot of experienced programmers talk about 'premature - optimisation', and here is what it means: if you have a piece of code called - once on startup that takes 10 seconds instead of one second to run, and a - piece of code that takes 0.05 seconds to run when it should take 0.01, and - it is called once per second, the second piece of code is the priority. - - In other words, make sure that what you think is slow, and a performance - problem in Insp actually is. - To do this, use the callgrind tool from Valgrind (valgrind --tool=cachegrind - bin/inspircd -nofork -debug), and kcachegrind (or similar) to view the output - files. diff --git a/docs/Changes b/docs/Changes index c89b46625..472204ae0 100644 --- a/docs/Changes +++ b/docs/Changes @@ -1,7 +1,4 @@ -Anope Version 2.0.5-git -------------------- - -Anope Version 2.0.4 +Anope Version 2.0.4-git ------------------- Add notice rpc method to XMLRPC Fix access check in cs_updown to not allow actions on users with equal access diff --git a/docs/EVENTS b/docs/EVENTS deleted file mode 100644 index ba34f0571..000000000 --- a/docs/EVENTS +++ /dev/null @@ -1,35 +0,0 @@ -Anope Internal Events ---------------------- - -1) Intro -2) Using Events - -1) Introduction to Internal Events - - Internal Events are setup to give module developers more information - about what the core is doing at different times. This information can - be as complex as data we are feeding to the uplink, to simple triggered - events such as the databases being saved. - - Additionally there is a module included with the core - which can provide some clue as to how to use the code in your modules. - The rest of this document assumes that you are used to writing modules. - -2) Using Events - - Each Event in Anope calls a function. - You must override these functions in your main modules class. - The full list of functions and parameters are in modules.h. In this - case, you would be overriding OnJoinChannel() and OnPartChannel() like so: - - void OnJoinChannel(User *u, Channel *c) anope_override { } - void OnPartChannel(User *u, Channel *c) anope_override { } - - Some of these event overrides can be used to prevent or allow things to - happen that would normally not be allowed or denied. You can also use - ModuleManager (not explained here) to set control which order the modules - are queried (when multiple modules hook to the same event). - - The "anope_override" identifier is for compatibility with C++11. - Its usage is highly recommended. - diff --git a/docs/FAQ b/docs/FAQ deleted file mode 100644 index f0142a2af..000000000 --- a/docs/FAQ +++ /dev/null @@ -1,10 +0,0 @@ -Frequently Asked Questions (FAQ) concerning Anope -------------------------------------------------- - -The information in the 1.9 FAQ is subject to change at any -moment due to new developments. Please visit our website -for the most up to date information. - -An updated version of the FAQ can be found here: - -http://wiki.anope.org/index.php/FAQ diff --git a/docs/INSTALL b/docs/INSTALL index 0a923ef97..071483b08 100644 --- a/docs/INSTALL +++ b/docs/INSTALL @@ -52,8 +52,8 @@ Note: You should also read the README and FAQ files! cause trouble on your network if passwords are not encrypted, or read the memos of any user. - Now go into the conf directory (by default, ~/services/conf). Copy the example - configuration file (example.conf) to services.conf, and open the latter + Now go into the conf directory (by default, ~/anope/conf). Copy the example + configuration file (anope.example.conf) to anope.conf, and open the latter with your favorite text editor. It contains all the configuration directives Anope will use at startup. Read the instructions contained in the file carefully. Using the default values is NOT a good idea, and will @@ -71,7 +71,7 @@ Note: You should also read the README and FAQ files! * IMPORTANT: Back up your old databases! * If you are upgrading to a new major release, ALWAYS restart a - fresh configuration file from example.conf. + fresh configuration file from anope.example.conf. 3) Setting up the IRCd @@ -83,7 +83,7 @@ Note: You should also read the README and FAQ files! a shared block), and be sure that the IRCd is listneing on the given port in the link block. - Example link configurations can be found in example.conf for some of the + Example link configurations can be found in anope.example.conf for some of the popular IRCds. Don't forget to /rehash your IRCd to apply changes. @@ -95,7 +95,7 @@ Note: You should also read the README and FAQ files! 4) Starting Anope Go into the directory where binaries were installed (by default, this is - ~/services/bin). Type ./services to launch Anope. + ~/anope/bin). Type ./anope to launch Anope. If there are syntax errors in the configuration file they will be displayed on the screen. Correct them until there are no errors anymore. @@ -104,7 +104,7 @@ Note: You should also read the README and FAQ files! Give Services at least one minute to link to your network, as certain IRCds on some OSes may be really slow for the link process. If nothing happens after about a minute, it is probably a configuration problem. Try - to launch Anope with ./services -debug -nofork to see any errors that it + to launch Anope with ./anope -debug -nofork to see any errors that it encounters, and try to correct them. If you need help to solve errors, feel free to subscribe to the Anope @@ -116,7 +116,7 @@ Note: You should also read the README and FAQ files! still running, and restart it if not. First rename the example.chk script that is in Anope path (by default, - this is ~/services/conf) to services.chk and edit it. You'll need to + this is ~/anope/conf) to services.chk and edit it. You'll need to modify the CONFIGURATION part of the file. Then ensure that the file is marked as executable by typing chmod +x services.chk, and try to launch the script to see if it works (Anope must not be running when you do this ;)) @@ -125,7 +125,7 @@ Note: You should also read the README and FAQ files! This will open the default text editor with the crontab file. Enter the following (with correct path): - */5 * * * * /home/ircd/services/conf/services.chk >/dev/null 2>&1 + */5 * * * * /home/ircd/anope/conf/services.chk >/dev/null 2>&1 The */5 at the beginning means "check every 5 minutes". You may replace the 5 with other another number if you want (but less than 60). Consult diff --git a/docs/INSTALL.fr b/docs/INSTALL.fr index f7af3aac8..4cb453d35 100644 --- a/docs/INSTALL.fr +++ b/docs/INSTALL.fr @@ -55,9 +55,9 @@ Note : Vous devrez également lire les fichiers README et FAQ ! mots de passe ne sont pas chiffrés, ou lire les mémos de tous les utilisateurs. - Allez maintenant dans le répertoire conf (par défaut, ~/services/conf). - Copiez l'exemple de fichier de configuration (example.conf) en - services.conf et ouvrez ce dernier avec votre éditeur de texte favori. + Allez maintenant dans le répertoire conf (par défaut, ~/anope/conf). + Copiez l'exemple de fichier de configuration (anope.example.conf) en + anope.conf et ouvrez ce dernier avec votre éditeur de texte favori. Il contient toutes les directives de configuration qu'Anope va utiliser en démarrant. Lisez attentivement les instructions contenues dans le fichier. L'utilisation des valeurs par défaut n'est pas toujours @@ -78,7 +78,7 @@ Note : Vous devrez également lire les fichiers README et FAQ ! * IMPORTANT : Sauvegardez vos anciennes bases de données ! * Si vous mettez à jour vers une nouvelle version majeure, recommencez *toujours* toute votre configuration à partir du - fichier example.conf. + fichier anope.example.conf. 3) Configuration de l'IRCd @@ -92,7 +92,7 @@ Note : Vous devrez également lire les fichiers README et FAQ ! sur le port donné dans le bloc link. Des exemples de configurations de bloc link peuvent être trouvés dans - le fichier example.conf pour certains des IRCd les plus populaires. + le fichier anope.example.conf pour certains des IRCd les plus populaires. Souvenez-vous de /rehash votre IRCd pour appliquer les changements. @@ -104,7 +104,7 @@ Note : Vous devrez également lire les fichiers README et FAQ ! 4) Mettre en route Anope Allez dans le répertoire où les fichiers binaires ont été installés - (par défaut, ~/services/bin). Tapez ./services pour lancer Anope. + (par défaut, ~/anope/bin). Tapez ./anope pour lancer Anope. S'il y a des erreurs de syntaxe dans le fichier de configuration, elles seront affichées à l'écran. Corrigez-les jusqu'à ce qu'il n'y en ait @@ -114,7 +114,7 @@ Note : Vous devrez également lire les fichiers README et FAQ ! réseau, car certains IRCds sur certains systèmes peuvent être très lents pour le processus de liaison. Si rien ne se passe après environ une minute, il y a probablement un problème de configuration. Essayez - de lancer Anope en mode debug avec ./services -debug -nofork pour voir + de lancer Anope en mode debug avec ./anope -debug -nofork pour voir toutes les erreurs rencontrées et essayez de les corriger. Si vous avez besoin d'aide pour résoudre des erreurs, n'hésitez pas à @@ -127,7 +127,7 @@ Note : Vous devrez également lire les fichiers README et FAQ ! est toujours en cours d'exécution et de le redémarrer s'il n'est pas. D'abord renommez le script example.chk qui est dans les dossiers - d'Anope (par défaut, ~/services/conf) en services.chk et modifiez-le. + d'Anope (par défaut, ~/anope/conf) en services.chk et modifiez-le. Vous aurez besoin de modifier la partie CONFIGURATION du fichier. Assurez-vous ensuite que le fichier est marqué comme exécutable en tapant chmod +x services.chk et essayez de lancer le script pour voir @@ -138,7 +138,7 @@ Note : Vous devrez également lire les fichiers README et FAQ ! crontab -e. Cela va ouvrir l'éditeur de texte par défaut avec le fichier crontab. Entrez la ligne suivante (avec le chemin correct) : - */5 * * * * /home/ircd/services/conf/services.chk > /dev/null 2>&1 + */5 * * * * /home/ircd/anope/conf/services.chk > /dev/null 2>&1 Le */5 au début signifie "vérifier toutes les 5 minutes". Vous pouvez remplacer le 5 par un autre numéro si vous voulez (mais moins de 60). diff --git a/docs/LANGUAGE b/docs/LANGUAGE index 33fa240fd..24c47124f 100644 --- a/docs/LANGUAGE +++ b/docs/LANGUAGE @@ -25,7 +25,7 @@ Anope Mutli Language Support Anope uses gettext (http://www.gnu.org/software/gettext/) to translate messages for users. To add a new language install gettext and run `msginit -l language -o anope.language.po -i anope.pot`. For example if I was translating to Spanish I could run `msginit -l es_ES -o anope.es_ES.po -i anope.pot`. Open the newly generating .po file and start - translating. Once you are done simply rerun ./Config; make && make install and add the language to your services.conf. + translating. Once you are done simply rerun ./Config; make && make install and add the language to your anope.conf. Note that on Windows it is not quite this simple, windows.cpp must be edited and Anope recompiled and restarted. Poedit (http://www.poedit.net/) is a popular po file editor, and we recommend using it or another editor designed to edit diff --git a/docs/MODULES b/docs/MODULES index 1699d2c52..e73412627 100644 --- a/docs/MODULES +++ b/docs/MODULES @@ -22,7 +22,7 @@ Anope Modules 1. If modules are supported by your system, they will be configured automatically when you run ./Config. The modules will be installed to the modules directory in your data path (by default this will - be ~/services/data/modules). + be ~/anope/data/modules). 2. Compile Anope as usual using ./Config. The "make" process will now compile module support into Anope, and compile the default sample @@ -89,7 +89,7 @@ Anope Modules You can download more useful modules from http://modules.anope.org/. Just grab the module file (usually with a .cpp extension). Place the module - file in your modules (anope-1.9.x/modules/third) folder; although any of + file in your modules (anope-x.x.x/modules/third) folder; although any of the other folders within the modules directory will work. The new modules need to be compiled and installed before you can make @@ -98,7 +98,7 @@ Anope Modules 1. Make sure you're in the main source directory. (usually anope-1.X.XX/) 2. Run ./Config to find and configure modules, then `cd build`. 3. Run `make` to compile Anope, and any modules. - 4. Run `make install` to copy the compiled binaries to the ~/services/ + 4. Run `make install` to copy the compiled binaries to the ~/anope/ directory. You can now use /msg OperServ MODLOAD to load the new modules. diff --git a/docs/MySQL.md b/docs/MySQL.md new file mode 100644 index 000000000..c463c1f00 --- /dev/null +++ b/docs/MySQL.md @@ -0,0 +1,24 @@ +# How to install rfc1459 character set into MySQL: + +Copy data/mysql/rfc1459.xml to your character_sets_dir, identified by + +``` +SHOW VARIABLES LIKE 'character_sets_dir'; +``` + +Add the following charset to Index.xml in the character_sets_dir directory: + +``` +<charset name="rfc1459"> + <collation name="rfc1459_ci" id="800"/> + <collation name="rfc1459_inspircd_ci" id="801" flag="primary"/> +</charset> +``` + +Restart MySQL. + +Now create the database using the appropriate character set: + +``` +CREATE DATABASE anope DEFAULT CHARACTER SET rfc1459 DEFAULT COLLATE rfc1459_inspircd_ci; +``` diff --git a/docs/NEWS b/docs/NEWS deleted file mode 100644 index 1010816cf..000000000 --- a/docs/NEWS +++ /dev/null @@ -1,7 +0,0 @@ -Highlighted News in Anope 1.9 -============================= - -* Added in live updating SQL and the ability to execute commands through SQL -* Re-designed configuration file -* Code refresh / rewrite into C++ - diff --git a/docs/README b/docs/README index 248684648..f47d9eb5c 100644 --- a/docs/README +++ b/docs/README @@ -9,8 +9,6 @@ This program is free but copyrighted software; see the file COPYING for details. Information about Anope may be found at http://www.anope.org/ -Information about Epona may be found at http://www.epona.org/ -Information about Services may be found at http://www.ircservices.esper.net/ Table of Contents ----------------- @@ -171,11 +169,11 @@ Table of Contents * Bahamut 1.4.27 or later (including 1.8) * Charybdis 3.4 or later * Hybrid 8.1 or later - * InspIRCd 1.2 or 2.0 + * InspIRCd 2.0 * ngIRCd 19.2 or later * Plexus 3 or later * Ratbox 2.0.6 or later - * UnrealIRCd 3.2 or 4 + * UnrealIRCd 4 or later Anope could also work with some of the daemons derived by the ones listed above, but there's no support for them if they work or don't work. diff --git a/docs/REDIS b/docs/REDIS deleted file mode 100644 index 54358d16f..000000000 --- a/docs/REDIS +++ /dev/null @@ -1,160 +0,0 @@ -Starting in Anope 1.9.9, Anope has Redis database support (http://redis.io/). -This document explains the data structure used by Anope, and explains how -keyspace notification works. - -This is not a tutorial on how to use Redis, see http://redis.io/documentation -for that. - -Table of Contents ------------------ -1) Data structure -2) Keyspace notifications -3) Examples of modifying, deleting, and creating objects - -1) Data structure - - There are 4 key namespaces in Anope, they are: - - id - The keys in id are used to atomically create object ids for new - objects. For example, if I were to create a new BotInfo I would first: - - redis 127.0.0.1:6379> INCR id:BotInfo - - To get the object ID of the new object. - - ids - The keys in ids contain a set of all object ids of the given type. - For example: - - redis 127.0.0.1:6379> SMEMBERS ids:BotInfo - - Returns "1", "2", "3", "4", "5", "6", "7", "8" because I have 8 bots that - have IDs 1, 2, 3, 4, 5, 6, 7, and 8, respectively. - - hash - The keys in hash are the actual objects, stored as hashes. For - example, if I had just looked up all BotInfo ids and wanted to iterate - over all of them, I woulld start by: - - redis 127.0.0.1:6379> HGETALL hash:BotInfo:1 - - Which gets all keys and values from the hash of type BotInfo with id 1. - This may return: - - "nick" -> "BotServ" - "user" -> "services" - "host" -> "services.anope.org" - "created" -> "1368704765" - - value - The keys in value only exist to aid looking up object IDs. They - are sets of object IDs and are used to map key+value pairs to objects. - For example: - - redis 127.0.0.1:6379> SMEMBERS value:NickAlias:nick:Adam - - Returns a set of object ids of NickAlias objects that have the key - 'nick' set to the value 'Adam' in its hash. Clearly this can only - ever contain at most one object, since it is not possible to have - more than one registered nick with the same name, but other keys - will contain more than one, such as: - - redis 127.0.0.1:6379> SMEMBERS value:NickCore:email:adam@anope.org - - Which would return all accounts with the email "adam@anope.org". - - redis 127.0.0.1:6379> SMEMBERS value:ChanAccess:mask:Adam - - Which would return all access entries set on the account "Adam". - - Behavior similar to SQL's AND, can be achieved using the - SINTER command, which does set intersection on one or more sets. - -2) Keyspace notifications - - Redis 2.7 (unstable) and 2.8 (stable) and newer support keyspace notifications - (http://redis.io/topics/notifications). This allows Redis to notify Anope of - any external changes to objects in the database. Once notified, Anope will - immediately update the object. Otherwise, Anope keeps all objects in memory - and will not regularly read from the databaes once started. - - You can use this to modify objects in Redis and have them immediately reflected - back into Anope. Additionally you can use this feature to run multiple Anope - instances simultaneously from the same database (see also, Redis database - replication). - - To use keyspace notifications you MUST execute - - redis 127.0.0.1:6379> CONFIG SET notify-keyspace-events KA - OK - - or set notify-keyspace-events in redis.conf properly. Anope always executes - CONFIG SET when it first connects. - - If you do not enable keyspace events properly Anope will be UNABLE to see any - object modifications you do. - - The key space ids and value are managed entirely by Anope, you do - not (and should not) modify them. Once you modify the object (hash), Anope will - update them for you to correctly refelect any changes made to the object. - - Finally, always use atomic operations. If you are inserting a new object with - multiple commands, or inserting multiple objects at once, specifically if the - objects depend on each other, you MUST use a transaction. - -3) Examples of modifying, deleting, and creating objects - - These examples will ONLY work if you meet the criteria in section 2. - - If I want to change the email account 'Adam' to 'Adam@anope.org', I would execute the following: - - redis 127.0.0.1:6379> SMEMBERS value:NickCore:display:Adam - - Which returns a value of "1", which is the object id I want to modify. - Now to change the email: - - redis 127.0.0.1:6379> HSET hash:NickCore:1 email Adam@anope.org - - You can now see this in NickServ's INFO command: - -NickServ- Email address: Adam@anope.org - - If I want to drop the account "Adam", I would execute the following: - - redis 127.0.0.1:6379> SMEMBERS value:NickCore:display:Adam - - Which returns a value of "1". I would then check: - - redis 127.0.0.1:6379> SMEMBERS value:NickAlias:nc:Adam - - To see what nicknames depend on this account to exist, as I will - have to remove those too. This returns the values "2", and "3". - - Finally, I can drop the nick using a transaction via: - - redis 127.0.0.1:6379> MULTI - OK - redis 127.0.0.1:6379> DEL hash:NickAlias:2 - QUEUED - redis 127.0.0.1:6379> DEL hash:NickAlias:3 - QUEUED - redis 127.0.0.1:6379> DEL hash:NickCore:1 - QUEUED - redis 127.0.0.1:6379> EXEC - - Or alternatively simply: - - redis 127.0.0.1:6379> DEL hash:NickAlias:2 hash:NickAlias:3 hash:NickCore:1 - - If I wanted to create a BotServ bot, I would execute the following: - - redis 127.0.0.1:6379> INCR id:BotInfo - - Which returns a new object ID for me, in this example it will be "8". - Now I can create the object: - - HMSET hash:BotInfo:8 nick redis user redis host services.anope.org realname "Services for IRC Networks" - - Note if you are using HSET instead of HMSET you will need to use a transaction, as shown in the above example. - If you are watching your services logs you will immediately see: - - USERS: redis!redis@services.anope.org (Services for IRC Networks) connected to the network (services.anope.org) - - And the bot redis will be in BotServ's bot list. - Notice how ids:BotInfo and the value keys are updated automatically. diff --git a/docs/REST.md b/docs/REST.md new file mode 100644 index 000000000..f8e6adf08 --- /dev/null +++ b/docs/REST.md @@ -0,0 +1,245 @@ +# Anope REST API + +Anope provides a RESTful HTTP API through the rest and httpd modules which +expose basic CRUD operations on all of Anope's internal data structures. + +The type names and data structures are the same as is used in the SQL/RDBMS +databaes support, but it otherwise currently not documented. + +The RESTful API documented here is relatively low level and allows you to +construct things that aren't normally possible in Anope, such as creating +nickless accounts or having an accounts display not matched a grouped nicks +name. This would produce weird behavior and not work as expected. It is +your responsibility to not do this. + +As an alternative you may execute commands remotely using the xmlrpc_main +module, which uses Anope's normal command system and is less subject to misuse. + +# Example usage + +## Getting available object types + +``` +$ curl localhost:8080/rest/types +{ + "types": [ + "botinfo", + "xline", + "oper", + "badword", + "channel", + "level", + "mlockmode", + "accesschanaccess", + "akick", + "entrymsg", + "flagschanaccess", + "logsetting", + "modelock", + "csmiscdata", + "cssuspendinfo", + "xopchanaccess", + "vhost", + "hostrequest", + "memoinfo", + "memo", + "memoignore", + "nick", + "account", + "mode", + "nsaccess", + "autojoin", + "nsmiscdata", + "nssuspendinfo", + "forbid", + "ignore", + "operinfo", + "newsitem", + "exception", + "stats" + ] +} +``` + +The types are subject to change, as several are dynamically added via modules, +including third party modules. + +## Listing objects of a type + +Send a GET to /rest/{object type} to return a list of all objects of that type. +For example, to fetch a list of all accounts. + +``` +$ curl localhost:8080/rest/account +{ + "account": [ + { + "display": "Adam", + "pass": "sha256:55ad6396a287df38967de578cbf92788faea8c94cd7d0e4f55eb45257921d75b:3df6978927389fb71a560a232572e5871bd072752eca27f159dc1fdc2462411c", + "email": "adam@sigterm.info", + "id": "10" + }, + { + "display": "Adam2", + "pass": "sha256:4cbb6ec03a8e7401342ee8832f5e4bd2abeb8fc7a007e66e2ac02e0c14f694f0:041167d04d70381e4218781e06b2b57b08165a987aced63f0a8ca8d25ac8ee51", + "email": "adam@anope.org", + "id": "95" + } + ] +} +``` + +## Searching for objects + +You may search for objects by the value of one of their fields, if it is unique. +This is most useful for looking up nicks, accounts, and channels. + +If the field you are searching for is not something commonly looked up by Anope, +which is mostly anything other than nick, account, and channel names, it will +likely cause the SQL database backend to on-the-fly index the field. + +Send a GET request to /rest/{object type}/{field name}/{search} + +``` +$ curl localhost:8080/rest/account/display/Adam +{ + "display": "Adam", + "pass": "sha256:55ad6396a287df38967de578cbf92788faea8c94cd7d0e4f55eb45257921d75b:3df6978927389fb71a560a232572e5871bd072752eca27f159dc1fdc2462411c", + "email": "adam@sigterm.info", + "id": "10" +} +``` + +Which will return the entire object. If it is not found, a non-200 status code is returned, +along with an error message. Error messages are never JSON formatted, but are simple strings. + +## Getting objects + +If you have an object ID, you can also fetch the object by id. + +Send a GET request to /rest/{object type}/{id} + +``` +$ curl localhost:8080/rest/account/10 +{ + "display": "Adam", + "pass": "sha256:55ad6396a287df38967de578cbf92788faea8c94cd7d0e4f55eb45257921d75b:3df6978927389fb71a560a232572e5871bd072752eca27f159dc1fdc2462411c", + "email": "adam@sigterm.info", + "id": "10" +} +``` + +## Updating the value of a field of an existing object + +You may PUT to /rest/{object type}/{id}/{field} data to update the value of a field. + +``` +$ curl -D - -X PUT localhost:8080/rest/account/10/email -d 'adam@anope.org' +HTTP/1.1 200 OK +Date: Sun, 30 Oct 2016 17:17:05 EDT +Server: Anope-2.1 +Content-Type: application/json +Content-Length: 0 +Connection: Close + +``` + +Again, a 200 status code is okay, anything else is an error, and a description is provided in the reply content. +You can now fetch the object back and notice the changed email address. + +## Creating objects + +You can create new objects by POSTing to /rest/{object type} + +``` +$ curl -D - -X POST localhost:8080/rest/account -d '{"display": "Adam3", "email": "Adam@anope.org"}' +HTTP/1.1 201 Created +Date: Sun, 30 Oct 2016 17:39:56 EDT +Server: Anope-2.1 +Content-Type: application/json +Content-Length: 3 +Connection: Close + +126 +``` + +This will return a 201 Ceated, with the body being the object's new id. + +## Deleting objects + +Similarly you can delete objects by sending DELETE to /rest/{object type}/{id}. + +``` +$ curl -D - -X DELETE localhost:8080/rest/account/126 +HTTP/1.1 200 OK +Date: Sun, 30 Oct 2016 17:42:40 EDT +Server: Anope-2.1 +Content-Type: application/json +Content-Length: 0 +Connection: Close +``` + +Due to the way Anope stores its data, deleting any object at any time should be safe, and will not leak +other (perhaps now unreachable) objects. + +# Object References and Relationships + +Object references are represented in the REST API by {type}:{id} + +``` +$ curl localhost:8080/rest/nsaccess/13 +{ + "account": "account:10", + "mask": "Adam@*.gvd.168.192.IP", + "id": "13" +} +``` + +Such as the value of "account" here for this nickserv access entry. Even though object ids within Anope +are global and not specific to the type. As such, if you submit a POST or PUT operation which creates a +field that is a reference, it is expected you supply both the type and id, in this format. + +It is possible to search for object references of a specific type to a given object. This is how all +one-to-many relationships are looked up within Anope. Objects never contain lists of other objects. +There are no join tables, and the objects within the C++ API do not contain collections of other +objects. + +For example: + +``` +$ curl localhost:8080/rest/account/10?refs=nsaccess +{ + "account": [ + { + "account": "account:10", + "mask": "Adam@*.gvd.168.192.IP", + "id": "13" + }, + { + "account": "account:10", + "mask": "adam@anope.org", + "id": "126" + } + ] +} +``` + +This fetches all objects of type nsaccess which have a reference to an account with id 10. Because +the type nsaccess only has one field that is a reference, the result is effectively the account's +NickServ access list. + +Because searching by refs searches object references and not at a field level, in cases of searching +for objects with mutltiple references, you would have to inspect the resulting objects to see if it +is what you want. For example, if you wanted to find all channels owned by a user, you may perform +something like GET /rest/account/10?refs=channel. The channels returned have a reference to the +given account, whether that is the channels founder or something else, like successor, or any other +field possible (that may have even been added by a 3rd party module), is unknown. + +Relationships defined within Anope, that is, the fields on objects which are object references, can +optionally depend on the existance of the object to which they reference. These fields can be seen +within the SQL schema as having foreign keys with ON CASCADE DELETE. When an object is deleted, all +references to it automatically get either NULLed, or the objects which reference it get recursively +deleted too. This is why it is generally safe to delete any object at any time. + +The field "account" on "nsaccess" is one that will cascade delete, which is why if you delete an +account, the access entries for it are automatically also cleaned up. diff --git a/docs/SQLite.md b/docs/SQLite.md new file mode 100644 index 000000000..30e0d7b12 --- /dev/null +++ b/docs/SQLite.md @@ -0,0 +1,43 @@ +# How to modify Anope sqlite databases + +Anope uses a custom SQLite function (anope_canonicalize) for canonicalizing strings for case insensitive comparisons. +It does this by using SQLites support for having indexes on expressions https://www.sqlite.org/expridx.html. + +For example the account table could look like: + +``` +CREATE TABLE `anope_account` ( + `id` INTEGER PRIMARY KEY AUTOINCREMENT, + `display`, + `pass`, + `email`, + `language` +); + +CREATE INDEX idx_display ON `anope_account` (anope_canonicalize(display)); +``` + +So, to do a SELECT which utilizes the indicies, Anope does something like: + +``` +SELECT id FROM `anope_account` WHERE anope_canonicalize(display) = anope_canonicalize('Adam'); +``` + +If you are using your own SQLite instance, like the sqlite command line interface, the anope_canonicalize function +will be missing. To fix this load one of libanope_sqlite_ascii.so, libanope_sqlite_rfc1459_inspircd.so, +or libanope_sqlite_rfc1459.so into SQLite, depending on your casemap configuration. + +``` +sqlite> .load lib/libanope_sqlite_ascii.so +``` + +## Example of registering a new user via SQLite + +``` +BEGIN TRANSACTION; +-- Insert new account +INSERT INTO anope_account (display, email, private, autoop, killprotect) VALUES ('Adam', 'adam@anope.org', 1, 1, 1); +-- Insert nickname, linking it to the account +INSERT INTO anope_nick (nick, account) VALUES ('Adam', last_insert_rowid()); +COMMIT; +``` diff --git a/docs/TOOLS b/docs/TOOLS index c8e92fc70..b1132c505 100644 --- a/docs/TOOLS +++ b/docs/TOOLS @@ -1,26 +1,4 @@ Anope Bundled Tools ------------------- -1) Anope SMTP Client - - Provided with Anope is a simple SMTP client which can be used instead of - programs like SendMail in some cases. - - The SMTP client can be used instead of sendmail for use with Anope's mail - options. To use the SMTP client instead of sendmail, find the line in your - services configuration file (services.conf) that defines sendmailpath. On - that line, change the path to your services installation directory, then - followed by "bin/anopesmtp" and the IP address of a valid SMTP server. It - should look like this: - - sendmailpath = "/home/anope/services/bin/anopesmtp 127.0.0.1" - - If the SMTP client doesn't send mail, or if there's an other problem with - it, you can enable debug mode by passing the --debug flag after the server - address. This should generate a log file of what happened when it tried - to connect to the SMTP server. - - Credits: - Originally written by Dominick Meglio <codemastr@unrealircd.com> - Ported to *nix by Trystan Scott Lee <trystan@nomadirc.net> - +XXX anoperc? diff --git a/docs/WIN32.txt b/docs/WIN32.txt index 071831995..9c3ce91f7 100644 --- a/docs/WIN32.txt +++ b/docs/WIN32.txt @@ -103,7 +103,7 @@ Anope for Windows INSTALL within the Solution Explorer. Right-click on INSTALL and choose Build.
When you have done this, all the files will be installed to where they belong.
- The only thing you need to do is rename "data/example.conf" to be "data/services.conf",
+ The only thing you need to do is rename "data/anope.example.conf" to be "data/anope.conf",
and then follow the steps to set up Anope.
You have now completed the building phase of Anope for Windows. You can
@@ -120,7 +120,7 @@ Anope for Windows Notepad will cause strange characters to appear, and you may not be able to
edit the file correctly.
- Open services.conf, and read through it carefully and adjust the settings
+ Open anope.conf, and read through it carefully and adjust the settings
you think you need to adjust.
If you are unsure of the settings, you can go to the dos command prompt
diff --git a/docs/XMLRPC/xmlrpc.php b/docs/XMLRPC/xmlrpc.php index 51a3ebe9a..872f018be 100644 --- a/docs/XMLRPC/xmlrpc.php +++ b/docs/XMLRPC/xmlrpc.php @@ -6,7 +6,6 @@ * (C) 2003-2017 Anope Team * Contact us at team@anope.org */ - class AnopeXMLRPC { /** |