Developer Cloud Sandboxes solution

h1. Getting Started

{{>toc}}

This guide will drive you step by step through the setup of your first sandbox from the instantiation to its remote access.

In order to perform the described procedures, you must have an access to the Sandbox Service enabled on the Dashboard.

*+Prerequisites+* 

1) You have a valid certificate registered

2) You have installed and configured a VPN client with your certificate. A procedure is proposed at [[VPNsetup|Setup your VPN client]]

3) You have imported your certificate in your web browser following this procedure [[Import Certificate in web browser]]

h2. 1 Access to Sandbox

h3. User setup (user access to VM)

The user (PI) who wants to access the VM, can do so by using his existing X.509 certificate. It is foreseen to generate these keys automatically when a sandbox instance is requested and make them downloadable from the portal interface. But for completeness, the manual steps involved for Unix and Windows are described below:

h4. *Unix / Linux*

* The user downloads his X.509 certificate from the user management portal (e.g. in PEM format), either with encrypted private key (recommended) or unencrypted private key (not recommended)

* On the command line, the user can now directly access the VM using:

<pre>ssh -i <username>.pem <username>@<sandboxhost></pre>

Depending on the downloaded format, the user has to provide his passphrase (if encrypted key was downloaded) or not (if the key was downloaded unencrypted).

h4. *Windows (using putty)*

If the user wants to login from Windows using putty (a well-known freely available ssh client), the key must be converted into a putty-compatible format first:

* The user must download his X.509 certificate from in PEM format [*with unencrypted key*].

* From the file, the private key must be extracted manually (using a text editor): Copy the part

<pre>-----BEGIN RSA PRIVATE KEY-----

MII....

-----END RSA PRIVATE KEY-----</pre>

and paste it into a new file named e.g. <user>.private. Make sure this file is in a secure and safe place.

* This private key must now be imported with "puttygen":http://the.earth.li/~sgtatham/putty/latest/x86/puttygen.exe either on the command line:

<pre>puttygen <user>.private</pre>

> or using the import or load function in puttygen. The import should succeed with the following message:

!/attachments/download/5/Screen%20Shot%202013-03-19%20at%2009.22.54.png!

* The file must now be saved as private key either with (recommended) or without (not recommended) passphrase. Preferably name the resulting key <user>.ppk by clicking the "Save private key" button in the screen below: 

!/attachments/download/6/Screen%20Shot%202013-03-19%20at%2009.24.54.png!

* Now the user can access the VM with "putty":http://the.earth.li/~sgtatham/putty/latest/x86/putty.exe in the command line:

<pre>

putty –I <user>.ppk <user>@<sandboxhost>

</pre>

or save the corresponding info in a "Pageant":http://the.earth.li/~sgtatham/putty/latest/x86/pageant.exe session with the following four steps: In the session dialog, the "Host Name (or IP address)" field needs to be set to <sandboxhost> (Protocol SSH, Port 22):

> !http://controller.ciop.terradue.com/attachments/download/3/Untitled3.png!

* The, <user> must be added to the "Auto-login username" field in the Connection dialog:

> !http://controller.ciop.terradue.com/attachments/download/4/Untitled4.png!

and the created private key file needs to be referenced in the "Private key file for authentication" field of the Auth dialog:

> !http://controller.ciop.terradue.com/attachments/download/5/Untitled5.png!

Finally, the session can be saved (Session dialog) or just opened (Open button below).

* Make sure that the unencrypted X.509 PEM certificate is deleted (or at least stored in a secure and safe location) after this setup. The X.590 PEM certificate is not used to access the system with putty. Only the generated *<user>.ppk* file is needed.

h2. 2 Start integrating an application

Now you have your sandbox main controls in hand, you may continue with the [[Sandbox Application Integration Tutorial]].

This will guide through the practical usage of the sandbox to integrate your application.