[tor-commits] [stem/master] Tutorial example of resuming an ephemeral hidden service

[atagar at torproject.org]

commit 3818c9a75221014caa1e84696164cdbe18b7cd96
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun May 8 11:21:52 2016 -0700

    Tutorial example of resuming an ephemeral hidden service
    
    On irc umoukun requested an example of how to reuse a *.onion address. Great
    idea!
---
 .../example/resuming_ephemeral_hidden_service.py   | 23 ++++++++++++++++++++++
 docs/change_log.rst                                |  1 +
 docs/download.rst                                  |  2 +-
 docs/tutorials/over_the_river.rst                  | 11 +++++++----
 4 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/docs/_static/example/resuming_ephemeral_hidden_service.py b/docs/_static/example/resuming_ephemeral_hidden_service.py
new file mode 100644
index 0000000..d2073f0
--- /dev/null
+++ b/docs/_static/example/resuming_ephemeral_hidden_service.py
@@ -0,0 +1,23 @@
+import os
+from stem.control import Controller
+
+key_path = os.path.expanduser('~/my_service_key')
+
+with Controller.from_port() as controller:
+  controller.authenticate()
+
+  if not os.path.exists(key_path):
+    service = controller.create_ephemeral_hidden_service({80: 5000}, await_publication = True)
+    print("Started a new hidden service with the address of %s.onion" % service.service_id)
+
+    with open(key_path, 'w') as key_file:
+      key_file.write('%s:%s' % (service.private_key_type, service.private_key))
+  else:
+    with open(key_path) as key_file:
+      key_type, key_content = key_file.read().split(':', 1)
+
+    service = controller.create_ephemeral_hidden_service({80: 5000}, key_type = key_type, key_content = key_content, await_publication = True)
+    print("Resumed %s.onion" % service.service_id)
+
+  raw_input('press any key to shut the service down...')
+  controller.remove_ephemeral_hidden_service(service.service_id)
diff --git a/docs/change_log.rst b/docs/change_log.rst
index 13824b2..b443c69 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -97,6 +97,7 @@ The following are only available within Stem's `git repository
 
   * `Comparison of our descriptor parsing libraries <tutorials/mirror_mirror_on_the_wall.html#are-there-any-other-parsing-libraries>`_
   * Example for `custom path selection for circuits <tutorials/to_russia_with_love.html#custom-path-selection>`_ (:trac:`8728`)
+  * Example for `persisting ephemeral hidden service keys <<tutorials/over_the_river.html#ephemeral-hidden-services>`_
 
 .. _version_1.4:
 
diff --git a/docs/download.rst b/docs/download.rst
index 64a3ca7..dfa234d 100644
--- a/docs/download.rst
+++ b/docs/download.rst
@@ -127,7 +127,7 @@ Download
           :target: https://apps.fedoraproject.org/packages/python-stem
 
        Packages maintained by Juan for Fedora. These include **python-stem**
-       (Stem for Python 2.x), **python3-stem** (Stem for Python 3.x), and
+       (for Python 2.x), **python3-stem** (for Python 3.x), and
        **python-stem-doc** (this website).
 
        ::
diff --git a/docs/tutorials/over_the_river.rst b/docs/tutorials/over_the_river.rst
index 67ff2e1..3f8ae0c 100644
--- a/docs/tutorials/over_the_river.rst
+++ b/docs/tutorials/over_the_river.rst
@@ -86,10 +86,6 @@ This has been a limitation of hidden services for years. However, as of version
 0.2.7.1 Tor offers another style for making services called **ephemeral hidden
 services**.
 
-Ephemeral hidden services do not touch disk, and as such are easier to work
-with but require you to persist your service's private key yourself if you want
-to reuse a '.onion' address.
-
 Ephemeral services can only be created through the controller, and only exist
 as long as your controller is attached unless you provide the **detached**
 flag. Controllers can only see their own ephemeral services, and ephemeral
@@ -107,6 +103,13 @@ For example, with a ephemeral service our earlier example becomes as simple as..
 .. literalinclude:: /_static/example/ephemeral_hidden_services.py
    :language: python
 
+Ephemeral hidden services do not touch disk, and as such are easier to work
+with but require you to persist your service's private key yourself if you want
+to reuse a '.onion' address...
+
+.. literalinclude:: /_static/example/resuming_ephemeral_hidden_service.py
+   :language: python
+
 .. _hidden-service-descriptors:
 
 Hidden service descriptors