cloudstack/docs/en-US/using-sshkeys.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file:///C:/Program%20Files%20(x86)/Publican/DocBook_DTD/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<section id="using-sshkeys">
    <title>Using the SSH Keys for Authentication on Cloud</title>
    <para>In addition to the username and password authentication, CloudStack supports using SSH
        keys to log in to the cloud infrastructure for additional security for your cloud
        infrastructure. You can use the createSSHKeyPair API to generate the SSH keys.</para>
    <para>Because each cloud user has their own ssh key, one cloud user cannot log in to another
        cloud user's instances unless they share their ssh key files.  Using a single SSH key pair,
        you can manage multiple instances.</para>    
    <sect1 id="create-template">
        <title> Creating an Instance Template that Supports SSH Keys</title>
            <para></para>
            <orderedlist>
                <listitem><para>Create a instance template that supports SSH Keys.</para>
                <orderedlist numeration="loweralpha"><listitem><para>Create a new instance by using the template provided by cloudstack.</para>
                 <para>For more information on creating a new instance, see </para></listitem>
                <listitem><para>Download the cloudstack script from  <ulink url="http://sourceforge.net/projects/cloudstack/files/SSH%20Key%20Gen%20Script/">The SSH Key Gen Script</ulink>to the instance you have created.</para>
                <programlisting>wget http://downloads.sourceforge.net/project/cloudstack/SSH%20Key%20Gen%20Script/cloud-set-guest-sshkey.in?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Fcloudstack%2Ffiles%2FSSH%2520Key%2520Gen%2520Script%2F&amp;ts=1331225219&amp;use_mirror=iweb</programlisting></listitem>
                <listitem><para>Copy the file to /etc/init.d.</para>
                <programlisting>cp cloud-set-guest-sshkey.in /etc/init.d/</programlisting></listitem>
                <listitem><para>Give the necessary permissions on the script:</para>
                <programlisting>chmod +x /etc/init.d/cloud-set-guest-sshkey.in</programlisting></listitem>  
                <listitem><para>Run the script while starting up the operating system:</para>
                <programlisting>chkconfig --add cloud-set-guest-sshkey.in</programlisting></listitem>                    
                <listitem><para>Stop the instance.</para></listitem>
                </orderedlist></listitem>
             </orderedlist>        
    </sect1>
    <sect1 id="gen-ssh-keypair">
        <title>Creating the SSH Keypair</title>
            <para>You must make a call to the createSSHKeyPair api method. You can either use the cloudstack python api library or the curl commands to make the call to the cloudstack api.</para>
            <para>For example, make a call from the cloudstack server to create a SSH keypair called "keypair-doc" for the admin account in the root domain:</para>
            <note><para>Ensure that you adjust these values to meet your needs. If you are making the API call from a different server, your URL/PORT will be different, and you will need to use the API keys.</para></note>
            <orderedlist>
                <listitem><para>Run the following curl command:</para>
                <programlisting>curl --globoff "http://localhost:8096/?command=createSSHKeyPair&amp;name=keypair-doc&amp;account=admin&amp;domainid=5163440e-c44b-42b5-9109-ad75cae8e8a2"</programlisting>
                <para>The output is something similar to what is given below:</para>
                <programlisting>&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;&lt;createsshkeypairresponse cloud-stack-version="3.0.0.20120228045507"&gt;&lt;keypair&gt;&lt;name&gt;keypair-doc&lt;/name&gt;&lt;fingerprint&gt;f6:77:39:d5:5e:77:02:22:6a:d8:7f:ce:ab:cd:b3:56&lt;/fingerprint&gt;&lt;privatekey&gt;-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQCSydmnQ67jP6lNoXdX3noZjQdrMAWNQZ7y5SrEu4wDxplvhYci
dXYBeZVwakDVsU2MLGl/K+wefwefwefwefwefJyKJaogMKn7BperPD6n1wIDAQAB
AoGAdXaJ7uyZKeRDoy6wA0UmF0kSPbMZCR+UTIHNkS/E0/4U+6lhMokmFSHtu
mfDZ1kGGDYhMsdytjDBztljawfawfeawefawfawfawQQDCjEsoRdgkduTy
QpbSGDIa11Jsc+XNDx2fgRinDsxXI/zJYXTKRhSl/LIPHBw/brW8vzxhOlSOrwm7
VvemkkgpAkEAwSeEw394LYZiEVv395ar9MLRVTVLwpo54jC4tsOxQCBlloocK
lYaocpk0yBqqOUSBawfIiDCuLXSdvBo1Xz5ICTM19vgvEp/+kMuECQBzm
nVo8b2Gvyagqt/KEQo8wzH2THghZ1qQ1QRhIeJG2aissEacF6bGB2oZ7Igim5L14
4KR7OeEToyCLC2k+02UCQQCrniSnWKtDVoVqeK/zbB32JhW3Wullv5p5zUEcd
KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3
-----END RSA PRIVATE KEY-----
&lt;/privatekey&gt;&lt;/keypair&gt;&lt;/createsshkeypairresponse&gt;</programlisting></listitem>
                <listitem><para>Copy the key data into a file. The file looks like this:</para>
                <programlisting>-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQCSydmnQ67jP6lNoXdX3noZjQdrMAWNQZ7y5SrEu4wDxplvhYci
dXYBeZVwakDVsU2MLGl/K+wefwefwefwefwefJyKJaogMKn7BperPD6n1wIDAQAB
AoGAdXaJ7uyZKeRDoy6wA0UmF0kSPbMZCR+UTIHNkS/E0/4U+6lhMokmFSHtu
mfDZ1kGGDYhMsdytjDBztljawfawfeawefawfawfawQQDCjEsoRdgkduTy
QpbSGDIa11Jsc+XNDx2fgRinDsxXI/zJYXTKRhSl/LIPHBw/brW8vzxhOlSOrwm7
VvemkkgpAkEAwSeEw394LYZiEVv395ar9MLRVTVLwpo54jC4tsOxQCBlloocK
lYaocpk0yBqqOUSBawfIiDCuLXSdvBo1Xz5ICTM19vgvEp/+kMuECQBzm
nVo8b2Gvyagqt/KEQo8wzH2THghZ1qQ1QRhIeJG2aissEacF6bGB2oZ7Igim5L14
4KR7OeEToyCLC2k+02UCQQCrniSnWKtDVoVqeK/zbB32JhW3Wullv5p5zUEcd
KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3
-----END RSA PRIVATE KEY-----</programlisting></listitem>
                <listitem><para>Save the file.</para></listitem>
            </orderedlist>
    </sect1>
    <sect1>
        <title>Creating an Instance</title>
        <para>After you save the SSH keypair file, you must create an instance by using the template that you created at <xref linkend="create-template"/>. Ensure that you use the same SSH key name that you created at <xref linkend="gen-ssh-keypair"/>.</para>
        <note><para>You cannot create the instance by using the GUI at this time and associate the instance with the newly created SSH keypair.</para></note>
        <para>A sample curl command to create a new instance is:</para>
        <programlisting>curl --globoff http://localhost:&lt;port numbet&gt;/?command=deployVirtualMachine\&amp;zoneId=1\&amp;serviceOfferingId=18727021-7556-4110-9322-d625b52e0813\&amp;templateId=e899c18a-ce13-4bbf-98a9-625c5026e0b5\&amp;securitygroupids=ff03f02f-9e3b-48f8-834d-91b822da40c5\&amp;account=admin\&amp;domainid=1\&amp;keypair=keypair-doc</programlisting>
        <para>Substitute the template, service offering and security group IDs (if you are using the security group feature) that are in your cloud environment.</para>
    </sect1>
    <sect1 id="login-using-sshkey">
        <title>Logging In Using the SSH Keypair</title>
            <para>To test your SSH key generation is successful, check whether you can log in to the cloud setup.</para>
            <para>For exaple, from a Linux OS, run:</para>
            <programlisting>ssh -i ~/.ssh/keypair-doc &lt;ip address&gt;</programlisting>
        <para>The -i parameter tells the ssh client to use a ssh key found at ~/.ssh/keypair-doc.</para>
    </sect1>
   </section>