en-US/using-sshkeys.xml - cloudstack-docs - Git at Google

 <?xml version='1.0' encoding='utf-8' ?>
 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 <!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
 %BOOK_ENTITIES;
 ]>

 <!-- Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
 -->

 <section id="using-sshkeys">
     <title>Using SSH Keys for Authentication</title>
     <para>In addition to the username and password authentication, &PRODUCT; supports using SSH keys to log in to the cloud infrastructure for additional security. 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>
         <section id="create-ssh-template">
         <title> Creating an Instance Template that Supports SSH Keys</title>
             <para>Create a instance template that supports SSH Keys.</para>
             <orderedlist>
                 <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>
         </section>
         <section id="create-ssh-keypair">
         <title>Creating the SSH Keypair</title>
             <para>You must make a call to the createSSHKeyPair api method. You can either use the &PRODUCT; 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>
         </section>
         <section id="creating-ssh-instance">
         <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-ssh-template"/>. Ensure that you use the same SSH key name that you created at <xref linkend="create-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 number&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>
         </section>
         <section id="logging-in-ssh">
             <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>
         </section>
     <section id="reset-ssh">
         <title>Resetting SSH Keys</title>
         <para>With the API command resetSSHKeyForVirtualMachine, a user can set or reset the SSH keypair
             assigned to a virtual machine. A lost or compromised SSH keypair
             can be changed, and the user can access the VM by using the new keypair. Just create or register a
             new keypair, then call resetSSHKeyForVirtualMachine.</para>
     </section>
 </section>
	<?xml version='1.0' encoding='utf-8' ?>
	<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
	<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
	%BOOK_ENTITIES;
	]>

	<!-- Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<section id="using-sshkeys">
	<title>Using SSH Keys for Authentication</title>
	<para>In addition to the username and password authentication, &PRODUCT; supports using SSH keys to log in to the cloud infrastructure for additional security. 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>
	<section id="create-ssh-template">
	<title> Creating an Instance Template that Supports SSH Keys</title>
	<para>Create a instance template that supports SSH Keys.</para>
	<orderedlist>
	<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&ts=1331225219&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>
	</section>
	<section id="create-ssh-keypair">
	<title>Creating the SSH Keypair</title>
	<para>You must make a call to the createSSHKeyPair api method. You can either use the &PRODUCT; 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&name=keypair-doc&account=admin&domainid=5163440e-c44b-42b5-9109-ad75cae8e8a2"</programlisting>
	<para>The output is something similar to what is given below:</para>
	<programlisting><?xml version="1.0" encoding="ISO-8859-1"?><createsshkeypairresponse cloud-stack-version="3.0.0.20120228045507"><keypair><name>keypair-doc</name><fingerprint>f6:77:39:d5:5e:77:02:22:6a:d8:7f:ce:ab:cd:b3:56</fingerprint><privatekey>-----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-----
	</privatekey></keypair></createsshkeypairresponse></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>
	</section>
	<section id="creating-ssh-instance">
	<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-ssh-template"/>. Ensure that you use the same SSH key name that you created at <xref linkend="create-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:<port number>/?command=deployVirtualMachine\&zoneId=1\&serviceOfferingId=18727021-7556-4110-9322-d625b52e0813\&templateId=e899c18a-ce13-4bbf-98a9-625c5026e0b5\&securitygroupids=ff03f02f-9e3b-48f8-834d-91b822da40c5\&account=admin\&domainid=1\&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>
	</section>
	<section id="logging-in-ssh">
	<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 <ip address></programlisting>
	<para>The -i parameter tells the ssh client to use a ssh key found at ~/.ssh/keypair-doc.</para>
	</section>
	<section id="reset-ssh">
	<title>Resetting SSH Keys</title>
	<para>With the API command resetSSHKeyForVirtualMachine, a user can set or reset the SSH keypair
	assigned to a virtual machine. A lost or compromised SSH keypair
	can be changed, and the user can access the VM by using the new keypair. Just create or register a
	new keypair, then call resetSSHKeyForVirtualMachine.</para>
	</section>
	</section>