incubator-wave-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a.@apache.org
Subject [4/4] incubator-wave-docs git commit: Add Install from confluence to the repository & also contains the FAQ'S
Date Sat, 22 Aug 2015 19:49:54 GMT
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 <ehugh1@gmail.com>
Authored: Thu Jul 9 19:11:45 2015 +1000
Committer: Evan Hughes <ehugh1@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. "bob@other.com") is
+updated (I.e. any operation is applied, including AddParticipant?("bob@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 webmaster@yourdomain.com, postmaster@yourdomain.com, or
+hostmaster@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


Mime
View raw message