JOH User Manual
Contents
1. merge those two alternatives to suit the situation If your document contains nontrivial examples of program code we rec ommend releasing these examples in parallel under your choice of free soft ware license such as the GNU General Public License to permit their use in free software Concept Index Concept Index This is a general index of all issues discussed in this manual etc hosts allow 1 5 A alias HTTP server 6 C 76 ClaSSuii coris id pv CAPE EX UR 11 c c option introduced 4 us EE EA AE TELF ENSE 6 CGI mode defined 2 class socket RE rn eene 4 controlling terminal F D D TTT Il d d number eee 1 d d option described 9 D D option introduction ig daemon mode johd T daemon name TCP wrappers 4 debugging bee d pe ree ret be 9 E E Ellen 11 E E option introduction 8 exit Codes 13 F Fy F facility AE eiue id F F option described 9 facility Sy8lO0g ce reet rere etema 9 FDL GNU Free Documentation License 19 firewalli siese es SERE cea EED A SED 1 27 H lj EE ER EE DE aes 11 hosts ALLOW se uns 5 hosts allow CGI sockets 6 HTTP Connect sis stens Res NG SE SR SE Es al HTTP Polling 8 pirssin ss 1 I dj RE SE EE OE 11 i i option descri2. 192 168 10 1 The use of 208 68 163 220 is granted to anybody and the use of 192 168 10 1 is allowed only for clients coming from IP addresses in the range 192 168 0 1 192 168 0 254 johd ALL johd jabber 208 68 163 220 ALL johd jabber 192 168 10 1 192 168 10 0 24 6 JOH User Manual 2 3 Using JOH in CGI Mode The CGI mode is a bit more complicated because it involves configuring two components However the default settings are chosen so as to simplify the configuration First select the socket to use for interprocess communi cation between johd and joh cgi If both processes run on the same box then localhost or some UNIX socket is a natural choice Now start the daemon johd 1 127 0 0 1 Make sure the socket 127 0 0 1 1100 is accessible from localhost In par ticular if your etc hosts deny contains the line ALL ALL place this in your etc hosts allow johd 127 0 0 1 Similarly make sure outgoing connections to selected Jabber servers are allowed for localhost johd jabber 213 130 31 41 127 0 0 1 Then copy joh cgi to your cgi bin directory and you re done You might also wish to configure your HTTP server to use some good looking alias for that For example in my Apache configuration I use Alias http poll var www cgi bin joh cgi If your HTTP server and johd are running on different machines you will need to inform joh cgi about the address johd is listening on Suppose for examp
3. Conditions under which the bug appears Any errors typos or omissions found in this manual also qualify as bugs Please report them if you happen to find any Appendix A GNU Free Documentation License Appendix A GNU Free Documentation 19 License Version 1 2 November 2002 Copyright 2000 2001 2002 Free Software Foundation Inc 59 Temple Place Suite 330 Boston MA 02111 1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document but changing it is not allowed PREAMBLE The purpose of this License is to make a manual textbook or other functional and useful document free in the sense of freedom to assure everyone the effective freedom to copy and redistribute it with or with out modifying it either commercially or noncommercially Secondarily this License preserves for the author and publisher a way to get credit for their work while not being considered responsible for modifications made by others This License is a kind of copyleft which means that derivative works of the document must themselves be free in the same sense It com plements the GNU General Public License which is a copyleft license designed for free software We have designed this License in order to use it for manuals for free soft ware because free software needs free documentation a free program should come with manuals providing the same freedoms that the soft ware does But this License i
4. back instead If JOH_ERROR_REDIRECT variable is set and its value isa URL which begins with http joh cgi responds with a redirection to that URL 2 6 Logging and Debugging Normally johd prints any errors warnings and other diagnostic messages on standard error You can however change this default and direct all diagnostic messages to syslog To do so specify the desired syslog facility with the F command line option For example johd F daemon Allowed facility names for use with this option are user daemon auth authpriv mail cron local0 through local7 All names are case insensitive Notice that when given the D option see daemon page 7 johd automatically assumes F daemon so you need not use the F option unless of course you want to change the default facility Messages sent to syslog are prefixed by the program name To change this prefix use the L option Its argument will be used as a log tag to prefix each message with Each diagnostic message has a severity level associated with it Sever ity levels are in order of increasing severity debug warning info error and crit The latter is assigned to conditions which cause imme diate termination of the program Normally severity levels are not printed To instruct johd to precede each message with its severity level use the P op
5. by the TCP service name johd the two HTTP sockets by service name johd http and the CGI socket 10 10 0 1 by service name johd cgi Connections to remote Jabber servers are also validated using TCP wrap pers However they use different service name The service name for vali dating a requested jabber connection is created using the following pattern srvname jabber ipaddr where srvname is the TCP service name as described above and ipaddr is the IP address of the server 2 2 Using JOH in Standalone Mode Configuring johd to work in standalone mode is pretty straightforward all you have to do is give it an address or addresses to listen on and instruct it to open these addresses in HTTP class In a simplest case the following command will do johd c HTTP It will instruct johd to listen on port 80 on all configured network inter faces To select a particular address or addresses to listen on use the 1 option as described in the previous section It is important to configure your etc hosts allow to control accesses to the incoming HTTP port and outgoing Jabber connections For example the two lines below allow access to HTTP from anywhere and grant anybody the right to request any Jabber servers johd ALL johd jabber ALL ALL As a more complex example the entries below allow access to HTTP from anywhere and limit the use of Jabber servers to 208 68 163 220 and
6. display copies 3 COPYING IN QUANTITY If you publish printed copies or copies in media that commonly have printed covers of the Document numbering more than 100 and the Document s license notice requires Cover Texts you must enclose the copies in covers that carry clearly and legibly all these Cover Texts Front Cover Texts on the front cover and Back Cover Texts on the back cover Both covers must also clearly and legibly identify you as the publisher of these copies The front cover must present the full title with all words of the title equally prominent and visible You may add other material on the covers in addition Copying with changes limited to the covers as long as they preserve the title of the Document and satisfy these conditions can be treated as verbatim copying in other respects If the required texts for either cover are too voluminous to fit legibly you should put the first ones listed as many as fit reasonably on the actual cover and continue the rest onto adjacent pages If you publish or distribute Opaque copies of the Document numbering more than 100 you must either include a machine readable Transparent copy along with each Opague copy or state in or with each Opaque 22 JOH User Manual Copy a computer network location from which the general network using public has access to download using public standard network protocols a complete Transparent copy of the Document free of added material If
7. parts scheme adress port Up to two parts can be omitted if that does not create ambiguity Valid URL schemes are unix inet Specifies a UNIX socket The address part is the socket path name and the port part is not used The pathname must be absolute e g unix var run joh socket To facilitate typing the two slashes after the colon can be omit ted as in unix var run joh socket Specifies an IPv4 socket The address part must be an IPv4 address in dotted quad form or a host name If the latter re solves to multiple addresses those belonging to the IPv4 family Chapter 3 Johd Jabber Over HTTP Daemon 13 are selected The port part is either the network port number in decimal or a corresponding service name from etc services For example inet 127 0 0 1 1100 inet6 Specifies an IPv6 socket The address part must be either an IPv6 address in numeric notation enclosed in square brackets or a host name If the latter resolves to multiple addresses those belonging to the IPv6 family are selected The port part is either the network port number in decimal or a corresponding service name from etc services E g inet6 1 1100 For URLs given as argument to the 1 option either address or port can be omitted If address is omitted the program will listen on all available network interfaces with addresses from the specified family e g inet6 1100 instructs johd to li
8. to receive data formatted in accordance with the HTTP pro tocol and auxiliary CGI sockets which are designed to communicate with joh cgi By default the latter is assumed The class of the socket to open is changed by the c command line option c HTTP tells johd to open all subsequent sockets for listening on HTTP requests and c CGI instructs it to open them for handling internal CGI protocol data The c option affects all 1 options that appear to the right of it in the command line until another c option is encountered which changes the default To illustrate this consider the following invocation johd 1 127 0 0 1 1111 c HTTP 1 10 10 0 1 1 192 168 0 2 c CGI 10 10 0 1 It opens two sockets for auxiliary CGI one at 127 0 0 1 1111 it appeared before the first c option and therefore belongs to the default class which is CGI and the other at 10 10 0 1 which appears after an explicit c CGI Notice that this later has no port specification If the port is missing johd will select the default port for this class The default port for CGI is 11003 and the default for HTTP is of course 80 Therefore the command above will listen for HTTP requests on 10 10 0 1 80 and 192 168 0 2 80 Each incoming connection is validated via TCP wrappers The default daemon or service name for validation coincides with the name johd was invoked with i e is johd un
9. wish to use a standalone machine as Jabber proxy In this case you would use johd in standalone mode on this machine and configure it to communicate with your main Jabber server 2 1 Configure johd Sockets Johd reads its configuration from the command line Only the traditional short options are used The order in which you place options is important some of them affect others that appear further in the command line The 1 option configures a socket to listen on hence its mnemonics listen Tts argument is an URL or address specification for the socket Nor mally this specification is the desired IP address and port number separated by a colon For example to have johd listen on IP address 127 0 0 1 port 1111 you would write johd 1 127 0 0 1 1111 If you wish it to listen on a given port on all configured network interfaces just specify that port alone without a specific IP address as in johd 1 1111 4 JOH User Manual In fact Johd is able to work with three distinct socket families UNIX sockets IPv4 and IPv6 inet addresses There are various ways to specify these For a detailed discussion of them see Section 3 1 URLs page 12 Any number of 1 options can be given johd will open all required sockets and will listen for connections on any of them The important point is the class of the socket to open As you already know johd works with two distinct socket classes HTTP sockets which are supposed
10. A A ate ete a eee ates 12 3 2 Exit Codes OE Er uet EE HE OE OK 13 o TN AE REO 14 4 Joh cgi Auxiliary CGI Utility 15 5 How to Report a Bug 17 Appendix A GNU Free Documentation License RE OE ere ere HEN 19 A1 ADDENDUM How to use this License for your documents 26 Concept Index da ninia Ree ies 27 Chapter 1 Introduction 1 1 Introduction Most site administrators use firewalls to protect their network from eventual abuse Quite often such firewalls do not allow outbound connections to un known and unused ports including Jabber client connection port 5222 tcp which makes it impossible to use Jabber services from inside such firewalls Several methods have been proposed so far to overcome this difficulty The most reliable of them is Jabber HTTP Polling which enables access to Jabber ports via HTTP requests Yet another method of accessing Jabber via HTTP is HTTP Connect This method uses the HTTP CONNECT command to establish a permanent connection to the remote Jabber server JOH supports both methods The name JOH stands for Jabber Over HTTP The package provides an easy to use proxy server for Jabber connec tions It is intended for use by system administrators who wish to provide access to their Jabber serves via HTTP for those users who happen to be behind strict firewalls 1 See http xmpp org extensions xep 0025 html Chapter 2 Quick Start 3 2 Quick Start T
11. JOH User Manual version 1 3 31 March 2011 Sergey Poznyakoff Copyright 2011 Sergey Poznyakoff Permission is granted to copy distribute and or modify this document un der the terms of the GNU Free Documentation License Version 1 3 or any later version published by the Free Software Foundation with no Invariant Sections with the Front Cover texts being JOH User Manual and with the Back Cover Texts as in a below A copy of the license is included in the section entitled GNU Free Documentation License a The Back Cover Text is You have freedom to copy and modify this manual like Free Software Short Contents gt O RE W W HH Miracle TOL LI 1 Quick de uet db Ee ES dd OE eR SE RE SE AF 3 Johd Jabber Over HTTP Daemon 2 4 11 Joh cgi Auxiliary CGI UGW 15 How to Report Bug za tad eek bit epa Ped aes 17 GNU Free Documentation License ooooooooo oo 19 Concept Index 22222252244 EER ern rein 27 ii Table of Contents 1 id AAA 1 2 Quick AS 3 2 1 Configure johd Sockets 0 SE SE ES Ee SE ee ge SS ke eg ke 3 2 2 Using JOH in Standalone Mode se esse ee Se see ee eee 5 2 3 Using JOH in CGI Mode sees ds se ee e 6 2 4 Two Ways to Start johd 22222ecsseeeeneeenerene rennen 6 2 5 HTTP GET Reguests iss ee ee se ee III He 8 2 6 Logging and Debugging iii ES SEG ES aaa eee eee ee 9 3 Johd Jabber Over HTTP Daemon 11 A
12. ML file The contents of this file will be sent back in 404 responses 6 Similarly to c and S options the E option applies to all HTTP sockets created by subsequent 1 options which appear to the right of it until another E or R option see below is encountered An example usage follows johd c HTTP E etc joh 404 html 1 10 10 10 1 Another way to handle GET requests is to return a 303 response redi recting the requester to another HTTP resource This is achieved via the R option Its argument is a valid URL beginning with a http For example johd c HTTP R http www example net jabber Notice that E and R options are mutually exclusive For example the following invocation will reply to GET requests arriving to 10 10 10 1 with the error page read from etc joh 404 html and will redirect any GET request arriving to 10 10 10 2 to http www example net jabber johd c HTTP E etc joh 404 html 1 10 10 10 1 R http www example net jabber 1 10 10 10 2 The joh cgi utility provides similar features except that it cannot send back a 404 response Chapter 2 Quick Start 9 If any request other than POST arrives joh cgi replies with the compiled in error page just as johd does If the JOH ERROR PAGE envi ronment variable is set and its value points to a readable file this file s contents is sent
13. R_URL Sets the URL of the johd server Default is 127 0 0 1 1100 JOH JABBER SERVER URL Sets the URL of the default Jabber server This value is used when the incoming HTTP request does not specify server and port explicitly The default value is inet gnu org ua JOH JABBER SERVER Specifies the IP address of the default Jabber server JOH JABBER PORT Sets the port name of the default Jabber server JOH ERROR PAGE If any request other than POST arrives return the contents of the file specified in the value of this variable See joh cgi bad request handling page 8 JOH ERROR REDIRECT If any request other than POST arrives redirect it to the URL supplied in this variable See joh cgi bad request handling page 8 Chapter 5 How to Report a Bug 17 5 How to Report a Bug Please report bugs and suggestions to graytjoh gnu org ua You hit a bug if at least one of the conditions below is met e johd of joh cgi terminate on signal 11 SIGSEGV or 6 SIGABRT e johd terminates with exit code 70 internal software error e Either of the components fails to do its job as described in this manual If you think you ve found a bug please be sure to include maximum information available to reliably reproduce it or at least to analyze it The information needed is e Version of the package you are using e Compilation options used when configuring the package e Command line options used e
14. art johd add the following component statement to your configuration file component johd command johd options strderr syslog err E Replace johd with the full pathname of the johd binary and options with the desired command line options For example component johd command usr sbin johd c HTTP strderr syslog err Another way to start johd is independently of the Jabber server To do so give it the D command line option This option instructs johd to disconnect from the controlling terminal and run in the background as a daemon Diagnostic messages are then sent to the syslog using the daemon facility this can be changed using the F option see Section 2 6 logging page 9 Normally johd continues its operation with the privileges of the user who started it If this user is root you may wish johd to run as some other user To do so use the u option e g johd cHTTP D u nobody The daemon switches to new user after completing operations that require root privileges such as e g creating sockets that listen on ports below 1024 etc When starting johd in daemon mode it is also common to give it the p option This option takes a file name as argument and causes the program to write its PID to that file after switching to the background If this file already exists johd will read the PID from it and will check if a process with that PID is actually running If so johd refus
15. bed 9 HIST AE EE 12 ON 13 IPv4 sockets sn 12 IPv6 sockets 22 122 1 13 JAD Ber 4 ese seg ass page REK DEER ENE 6 JOM ER das ui Me De ERA iamos ie de EWER 15 joh cgi described 6 JOH ERROR PAGE 8 15 JOH_ERROR_REDIRECT 9 15 JOH_JABBER_PORT 15 JOH_JABBER_SERVER 15 JOH_JABBER_SERVER_URL 15 JOH SERVER URL ss awa sea a 15 JO di 11 L l l option introduced 3 L L option described 9 Ly EL AE ea 11 lj l Url eu a nee na 11 log tags ass ea 9 P PEER EE 11 Pi El AE excede 11 p p option described T P P option described 9 Ip T ls aT TTT 7 28 R R R option introduction 8 R SR urd esse ieee as ans A S Si AD Dame MA ctra EO 12 S S option introduced 4 AE ii 12 service name TCP wrappers 4 severity level 221 111 1 9 a OR Gad WA 14 socket class 2 cece eee eee eee eee 4 sock ts JONG ees sie Ee DoE EE NE EE ie 3 source location Ee ee Sek eee 9 standalone mode 5 standalone mode defined 3 startup Script us EES EERDER BE eve BESIG EE T startup JON iss see HERE EER EER EE EE weeds 6 JOH User Manual t t type timeout 12 AI ce ee eme he atei 9 TCP wrappers ee ed ss s
16. e eed 4 U u u option introduction Pi U FU US RE RE RE Dar 12 UNIX socket 12 uni URG ns gee GE EER RE DEE 12 iji Mc EE ER EG EG 12
17. ents provided it contains nothing but endorsements of your Modified Version by various parties for example statements of peer review or that the text has been ap proved by an organization as the authoritative definition of a standard You may add a passage of up to five words as a Front Cover Text and a passage of up to 25 words as a Back Cover Text to the end of the list of Cover Texts in the Modified Version Only one passage of Front Cover Text and one of Back Cover Text may be added by or through ar rangements made by any one entity If the Document already includes a cover text for the same cover previously added by you or by arrange ment made by the same entity you are acting on behalf of you may not add another but you may replace the old one on explicit permission from the previous publisher that added the old one 24 JOH User Manual The author s and publisher s of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version COMBINING DOCUMENTS You may combine the Document with other documents released under this License under the terms defined in section 4 above for modified versions provided that you include in the combination all of the Invari ant Sections of all of the original documents unmodified and list them all as Invariant Sections of your combined work in its license notice and that you preserve all their Wa
18. es to startup and outputs an appropriate diagnostics Otherwise it will overwrite the file with the new PID value If both u and p are used the pidfile is opened after switching to the user provileges In this case you should make sure the directory component of the pidfile is writable for the user supplied with the u option Following is an example startup command johd D p var run johd pid To automate startup and shutdown of johd in daemon mode use the following shell script 8 JOH User Manual bin sh PIDFILE var run johd pid case 1 in start usr bin johd D p PIDFILE stop test f PIDFILE amp amp kill TERM cat PIDFILE restart 0 stop 0 start echo gt amp 2 usage 0 start stop restart esac 2 5 HTTP GET Requests Proxying of Jabber connections is requested by HTTP requests with either POST or CONNECT methods Any other requests received by johd are nor mally dropped However GET requests are handled separately Normally an incoming GET request means that someone has pointed his web browser to the URL served by johd When such a request arrives johd replies with a 404 response code A compiled in error page is sent back in the response This behavior can be customized in two ways First you can supply a custom error page using the E command line option The argument to this option must specify an absolute pathname to a valid HT
19. he controlling terminal An internal software error has been detected If it ever hap pens please report this as bug See Chapter 5 Reporting Bugs page 17 Temporary error condition Currently this happens if the p file option is specified file exists but cannot be accessed A configuration error occurred This is different from usage error 64 in that the data supplied to the program where syntactically correct but cannot be used For example a host name supplied with 1 cannot be resolved 3 3 Signals The following signals cause immediate program termination with exit code 0 SIGPIPE SIGINT SIGQUIT SIGTERM SIGHUP Chapter 4 Joh cgi Auxiliary CGI Utility 15 4 Joh cgi Auxiliary CGI Utility If you need to run johd on a box which already runs an HTTP server it is impossible to have johd handle HTTP connections directly because port 80 is already in use The solution then is to use joh cgi within your HTTP server and to start johd in CGI mode This approach is discussed in detail in Section 2 3 cgi page 6 The usual way to run joh cgi is to copy it to your cgi bin directory and to provide an alias for it For example in Apache httpd conf Alias http poll var www cgi bin joh cgi The built in default configuration is sufficient for most cases If however you need to configure joh cgi you can do so via the following environment variables JOH_SERVE
20. here are two most common scenarios for configuring Jabber Over HTTP proxy In the first scenario you have a dedicated Jabber server and the port 80 HTTP is not used on that server In this case you will use standalone mode In this mode johd is configured to listen on port 80 to proxy incoming requests to your Jabber server and vice versa In the second scenario the port 80 is already in use by an HTTP server running on the same box as your Jabber server For such cases JOH provides a CGI mode In this mode you start johd to listen on an auxiliary port and configure your HTTP server to run a CGI program joh cgi which is included in the package The system then works as follows HTTP polling requests are received by your HTTP server which invokes joh cgi to handle them In its turn joh cgi extracts the necessary data from each request reformats it and sends it over to the johd daemon over the auxiliary port When a subsequent request arrives joh cgi receives the reply from johd formats it as a HTTP response and sends it back to the HTTP server which sends it to the requesting client The CGI mode works only with HTTP Polling Of course there may be combined cases e g e You run HTTP and Jabber servers on separate boxes but wish your HTTP server to handle polling requests for your Jabber server In such cases you would also use the CGI mode The joh cgi would be installed on the HTTP server and johd on the Jabber server e You
21. ied Version together with at least five of the principal authors of the Document all of its principal authors if it has fewer than five unless they release you from this requirement C State on the Title page the name of the publisher of the Modified Version as the publisher D Preserve all the copyright notices of the Document E Add an appropriate copyright notice for your modifications adja cent to the other copyright notices F Include immediately after the copyright notices a license notice giving the public permission to use the Modified Version under the terms of this License in the form shown in the Addendum below G Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document s license notice H Include an unaltered copy of this License I Preserve the section Entitled History Preserve its Title and add to it an item stating at least the title year new authors and publisher of the Modified Version as given on the Title Page If Appendix A GNU Free Documentation License 23 there is no section Entitled History in the Document create one stating the title year authors and publisher of the Document as given on its Title Page then add an item describing the Modified Version as stated in the previous sentence J Preserve the network location if any given in the Document for public access to a Transparent copy of the Document and likew
22. ise the network locations given in the Document for previous versions it was based on These may be placed in the History section You may omit a network location for a work that was published at least four years before the Document itself or if the original publisher of the version it refers to gives permission K For any section Entitled Acknowledgements or Dedications Preserve the Title of the section and preserve in the section all the substance and tone of each of the contributor acknowledgements and or dedications given therein L Preserve all the Invariant Sections of the Document unaltered in their text and in their titles Section numbers or the eguivalent are not considered part of the section titles M Delete any section Entitled Endorsements Such a section may not be included in the Modified Version N Do not retitle any existing section to be Entitled Endorsements or to conflict in title with any Invariant Section O Preserve any Warranty Disclaimers If the Modified Version includes new front matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document you may at your option designate some or all of these sections as invariant To do this add their titles to the list of Invariant Sections in the Modified Version s license notice These titles must be distinct from any other section titles You may add a section Entitled Endorsem
23. le that johd is running on machine A and is listening on IP address 192 168 0 1 port 1100 The HTTP server is running on the machine B which has IP address 192 168 0 2 To tell joh cgi it must connect to 192 168 0 1 1100 set the environment variable JOH SERVER URL For example if B is running Apache then in your httpd conf you would set SetEnv JOH SERVER URL 192 168 0 1 1100 Notice also that you need to ensure that this socket on the box A is accessible only to 192 168 0 2 For example 1 In etc hosts deny johd ALL 2 In etc hosts allow johd 192 168 0 2 2 4 Two Ways to Start johd One of the basic assumptions made when designing johd was that it was to be run as a transport within Jabber configuration Therefore after startup johd remains in the foreground and does not disconnect from the controlling terminal It also normally sends all its diagnostic messages to the standard error output but see Section 2 6 logging page 9 below To start jabber2 components we recommend using GNU Pies instead of the default simple program manager shipped with Jabberd2 Pies of Chapter 2 Quick Start 7 fers considerable flexibility in handling jabber components For a detailed description of Pies Section Top in GNU Pies Manual For an exam ple of Jabberd2 configuration with Pies refer to http www gnu org ua software pies example php what jabberd2 To configure Pies to st
24. less you renamed the program or started it via a symlink However the validation rules will most probably depend on the class of socket that received the connection internal CGI sockets in most cases should not be visible outside your host whereas HTTP ones should be accessible to everybody Therefore a special option is provided which changes the TCP wrapper service name for subsequent sockets This is the S option mnemonics Service name Similarly to c the S 1 The decision which class to take as the default is somehow arbitrary we might as well have chosen HTTP but historically it happened to be CGI 7 Again the choice was somewhat arbitrary but we know of no other service using this number 3 See Section ACCESS CONTROL FILES in hosts_access 5 man page for detailed description of TCP wrapper access control files Note also that this feature can be disabled at compile time by the without tcp wrappers option to configure although this is highly unrecommended Chapter 2 Quick Start 5 option affects all 1 options to the right of it until another S option or end of the command line is encountered whichever occurs first Now let s illustrate this by an improved version the example above johd 1 127 0 0 1 1111 S johd http c HTTP 1 10 10 0 1 1 192 168 0 2 s johd cgi c CGI 10 10 0 1 In this configuration the 127 0 0 1 1111 socket will be protected
25. matics The relationship could be a matter of historical connection with the subject or with related matters or of legal commercial philosophical ethical or political position regarding them The Invariant Sections are certain Secondary Sections whose titles are designated as being those of Invariant Sections in the notice that says that the Document is released under this License If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant The Document may contain zero Invariant Sections If the Document does not identify any Invariant Sections then there are none The Cover Texts are certain short passages of text that are listed as Front Cover Texts or Back Cover Texts in the notice that says that the Document is released under this License A Front Cover Text may be at most 5 words and a Back Cover Text may be at most 25 words A Transparent copy of the Document means a machine readable copy represented in a format whose specification is available to the general public that is suitable for revising the document straightforwardly with generic text editors or for images composed of pixels generic paint pro grams or for drawings some widely available drawing editor and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters A copy made in an otherwise Transparent file format who
26. ment specifies that a particular numbered version of this License or any later version applies to it you have the option of following the terms and conditions either of that specified version or of any later version that has been published not as a draft by the Free Software Foundation If the Document does not specify a version number of this License you may choose any version ever published not as a draft by the Free Software Foundation 26 JOH User Manual A 1 ADDENDUM How to use this License for your documents To use this License in a document you have written include a copy of the License in the document and put the following copyright and license notices just after the title page Copyright C year your name Permission is granted to copy distribute and or modify this document under the terms of the GNU Free Documentation License Version 1 2 or any later version published by the Free Software Foundation with no Invariant Sections no Front Cover Texts and no Back Cover Texts A copy of the license is included in the section entitled GNU Free Documentation License If you have Invariant Sections Front Cover Texts and Back Cover Texts replace the with Texts line with this with the Invariant Sections being list their titles with the Front Cover Texts being list and with the Back Cover Texts being list If you have Invariant Sections without Cover Texts or some other com bination of the three
27. ng page 9 Write PID to file See daemon page 7 12 R url S name s url JOH User Manual Redirect HTTP GET requests to url The argument must begin with http See Section 2 5 get page 8 This option affects all HTTP sockets created by subsequent 1 options which appear to the right of it until another R option or end of command line is encountered whichever occurs first Sets service name for TCP wrappers This option affects all subsequent 1 options appearing to the right of it until another S option or end of command line is encountered whichever occurs first See TCP wrappers page 4 Sets URL of the default jabber server It is used if the request does not specify the server explicitly t type timeout Sets session idle timeout Type is the type of the socket C for client sockets either CGI or HTTP and J for Jabber socket Timeout is the timeout value either in seconds or in XhYmZs form Defaults are t C 5m t J 1m u user Run as user after completing privileged operations such as cre ating sockets that listen on ports below 1024 See daemon page 7 eV Prints the program version 3 1 URLs JOH components are able to handle three socket families UNIX sockets IPv4 and IPv6 URLs provide a uniform way of specifying socket addresses in any of these families A URL consists of the following
28. ntheses fol lowing text that translates XYZ in another language Here XYZ stands for a specific section name mentioned below such as Acknowledge ments Dedications Endorsements or History To Preserve the Title of such a section when you modify the Document means that it remains a section Entitled XYZ according to this definition The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document These Warranty Disclaimers are considered to be included by reference in this License but only as regards disclaiming warranties any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License 2 VERBATIM COPYING You may copy and distribute the Document in any medium either com mercially or noncommercially provided that this License the copyright notices and the license notice saying this License applies to the Docu ment are reproduced in all copies and that you add no other conditions whatsoever to those of this License You may not use technical mea sures to obstruct or control the reading or further copying of the copies you make or distribute However you may accept compensation in ex change for copies If you distribute a large enough number of copies you must also follow the conditions in section 3 You may also lend copies under the same conditions stated above and you may publicly
29. quent 1 options appearing to the right of it until another c option or end of command line is encountered whichever occurs first See socket class page 4 D After startup switch to the background and run as daemon See daemon page 7 d number Sets debugging level See Section 2 6 logging page 9 E file Read the 404 error page from file This error page is returned as a response to HTTP GET requests The file must contain a valid HTML document without external references in the head section See Section 2 5 get page 8 This option affects all HTTP sockets created by subsequent 1 options which appear to the right of it until another E option or end of command line is encountered whichever occurs first F facility Sets syslog facility Allowed values for facility are user daemon auth authpriv mail cron local0 through local7 All names are case insensitive See Section 2 6 logging page 9 h Shows a terse help summary i Show source line information with debug messages See Section 2 6 logging page 9 L string Sets log tag See Section 2 6 logging page 9 l url Listen on the given url Several 1 options can appear in the command line See listen option page 3 p Prefix diagnostic messages with their severity level See p file Section 2 6 loggi
30. rranty Disclaimers The combined work need only contain one copy of this License and multiple identical Invariant Sections may be replaced with a single copy If there are multiple Invariant Sections with the same name but different contents make the title of each such section unique by adding at the end of it in parentheses the name of the original author or publisher of that section if known or else a unique number Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work In the combination you must combine any sections Entitled History in the various original documents forming one section Entitled His tory likewise combine any sections Entitled Acknowledgements and any sections Entitled Dedications You must delete all sections Enti tled Endorsements COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other docu ments released under this License and replace the individual copies of this License in the various documents with a single copy that is included in the collection provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects You may extract a single document from such a collection and distribute it individually under this License provided you insert a copy of this License into the extracted document and follow this License in all other respec
31. s not limited to software manuals it can be used for any textual work regardless of subject matter or whether it is published as a printed book We recommend this License principally for works whose purpose is instruction or reference APPLICABILITY AND DEFINITIONS This License applies to any manual or other work in any medium that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License Such a notice grants a world wide royalty free license unlimited in duration to use that work under the conditions stated herein The Document below refers to any such manual or work Any member of the public is a licensee and is addressed as you You accept the license if you copy modify or distribute the work in a way requiring permission under copyright law A Modified Version of the Document means any work containing the Document or a portion of it either copied verbatim or with modifica tions and or translated into another language A Secondary Section is a named appendix or a front matter section of the Document that deals exclusively with the relationship of the pub lishers or authors of the Document to the Document s overall subject or to related matters and contains nothing that could fall directly within 20 JOH User Manual that overall subject Thus if the Document is in part a textbook of mathematics a Secondary Section may not explain any mathe
32. se markup or absence of markup has been arranged to thwart or discourage subsequent modi fication by readers is not Transparent An image format is not Trans parent if used for any substantial amount of text A copy that is not Transparent is called Opaque Examples of suitable formats for Transparent copies include plain ASCII without markup Texinfo input format LaTEX input format SGML or XML using a publicly available DTD and standard conforming simple HTML PostScript or PDF designed for human modification Examples of transparent image formats include PNG XCF and JPG Opaque for mats include proprietary formats that can be read and edited only by proprietary word processors SGML or XML for which the DTD and or processing tools are not generally available and the machine generated HTML PostScript or PDF produced by some word processors for output purposes only The Title Page means for a printed book the title page itself plus such following pages as are needed to hold legibly the material this License requires to appear in the title page For works in formats which do not have any title page as such Title Page means the text near the most prominent appearance of the work s title preceding the beginning of the body of the text Appendix A GNU Free Documentation License 21 A section Entitled XYZ means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in pare
33. sten on port 1100 on all IPv6 interfaces 6 If port is omitted the default is selected depending upon the class of the socket 1100 is used for CGI sockets and 80 is used for HTTP sockets The port component can also be omitted in URLs which are arguments to the s option see default jabber server page 12 In this case port defaults to 5222 e g inet6 1 inet 127 0 0 1 For compatibility with earlier versions johd accepts IPv6 addresses with out square brackets although such use is not recommended e g inet6 1 1100 If the scheme part is omitted johd tries to do its best to guess what address family is assumed Thus var run socket is treated as unix var run socket 127 0 0 1 is treated as inet 127 0 0 1 1 3398 is treated as inet6 1 3398 1 3398 is treated as inet6 1 3398 The URL 3456 causes johd to listen on port 3456 on all available net work interfaces no matter what their address family is 3 2 Exit Codes Depending on the reason for termination johd exits with the following codes 0 Normal termination This includes e g termination on SIGTERM signal 64 Usage error e g unknown option or erroneous argument was given in the command line 14 69 70 75 78 JOH User Manual A service is unavailable This happens for instance if the pro gram could not fork or disconnect from t
34. tion Debugging diagnostics is useful when you trace some difficult configura tion problem or investigate a bug in johd itself This diagnostics is printed only when the d option is given The argument to the d option is the debugging level an integer number ranging from 0 to 100 Level 0 effectively disables all debugging and is equivalent to not specifying d option at all Subsequent levels produce increasing amount of debugging information Fi nally the level 100 prints dumps of network packets received and sent by johd Notice that the use of the d option with levels greater than 10 requires a good knowledge about johd internals and slows down its operation so use it sparingly if at all When debugging johd it may be helpful to know where precisely in the source code each debugging message was generated This information can be obtained using the i source info option When it is given each debug 10 JOH User Manual message is additionally prefixed with the name of the source file and line number in it Chapter 3 Johd Jabber Over HTTP Daemon 11 3 Johd Jabber Over HTTP Daemon The following table summarizes the available command line options in al phabetic order For each option it provides a reference to the place in the tutorial where the option is discussed c class Sets socket class Allowed values for class are CGI and HTTP This option affects all subse
35. translation of this License and all the license notices in the Document and any Warranty Disclaimers pro vided that you also include the original English version of this License and the original versions of those notices and disclaimers In case of a disagreement between the translation and the original version of this License or a notice or disclaimer the original version will prevail If a section in the Document is Entitled Acknowledgements Dedi cations or History the requirement section 4 to Preserve its Title section 1 will typically require changing the actual title TERMINATION You may not copy modify sublicense or distribute the Document ex cept as expressly provided for under this License Any other attempt to copy modify sublicense or distribute the Document is void and will automatically terminate your rights under this License However par ties who have received copies or rights from you under this License will not have their licenses terminated so long as such parties remain in full compliance FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new revised versions of the GNU Free Documentation 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 See http www gnu org copyleft Each version of the License is given a distinguishing version number If the Docu
36. ts regarding verbatim copying of that document AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works in or on a volume of a storage or distribution medium is called an aggregate if the copyright resulting from the compilation is not used to limit the legal rights of the com pilation s users beyond what the individual works permit When the Document is included an aggregate this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document If the Cover Text requirement of section 3 is applicable to these copies of the Document then if the Document is less than one half of the entire Appendix A GNU Free Documentation License 25 10 aggregate the Document s Cover Texts may be placed on covers that bracket the Document within the aggregate or the electronic eguivalent of covers if the Document is in electronic form Otherwise they must appear on printed covers that bracket the whole aggregate TRANSLATION Translation is considered a kind of modification so you may distribute translations of the Document under the terms of section 4 Replacing Invariant Sections with translations requires special permission from their copyright holders but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections You may include a
37. you use the latter option you must take reasonably prudent steps when you begin distribution of Opaque copies in quantity to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy directly or through your agents or retailers of that edition to the public It is requested but not required that you contact the authors of the Document well before redistributing any large number of copies to give them a chance to provide you with an updated version of the Document MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above provided that you release the Modified Version under precisely this License with the Modified Version filling the role of the Document thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it In addition you must do these things in the Modified Version A Use in the Title Page and on the covers if any a title distinct from that of the Document and from those of previous versions which should if there were any be listed in the History section of the Document You may use the same title as a previous version if the original publisher of that version gives permission B List on the Title Page as authors one or more persons or enti ties responsible for authorship of the modifications in the Modif
Download Pdf Manuals
Related Search