.. _Configuring-label:


================================================================================
Configuring pysiriproxy
================================================================================

The first time pysiriproxy is executed on your system (assuming it has been
:ref:`installed <Installing-label>`), the following directory will be created
in your home directory. The typical location of this directory is:

    **~/.pysiriproxy**

.. note:: All instructions will refer to this directory location even though
   it may be located in different place on your system.

The default contents of the configuration directory will look like:

    *./pysiriproxy.cfg*
    
    **./certificates**
        *ca.pem*
        *cert.log*
        *server.passless.crt*
        *server.passless.key*

    **./plugins:**
        *__init__.py*
        *buttonTest.py*
        *locationTest.py*
        *resetPlugin.py*
        *testPlugin.py*

    **./scripts:**
        *gen_certs.sh*
        *openssl.cnf*
        *setDnsmasq.sh*

The contents are described below:

--------------------------------------------------------------------------------
The pysiriproxy configuration file
--------------------------------------------------------------------------------

The pysiriproxy configuration file is named *pysiriproxy.cfg* and it has
the standard :mod:`ConfigParser` format. This configuration contains the
following configuration sections and settings which can alter how pysiriproxy
will run:

    * The **General** section:
        - **PluginsDir** -- This setting contains the path where pysiriproxy
          plugins are located.
    * The **Server** section:
        - **Host** -- This setting contains the hostname for Apple's web server.
        - **Port** -- This setting contains the port number for Apple's web server.
    * The **iPhone** section:
        - **Port** -- This setting contains the port number which the iPhone
          will connect to.
        - **KeyFile** -- This setting contains the path to the *key* file which
          was generated by the
          :ref:`certificate generation process <gencerts-label>`.
        - **CertFile** -- This setting contains the path to the *crt* file
          which was generated by the
          :ref:`certificate generation process <gencerts-label>`.
    * The **Logging** section:
        - **LogLevel** -- This setting contains the log level used by
          pysiriproxy. This can have the following values: DEBUG, INFO, WARN, or
          ERROR. This setting controls the amount of output which is logged by
          the system.
        - **DebugLevel** -- This setting contains the debug level to use for
          the system, where a value of 0 indicates a higher importance.
    * The **Responses** section:
        - **Error** -- This setting contains a string which Siri will say in
          the event that an Exception is encountered during the process of
          processing an iPhone request.

--------------------------------------------------------------------------------
The plugins directory
--------------------------------------------------------------------------------

The plugins directory is the location where pysiriproxy expects all plugins to
be stored. At runtime, pysiriproxy will load all of the Python files located
in this directory into memory and the loaded plugins will then be used to
intercept the communications between the iPhone and Apple's web server.

After the initial installation of pysiriproxy, the plugins directory will
contain the following files:

    * **__init__.py** -- This file is needed to allow pysiriproxy to import
      the plugin scripts at runtime.
    * **buttonTest.py** -- This is an example of a plugin that creates
      buttons which the user is able to interact with to perform different
      tasks.
    * **locationTest.py** -- This is an example of a plugin that allows the
      user to test creating map locations, and getting directions between
      two map locations.
    * **resetPlugin.py** -- This is a plugin which performs the task of
      resetting the request context in the event that an object is received
      that cancels the current request.
    * **testPlugin.py** -- This is an example of plugin that demonstrates how
      to command Siri to interact with the user in various ways, such as:
      asking the user a question, or displaying text to the user.

.. note:: Developers should never need to modify the  __init__.py, or 
   resetPlugin.py files.

Developers can create new plugins by adding a new Python file to the plugins
directory. This file should contain a subclass of the
:class:`~pysiriproxy.plugins.plugin.BasePlugin` class, and should have the
*.py* extension. These new plugins will be loaded by pysiriproxy at the
start of the system.

Please see the section on :ref:`Writing plugins <WritingPlugins-label>` for
instructions on how to create a custom plugin.


--------------------------------------------------------------------------------
The scripts directory
--------------------------------------------------------------------------------

The scripts directory contains various scripts needed by pysiriproxy. The
scripts are as follows:

    * **gen_certs.sh** -- This script generates the certificate files needed
      to create the correct permissions to connect to Apple's web server.
    * **openssl.cnf** -- This is a configuration file used by the gen_certs
      script to generate the certificate files.
    * **setDnsmasq.sh** -- This script takes an IP address as its only
      argument and modifies the */etc/dnsmasq.conf* to use the given IP
      address. It also handles restarting dnsmasq to use the new settings.


--------------------------------------------------------------------------------
The certificates directory
--------------------------------------------------------------------------------

The certificates directory contains the certificate files generated by the
gen_certs script. Once the certificates have been generated this directory
will contain the following files:

    * **ca.pem** -- The security certificate which should be sent to the iPhone
      which will use pysiriproxy.
    * **cert.log** -- The log file created by the gen_certs script.
    * **server.passless.crt** -- The certificate file generated by the gen_certs
      script.
    * **server.passless.key** -- The key file generated by the gen_certs script.


.. _gencerts-label:

----------------------------------------
Generating certificates for pysiriproxy
----------------------------------------

.. highlight:: console
   :linenothreshold: 1000


The pysiriproxy certificates can be generated by running the following
commands (assuming the :ref:`installation process <Installing-label>` was
followed exactly)::

    $ cd /opt/pysiriproxy
    $ ./siriproxy --gencerts


.. _installing-certificates-label:

------------------------------------------
Installing the certificate on your iPhone
------------------------------------------

In order for your iPhone to have the correct permissions to interact with
pysiriproxy, you must first generate the certificate files (see the section
on :ref:`generating certificates for pysiriproxy <gencerts-label>`), and then
you must install the certificate onto your iPhone.

In order to install the certificate on your iPhone you must copy the
*~/pysiriproxy/certificates/ca.pem* file onto your iPhone. The easiest method
for doing this is through e-mail. 

On your iPhone, you should be able to open the e-mail attachment and it should
give you the option to open the file in Safari. Once opened, you will have the
option to install the certificate onto your phone. Select *yes* and continue
through the remaining prompts.

The certificate is now installed onto your iPhone. You can edit this at any
time by navigating through the following menus:

Settings > General > Profiles > SiriProxyCA

This will give you the ability to view settings about the certificate, or
to remove the certificate from your phone.

.. _changingDnsmasqIp-label:

----------------------------------------
Changing your dnsmasq IP address
----------------------------------------

The next step in the configuration process is to set up your computer to
properly intercept requests for Apple's web server. This is done through
use of the dnsmasq tool (see the section on
:ref:`installing dnsmasq <dnsmasq-label>`). Dnsmasq needs to be configured
with the IP address of the machine on which it is running in order to
properly function. The following steps will help you easily configure
dnsmasq to use the IP address of your choosing:

Once the pysiriproxy configuration directory has been created, there will be
a script called **~/.pysiriproxy/scripts/setDnsmasq.sh** which can be used
to quickly change the IP address used by dnsmasq.

Here is an example of how to use this script to set the dnsmasq IP address to
use 192.168.0.5::

    $ sh ~/.pysiriproxy/scripts/setDnsmasq.sh 192.168.0.5

This script should be run with the IP address of your machine which is connected
to the same network as the iPhone. You will not be able to successfully use
pysiriproxy if both the machine running dnsmasq and the iPhone are not connected
to the same network.


.. _iphoneWireless-label:

----------------------------------------
Configure the iPhone wireless setttings
----------------------------------------

The final step in the configuration process is to set up the wireless settings for
the iPhone so that its requests are processed by the machine running dnsmasq. This
is done by modifying the DNS option of the wireless network. The following will
describe how this is done:

On the iPhone, navigate through the following menus:

Settings > WiFi

On this menu you should first connect to the desired wireless network, and then
once connected click on the blue arrow to modify the settings for that wireless
network.

This will bring you to the settings menu for your wireless network. Scroll down
and select the text in the **DNS** option. This will allow you to enter the IP
address for the machine running dnsmasq. This should be the **same** IP address
as was used when :ref:`configuring dnsmasq <changingDnsmasqIp-label>`. This
will force all DNS requests to be processed by the machine running dnsmasq,
which allows pysiriproxy to intercept the commands being sent to Apple's server.

.. note:: If you find that you wish to reset the DNS settings for this wireless
   network you can do so by deleting the entire IP address from the DNS option.
   Once you do this, and leave the menu you will find that the DNS option will
   be reset to its original value.


.. highlight:: python
   :linenothreshold: 1000


--------------------------------
Configure pysiriproxy for iOS 6
--------------------------------

With the release of iOS 6 Apple has updated Siri to use different servers
than it was using in the previous version of iOS. As of release 0.0.6,
the pysiriproxy server has been updated to accept requests from iPhones
running either iOS 5 or iOS 6 with only a single configuration change.

This is accomplished by generating a generic SSL certificate for the
iPhone which supports the ``*.apple.com`` server. This should allow
the same certificate to support future changes to the Apple server.

The *setDnsmasq.sh* script properly configures dnsmasq to route requests
for both the Guzzoni and Kryten servers to the local machine.

The pysiriproxy server is now setup, by default, to route queries to
the iOS 6 server at ``kryten.apple.com`` rather than the iOS 5 server
at ``guzzoni.apple.com``. If you wish to change which server is being
used modify the **Hosts** property under the **Server** section to
be the desired server address.

The **only** configuration change needed to change whether pysiriproxy
supports iOS 5 or iOS 6 phones is to change the configuration file
*~/.pysiriproxy/pysiriproxy.cfg*. The **Hosts** setting under the
**Server** section needs to be updated according to which version of
iOS you would like the server to support.

For **iOS 5** the file should read::

    Host = "guzzoni.apple.com"

And for **iOS 6** the file should read::

    Host = "kryten.apple.com"

A special thanks to Aaron (meluvalli) for his help with thoroughly
investigating and testing support for iOS 6.
