@@ -1,3 +1,141 @@
1+-- | This module provides the low-level API to running Cloud Haskell on
2+-- Microsoft Azure virtual machines (<http://www.windowsazure.com>). Virtual
3+-- machines within an Azure cloud service can talk to each other directly using
4+-- standard Cloud Haskell primitives (using TCP/IP under the hood); to talk to
5+-- the remote machines from your local machine you can use the primitives
6+-- provided in this module (which use ssh under the hood). It looks something
11+-- > ( ) `) Azure cloud service
19+-- > | | Local machine
22+-- In this module we concentrate on the link between the local machine to the
23+-- remote machines. "Control.Distributed.Process.Backend.Azure.Process" provides
24+-- a higher-level interface that can be used in code that runs on the remote
27+-- /NOTE/: It is unfortunate that the local machine cannot talk to the remote
28+-- machine using the standard Cloud Haskell primitives. In an ideal world, we
29+-- could just start a Cloud Haskell node on the local machine, too.
30+-- Unfortunately, Cloud Haskell does not yet support using multiple network
31+-- transports (TCP/IP vs SSH). This is a temporary workaround.
35+-- In this section we describe how to set up an Azure Cloud Service for use
36+-- with Cloud Haskell, starting from a brand new Azure account. It is not
37+-- intended as an Azure tutorial, but as a guide to making the right choices to
38+-- get Cloud Haskell up and running as quickly as possible.
40+-- An Azure /Cloud Service/ is a set of virtual machines that can talk to each
41+-- other directly over TCP/IP (they are part of the same private network). You
42+-- don't create the cloud service directly; instead, after you have set up your
43+-- first virtual machine as a /stand alone/ virtual machine, you can /connect/
44+-- subsequent virtual machines to the first virtual machine, thereby implicitly
45+-- setting up a Cloud Service.
47+-- We have only tested Cloud Haskell with Linux based virtual machines;
48+-- Windows based virtual machines /might/ work, but you'll be entering
49+-- unchartered territory. Cloud Haskell assumes that all nodes run the same
50+-- binary code; hence, you must use the same OS on all virtual machines,
51+-- /as well as on your local machine/. We use Ubuntu Server 12.04 LTS for our
52+-- tests (running on VirtualBox on our local machine).
54+-- When you set up your virtual machine, you can pick an arbitrary name; these
55+-- names are for your own use only and do not need to be globally unique. Set a
56+-- username and password; you should use the same username on all virtual
57+-- machines. You should also upload
58+-- an SSH key for authentication (see
59+-- /Converting OpenSSH keys for use on Windows Azure Linux VM's/,
60+-- <http://utlemming.azurewebsites.net/?p=91>, for
61+-- information on how to convert a standard Linux @id_rsa.pub@ public key to
62+-- X509 format suitable for Azure). For the first VM you create select
63+-- /Standalone Virtual Machine/, and pick an appropriate DNS name. The DNS name
64+-- /does/ have to be globally unique, and will also be the name of the Cloud
65+-- Service. For subsequent virtual machines, select
66+-- /Connect to Existing Virtual Machine/ instead and then select the first VM
69+-- In these notes, we assume three virtual machines called @CHDemo1@,
70+-- @CHDemo2@, and @CHDemo3@, all part of the @CloudHaskellDemo@ cloud service.
72+-- [Obtaining a Management Certificate]
74+-- Azure authentication is by means of an X509 certificate and corresponding
75+-- private key. /Create management certificates for Linux in Windows Azure/,
76+-- <https://www.windowsazure.com/en-us/manage/linux/common-tasks/manage-certificates/>,
77+-- describes how you can create a management certificate for Azure, download it
78+-- as a @.publishsettings@ file, and extract an @.pfx@ file from it. You cannot
79+-- use this @.pfx@ directly; instead, you will need to extract an X509
80+-- certificate from it and a private key in suitable format. You can use the
81+-- @openssl@ command line tool for both tasks; assuming that you stored the
82+-- @.pfx@ file as @credentials.pfx@, to extract the X509 certificate:
84+-- > openssl pkcs12 -in credentials.pfx -nokeys -out credentials.x509
86+-- And to extract the private key:
88+-- > openssl pkcs12 -in credentials.pfx -nocerts -nodes | openssl rsa -out credentials.private
90+-- (@openssl pkcs12@ outputs the private key in PKCS#8 format (BEGIN PRIVATE
91+-- KEY), but we need it in PKCS#1 format (BEGIN RSA PRIVATE KEY).
93+-- [Testing the Setup]
95+-- Build and install the @distributed-process-azure@ package, making sure to
96+-- pass the @build-demos@ flag to Cabal.
98+-- > cabal-dev install distributed-process-azure -f build-demos
100+-- We can use any of the demos to test our setup; we will use the @ping@ demo:
102+-- > cloud-haskell-azure-ping list \
103+-- > --subscription-id <<your subscription ID>> \
104+-- > --certificate /path/to/credentials.x509 \
105+-- > --private /path/to/credentials.private
107+-- (you can find your subscription ID in the @.publishsettings@ file from the previous step).
108+-- If everything went well, this will output something like
110+-- > Cloud Service "CloudHaskellDemo"
111+-- > VIRTUAL MACHINES
112+-- > Virtual Machine "CHDemo3"
113+-- > IP 10.119.182.127
115+-- > Input endpoint "SSH"
117+-- > VIP 168.63.31.38
118+-- > Virtual Machine "CHDemo2"
119+-- > IP 10.59.238.125
121+-- > Input endpoint "SSH"
123+-- > VIP 168.63.31.38
124+-- > Virtual Machine "CHDemo1"
125+-- > IP 10.59.224.122
127+-- > Input endpoint "SSH"
129+-- > VIP 168.63.31.38
131+-- The IP addresses listed are /internal/ IP addresses; they can be used by the
132+-- virtual machines to talk to each other, but not by the outside world to talk
133+-- to the virtual machines. To do that, you will need to use the VIP (Virtual
134+-- IP) address instead, which you will notice is the same for all virtual
135+-- machines that are part of the cloud service. The corresponding DNS name
136+-- (here @CloudHaskellDemo.cloudapp.net@) will also resolve to this (V)IP
137+-- address. To login to individual machines (through SSH) you will need to use
138+-- the specific port mentioned under INPUT ENDPOINTS.
1module Control.Distributed.Process.Backend.Azure
139module Control.Distributed.Process.Backend.Azure
2 ( -- * Initialization
140 ( -- * Initialization
3 Backend(..)
141 Backend(..)