| | Here are a few questions that people most commonly encounter while setting up, using or starting to develop on Maintain. |
| | |
| | h1. Questions |
| | |
| | h2. General |
| | # [What is Maintain?|#whatsmaintain] |
| | # [What is Maintain NOT?|#whatsnotmaintain] |
| | # [What do I need to run Maintain?|#requirements] |
| | # [How can I contribute to Maintain?|#contributions] |
| | ## [Code?|#contrib-code] |
| | ## [Modules?|#contrib-mods] |
| | ## [Money?|#contrib-money] |
| | # [Are there distro-specific packages of Maintain?|#distro-packages] |
| | |
| | h2. Web Frontend |
| | # [What is phpHtmlLib?|#phphtmllib] |
| | # [How do Skins work?|#skinning] |
| | |
| | h2. Database |
| | # [What databases does Maintain Support?|#databases] |
| | # [What's a DB_DataObject?|#dbdo] |
| | |
| | h2. Module Engine |
| | # [How do I make my own module?|#module] |
| | # [What are modules capable of?|#module-capabilities] |
| | # [What is a "hook"?|#hooks] |
| | # [Whats the difference between an "action" and a "filter"?|#action-vs-filter] |
| | ## [How do I add my own hooks?|#own-hooks] |
| | ## [Where can hooks go?|#hooks-where] |
| | ## [What is a "good" hook?|#good-hook] |
| | # [How does module security work?|#module-security] |
| | |
| | h2. Backend |
| | # [How does Maintain generate TinyDNS Files?|#tiny-how] |
| | ## [When?|#tiny-when] |
| | ## [Where?|#tiny-where] |
| | ## [What TinyDNS files does Maintain generate?|#tiny-what] |
| | # [What DNS servers does Maintain support?|#dns] |
| | # [What do I have to configure for the backend to run correctly?|#backend-configs] |
| | # [What else goes on (besides TinyDNS file generation) in the backend?|#backend-what] |
| | ## [And how do these things work?|#backend-how] |
| | # [How does the CRON job work?|#cron] |
| | ## [How do I set this up?|#cron-setup] |
| | ## [Is there a way to force generation of files?|#force-backend] |
| | # [How does Maintain handle DHCP?|#dhcp] |
| | ## [When?|#dhcp-when] |
| | ## [Where?|#dhcp-where] |
| | |
| | |
| | ---- |
| | h1. Answers |
| | |
| | h2. General |
| | # {anchor:whatsmaintain} *What is Maintain?* |
| |  | dhcpdns |
| | | Maintain is a web-based DHCP and DNS management software. It is most useful for medium to large size computer networks. Maintain lets users set up the network on the frontend interface, and in the backend part, it generates the config files for, by default, [DJBDNS|http://cr.yp.to/djbdns.html] and [ISC DHCP3|http://www.isc.org/products/DHCP/] servers. Through a flexible module system, Maintain can be extended to perform additional operations, such as displaying more information about the network, or building files for additional servers. |
| | # {anchor:whatsnotmaintain} *What is Maintain NOT?* |
 | | cmsraiv |
| | | Maintain is not a [content management system|http://en.wikipedia.org/wiki/Content_management_system]. (Though, of course the module system allows to flexibly manipulate vast parts of the application, technically enabling you to make a "Maintain CMS"). |
| | Maintain is also not a rack inventory program, and even though your "host list" can theoretically serve as an inventory list, there are more appropriate tools out there for this job. |
| | # {anchor:requirements} *What do I need to run Maintain?* |
| | The [INSTALL|https://svn.osuosl.org/public/maintain-project/trunk/INSTALL] document in the Maintain source tree tells you about that. Basically, the components needed are: |
| | #* [Apache|http://apache.org] >= 1.3.29 |
| | #* [PHP|http://php.net] >= 4.3 |
| | #* [MySQL|http://mysql.com] >= 4.1 |
| | #* optional |
| | #** [Perl|http://perl.com] >= 5.6.1 |
| | #** [PHPHTMLLib|http://phphtmllib.newsblob.com] >= 2.5.4 |
| | #** for DNS: [djbdns|http://cr.yp.to/djbdns.html] >= 1.05 |
| | #** for DHCP: [ICS dhcpd|http://www.isc.org/sw/dhcp/] >= 3.0 |
| | # {anchor:contributions} *How can I contribute to Maintain?* |
| | There are quite a few ways to contribute to Maintain. For example, you can contribute code, add a bug report, or just spread the word. Check out the ["get involved!"|http://maintainproject.osuosl.org/get_involved] section on the web site! |
| | ## {anchor:contrib-code} *Code?* |
| | If you want to contribute code to the Maintain core codebase, you are very welcome. Check out the [code contribution guide|Maintain Code Contribution Guide] to get you started. |
| | ## {anchor:contrib-mods} *Modules?* |
| | If you want to extend Maintain by writing your own modules, go ahead. First, you should read the [code contribution guide|Maintain Code Contribution Guide] in order to know some basics of writing code for Maintain. Second, there is an extensive [Module Writing Guide] that will guide you through how modules work, how you can write your own and to make the learning curve for new module writers less steep. |
| | ## {anchor:contrib-money} *Money?* |
| | The Maintain project is a community project started by the [OSU Open Source Lab|http://osuosl.org]. If you like Maintain and you use it for your network, please consider donating to the OSL to support its efforts for the Open Source world. [Click here to learn more about donations for the Open Source Lab|http://osuosl.org/contribute]. |
| | # {anchor:distro-packages} *Are there distro-specific packages of Maintain?* |
| | No, not yet. There are plans on making them, so that you can soon enter |
| | {code:none} |
| | $ apt-get install maintain |
| | {code} |
| | or similar without having to do too much my hand. However, maintaining packages is a lot of work, so we need your help. If you are willing to make Maintain packages for your favorite distribution, [contact us|http://maintainproject.osuosl.org/contacts] about it. Thanks! |
| | |
| | h2. Web Frontend |
| | # {anchor:phphtmllib} *What is phpHtmlLib?* |
| | {quote} |
| | "phpHtmlLib is a set of PHP classes and library functions to help facilitate building, debugging, and rendering of HTML." |
| | {quote} |
| | For more information, see http://phphtmllib.newsblob.com/. |
| | # {anchor:skinning} *How do Skins work?* |
| | There is an extensive [Maintain Skinning Guide|Guide to Maintain's Skinning Interface] explaining you how you can make your own Maintain skin. |
| | |
| | h2. Database |
| | # {anchor:databases} *What databases does Maintain Support?* |
| | Currently, the Maintain code has some [MySQL|http://mysql.com]-specific parts. However most of Maintain is database agnostic. With a few changes, Maintain can therefore be able to run on any database supported by [PEAR:DB|http://pear.php.net/manual/en/package.database.db.intro-dsn.php]. |
| | # {anchor:dbdo} *What's a DB_DataObject?* |
| | [DB_DataObjects|http://pear.php.net/package/DB_DataObject] are an object-oriented [database abstraction layer|http://en.wikipedia.org/wiki/Database_abstraction_layer] for PHP. They are used throughout Maintain to access the database without writing (database-specific) SQL code. |
| | |
| | h2. Module Engine |
| | # {anchor:module} *How do I make my own module?* |
| | Glad you are thinking about extending Maintain's functionality. To make it easier for you to do that, we made two introductory documentation page: First, there is the [code contribution guide|Maintain Code Contribution Guide] that's intending to give you an overview on how to contribute code to the Maintain project in General. Then there is the [Module Writing Guide] that should give you a lot of information on how to write your own, first module. |
| | # {anchor:module-capabilities} *What are modules capable of?* |
| | Generally speaking, modules can extend every single part of Maintain by connecting to so-called "hooks". Wherever there is a hook inside Maintain, modules can connect to it and modify and/or extend how Maintain is behaving. Whenever this part of the code is executed, Maintain will then go through the list of modules that registered themselves to this particular hook and trigger the methods these modules asked for. |
| | # {anchor:hooks} *What is a "hook"?* |
| | A hook is a named place in the Maintain code where modules can define functionality, either additionally or by modifying objects. In order to get called by the module system when this part of the code comes around, it has to register with the hook in advance. For more info on how to do that, read the [module system documentation|Wordpress Style Modules]. |
| | # {anchor:action-vs-filter} *Whats the difference between an "action" and a "filter"?* |
| | This is described in more detail in the [module system documentation|Wordpress Style Modules]. But in short, an *action hook* is used when different modules should be called in a similar manner, like, for example the {{build_dhcp}} hook in the backend which gets called at the time when the DHCP config files should be generated. |
| | A *filter hook* in turn passes on an object to registered module, allowing them to *modify* this object, one after the other. A hook could for example pass a string "Test" to the modules, the first one of which could make the font bold, and another one could remove all vowels. Eventually, the filtered string would be displayed like this: "*Tst*". |
| | ## {anchor:own-hooks}How do I add my own hooks? |
| | ## {anchor:hooks-where}Where can hooks go? |
| | ## {anchor:good-hook}What is a "good" hook? |
| | # {anchor:module-security} *How does module security work?* |
| | There is a [section about module security|Module Writing Guide#module-security] in the [Module Writing Guide]. |
| | |
| | h2. Backend |
| | # {anchor:tiny-how} *How does Maintain generate TinyDNS Files?* |
| | Maintain generates TinyDNS files directly from the Maintain database. It loops through the records you created on the frontend and makes DNS records in a TinyDNS config file for SOA, MX, CNAME, PTR, NS and HOST records. For more information on how the Maintain backend works (in general and with respect to DNS and DHCP), please refer to the [Maintain Backend Description]. |
| | ## {anchor:tiny-when} *When?* |
| | There are currently two/three ways to trigger the backend scripts: |
| | ##* One way is to trigger them from the command line, as an admin. Go to the folder {{maintain/bin/build}} and execute {{./all -p}} which will trigger the backend hooks on all enabled backend modules. |
| | ##* You can do the same with a cron job, triggering the build process, for example, every 10 minutes. |
| | ##* There is also a module called {{kickit}} that gives the admin user a link on the web frontend to trigger a build run from within the web frontend. |
| | ## {anchor:tiny-where} *Where?* |
| | The backend files are all generated in the folder {{maintain/build}} or subdirs thereof. |
| | ## {anchor:tiny-what} *What TinyDNS files does Maintain generate?* |
| | The TinyDNS config files generated by Maintain are the {{data}} file which contains all the DNS records handled by the TinyDNS server. Maintain also generates a {{dnscache}} config file which points a client querying the DNS cache directly to the TinyDNS server if our server is authoritative for that domain. For the relation between (authoritative) nameservers (like TinyDNS) and recursive DNS resolvers (like dnscache) I recommend reading [life with djbdns|http://www.lifewithdjbdns.com/#Resolvers%20and%20Nameservers:%20definitions]. |
| | # {anchor:dns} *What DNS servers does Maintain support?* |
| | Maintain currently mainly supports *djbdns* (or tinydns, how it is sometimes called). However, every standards compliant nameserver is technically supported if you set up a tinydns server to be fed by Maintain and you make your secondary ("slave") name server pull the information from the primary server via [zone transfers|http://en.wikipedia.org/wiki/DNS_zone_transfer] (AXFR). With this constellation, Maintain can support *BIND* name server, for example, which has been successfully used on production system in the past. |
| | # {anchor:backend-configs} *What do I have to configure for the backend to run correctly?* |
| | Almost all modules (not only backend build modules) come with a config file called {{modulename.cfg}} (cf. the [module writing guide|Module Writing Guide#configs]). In order for these modules to work correctly, copy the distributed {{modulename.cfg.dist}} into a new {{modulename.cfg}} file and edit it to fit your needs. |
| | # {anchor:backend-what} *What else goes on (besides TinyDNS file generation) in the backend?* |
| | Technically, modules can extend the backend scripts with all sorts of functionality. Most commonly, also DHCPD3 config files are generated. But there is also a module which makes a database dump, for example. |
| | Note that besides building the config files, most build modules also have a "push" function intended to rsync the generated config file(s) to the servers. They also come with a config option that allows you to execute an arbitrary script at the end of a build process, so that you can remotely restart the DHCP/DNS services or similar. |
| | ## {anchor:backend-how} *And how do these things work?* |
| | People write a module (see the module FAQ below and also the module writing guide linked therein) that registers to one of the [action hooks in the backend|Maintain Module Hooks]. It will then get called by the backend scripts every time the backend process is triggered (either by the admin or by a cron job). |
| | # {anchor:cron} *How does the CRON job work?* |
| | As mentioned [above|#tiny-when], the cron job just triggers the same build command an admin would execute manually. You are free to choose what time intervals you want to run the backend in, or if you want a cron job at all. For more fluctuating networks, 10 to 15 minutes seem reasonable, but if you hardly ever change parts of your network, an hour between runs seems to be reasonable, too. |
| | ## {anchor:cron-setup} *How do I set this up?* |
| | See the various documentations about [crontabs|http://en.wikipedia.org/wiki/Crontab] to find out about the cron job syntax. Generally speaking you want to add a line to your crontab file, similar to: |
| | {code:None} |
| | */10 * * * * /path/to/maintain/bin/build/all -p |
| | {code} |
| | This line, for example, will run the build scripts every ten minutes. |
| | ## {anchor:force-backend} *Is there a way to force generation of files?* |
| | Absolutely. You can either go to the maintain bin folder on the shell and execute the script as an admin, or you can use the {{kickit}} module. |
| | # {anchor:dhcp} *How does Maintain handle DHCP?* |
| | Maintain can generate [DHCP3|http://www.isc.org/products/DHCP/] config files. It takes all the hosts you set up in the web frontend and generates the respective DHCP rules for you. |
| | ## {anchor:dhcp-when} *When?* |
| | Since {{build_dhcp}} is a regular backend build module, it is called, just like {{build_dns}}, from the backend build scripts. |
| | ## {anchor:dhcp-where} *Where?* |
| | {{build_dhcp}} generated a {{dhcpd.conf}} file underneath the {{build}} directory. |
