Add Install from confluence to the repository & also contains the FAQ'S
Project: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/commit/97eda9a7 Tree: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/tree/97eda9a7 Diff: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/diff/97eda9a7 Branch: refs/heads/0.4 Commit: 97eda9a77c6cdd3df14d0b1709d354e712d3fa1c Parents: 6547712 Author: Evan Hughes <ehu...@gmail.com> Authored: Thu Jul 9 19:11:45 2015 +1000 Committer: Evan Hughes <ehu...@gmail.com> Committed: Thu Jul 9 19:11:45 2015 +1000 ---------------------------------------------------------------------- source/manual/Installing/Wave-As-Service.rst | 78 +++++ source/manual/Installing/build.rst | 67 +++++ source/manual/Installing/federation.rst | 288 +++++++++++++++++++ .../Installing/federation/certificates.rst | 277 ++++++++++++++++++ .../manual/Installing/federation/openfire.rst | 126 ++++++++ source/manual/Installing/federation/prosody.rst | 51 ++++ source/manual/Installing/index.rst | 182 ++++++++++++ source/manual/Installing/logging.rst | 78 +++++ source/manual/Installing/run-export.rst | 40 +++ source/manual/Resources/fedone.png | Bin 0 -> 21128 bytes source/manual/Resources/networklayout.png | Bin 0 -> 12299 bytes .../Resources/openfire01-server-setting.jpg | Bin 0 -> 39526 bytes .../Resources/openfire02-database-settings.jpg | Bin 0 -> 47634 bytes .../Resources/openfire03-profile-settings.jpg | Bin 0 -> 53911 bytes .../Resources/openfire04-administer-account.jpg | Bin 0 -> 52232 bytes .../openfire05-external-components-02.png | Bin 0 -> 61802 bytes .../openfire06-security-settings-tls-custom.jpg | Bin 0 -> 48097 bytes source/manual/index.rst | 3 +- 18 files changed, 1189 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Installing/Wave-As-Service.rst ---------------------------------------------------------------------- diff --git a/source/manual/Installing/Wave-As-Service.rst b/source/manual/Installing/Wave-As-Service.rst new file mode 100644 index 0000000..6e9b39c --- /dev/null +++ b/source/manual/Installing/Wave-As-Service.rst @@ -0,0 +1,78 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _Run-Wave-as-a-Windows-Service: + +Run Wave as a Windows Service +============================= + +Running WIAB as a Windows Service allows Wave to run in the background when the host machine is started. This negates +the need for you to log in and run the batch file from the command line. To accomplish this you must register Wave with +the Windows Service Manager. The Windows Service Manager does not have native support for running batch (.bat) files, +therefore you must use an external program to execute Wave through the Service Manager. The two most prevalent options +are the Windows Resource Kit and NSSM (the Non-Sucking Service Manager). These instructions focus on the NSSM +installation. + + +Service Installation (NSSM) +--------------------------- + +Download and extract NSSM-<version>.zip from http://iain.cx/src/nssm/ into a path on local machine (note: advise to use +path without spaces) + +Open a Command Prompt at the directory NSSM is installed (if not placed on system path) and run: + +* nssm install WaveInABox (note: you can substiture WaveInABox for the service name of your choice) + +After executing this command a Graphical UI will appear. On the UI edit the Application field to + +* c:\<path-to>\run-nofed-config.bat + +Edit Default Behaviour on AppExit +--------------------------------- +The default behavior of NSSM is to restart WaveInaBox if it errors out or is killed. To set it to gracefully exit: + +* open regedit (start > run > type regedit or open command prompt and type regedit) +* navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WaveInABox <or your chosen service name>\Parameters\ + AppExit +* Edit (Default) key to equal Exit or Ignore or Suicide or Restart (Restart is default) + +Create a Dependency for Service +------------------------------- +You must edit the registry to set up a dependency for the WaveInABox service. This is useful, for example, to ensure +your XMPP server (e.g. - OpenFire) or persistent store (e.g. - mongodb) is started before WaveInABox is started. Also, +any attempt to kill the XMPP server or mongodb will alert that WaveInABox will also be affected. To create a dependency: + +* open regedit (start > run > type regedit or open command prompt and type regedit) +* navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WaveInABox <or your chosen service name> +* Right click on this folder (WaveInABox) and select New > Multi-String Value +* Edit the value name to DependOnService and then click OK. +* Double-Click the DependOnService key to open the Data dialog box. Type the name or names of the services that you + prefer to start before the wave service. You must input one entry for each line, and then click OK. For example: + MongoDB OpenFire + +.. note:: The name of the service you would enter in the Data dialog box is the exact name of the service as it + appears in the Windows Service Manager (start > run > type services.msc or open command prompt then type services.msc). + +Verify Service Installed +------------------------ +The final step is to verify the service was installed correctly and to start up your wave in a box service. + +* Go to services.msc (start > run > type services.msc or open command prompt then type services.msc). You should see + your new wave service WaveInABox. +* start WaveInABox by selecting service and clicking Start in left pane. You may also set other options at this point + by right-clicking on the serice and selecting properties. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Installing/build.rst ---------------------------------------------------------------------- diff --git a/source/manual/Installing/build.rst b/source/manual/Installing/build.rst new file mode 100644 index 0000000..07f5cfb --- /dev/null +++ b/source/manual/Installing/build.rst @@ -0,0 +1,67 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + +Building Apache Wave +==================== + +.. todo:: Add how to download source etc + +Windows +------- +Once you have the source and all of the tools installed, open up a Command shell and do the following: +:: + + set JAVA_HOME=c:\Program Files\Java\jdk[YOUR_VERSION] + set ANT=c:\Program Files\winant\bin\ant + cd [THE_FULL_PATH_TO]wave-protocol + ANT + +Note, this is for a first time build. I would recommend using the Environmental Variables section in Windows to set +these permanently for future builds. + +Running ANT will commence the build process. This will build both the Wave Server and the Web Interface. + +To rebuild the source (say after you make changes, or pull down the latest version of the code), run the following in +your wave-protocol directory via a Command shell: +:: + + ANT clean + ANT + +Linux/MacOSX +------------ +Building under OSX and Linux should not require manually setting path elements (as we had to in Windows). Simply move to +the wave-protocol directory and run: +:: + + $: ant + +To rebuild the server run: +:: + + $: ant clean; ant + +End Result +---------- +At the end of the build process you should have the following files in the dist directory under the wave-protocol +directory: + +waveinabox-client-console-0.3.jar +waveinabox-server-0.3.jar + +If you don't then go back and check the build process, something probably broke. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Installing/federation.rst ---------------------------------------------------------------------- diff --git a/source/manual/Installing/federation.rst b/source/manual/Installing/federation.rst new file mode 100644 index 0000000..b18d5d6 --- /dev/null +++ b/source/manual/Installing/federation.rst @@ -0,0 +1,288 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +Federation +========== + +.. toctree:: + :hidden: + + federation/certificates + federation/openfire + federation/prosody + + +.. todo:: Move links over to Apache infra. Explain server.federation.config. + +Introduction +------------ +Okay, so now you have WIAB up and running on your laptop. You can successfully login and talk to yourself. Now you're +getting the urge to talk to other people on other Wave servers. In order to do this you need to Federate. + +In order to federate your server you are going to need the following: + +1. A domain name +2. An ssl certificate from a trusted source (in this case, we use StartSSL) (Recommended, but not necessary whilst you + test federation) +3. An XMPP server + +Most of the instructions for setting up these things are found in the following child pages: + +* :ref:`Certificates` +* :ref:`Openfire-Installation` +* :ref:`Prosody-Installation` + +This document will walk you through setting up federation. With the exception of the configuration script, the +instructions will be OS agnostic. + +The utility of waves is greatly enhanced if they can be federated in the sense that they are shared between users from +different organisations, hosted by different service providers across the Internet. This is accomplished by the Apache +Wave federation protocol, a server-to-server network protocol between service providers, supporting low-latency, +concurrent updates to conversations ("live typing") and domain authentication. + +:strong:`STOP.` + + +:strong:`IF YOU ARE JUST TRYING TO SETUP FEDERATION ON YOUR SERVER FOLLOW THE LINKS ABOVE. IF YOU HAVE A 'SPECIAL' SETUP +, OR WANT TO UNDERSTAND HOW IT WORKS, YOU MAY CONTINUE BELOW THIS LINE.` + + +Here are some resources that explain the protocol and show how to run a federated "Wave in a Box" wave server: + +* The federation protocol `white paper <http://wave-protocol.googlecode.com/hg/whitepapers/google-wave-architecture/ + google-wave-architecture.html>`_ that accompanied the launch of Google Wave at Google IO 2009. +* The `secure server authentication design <http://www.waveprotocol.org/whitepapers/wave-protocol-verification>`_. +* The `draft protocol specification <http://wave-protocol.googlecode.com/hg/spec/federation/wavespec.html>`_. +* Wave in a Box `installation instructions <http://www.waveprotocol.org/code/installation>`_. + +After you have `installed <http://www.waveprotocol.org/code/installation>`_ your XMPP server and the Federation +extension, you can federate with other Wave servers. + +.. image:: ../Resources/fedone.png + +Overview +-------- + +To get federation working the two servers that are going to talk will need a clear view of each other. That is, each +server in the conversation needs to be able to initiate a connection with the other server doing federation, and +vise-versa. Not only does that mean that your server needs to be found via DNS, it also means that the correct port to +use for federation must be able to be found and used. + +A wave server (e.g. the one hosting waves at "initech-corp.com") will attempt to send updates to a remote wave server +(e.g. the one hosting waves at "other.com") whenever a wavelet with a remote participant (e.g. "b...@other.com") is +updated (I.e. any operation is applied, including AddParticipant?("b...@other.com")). The other case where a wave server +will send a message to a remote wave server is to submit a delta on a wave hosted at the remote wave server. The domain +name for the remote wave server is taken directly from the participant's ID (e.g. "other.com"). + +If no existing XMPP connection exists between the XMPP servers to which the wave servers are connected (via the XMPP +component protocol), a new connection needs to be established. The connection is established using XMPP hostname +resolution (draft-ietf-xmpp-3920bis) and XMPP service discovery (XEP-0030). Where a XMPP server does not offer XMPP +service discovery, or the hostname resolution on the domain name fails, a guess is made about where the wave service is +available; "wave." is prepended to the the remote domain name. + +Connection Establishment +------------------------ + +This describes the algorithm by which two Wave servers establish a connection for the purpose of federation. In this +description the functionality of the XMPP server and the wave server XMPP component are conflated into "XMPP server". +In the description below we trace the possible steps an Initiating Server (IS) takes to connect to some Other Server +(OS). The following steps reference `draft-ietf-xmpp-3920bis <http://tools.ietf.org/html/draft-ietf- +xmpp-3920bis-03#section-4.2>`_ and XMPP service discovery `XEP-0030 <http://xmpp.org/extensions/xep-0030.html>`_. + +1. Initiating XMPP server (IS) attempts to look up the SRV record(s) for _xmpp-server._tcp.other.com (OS). +2. If the lookup succeeds, proceed to step 5. +3. If the lookup fails, attempt an A record lookup for other.com +4. If the lookup succeeds, proceed to step 5, otherwise go to step 13. +5. IS connects to the XMPP server OS and initiates XMPP discovery. +6. If OS supports XMPP discovery, IS enumerates services, one item of which is hopefully "category: collaboration, type: + google-wave". The enumerated item is available on a jid, e.g. "waveservice.other.com". +7. If IS finds the disco record, and the provided jid does not match the hostname of the existing connection, it will + attempt to resolve the provided jid via the regular XMPP SRV record lookup e.g. _xmpp-server._tcp.waveservice.other + .com or the A record fallback e.g. waveservice.other.com. +8. If step 7 succeeds, proceed to step 12, otherwise goto step 9. +9. If OS does not support XMPP discovery, or does not return a discovery item for "google-wave", or the lookup on the + discovery item failed, IS will make a guess at a service jid by adding "wave." to the remote domain name, e.g. + "wave.other.com". +10. IS will attempt to resolve the guessed "wave" jid via the regular XMPP SRV record lookup e.g. + _xmpp-server._tcp.wave.other.com or the A record fallback e.g. wave.other.com. +11. If the lookup succeeds, and the IP or port is different to the connection established in 5. above, connect to the + new IP/port. If the lookup fails, goto step 13. +12. IS and OS are ready to establish TLS. Stop. +13. Failed to establish a connection. Stop. + +.. _federation-background: + +Background +---------- + +SRV Settings +^^^^^^^^^^^^ + +In order to expose a federation server, you require SRV records that describe which servers and ports that the incoming +connection should use. + +The SRV record is analogous to the old MX record for mail servers, that is, it 'points' the incoming query to the +correct server, and assigns priorities to different machines. However it contains extra information on top of this basic +data. + +A typical SRV record takes the form of: +:: + + _Service._Protocol.Name TTL Class SRV Priority Weight Port Target + +A typical Wave SRV record could be: +:: + + _xmpp-server._tcp.example.com. 86400 IN SRV 10 0 5269 wave.example.com. + +A server trying to connect to the Wave server for example.com would retrieve this record, and proceed to attempt to +connect to wave.example.com on port 5269. + +Note you could have several SRV records to specify failover/redundancy or whatever: +:: + + _xmpp-server._tcp.example.com. 86400 IN SRV 10 50 5269 wave1.example.com. + _xmpp-server._tcp.example.com. 86400 IN SRV 10 50 5269 wave2.example.com. + _xmpp-server._tcp.example.com. 86400 IN SRV 20 0 5269 backup-wave.example.com. + +A Records +^^^^^^^^^ +Every 'Target' of an SRV should have an appropriate A record in DNS, so that the server can resolve the name to an IP +address. In the example above, you would need to assure that wave.example.com had a valid record, and could be resolved +externally. + +Ports +^^^^^ +An SRV record defines which port the service is available on. For example the following service is accepting connections +via port 31423: +:: + + _xmpp-server._tcp.example.com. 86400 IN SRV 10 0 31423 wave.example.com. + +You can specify any valid port number for your server. This is especially useful as in the diagram below, where a wave +server is behind a NAT/Firewall. + +In this diagram, you would need to configure the incoming port 31423 (as per our example) on your firewall to pass +through to the correct server. The usefulness of this setup is that you would be able to run multiple Wave servers +behind a firewall, even for multiple domains, and simply assign each one a unique port: +:: + + _xmpp-server._tcp.example.com. 86400 IN SRV 10 0 5269 wave.example.com. + _xmpp-server._tcp.anotherexample.com. 86400 IN SRV 10 0 5270 wave.anotherexample.com. + _xmpp-server._tcp.fickleexample.com. 86400 IN SRV 10 0 5271 wave.fickleexample.com. + +Recommended DNS Configuration +----------------------------- +The following DNS records are recommended. If your Wave server provides hosting for the domain <yourdomain> then: + +1. Configure a SRV record for _xmpp-server._tcp.<yourdomain> that points to the port and domain name of your XMPP + server. +2. If your server supports XMPP disco, and the "google-wave" disco item jid is <yourdomain>, you don't need any other + records. +3. If your server supports XMPP disco, and the "google-wave" disco item jid is <some prefix>.<yourdomain>, you should + configure an SRV record for _xmpp-server._tcp.<some prefix>.<yourdomain> that points to the port and domain name of + your XMPP Wave component server. +4. If your server does not support XMPP discovery, you will need to configure a SRV record for + _xmpp-server._tcp.wave.<yourdomain>. +5. Using SRV records as described above is the preferred resolution mechanism. If for some reason this does not work + for you, DNS A records can be used in place of the SRV records. + +Example +------- +Let's presume the following setup, that you are running your XMPP server and Federation extension behind a NAT and are +trying to federate with acmewave.com: + +.. image:: ../Resources/networklayout.png + +We will also presume that the wave XMPP service is running at wave.example.com. + +First, acmewave.com needs to be able to look up your server via DNS, so you will need to configure A records for +example.com and wave.example.com that point to your server. How you set that up is particular to your ISP and domain +name provider so we can't give detailed instructions on how to set this up, but there is a command line program to use +to determine if you do have it set up correctly: dig. You can run dig and if each of the following return a good IP +address then you are in good shape (substitute in your domain name on the command line). +:: + + $ dig +short -t A example.com + 72.148.43.48 + $ dig +short -t A wave.example.com + 72.148.43.48 + +Note that you need both your domain name, and the wave sub-domain to resolve via DNS. + +Ports and SRV +------------- + +Now acmewave.com can find your server but it still might not be able to talk to your XMPP server. If you are behind a +NAT, as in this example, you need to open port 5269 on your server, and forward connections to your NAT/Router that come +in on port 5269 to your server. You may also need to open up port 5269 on your firewall if you have one on your server. + +We are almost done, now we just need to set up SRV records for our XMPP services. This is done via SRV records. To do +that you will need to set up two sub-domains, one a sub-domain of example.com and another of wave.example.com, and then +attach SRV records to them. The two subdomains are _xmpp-server._tcp.example.com and _xmpp-server._tcp.wave.example.com. +To each of them you need to attach an SRV record that looks like: +:: + + 10 0 5269 example.com. + +This is just the standard algorithm that XMPP uses to find another server, it prepends xmpp-server.tcp to the domain +name and then looks up the SRV record to find out the port and domain name of the server it needs to connect to. +Remember to set up SRV records for both _xmpp-server._tcp.example.com and _xmpp-server._tcp.wave.example.com. Also note +that the trailing "." isn't a typo, you will need that. To test that you have everything setup properly you can again +use dig: +:: + + $ dig +short -t SRV _xmpp-server._tcp.example.com + 10 0 5269 example.com. + $ dig +short -t SRV _xmpp-server._tcp.wave.example.com + 10 0 5269 example.com. + +Testing +------- +Once you have that all configured you can now test federation. Edit run-server.sh and set the ping server to +{{acmewave.com}: +:: + + ... + --xmpp_server_ping="acmewave.com" \ + ... + +Now when you start up the server you should see your server ping acmewave.com and then acmewave.com should send back a +packet: +:: + + $ ./run-server.sh + . + . + . + Aug 26, 2009 7:02:47 PM org.waveprotocol.wave.examples.fedone.federation.xmpp.WaveXmppComponent processPacket + INFO: received XMPP packet: + <message type="normal" id="4191-2" from="wave.acmewave.com" to="wave.example.com"> + <received xmlns="urn:xmpp:receipts"/> + </message> + Aug 26, 2009 7:02:47 PM org.waveprotocol.wave.examples.fedone.federation.xmpp.WaveXmppComponent processMessageReceipt + INFO: got ping response from acmewave.com + <message type="normal" id="4191-2" from="wave.acmewave.com" to="wave.example.com"> + <received xmlns="urn:xmpp:receipts"/> + </message> + +Chatting +-------- +From within the client create a new wave and add a participant from another federated server: + +If that user is available they can now chat with you. Server details and times that people are available are posted to +the wave-dev@incubator.apache.org mailing list. Post yours too and help test federation. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Installing/federation/certificates.rst ---------------------------------------------------------------------- diff --git a/source/manual/Installing/federation/certificates.rst b/source/manual/Installing/federation/certificates.rst new file mode 100644 index 0000000..8dfdfc0 --- /dev/null +++ b/source/manual/Installing/federation/certificates.rst @@ -0,0 +1,277 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _certificates: + +Certificates +============ + +Introduction +------------ + +.. todo:: do these test servers still work? is wave-protocol still the right place for this? + +The instructions below are for self-signed certificates, which the current test server, initech-corp.com, will accept, +which allows for easy testing of the federation protocol. The acmewave.com test server has been transitioned to only +accept CA-issued certificates. CA-issued certificates are better as they involve a trusted third-party, and it is +expected that in production a Wave server would only accept CA-issued certificates. Changes to the test servers that +affect which kind of certificate they accept will be announced on the wave-protocol mailing list. + +If you want to go through the steps to generate a CA-issued certificate the instructions are at the end of this page. A +server that is set up to accept self-signed certificates will also accept CA-issued certificates, so you will still be +able to interop with both test servers with a CA-issued certificate. + +Note that real certs will contain a critical extension that only Wave servers should accept, to prevent them being +re-used as SSL server certificates. + +Self-Signed Certificates +------------------------ +There is a script called make_cert.sh for generating certificates in the root directory of the repository. When you run +it, you'll see roughly this: +:: + + $ ./make_cert.sh test + 1) Generating key for test in 'test.key' ... + + Generating RSA private key, 2048 bit long modulus + ..............................+++ + ......................................................+++ + e is 65537 (0x10001) + + 2) Generating certificate request for test in 'test.crt' ... + + You are about to be asked to enter information that will be incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [AU]: + State or Province Name (full name) [Some-State]: + Locality Name (eg, city) []: + Organization Name (eg, company) [Internet Widgits Pty Ltd]: + Organizational Unit Name (eg, section) []: + Common Name (eg, YOUR name) []: + Email Address []: + +You can answer whatever you want to all questions except the Common Name question. There you should answer the DNS name +of your server. + +The result of this would be two files, test.crt and test.key. The certificate you can give to anyone, especially those +who want to check its a known good cert. The key is your private key and should not be revealed. + +.. note::The FedOne code does not support password protected private keys. This is not a concern if you used the script + supplied above as the generated private key will not be password protected. + +.. todo:: still fedone?) + +View the certificate +:: + + $ openssl x509 -text -in test.crt + Certificate: + Data: + Version: 3 (0x2) + Serial Number: + e1:e7:23:24:cc:5e:71:d1 + Signature Algorithm: sha1WithRSAEncryption + Issuer: C=AU, ST=Some-State, O=Internet Widgits Pty Ltd, CN=www.links.org + Validity + Not Before: Jul 17 20:59:30 2009 GMT + Not After : Jul 17 20:59:30 2010 GMT + Subject: C=AU, ST=Some-State, O=Internet Widgits Pty Ltd, CN=www.links.org + Subject Public Key Info: + Public Key Algorithm: rsaEncryption + RSA Public Key: (2048 bit) + Modulus (2048 bit): + 00:d9:0c:57:6b:fa:ad:b2:8f:b1:17:08:1f:d4:b1: + 10:5a:eb:7c:35:01:02:73:3f:67:68:5d:fd:3e:4c: + ec:29:fa:3c:76:09:88:f5:fd:e2:ec:ad:47:44:d9: + 6a:a9:4f:b6:2e:42:17:f3:11:b2:59:fd:2e:ab:69: + c6:95:a5:e2:2f:15:16:43:5f:1f:b5:c0:38:35:f0: + a3:db:30:19:6b:a9:b1:10:4f:e7:80:a2:a5:68:c5: + b5:3e:1c:81:ce:7c:98:b0:bb:8e:5b:d0:f3:21:25: + f7:b5:eb:d0:bf:72:f5:69:bc:24:ab:69:38:db:f5: + 85:c9:92:98:e7:e0:a6:30:57 + Exponent: 65537 (0x10001) + X509v3 extensions: + X509v3 Subject Key Identifier: + C1:B6:25:4F:F7:59:52:9C:8D:87:B9:7F:88:EC:2C:1D:3B:0F:DC:0F + X509v3 Authority Key Identifier: + keyid:C1:B6:25:4F:F7:59:52:9C:8D:87:B9:7F:88:EC:2C:1D:3B:0F:DC:0F + DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/CN=www.links.org + serial:E1:E7:23:24:CC:5E:71:D1 + + X509v3 Basic Constraints: + CA:TRUE + Signature Algorithm: sha1WithRSAEncryption + 6d:0c:b9:a1:1e:37:9f:53:d9:bf:a1:10:21:04:46:84:27:57: + cd:91:2a:3d:11:38:51:3e:80:ac:e0:10:d9:37:f3:27:00:20: + 04:88:2f:de:2a:54:6f:e2:f1:a5:1b:d7:54:04:4c:02:ef:6a: + 60:76:d6:68:6a:42:02:c8:ac:0f:df:16:fa:e8:b6:a6:19:8b: + 46:26:1f:bb:d6:69:6f:15:5a:43:89:ce:41:df:8b:58:74:9d: + 66:13:d9:e5:b6:9e:84:0e:fe:63:2a:d6:5c:6c:96:e7:ae:ae: + 6a:a2:a9:2e:81:98:87:2d:ce:3c:48:7c:d4:2b:71:98:97:1d: + 78:d0 + -----BEGIN CERTIFICATE----- + MIIC+zCCAmSgAwIBAgIJAOHnIyTMXnHRMA0GCSqGSIb3DQEBBQUAMF0xCzAJBgNV + BAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX + aWRnaXRzIFB0eSBMdGQxFjAUBgNVBAMTDXd3dy5saW5rcy5vcmcwHhcNMDkwNzE3 + MjA1OTMwWhcNMTAwNzE3MjA1OTMwWjBdMQswCQYDVQQGEwJBVTETMBEGA1UECBMK + U29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMRYw + FAYDVQQDEw13d3cubGlua3Mub3JnMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB + gQDZDFdr+q2yj7EXCB/UsRBa63w1AQJzP2doXf0+TOwp+jx2CYj1/eLsrUdE2Wqp + T7YuQhfzEbJZ/S6racaVpeIvFRZDXx+1wDg18KPbMBlrqbEQT+eAoqVoxbU+HIHO + fJiwu45b0PMhJfe169C/cvVpvCSraTjb9YXJkpjn4KYwVwIDAQABo4HCMIG/MB0G + A1UdDgQWBBTBtiVP91lSnI2HuX+I7CwdOw/cDzCBjwYDVR0jBIGHMIGEgBTBtiVP + 91lSnI2HuX+I7CwdOw/cD6FhpF8wXTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNv + bWUtU3RhdGUxITAfBgNVBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDEWMBQG + A1UEAxMNd3d3LmxpbmtzLm9yZ4IJAOHnIyTMXnHRMAwGA1UdEwQFMAMBAf8wDQYJ + KoZIhvcNAQEFBQADgYEAbQy5oR43n1PZv6EQIQRGhCdXzZEqPRE4UT6ArOAQ2Tfz + JwAgBIgv3ipUb+LxpRvXVARMAu9qYHbWaGpCAsisD98W+ui2phmLRiYfu9ZpbxVa + Q4nOQd+LWHSdZhPZ5baehA7+YyrWXGyW566uaqKpLoGYhy3OPEh81CtxmJcdeNA= + -----END CERTIFICATE----- + +Check certificate and key match +:: + + $ openssl x509 -modulus -in test.crt -noout + Modulus=AC12A9EDA81134852DE9887BD0B4B36940B48F2520BF6970DE8854FAF4A476EAF32711C36E65DAB96729FABDDCA4531ABC3AEAD1DD3B + C0E58429CE434B070617D9065A6B7B3EBC76DE7DFBD9150DF0D27D6F5E6D6F11C7D0A4CFDCB6763BC1C01208AF184A28BC2628F195BD75B96EB2 + C58F94D5EC74F7A301F2D8EB6936858B + $ openssl rsa -in test.key -modulus -noout + Modulus=AC12A9EDA81134852DE9887BD0B4B36940B48F2520BF6970DE8854FAF4A476EAF32711C36E65DAB96729FABDDCA4531ABC3AEAD1DD3B + C0E58429CE434B070617D9065A6B7B3EBC76DE7DFBD9150DF0D27D6F5E6D6F11C7D0A4CFDCB6763BC1C01208AF184A28BC2628F195BD75B96EB2 + C58F94D5EC74F7A301F2D8EB6936858B + +The two outputs should match. + +Now you are done and can add the key and cert to you Wave server and interop with other Wave servers that accept +self-signed certificates. If you want to generate a CA-issued Certificate follow the directions in the next section. + +Getting a CA-issued Certificate +------------------------------- +You will need access to the email account webmas...@yourdomain.com, postmas...@yourdomain.com, or +hostmas...@yourdomain.com. + +First generate an encrypted private key: +:: + + $ openssl genrsa -des3 -out example.com.encrypted.key 2048 + +You will be asked for passphrase, make sure it is at least 10 characters. + +Then generate a certificate request: +:: + + $ openssl req -new -key example.com.encrypted.key -out example.com.csr + +You will be asked for passphrase from above. After that you will be asked to fill in a bunch of details. + +.. note:: The Common Name should be in the form wave.example.com + +You can use this certificate request with your Certificate Authority of choice. Below are instructions on getting a free +Class 1 CA-issued certificate from StartSSL. Using StartSSL is not required, but is documented here because it is one of +the CAs that provide free CA certs. + +StartSSL instructions +--------------------- + +1. Go to https://www.startssl.com. +2. Sign in, or sign up. To sign up you will need to provide email that you can validate, then log out and log in again + - click in Authenticate - you will be asked for (email) certificate that was generated in the sign up process. +3. Go to Control Panel. +4. Click on the Validations Wizard. +5. Choose Domain Name Validation where you have to validate you domain, i.e. example com. +6. Go to Certificates Wizard. +7. Choose XMPP certificate. +8. In the private key generation step click on "skip". +9. In the next step paste the certificate request that was generated earlier (the contents of the example.com.csr). +10. Choose your domain, i.e. example.com. In the subdomain you need to enter "wave", i.e. http://wave.example.com. +11. Click on Continue until Finish. +12. After that you will have your signed certificate. Save it as example.com.crt. +13. Go to ToolBox, choose StartCom CA Certificates. Download your intermediate certificate sub.class1.server.ca.pem and + the Certification Authority certificate ca.pem. + +So by now you should have 5 files: + +* example.com.encrypted.key +* example.com.crt +* example.com.csr +* sub.class1.server.ca.pem +* ca.pem + +Make sure to backup the private key and signed certificate (example.com.encrypted.key example.com.crt) and put it +somewhere in a safe place. + +Now let's remove the passphrase from the private key with: +:: + + $ openssl rsa -in example.com.encrypted.key -out example.com.nonencrypted.key + +then convert the key to a different format with: +:: + + $ openssl pkcs8 -topk8 -nocrypt -in example.com.nonencrypted.key -out example.com.key + +Now we have the private key we can use with waveinabox server and a certificate signed by StartCom. + +You can test your certificate using the openssl command line tool. If you get a CA-issued cert for the domain +example.com then you can test the cert with: +:: + + $ openssl verify -CAfile sub.class1.server.ca.pem example.com.crt + example.com.crt: OK + +.. todo:: Make this refer to server.federation.config instead + +To enable the certs you will need to make some changes to run-config.sh. Enable certs, and add the intermediate cert to +the list of certificates: +:: + + # Set true to disable the verification of signed deltas + WAVESERVER_DISABLE_VERIFICATION=false + + # Set true to disable the verification of signers (certificates) + WAVESERVER_DISABLE_SIGNER_VERIFICATION=false + + CERTIFICATE_FILENAME_LIST=${WAVE_SERVER_DOMAIN_NAME}.crt,sub.class1.server.ca.pem + +Note: Some people have found that they need to include both the sub.class1.server.pem and the ca-bundle cert in the +chain as follows: +:: + + CERTIFICATE_FILENAME_LIST=$\{WAVE_SERVER_DOMAIN_NAME}.crt,sub.class1.server.ca.pem,ca.pem + +The order of the certificates listed in the CERTIFICATE_FILENAME_LIST is important, with your certificate going first, +and intermediate certs following. + +Check Certificates +------------------ + +.. todo:: change FedOne to WIAB? + +The check-certificates.sh script included in the FedOne? source will do all of the above checks for you. Make sure +run-config.sh is configured first then run check-certificates.sh. If the certificates are valid and configured correctly +you will see: + +:: + + SUCCESS: The certificates have been verified and are working correctly + +Otherwise and error message will be printed pointing to the cause of the error. http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Installing/federation/openfire.rst ---------------------------------------------------------------------- diff --git a/source/manual/Installing/federation/openfire.rst b/source/manual/Installing/federation/openfire.rst new file mode 100644 index 0000000..fccdce4 --- /dev/null +++ b/source/manual/Installing/federation/openfire.rst @@ -0,0 +1,126 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _Openfire-Installation: + +Openfire Installation +===================== + +.. todo:: check these instructions still work and change links to apache infra + +.. note:: THESE INSTRUCTIONS ARE UNTESTED AND VERY OUT-OF-DATE NOW. Please use Prosody instead. + +.. note:: :strong:`Be Careful` Openfire (3.6.4) has a bug in it's DNS code. + +Introduction +------------ +The open source Wave In a Box is delivered as a Java application that conforms to XEP-0114, the Jabber Component +Protocol. In the examples below we show how to install the Wave Federation Prototype Server as an extension to the +http://www.igniterealtime.org/projects/openfire/index.jsp XMPP server, but it should run against any XEP-0114 compliant +server. We also have instructions for using Prosody. + +To run the Prototype Server you will first need to install the Openfire server. The instructions for installing Openfire +are included below are for a Debian based Linux distribution and are there for your convenience, but any issues with +installing Openfire should be directed to the standard Openfire community support. + +Preliminaries +------------- +Openfire is written in Java so you will need to make sure Java is installed on your machine. While WIAB should run on +any platform with Java 6 the instructions below are only for Mac OSX and a Debian based Linux distribution. + +Mac OSX +^^^^^^^ +For Mac OSX you will need to download Java from `Apple <http://developer.apple.com/java/download/>`_. + +After installing Java you will need to set the following environment variables: + +:: + + $ export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home + $ export PATH=$JAVA_HOME/bin:$PATH + +Now visit the http://www.igniterealtime.org/downloads/index.jsp and download and install the Mac OSX version of +Openfire. + +Debian/Ubuntu +^^^^^^^^^^^^^ + +Install Java 6: +:: + + $ apt-get install sun-java6-jdk sun-java6-fonts + +Now download and install the Openfire server: +:: + + $ wget http://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_3.6.4_all.deb + $ sudo dpkg -i openfire_3.6.4_all.deb + $ sudo /etc/init.d/openfire restart + +Other Linux Distros +^^^^^^^^^^^^^^^^^^^ +Other Linux distributions are not directly supported, but installation should work mostly in the same way as for +Debian/Ubuntu. However, there have been many reported configuration issues that we are tracking. + +Configure Openfire (all platforms) +---------------------------------- +After installing Openfire visit http://localhost:9090 with your browser. Substitute the domain name of the server you +installed Openfire on for localhost if you didn't install it on your local machine. You will be guided through the setup +process by a wizard. For the simplest installation select the defaults. + + +.. image:: /Resources/openfire01-server-setting.jpg + +.. image:: /Resources/openfire02-database-settings.jpg + +.. image:: /Resources/openfire03-profile-settings.jpg + +.. image:: /Resources/openfire04-administer-account.jpg + + +Configure Openfire for the Wave extension +----------------------------------------- + +Restart the server after you have finished the configuration. On Debian/Ubuntu you would restart it by: +:: + + $ sudo /etc/init.d/openfire restart + +After the server has restarted login as admin and go to Server -> Server Settings -> External Components. +:strong:`Login using the name 'admin' and not the email address you gave during setup.` + +Enable external components on port 5275 and a default shared secret of your own choosing. Press save. Then add wave as +a whitelisted component, by choosing a subdomain of wave and choose a shared secret for the wave extension. The shared +secret and port number are arguments that will be passed to the wave extension. + +.. image:: /Resources/openfire05-external-components-02.png + +Now go to Server -> Server Settings -> Security Settings. For "Server Connection Security" select "Custom" and enable +"Server Dialback". Also check the "Accept self-signed certificates" check box. + +.. image:: /Resources/openfire06-security-settings-tls-custom.jpg + +Security +-------- +The following changes are not required for the wave extension to work, but are good practices if you are running a +public facing XMPP server. + +* Go to Server -> Server Settings -> Registration and Login. Disable +* "Inband Account Registration". Disable "Change Password". Disable "Anonymous Login" +* Enable server-server compression in "Compression Settings" +* Disable file proxy transfer in "File Transfer Settings" +* Now continue following the instructions for installing the server. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Installing/federation/prosody.rst ---------------------------------------------------------------------- diff --git a/source/manual/Installing/federation/prosody.rst b/source/manual/Installing/federation/prosody.rst new file mode 100644 index 0000000..b82da00 --- /dev/null +++ b/source/manual/Installing/federation/prosody.rst @@ -0,0 +1,51 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _Prosody-Installation: + +Prosody Installation +==================== + +Introduction +------------ + +Prosody is a lightweight XMPP server, written in lua. It's available from http://prosody.im. + +Details +------- + +Prosody is included in most linux distributions. For debian-based distros, run: +:: + + $ sudo aptitude install prosody + +To configure it, you may use the Prosody configuration tool provided with WaveInABox: +:: + + $ ant -f server-config.xml server-federation-config prosody-config -Dxmpp_server_secret=secret_password + -Dxmpp_server_ping=example.com -Dxmpp_server_ip=localhost + +.. warning:: You may want to provide different -D options to suit your specific setup. + +That will generate a prosody configuration file named something like: example.com.cfg.lua. Copy it wherever Prosody can +find it usually /etc/prosody/conf.d and restart the Prosody server: +:: + + $ sudo cp example.com.fg.lua /etc/prosody/conf.d/ + $ sudo service prosody restart + +You can now continue with the instructions for installing and running the server. http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Installing/index.rst ---------------------------------------------------------------------- diff --git a/source/manual/Installing/index.rst b/source/manual/Installing/index.rst new file mode 100644 index 0000000..7f3ae35 --- /dev/null +++ b/source/manual/Installing/index.rst @@ -0,0 +1,182 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +Install Apache Wave +=================== + +Wave in a Box is delivered as a Java application. Installation comprises installing the server code and (optionally) +configuring federation with XMPP. + +.. toctree:: + + build + logging + run-export + +Server installation +------------------- + +Getting Java +^^^^^^^^^^^^ + +Ensure you have Java 6 installed before attempting to install Wave in a Box + +Building the code +^^^^^^^^^^^^^^^^^ +WIAB is currently distributed on in source code form. Obtain the source for the project: + +:: + + $ svn co https://svn.apache.org/repos/asf/incubator/wave/trunk + $ cd wave-protocol + $ ant + +If the build is successful you should see: + +:: + + BUILD SUCCESSFUL + Total time: NN minutes MM seconds + +Running the server +------------------ +Copy the run-nofed-config.sh.example to run-config.sh, then edit run-config.sh to configure it to your setup. +The example file explains the configuration options. You can ignore all those concerning federation and certificates +for now. + +Run the server with + +:: + + $ ./run-server.sh + +Running the client +------------------ + +The configuration in run-config.sh is used by the client too, so nothing extra should be necessary to run the console +client. + +:: + + $ ./run-client-console.sh <username> + +Running the webclient +--------------------- + +Once you have followed the instructions on this page about how to get the server running you should be able to reach the +web client by going to: http://localhost:9898 when running locally or by contacting port 9898 on the machine running the +server. Note that if you have changed the websocket server port in your settings you should use that port instead. + +Mongo DB Installation (optional) +-------------------------------- + +It is possible to use Mongo DB to store Waves, instead of a filesystem-based system. + +Download and extract the MongoDB `distribution <http://www.mongodb.org/>`_ for your system. + +By default MongoDB will store data in /data/db/ which means you need to create and set the properties for that folder. +You can use any other location if you'd like just remember to give the server the --dbpath option. :: + + sudo mkdir -p /data/db/ + sudo chown `id -u` /data/db/ + +Run the server in a terminal window or use whatever means necessary to start the server process: +./<mongodb_location>/bin/mongod. + +You can test whether it works by running ./<mongodb_location>/bin/mongo. + +* Default connection port: 27017 +* Default webadmin port: 28017 + +For more information read the `manual <http://www.mongodb.org/display/DOCS/Manual>`_. + +Running the Server as a Windows Service (optional) +-------------------------------------------------- + +It is possible to run Wave in a Box as a Windows Service, so it starts and stops automatically. +See :ref:`Run-Wave-as-a-Windows-Service` + +.. toctree:: + :hidden: + + Wave-As-Service + + +Federation configuration (optional) +----------------------------------- + +The server conforms to XEP-0114, the Jabber Component Protocol. The first step in +running the Federation Prototype Server is to install an XMPP server that is +XEP-0114 compatible. + +Follow the instructions below for your server of choice: + +* :ref:`Openfire-Installation` +* :ref:`Prosody-Installation` + +There are many XEP-0114 compatible XMPP servers and we don't have instructions for +all of them. Please contribute instructions if you have them for a server we don't +have listed. + +See :ref:`federation-background` the explanation of DNS, SRV records, and ports. + +.. toctree:: + + federation + +Configure Your XMPP Server +-------------------------- + +WIAB runs as a separate process that communicates with the XMPP server. For that communication to take place the XMPP +server has to be notified of which port the WIAB extension will be using and also will need a shared secret for security +purposes. In your XMPP server enable external components on port 5275 and a default shared secret of your own choosing. +The extesion should be named wave.<domain-name> where <domain-name> is the domain name of your XMPP server. You will +also need to enable Server Dialback for server to server communication. Each type of XMPP server is configured +differently, so look to their specific installation instructions for details. + +Security +-------- + +The following changes are not required for the wave extension to work, but are good practices if you are running a +public facing XMPP server. + +* Disable inband account registration. +* Disable anonymous login +* Enable server-server compression +* Disable file proxy transfer + +Wave Extension Installation +--------------------------- +To run the extension you will need some of the parameters you used to set up the XMPP server. They are the extension +port, the extension shared secret, the server name, and finally the component name which is "wave". + +The wave server requires a set of certificates used for signing deltas. Please see the [certificates|:ref:`Certificates` +page for help generating these. + +Copy the *run-config.sh.example* to *run-config.sh*, then edit *run-config.sh* to configure it to your setup. + +When you're done editing the script, run check-certificates.sh to verify that the certificates are configured correctly: + +:: + + $ ./check-certificates.sh + +If that runs successfully then run the server: + +:: + + $ ./run-server.sh http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Installing/logging.rst ---------------------------------------------------------------------- diff --git a/source/manual/Installing/logging.rst b/source/manual/Installing/logging.rst new file mode 100644 index 0000000..3b9d913 --- /dev/null +++ b/source/manual/Installing/logging.rst @@ -0,0 +1,78 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +Logging +======= + +Enable ALL logging +------------------ + +.. todo:: document the logging levels available. + +By requesting Java uses a logging configuration file, we can easily configure the logging level to more than the default. (Default depends on whether WIAB was compiled in demo mode or not). + +In run-server.sh, change the exec java to something like: + +:: + + exec java $DEBUG_FLAGS \ + -Djava.util.logging.config.file=wiab-logging \ + -Djava.security.auth.login.config=jaas.config \ + -Dwave.server.config=server.config \ + -jar dist/$NAME-server-$WAVEINABOX_VERSION.jar + +The -Djava.util.logging.config.file=/home/wave/wiab-logging is the only new line. + +I have deliberately, turned down the logging from jetty to ERROR only, so that the log fills up with Wave only messages. + +Then create the logging configuration file at the path specified: + +.. todo:: make this only change logging for Wave. + +:: + + handlers=java.util.logging.FileHandler, java.util.logging.ConsoleHandler + .level = ALL + java.util.logging.ConsoleHandler.level=ALL + java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter + org.waveprotocol.level=ALL + +Then upon rebooting your server, the amount of logging information should be dramatically increased. I suggest pipeing it to a file from here. + +Uploading logs +^^^^^^^^^^^^^^ + +Since the logs consist of huge quantities of almost the same message, dictionary compression schemes work incredibly well on it. So please compress it with something before uploading. + +(Anecdotally, a 224M log file compresses to 1.9M using xz)! + +Jetty Logging +------------- +Since Jetty 9, the logging implementation in Jetty has changed to have a more extensible backend. + +The settings have become completely independent of the rest of the logging settings. To set them, change the run-server script to pass the following flags: +:: + + -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog \ + -Dorg.eclipse.jetty.level=INFO \ + +For more information, refer to the `Jetty9 documentation <https://cwiki.apache.org/confluence/h>`_. + +Disable Logging +--------------- + +.. todo:: write about it here, it simply consists of removing the lines from run-server.sh http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Installing/run-export.rst ---------------------------------------------------------------------- diff --git a/source/manual/Installing/run-export.rst b/source/manual/Installing/run-export.rst new file mode 100644 index 0000000..ad7b025 --- /dev/null +++ b/source/manual/Installing/run-export.rst @@ -0,0 +1,40 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +run-export.sh +============= + +This file allows users and administrators to export and backup waves. + +Parameters +---------- + +.. todo:: .. + +General Usage Instructions +-------------------------- +The script takes a number of options. It also wants at least two arguments: The url of the server (including http:// or +https://) and the directory to store the exported waves to. All options must follow after these arguments. + +If you just run the script with these two arguments, it will show you a URL to paste into the browser. You will then be +asked to allow or deny permission. If you allow it, youâll see a long string. Paste this into the command line to let +the script proceed. Now it will export all your waves, including their attachments. + +You can limit the number of waves to be exported. One way of doing so is with the search parameter. It will take the +same searches that work in the webgui too. (for example in:inbox). + +Another way to filter the output would certainly be to use the include and exclude options. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Resources/fedone.png ---------------------------------------------------------------------- diff --git a/source/manual/Resources/fedone.png b/source/manual/Resources/fedone.png new file mode 100644 index 0000000..aff1045 Binary files /dev/null and b/source/manual/Resources/fedone.png differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Resources/networklayout.png ---------------------------------------------------------------------- diff --git a/source/manual/Resources/networklayout.png b/source/manual/Resources/networklayout.png new file mode 100644 index 0000000..105a7cd Binary files /dev/null and b/source/manual/Resources/networklayout.png differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Resources/openfire01-server-setting.jpg ---------------------------------------------------------------------- diff --git a/source/manual/Resources/openfire01-server-setting.jpg b/source/manual/Resources/openfire01-server-setting.jpg new file mode 100644 index 0000000..348fe41 Binary files /dev/null and b/source/manual/Resources/openfire01-server-setting.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Resources/openfire02-database-settings.jpg ---------------------------------------------------------------------- diff --git a/source/manual/Resources/openfire02-database-settings.jpg b/source/manual/Resources/openfire02-database-settings.jpg new file mode 100644 index 0000000..20591bd Binary files /dev/null and b/source/manual/Resources/openfire02-database-settings.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Resources/openfire03-profile-settings.jpg ---------------------------------------------------------------------- diff --git a/source/manual/Resources/openfire03-profile-settings.jpg b/source/manual/Resources/openfire03-profile-settings.jpg new file mode 100644 index 0000000..119c6a4 Binary files /dev/null and b/source/manual/Resources/openfire03-profile-settings.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Resources/openfire04-administer-account.jpg ---------------------------------------------------------------------- diff --git a/source/manual/Resources/openfire04-administer-account.jpg b/source/manual/Resources/openfire04-administer-account.jpg new file mode 100644 index 0000000..a152f65 Binary files /dev/null and b/source/manual/Resources/openfire04-administer-account.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Resources/openfire05-external-components-02.png ---------------------------------------------------------------------- diff --git a/source/manual/Resources/openfire05-external-components-02.png b/source/manual/Resources/openfire05-external-components-02.png new file mode 100644 index 0000000..7a04f7b Binary files /dev/null and b/source/manual/Resources/openfire05-external-components-02.png differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/Resources/openfire06-security-settings-tls-custom.jpg ---------------------------------------------------------------------- diff --git a/source/manual/Resources/openfire06-security-settings-tls-custom.jpg b/source/manual/Resources/openfire06-security-settings-tls-custom.jpg new file mode 100644 index 0000000..d03bbad Binary files /dev/null and b/source/manual/Resources/openfire06-security-settings-tls-custom.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/97eda9a7/source/manual/index.rst ---------------------------------------------------------------------- diff --git a/source/manual/index.rst b/source/manual/index.rst index edb3b5f..ff1714d 100644 --- a/source/manual/index.rst +++ b/source/manual/index.rst @@ -22,4 +22,5 @@ Apache Wave (incubating)'s User Manual .. toctree:: :maxdepth: 2 - faq \ No newline at end of file + faq + Installing/index \ No newline at end of file
