diff options
45 files changed, 5408 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..1377554e --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*.swp diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..dba13ed2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,661 @@ + GNU AFFERO GENERAL PUBLIC LICENSE + Version 3, 19 November 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU Affero General Public License is a free, copyleft license for +software and other kinds of works, specifically designed to ensure +cooperation with the community in the case of network server software. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +our General Public Licenses are 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. + + 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. + + Developers that use our General Public Licenses protect your rights +with two steps: (1) assert copyright on the software, and (2) offer +you this License which gives you legal permission to copy, distribute +and/or modify the software. + + A secondary benefit of defending all users' freedom is that +improvements made in alternate versions of the program, if they +receive widespread use, become available for other developers to +incorporate. Many developers of free software are heartened and +encouraged by the resulting cooperation. However, in the case of +software used on network servers, this result may fail to come about. +The GNU General Public License permits making a modified version and +letting the public access it on a server without ever releasing its +source code to the public. + + The GNU Affero General Public License is designed specifically to +ensure that, in such cases, the modified source code becomes available +to the community. It requires the operator of a network server to +provide the source code of the modified version running there to the +users of that server. Therefore, public use of a modified version, on +a publicly accessible server, gives the public access to the source +code of the modified version. + + An older license, called the Affero General Public License and +published by Affero, was designed to accomplish similar goals. This is +a different license, not a version of the Affero GPL, but Affero has +released a new version of the Affero GPL which permits relicensing under +this license. + + 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 Affero 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. Remote Network Interaction; Use with the GNU General Public License. + + Notwithstanding any other provision of this License, if you modify the +Program, your modified version must prominently offer all users +interacting with it remotely through a computer network (if your version +supports such interaction) an opportunity to receive the Corresponding +Source of your version by providing access to the Corresponding Source +from a network server at no charge, through some standard or customary +means of facilitating copying of software. This Corresponding Source +shall include the Corresponding Source for any work covered by version 3 +of the GNU General Public License that is incorporated pursuant to the +following paragraph. + + 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 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 work with which it is combined will remain governed by version +3 of the GNU General Public License. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU Affero 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 Affero 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 Affero 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 Affero 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. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) <year> <name of author> + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero 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 Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see <http://www.gnu.org/licenses/>. + +Also add information on how to contact you by electronic and paper mail. + + If your software can interact with users remotely through a computer +network, you should also make sure that it provides a way for users to +get its source. For example, if your program is a web application, its +interface could display a "Source" link that leads users to an archive +of the code. There are many ways you could offer source, and different +solutions will be better for different programs; see section 13 for the +specific requirements. + + 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 AGPL, see +<http://www.gnu.org/licenses/>. @@ -0,0 +1,214 @@ +puppet module for managing tor +============================== + +This module tries to manage tor, making sure it is installed, running, has munin +graphs if desired and allows for configuration of relays, hidden services, exit +policies, etc. + +! Upgrade Notice ! + + previously, if you did not set the $outbound_bindaddress variable, it was being + automatically set to the $listen_address variable. Now this is not being done + and instead you will need to set the $outbound_bindaddress explicitly for it to + be set. + + the tor::relay{} variables $bandwidth_rate and $bandwidth_burst were previously + used for the tor configuration variables RelayBandwidthRate and + RelayBandwidthBurst, these have been renamed to $relay_bandwidth_rate and + $relay_bandwidth_burst. If you were using these, please rename your variables in + your configuration. + + The variables $bandwidth_rate and $bandwidth_burst are now used for the tor + configuration variables BandwidthRate and BandwidthBurst. If you used + $bandwidth_rate or $bandwidth_burst please be aware that these values have + changed and adjust your configuration as necessary. + + The $tor_ensure_version was converted to a parameter for the tor and + tor::daemon classes. + + The $torsocks_ensure_version was converted to a parameter for the + tor::torsocks class. + + The options that used to be settable with the + tor::daemon::global_opts define now are parameters for the + tor::daemon class, and tor::daemon::global_opts was + removed accordingly. + + +Dependencies +============ + +This module needs: + +- the concat module: git://labs.riseup.net/shared-concat + +Usage +===== + +Installing tor +-------------- + +To install tor, simply include the 'tor' class in your manifests: + + class { 'tor': } + +You can specify the $ensure_version class parameter to get a specific +version installed. + +However, if you want to make configuration changes to your tor daemon, you will +want to instead include the 'tor::daemon' class in your manifests, which will +inherit the 'tor' class from above: + + class { '::tor::daemon': } + +You have the following class parameters that you can specify: + +data_dir (default: '/var/lib/tor') +config_file (default: '/etc/tor/torrc') +use_bridges (default: 0) +automap_hosts_on_resolve (default: 0) +log_rules (default: ['notice file /var/log/tor/notices.log']) + +The data_dir will be used for the tor user's $HOME, and the tor DataDirectory +value. + +The config_file will be managed and the daemon restarted when +it changed. + +use_bridges and automap_hosts_on_resolve are used to set the +UseBridges and AutomapHostsOnResolve torrc settings. + +The log_rules can be an array of different Log lines, each will be added to the +config, for example the following will use syslog: + + class { '::tor::daemon': + log_rules => [ 'notice syslog' ], + } + +If you want to set specific options for the tor class, +you may pass them directly to the tor::daemon in your manifests, +e.g.: + + class { '::tor::daemon': + use_munin => true, + automap_hosts_on_resolve => 1, + } + +Configuring socks +----------------- + +To configure tor socks support, you can do the following: + + tor::daemon::socks { "listen_locally": listen_addresses => [ '127.0.0.1' ]; } + +this will setup the SocksListenAddress to be 127.0.0.1. You also can pass the +following options to tor::daemon::socks: + +$port = 0 - SocksPort +$listen_address - can pass multiple values to configure SocksListenAddress lines +$policies - can pass multiple values to configure SocksPolicy lines + +Installing torsocks +------------------- + +To install torsocks, simply include the 'torsocks' class in your manifests: + + class { 'torsocks': } + +You can specify the $ensure_version class parameter to get a specific +version installed. + +Configuring relays +================== + +An example relay configuration: + + tor::daemon::relay { "foobar": + port => 9001, listen_addresses => '192.168.0.1', address => '192.168.0.1', + bandwidth_rate => '256', bandwidth_burst => '256', contact_info => "Foo <collective at example dot com>", + my_family => '<long family string here>' + } + +You have the following options that can be passed to a relay, with the defaults shown: + +$port = 0, +$listen_addresses = [], +$portforwarding = 0, # PortForwarding 0|1, set for opening ports at the router via UPnP. + # Requires 'tor-fw-helper' binary present. +$bandwidth_rate = '', # KB/s, defaulting to using tor's default: 5120KB/s +$bandwidth_burst = '', # KB/s, defaulting to using tor's default: 10240KB/s +$relay_bandwidth_rate = 0, # KB/s, 0 for no limit. +$relay_bandwidth_burst = 0, # KB/s, 0 for no limit. +$accounting_max = 0, # GB, 0 for no limit. +$accounting_start = [], +$contact_info = '', +$my_family = '', # TODO: autofill with other relays +$address = "tor.${domain}", +$bridge_relay = 0, +$ensure = present +$nickname = $name + +Configuring the control +----------------------- + +To pass parameters to configure the ControlPort and the HashedControlPassword, +you would do something like this: + + tor::daemon::control { "foo-control": + port => '80', hashed_control_password => '<somehash>', + ensure => present +} + +Note: you must pass a hashed password to the control port, if you are going to +use it. + + +Configuring hidden services +--------------------------- + +To configure a tor hidden service you can do something like the following: + + tor::daemon::hidden_service { "hidden_ssh": ports => 22 } + +The HiddenServiceDir is set to the ${data_dir}/${name}. + +Configuring directories +----------------------- + +An example directory configuration: + + tor::daemon::directory { 'ssh_directory': + port => 80, listen_address => '192.168.0.1', + port_front_page => '/etc/tor/tor.html' + } + +Configuring exit policies +-------------------------- + +To configure exit policies, you can do the following: + +tor::daemon::exit_policy { "ssh_exit_policy": + accept => "192.168.0.1:22", + reject => "*:*"; + } + } + + +Polipo +====== + +Polipo support can be enabled by doing: + + include tor::polipo + +this will inherit the tor class by default, remove privoxy if its installed, and +install polipo, making sure it is running. + + +Munin +===== + +If you are using munin, and have the puppet munin module installed, you can set +the use_munin parameter to true when defining the tor::daemon class to have +graphs setup for you. + diff --git a/files/munin/tor_connections b/files/munin/tor_connections new file mode 100755 index 00000000..c1d0a928 --- /dev/null +++ b/files/munin/tor_connections @@ -0,0 +1,162 @@ +#!/usr/bin/perl -w +# +# Munin plugin to monitor Tor +# +# Author: Ge van Geldorp <ge@gse.nl> +# +# Parameters understood: +# +# host - Change which host to graph (default localhost) +# port - Change which port to connect to (default 9051) +# password - Plain-text control channel password (see torrc +# HashedControlPassword parameter) +# cookiefile - Name of the file containing the control channel cookie +# (see torrc CookieAuthentication parameter) +# +# Using HashedControlPassword authentication has the problem that you must +# include the plain-text password in the munin config file. To have any +# effect, that file shouldn't be world-readable. +# If you're using CookieAuthentication, you should run this plugin as a user +# which has read access to the tor datafiles. Also note that bugs in versions +# upto and including 0.1.1.20 prevent CookieAuthentication from working. +# +# Usage: place in /etc/munin/node.d/ (or link it there using ln -s) +# +# Parameters understood: +# config (required) +# autoconf (optional - used by munin-config) +# +# +# Magic markers - optional - used by installation scripts and +# munin-config: +# +#%# family=contrib +#%# capabilities=autoconf + +use strict; +use IO::Socket::INET; + +# Config +our $address = $ENV{host} || "localhost"; # Default: localhost +our $port = $ENV{port} || 9051; # Default: 9051 + +# Don't edit below this line + +sub Authenticate +{ + my ($socket) = @_; + my $authline = "AUTHENTICATE"; + if (defined($ENV{cookiefile})) { + if (open(COOKIE, "<$ENV{cookiefile}")) { + binmode COOKIE; + my $cookie; + $authline .= " "; + while (read(COOKIE, $cookie, 32)) { + foreach my $byte (unpack "C*", $cookie) { + $authline .= sprintf "%02x", $byte; + } + } + close COOKIE; + } + } elsif (defined($ENV{password})) { + $authline .= ' "' . $ENV{password} . '"'; + } + print $socket "$authline\r\n"; + my $replyline = <$socket>; + if (substr($replyline, 0, 1) != '2') { + $replyline =~ s/\s*$//; + return "Failed to authenticate: $replyline"; + } + + return; +} + +if ($ARGV[0] and $ARGV[0] eq "autoconf") { + # Try to connect to the daemon + my $socket = IO::Socket::INET->new("$address:$port") + or my $failed = 1; + + if ($failed) { + print "no (failed to connect to $address port $port)\n"; + exit 1; + } + + my $msg = Authenticate($socket); + if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + print "no ($msg)\n"; + exit 1; + } + + print $socket "QUIT\r\n"; + close($socket); + print "yes\n"; + exit 0; +} + +my %connections = ("new", 0, + "launched", 0, + "connected", 0, + "failed", 0, + "closed", 0); + +if ($ARGV[0] and $ARGV[0] eq "config") { + print "graph_title Connections\n"; + print "graph_args -l 0 --base 1000\n"; + print "graph_vlabel connections\n"; + print "graph_category Tor\n"; + print "graph_period second\n"; + print "graph_info This graph shows the number of Tor OR connections.\n"; + + foreach my $status (keys %connections) { + print "$status.label $status\n"; + print "$status.type GAUGE\n"; + print "$status.max 50000\n"; + print "$status.min 0\n"; + } + + exit 0; +} + +my $socket = IO::Socket::INET->new("$address:$port") + or die("Couldn't connect to $address port $port: $!"); + +my $msg = Authenticate($socket); +if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + die "$msg\n"; +} + +print $socket "GETINFO orconn-status\r\n"; +my $replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to get orconn-status info: $replyline\n"; +} + +while (! (($replyline = <$socket>) =~ /^\.\s*$/)) { + my @reply = split(/\s+/, $replyline); + $connections{lc($reply[1])}++; +} +$replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to authenticate: $replyline\n"; +} + +print $socket "QUIT\r\n"; +close($socket); + +while (my ($status, $count) = each(%connections)) { + print "$status.value $count\n"; +} + +exit 0; + +# vim:syntax=perl diff --git a/files/munin/tor_routers b/files/munin/tor_routers new file mode 100755 index 00000000..b977f9aa --- /dev/null +++ b/files/munin/tor_routers @@ -0,0 +1,151 @@ +#!/usr/bin/perl -w +# +# Munin plugin to monitor Tor routers +# +# Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>, based on a plugin by Ge van Geldorp <ge@gse.nl> +# +# Parameters understood: +# +# host - Change which host to graph (default localhost) +# port - Change which port to connect to (default 9051) +# password - Plain-text control channel password (see torrc +# HashedControlPassword parameter) +# cookiefile - Name of the file containing the control channel cookie +# (see torrc CookieAuthentication parameter) +# +# Using HashedControlPassword authentication has the problem that you must +# include the plain-text password in the munin config file. To have any +# effect, that file shouldn't be world-readable. +# If you're using CookieAuthentication, you should run this plugin as a user +# which has read access to the tor datafiles. Also note that bugs in versions +# upto and including 0.1.1.20 prevent CookieAuthentication from working. +# +# Usage: place in /etc/munin/node.d/ (or link it there using ln -s) +# +# Parameters understood: +# config (required) +# autoconf (optional - used by munin-config) +# +# +# Magic markers - optional - used by installation scripts and +# munin-config: +# +#%# family=contrib +#%# capabilities=autoconf + +use strict; +use IO::Socket::INET; + +# Config +our $address = $ENV{host} || "localhost"; # Default: localhost +our $port = $ENV{port} || 9051; # Default: 9051 + +# Don't edit below this line + +sub Authenticate +{ + my ($socket) = @_; + my $authline = "AUTHENTICATE"; + if (defined($ENV{cookiefile})) { + if (open(COOKIE, "<$ENV{cookiefile}")) { + binmode COOKIE; + my $cookie; + $authline .= " "; + while (read(COOKIE, $cookie, 32)) { + foreach my $byte (unpack "C*", $cookie) { + $authline .= sprintf "%02x", $byte; + } + } + close COOKIE; + } + } elsif (defined($ENV{password})) { + $authline .= ' "' . $ENV{password} . '"'; + } + print $socket "$authline\r\n"; + my $replyline = <$socket>; + if (substr($replyline, 0, 1) != '2') { + $replyline =~ s/\s*$//; + return "Failed to authenticate: $replyline"; + } + + return; +} + +if ($ARGV[0] and $ARGV[0] eq "autoconf") { + # Try to connect to the daemon + my $socket = IO::Socket::INET->new("$address:$port") + or my $failed = 1; + + if ($failed) { + print "no (failed to connect to $address port $port)\n"; + exit 1; + } + + my $msg = Authenticate($socket); + if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + print "no ($msg)\n"; + exit 1; + } + + print $socket "QUIT\r\n"; + close($socket); + print "yes\n"; + exit 0; +} + +if ($ARGV[0] and $ARGV[0] eq "config") { + print "graph_title Routers\n"; + print "graph_args -l 0\n"; + print "graph_vlabel routers\n"; + print "graph_category Tor\n"; + print "graph_info This graph shows the number of known Tor ORs.\n"; + + print "ors.label routers\n"; + print "ors.type GAUGE\n"; + print "ors.info The number of known Tor ORs (onion routers)\n"; + + exit 0; +} + +my $socket = IO::Socket::INET->new("$address:$port") + or die("Couldn't connect to $address port $port: $!"); + +my $msg = Authenticate($socket); +if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + die "$msg\n"; +} + +print $socket "GETINFO ns/all\r\n"; +my $replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to get orconn-status info: $replyline\n"; +} + +my $count; +while (! (($replyline = <$socket>) =~ /^\.\s*$/)) { + my @reply = split(/\s+/, $replyline); + $count++ if $reply[0] eq 'r'; +} +$replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to authenticate: $replyline\n"; +} + +print $socket "QUIT\r\n"; +close($socket); + +print "ors.value $count\n"; + +exit 0; + +# vim:syntax=perl diff --git a/files/munin/tor_traffic b/files/munin/tor_traffic new file mode 100755 index 00000000..a72e7d7f --- /dev/null +++ b/files/munin/tor_traffic @@ -0,0 +1,154 @@ +#!/usr/bin/perl -w +# +# Munin plugin to monitor Tor traffic +# +# Author: Ge van Geldorp <ge@gse.nl> +# +# Parameters understood: +# +# host - Change which host to graph (default localhost) +# port - Change which port to connect to (default 9051) +# password - Plain-text control channel password (see torrc +# HashedControlPassword parameter) +# cookiefile - Name of the file containing the control channel cookie +# (see torrc CookieAuthentication parameter) +# +# Using HashedControlPassword authentication has the problem that you must +# include the plain-text password in the munin config file. To have any +# effect, that file shouldn't be world-readable. +# If you're using CookieAuthentication, you should run this plugin as a user +# which has read access to the tor datafiles. Also note that bugs in versions +# upto and including 0.1.1.20 prevent CookieAuthentication from working. +# +# Usage: place in /etc/munin/node.d/ (or link it there using ln -s) +# +# Parameters understood: +# config (required) +# autoconf (optional - used by munin-config) +# +# +# Magic markers - optional - used by installation scripts and +# munin-config: +# +#%# family=contrib +#%# capabilities=autoconf + +use strict; +use IO::Socket::INET; + +# Config +our $address = $ENV{host} || "localhost"; # Default: localhost +our $port = $ENV{port} || 9051; # Default: 9051 + +# Don't edit below this line + +sub Authenticate +{ + my ($socket) = @_; + my $authline = "AUTHENTICATE"; + if (defined($ENV{cookiefile})) { + if (open(COOKIE, "<$ENV{cookiefile}")) { + binmode COOKIE; + my $cookie; + $authline .= " "; + while (read(COOKIE, $cookie, 32)) { + foreach my $byte (unpack "C*", $cookie) { + $authline .= sprintf "%02x", $byte; + } + } + close COOKIE; + } + } elsif (defined($ENV{password})) { + $authline .= ' "' . $ENV{password} . '"'; + } + print $socket "$authline\r\n"; + my $replyline = <$socket>; + if (substr($replyline, 0, 1) != '2') { + $replyline =~ s/\s*$//; + return "Failed to authenticate: $replyline"; + } + + return; +} + +if ($ARGV[0] and $ARGV[0] eq "autoconf") { + # Try to connect to the daemon + my $socket = IO::Socket::INET->new("$address:$port") + or my $failed = 1; + + if ($failed) { + print "no (failed to connect to $address port $port)\n"; + exit 1; + } + + my $msg = Authenticate($socket); + if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + print "no ($msg)\n"; + exit 1; + } + + print $socket "QUIT\r\n"; + close($socket); + print "yes\n"; + exit 0; +} + +if ($ARGV[0] and $ARGV[0] eq "config") { + print "graph_title Traffic\n"; + print "graph_vlabel bytes per \${graph_period} read (-) / written (+)\n"; + print "graph_category Tor\n"; + print "graph_info This graph shows the bandwidth used by Tor.\n"; + + print "read.label byte/s\n"; + print "read.type GAUGE\n"; + print "read.graph no\n"; + print "read.max 10000000\n"; + print "write.label byte/s\n"; + print "write.type GAUGE\n"; + print "write.negative read\n"; + print "write.max 10000000\n"; + + exit 0; +} + +my $socket = IO::Socket::INET->new("$address:$port") + or die("Couldn't connect to $address port $port: $!"); + +my $msg = Authenticate($socket); +if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + die "$msg\n"; +} + +print $socket "SETEVENTS bw\r\n"; +my $replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to get orconn-status info: $replyline\n"; +} + +$replyline = <$socket>; +if (substr($replyline, 0, 1) != '6') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to get bw: $replyline\n"; +} +my @reply = split(/\s+/, $replyline); + +print $socket "SETEVENTS\r\n"; +$replyline = <$socket>; +print $socket "QUIT\r\n"; +close($socket); + +print "read.value $reply[2]\n"; +print "write.value $reply[3]\n"; + +exit 0; + +# vim:syntax=perl diff --git a/files/polipo/polipo.conf b/files/polipo/polipo.conf new file mode 100644 index 00000000..12b10c41 --- /dev/null +++ b/files/polipo/polipo.conf @@ -0,0 +1,164 @@ +# Polipo Configuration from https://svn.torproject.org/svn/torbrowser/trunk/build-scripts/config/polipo.conf +# Managed by puppet. + +### Basic configuration +### ******************* + +# Uncomment one of these if you want to allow remote clients to +# connect: + +# proxyAddress = "::0" # both IPv4 and IPv6 +# proxyAddress = "0.0.0.0" # IPv4 only + +proxyAddress = "127.0.0.1" +proxyPort = 8118 + +# If you do that, you'll want to restrict the set of hosts allowed to +# connect: + +# allowedClients = "127.0.0.1, 134.157.168.57" +# allowedClients = "127.0.0.1, 134.157.168.0/24" + +allowedClients = 127.0.0.1 +allowedPorts = 1-65535 + +# Uncomment this if you want your Polipo to identify itself by +# something else than the host name: + +proxyName = "localhost" + +# Uncomment this if there's only one user using this instance of Polipo: + +cacheIsShared = false + +# Uncomment this if you want to use a parent proxy: + +# parentProxy = "squid.example.org:3128" + +# Uncomment this if you want to use a parent SOCKS proxy: + +socksParentProxy = "localhost:9050" +socksProxyType = socks5 + + +### Memory +### ****** + +# Uncomment this if you want Polipo to use a ridiculously small amount +# of memory (a hundred C-64 worth or so): + +# chunkHighMark = 819200 +# objectHighMark = 128 + +# Uncomment this if you've got plenty of memory: + +# chunkHighMark = 50331648 +# objectHighMark = 16384 + +chunkHighMark = 67108864 + +### On-disk data +### ************ + +# Uncomment this if you want to disable the on-disk cache: + +diskCacheRoot = "" + +# Uncomment this if you want to put the on-disk cache in a +# non-standard location: + +# diskCacheRoot = "~/.polipo-cache/" + +# Uncomment this if you want to disable the local web server: + +localDocumentRoot = "" + +# Uncomment this if you want to enable the pages under /polipo/index? +# and /polipo/servers?. This is a serious privacy leak if your proxy +# is shared. + +# disableIndexing = false +# disableServersList = false + +disableLocalInterface = true +disableConfiguration = true + +### Domain Name System +### ****************** + +# Uncomment this if you want to contact IPv4 hosts only (and make DNS +# queries somewhat faster): +# +# dnsQueryIPv6 = no + +# Uncomment this if you want Polipo to prefer IPv4 to IPv6 for +# double-stack hosts: +# +# dnsQueryIPv6 = reluctantly + +# Uncomment this to disable Polipo's DNS resolver and use the system's +# default resolver instead. If you do that, Polipo will freeze during +# every DNS query: + +dnsUseGethostbyname = yes + + +### HTTP +### **** + +# Uncomment this if you want to enable detection of proxy loops. +# This will cause your hostname (or whatever you put into proxyName +# above) to be included in every request: + +disableVia = true + +# Uncomment this if you want to slightly reduce the amount of +# information that you leak about yourself: + +# censoredHeaders = from, accept-language +# censorReferer = maybe + +censoredHeaders = from,accept-language,x-pad,link +censorReferer = maybe + +# Uncomment this if you're paranoid. This will break a lot of sites, +# though: + +# censoredHeaders = set-cookie, cookie, cookie2, from, accept-language +# censorReferer = true + +# Uncomment this if you want to use Poor Man's Multiplexing; increase +# the sizes if you're on a fast line. They should each amount to a few +# seconds' worth of transfer; if pmmSize is small, you'll want +# pmmFirstSize to be larger. + +# Note that PMM is somewhat unreliable. + +# pmmFirstSize = 16384 +# pmmSize = 8192 + +# Uncomment this if your user-agent does something reasonable with +# Warning headers (most don't): + +# relaxTransparency = maybe + +# Uncomment this if you never want to revalidate instances for which +# data is available (this is not a good idea): + +# relaxTransparency = yes + +# Uncomment this if you have no network: + +# proxyOffline = yes + +# Uncomment this if you want to avoid revalidating instances with a +# Vary header (this is not a good idea): + +# mindlesslyCacheVary = true + +# Suggestions from Incognito configuration +maxConnectionAge = 5m +maxConnectionRequests = 120 +serverMaxSlots = 8 +serverSlots = 2 +tunnelAllowedPorts = 1-65535 diff --git a/files/tor-exit-notice.html b/files/tor-exit-notice.html new file mode 100644 index 00000000..de3be174 --- /dev/null +++ b/files/tor-exit-notice.html @@ -0,0 +1,144 @@ +<?xml version="1.0"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/html;charset=utf-8" /> +<title>This is a Tor Exit Router</title> + +<!-- + +This notice is intended to be placed on a virtual host for a domain that +your Tor exit node IP reverse resolves to so that people who may be about +to file an abuse complaint would check it first before bothering you or +your ISP. Ex: +http://tor-exit.yourdomain.org or http://tor-readme.yourdomain.org. + +This type of setup has proven very effective at reducing abuse complaints +for exit node operators. + +There are a few places in this document that you may want to customize. +They are marked with FIXME. + +--> + +</head> +<body> + +<p style="text-align:center; font-size:xx-large; font-weight:bold">This is a +Tor Exit Router</p> + +<p> +Most likely you are accessing this website because you had some issue with +the traffic coming from this IP. This router is part of the <a +href="https://www.torproject.org/">Tor Anonymity Network</a>, which is +dedicated to <a href="https://www.torproject.org/about/overview">providing +privacy</a> to people who need it most: average computer users. This +router IP should be generating no other traffic, unless it has been +compromised.</p> + + +<!-- FIXME: you should probably grab your own copy of how_tor_works_thumb.png + and serve it locally --> + +<p style="text-align:center"> +<a href="https://www.torproject.org/about/overview"> +<img src="https://www.torproject.org/images/how_tor_works_thumb.png" alt="How Tor works" style="border-style:none"/> +</a></p> + +<p> +Tor sees use by <a href="https://www.torproject.org/about/torusers">many +important segments of the population</a>, including whistle blowers, +journalists, Chinese dissidents skirting the Great Firewall and oppressive +censorship, abuse victims, stalker targets, the US military, and law +enforcement, just to name a few. While Tor is not designed for malicious +computer users, it is true that they can use the network for malicious ends. +In reality however, the actual amount of <a +href="https://www.torproject.org/docs/faq-abuse">abuse</a> is quite low. This +is largely because criminals and hackers have significantly better access to +privacy and anonymity than do the regular users whom they prey upon. Criminals +can and do <a +href="http://voices.washingtonpost.com/securityfix/2008/08/web_fraud_20_tools.html">build, +sell, and trade</a> far larger and <a +href="http://voices.washingtonpost.com/securityfix/2008/08/web_fraud_20_distributing_your.html">more +powerful networks</a> than Tor on a daily basis. Thus, in the mind of this +operator, the social need for easily accessible censorship-resistant private, +anonymous communication trumps the risk of unskilled bad actors, who are +almost always more easily uncovered by traditional police work than by +extensive monitoring and surveillance anyway.</p> + +<p> +In terms of applicable law, the best way to understand Tor is to consider it a +network of routers operating as common carriers, much like the Internet +backbone. However, unlike the Internet backbone routers, Tor routers +explicitly do not contain identifiable routing information about the source of +a packet, and no single Tor node can determine both the origin and destination +of a given transmission.</p> + +<p> +As such, there is little the operator of this router can do to help you track +the connection further. This router maintains no logs of any of the Tor +traffic, so there is little that can be done to trace either legitimate or +illegitimate traffic (or to filter one from the other). Attempts to +seize this router will accomplish nothing.</p> + +<!-- FIXME: US-Only section. Remove if you are a non-US operator --> + +<p> +Furthermore, this machine also serves as a carrier of email, which means that +its contents are further protected under the ECPA. <a +href="http://www4.law.cornell.edu/uscode/html/uscode18/usc_sec_18_00002707----000-.html">18 +USC 2707</a> explicitly allows for civil remedies ($1000/account +<i><b>plus</b></i> legal fees) +in the event of a seizure executed without good faith or probable cause (it +should be clear at this point that traffic with an originating IP address of +FIXME_DNS_NAME should not constitute probable cause to seize the +machine). Similar considerations exist for 1st amendment content on this +machine.</p> + +<!-- FIXME: May or may not be US-only. Some non-US tor nodes have in + fact reported DMCA harassment... --> + +<p> +If you are a representative of a company who feels that this router is being +used to violate the DMCA, please be aware that this machine does not host or +contain any illegal content. Also be aware that network infrastructure +maintainers are not liable for the type of content that passes over their +equipment, in accordance with <a +href="http://www4.law.cornell.edu/uscode/html/uscode17/usc_sec_17_00000512----000-.html">DMCA +"safe harbor" provisions</a>. In other words, you will have just as much luck +sending a takedown notice to the Internet backbone providers. Please consult +<a href="https://www.torproject.org/eff/tor-dmca-response">EFF's prepared +response</a> for more information on this matter.</p> + +<p>For more information, please consult the following documentation:</p> + +<ol> +<li><a href="https://www.torproject.org/about/overview">Tor Overview</a></li> +<li><a href="https://www.torproject.org/docs/faq-abuse">Tor Abuse FAQ</a></li> +<li><a href="https://www.torproject.org/eff/tor-legal-faq">Tor Legal FAQ</a></li> +</ol> + +<p> +That being said, if you still have a complaint about the router, you may +email the <a href="mailto:FIXME_YOUR_EMAIL_ADDRESS">maintainer</a>. If +complaints are related to a particular service that is being abused, I will +consider removing that service from my exit policy, which would prevent my +router from allowing that traffic to exit through it. I can only do this on an +IP+destination port basis, however. Common P2P ports are +already blocked.</p> + +<p> +You also have the option of blocking this IP address and others on +the Tor network if you so desire. The Tor project provides a <a +href="https://check.torproject.org/cgi-bin/TorBulkExitList.py">web service</a> +to fetch a list of all IP addresses of Tor exit nodes that allow exiting to a +specified IP:port combination, and an official <a +href="https://www.torproject.org/tordnsel/dist/">DNSRBL</a> is also available to +determine if a given IP address is actually a Tor exit server. Please +be considerate +when using these options. It would be unfortunate to deny all Tor users access +to your site indefinitely simply because of a few bad apples.</p> + +</body> +</html> diff --git a/files/tor.html b/files/tor.html new file mode 100644 index 00000000..484545b8 --- /dev/null +++ b/files/tor.html @@ -0,0 +1,3157 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="generator" content="AsciiDoc 8.4.5" />
+<title>TOR(1)</title>
+<style type="text/css">
+/* Debug borders */
+p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
+/*
+ border: 1px solid red;
+*/
+}
+
+body {
+ margin: 1em 5% 1em 5%;
+}
+
+a {
+ color: blue;
+ text-decoration: underline;
+}
+a:visited {
+ color: fuchsia;
+}
+
+em {
+ font-style: italic;
+ color: navy;
+}
+
+strong {
+ font-weight: bold;
+ color: #083194;
+}
+
+tt {
+ color: navy;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: #527bbd;
+ font-family: sans-serif;
+ margin-top: 1.2em;
+ margin-bottom: 0.5em;
+ line-height: 1.3;
+}
+
+h1, h2, h3 {
+ border-bottom: 2px solid silver;
+}
+h2 {
+ padding-top: 0.5em;
+}
+h3 {
+ float: left;
+}
+h3 + * {
+ clear: left;
+}
+
+div.sectionbody {
+ font-family: serif;
+ margin-left: 0;
+}
+
+hr {
+ border: 1px solid silver;
+}
+
+p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+ul, ol, li > p {
+ margin-top: 0;
+}
+
+pre {
+ padding: 0;
+ margin: 0;
+}
+
+span#author {
+ color: #527bbd;
+ font-family: sans-serif;
+ font-weight: bold;
+ font-size: 1.1em;
+}
+span#email {
+}
+span#revnumber, span#revdate, span#revremark {
+ font-family: sans-serif;
+}
+
+div#footer {
+ font-family: sans-serif;
+ font-size: small;
+ border-top: 2px solid silver;
+ padding-top: 0.5em;
+ margin-top: 4.0em;
+}
+div#footer-text {
+ float: left;
+ padding-bottom: 0.5em;
+}
+div#footer-badges {
+ float: right;
+ padding-bottom: 0.5em;
+}
+
+div#preamble {
+ margin-top: 1.5em;
+ margin-bottom: 1.5em;
+}
+div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
+div.admonitionblock {
+ margin-top: 1.5em;
+ margin-bottom: 1.5em;
+}
+div.admonitionblock {
+ margin-top: 2.5em;
+ margin-bottom: 2.5em;
+}
+
+div.content { /* Block element content. */
+ padding: 0;
+}
+
+/* Block element titles. */
+div.title, caption.title {
+ color: #527bbd;
+ font-family: sans-serif;
+ font-weight: bold;
+ text-align: left;
+ margin-top: 1.0em;
+ margin-bottom: 0.5em;
+}
+div.title + * {
+ margin-top: 0;
+}
+
+td div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content + div.title {
+ margin-top: 0.0em;
+}
+
+div.sidebarblock > div.content {
+ background: #ffffee;
+ border: 1px solid silver;
+ padding: 0.5em;
+}
+
+div.listingblock > div.content {
+ border: 1px solid silver;
+ background: #f4f4f4;
+ padding: 0.5em;
+}
+
+div.quoteblock {
+ padding-left: 2.0em;
+ margin-right: 10%;
+}
+div.quoteblock > div.attribution {
+ padding-top: 0.5em;
+ text-align: right;
+}
+
+div.verseblock {
+ padding-left: 2.0em;
+ margin-right: 10%;
+}
+div.verseblock > div.content {
+ white-space: pre;
+}
+div.verseblock > div.attribution {
+ padding-top: 0.75em;
+ text-align: left;
+}
+/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
+div.verseblock + div.attribution {
+ text-align: left;
+}
+
+div.admonitionblock .icon {
+ vertical-align: top;
+ font-size: 1.1em;
+ font-weight: bold;
+ text-decoration: underline;
+ color: #527bbd;
+ padding-right: 0.5em;
+}
+div.admonitionblock td.content {
+ padding-left: 0.5em;
+ border-left: 2px solid silver;
+}
+
+div.exampleblock > div.content {
+ border-left: 2px solid silver;
+ padding: 0.5em;
+}
+
+div.imageblock div.content { padding-left: 0; }
+span.image img { border-style: none; }
+a.image:visited { color: white; }
+
+dl {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+dt {
+ margin-top: 0.5em;
+ margin-bottom: 0;
+ font-style: normal;
+ color: navy;
+}
+dd > *:first-child {
+ margin-top: 0.1em;
+}
+
+ul, ol {
+ list-style-position: outside;
+}
+ol.arabic {
+ list-style-type: decimal;
+}
+ol.loweralpha {
+ list-style-type: lower-alpha;
+}
+ol.upperalpha {
+ list-style-type: upper-alpha;
+}
+ol.lowerroman {
+ list-style-type: lower-roman;
+}
+ol.upperroman {
+ list-style-type: upper-roman;
+}
+
+div.compact ul, div.compact ol,
+div.compact p, div.compact p,
+div.compact div, div.compact div {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+}
+
+div.tableblock > table {
+ border: 3px solid #527bbd;
+}
+thead {
+ font-family: sans-serif;
+ font-weight: bold;
+}
+tfoot {
+ font-weight: bold;
+}
+td > div.verse {
+ white-space: pre;
+}
+p.table {
+ margin-top: 0;
+}
+/* Because the table frame attribute is overriden by CSS in most browsers. */
+div.tableblock > table[frame="void"] {
+ border-style: none;
+}
+div.tableblock > table[frame="hsides"] {
+ border-left-style: none;
+ border-right-style: none;
+}
+div.tableblock > table[frame="vsides"] {
+ border-top-style: none;
+ border-bottom-style: none;
+}
+
+
+div.hdlist {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+div.hdlist tr {
+ padding-bottom: 15px;
+}
+dt.hdlist1.strong, td.hdlist1.strong {
+ font-weight: bold;
+}
+td.hdlist1 {
+ vertical-align: top;
+ font-style: normal;
+ padding-right: 0.8em;
+ color: navy;
+}
+td.hdlist2 {
+ vertical-align: top;
+}
+div.hdlist.compact tr {
+ margin: 0;
+ padding-bottom: 0;
+}
+
+.comment {
+ background: yellow;
+}
+
+@media print {
+ div#footer-badges { display: none; }
+}
+
+div#toctitle {
+ color: #527bbd;
+ font-family: sans-serif;
+ font-size: 1.1em;
+ font-weight: bold;
+ margin-top: 1.0em;
+ margin-bottom: 0.1em;
+}
+
+div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+div.toclevel2 {
+ margin-left: 2em;
+ font-size: 0.9em;
+}
+div.toclevel3 {
+ margin-left: 4em;
+ font-size: 0.9em;
+}
+div.toclevel4 {
+ margin-left: 6em;
+ font-size: 0.9em;
+}
+/* Overrides for manpage documents */
+h1 {
+ padding-top: 0.5em;
+ padding-bottom: 0.5em;
+ border-top: 2px solid silver;
+ border-bottom: 2px solid silver;
+}
+h2 {
+ border-style: none;
+}
+div.sectionbody {
+ margin-left: 5%;
+}
+
+@media print {
+ div#toc { display: none; }
+}
+
+/* Workarounds for IE6's broken and incomplete CSS2. */
+
+div.sidebar-content {
+ background: #ffffee;
+ border: 1px solid silver;
+ padding: 0.5em;
+}
+div.sidebar-title, div.image-title {
+ color: #527bbd;
+ font-family: sans-serif;
+ font-weight: bold;
+ margin-top: 0.0em;
+ margin-bottom: 0.5em;
+}
+
+div.listingblock div.content {
+ border: 1px solid silver;
+ background: #f4f4f4;
+ padding: 0.5em;
+}
+
+div.quoteblock-attribution {
+ padding-top: 0.5em;
+ text-align: right;
+}
+
+div.verseblock-content {
+ white-space: pre;
+}
+div.verseblock-attribution {
+ padding-top: 0.75em;
+ text-align: left;
+}
+
+div.exampleblock-content {
+ border-left: 2px solid silver;
+ padding-left: 0.5em;
+}
+
+/* IE6 sets dynamically generated links as visited. */
+div#toc a:visited { color: blue; }
+</style>
+</head>
+<body>
+<div id="header">
+<h1>
+TOR(1) Manual Page
+</h1>
+<h2>NAME</h2>
+<div class="sectionbody">
+<p>tor -
+ The second-generation onion router
+</p>
+</div>
+</div>
+<h2 id="_synopsis">SYNOPSIS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p><strong>tor</strong> [<em>OPTION</em> <em>value</em>]…</p></div>
+</div>
+<h2 id="_description">DESCRIPTION</h2>
+<div class="sectionbody">
+<div class="paragraph"><p><em>tor</em> is a connection-oriented anonymizing communication
+service. Users choose a source-routed path through a set of nodes, and
+negotiate a "virtual circuit" through the network, in which each node
+knows its predecessor and successor, but no others. Traffic flowing down
+the circuit is unwrapped by a symmetric key at each node, which reveals
+the downstream node.<br /></p></div>
+<div class="paragraph"><p>Basically <em>tor</em> provides a distributed network of servers ("onion routers").
+Users bounce their TCP streams — web traffic, ftp, ssh, etc — around the
+routers, and recipients, observers, and even the routers themselves have
+difficulty tracking the source of the stream.</p></div>
+</div>
+<h2 id="_options">OPTIONS</h2>
+<div class="sectionbody">
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>-h</strong>, <strong>-help</strong>
+</dt>
+<dd>
+<p>
+ Display a short help message and exit.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>-f</strong> <em>FILE</em>
+</dt>
+<dd>
+<p>
+ FILE contains further "option value" pairs. (Default: /etc/tor/torrc)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>--hash-password</strong>
+</dt>
+<dd>
+<p>
+ Generates a hashed password for control port access.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>--list-fingerprint</strong>
+</dt>
+<dd>
+<p>
+ Generate your keys and output your nickname and fingerprint.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>--verify-config</strong>
+</dt>
+<dd>
+<p>
+ Verify the configuration file is valid.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>--nt-service</strong>
+</dt>
+<dd>
+<p>
+ <strong>--service [install|remove|start|stop]</strong> Manage the Tor Windows
+ NT/2000/XP service. Current instructions can be found at
+ <a href="https://wiki.torproject.org/noreply/TheOnionRouter/TorFAQ#WinNTService">https://wiki.torproject.org/noreply/TheOnionRouter/TorFAQ#WinNTService</a>
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>--list-torrc-options</strong>
+</dt>
+<dd>
+<p>
+ List all valid options.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>--version</strong>
+</dt>
+<dd>
+<p>
+ Display Tor version and exit.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>--quiet</strong>
+</dt>
+<dd>
+<p>
+ Do not start Tor with a console log unless explicitly requested to do so.
+ (By default, Tor starts out logging messages at level "notice" or higher to
+ the console, until it has parsed its configuration.)
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Other options can be specified either on the command-line (--option
+ value), or in the configuration file (option value or option "value").
+ Options are case-insensitive. C-style escaped characters are allowed inside
+ quoted values. Options on the command line take precedence over
+ options found in the configuration file, except indicated otherwise. To
+ split one configuration entry into multiple lines, use a single \ before
+ the end of the line. Comments can be used in such multiline entries, but
+ they must start at the beginning of a line.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>BandwidthRate</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>
+</dt>
+<dd>
+<p>
+ A token bucket limits the average incoming bandwidth usage on this node to
+ the specified number of bytes per second, and the average outgoing
+ bandwidth usage to that same value. If you want to run a relay in the
+ public network, this needs to be <em>at the very least</em> 20 KB (that is,
+ 20480 bytes). (Default: 5 MB)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>BandwidthBurst</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>
+</dt>
+<dd>
+<p>
+ Limit the maximum token bucket size (also known as the burst) to the given
+ number of bytes in each direction. (Default: 10 MB)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>MaxAdvertisedBandwidth</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>
+</dt>
+<dd>
+<p>
+ If set, we will not advertise more than this amount of bandwidth for our
+ BandwidthRate. Server operators who want to reduce the number of clients
+ who ask to build circuits through them (since this is proportional to
+ advertised bandwidth rate) can thus reduce the CPU demands on their server
+ without impacting network performance.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>RelayBandwidthRate</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>
+</dt>
+<dd>
+<p>
+ If not 0, a separate token bucket limits the average incoming bandwidth
+ usage for _relayed traffic_ on this node to the specified number of bytes
+ per second, and the average outgoing bandwidth usage to that same value.
+ Relayed traffic currently is calculated to include answers to directory
+ requests, but that may change in future versions. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>RelayBandwidthBurst</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>
+</dt>
+<dd>
+<p>
+ If not 0, limit the maximum token bucket size (also known as the burst) for
+ _relayed traffic_ to the given number of bytes in each direction.
+ (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>PerConnBWRate</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>
+</dt>
+<dd>
+<p>
+ If set, do separate rate limiting for each connection from a non-relay.
+ You should never need to change this value, since a network-wide value is
+ published in the consensus and your relay will use that value. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>PerConnBWBurst</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>
+</dt>
+<dd>
+<p>
+ If set, do separate rate limiting for each connection from a non-relay.
+ You should never need to change this value, since a network-wide value is
+ published in the consensus and your relay will use that value. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ConnLimit</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ The minimum number of file descriptors that must be available to the Tor
+ process before it will start. Tor will ask the OS for as many file
+ descriptors as the OS will allow (you can find this by "ulimit -H -n").
+ If this number is less than ConnLimit, then Tor will refuse to start.<br />
+<br />
+ You probably don’t need to adjust this. It has no effect on Windows
+ since that platform lacks getrlimit(). (Default: 1000)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ConstrainedSockets</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set, Tor will tell the kernel to attempt to shrink the buffers for all
+ sockets to the size specified in <strong>ConstrainedSockSize</strong>. This is useful for
+ virtual servers and other environments where system level TCP buffers may
+ be limited. If you’re on a virtual server, and you encounter the "Error
+ creating network socket: No buffer space available" message, you are
+ likely experiencing this problem.<br />
+<br />
+ The preferred solution is to have the admin increase the buffer pool for
+ the host itself via /proc/sys/net/ipv4/tcp_mem or equivalent facility;
+ this configuration option is a second-resort.<br />
+<br />
+ The DirPort option should also not be used if TCP buffers are scarce. The
+ cached directory requests consume additional sockets which exacerbates
+ the problem.<br />
+<br />
+ You should <strong>not</strong> enable this feature unless you encounter the "no buffer
+ space available" issue. Reducing the TCP buffers affects window size for
+ the TCP stream and will reduce throughput in proportion to round trip
+ time on long paths. (Default: 0.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ConstrainedSockSize</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>
+</dt>
+<dd>
+<p>
+ When <strong>ConstrainedSockets</strong> is enabled the receive and transmit buffers for
+ all sockets will be set to this limit. Must be a value between 2048 and
+ 262144, in 1024 byte increments. Default of 8192 is recommended.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ControlPort</strong> <em>PORT</em>|<strong>auto</strong>
+</dt>
+<dd>
+<p>
+ If set, Tor will accept connections on this port and allow those
+ connections to control the Tor process using the Tor Control Protocol
+ (described in control-spec.txt). Note: unless you also specify one or
+ more of <strong>HashedControlPassword</strong> or <strong>CookieAuthentication</strong>,
+ setting this option will cause Tor to allow any process on the local
+ host to control it. (Setting both authentication methods means either
+ method is sufficient to authenticate to Tor.) This
+ option is required for many Tor controllers; most use the value of 9051.
+ Set it to "auto" to have Tor pick a port for you. (Default: 0).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ControlListenAddress</strong> <em>IP</em>[:<em>PORT</em>]
+</dt>
+<dd>
+<p>
+ Bind the controller listener to this address. If you specify a port, bind
+ to this port rather than the one specified in ControlPort. We strongly
+ recommend that you leave this alone unless you know what you’re doing,
+ since giving attackers access to your control listener is really
+ dangerous. (Default: 127.0.0.1) This directive can be specified multiple
+ times to bind to multiple addresses/ports.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ControlSocket</strong> <em>Path</em>
+</dt>
+<dd>
+<p>
+ Like ControlPort, but listens on a Unix domain socket, rather than a TCP
+ socket. (Unix and Unix-like systems only.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ControlSocketsGroupWritable</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If this option is set to 0, don’t allow the filesystem group to read and
+ write unix sockets (e.g. ControlSocket). If the option is set to 1, make
+ the control socket readable and writable by the default GID. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HashedControlPassword</strong> <em>hashed_password</em>
+</dt>
+<dd>
+<p>
+ Allow connections on the control port if they present
+ the password whose one-way hash is <em>hashed_password</em>. You
+ can compute the hash of a password by running "tor --hash-password
+ <em>password</em>". You can provide several acceptable passwords by using more
+ than one HashedControlPassword line.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>CookieAuthentication</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If this option is set to 1, allow connections on the control port
+ when the connecting process knows the contents of a file named
+ "control_auth_cookie", which Tor will create in its data directory. This
+ authentication method should only be used on systems with good filesystem
+ security. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>CookieAuthFile</strong> <em>Path</em>
+</dt>
+<dd>
+<p>
+ If set, this option overrides the default location and file name
+ for Tor’s cookie file. (See CookieAuthentication above.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>CookieAuthFileGroupReadable</strong> <strong>0</strong>|<strong>1</strong>|<em>Groupname</em>
+</dt>
+<dd>
+<p>
+ If this option is set to 0, don’t allow the filesystem group to read the
+ cookie file. If the option is set to 1, make the cookie file readable by
+ the default GID. [Making the file readable by other groups is not yet
+ implemented; let us know if you need this for some reason.] (Default: 0).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ControlPortWriteToFile</strong> <em>Path</em>
+</dt>
+<dd>
+<p>
+ If set, Tor writes the address and port of any control port it opens to
+ this address. Usable by controllers to learn the actual control port
+ when ControlPort is set to "auto".
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ControlPortFileGroupReadable</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If this option is set to 0, don’t allow the filesystem group to read the
+ control port file. If the option is set to 1, make the control port
+ file readable by the default GID. (Default: 0).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DataDirectory</strong> <em>DIR</em>
+</dt>
+<dd>
+<p>
+ Store working data in DIR (Default: /var/lib/tor)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DirServer</strong> [<em>nickname</em>] [<strong>flags</strong>] <em>address</em>:<em>port</em> <em>fingerprint</em>
+</dt>
+<dd>
+<p>
+ Use a nonstandard authoritative directory server at the provided address
+ and port, with the specified key fingerprint. This option can be repeated
+ many times, for multiple authoritative directory servers. Flags are
+ separated by spaces, and determine what kind of an authority this directory
+ is. By default, every authority is authoritative for current ("v2")-style
+ directories, unless the "no-v2" flag is given. If the "v1" flags is
+ provided, Tor will use this server as an authority for old-style (v1)
+ directories as well. (Only directory mirrors care about this.) Tor will
+ use this server as an authority for hidden service information if the "hs"
+ flag is set, or if the "v1" flag is set and the "no-hs" flag is <strong>not</strong> set.
+ Tor will use this authority as a bridge authoritative directory if the
+ "bridge" flag is set. If a flag "orport=<strong>port</strong>" is given, Tor will use the
+ given port when opening encrypted tunnels to the dirserver. Lastly, if a
+ flag "v3ident=<strong>fp</strong>" is given, the dirserver is a v3 directory authority
+ whose v3 long-term signing key has the fingerprint <strong>fp</strong>.<br />
+<br />
+ If no <strong>dirserver</strong> line is given, Tor will use the default directory
+ servers. NOTE: this option is intended for setting up a private Tor
+ network with its own directory authorities. If you use it, you will be
+ distinguishable from other users, because you won’t believe the same
+ authorities they do.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p><strong>AlternateDirAuthority</strong> [<em>nickname</em>] [<strong>flags</strong>] <em>address</em>:<em>port</em> <em>fingerprint</em><br /></p></div>
+<div class="paragraph"><p><strong>AlternateHSAuthority</strong> [<em>nickname</em>] [<strong>flags</strong>] <em>address</em>:<em>port</em> <em>fingerprint</em><br /></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>AlternateBridgeAuthority</strong> [<em>nickname</em>] [<strong>flags</strong>] <em>address</em>:<em>port</em> <em> fingerprint</em>
+</dt>
+<dd>
+<p>
+ As DirServer, but replaces less of the default directory authorities. Using
+ AlternateDirAuthority replaces the default Tor directory authorities, but
+ leaves the hidden service authorities and bridge authorities in place.
+ Similarly, Using AlternateHSAuthority replaces the default hidden service
+ authorities, but not the directory or bridge authorities.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DisableAllSwap</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 1, Tor will attempt to lock all current and future memory pages,
+ so that memory cannot be paged out. Windows, OS X and Solaris are currently
+ not supported. We believe that this feature works on modern Gnu/Linux
+ distributions, and that it should work on *BSD systems (untested). This
+ option requires that you start your Tor as root, and you should use the
+ <strong>User</strong> option to properly reduce Tor’s privileges. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FetchDirInfoEarly</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 1, Tor will always fetch directory information like other
+ directory caches, even if you don’t meet the normal criteria for fetching
+ early. Normal users should leave it off. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FetchDirInfoExtraEarly</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 1, Tor will fetch directory information before other directory
+ caches. It will attempt to download directory information closer to the
+ start of the consensus period. Normal users should leave it off.
+ (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FetchHidServDescriptors</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 0, Tor will never fetch any hidden service descriptors from the
+ rendezvous directories. This option is only useful if you’re using a Tor
+ controller that handles hidden service fetches for you. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FetchServerDescriptors</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 0, Tor will never fetch any network status summaries or server
+ descriptors from the directory servers. This option is only useful if
+ you’re using a Tor controller that handles directory fetches for you.
+ (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FetchUselessDescriptors</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 1, Tor will fetch every non-obsolete descriptor from the
+ authorities that it hears about. Otherwise, it will avoid fetching useless
+ descriptors, for example for routers that are not running. This option is
+ useful if you’re using the contributed "exitlist" script to enumerate Tor
+ nodes that exit to certain addresses. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HTTPProxy</strong> <em>host</em>[:<em>port</em>]
+</dt>
+<dd>
+<p>
+ Tor will make all its directory requests through this host:port (or host:80
+ if port is not specified), rather than connecting directly to any directory
+ servers.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HTTPProxyAuthenticator</strong> <em>username:password</em>
+</dt>
+<dd>
+<p>
+ If defined, Tor will use this username:password for Basic HTTP proxy
+ authentication, as in RFC 2617. This is currently the only form of HTTP
+ proxy authentication that Tor supports; feel free to submit a patch if you
+ want it to support others.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HTTPSProxy</strong> <em>host</em>[:<em>port</em>]
+</dt>
+<dd>
+<p>
+ Tor will make all its OR (SSL) connections through this host:port (or
+ host:443 if port is not specified), via HTTP CONNECT rather than connecting
+ directly to servers. You may want to set <strong>FascistFirewall</strong> to restrict
+ the set of ports you might try to connect to, if your HTTPS proxy only
+ allows connecting to certain ports.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HTTPSProxyAuthenticator</strong> <em>username:password</em>
+</dt>
+<dd>
+<p>
+ If defined, Tor will use this username:password for Basic HTTPS proxy
+ authentication, as in RFC 2617. This is currently the only form of HTTPS
+ proxy authentication that Tor supports; feel free to submit a patch if you
+ want it to support others.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>Socks4Proxy</strong> <em>host</em>[:<em>port</em>]
+</dt>
+<dd>
+<p>
+ Tor will make all OR connections through the SOCKS 4 proxy at host:port
+ (or host:1080 if port is not specified).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>Socks5Proxy</strong> <em>host</em>[:<em>port</em>]
+</dt>
+<dd>
+<p>
+ Tor will make all OR connections through the SOCKS 5 proxy at host:port
+ (or host:1080 if port is not specified).
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p><strong>Socks5ProxyUsername</strong> <em>username</em><br /></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>Socks5ProxyPassword</strong> <em>password</em>
+</dt>
+<dd>
+<p>
+ If defined, authenticate to the SOCKS 5 server using username and password
+ in accordance to RFC 1929. Both username and password must be between 1 and
+ 255 characters.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>KeepalivePeriod</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ To keep firewalls from expiring connections, send a padding keepalive cell
+ every NUM seconds on open connections that are in use. If the connection
+ has no open circuits, it will instead be closed after NUM seconds of
+ idleness. (Default: 5 minutes)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>Log</strong> <em>minSeverity</em>[-<em>maxSeverity</em>] <strong>stderr</strong>|<strong>stdout</strong>|<strong>syslog</strong>
+</dt>
+<dd>
+<p>
+ Send all messages between <em>minSeverity</em> and <em>maxSeverity</em> to the standard
+ output stream, the standard error stream, or to the system log. (The
+ "syslog" value is only supported on Unix.) Recognized severity levels are
+ debug, info, notice, warn, and err. We advise using "notice" in most cases,
+ since anything more verbose may provide sensitive information to an
+ attacker who obtains the logs. If only one severity level is given, all
+ messages of that level or higher will be sent to the listed destination.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>Log</strong> <em>minSeverity</em>[-<em>maxSeverity</em>] <strong>file</strong> <em>FILENAME</em>
+</dt>
+<dd>
+<p>
+ As above, but send log messages to the listed filename. The
+ "Log" option may appear more than once in a configuration file.
+ Messages are sent to all the logs that match their severity
+ level.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p><strong>Log</strong> <strong>[</strong><em>domain</em>,…<strong>]</strong><em>minSeverity</em>[-<em>maxSeverity</em>] … <strong>file</strong> <em>FILENAME</em><br /></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>Log</strong> <strong>[</strong><em>domain</em>,…<strong>]</strong><em>minSeverity</em>[-<em>maxSeverity</em>] … <strong>stderr</strong>|<strong>stdout</strong>|<strong>syslog</strong>
+</dt>
+<dd>
+<p>
+ As above, but select messages by range of log severity <em>and</em> by a
+ set of "logging domains". Each logging domain corresponds to an area of
+ functionality inside Tor. You can specify any number of severity ranges
+ for a single log statement, each of them prefixed by a comma-separated
+ list of logging domains. You can prefix a domain with ~ to indicate
+ negation, and use * to indicate "all domains". If you specify a severity
+ range without a list of domains, it matches all domains.<br />
+<br />
+ This is an advanced feature which is most useful for debugging one or two
+ of Tor’s subsystems at a time.<br />
+<br />
+ The currently recognized domains are: general, crypto, net, config, fs,
+ protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge,
+ acct, hist, and handshake. Domain names are case-insensitive.<br />
+<br />
+ For example, "<tt>Log [handshake]debug [~net,~mm]info notice stdout</tt>" sends
+ to stdout: all handshake messages of any severity, all info-and-higher
+ messages from domains other than networking and memory management, and all
+ messages of severity notice or higher.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>LogMessageDomains</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If 1, Tor includes message domains with each log message. Every log
+ message currently has at least one domain; most currently have exactly
+ one. This doesn’t affect controller log messages. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>OutboundBindAddress</strong> <em>IP</em>
+</dt>
+<dd>
+<p>
+ Make all outbound connections originate from the IP address specified. This
+ is only useful when you have multiple network interfaces, and you want all
+ of Tor’s outgoing connections to use a single one. This setting will be
+ ignored for connections to the loopback addresses (127.0.0.0/8 and ::1).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>PidFile</strong> <em>FILE</em>
+</dt>
+<dd>
+<p>
+ On startup, write our PID to FILE. On clean shutdown, remove
+ FILE.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ProtocolWarnings</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If 1, Tor will log with severity 'warn' various cases of other parties not
+ following the Tor specification. Otherwise, they are logged with severity
+ 'info'. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>RunAsDaemon</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If 1, Tor forks and daemonizes to the background. This option has no effect
+ on Windows; instead you should use the --service command-line option.
+ (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SafeLogging</strong> <strong>0</strong>|<strong>1</strong>|<strong>relay</strong>
+</dt>
+<dd>
+<p>
+ Tor can scrub potentially sensitive strings from log messages (e.g.
+ addresses) by replacing them with the string [scrubbed]. This way logs can
+ still be useful, but they don’t leave behind personally identifying
+ information about what sites a user might have visited.<br />
+<br />
+ If this option is set to 0, Tor will not perform any scrubbing, if it is
+ set to 1, all potentially sensitive strings are replaced. If it is set to
+ relay, all log messages generated when acting as a relay are sanitized, but
+ all messages generated when acting as a client are not. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>User</strong> <em>UID</em>
+</dt>
+<dd>
+<p>
+ On startup, setuid to this user and setgid to their primary group.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HardwareAccel</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If non-zero, try to use built-in (static) crypto hardware acceleration when
+ available. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AccelName</strong> <em>NAME</em>
+</dt>
+<dd>
+<p>
+ When using OpenSSL hardware crypto acceleration attempt to load the dynamic
+ engine of this name. This must be used for any dynamic hardware engine.
+ Names can be verified with the openssl engine command.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AccelDir</strong> <em>DIR</em>
+</dt>
+<dd>
+<p>
+ Specify this option if using dynamic hardware acceleration and the engine
+ implementation library resides somewhere other than the OpenSSL default.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AvoidDiskWrites</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If non-zero, try to write to disk less frequently than we would otherwise.
+ This is useful when running on flash memory or other media that support
+ only a limited number of writes. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TunnelDirConns</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If non-zero, when a directory server we contact supports it, we will build
+ a one-hop circuit and make an encrypted connection via its ORPort.
+ (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>PreferTunneledDirConns</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If non-zero, we will avoid directory servers that don’t support tunneled
+ directory connections, when possible. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>CircuitPriorityHalflife</strong> <em>NUM1</em>
+</dt>
+<dd>
+<p>
+ If this value is set, we override the default algorithm for choosing which
+ circuit’s cell to deliver or relay next. When the value is 0, we
+ round-robin between the active circuits on a connection, delivering one
+ cell from each in turn. When the value is positive, we prefer delivering
+ cells from whichever connection has the lowest weighted cell count, where
+ cells are weighted exponentially according to the supplied
+ CircuitPriorityHalflife value (in seconds). If this option is not set at
+ all, we use the behavior recommended in the current consensus
+ networkstatus. This is an advanced option; you generally shouldn’t have
+ to mess with it. (Default: not set.)
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_client_options">CLIENT OPTIONS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The following options are useful only for clients (that is, if
+<strong>SocksPort</strong> is non-zero):</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>AllowInvalidNodes</strong> <strong>entry</strong>|<strong>exit</strong>|<strong>middle</strong>|<strong>introduction</strong>|<strong>rendezvous</strong>|<strong>…</strong>
+</dt>
+<dd>
+<p>
+ If some Tor servers are obviously not working right, the directory
+ authorities can manually mark them as invalid, meaning that it’s not
+ recommended you use them for entry or exit positions in your circuits. You
+ can opt to use them in some circuit positions, though. The default is
+ "middle,rendezvous", and other choices are not advised.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ExcludeSingleHopRelays</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ This option controls whether circuits built by Tor will include relays with
+ the AllowSingleHopExits flag set to true. If ExcludeSingleHopRelays is set
+ to 0, these relays will be included. Note that these relays might be at
+ higher risk of being seized or observed, so they are not normally
+ included. Also note that relatively few clients turn off this option,
+ so using these relays might make your client stand out.
+ (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>Bridge</strong> <em>IP</em>:<em>ORPort</em> [fingerprint]
+</dt>
+<dd>
+<p>
+ When set along with UseBridges, instructs Tor to use the relay at
+ "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint"
+ is provided (using the same format as for DirServer), we will verify that
+ the relay running at that location has the right fingerprint. We also use
+ fingerprint to look up the bridge descriptor at the bridge authority, if
+ it’s provided and if UpdateBridgesFromAuthority is set too.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>LearnCircuitBuildTimeout</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>CircuitBuildTimeout</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ Try for at most NUM seconds when building circuits. If the circuit isn’t
+ open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this
+ value serves as the initial value to use before a timeout is learned. If
+ LearnCircuitBuildTimeout is 0, this value is the only value used.
+ (Default: 60 seconds.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>CircuitIdleTimeout</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ If we have kept a clean (never used) circuit around for NUM seconds, then
+ close it. This way when the Tor client is entirely idle, it can expire all
+ of its circuits, and then expire its TLS connections. Also, if we end up
+ making a circuit that is not useful for exiting any of the requests we’re
+ receiving, it won’t forever take up a slot in the circuit list. (Default: 1
+ hour.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>CircuitStreamTimeout</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ If non-zero, this option overrides our internal timeout schedule for how
+ many seconds until we detach a stream from a circuit and try a new circuit.
+ If your network is particularly slow, you might want to set this to a
+ number like 60. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ClientOnly</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 1, Tor will under no circumstances run as a server or serve
+ directory requests. The default is to run as a client unless ORPort is
+ configured. (Usually, you don’t need to set this; Tor is pretty smart at
+ figuring out whether you are reliable and high-bandwidth enough to be a
+ useful server.) (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ExcludeNodes</strong> <em>node</em>,<em>node</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ A list of identity fingerprints, nicknames, country codes and address
+ patterns of nodes to avoid when building a circuit.
+ (Example:
+ ExcludeNodes SlowServer, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, {cc}, 255.254.0.0/8)<br />
+<br />
+ By default, this option is treated as a preference that Tor is allowed
+ to override in order to keep working.
+ For example, if you try to connect to a hidden service,
+ but you have excluded all of the hidden service’s introduction points,
+ Tor will connect to one of them anyway. If you do not want this
+ behavior, set the StrictNodes option (documented below). <br />
+<br />
+ Note also that if you are a relay, this (and the other node selection
+ options below) only affects your own circuits that Tor builds for you.
+ Clients can still build circuits through you to any node. Controllers
+ can tell Tor to build circuits through any node.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ExcludeExitNodes</strong> <em>node</em>,<em>node</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ A list of identity fingerprints, nicknames, country codes and address
+ patterns of nodes to never use when picking an exit node---that is, a
+ node that delivers traffic for you outside the Tor network. Note that any
+ node listed in ExcludeNodes is automatically considered to be part of this
+ list too. See also the caveats on the "ExitNodes" option below.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ExitNodes</strong> <em>node</em>,<em>node</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ A list of identity fingerprints, nicknames, country codes and address
+ patterns of nodes to use as exit node---that is, a
+ node that delivers traffic for you outside the Tor network.<br />
+<br />
+ Note that if you list too few nodes here, or if you exclude too many exit
+ nodes with ExcludeExitNodes, you can degrade functionality. For example,
+ if none of the exits you list allows traffic on port 80 or 443, you won’t
+ be able to browse the web.<br />
+<br />
+ Note also that not every circuit is used to deliver traffic outside of
+ the Tor network. It is normal to see non-exit circuits (such as those
+ used to connect to hidden services, those that do directory fetches,
+ those used for relay reachability self-tests, and so on) that end
+ at a non-exit node. To
+ keep a node from being used entirely, see ExcludeNodes and StrictNodes.<br />
+<br />
+ The ExcludeNodes option overrides this option: any node listed in both
+ ExitNodes and ExcludeNodes is treated as excluded.<br />
+<br />
+ The .exit address notation, if enabled via AllowDotExit, overrides
+ this option.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>EntryNodes</strong> <em>node</em>,<em>node</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ A list of identity fingerprints and nicknames of nodes
+ to use for the first hop in your normal circuits. (Country codes and
+ address patterns are not yet supported.) Normal circuits include all
+ circuits except for direct connections to directory servers. The Bridge
+ option overrides this option; if you have configured bridges and
+ UseBridges is 1, the Bridges are used as your entry nodes.<br />
+<br />
+ The ExcludeNodes option overrides this option: any node listed in both
+ EntryNodes and ExcludeNodes is treated as excluded.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>StrictNodes</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If StrictNodes is set to 1, Tor will treat the ExcludeNodes option as a
+ requirement to follow for all the circuits you generate, even if doing so
+ will break functionality for you. If StrictNodes is set to 0, Tor will
+ still try to avoid nodes in the ExcludeNodes list, but it will err on the
+ side of avoiding unexpected errors. Specifically, StrictNodes 0 tells
+ Tor that it is okay to use an excluded node when it is <strong>necessary</strong> to
+ perform relay reachability self-tests, connect to
+ a hidden service, provide a hidden service to a client, fulfill a .exit
+ request, upload directory information, or download directory information.
+ (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FascistFirewall</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If 1, Tor will only create outgoing connections to ORs running on ports
+ that your firewall allows (defaults to 80 and 443; see <strong>FirewallPorts</strong>).
+ This will allow you to run Tor as a client behind a firewall with
+ restrictive policies, but will not allow you to run as a server behind such
+ a firewall. If you prefer more fine-grained control, use
+ ReachableAddresses instead.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FirewallPorts</strong> <em>PORTS</em>
+</dt>
+<dd>
+<p>
+ A list of ports that your firewall allows you to connect to. Only used when
+ <strong>FascistFirewall</strong> is set. This option is deprecated; use ReachableAddresses
+ instead. (Default: 80, 443)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HidServAuth</strong> <em>onion-address</em> <em>auth-cookie</em> [<em>service-name</em>]
+</dt>
+<dd>
+<p>
+ Client authorization for a hidden service. Valid onion addresses contain 16
+ characters in a-z2-7 plus ".onion", and valid auth cookies contain 22
+ characters in A-Za-z0-9+/. The service name is only used for internal
+ purposes, e.g., for Tor controllers. This option may be used multiple times
+ for different hidden services. If a hidden service uses authorization and
+ this option is not set, the hidden service is not accessible. Hidden
+ services can be configured to require authorization using the
+ <strong>HiddenServiceAuthorizeClient</strong> option.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ReachableAddresses</strong> <em>ADDR</em>[/<em>MASK</em>][:<em>PORT</em>]…
+</dt>
+<dd>
+<p>
+ A comma-separated list of IP addresses and ports that your firewall allows
+ you to connect to. The format is as for the addresses in ExitPolicy, except
+ that "accept" is understood unless "reject" is explicitly provided. For
+ example, 'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept
+ *:80' means that your firewall allows connections to everything inside net
+ 99, rejects port 80 connections to net 18, and accepts connections to port
+ 80 otherwise. (Default: 'accept *:*'.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ReachableDirAddresses</strong> <em>ADDR</em>[/<em>MASK</em>][:<em>PORT</em>]…
+</dt>
+<dd>
+<p>
+ Like <strong>ReachableAddresses</strong>, a list of addresses and ports. Tor will obey
+ these restrictions when fetching directory information, using standard HTTP
+ GET requests. If not set explicitly then the value of
+ <strong>ReachableAddresses</strong> is used. If <strong>HTTPProxy</strong> is set then these
+ connections will go through that proxy.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ReachableORAddresses</strong> <em>ADDR</em>[/<em>MASK</em>][:<em>PORT</em>]…
+</dt>
+<dd>
+<p>
+ Like <strong>ReachableAddresses</strong>, a list of addresses and ports. Tor will obey
+ these restrictions when connecting to Onion Routers, using TLS/SSL. If not
+ set explicitly then the value of <strong>ReachableAddresses</strong> is used. If
+ <strong>HTTPSProxy</strong> is set then these connections will go through that proxy.<br />
+<br />
+ The separation between <strong>ReachableORAddresses</strong> and
+ <strong>ReachableDirAddresses</strong> is only interesting when you are connecting
+ through proxies (see <strong>HTTPProxy</strong> and <strong>HTTPSProxy</strong>). Most proxies limit
+ TLS connections (which Tor uses to connect to Onion Routers) to port 443,
+ and some limit HTTP GET requests (which Tor uses for fetching directory
+ information) to port 80.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>LongLivedPorts</strong> <em>PORTS</em>
+</dt>
+<dd>
+<p>
+ A list of ports for services that tend to have long-running connections
+ (e.g. chat and interactive shells). Circuits for streams that use these
+ ports will contain only high-uptime nodes, to reduce the chance that a node
+ will go down before the stream is finished. (Default: 21, 22, 706, 1863,
+ 5050, 5190, 5222, 5223, 6667, 6697, 8300)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>MapAddress</strong> <em>address</em> <em>newaddress</em>
+</dt>
+<dd>
+<p>
+ When a request for address arrives to Tor, it will rewrite it to newaddress
+ before processing it. For example, if you always want connections to
+ www.indymedia.org to exit via <em>torserver</em> (where <em>torserver</em> is the
+ nickname of the server), use "MapAddress www.indymedia.org
+ www.indymedia.org.torserver.exit".
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>NewCircuitPeriod</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ Every NUM seconds consider whether to build a new circuit. (Default: 30
+ seconds)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>MaxCircuitDirtiness</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ Feel free to reuse a circuit that was first used at most NUM seconds ago,
+ but never attach a new stream to a circuit that is too old. (Default: 10
+ minutes)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>NodeFamily</strong> <em>node</em>,<em>node</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ The Tor servers, defined by their identity fingerprints or nicknames,
+ constitute a "family" of similar or co-administered servers, so never use
+ any two of them in the same circuit. Defining a NodeFamily is only needed
+ when a server doesn’t list the family itself (with MyFamily). This option
+ can be used multiple times.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>EnforceDistinctSubnets</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If 1, Tor will not put two servers whose IP addresses are "too close" on
+ the same circuit. Currently, two addresses are "too close" if they lie in
+ the same /16 range. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SocksPort</strong> <em>PORT</em>|<strong>auto</strong>
+</dt>
+<dd>
+<p>
+ Advertise this port to listen for connections from Socks-speaking
+ applications. Set this to 0 if you don’t want to allow application
+ connections via SOCKS. Set it to "auto" to have Tor pick a port for
+ you. (Default: 9050)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SocksListenAddress</strong> <em>IP</em>[:<em>PORT</em>]
+</dt>
+<dd>
+<p>
+ Bind to this address to listen for connections from Socks-speaking
+ applications. (Default: 127.0.0.1) You can also specify a port (e.g.
+ 192.168.0.1:9100). This directive can be specified multiple times to bind
+ to multiple addresses/ports.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SocksPolicy</strong> <em>policy</em>,<em>policy</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ Set an entrance policy for this server, to limit who can connect to the
+ SocksPort and DNSPort ports. The policies have the same form as exit
+ policies below.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SocksTimeout</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ Let a socks connection wait NUM seconds handshaking, and NUM seconds
+ unattached waiting for an appropriate circuit, before we fail it. (Default:
+ 2 minutes.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TrackHostExits</strong> <em>host</em>,<em>.domain</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ For each value in the comma separated list, Tor will track recent
+ connections to hosts that match this value and attempt to reuse the same
+ exit node for each. If the value is prepended with a '.', it is treated as
+ matching an entire domain. If one of the values is just a '.', it means
+ match everything. This option is useful if you frequently connect to sites
+ that will expire all your authentication cookies (i.e. log you out) if
+ your IP address changes. Note that this option does have the disadvantage
+ of making it more clear that a given history is associated with a single
+ user. However, most people who would wish to observe this will observe it
+ through cookies or other protocol-specific means anyhow.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TrackHostExitsExpire</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ Since exit servers go up and down, it is desirable to expire the
+ association between host and exit server after NUM seconds. The default is
+ 1800 seconds (30 minutes).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>UpdateBridgesFromAuthority</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When set (along with UseBridges), Tor will try to fetch bridge descriptors
+ from the configured bridge authorities when feasible. It will fall back to
+ a direct request if the authority responds with a 404. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>UseBridges</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When set, Tor will fetch descriptors for each bridge listed in the "Bridge"
+ config lines, and use these relays as both entry guards and directory
+ guards. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>UseEntryGuards</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If this option is set to 1, we pick a few long-term entry servers, and try
+ to stick with them. This is desirable because constantly changing servers
+ increases the odds that an adversary who owns some servers will observe a
+ fraction of your paths. (Defaults to 1.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>NumEntryGuards</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ If UseEntryGuards is set to 1, we will try to pick a total of NUM routers
+ as long-term entries for our circuits. (Defaults to 3.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SafeSocks</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled, Tor will reject application connections that
+ use unsafe variants of the socks protocol — ones that only provide an IP
+ address, meaning the application is doing a DNS resolve first.
+ Specifically, these are socks4 and socks5 when not doing remote DNS.
+ (Defaults to 0.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TestSocks</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled, Tor will make a notice-level log entry for
+ each connection to the Socks port indicating whether the request used a
+ safe socks protocol or an unsafe one (see above entry on SafeSocks). This
+ helps to determine whether an application using Tor is possibly leaking
+ DNS requests. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>WarnUnsafeSocks</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled, Tor will warn whenever a request is
+ received that only contains an IP address instead of a hostname. Allowing
+ applications to do DNS resolves themselves is usually a bad idea and
+ can leak your location to attackers. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>VirtualAddrNetwork</strong> <em>Address</em>/<em>bits</em>
+</dt>
+<dd>
+<p>
+ When Tor needs to assign a virtual (unused) address because of a MAPADDRESS
+ command from the controller or the AutomapHostsOnResolve feature, Tor
+ picks an unassigned address from this range. (Default:
+ 127.192.0.0/10)<br />
+<br />
+ When providing proxy server service to a network of computers using a tool
+ like dns-proxy-tor, change this address to "10.192.0.0/10" or
+ "172.16.0.0/12". The default <strong>VirtualAddrNetwork</strong> address range on a
+ properly configured machine will route to the loopback interface. For
+ local use, no change to the default VirtualAddrNetwork setting is needed.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AllowNonRFC953Hostnames</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is disabled, Tor blocks hostnames containing illegal
+ characters (like @ and :) rather than sending them to an exit node to be
+ resolved. This helps trap accidental attempts to resolve URLs and so on.
+ (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AllowDotExit</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If enabled, we convert "www.google.com.foo.exit" addresses on the
+ SocksPort/TransPort/NATDPort into "www.google.com" addresses that exit from
+ the node "foo". Disabled by default since attacking websites and exit
+ relays can use it to manipulate your path selection. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FastFirstHopPK</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is disabled, Tor uses the public key step for the first
+ hop of creating circuits. Skipping it is generally safe since we have
+ already used TLS to authenticate the relay and to establish forward-secure
+ keys. Turning this option off makes circuit building slower.<br />
+<br />
+ Note that Tor will always use the public key step for the first hop if it’s
+ operating as a relay, and it will never use the public key step if it
+ doesn’t yet know the onion key of the first hop. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TransPort</strong> <em>PORT</em>|<strong>auto</strong>
+</dt>
+<dd>
+<p>
+ If non-zero, enables transparent proxy support on <em>PORT</em> (by convention,
+ 9040). Requires OS support for transparent proxies, such as BSDs' pf or
+ Linux’s IPTables. If you’re planning to use Tor as a transparent proxy for
+ a network, you’ll want to examine and change VirtualAddrNetwork from the
+ default setting. You’ll also want to set the TransListenAddress option for
+ the network you’d like to proxy. Set it to "auto" to have Tor pick a
+ port for you. (Default: 0).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TransListenAddress</strong> <em>IP</em>[:<em>PORT</em>]
+</dt>
+<dd>
+<p>
+ Bind to this address to listen for transparent proxy connections. (Default:
+ 127.0.0.1). This is useful for exporting a transparent proxy server to an
+ entire network.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>NATDPort</strong> <em>PORT</em>|<strong>auto</strong>
+</dt>
+<dd>
+<p>
+ Allow old versions of ipfw (as included in old versions of FreeBSD, etc.)
+ to send connections through Tor using the NATD protocol. This option is
+ only for people who cannot use TransPort. Set it to "auto" to have Tor
+ pick a port for you. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>NATDListenAddress</strong> <em>IP</em>[:<em>PORT</em>]
+</dt>
+<dd>
+<p>
+ Bind to this address to listen for NATD connections. (Default: 127.0.0.1).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AutomapHostsOnResolve</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled, and we get a request to resolve an address
+ that ends with one of the suffixes in <strong>AutomapHostsSuffixes</strong>, we map an
+ unused virtual address to that address, and return the new virtual address.
+ This is handy for making ".onion" addresses work with applications that
+ resolve an address and then connect to it. (Default: 0).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AutomapHostsSuffixes</strong> <em>SUFFIX</em>,<em>SUFFIX</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ A comma-separated list of suffixes to use with <strong>AutomapHostsOnResolve</strong>.
+ The "." suffix is equivalent to "all addresses." (Default: .exit,.onion).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DNSPort</strong> <em>PORT</em>|<strong>auto</strong>
+</dt>
+<dd>
+<p>
+ If non-zero, Tor listens for UDP DNS requests on this port and resolves
+ them anonymously. Set it to "auto" to have Tor pick a port for
+ you. (Default: 0).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DNSListenAddress</strong> <em>IP</em>[:<em>PORT</em>]
+</dt>
+<dd>
+<p>
+ Bind to this address to listen for DNS connections. (Default: 127.0.0.1).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ClientDNSRejectInternalAddresses</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If true, Tor does not believe any anonymously retrieved DNS answer that
+ tells it that an address resolves to an internal address (like 127.0.0.1 or
+ 192.168.0.1). This option prevents certain browser-based attacks; don’t
+ turn it off unless you know what you’re doing. (Default: 1).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ClientRejectInternalAddresses</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If true, Tor does not try to fulfill requests to connect to an internal
+ address (like 127.0.0.1 or 192.168.0.1) <em>unless a exit node is
+ specifically requested</em> (for example, via a .exit hostname, or a
+ controller request). (Default: 1).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DownloadExtraInfo</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If true, Tor downloads and caches "extra-info" documents. These documents
+ contain information about servers other than the information in their
+ regular router descriptors. Tor does not use this information for anything
+ itself; to save bandwidth, leave this option turned off. (Default: 0).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FallbackNetworkstatusFile</strong> <em>FILENAME</em>
+</dt>
+<dd>
+<p>
+ If Tor doesn’t have a cached networkstatus file, it starts out using this
+ one instead. Even if this file is out of date, Tor can still use it to
+ learn about directory mirrors, so it doesn’t need to put load on the
+ authorities. (Default: None).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>WarnPlaintextPorts</strong> <em>port</em>,<em>port</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ Tells Tor to issue a warnings whenever the user tries to make an anonymous
+ connection to one of these ports. This option is designed to alert users
+ to services that risk sending passwords in the clear. (Default:
+ 23,109,110,143).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>RejectPlaintextPorts</strong> <em>port</em>,<em>port</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor
+ will instead refuse to make the connection. (Default: None).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AllowSingleHopCircuits</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set, the attached Tor controller can use relays
+ that have the <strong>AllowSingleHopExits</strong> option turned on to build
+ one-hop Tor connections. (Default: 0)
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_server_options">SERVER OPTIONS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The following options are useful only for servers (that is, if ORPort
+is non-zero):</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>Address</strong> <em>address</em>
+</dt>
+<dd>
+<p>
+ The IP address or fully qualified domain name of this server (e.g.
+ moria.mit.edu). You can leave this unset, and Tor will guess your IP
+ address. This IP address is the one used to tell clients and other
+ servers where to find your Tor server; it doesn’t affect the IP that your
+ Tor client binds to. To bind to a different address, use the
+ *ListenAddress and OutboundBindAddress options.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AllowSingleHopExits</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ This option controls whether clients can use this server as a single hop
+ proxy. If set to 1, clients can use this server as an exit even if it is
+ the only hop in the circuit. Note that most clients will refuse to use
+ servers that set this option, since most clients have
+ ExcludeSingleHopRelays set. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AssumeReachable</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ This option is used when bootstrapping a new Tor network. If set to 1,
+ don’t do self-reachability testing; just upload your server descriptor
+ immediately. If <strong>AuthoritativeDirectory</strong> is also set, this option
+ instructs the dirserver to bypass remote reachability testing too and list
+ all connected servers as running.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>BridgeRelay</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ Sets the relay to act as a "bridge" with respect to relaying connections
+ from bridge users to the Tor network. It mainly causes Tor to publish a
+ server descriptor to the bridge database, rather than publishing a relay
+ descriptor to the public directory authorities.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ContactInfo</strong> <em>email_address</em>
+</dt>
+<dd>
+<p>
+ Administrative contact information for server. This line might get picked
+ up by spam harvesters, so you may want to obscure the fact that it’s an
+ email address.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ExitPolicy</strong> <em>policy</em>,<em>policy</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ Set an exit policy for this server. Each policy is of the form
+ "<strong>accept</strong>|<strong>reject</strong> <em>ADDR</em>[/<em>MASK</em>][:<em>PORT</em>]". If /<em>MASK</em> is
+ omitted then this policy just applies to the host given. Instead of giving
+ a host or network you can also use "*" to denote the universe (0.0.0.0/0).
+ <em>PORT</em> can be a single port number, an interval of ports
+ "<em>FROM_PORT</em>-<em>TO_PORT</em>", or "*". If <em>PORT</em> is omitted, that means
+ "*".<br />
+<br />
+ For example, "accept 18.7.22.69:*,reject 18.0.0.0/8:*,accept *:*" would
+ reject any traffic destined for MIT except for web.mit.edu, and accept
+ anything else.<br />
+<br />
+ To specify all internal and link-local networks (including 0.0.0.0/8,
+ 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, and
+ 172.16.0.0/12), you can use the "private" alias instead of an address.
+ These addresses are rejected by default (at the beginning of your exit
+ policy), along with your public IP address, unless you set the
+ ExitPolicyRejectPrivate config option to 0. For example, once you’ve done
+ that, you could allow HTTP to 127.0.0.1 and block all other connections to
+ internal networks with "accept 127.0.0.1:80,reject private:*", though that
+ may also allow connections to your own computer that are addressed to its
+ public (external) IP address. See RFC 1918 and RFC 3330 for more details
+ about internal and reserved IP address space.<br />
+<br />
+ This directive can be specified multiple times so you don’t have to put it
+ all on one line.<br />
+<br />
+ Policies are considered first to last, and the first match wins. If you
+ want to _replace_ the default exit policy, end your exit policy with
+ either a reject *:* or an accept *:*. Otherwise, you’re _augmenting_
+ (prepending to) the default exit policy. The default exit policy is:<br />
+</p>
+<div class="literalblock">
+<div class="content">
+<pre><tt>reject *:25
+reject *:119
+reject *:135-139
+reject *:445
+reject *:563
+reject *:1214
+reject *:4661-4666
+reject *:6346-6429
+reject *:6699
+reject *:6881-6999
+accept *:*</tt></pre>
+</div></div>
+</dd>
+<dt class="hdlist1">
+<strong>ExitPolicyRejectPrivate</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ Reject all private (local) networks, along with your own public IP address,
+ at the beginning of your exit policy. See above entry on ExitPolicy.
+ (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>MaxOnionsPending</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ If you have more than this number of onionskins queued for decrypt, reject
+ new ones. (Default: 100)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>MyFamily</strong> <em>node</em>,<em>node</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ Declare that this Tor server is controlled or administered by a group or
+ organization identical or similar to that of the other servers, defined by
+ their identity fingerprints or nicknames. When two servers both declare
+ that they are in the same 'family', Tor clients will not use them in the
+ same circuit. (Each server only needs to list the other servers in its
+ family; it doesn’t need to list itself, but it won’t hurt.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>Nickname</strong> <em>name</em>
+</dt>
+<dd>
+<p>
+ Set the server’s nickname to 'name'. Nicknames must be between 1 and 19
+ characters inclusive, and must contain only the characters [a-zA-Z0-9].
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>NumCPUs</strong> <em>num</em>
+</dt>
+<dd>
+<p>
+ How many processes to use at once for decrypting onionskins. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ORPort</strong> <em>PORT</em>|<strong>auto</strong>
+</dt>
+<dd>
+<p>
+ Advertise this port to listen for connections from Tor clients and
+ servers. This option is required to be a Tor server.
+ Set it to "auto" to have Tor pick a port for you. (Default: 0).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ORListenAddress</strong> <em>IP</em>[:<em>PORT</em>]
+</dt>
+<dd>
+<p>
+ Bind to this IP address to listen for connections from Tor clients and
+ servers. If you specify a port, bind to this port rather than the one
+ specified in ORPort. (Default: 0.0.0.0) This directive can be specified
+ multiple times to bind to multiple addresses/ports.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>PublishServerDescriptor</strong> <strong>0</strong>|<strong>1</strong>|<strong>v1</strong>|<strong>v2</strong>|<strong>v3</strong>|<strong>bridge</strong>,<strong>…</strong>
+</dt>
+<dd>
+<p>
+ This option specifies which descriptors Tor will publish when acting as
+ a relay. You can
+ choose multiple arguments, separated by commas.
+<br />
+ If this option is set to 0, Tor will not publish its
+ descriptors to any directories. (This is useful if you’re testing
+ out your server, or if you’re using a Tor controller that handles directory
+ publishing for you.) Otherwise, Tor will publish its descriptors of all
+ type(s) specified. The default is "1",
+ which means "if running as a server, publish the
+ appropriate descriptors to the authorities".
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ShutdownWaitLength</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ When we get a SIGINT and we’re a server, we begin shutting down:
+ we close listeners and start refusing new circuits. After <strong>NUM</strong>
+ seconds, we exit. If we get a second SIGINT, we exit immedi-
+ ately. (Default: 30 seconds)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AccountingMax</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>|<strong>TB</strong>
+</dt>
+<dd>
+<p>
+ Never send more than the specified number of bytes in a given accounting
+ period, or receive more than that number in the period. For example, with
+ AccountingMax set to 1 GB, a server could send 900 MB and receive 800 MB
+ and continue running. It will only hibernate once one of the two reaches 1
+ GB. When the number of bytes gets low, Tor will stop accepting new
+ connections and circuits. When the number of bytes
+ is exhausted, Tor will hibernate until some
+ time in the next accounting period. To prevent all servers from waking at
+ the same time, Tor will also wait until a random point in each period
+ before waking up. If you have bandwidth cost issues, enabling hibernation
+ is preferable to setting a low bandwidth, since it provides users with a
+ collection of fast servers that are up some of the time, which is more
+ useful than a set of slow servers that are always "available".
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AccountingStart</strong> <strong>day</strong>|<strong>week</strong>|<strong>month</strong> [<em>day</em>] <em>HH:MM</em>
+</dt>
+<dd>
+<p>
+ Specify how long accounting periods last. If <strong>month</strong> is given, each
+ accounting period runs from the time <em>HH:MM</em> on the <em>dayth</em> day of one
+ month to the same day and time of the next. (The day must be between 1 and
+ 28.) If <strong>week</strong> is given, each accounting period runs from the time <em>HH:MM</em>
+ of the <em>dayth</em> day of one week to the same day and time of the next week,
+ with Monday as day 1 and Sunday as day 7. If <strong>day</strong> is given, each
+ accounting period runs from the time <em>HH:MM</em> each day to the same time on
+ the next day. All times are local, and given in 24-hour time. (Defaults to
+ "month 1 0:00".)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>RefuseUnknownExits</strong> <strong>0</strong>|<strong>1</strong>|<strong>auto</strong>
+</dt>
+<dd>
+<p>
+ Prevent nodes that don’t appear in the consensus from exiting using this
+ relay. If the option is 1, we always block exit attempts from such
+ nodes; if it’s 0, we never do, and if the option is "auto", then we do
+ whatever the authorities suggest in the consensus. (Defaults to auto.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ServerDNSResolvConfFile</strong> <em>filename</em>
+</dt>
+<dd>
+<p>
+ Overrides the default DNS configuration with the configuration in
+ <em>filename</em>. The file format is the same as the standard Unix
+ "<strong>resolv.conf</strong>" file (7). This option, like all other ServerDNS options,
+ only affects name lookups that your server does on behalf of clients.
+ (Defaults to use the system DNS configuration.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ServerDNSAllowBrokenConfig</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If this option is false, Tor exits immediately if there are problems
+ parsing the system DNS configuration or connecting to nameservers.
+ Otherwise, Tor continues to periodically retry the system nameservers until
+ it eventually succeeds. (Defaults to "1".)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ServerDNSSearchDomains</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 1, then we will search for addresses in the local search domain.
+ For example, if this system is configured to believe it is in
+ "example.com", and a client tries to connect to "www", the client will be
+ connected to "www.example.com". This option only affects name lookups that
+ your server does on behalf of clients. (Defaults to "0".)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ServerDNSDetectHijacking</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set to 1, we will test periodically to determine
+ whether our local nameservers have been configured to hijack failing DNS
+ requests (usually to an advertising site). If they are, we will attempt to
+ correct this. This option only affects name lookups that your server does
+ on behalf of clients. (Defaults to "1".)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ServerDNSTestAddresses</strong> <em>address</em>,<em>address</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ When we’re detecting DNS hijacking, make sure that these <em>valid</em> addresses
+ aren’t getting redirected. If they are, then our DNS is completely useless,
+ and we’ll reset our exit policy to "reject <strong>:</strong>". This option only affects
+ name lookups that your server does on behalf of clients. (Defaults to
+ "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org".)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ServerDNSAllowNonRFC953Hostnames</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is disabled, Tor does not try to resolve hostnames
+ containing illegal characters (like @ and :) rather than sending them to an
+ exit node to be resolved. This helps trap accidental attempts to resolve
+ URLs and so on. This option only affects name lookups that your server does
+ on behalf of clients. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>BridgeRecordUsageByCountry</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled and BridgeRelay is also enabled, and we have
+ GeoIP data, Tor keeps a keep a per-country count of how many client
+ addresses have contacted it so that it can help the bridge authority guess
+ which countries have blocked access to it. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ServerDNSRandomizeCase</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set, Tor sets the case of each character randomly in
+ outgoing DNS requests, and makes sure that the case matches in DNS replies.
+ This so-called "0x20 hack" helps resist some types of DNS poisoning attack.
+ For more information, see "Increased DNS Forgery Resistance through
+ 0x20-Bit Encoding". This option only affects name lookups that your server
+ does on behalf of clients. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>GeoIPFile</strong> <em>filename</em>
+</dt>
+<dd>
+<p>
+ A filename containing GeoIP data, for use with BridgeRecordUsageByCountry.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>CellStatistics</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled, Tor writes statistics on the mean time that
+ cells spend in circuit queues to disk every 24 hours. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DirReqStatistics</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled, Tor writes statistics on the number and
+ response time of network status requests to disk every 24 hours.
+ (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>EntryStatistics</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled, Tor writes statistics on the number of
+ directly connecting clients to disk every 24 hours. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ExitPortStatistics</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled, Tor writes statistics on the number of relayed
+ bytes and opened stream per exit port to disk every 24 hours. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ExtraInfoStatistics</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is enabled, Tor includes previously gathered statistics in
+ its extra-info documents that it uploads to the directory authorities.
+ (Default: 0)
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_directory_server_options">DIRECTORY SERVER OPTIONS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The following options are useful only for directory servers (that is,
+if DirPort is non-zero):</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>AuthoritativeDirectory</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set to 1, Tor operates as an authoritative directory
+ server. Instead of caching the directory, it generates its own list of
+ good servers, signs it, and sends that to the clients. Unless the clients
+ already have you listed as a trusted directory, you probably do not want
+ to set this option. Please coordinate with the other admins at
+ <a href="mailto:tor-ops@torproject.org">tor-ops@torproject.org</a> if you think you should be a directory.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DirPortFrontPage</strong> <em>FILENAME</em>
+</dt>
+<dd>
+<p>
+ When this option is set, it takes an HTML file and publishes it as "/" on
+ the DirPort. Now relay operators can provide a disclaimer without needing
+ to set up a separate webserver. There’s a sample disclaimer in
+ contrib/tor-exit-notice.html.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>V1AuthoritativeDirectory</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set in addition to <strong>AuthoritativeDirectory</strong>, Tor
+ generates version 1 directory and running-routers documents (for legacy
+ Tor clients up to 0.1.0.x).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>V2AuthoritativeDirectory</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set in addition to <strong>AuthoritativeDirectory</strong>, Tor
+ generates version 2 network statuses and serves descriptors, etc as
+ described in doc/spec/dir-spec-v2.txt (for Tor clients and servers running
+ 0.1.1.x and 0.1.2.x).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>V3AuthoritativeDirectory</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set in addition to <strong>AuthoritativeDirectory</strong>, Tor
+ generates version 3 network statuses and serves descriptors, etc as
+ described in doc/spec/dir-spec.txt (for Tor clients and servers running at
+ least 0.2.0.x).
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>VersioningAuthoritativeDirectory</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set to 1, Tor adds information on which versions of
+ Tor are still believed safe for use to the published directory. Each
+ version 1 authority is automatically a versioning authority; version 2
+ authorities provide this service optionally. See <strong>RecommendedVersions</strong>,
+ <strong>RecommendedClientVersions</strong>, and <strong>RecommendedServerVersions</strong>.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>NamingAuthoritativeDirectory</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set to 1, then the server advertises that it has
+ opinions about nickname-to-fingerprint bindings. It will include these
+ opinions in its published network-status pages, by listing servers with
+ the flag "Named" if a correct binding between that nickname and fingerprint
+ has been registered with the dirserver. Naming dirservers will refuse to
+ accept or publish descriptors that contradict a registered binding. See
+ <strong>approved-routers</strong> in the <strong>FILES</strong> section below.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HSAuthoritativeDir</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set in addition to <strong>AuthoritativeDirectory</strong>, Tor also
+ accepts and serves v0 hidden service descriptors,
+ which are produced and used by Tor 0.2.1.x and older. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HidServDirectoryV2</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set, Tor accepts and serves v2 hidden service
+ descriptors. Setting DirPort is not required for this, because clients
+ connect via the ORPort by default. (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>BridgeAuthoritativeDir</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set in addition to <strong>AuthoritativeDirectory</strong>, Tor
+ accepts and serves router descriptors, but it caches and serves the main
+ networkstatus documents rather than generating its own. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>MinUptimeHidServDirectoryV2</strong> <em>N</em> <strong>seconds</strong>|<strong>minutes</strong>|<strong>hours</strong>|<strong>days</strong>|<strong>weeks</strong>
+</dt>
+<dd>
+<p>
+ Minimum uptime of a v2 hidden service directory to be accepted as such by
+ authoritative directories. (Default: 25 hours)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DirPort</strong> <em>PORT</em>|<strong>auto</strong>
+</dt>
+<dd>
+<p>
+ If this option is nonzero, advertise the directory service on this port.
+ Set it to "auto" to have Tor pick a port for you. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DirListenAddress</strong> <em>IP</em>[:<em>PORT</em>]
+</dt>
+<dd>
+<p>
+ Bind the directory service to this address. If you specify a port, bind to
+ this port rather than the one specified in DirPort. (Default: 0.0.0.0)
+ This directive can be specified multiple times to bind to multiple
+ addresses/ports.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DirPolicy</strong> <em>policy</em>,<em>policy</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ Set an entrance policy for this server, to limit who can connect to the
+ directory ports. The policies have the same form as exit policies above.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>FetchV2Networkstatus</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set, we try to fetch the (obsolete, unused) version 2 network status
+ consensus documents from the directory authorities. No currently
+ supported Tor version uses them. (Default: 0.)
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_directory_authority_server_options">DIRECTORY AUTHORITY SERVER OPTIONS</h2>
+<div class="sectionbody">
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>RecommendedVersions</strong> <em>STRING</em>
+</dt>
+<dd>
+<p>
+ STRING is a comma-separated list of Tor versions currently believed to be
+ safe. The list is included in each directory, and nodes which pull down the
+ directory learn whether they need to upgrade. This option can appear
+ multiple times: the values from multiple lines are spliced together. When
+ this is set then <strong>VersioningAuthoritativeDirectory</strong> should be set too.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>RecommendedClientVersions</strong> <em>STRING</em>
+</dt>
+<dd>
+<p>
+ STRING is a comma-separated list of Tor versions currently believed to be
+ safe for clients to use. This information is included in version 2
+ directories. If this is not set then the value of <strong>RecommendedVersions</strong>
+ is used. When this is set then <strong>VersioningAuthoritativeDirectory</strong> should
+ be set too.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>RecommendedServerVersions</strong> <em>STRING</em>
+</dt>
+<dd>
+<p>
+ STRING is a comma-separated list of Tor versions currently believed to be
+ safe for servers to use. This information is included in version 2
+ directories. If this is not set then the value of <strong>RecommendedVersions</strong>
+ is used. When this is set then <strong>VersioningAuthoritativeDirectory</strong> should
+ be set too.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>ConsensusParams</strong> <em>STRING</em>
+</dt>
+<dd>
+<p>
+ STRING is a space-separated list of key=value pairs that Tor will include
+ in the "params" line of its networkstatus vote.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>DirAllowPrivateAddresses</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 1, Tor will accept router descriptors with arbitrary "Address"
+ elements. Otherwise, if the address is not an IP address or is a private IP
+ address, it will reject the router descriptor. Defaults to 0.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirBadDir</strong> <em>AddressPattern…</em>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. A set of address patterns for servers that
+ will be listed as bad directories in any network status document this
+ authority publishes, if <strong>AuthDirListBadDirs</strong> is set.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirBadExit</strong> <em>AddressPattern…</em>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. A set of address patterns for servers that
+ will be listed as bad exits in any network status document this authority
+ publishes, if <strong>AuthDirListBadExits</strong> is set.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirInvalid</strong> <em>AddressPattern…</em>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. A set of address patterns for servers that
+ will never be listed as "valid" in any network status document that this
+ authority publishes.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirReject</strong> <em>AddressPattern</em>…
+</dt>
+<dd>
+<p>
+ Authoritative directories only. A set of address patterns for servers that
+ will never be listed at all in any network status document that this
+ authority publishes, or accepted as an OR address in any descriptor
+ submitted for publication by this authority.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirListBadDirs</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. If set to 1, this directory has some
+ opinion about which nodes are unsuitable as directory caches. (Do not set
+ this to 1 unless you plan to list non-functioning directories as bad;
+ otherwise, you are effectively voting in favor of every declared
+ directory.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirListBadExits</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. If set to 1, this directory has some
+ opinion about which nodes are unsuitable as exit nodes. (Do not set this to
+ 1 unless you plan to list non-functioning exits as bad; otherwise, you are
+ effectively voting in favor of every declared exit as an exit.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirRejectUnlisted</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. If set to 1, the directory server rejects
+ all uploaded server descriptors that aren’t explicitly listed in the
+ fingerprints file. This acts as a "panic button" if we get hit with a Sybil
+ attack. (Default: 0)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirMaxServersPerAddr</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. The maximum number of servers that we will
+ list as acceptable on a single IP address. Set this to "0" for "no limit".
+ (Default: 2)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirMaxServersPerAuthAddr</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. Like AuthDirMaxServersPerAddr, but applies
+ to addresses shared with directory authorities. (Default: 5)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirFastGuarantee</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. If non-zero, always vote the
+ Fast flag for any relay advertising this amount of capacity or
+ more. (Default: 20 KB)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>AuthDirGuardBWGuarantee</strong> <em>N</em> <strong>bytes</strong>|<strong>KB</strong>|<strong>MB</strong>|<strong>GB</strong>
+</dt>
+<dd>
+<p>
+ Authoritative directories only. If non-zero, this advertised capacity
+ or more is always sufficient to satisfy the bandwidth requirement
+ for the Guard flag. (Default: 250 KB)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>BridgePassword</strong> <em>Password</em>
+</dt>
+<dd>
+<p>
+ If set, contains an HTTP authenticator that tells a bridge authority to
+ serve all requested bridge information. Used for debugging. (Default:
+ not set.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>V3AuthVotingInterval</strong> <em>N</em> <strong>minutes</strong>|<strong>hours</strong>
+</dt>
+<dd>
+<p>
+ V3 authoritative directories only. Configures the server’s preferred voting
+ interval. Note that voting will <em>actually</em> happen at an interval chosen
+ by consensus from all the authorities' preferred intervals. This time
+ SHOULD divide evenly into a day. (Default: 1 hour)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>V3AuthVoteDelay</strong> <em>N</em> <strong>minutes</strong>|<strong>hours</strong>
+</dt>
+<dd>
+<p>
+ V3 authoritative directories only. Configures the server’s preferred delay
+ between publishing its vote and assuming it has all the votes from all the
+ other authorities. Note that the actual time used is not the server’s
+ preferred time, but the consensus of all preferences. (Default: 5 minutes.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>V3AuthDistDelay</strong> <em>N</em> <strong>minutes</strong>|<strong>hours</strong>
+</dt>
+<dd>
+<p>
+ V3 authoritative directories only. Configures the server’s preferred delay
+ between publishing its consensus and signature and assuming it has all the
+ signatures from all the other authorities. Note that the actual time used
+ is not the server’s preferred time, but the consensus of all preferences.
+ (Default: 5 minutes.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>V3AuthNIntervalsValid</strong> <em>NUM</em>
+</dt>
+<dd>
+<p>
+ V3 authoritative directories only. Configures the number of VotingIntervals
+ for which each consensus should be valid for. Choosing high numbers
+ increases network partitioning risks; choosing low numbers increases
+ directory traffic. Note that the actual number of intervals used is not the
+ server’s preferred number, but the consensus of all preferences. Must be at
+ least 2. (Default: 3.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>V3BandwidthsFile</strong> <em>FILENAME</em>
+</dt>
+<dd>
+<p>
+ V3 authoritative directories only. Configures the location of the
+ bandiwdth-authority generated file storing information on relays' measured
+ bandwidth capacities. (Default: unset.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>V3AuthUseLegacyKey</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set, the directory authority will sign consensuses not only with its
+ own signing key, but also with a "legacy" key and certificate with a
+ different identity. This feature is used to migrate directory authority
+ keys in the event of a compromise. (Default: 0.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>RephistTrackTime</strong> <em>N</em> <strong>seconds</strong>|<strong>minutes</strong>|<strong>hours</strong>|<strong>days</strong>|<strong>weeks</strong>
+</dt>
+<dd>
+<p>
+ Tells an authority, or other node tracking node reliability and history,
+ that fine-grained information about nodes can be discarded when it hasn’t
+ changed for a given amount of time. (Default: 24 hours)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>VoteOnHidServDirectoriesV2</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ When this option is set in addition to <strong>AuthoritativeDirectory</strong>, Tor
+ votes on whether to accept relays as hidden service directories.
+ (Default: 1)
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_hidden_service_options">HIDDEN SERVICE OPTIONS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The following options are used to configure a hidden service.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>HiddenServiceDir</strong> <em>DIRECTORY</em>
+</dt>
+<dd>
+<p>
+ Store data files for a hidden service in DIRECTORY. Every hidden service
+ must have a separate directory. You may use this option multiple times to
+ specify multiple services. DIRECTORY must be an existing directory.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HiddenServicePort</strong> <em>VIRTPORT</em> [<em>TARGET</em>]
+</dt>
+<dd>
+<p>
+ Configure a virtual port VIRTPORT for a hidden service. You may use this
+ option multiple times; each time applies to the service using the most
+ recent hiddenservicedir. By default, this option maps the virtual port to
+ the same port on 127.0.0.1. You may override the target port, address, or
+ both by specifying a target of addr, port, or addr:port. You may also have
+ multiple lines with the same VIRTPORT: when a user connects to that
+ VIRTPORT, one of the TARGETs from those lines will be chosen at random.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>PublishHidServDescriptors</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 0, Tor will run any hidden services you configure, but it won’t
+ advertise them to the rendezvous directory. This option is only useful if
+ you’re using a Tor controller that handles hidserv publishing for you.
+ (Default: 1)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HiddenServiceVersion</strong> <em>version</em>,<em>version</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ A list of rendezvous service descriptor versions to publish for the hidden
+ service. Currently, only version 2 is supported. (Default: 2)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>HiddenServiceAuthorizeClient</strong> <em>auth-type</em> <em>client-name</em>,<em>client-name</em>,<em>…</em>
+</dt>
+<dd>
+<p>
+ If configured, the hidden service is accessible for authorized clients
+ only. The auth-type can either be 'basic' for a general-purpose
+ authorization protocol or 'stealth' for a less scalable protocol that also
+ hides service activity from unauthorized clients. Only clients that are
+ listed here are authorized to access the hidden service. Valid client names
+ are 1 to 19 characters long and only use characters in A-Za-z0-9+-_ (no
+ spaces). If this option is set, the hidden service is not accessible for
+ clients without authorization any more. Generated authorization data can be
+ found in the hostname file. Clients need to put this authorization data in
+ their configuration file using <strong>HidServAuth</strong>.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>RendPostPeriod</strong> <em>N</em> <strong>seconds</strong>|<strong>minutes</strong>|<strong>hours</strong>|<strong>days</strong>|<strong>weeks</strong>
+</dt>
+<dd>
+<p>
+ Every time the specified period elapses, Tor uploads any rendezvous
+ service descriptors to the directory servers. This information is also
+ uploaded whenever it changes. (Default: 1 hour)
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_testing_network_options">TESTING NETWORK OPTIONS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The following options are used for running a testing Tor network.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>TestingTorNetwork</strong> <strong>0</strong>|<strong>1</strong>
+</dt>
+<dd>
+<p>
+ If set to 1, Tor adjusts default values of the configuration options below,
+ so that it is easier to set up a testing Tor network. May only be set if
+ non-default set of DirServers is set. Cannot be unset while Tor is running.
+ (Default: 0)<br />
+</p>
+<div class="literalblock">
+<div class="content">
+<pre><tt>ServerDNSAllowBrokenConfig 1
+DirAllowPrivateAddresses 1
+EnforceDistinctSubnets 0
+AssumeReachable 1
+AuthDirMaxServersPerAddr 0
+AuthDirMaxServersPerAuthAddr 0
+ClientDNSRejectInternalAddresses 0
+ClientRejectInternalAddresses 0
+ExitPolicyRejectPrivate 0
+V3AuthVotingInterval 5 minutes
+V3AuthVoteDelay 20 seconds
+V3AuthDistDelay 20 seconds
+MinUptimeHidServDirectoryV2 0 seconds
+TestingV3AuthInitialVotingInterval 5 minutes
+TestingV3AuthInitialVoteDelay 20 seconds
+TestingV3AuthInitialDistDelay 20 seconds
+TestingAuthDirTimeToLearnReachability 0 minutes
+TestingEstimatedDescriptorPropagationTime 0 minutes</tt></pre>
+</div></div>
+</dd>
+<dt class="hdlist1">
+<strong>TestingV3AuthInitialVotingInterval</strong> <em>N</em> <strong>minutes</strong>|<strong>hours</strong>
+</dt>
+<dd>
+<p>
+ Like V3AuthVotingInterval, but for initial voting interval before the first
+ consensus has been created. Changing this requires that
+ <strong>TestingTorNetwork</strong> is set. (Default: 30 minutes)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TestingV3AuthInitialVoteDelay</strong> <em>N</em> <strong>minutes</strong>|<strong>hours</strong>
+</dt>
+<dd>
+<p>
+ Like TestingV3AuthInitialVoteDelay, but for initial voting interval before
+ the first consensus has been created. Changing this requires that
+ <strong>TestingTorNetwork</strong> is set. (Default: 5 minutes)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TestingV3AuthInitialDistDelay</strong> <em>N</em> <strong>minutes</strong>|<strong>hours</strong>
+</dt>
+<dd>
+<p>
+ Like TestingV3AuthInitialDistDelay, but for initial voting interval before
+ the first consensus has been created. Changing this requires that
+ <strong>TestingTorNetwork</strong> is set. (Default: 5 minutes)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TestingAuthDirTimeToLearnReachability</strong> <em>N</em> <strong>minutes</strong>|<strong>hours</strong>
+</dt>
+<dd>
+<p>
+ After starting as an authority, do not make claims about whether routers
+ are Running until this much time has passed. Changing this requires
+ that <strong>TestingTorNetwork</strong> is set. (Default: 30 minutes)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>TestingEstimatedDescriptorPropagationTime</strong> <em>N</em> <strong>minutes</strong>|<strong>hours</strong>
+</dt>
+<dd>
+<p>
+ Clients try downloading router descriptors from directory caches after this
+ time. Changing this requires that <strong>TestingTorNetwork</strong> is set. (Default:
+ 10 minutes)
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_signals">SIGNALS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Tor catches the following signals:</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>SIGTERM</strong>
+</dt>
+<dd>
+<p>
+ Tor will catch this, clean up and sync to disk if necessary, and exit.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SIGINT</strong>
+</dt>
+<dd>
+<p>
+ Tor clients behave as with SIGTERM; but Tor servers will do a controlled
+ slow shutdown, closing listeners and waiting 30 seconds before exiting.
+ (The delay can be configured with the ShutdownWaitLength config option.)
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SIGHUP</strong>
+</dt>
+<dd>
+<p>
+ The signal instructs Tor to reload its configuration (including closing and
+ reopening logs), and kill and restart its helper processes if applicable.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SIGUSR1</strong>
+</dt>
+<dd>
+<p>
+ Log statistics about current connections, past connections, and throughput.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SIGUSR2</strong>
+</dt>
+<dd>
+<p>
+ Switch all logs to loglevel debug. You can go back to the old loglevels by
+ sending a SIGHUP.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SIGCHLD</strong>
+</dt>
+<dd>
+<p>
+ Tor receives this signal when one of its helper processes has exited, so it
+ can clean up.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SIGPIPE</strong>
+</dt>
+<dd>
+<p>
+ Tor catches this signal and ignores it.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>SIGXFSZ</strong>
+</dt>
+<dd>
+<p>
+ If this signal exists on your platform, Tor catches and ignores it.
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_files">FILES</h2>
+<div class="sectionbody">
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<strong>/etc/tor/torrc</strong>
+</dt>
+<dd>
+<p>
+ The configuration file, which contains "option value" pairs.
+</p>
+</dd>
+<dt class="hdlist1">
+<strong>/var/lib/tor/</strong>
+</dt>
+<dd>
+<p>
+ The tor process stores keys and other data here.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/cached-status/</strong>
+</dt>
+<dd>
+<p>
+ The most recently downloaded network status document for each authority.
+ Each file holds one such document; the filenames are the hexadecimal
+ identity key fingerprints of the directory authorities.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/cached-descriptors</strong> and <strong>cached-descriptors.new</strong>
+</dt>
+<dd>
+<p>
+ These files hold downloaded router statuses. Some routers may appear more
+ than once; if so, the most recently published descriptor is used. Lines
+ beginning with @-signs are annotations that contain more information about
+ a given router. The ".new" file is an append-only journal; when it gets
+ too large, all entries are merged into a new cached-descriptors file.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/cached-routers</strong> and <strong>cached-routers.new</strong>
+</dt>
+<dd>
+<p>
+ Obsolete versions of cached-descriptors and cached-descriptors.new. When
+ Tor can’t find the newer files, it looks here instead.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/state</strong>
+</dt>
+<dd>
+<p>
+ A set of persistent key-value mappings. These are documented in
+ the file. These include:
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+The current entry guards and their status.
+</p>
+</li>
+<li>
+<p>
+The current bandwidth accounting values (unused so far; see
+ below).
+</p>
+</li>
+<li>
+<p>
+When the file was last written
+</p>
+</li>
+<li>
+<p>
+What version of Tor generated the state file
+</p>
+</li>
+<li>
+<p>
+A short history of bandwidth usage, as produced in the router
+ descriptors.
+</p>
+</li>
+</ul></div>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/bw_accounting</strong>
+</dt>
+<dd>
+<p>
+ Used to track bandwidth accounting values (when the current period starts
+ and ends; how much has been read and written so far this period). This file
+ is obsolete, and the data is now stored in the 'state' file as well. Only
+ used when bandwidth accounting is enabled.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/control_auth_cookie</strong>
+</dt>
+<dd>
+<p>
+ Used for cookie authentication with the controller. Location can be
+ overridden by the CookieAuthFile config option. Regenerated on startup. See
+ control-spec.txt for details. Only used when cookie authentication is
+ enabled.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/keys/</strong>*
+</dt>
+<dd>
+<p>
+ Only used by servers. Holds identity keys and onion keys.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/fingerprint</strong>
+</dt>
+<dd>
+<p>
+ Only used by servers. Holds the fingerprint of the server’s identity key.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/approved-routers</strong>
+</dt>
+<dd>
+<p>
+ Only for naming authoritative directory servers (see
+ <strong>NamingAuthoritativeDirectory</strong>). This file lists nickname to identity
+ bindings. Each line lists a nickname and a fingerprint separated by
+ whitespace. See your <strong>fingerprint</strong> file in the <em>DataDirectory</em> for an
+ example line. If the nickname is <strong>!reject</strong> then descriptors from the
+ given identity (fingerprint) are rejected by this server. If it is
+ <strong>!invalid</strong> then descriptors are accepted but marked in the directory as
+ not valid, that is, not recommended.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>DataDirectory</em><strong>/router-stability</strong>
+</dt>
+<dd>
+<p>
+ Only used by authoritative directory servers. Tracks measurements for
+ router mean-time-between-failures so that authorities have a good idea of
+ how to set their Stable flags.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>HiddenServiceDirectory</em><strong>/hostname</strong>
+</dt>
+<dd>
+<p>
+ The <base32-encoded-fingerprint>.onion domain name for this hidden service.
+ If the hidden service is restricted to authorized clients only, this file
+ also contains authorization data for all clients.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>HiddenServiceDirectory</em><strong>/private_key</strong>
+</dt>
+<dd>
+<p>
+ The private key for this hidden service.
+</p>
+</dd>
+<dt class="hdlist1">
+<em>HiddenServiceDirectory</em><strong>/client_keys</strong>
+</dt>
+<dd>
+<p>
+ Authorization data for a hidden service that is only accessible by
+ authorized clients.
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_see_also">SEE ALSO</h2>
+<div class="sectionbody">
+<div class="paragraph"><p><strong>privoxy</strong>(1), <strong>tsocks</strong>(1), <strong>torify</strong>(1)<br /></p></div>
+<div class="paragraph"><p><strong>https://www.torproject.org/</strong></p></div>
+</div>
+<h2 id="_bugs">BUGS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Plenty, probably. Tor is still in development. Please report them.</p></div>
+</div>
+<h2 id="_authors">AUTHORS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at alum.mit.edu].</p></div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2011-12-15 11:28:37 EDT
+</div>
+</div>
+</body>
+</html>
diff --git a/manifests/arm.pp b/manifests/arm.pp new file mode 100644 index 00000000..44ddcbbf --- /dev/null +++ b/manifests/arm.pp @@ -0,0 +1,9 @@ +# manage tor-arm +class tor::arm ( + $ensure_version = 'installed' +){ + include ::tor + package{'tor-arm': + ensure => $ensure_version, + } +} diff --git a/manifests/base.pp b/manifests/base.pp new file mode 100644 index 00000000..b98451be --- /dev/null +++ b/manifests/base.pp @@ -0,0 +1,14 @@ +# basic management of resources for tor +class tor::base { + package { [ 'tor', 'tor-geoipdb' ]: + ensure => $tor::ensure_version, + } + + service { 'tor': + ensure => running, + enable => true, + hasrestart => true, + hasstatus => true, + require => Package['tor'], + } +} diff --git a/manifests/compact.pp b/manifests/compact.pp new file mode 100644 index 00000000..c0f59199 --- /dev/null +++ b/manifests/compact.pp @@ -0,0 +1,7 @@ +# manage a complete tor +# installation with all the basics +class tor::compact { + include ::tor + include tor::polipo + include tor::torsocks +} diff --git a/manifests/daemon.pp b/manifests/daemon.pp new file mode 100644 index 00000000..2522b2cc --- /dev/null +++ b/manifests/daemon.pp @@ -0,0 +1,22 @@ +# manage a snippet based tor installation +class tor::daemon ( + $ensure_version = 'installed', + $use_munin = false, + $data_dir = '/var/lib/tor', + $config_file = '/etc/tor/torrc', + $use_bridges = 0, + $automap_hosts_on_resolve = 0, + $log_rules = [ 'notice file /var/log/tor/notices.log' ], + $safe_logging = 1, +) { + + class{'tor': + ensure_version => $ensure_version, + } + + include tor::daemon::base + + if $use_munin { + include tor::munin + } +} diff --git a/manifests/daemon/base.pp b/manifests/daemon/base.pp new file mode 100644 index 00000000..63d7bc4d --- /dev/null +++ b/manifests/daemon/base.pp @@ -0,0 +1,77 @@ +# extend basic tor things with a snippet based daemon configuration +class tor::daemon::base inherits tor::base { + # packages, user, group + Service['tor'] { + subscribe => File[$tor::daemon::config_file], + } + + Package[ 'tor' ] { + require => File[$tor::daemon::data_dir], + } + + group { 'debian-tor': + ensure => present, + allowdupe => false, + } + + user { 'debian-tor': + ensure => present, + allowdupe => false, + comment => 'tor user,,,', + home => $tor::daemon::data_dir, + shell => '/bin/false', + gid => 'debian-tor', + require => Group['debian-tor'], + } + + # directories + file { $tor::daemon::data_dir: + ensure => directory, + mode => '0700', + owner => 'debian-tor', + group => 'debian-tor', + require => User['debian-tor'], + } + + file { '/etc/tor': + ensure => directory, + mode => '0755', + owner => 'debian-tor', + group => 'debian-tor', + require => User['debian-tor'], + } + + file { '/var/lib/puppet/modules/tor': + ensure => absent, + recurse => true, + force => true, + } + + # tor configuration file + concat { $tor::daemon::config_file: + mode => '0600', + owner => 'debian-tor', + group => 'debian-tor', + } + + # config file headers + concat::fragment { '00.header': + ensure => present, + content => template('tor/torrc.header.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => 00, + target => $tor::daemon::config_file, + } + + # global configurations + concat::fragment { '01.global': + content => template('tor/torrc.global.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => 01, + target => $tor::daemon::config_file, + } +} diff --git a/manifests/daemon/bridge.pp b/manifests/daemon/bridge.pp new file mode 100644 index 00000000..063f5656 --- /dev/null +++ b/manifests/daemon/bridge.pp @@ -0,0 +1,18 @@ +# Bridge definition +define tor::daemon::bridge( + $ip, + $port, + $fingerprint = false, + $ensure = present ) { + + concat::fragment { "10.bridge.${name}": + ensure => $ensure, + content => template('tor/torrc.bridge.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => 10, + target => $tor::daemon::config_file, + } +} + diff --git a/manifests/daemon/control.pp b/manifests/daemon/control.pp new file mode 100644 index 00000000..01726562 --- /dev/null +++ b/manifests/daemon/control.pp @@ -0,0 +1,27 @@ +# control definition +define tor::daemon::control( + $port = 0, + $hashed_control_password = '', + $cookie_authentication = 0, + $cookie_auth_file = '', + $cookie_auth_file_group_readable = '', + $ensure = present ) { + + if $cookie_authentication == '0' and $hashed_control_password == '' and $ensure != 'absent' { + fail('You need to define the tor control password') + } + + if $cookie_authentication == 0 and ($cookie_auth_file != '' or $cookie_auth_file_group_readable != '') { + notice('You set a tor cookie authentication option, but do not have cookie_authentication on') + } + + concat::fragment { '04.control': + ensure => $ensure, + content => template('tor/torrc.control.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0600', + order => 04, + target => $tor::daemon::config_file, + } +} diff --git a/manifests/daemon/directory.pp b/manifests/daemon/directory.pp new file mode 100644 index 00000000..d877a861 --- /dev/null +++ b/manifests/daemon/directory.pp @@ -0,0 +1,27 @@ +# directory advertising +define tor::daemon::directory ( + $port = 0, + $listen_addresses = [], + $port_front_page = '/etc/tor/tor-exit-notice.html', + $ensure = present ) { + + concat::fragment { '06.directory': + ensure => $ensure, + content => template('tor/torrc.directory.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => 06, + target => $tor::daemon::config_file, + } + + file { '/etc/tor/tor-exit-notice.html': + ensure => $ensure, + source => 'puppet:///modules/tor/tor-exit-notice.html', + require => File['/etc/tor'], + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + } +} + diff --git a/manifests/daemon/dns.pp b/manifests/daemon/dns.pp new file mode 100644 index 00000000..4677f24d --- /dev/null +++ b/manifests/daemon/dns.pp @@ -0,0 +1,17 @@ +# DNS definition +define tor::daemon::dns( + $port = 0, + $listen_addresses = [], + $ensure = present ) { + + concat::fragment { "08.dns.${name}": + ensure => $ensure, + content => template('tor/torrc.dns.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => '08', + target => $tor::daemon::config_file, + } +} + diff --git a/manifests/daemon/exit_policy.pp b/manifests/daemon/exit_policy.pp new file mode 100644 index 00000000..f459ece7 --- /dev/null +++ b/manifests/daemon/exit_policy.pp @@ -0,0 +1,18 @@ +# exit policies +define tor::daemon::exit_policy( + $accept = [], + $reject = [], + $reject_private = 1, + $ensure = present ) { + + concat::fragment { "07.exit_policy.${name}": + ensure => $ensure, + content => template('tor/torrc.exit_policy.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => 07, + target => $tor::daemon::config_file, + } +} + diff --git a/manifests/daemon/hidden_service.pp b/manifests/daemon/hidden_service.pp new file mode 100644 index 00000000..c8272116 --- /dev/null +++ b/manifests/daemon/hidden_service.pp @@ -0,0 +1,17 @@ +# hidden services definition +define tor::daemon::hidden_service( + $ports = [], + $data_dir = $tor::daemon::data_dir, + $ensure = present ) { + + concat::fragment { "05.hidden_service.${name}": + ensure => $ensure, + content => template('tor/torrc.hidden_service.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => 05, + target => $tor::daemon::config_file, + } +} + diff --git a/manifests/daemon/map_address.pp b/manifests/daemon/map_address.pp new file mode 100644 index 00000000..270eac21 --- /dev/null +++ b/manifests/daemon/map_address.pp @@ -0,0 +1,17 @@ +# map address definition +define tor::daemon::map_address( + $address = '', + $newaddress = '', + $ensure = 'present') { + + concat::fragment { "08.map_address.${name}": + ensure => $ensure, + content => template('tor/torrc.map_address.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => '08', + target => $tor::daemon::config_file, + } +} + diff --git a/manifests/daemon/relay.pp b/manifests/daemon/relay.pp new file mode 100644 index 00000000..ff528937 --- /dev/null +++ b/manifests/daemon/relay.pp @@ -0,0 +1,42 @@ +# relay definition +define tor::daemon::relay( + $port = 0, + $listen_addresses = [], + $outbound_bindaddresses = [], + $portforwarding = 0, + # KB/s, defaulting to using tor's default: 5120KB/s + $bandwidth_rate = '', + # KB/s, defaulting to using tor's default: 10240KB/s + $bandwidth_burst = '', + # KB/s, 0 for no limit + $relay_bandwidth_rate = 0, + # KB/s, 0 for no limit + $relay_bandwidth_burst = 0, + # GB, 0 for no limit + $accounting_max = 0, + $accounting_start = [], + $contact_info = '', + # TODO: autofill with other relays + $my_family = '', + $address = "tor.${::domain}", + $bridge_relay = 0, + $ensure = present ) { + + $nickname = $name + + if $outbound_bindaddresses == [] { + $real_outbound_bindaddresses = [] + } else { + $real_outbound_bindaddresses = $outbound_bindaddresses + } + + concat::fragment { '03.relay': + ensure => $ensure, + content => template('tor/torrc.relay.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => 03, + target => $tor::daemon::config_file, + } +} diff --git a/manifests/daemon/snippet.pp b/manifests/daemon/snippet.pp new file mode 100644 index 00000000..b9089b40 --- /dev/null +++ b/manifests/daemon/snippet.pp @@ -0,0 +1,16 @@ +# Arbitrary torrc snippet definition +define tor::daemon::snippet( + $content = '', + $ensure = present ) { + + concat::fragment { "99.snippet.${name}": + ensure => $ensure, + content => $content, + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => 99, + target => $tor::daemon::config_file, + } +} + diff --git a/manifests/daemon/socks.pp b/manifests/daemon/socks.pp new file mode 100644 index 00000000..910461c9 --- /dev/null +++ b/manifests/daemon/socks.pp @@ -0,0 +1,15 @@ +# socks definition +define tor::daemon::socks( + $port = 0, + $listen_addresses = [], + $policies = [] ) { + + concat::fragment { '02.socks': + content => template('tor/torrc.socks.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => 02, + target => $tor::daemon::config_file, + } +} diff --git a/manifests/daemon/transparent.pp b/manifests/daemon/transparent.pp new file mode 100644 index 00000000..65d744f4 --- /dev/null +++ b/manifests/daemon/transparent.pp @@ -0,0 +1,17 @@ +# Transparent proxy definition +define tor::daemon::transparent( + $port = 0, + $listen_addresses = [], + $ensure = present ) { + + concat::fragment { "09.transparent.${name}": + ensure => $ensure, + content => template('tor/torrc.transparent.erb'), + owner => 'debian-tor', + group => 'debian-tor', + mode => '0644', + order => '09', + target => $tor::daemon::config_file, + } +} + diff --git a/manifests/init.pp b/manifests/init.pp new file mode 100644 index 00000000..9c19c648 --- /dev/null +++ b/manifests/init.pp @@ -0,0 +1,6 @@ +# manage a basic tor installation +class tor ( + $ensure_version = 'installed' +){ + include tor::base +} diff --git a/manifests/munin.pp b/manifests/munin.pp new file mode 100644 index 00000000..4412337a --- /dev/null +++ b/manifests/munin.pp @@ -0,0 +1,21 @@ +# munin plugins for puppet +class tor::munin { + tor::daemon::control{ + 'control_port_for_munin': + port => 19051, + cookie_authentication => 1, + cookie_auth_file => '/var/run/tor/control.authcookie', + } + + Munin::Plugin::Deploy { + config => "user debian-tor\n env.cookiefile /var/run/tor/control.authcookie\n env.port 19051" + } + munin::plugin::deploy { + 'tor_connections': + source => 'tor/munin/tor_connections'; + 'tor_routers': + source => 'tor/munin/tor_routers'; + 'tor_traffic': + source => 'tor/munin/tor_traffic'; + } +} diff --git a/manifests/polipo.pp b/manifests/polipo.pp new file mode 100644 index 00000000..73dc2262 --- /dev/null +++ b/manifests/polipo.pp @@ -0,0 +1,9 @@ +# manage the polipo proxy service +class tor::polipo { + include ::tor + + case $::operatingsystem { + 'debian': { include tor::polipo::debian } + default: { include tor::polipo::base } + } +} diff --git a/manifests/polipo/base.pp b/manifests/polipo/base.pp new file mode 100644 index 00000000..df2d6ea6 --- /dev/null +++ b/manifests/polipo/base.pp @@ -0,0 +1,22 @@ +# manage polipo resources +class tor::polipo::base { + package{'polipo': + ensure => present, + } + + file { '/etc/polipo/config': + ensure => present, + owner => root, + group => root, + mode => '0644', + source => 'puppet:///modules/tor/polipo/polipo.conf', + require => Package['polipo'], + notify => Service['polipo'], + } + + service { 'polipo': + ensure => running, + enable => true, + require => [ Package['polipo'], Service['tor'] ], + } +} diff --git a/manifests/polipo/debian.pp b/manifests/polipo/debian.pp new file mode 100644 index 00000000..607b3617 --- /dev/null +++ b/manifests/polipo/debian.pp @@ -0,0 +1,7 @@ +# manage polipo on debian +class tor::polipo::debian inherits tor::polipo::base { + Service['polipo'] { + hasstatus => false, + pattern => '/usr/bin/polipo', + } +} diff --git a/manifests/repo.pp b/manifests/repo.pp new file mode 100644 index 00000000..f6255995 --- /dev/null +++ b/manifests/repo.pp @@ -0,0 +1,16 @@ +class tor::repo ( + $ensure = present, + $source_name = 'torproject.org', + $include_src = false, +) { + case $::osfamily { + 'Debian': { + $key = '886DDD89' + $location = 'https://deb.torproject.org/torproject.org/' + class { 'tor::repo::debian': } + } + default: { + fail("Unsupported managed repository for osfamily: ${::osfamily}, operatingsystem: ${::operatingsystem}, module ${module_name} currently only supports managing repos for osfamily Debian and Ubuntu") + } + } +} diff --git a/manifests/repo/debian.pp b/manifests/repo/debian.pp new file mode 100644 index 00000000..174c3310 --- /dev/null +++ b/manifests/repo/debian.pp @@ -0,0 +1,9 @@ +# PRIVATE CLASS: do not use directly +class tor::repo::debian inherits tor::repo { + apt::source { $source_name: + ensure => $::tor::repo::ensure, + location => $::tor::repo::location, + key => $::tor::repo::key, + include_src => $::tor::repo::include_src, + } +} diff --git a/manifests/torsocks.pp b/manifests/torsocks.pp new file mode 100644 index 00000000..e9fc75b2 --- /dev/null +++ b/manifests/torsocks.pp @@ -0,0 +1,9 @@ +# manage torsocks +class tor::torsocks ( + $ensure_version = 'installed' +){ + include ::tor + package{'torsocks': + ensure => $ensure_version, + } +} diff --git a/templates/torrc.bridge.erb b/templates/torrc.bridge.erb new file mode 100644 index 00000000..559ce5df --- /dev/null +++ b/templates/torrc.bridge.erb @@ -0,0 +1,3 @@ +# Bridge <%= @name %> +Bridge <%= @ip %>:<%= @port %><% if @fingerprint -%> <%= @fingerprint%><% end -%> + diff --git a/templates/torrc.control.erb b/templates/torrc.control.erb new file mode 100644 index 00000000..0b68faff --- /dev/null +++ b/templates/torrc.control.erb @@ -0,0 +1,16 @@ +# tor controller +<% if @port != '0' -%> +ControlPort <%= @port %> +<% if @cookie_authentication != '0' -%> +CookieAuthentication 1 +<% if @cookie_auth_file != '' -%> +CookieAuthFile <%= @cookie_auth_file %> +<% end -%> +<% if @cookie_auth_file_group_readable != '' -%> +CookieAuthFileGroupReadable <%= @cookie_auth_file_group_readable %> +<% end -%> +<% else -%> +HashedControlPassword <%= @hashed_control_password %> +<% end -%> +<% end -%> + diff --git a/templates/torrc.directory.erb b/templates/torrc.directory.erb new file mode 100644 index 00000000..1af9f40f --- /dev/null +++ b/templates/torrc.directory.erb @@ -0,0 +1,11 @@ +# directory listing +<% if port != '0' -%> +DirPort <%= @port %> +<% end -%> +<% listen_addresses.each do |listen_address| -%> +DirListenAddress <%= listen_address %> +<% end -%> +<% if @port_front_page != '' -%> +DirPortFrontPage <%= port_front_page %> +<%- end -%> + diff --git a/templates/torrc.dns.erb b/templates/torrc.dns.erb new file mode 100644 index 00000000..57cf46d9 --- /dev/null +++ b/templates/torrc.dns.erb @@ -0,0 +1,5 @@ +# DNS +DNSPort <%= @port %> +<% @listen_addresses.each do |listen_address| -%> +DNSListenAddress <%= listen_address %> +<% end -%> diff --git a/templates/torrc.exit_policy.erb b/templates/torrc.exit_policy.erb new file mode 100644 index 00000000..a30d43b8 --- /dev/null +++ b/templates/torrc.exit_policy.erb @@ -0,0 +1,11 @@ +# exit policies: <%= @name %> +<% if @reject_private != '1' -%> +ExitPolicyRejectPrivate <%= @reject_private %> +<% end -%> +<% @accept.each do |policy| -%> +ExitPolicy accept <%= policy %> +<% end -%> +<% @reject.each do |policy| -%> +ExitPolicy reject <%= policy %> +<% end -%> + diff --git a/templates/torrc.global.erb b/templates/torrc.global.erb new file mode 100644 index 00000000..f577673d --- /dev/null +++ b/templates/torrc.global.erb @@ -0,0 +1,24 @@ +# runtime +RunAsDaemon 1 +<% if (v=scope.lookupvar('tor::daemon::data_dir')) != '/var/lib/tor' -%> +DataDirectory <%= v %> +<% end -%> + +# log +<% if (rules=scope.lookupvar('tor::daemon::log_rules')).empty? -%> +Log notice syslog +<% else -%> +<% rules.each do |log_rule| -%> +Log <%= log_rule %> +<% end -%> +<% end -%> +<%- if @safe_logging != 1 then -%> +SafeLogging <%= @safe_logging %> +<%- end -%> + +<% if (v=scope.lookupvar('tor::daemon::automap_hosts_on_resolve')) != '0' -%> +AutomapHostsOnResolve <%= v %> +<% end -%> +<% if (v=scope.lookupvar('tor::daemon::use_bridges')) != '0' -%> +UseBridges <%= v %> +<%- end -%> diff --git a/templates/torrc.header.erb b/templates/torrc.header.erb new file mode 100644 index 00000000..79d6da9d --- /dev/null +++ b/templates/torrc.header.erb @@ -0,0 +1,2 @@ +# This file is managed by puppet. + diff --git a/templates/torrc.hidden_service.erb b/templates/torrc.hidden_service.erb new file mode 100644 index 00000000..4dec0b25 --- /dev/null +++ b/templates/torrc.hidden_service.erb @@ -0,0 +1,6 @@ +# hidden service <%= @name %> +HiddenServiceDir <%= @data_dir %>/<%= @name %> +<% @ports.each do |port| -%> +HiddenServicePort <%= port %> +<% end -%> + diff --git a/templates/torrc.map_address.erb b/templates/torrc.map_address.erb new file mode 100644 index 00000000..ef4f2683 --- /dev/null +++ b/templates/torrc.map_address.erb @@ -0,0 +1,3 @@ +# map address <%= @name %> +MapAddress <%= @address %> <%= @newaddress %> + diff --git a/templates/torrc.relay.erb b/templates/torrc.relay.erb new file mode 100644 index 00000000..a286459f --- /dev/null +++ b/templates/torrc.relay.erb @@ -0,0 +1,46 @@ +# relay +<% if @port != 0 -%> +ORPort <%= @port %> +<% @listen_addresses.each do |listen_address| -%> +ORListenAddress <%= @listen_address %> +<% end -%> +<% @real_outbound_bindaddresses.each do |outbound_bindaddress| -%> +OutboundBindAddress <%= @outbound_bindaddress %> +<% end -%> +<% if @nickname != '' -%> +Nickname <%= @nickname %> +<% end -%> +<% if @address != '' -%> +Address <%= @address %> +<% end -%> +<% if @portforwarding != '0' -%> +PortForwarding <%= @portforwarding %> +<% end -%> +<% if @bandwidth_rate != '' -%> +BandwidthRate <%= @bandwidth_rate %> KB +<% end -%> +<% if @bandwidth_burst != '' -%> +BandwidthBurst <%= @bandwidth_burst %> KB +<% end -%> +<% if @relay_bandwidth_rate != '0' -%> +RelayBandwidthRate <%= @relay_bandwidth_rate %> KB +<% end -%> +<% if @relay_bandwidth_burst != '0' -%> +RelayBandwidthBurst <%= @relay_bandwidth_burst %> KB +<% end -%> +<% if @accounting_max != '0' -%> +AccountingMax <%= @accounting_max %> GB +<% if @accounting_start -%> +AccountingStart <%= @accounting_start %> +<% end -%> +<% end -%> +<% if @contact_info != '' -%> +ContactInfo <%= @contact_info %> +<% end -%> +<% end -%> +<% if @my_family != '' -%> +MyFamily <%= @my_family %> +<% end -%> +<% if @bridge_relay != '0' -%> +BridgeRelay <%= @bridge_relay %> +<% end -%> diff --git a/templates/torrc.socks.erb b/templates/torrc.socks.erb new file mode 100644 index 00000000..4bc3ddc1 --- /dev/null +++ b/templates/torrc.socks.erb @@ -0,0 +1,9 @@ +# socks +SocksPort <%= @port %> +<% @listen_addresses.each do |listen_address| -%> +SocksListenAddress <%= listen_address %> +<% end -%> +<% @policies.each do |policy| -%> +SocksPolicy <%= policy %> +<% end -%> + diff --git a/templates/torrc.transparent.erb b/templates/torrc.transparent.erb new file mode 100644 index 00000000..c683150f --- /dev/null +++ b/templates/torrc.transparent.erb @@ -0,0 +1,5 @@ +# Transparent proxy +TransPort <%= @port %> +<% @listen_addresses.each do |listen_address| -%> +TransListenAddress <%= listen_address %> +<% end -%> |