Index: cleverbox/tags/0.3/LICENSE =================================================================== --- cleverbox/tags/0.3/LICENSE (revision 131) +++ cleverbox/tags/0.3/LICENSE (revision 131) @@ -0,0 +1,674 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. Index: cleverbox/tags/0.3/assets/apache.conf.single =================================================================== --- cleverbox/tags/0.3/assets/apache.conf.single (revision 127) +++ cleverbox/tags/0.3/assets/apache.conf.single (revision 127) @@ -0,0 +1,43 @@ +# +# Client : %(client_name)s +# Project : %(project_name)s +# + +# -- Subversion + + DAV svn + SVNPath %(clients_root)s/%(client_name)s/var/svn/%(project_name)s + AuthType Basic + AuthName "%(client_name)s :: %(project_name)s :: SVN" + + # -- File based authentification + AuthUserFile %(clients_root)s/%(client_name)s/var/svn/%(project_name)s/.htusers + + require valid-user + + +# -- Trac + + SetHandler mod_python + PythonPath "['%(trac_install_dir)s'] + sys.path" + PythonHandler trac.web.modpython_frontend + PythonOption TracEnv %(clients_root)s/%(client_name)s/var/trac/%(project_name)s + PythonOption TracUriRoot /%(client_name)s/%(project_name)s/trac + SetEnv PYTHON_EGG_CACHE %(clients_root)s/%(client_name)s/tmp + + +# Note : the match against "timeline" is needed to provide authenticated RSS feeds (see http://lab.clever-age.net/ticket/35) + + AuthType Basic + AuthName "%(client_name)s :: %(project_name)s :: Trac" + + # -- File based authentification + # -- Users can be used using : + # -- htpasswd2 %(clients_root)s/%(client_name)s/var/trac/%(project_name)s/.htusers + AuthUserFile %(clients_root)s/%(client_name)s/var/trac/%(project_name)s/.htusers + + Require valid-user + + +# -- Files under src/ will be available on the web +AliasMatch /%(client_name)s/%(project_name)s/src(.*) /home/%(client_name)s/htdocs/%(project_name)s$1 Index: cleverbox/tags/0.3/assets/permissions.ini =================================================================== --- cleverbox/tags/0.3/assets/permissions.ini (revision 125) +++ cleverbox/tags/0.3/assets/permissions.ini (revision 125) @@ -0,0 +1,3 @@ +[trac] +authenticated = BROWSER_VIEW CHANGESET_VIEW FILE_VIEW LOG_VIEW MILESTONE_VIEW REPORT_SQL_VIEW REPORT_VIEW ROADMAP_VIEW SEARCH_VIEW TICKET_CREATE TICKET_MODIFY TICKET_VIEW TIMELINE_VIEW WIKI_CREATE WIKI_MODIFY WIKI_VIEW +privileged = TRAC_ADMIN Index: cleverbox/tags/0.3/assets/trac-defaults.ini =================================================================== --- cleverbox/tags/0.3/assets/trac-defaults.ini (revision 129) +++ cleverbox/tags/0.3/assets/trac-defaults.ini (revision 129) @@ -0,0 +1,6 @@ +[attachment] +max_size = 25600 + +[components] +webadmin.* = enabled +themeengine.* = enabled Index: cleverbox/tags/0.3/assets/apache.conf.multi =================================================================== --- cleverbox/tags/0.3/assets/apache.conf.multi (revision 127) +++ cleverbox/tags/0.3/assets/apache.conf.multi (revision 127) @@ -0,0 +1,48 @@ +# +# Client : %(client_name)s +# Project : %(project_name)s +# + + + # -- Virtual host general configuration + ServerName %(client_name)s-%(project_name)s.%(domain_name)s + + # -- Subversion + + DAV svn + SVNPath %(clients_root)s/%(client_name)s/var/svn/%(project_name)s + AuthType Basic + AuthName "%(client_name)s :: %(project_name)s :: SVN" + + # -- File based authentification + AuthUserFile %(clients_root)s/%(client_name)s/var/svn/%(project_name)s/.htusers + + require valid-user + + + # -- Trac + + SetHandler mod_python + PythonPath "['%(trac_install_dir)s'] + sys.path" + PythonHandler trac.web.modpython_frontend + PythonOption TracEnv %(clients_root)s/%(client_name)s/var/trac/%(project_name)s + PythonOption TracUriRoot /%(project_name)s/trac + SetEnv PYTHON_EGG_CACHE %(clients_root)s/%(client_name)s/tmp + + + # Note : the match against "timeline" is needed to provide authenticated RSS feeds (see http://lab.clever-age.net/ticket/35) + + AuthType Basic + AuthName "%(client_name)s :: %(project_name)s :: Trac" + + # -- File based authentification + # -- Users can be used using : + # -- htpasswd2 %(clients_root)s/%(client_name)s/var/trac/%(project_name)s/.htusers + AuthUserFile %(clients_root)s/%(client_name)s/var/trac/%(project_name)s/.htusers + + Require valid-user + + + # -- Files under src/ will be available on the web + AliasMatch /%(project_name)s/src(.*) /home/%(client_name)s/htdocs/%(project_name)s$1 + Index: cleverbox/tags/0.3/scripts/cleverbox-admin =================================================================== --- cleverbox/tags/0.3/scripts/cleverbox-admin (revision 91) +++ cleverbox/tags/0.3/scripts/cleverbox-admin (revision 91) @@ -0,0 +1,6 @@ +#!/usr/bin/env python + +import sys + +from cleverbox.scripts.admin import run +sys.exit(run(sys.argv[1:])) Index: cleverbox/tags/0.3/setup.py =================================================================== --- cleverbox/tags/0.3/setup.py (revision 130) +++ cleverbox/tags/0.3/setup.py (revision 130) @@ -0,0 +1,17 @@ +#!/usr/bin/env python + +from glob import glob +from distutils.core import setup + +setup(name='Cleverbox', + version='0.3', + description='Script for automating multiple trac instances deployment and maintenance.', + author='Tristan Rivoallan', + author_email='trivoallan@clever-age.com', + url='http://www.clever-age.com', + packages=['cleverbox', 'cleverbox.scripts'], + scripts=['scripts/cleverbox-admin'], + data_files=[('/usr/share/cleverbox', glob('assets/*'))], + license='GPL', + install_requires=['setuptools>=0.6b1', 'trac>=0.12'] +) Index: cleverbox/tags/0.3/cleverbox/__init__.py =================================================================== --- cleverbox/tags/0.3/cleverbox/__init__.py (revision 44) +++ cleverbox/tags/0.3/cleverbox/__init__.py (revision 44) @@ -0,0 +1,1 @@ +# -*- coding: utf-8 -*- Index: cleverbox/tags/0.3/cleverbox/CHANGELOG =================================================================== --- cleverbox/tags/0.3/cleverbox/CHANGELOG (revision 85) +++ cleverbox/tags/0.3/cleverbox/CHANGELOG (revision 85) @@ -0,0 +1,7 @@ +Trunk +----- + +Version 0.1 +------------ + +* Initial public release Index: cleverbox/tags/0.3/cleverbox/scripts/admin.py =================================================================== --- cleverbox/tags/0.3/cleverbox/scripts/admin.py (revision 133) +++ cleverbox/tags/0.3/cleverbox/scripts/admin.py (revision 133) @@ -0,0 +1,1056 @@ +# -*- coding: utf-8 -*- + +import cmd +import os +import shlex +import sys +import traceback +import re +from trac import util +from trac.scripts.admin import TracAdmin +import ConfigParser + +_defaults = { + 'env_dir_layout' : ('clients-available', 'clients-enabled', + 'projects-available', 'projects-enabled'), + 'client_dir_layout' : ('htdocs', 'logs', 'tmp', 'uploads', + 'var/svn', 'var/trac'), +} + +_version = 'trunk' + +class CleverboxAdmin(cmd.Cmd): + intro = '' + license = '' + doc_header = 'Cleverbox Admin Console \n' \ + 'Available Commands:\n' + ruler = '' + prompt = "Cleverbox > " + envname = None + __env = None + _date_format = '%Y-%m-%d' + _datetime_format = '%Y-%m-%d %H:%M:%S' + _date_format_hint = 'YYYY-MM-DD' + + _config = None + + def __init__(self, envdir = None): + cmd.Cmd.__init__(self) + if envdir: + self.env_set(os.path.abspath(envdir)) + self.interactive = False + + ## + ## Environment methods + ## + + def env_set(self, envname, env=None): + self.envname = envname + self.prompt = "Cleverbox [%s] > " % self.envname + if env is not None: + self.__env = env + + # Read configuration + self._config = ConfigParser.SafeConfigParser() + self._config.read(os.path.join(self.envname, 'cleverbox.ini')) + + + def env_check(self): + try: + pass + #self.__env = Environment(self.envname) + except: + return 0 + return 1 + + def env_open(self): + try: + if not self.__env: + #self.__env = Environment(self.envname) + return self.__env + except Exception, e: + print 'Failed to open environment.', e + traceback.print_exc() + sys.exit(1) + + def emptyline(self): + pass + + def onecmd(self, line): + try: + rv = cmd.Cmd.onecmd(self, line) or 0 + except SystemExit: + raise + except Exception, e: + print >> sys.stderr, 'Command failed: %s' % e + rv = 2 + if not self.interactive: + return rv + + def run(self): + self.interactive = True + print 'Welcome to cleverbox-admin\n' \ + 'Interactive Cleverbox administration console.\n' \ + "Type: '?' or 'help' for help on commands.\n" + self.cmdloop() + + # + # Configuration related methods + # + def getConfig(self, directive, section): + try: + val = self._config.get(section, directive) + except ConfigParser.NoOptionError, exception: + val = '' + return val + + # + # Commands + # + + ## Environment + _help_initenv = [('initenv', 'Environment initialisation')] + def do_initenv(self, line=None): + print "Environment initialisation in %(env_dir)s" % {'env_dir' : self.envname} + + # Collect local configuration info + collected_infos = {} + + # Path to client dir + default_root = '/var/cleverbox' + collected_infos['clients_root'] = raw_input('Projects directory [%s]> ' % default_root).strip() or default_root + + try : + os.makedirs(collected_infos['clients_root'], 0775) + except IOError, ioexception : + print ioexception + print "** Projects storage dir could not be created." + + # Apache user & group + d_uid = 33 + d_gid = 33 + collected_infos['apache_user'] = raw_input('Webserver user id [%d]> ' % d_uid).strip() or d_uid + collected_infos['apache_group'] = raw_input('Webserver group id [%d]> ' % d_gid).strip() or d_gid + + # SSH user & group + d_uid = '1001' + d_gid = '1001' + collected_infos['ssh_user'] = raw_input('SSH user id [%s]> ' % d_uid).strip() or d_uid + collected_infos['ssh_group'] = raw_input('SSH group id [%s]> ' % d_gid).strip() or d_gid + + # Virtual Host mode : single or multi ? + d_vhost_mode = 'single' + collected_infos['vhost_mode'] = raw_input('Virtual host mode (either "single" or "multi") [%s]> ' % d_vhost_mode).strip() or d_vhost_mode + + if collected_infos['vhost_mode'] == 'multi': + collected_infos['domain'] = raw_input('Domain name > ').strip() + + # Cleverbox assets + d_cleverbox_assets = '/usr/share/cleverbox' + collected_infos['assets_dir'] = raw_input('Cleverbox assets directory [%s]> ' % d_cleverbox_assets).strip() or d_cleverbox_assets + + # Authentication backend password (if any) + collected_infos['authbackend_pass'] = raw_input('Authentication backend password (if any) []> ').strip() or '' + + # Write ini file + self._config.add_section('general') + for directive, value in collected_infos.items() : + self._config.set('general', directive, str(value)) + + trac_infos = {} + d_lib_dir = '/usr/share/python-support/trac' + trac_infos['lib_dir'] = raw_input('Trac libs directory [%s]> ' % d_lib_dir).strip() or d_lib_dir + + d_assets_dir = '/usr/share/trac' + trac_infos['assets_dir'] = raw_input('Trac assets directory [%s]> ' % d_assets_dir).strip() or d_assets_dir + + self._config.add_section('trac') + for directive, value in trac_infos.items() : + self._config.set('trac', directive, str(value)) + + fh_config = open(os.path.join(self.envname, 'cleverbox.ini'), 'w+') + self._config.write(fh_config) + + # Create directory structure + try: + print "\n\tCreating directory structure\n" + env_dirs = [] + for dirname in _defaults['env_dir_layout']: + env_dirs.append( os.path.join(self.envname, dirname) ) + map( os.makedirs, env_dirs ) + except IOError, ioexception : + print ioexception + print "** Environment couldn't be initialized in %(env_dir)s\n" % {'env_dir' : self.envname} + + # Create VERSION file + try: + fd = open( os.path.join(self.envname, 'VERSION'), 'w' ) + fd.write(_version) + finally: + fd.close() + + print + print "Environment successfully initialized\n" + print "You need to add this statement to your apache configuration : \n" \ + "\t'Include %(env_dir)s/clients-enabled/*'\n" % {'env_dir' : self.envname} + + ## help + def do_help(self, line=None): + arg = self._arg_tokenize(line) + + if arg[0]: + try: + doc = getattr(self, "_help_" + arg[0]) + TracAdmin.print_doc(doc) + except AttributeError: + print "No documentation found for %s" % arg[0] + else: + docs = (self._help_client + self._help_project + self._help_initenv) + print 'cleverbox-admin - The Cleverbox Administration Console' + if not self.interactive: + print + print "Usage: cleverbox-admin env_dir [command [subcommand] [option ...]]\n" + print "Invoking cleverbox-admin without command starts "\ + "interactive mode." + TracAdmin.print_doc(docs) + + + # + # "Client" command set + # + _help_client = [('client list', 'Lists available clients'), + ('client add ', 'Adds a client'), + ('client remove ', 'Deletes a client'), + ('client enable ', 'Enables a client'), + ('client disable ', 'Disables a client')] + def do_client(self, line): + args = self._arg_tokenize(line) + if args[0] == 'list': + self._do_client_list() + elif args[0] == 'add' and len(args) == 2: + self._do_client_add(args[1]) + elif args[0] == 'remove' and len(args) == 2: + self._do_client_remove(args[1]) + elif args[0] == 'enable' and len(args) == 2: + self._do_client_enable(args[1]) + elif args[0] == 'disable' and len(args) == 2: + self._do_client_disable(args[1]) + else: + self.do_help('client') + + + def complete_client(self, text, line, begidx, endidx): + ''' + Completions for the client command. + Each client subcommand has its own completion command, named _complete_client_ + ''' + + comp = ['list', 'add', 'remove', 'enable', 'disable'] + parts = self._arg_tokenize(line) + + if len(parts) > 1 and parts[1] in comp: + complete_func = getattr(self, '_complete_client_' + parts[1]) + if (float(sys.version[:3]) < 2.4): + comp = complete_func.__call__(self) + else: + comp = complete_func.__call__() + + return self.word_complete( text, comp ) + + + def _do_client_list(self): + ''' + Displays enabled and disabled clients. + ''' + + print "Enabled :\n" \ + "%s\n\n" \ + "Disabled : \n" \ + "%s\n" % (self._get_clients('enabled'), self._get_clients('disabled')) + + def _do_client_add(self, client_name): + """ + Creates a new client. + * Checks if client not already exists. + * Collects informations about client + * Checks informations are correct + * Create clients environment directory layout + * Creates apache conf for apache + * Inserts client into LDAP + """ + + if not self._client_exists(client_name): + + # Client name cannot contain strokes + if client_name.count('-') != 0: + print "** Client's identifier can not contain the '-' character." + return + + # Information collection + collected_infos = { 'full_name' : None, + 'home_dir' : None, + 'ftp_password' : None } + + collected_infos['home_dir'] = os.path.join(self.getConfig('clients_root', 'general'), client_name) + + # A few checks before effectively creating client + # -- homedir + parent_dir = os.path.normpath(os.path.join(collected_infos['home_dir'], os.pardir)) + dir_is_ok = os.access(parent_dir, os.W_OK) and not os.access(collected_infos['home_dir'], os.R_OK) + if not dir_is_ok: + print "Directory %s is not writable or already exists, aborting." % collected_infos['home_dir'] + raise os.error + + + print + print "Creating a new client." + print "Let's collect some informations about him : " + print + print " Please enter client's full name." + print " This will be used in several interface screens and in emails." + print + + dfn = client_name.capitalize() + collected_infos['full_name'] = raw_input('Full Name [%s]> ' % dfn).strip() or dfn + + print + print "Supplied informations verified." + print "Let's proceed with client creation :" + print + + # Client creation + # -- Homedir layout + homedir_layout = [] + for d in _defaults['client_dir_layout']: + homedir_layout.append( os.path.join(collected_infos['home_dir'], d) ) + map( os.makedirs, homedir_layout ) + + print " Directory layout created in %s\n" % collected_infos['home_dir'] + + # -- Apache configuration + apache_conf = """ +# -- Include enabled projects configuration files +Include %(env_dir)s/projects-enabled/%(client_name)s-* +""" % { 'client_name' : client_name, + 'home_dir' : collected_infos['home_dir'], + 'env_dir' : self.envname } + + # -- Write conf to filesystem + apache_conf_filepath = os.path.join( self.envname, 'clients-available', client_name ) + f = file(apache_conf_filepath, 'w+') + f.write(apache_conf) + f.close() + + print " Apache configuration written to %s\n" % apache_conf_filepath + + # -- Fix permissions + """ + chown -R dev:dev /$CLIENTSROOT/$CLIENTNAME + chown dev:www-data /$CLIENTSROOT/$CLIENTNAME/logs + chmod g+w /$CLIENTSROOT/$CLIENTNAME/logs + chown dev:www-data /$CLIENTSROOT/$CLIENTNAME/uploads + chmod g+w /$CLIENTSROOT/$CLIENTNAME/uploads + """ + self._rchown( collected_infos['home_dir'], + int(self.getConfig('ssh_user', 'general')), + int(self.getConfig('ssh_group', 'general')) ) + os.chown( os.path.join(collected_infos['home_dir'], 'logs'), + int(self.getConfig('ssh_user', 'general')), int(self.getConfig('apache_group', 'general')) ) + os.chmod( os.path.join(collected_infos['home_dir'], 'logs'), 0775 ) + os.chown( os.path.join(collected_infos['home_dir'], 'uploads'), + int(self.getConfig('ssh_user', 'general')), int(self.getConfig('apache_group', 'general')) ) + os.chmod( os.path.join(collected_infos['home_dir'], 'uploads'), 0775 ) + + print " Fixed permissions in %s\n" % collected_infos['home_dir'] + + # Final steps + # -- Enable client ? + print "Client has been created. Do you want to enable it ?" + print + enable_client = raw_input('Enable client ? [y/N]> ').strip() or False + + if enable_client == 'y': + self._do_client_enable(client_name) + + print + print "Client %s was successfully created." % collected_infos['full_name'] + print "Apache configuration need to be reloaded for this to be effective." + print + print "You may want create some projects now. Try 'help project' for some documentation." + print + + else: + print "This client already exists !" + + def _do_client_remove(self, client_name): + """ + Suppression d'un client. + Un client actif ne peut être supprimé. + TODO : suppression du répertoire du client. (bof) + """ + + if self._client_exists(client_name): + continue_removal = False + print "You are about to remove client '%s'." % client_name + confirm_removal = raw_input('Remove client ? [y/N]> ').strip() or False + if confirm_removal == 'y': + continue_removal = True + + if not continue_removal: + print "Client '%s' was *not* removed" % client_name + return + + # Client is enabled, propose disabling it + client_disabled = True + if client_name in self._get_clients('enabled'): + client_disabled = False + print "You can not remove an enabled client. Disabling it." + try: + self._do_client_disable(client_name) + except Exception, e: + print e + + # Disable client's projects + for project_name in self._get_projects(client_name, 'enabled'): + self._do_project_disable((client_name, project_name)) + + # Disable client + client_apacheconf = os.path.join( self.envname, 'clients-available', client_name ) + os.unlink(client_apacheconf) + print "Client '%s' has been removed." % client_name + print "Apache configuration needs to be reloaded for this to be effective." + else: + print "This client does not exist !" + + def _do_client_enable(self, client_name): + enable_client = True + if not self._client_exists(client_name): + print "This client does not exist !" + enable_client = False + + if client_name in self._get_clients('enabled'): + print "This client is already enabled !" + enable_client = False + + if enable_client: + target = os.path.join( self.envname, 'clients-available', client_name ) + linkname = os.path.join( self.envname, 'clients-enabled', client_name ) + os.symlink( target, linkname ) + print "Client '%s' has been enabled" % client_name + print "Apache configuration needs to be reloaded for this to be effective." + else: + print "Client '%s' was *not* enabled" % client_name + + def _do_client_disable(self, client_name): + """ + Disables a client. + TODO : disable client's projects. + """ + disable_client = True + if not self._client_exists(client_name): + print "This client does not exist !" + disable_client = False + + if client_name in self._get_clients('disabled'): + print "This client is already disabled !" + disable_client = False + + if disable_client: + linkname = os.path.join( self.envname, 'clients-enabled', client_name ) + os.unlink( linkname ) + print "Client '%s' has been disabled" % client_name + print "Apache configuration needs to be reloaded for this to be effective." + else: + print "Client '%s' was *not* disabled" % client_name + + + def _complete_client_remove(self): + return self._get_clients() + + def _complete_client_enable(self): + return self._get_clients('disabled') + + def _complete_client_disable(self): + return self._get_clients('enabled') + + + def _client_exists(self, name): + """ + Tells whether or not a client exists. + return bool + """ + return name in self._get_clients() + + def _get_clients(self, only = False): + ''' + Returns a list of clients. + The "only" parameter is used to restrict returned clients list. Recognized values are "enabled" and "disabled". + ''' + + list_clients = [] + + # Each client + if not only: + list_clients = os.listdir(os.path.join(self.envname, 'clients-available')) + + # Only enabled clients + elif only == 'enabled': + list_clients = os.listdir(os.path.join(self.envname, 'clients-enabled')) + + # Only disabled clients (ie. not enabled) + elif only == 'disabled': + + disabled_clients = [] + available_clients = os.listdir(os.path.join(self.envname, 'clients-available')) + enabled_clients = os.listdir(os.path.join(self.envname, 'clients-enabled')) + + # Expect poor performances for this intersection algorithm + # see http://python.project.cwi.nl/search/hypermail/python-recent/0159.html + for e in available_clients: + if e not in enabled_clients: + disabled_clients.append(e) + + list_clients = disabled_clients + + return list_clients + + + # + # Project command set + # + + _help_project = [('project list', 'Lists available projects'), + ('project add ', 'Adds a project'), + ('project remove ', 'Deletes a project'), + ('project enable ', 'Enables a project'), + ('project disable ', 'Disables a project')] + def do_project(self, line): + parts = self._arg_tokenize(line) + try: + do_func = getattr(self, '_do_project_' + parts[0]) + # Python __call__() signature changed in Python2.4 + if ( sys.version[:3] == '2.4'): + do_func.__call__(parts[1:]) + else: + do_func.__call__(self, parts[1:]) + except AttributeError, e: + print e + self.do_help('project') + + def _do_project_list(self, line=None): + """ + TODO : Nicer formatting + """ + + print + print "Available projects :" + print "--------------------" + + client_projects = {} + + clients = self._get_clients() + for client_name in clients: + client_projects[client_name] = self._get_projects(client_name) + + print client_projects + + + def _project_exists(self, client_name, project_name, project_status = None): + return project_name in self._get_projects(client_name, project_status) + + def _get_projects(self, client_name = None, status = None): + """ + TODO : Extend command options in order to provide better filtering (client, enabled / disabled) + """ + list_projects = [] + + # -- List of requested projects + enabled_projects_dir = 'projects-enabled' + all_projects_dir = 'projects-available' + + list_enabled_projects = os.listdir(os.path.join(self.envname, enabled_projects_dir)) + list_all_projects = os.listdir(os.path.join(self.envname, all_projects_dir)) + + list_projects = [] + if (status == None): + list_projects = list_all_projects + if (status == 'enabled'): + list_projects = list_enabled_projects + if (status == 'disabled'): + for p in list_all_projects: + if p not in list_enabled_projects: + list_projects.append(p) + + # Restrict to requested client + pattern = re.compile('(\w+)-(.*)') + if (client_name): + client_projects = [] + for project_name in list_projects: + matches = pattern.findall(project_name) + if (client_name == matches[0][0]): + client_projects.append(matches[0][1]) + list_projects = client_projects + + return list_projects + + def _do_project_disable(self, args): + if len(args) == 2: + (client_name, project_name) = args + if (self._project_exists(client_name, project_name)): + try: + os.unlink( os.path.join(self.envname, 'projects-enabled', '%s-%s' % (client_name, project_name)) ) + print "Project '%s' has been disabled. Apache needs to be reloaded." % project_name + except (IOError, os.error), exception: + print "** Project '%s' is already disabled." % project_name + + else: + print "** Client '%s' has no project '%s'" % (client_name, project_name) + else: + print "** Invalid syntax" + self.do_help('project') + + def _do_project_enable(self, args): + if len(args) == 2: + (client_name, project_name) = args + if self._project_exists(client_name, project_name): + try: + target = os.path.join( self.envname, + 'projects-available', + '%s-%s' % (client_name, project_name) ) + linkname = os.path.join( self.envname, + 'projects-enabled', + '%s-%s' % (client_name, project_name) ) + os.symlink( target, linkname ) + print "Project '%s' has been enabled. Apache needs to be reloaded." % project_name + except Exception, e: + print e + + else: + print "** Client '%s' has no project '%s'" % (client_name, project_name) + else: + print "** Invalid syntax" + self.do_help('project') + + def _do_project_remove(self, args): + print "** TODO : This command has yet to be implemented." + + (client_name, project_name) = args + + # Confirm deletion + continue_removal = False + print "You are about to remove project '%s'." % project_name + confirm_removal = raw_input('Remove project ? [y/N]> ').strip() or False + if confirm_removal == 'y': + continue_removal = True + + if not continue_removal: + print "Project '%s' was *not* removed\n" % project_name + return + + # Disable project + if self._project_exists(client_name, project_name, 'enabled'): + print "You cannot remove an enabled project. Disabling it." + self._do_project_disable(args) + + # Delete apache config file + try: + linkname = os.path.join( self.envname, 'projects-available', '%s-%s'% (client_name, project_name) ) + os.unlink( linkname ) + print "Project '%s' has been removed" % project_name + print "Apache configuration needs to be reloaded for this to be effective." + except (IOError, os.error), exception: + print "** An error occured. Project was NOT removed. Report the following message to the sysadmin." + print exception + + def _do_project_add(self, args): + if len(args) == 2: + client_name = args[0] + project_name = args[1] + + # Make sure client exists + if not self._client_exists(client_name): + print "Client '%s' does not exist !" % client_name + return + # Make sure project does not already exists + if self._project_exists(client_name, project_name): + print "Client '%s' already has a project named '%s'" % (client_name, project_name) + return + + # Information collection + collected_infos = { + 'client' : client_name, + 'short_name' : project_name, + 'full_name' : None + } + + print + print "Creating a new project for client '%s'" % client_name + print "Let's collect some informations about the project :" + print + print " Please enter project's full name." + print " This will be displayed in various places and emails." + print + + dfn = project_name.capitalize() + collected_infos['full_name'] = raw_input('Full Name [%s]> ' % dfn).strip() or dfn + + # Project creation + print + print "Supplied informations verified." + print "Let's proceed with project creation :" + print + + try: + # -- Apache configuration file + self._project_write_apache_conf( collected_infos ) + + # -- Create required dirs + self._project_create_dirs( collected_infos ) + + # -- SVN repository creation + self._project_create_svn_repos( collected_infos ) + + # -- Trac environment initialisation + self._project_trac_initenv( collected_infos ) + + # -- Trac initial permissions + self._project_trac_setperms( collected_infos ) + + # -- Modifies Trac default conf + self._project_trac_defaultconf( collected_infos ) + + # -- Fix perms + self._project_fix_perms( collected_infos ) + + except Exception, e: + print "An error occured :" + print e + traceback.print_exc() + + # -- Enable client ? + print "Project has been created. Do you want to enable it ?" + print + enable_project = raw_input('Enable project ? [y/N]> ').strip() or False + + if enable_project.find('y') == 0: + self._do_project_enable((client_name, project_name)) + + else: + self.do_help('project') + + def _project_create_dirs(self, infos): + os.makedirs(os.path.join(self.getConfig('clients_root', 'general'), + infos['client'], + 'htdocs', + infos['short_name']), 0775) + + print " Creating project's directory layout\n" + + def _project_write_apache_conf(self, infos): + """ + TODO : clients may not be stored in 'clients_root', be careful with that. + """ + conf_template = open('%s/%s.%s' % (self.getConfig('assets_dir', 'general'), 'apache.conf', self.getConfig('vhost_mode', 'general'))) + conf_data = conf_template.read() % {'client_name' : infos['client'], + 'project_name' : infos['short_name'], + 'clients_root' : self.getConfig('clients_root', 'general'), + 'authbackend_pass' : self.getConfig('authbackend_pass', 'general'), + 'trac_install_dir' : self.getConfig('lib_dir', 'trac'), + 'domain_name' : self.getConfig('domain', 'general')} + + apache_conf_filepath = os.path.join( self.envname, 'projects-available', '%s-%s' % (infos['client'], infos['short_name']) ) + f = file(apache_conf_filepath, 'w+') + f.write(conf_data) + f.close() + + print " Apache configuration written to %s\n" % apache_conf_filepath + + def _project_create_svn_repos(self, infos): + repos_path = os.path.join( self.getConfig('clients_root', 'general'), infos['client'], 'var/svn', infos['short_name'] ) + create_cmd = 'svnadmin create %s' % repos_path + (stdin, stdout, stderr) = os.popen3( create_cmd ) + + err = stderr.read() + if err: + raise Exception( err ) + + print " Subversion repository created in %s\n" % repos_path + + def _project_trac_initenv(self, infos): + + trac_env_path = os.path.join( self.getConfig('clients_root', 'general'), + infos['client'], + 'var/trac', + infos['short_name'] ) + + svn_path = os.path.join( self.getConfig('clients_root', 'general'), + infos['client'], + 'var/svn', + infos['short_name'] ) + + cmd_data = { 'env_path' : trac_env_path, + 'title' : '"%s - %s - Trac"' % (infos['client'], infos['short_name']), + 'db_dsn' : 'sqlite:db/trac.db', + 'svn_path' : svn_path, + 'templates_path' : '%s/templates' % self.getConfig('assets_dir', 'trac'), + 'trac_install_dir' : self.getConfig('lib_dir', 'trac')} + + trac_cmd = '/usr/bin/trac-admin %(env_path)s initenv %(title)s %(db_dsn)s svn %(svn_path)s %(templates_path)s' % cmd_data + + (stdin, stdout, stderr) = os.popen3( trac_cmd ) + + err = stderr.read() + if err: + err = stdout.read() + raise Exception( err ) + + print " Trac project initialized in %s\n" % trac_env_path + + def _project_trac_setperms(self, infos): + trac_env_path = os.path.join( self.getConfig('clients_root', 'general'), + infos['client'], + 'var/trac', + infos['short_name'] ) + + # Perms for authenticated users + default_perms = ( 'BROWSER_VIEW', + 'CHANGESET_VIEW', + 'FILE_VIEW', + 'LOG_VIEW', + 'MILESTONE_VIEW', + 'REPORT_SQL_VIEW', + 'REPORT_VIEW', + 'ROADMAP_VIEW', + 'SEARCH_VIEW', + 'TICKET_CREATE', + 'TICKET_MODIFY', + 'TICKET_VIEW', + 'TIMELINE_VIEW', + 'WIKI_CREATE', + 'WIKI_MODIFY', + 'WIKI_VIEW' ) + + trac_perms_cmd = 'trac-admin %(env_path)s permission %(subcommand)s %(subject)s %(perms)s' + + # Remove all anonymous permissions + os.system( trac_perms_cmd % {'env_path' : trac_env_path, + 'subcommand' : 'remove', + 'subject' : 'anonymous', + 'perms' : ' '.join(default_perms)} ) + + # Grant default permissions + perms_config = ConfigParser.SafeConfigParser() + perms_config.read(os.path.join(self.getConfig('assets_dir', 'general'), 'permissions.ini')) + for profile in perms_config.options('trac'): + os.system( trac_perms_cmd % {'env_path' : trac_env_path, + 'subcommand' : 'add', + 'subject' : profile, + 'perms' : perms_config.get('trac', profile)} ) + + # Let user choose who gets admin rights + print " Please enter trac administrator username." + print " This user will be granted full privileges on project's Trac instance." + print + + dan = infos['short_name'] + '-admin' + admin_login = raw_input('Admin Login [%s]> ' % dan).strip() or dan + + os.system( trac_perms_cmd % {'env_path' : trac_env_path, + 'subcommand' : 'add', + 'subject' : admin_login, + 'perms' : 'TRAC_ADMIN'} ) + print + print " Trac initial permissions set (admin rights given to '%s')\n" % admin_login + + def _project_fix_perms(self, infos): + """ + chown -R dev:www-data /$CLIENTSROOT/$CLIENTNAME/var/svn/$PROJECTNAME + chmod g+w /$CLIENTSROOT/$CLIENTNAME/var/svn/$PROJECTNAME + chown -R www-data:dev /$CLIENTSROOT/$CLIENTNAME/var/trac/$PROJECTNAME/db + chown dev:www-data /$CLIENTSROOT/$CLIENTNAME/var/trac/conf/trac.ini + chmod g+w /$CLIENTSROOT/$CLIENTNAME/var/trac/conf/trac.ini + """ + + # Trac DB + trac_db_path = os.path.join( self.getConfig('clients_root', 'general'), + infos['client'], + 'var/trac', + infos['short_name'], + 'db' ) + self._rchown( trac_db_path , int(self.getConfig('apache_user', 'general')), int(self.getConfig('ssh_group', 'general')) ) + + # Trac attachments + trac_attachments_path = os.path.join( self.getConfig('clients_root', 'general'), + infos['client'], + 'var/trac', + infos['short_name'], + 'attachments' ) + + self._rchown( trac_attachments_path , int(self.getConfig('apache_user', 'general')), int(self.getConfig('ssh_group', 'general')) ) + + # Trac conf + trac_ini_path = os.path.join( self.getConfig('clients_root', 'general'), + infos['client'], + 'var','trac', + infos['short_name'], + 'conf','trac.ini' ) + os.chmod( trac_ini_path, 0777 ) + + # Subversion repository + svn_repos_path = os.path.join( self.getConfig('clients_root', 'general'), + infos['client'], + 'var/svn', + infos['short_name'] ) + + self._rchown( svn_repos_path, int(self.getConfig('apache_user', 'general')), int(self.getConfig('ssh_group', 'general')) ) + os.chmod( svn_repos_path, 0775 ) + + print " Perms fixed\n" + + def _project_trac_defaultconf(self, infos): + # New defaults + tracdefaults_config = ConfigParser.SafeConfigParser() + tracdefaults_config.read(os.path.join(self.getConfig('assets_dir', 'general'), 'trac-defaults.ini')) + + # Trac base config file + project_config_path = os.path.join('%s/%s/var/trac/%s/conf/trac.ini' % (self.getConfig('clients_root', 'general'), infos['client'], infos['short_name'])) + tracproject_config = ConfigParser.SafeConfigParser() + tracproject_config.read(project_config_path) + + # Overriding + for section in tracdefaults_config.sections(): + if not tracproject_config.has_section(section): + tracproject_config.add_section(section) + for option in tracdefaults_config.options(section): + tracproject_config.set(section, option, tracdefaults_config.get(section, option)) + + fp = open(project_config_path, 'w+') + tracproject_config.write(fp) + + def complete_project(self, text, line, begidx, endidx): + comp = ['list', 'add', 'remove', 'enable', 'disable'] + parts = self._arg_tokenize(line) + + if len(parts) > 1 and parts[1] in comp: + complete_func = getattr(self, '_complete_project_' + parts[1]) + if (float(sys.version[:3]) < 2.4): + comp = complete_func.__call__(self, parts[2:]) + else: + comp = complete_func.__call__(parts[2:]) + + return self.word_complete(text, comp) + + def _complete_project_add(self, args): + comp = [] + + # "add" subcommand's first argument is client's name + if not args or (len(args) <= 1 and args[0] not in self._get_clients()): + comp = self._get_clients() + + return comp + + def _complete_project_enable(self, args): + comp = [] + + # "enable" subcommand's first argument is client's name + if not args or (len(args) <= 1 and args[0] not in self._get_clients()): + comp = self._get_clients() + # "enable" subcommand second argument is project's name + else : + comp = self._get_projects(args[0], 'disabled') + + return comp + + def _complete_project_disable(self, args): + comp = [] + + # "disable" subcommand's first argument is client's name + if not args or (len(args) <= 1 and args[0] not in self._get_clients()): + comp = self._get_clients() + # "disable" subcommand second argument is project's name + else : + comp = self._get_projects(args[0], 'enabled') + + return comp + + def _complete_project_remove(self, args): + comp = [] + + # "remove" subcommand's first argument is client's name + if not args or (len(args) <= 1 and args[0] not in self._get_clients()): + comp = self._get_clients() + # "remove" subcommand second argument is project's name + else : + comp = self._get_projects(args[0]) + + return comp + + ## Quit / EOF + def do_quit(self, line): + print + sys.exit() + + do_exit = do_quit # Alias + do_EOF = do_quit # Alias + + + + # + # Helpers + # + + def word_complete (self, text, words): + """ + Word completion helper. + """ + return [a for a in words if a.startswith (text)] + + def _rchown(self, directory, uid, gid): + """ + Recursive chown. + """ + try: + if (os.path.isdir(directory)): + os.chown(directory, uid, gid) + direntries = os.listdir(directory) + for direntry in direntries: + direntry = os.path.join(directory, direntry) + if (os.path.isdir(direntry)): + os.chown(direntry, uid, gid) + os.chdir(direntry) + self._rchown(direntry, uid, gid) + else: + os.chown(direntry, uid, gid) + else: + os.chown(directory, uid, gid) + except (IOError, os.error), why: + print "rchown %s: %s" % (str(directory), str(why)) + + def _arg_tokenize (self, argstr): + """ + Command line parameters tokenizer + """ + argstr = util.to_utf8(argstr, sys.stdin.encoding) + return shlex.split(argstr) or [''] + +def run(args): + """Main entry point.""" + admin = CleverboxAdmin() + + if len(args) > 0: + if args[0] in ('-h', '--help', 'help'): + return admin.onecmd("help") + elif args[0] in ('-v','--version','about'): + return admin.onecmd("about") + else: + admin.env_set(os.path.abspath(args[0])) + if len(args) > 1: + s_args = ' '.join(["'%s'" % command_parts for command_parts in args[2:]]) + command = args[1] + ' ' +s_args + return admin.onecmd(command) + else: + while True: + admin.run() + else: + return admin.onecmd("help") + Index: cleverbox/tags/0.3/README =================================================================== --- cleverbox/tags/0.3/README (revision 134) +++ cleverbox/tags/0.3/README (revision 134) @@ -0,0 +1,140 @@ += Cleverbox = + +The Cleverbox sits on top of [http://trac.edgewall.org Trac] and [http://subversion.tigris.org Subversion]. +It provides an interactive shell for deploying and maintaining instances of both projects. + +== Features == + + * Apache configuration templates + * `trac.ini` configuration templates + * Easy to setup + * Easy to use + +== Prerequisites == + + * Python-2.4+ + * Apache-2.0+ + * mod_python-3.0+ + * Trac-0.10+ + * Subversion-1.2+ + +== Installation == + +All operations should be performed as root. + + * Download sources : +{{{ +svn export http://lab.clever-age.net/svn/lab/cleverbox/tags/0.3 +}}} + * Install sources : +{{{ +python setup.py install +}}} + * Create the directory that will hold apache configuration and cleverobx preferences : +{{{ +mkdir /etc/cleverbox +}}} + * Initialize environment : +{{{ +cleverbox-admin /etc/cleverbox initenv +}}} +Provide informations required by script, follow its instructions regarding apache configuration. + +== Basic usage == + +The Cleverbox implements a "client has many projects" model. You must therefore create at least one client prior to creating a new project. + +Full documentation of available commands can be obtained with the command : +{{{ +cleverbox-admin /etc/cleverbox help +}}} + +=== Console launch === + +{{{ +cleverbox-admin /etc/cleverbox +}}} + +=== Client creation === + +If client already exists, you can skip this step. + +{{{ +client add +}}} + +When asked about enabling the client, answer "y" + +=== Project creation === + +{{{ +project add +}}} + + * When asked about the project admin, enter your login + * When asked about enabling the project, answer "y" + +Don't forget to reload Apache. + +== Advanced usage == + +=== Customising Apache configuration templates for your needs === + +When creating a new project, the cleverbox will look for Apache configuration templates in directory referenced by `assets_dir` configuration directive. + +Provided defaults work out of the box, but you may want to use custom configuration templates. +You just have to change the value of `assets_dir` configuration directive and the Cleverbox will look for configuration templates in this new directory. + +The available configuration templates are `apache.conf.single` or `apache.conf.multi` (depending on the value of `vhost_mode` cleverbox directive). + +At project creation, the selected template's variables are subtituted with concrete values : + * `client_name` : client's short name + * `project_name` : project's short name + * `clients_root` : directory holding Subversion and Trac data for each project + * `authbackend_pass` : password for hypothetical authentication backend (ldap, etc) + * `trac_install_dir` : directory where Trac is installed on the server + * `domain_name` : if in "single" `vhost_mode`, host's domain name + +=== Customising `trac-defaults.ini` configuration for your needs === + +This file resides in Cleverbox's `assets_dir` directory. It holds values that will override standard's trac.ini values. + +For instance, you may want The webadmin plugin to be enabled by default in all new project instances. +You just have to add these lines to the file : +{{{ +[components] +webadmin.* = enabled +}}} + +=== Defining defaut permission profiles === + +At project creation, the Cleverbox removes the `anonymous` permission profile and creates new profiles based on the contents of the +`permissions.ini` file (which resides in `assets_dir` directory). Example file : +{{{ +[trac] +authenticated = BROWSER_VIEW CHANGESET_VIEW FILE_VIEW LOG_VIEW MILESTONE_VIEW REPORT_SQL_VIEW REPORT_VIEW ROADMAP_VIEW SEARCH_VIEW TICKET_CREATE TICKET_MODIFY TICKET_VIEW TIMELINE_VIEW WIKI_CREATE WIKI_MODIFY WIKI_VIEW +privileged = TRAC_ADMIN +}}} + +== Roadmap == + +=== 0.4-beta === + + * Integrity checks prior to environment initialisation in `ìnitenv` task + * Better unix rights usage + * Integration of `cleverbox-backup.sh` script + +== Changelog == + +=== 2007-08-07 | trunk === + + * '''[BC BREAK]''' Implemented overridable trac and apache configuration + * Wrote better documentation + * Got read of hardcoded Clever Age stuff + * Implemented distutils installation + * Adopted GPLv3 + * Fixed "Iteration over a non-sequence" bug + +== Maintainer == + +Tristan Rivoallan (trivoallan AT clever-age DOT com)