diff --git a/docs/tmp/en-US/html/accounts-users-domains.html b/docs/tmp/en-US/html/accounts-users-domains.html index 360c8b2dc0c..19b5e832683 100644 --- a/docs/tmp/en-US/html/accounts-users-domains.html +++ b/docs/tmp/en-US/html/accounts-users-domains.html @@ -1,20 +1,20 @@ -3.1. Accounts, Users, and Domains

Product SiteDocumentation Site

3.1. Accounts, Users, and Domains

Accounts
+3.1. Accounts, Users, and Domains

Product SiteDocumentation Site

3.1. Accounts, Users, and Domains

Accounts
An account typically represents a customer of the service provider or a department in a large organization. Multiple users can exist in an account. -
Domains
+
Domains
Accounts are grouped by domains. Domains usually contain multiple accounts that have some logical relationship to each other and a set of delegated administrators with some authority over the domain and its subdomains. For example, a service provider with several resellers could create a domain for each reseller.
For each account created, the Cloud installation creates three different types of user accounts: root administrator, domain administrator, and user. -
Users
+
Users
Users are like aliases in the account. Users in the same account are not isolated from each other, but they are isolated from users in other accounts. Most installations need not surface the notion of users; they just have one user per account. The same user cannot belong to multiple accounts.
Username is unique in a domain across accounts in that domain. The same username can exist in other domains, including sub-domains. Domain name can repeat only if the full pathname from root is unique. For example, you can create root/d1, as well as root/foo/d1, and root/sales/d1.
Administrators are accounts with special privileges in the system. There may be multiple administrators in the system. Administrators can create or delete other administrators, and change the password for any user in the system. -
Domain Administrators
+
Domain Administrators
Domain administrators can perform administrative operations for users who belong to that domain. Domain administrators do not have visibility into physical servers or other domains. -
Root Administrator
+
Root Administrator
Root administrators have complete access to the system, including managing templates, service offerings, customer care administrators, and domains
The resources belong to the account, not individual users in that account. For example, billing, resource limits, and so on are maintained by the account, not the users. A user can operate on any resource in the account provided the user has privileges for that operation. The privileges are determined by the role. diff --git a/docs/tmp/en-US/html/configure-vpc.html b/docs/tmp/en-US/html/configure-vpc.html index 2748895e7e8..02d902e71c1 100644 --- a/docs/tmp/en-US/html/configure-vpc.html +++ b/docs/tmp/en-US/html/configure-vpc.html @@ -4,7 +4,7 @@ CloudStack Virtual Private Cloud is a private, isolated part of CloudStack. A VPC can have its own virtual network topology that resembles a traditional physical network. You can launch VMs in the virtual network that can have private addresses in the range of your choice, for example: 10.0.0.0/16. You can define network tiers within your VPC network range, which in turn enables you to group similar kinds of instances based on IP address range.
For example, if a VPC has the private range 10.0.0.0/16, its guest networks can have the network ranges 10.0.1.0/24, 10.0.2.0/24, 10.0.3.0/24, and so on. -
Major Components of a VPC:
+
Major Components of a VPC:
A VPC is comprised of the following network components:
Network Architecture in a VPC
+
Network Architecture in a VPC
In a VPC, the following four basic options of network architectures are present:
  • VPC with a public gateway only @@ -34,7 +34,7 @@ VPC with public and private gateways and site-to-site VPN access
  • VPC with a private gateway only and site-to-site VPN access -
Connectivity Options for a VPC
+
Connectivity Options for a VPC
You can connect your VPC to:
VPC Network Considerations
+
VPC Network Considerations
Consider the following before you create a VPC:

7.5.1. Adding a Host (XenServer or KVM)

XenServer and KVM hosts can be added to a cluster at any time. -

7.5.1.1. Requirements for XenServer and KVM Hosts

Warning

+

7.5.1.1. Requirements for XenServer and KVM Hosts

Warning

Make sure the hypervisor host does not have any VMs already running before you add it to CloudStack.
Configuration requirements: @@ -26,7 +26,7 @@ For KVM, do not put more than 16 hosts in a cluster.
For hardware requirements, see the installation section for your hypervisor in the CloudStack Installation Guide. -
7.5.1.1.1. XenServer Host Additional Requirements
+
7.5.1.1.1. XenServer Host Additional Requirements
If network bonding is in use, the administrator must cable the new host identically to other hosts in the cluster.
For all additional hosts to be added to the cluster, run the following command. This will cause the host to join the master in a XenServer pool. @@ -38,11 +38,11 @@ Copy the script from the Management Server in /usr/lib64/cloud/common/scripts/vm/hypervisor/xenserver/cloud-setup-bonding.sh to the master host and ensure it is executable.
  • Run the script: -
    # ./cloud-setup-bonding.sh
  • 7.5.1.1.2. KVM Host Additional Requirements
    • +
      # ./cloud-setup-bonding.sh
    7.5.1.1.2. KVM Host Additional Requirements
    • If shared mountpoint storage is in use, the administrator should ensure that the new host has all the same mountpoints (with storage mounted) as the other hosts in the cluster.
    • Make sure the new host has the same network configuration (guest, private, and public network) as other hosts in the cluster. -

    7.5.1.2. Adding a XenServer or KVM Host

    • +

    7.5.1.2. Adding a XenServer or KVM Host

    • If you have not already done so, install the hypervisor software on the host. You will need to know which version of the hypervisor software version is supported by CloudStack and what additional configuration is required to ensure the host will work with CloudStack. To find these installation details, see the appropriate section for your hypervisor in the CloudStack Installation Guide.
    • Log in to the CloudStack UI as administrator. diff --git a/docs/tmp/en-US/html/index.html b/docs/tmp/en-US/html/index.html index 229192f2767..89a0e0ce36d 100644 --- a/docs/tmp/en-US/html/index.html +++ b/docs/tmp/en-US/html/index.html @@ -1,9 +1,9 @@ -Version 4.0.0-incubating Release Notes

      Product SiteDocumentation Site

      Apache CloudStack

      Version 4.0.0-incubating Release Notes

      Revised October 17, 2012 19:49 UTC

      +Version 4.0.0-incubating Release Notes

      Product SiteDocumentation Site

      Apache CloudStack

      Version 4.0.0-incubating Release Notes

      Revised October 17, 2012 19:49 UTC

      -

      Apache CloudStack


      Legal Notice

      +

      Apache CloudStack


      Legal Notice

      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 diff --git a/docs/tmp/en-US/html/log-in.html b/docs/tmp/en-US/html/log-in.html index 6ece78e2284..30f63078010 100644 --- a/docs/tmp/en-US/html/log-in.html +++ b/docs/tmp/en-US/html/log-in.html @@ -4,11 +4,11 @@ CloudStack provides a web-based UI that can be used by both administrators and end users. The appropriate version of the UI is displayed depending on the credentials used to log in. The UI is available in popular browsers including IE7, IE8, IE9, Firefox 3.5+, Firefox 4, Safari 4, and Safari 5. The URL is: (substitute your own management server IP address)
      http://<management-server-ip-address>:8080/client
      On a fresh Management Server installation, a guided tour splash screen appears. On later visits, you’ll see a login screen where you specify the following to proceed to your Dashboard: -
      Username
      +
      Username
      The user ID of your account. The default username is admin. -
      Password
      +
      Password
      The password associated with the user ID. The password for the default username is password. -
      Domain
      +
      Domain
      If you are a root user, leave this field blank.
      If you are a user in the sub-domains, enter the full path to the domain, excluding the root domain. diff --git a/docs/tmp/en-US/html/network-service-providers.html b/docs/tmp/en-US/html/network-service-providers.html index 4c59e845d1d..48b4b54844d 100644 --- a/docs/tmp/en-US/html/network-service-providers.html +++ b/docs/tmp/en-US/html/network-service-providers.html @@ -8,6 +8,6 @@ You can have multiple instances of the same service provider in a network (say, more than one Juniper SRX device).
      If different providers are set up to provide the same service on the network, the administrator can create network offerings so users can specify which network service provider they prefer (along with the other choices offered in network offerings). Otherwise, CloudPlatform will choose which provider to use whenever the service is called for. -
      Supported Network Service Providers
      +
      Supported Network Service Providers
      CloudPlatform ships with an internal list of the supported service providers, and you can choose from this list when creating a network offering.
      diff --git a/docs/tmp/en-US/html/troubleshooting-dataloss-on-exported-primary-storage.html b/docs/tmp/en-US/html/troubleshooting-dataloss-on-exported-primary-storage.html index 91bfe531a62..0981ebc663a 100644 --- a/docs/tmp/en-US/html/troubleshooting-dataloss-on-exported-primary-storage.html +++ b/docs/tmp/en-US/html/troubleshooting-dataloss-on-exported-primary-storage.html @@ -1,13 +1,13 @@ -22.3. Data Loss on Exported Primary Storage

      Product SiteDocumentation Site

      22.3. Data Loss on Exported Primary Storage

      Symptom
      +22.3. Data Loss on Exported Primary Storage

      Product SiteDocumentation Site

      22.3. Data Loss on Exported Primary Storage

      Symptom
      Loss of existing data on primary storage which has been exposed as a Linux NFS server export on an iSCSI volume. -
      Cause
      +
      Cause
      It is possible that a client from outside the intended pool has mounted the storage. When this occurs, the LVM is wiped and all data in the volume is lost -
      Solution
      +
      Solution
      When setting up LUN exports, restrict the range of IP addresses that are allowed access by specifying a subnet mask. For example:
      echo “/export 192.168.1.0/24(rw,async,no_root_squash)” > /etc/exports
      Adjust the above command to suit your deployment needs. -
      More Information
      +
      More Information
      See the export procedure in the "Secondary Storage" section of the CloudStack Installation Guide
      diff --git a/docs/tmp/en-US/html/troubleshooting-lb-rules-fails.html b/docs/tmp/en-US/html/troubleshooting-lb-rules-fails.html index adb82ff6597..fc73fbaf796 100644 --- a/docs/tmp/en-US/html/troubleshooting-lb-rules-fails.html +++ b/docs/tmp/en-US/html/troubleshooting-lb-rules-fails.html @@ -1,9 +1,9 @@ -22.8. Load balancer rules fail after changing network offering

      Product SiteDocumentation Site

      22.8. Load balancer rules fail after changing network offering

      Symptom
      +22.8. Load balancer rules fail after changing network offering

      Product SiteDocumentation Site

      22.8. Load balancer rules fail after changing network offering

      Symptom
      After changing the network offering on a network, load balancer rules stop working. -
      Cause
      +
      Cause
      Load balancing rules were created while using a network service offering that includes an external load balancer device such as NetScaler, and later the network service offering changed to one that uses the CloudPlatform virtual router. -
      Solution
      +
      Solution
      Create a firewall rule on the virtual router for each of your existing load balancing rules so that they continue to function.
      diff --git a/docs/tmp/en-US/html/troubleshooting-maintenance-mode-not-working-on-vCenter.html b/docs/tmp/en-US/html/troubleshooting-maintenance-mode-not-working-on-vCenter.html index 867ad3d423c..7b86c4ab4de 100644 --- a/docs/tmp/en-US/html/troubleshooting-maintenance-mode-not-working-on-vCenter.html +++ b/docs/tmp/en-US/html/troubleshooting-maintenance-mode-not-working-on-vCenter.html @@ -1,11 +1,11 @@ -22.5. Maintenance mode not working on vCenter

      Product SiteDocumentation Site

      22.5. Maintenance mode not working on vCenter

      Symptom
      +22.5. Maintenance mode not working on vCenter

      Product SiteDocumentation Site

      22.5. Maintenance mode not working on vCenter

      Symptom
      Host was placed in maintenance mode, but still appears live in vCenter. -
      Cause
      +
      Cause
      The CloudPlatform administrator UI was used to place the host in scheduled maintenance mode. This mode is separate from vCenter's maintenance mode. -
      Solution
      +
      Solution
      Use vCenter to place the host in maintenance mode. -
      More Information
      +
      diff --git a/docs/tmp/en-US/html/troubleshooting-recover-lost-virtual-router.html b/docs/tmp/en-US/html/troubleshooting-recover-lost-virtual-router.html index 8f16d7eb5f4..685f2f50f1b 100644 --- a/docs/tmp/en-US/html/troubleshooting-recover-lost-virtual-router.html +++ b/docs/tmp/en-US/html/troubleshooting-recover-lost-virtual-router.html @@ -1,10 +1,10 @@ -22.4. Recovering a Lost Virtual Router

      Product SiteDocumentation Site

      22.4. Recovering a Lost Virtual Router

      Symptom
      +22.4. Recovering a Lost Virtual Router

      Product SiteDocumentation Site

      22.4. Recovering a Lost Virtual Router

      Symptom
      A virtual router is running, but the host is disconnected. A virtual router no longer functions as expected. -
      Cause
      +
      Cause
      The Virtual router is lost or down. -
      Solution
      +
      Solution
      If you are sure that a virtual router is down forever, or no longer functions as expected, destroy it. You must create one afresh while keeping the backup router up and running (it is assumed this is in a redundant router setup):
      • Force stop the router. Use the stopRouter API with forced=true parameter to do so. diff --git a/docs/tmp/en-US/html/troubleshooting-unable-to-deploy-vms.html b/docs/tmp/en-US/html/troubleshooting-unable-to-deploy-vms.html index 0f422351879..c017acb78f4 100644 --- a/docs/tmp/en-US/html/troubleshooting-unable-to-deploy-vms.html +++ b/docs/tmp/en-US/html/troubleshooting-unable-to-deploy-vms.html @@ -1,9 +1,9 @@ -22.6. Unable to deploy VMs from uploaded vSphere template

        Product SiteDocumentation Site

        22.6. Unable to deploy VMs from uploaded vSphere template

        Symptom
        +22.6. Unable to deploy VMs from uploaded vSphere template

        Product SiteDocumentation Site

        22.6. Unable to deploy VMs from uploaded vSphere template

        Symptom
        When attempting to create a VM, the VM will not deploy. -
        Cause
        +
        Cause
        If the template was created by uploading an OVA file that was created using vSphere Client, it is possible the OVA contained an ISO image. If it does, the deployment of VMs from the template will fail. -
        Solution
        +
        Solution
        Remove the ISO and re-upload the template.
        diff --git a/docs/tmp/en-US/html/troubleshooting-unable-to-power-on-vm.html b/docs/tmp/en-US/html/troubleshooting-unable-to-power-on-vm.html index f5ad17c4d41..2d53a1f6a1d 100644 --- a/docs/tmp/en-US/html/troubleshooting-unable-to-power-on-vm.html +++ b/docs/tmp/en-US/html/troubleshooting-unable-to-power-on-vm.html @@ -1,6 +1,6 @@ -22.7. Unable to power on virtual machine on VMware

        Product SiteDocumentation Site

        22.7. Unable to power on virtual machine on VMware

        Symptom
        +22.7. Unable to power on virtual machine on VMware

        Product SiteDocumentation Site

        22.7. Unable to power on virtual machine on VMware

        Symptom
        Virtual machine does not power on. You might see errors like:
        • Unable to open Swap File @@ -8,9 +8,9 @@ Unable to access a file since it is locked
        • Unable to access Virtual machine configuration -
        Cause
        +
      Cause
      A known issue on VMware machines. ESX hosts lock certain critical virtual machine files and file systems to prevent concurrent changes. Sometimes the files are not unlocked when the virtual machine is powered off. When a virtual machine attempts to power on, it can not access these critical files, and the virtual machine is unable to power on. -
      Solution
      +
      Solution
      See the following:
      VMware Knowledge Base Article diff --git a/docs/tmp/en-US/html/upgrade-instructions.html b/docs/tmp/en-US/html/upgrade-instructions.html index 442b2d780a1..006851663f6 100644 --- a/docs/tmp/en-US/html/upgrade-instructions.html +++ b/docs/tmp/en-US/html/upgrade-instructions.html @@ -574,14 +574,14 @@ Done restarting router(s). If you would like additional confirmation that the new system VM templates were correctly applied when these system VMs were rebooted, SSH into the System VM and check the version.
      Use one of the following techniques, depending on the hypervisor. -
      XenServer or KVM:
      +
      XenServer or KVM:
      SSH in by using the link local IP address of the system VM. For example, in the command below, substitute your own path to the private key used to log in to the system VM and your own link local IP.
      Run the following commands on the XenServer or KVM host on which the system VM is present:
      # ssh -i private-key-path link-local-ip -p 3922
       # cat /etc/cloudstack-release
      The output should be like the following: -
      Cloudstack Release 4.0.0-incubating Mon Oct 9 15:10:04 PST 2012
      ESXi
      +
      Cloudstack Release 4.0.0-incubating Mon Oct 9 15:10:04 PST 2012
      ESXi
      SSH in using the private IP address of the system VM. For example, in the command below, substitute your own path to the private key used to log in to the system VM and your own private IP.
      Run the following commands on the Management Server: diff --git a/docs/tmp/en-US/html/vpn.html b/docs/tmp/en-US/html/vpn.html index f873ebf9150..59b71e19706 100644 --- a/docs/tmp/en-US/html/vpn.html +++ b/docs/tmp/en-US/html/vpn.html @@ -140,7 +140,7 @@ Dead Peer Detection: A method to detect an unavailable Internet Key Exchange (IKE) peer. Select this option if you want the virtual router to query the liveliness of its IKE peer at regular intervals. It’s recommended to have the same configuration of DPD on both side of VPN connection.
  • Click OK. -
  • Updating and Removing a VPN Customer Gateway
    +
    Updating and Removing a VPN Customer Gateway
    You can update a customer gateway either with no VPN connection, or related VPN connection is in error state.
    1. Log in to the CloudStack UI as an administrator or end user. diff --git a/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-API_Developers_Guide-en-US.pdf b/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-API_Developers_Guide-en-US.pdf index c4e90e663dc..0beeff2b58e 100644 Binary files a/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-API_Developers_Guide-en-US.pdf and b/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-API_Developers_Guide-en-US.pdf differ diff --git a/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-Admin_Guide-en-US.pdf b/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-Admin_Guide-en-US.pdf index 6d4d06b634a..82cdd99bb69 100644 Binary files a/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-Admin_Guide-en-US.pdf and b/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-Admin_Guide-en-US.pdf differ diff --git a/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-Release_Notes-en-US.pdf b/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-Release_Notes-en-US.pdf index 82b5c89487d..283f8808a7b 100644 Binary files a/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-Release_Notes-en-US.pdf and b/docs/tmp/en-US/pdf/Apache_CloudStack-4.0.0-incubating-Release_Notes-en-US.pdf differ diff --git a/docs/tmp/en-US/xml/API_Developers_Guide.fo b/docs/tmp/en-US/xml/API_Developers_Guide.fo index be22005ebb8..cac56b45d9c 100644 --- a/docs/tmp/en-US/xml/API_Developers_Guide.fo +++ b/docs/tmp/en-US/xml/API_Developers_Guide.fo @@ -1,8 +1,8 @@ -CloudStack API Developer's GuideDocBook XSL Stylesheets with Apache FOPCloudStack API Developer's GuideTable of ContentsChapter 1. Concepts1.1. What Is CloudStack?1.2. What Can CloudStack Do?1.3. Deployment Architecture Overview1.3.1. Management Server Overview1.3.2. Cloud Infrastructure Overview1.3.3. Networking OverviewChapter 2. Introduction for Developers2.1. Roles2.2. API Reference Documentation2.3. Getting StartedChapter 3. What's New in the API?3.1. What's New in the API for 4.03.1.1. Changed API Commands in 4.0.0-incubating3.1.2. Added API Commands in 4.0.0-incubating3.2. What's New in the API for 3.03.2.1. Enabling Port 80963.2.2. Stopped VM3.2.3. Change to Behavior of List Commands3.2.4. Removed API commands3.2.5. Added API commands in 3.03.2.5.1. Added in 3.0.23.2.5.2. Added in 3.0.13.2.5.3. Added in 3.0.03.2.6. Added CloudStack Error CodesChapter 4. Calling the CloudStack API4.1. Making API Requests4.2. Enabling API Call Expiration4.3. Signing API Requests4.4. Responses4.4.1. Response Formats: XML and JSON4.4.2. Maximum Result Pages Returned4.4.3. Error Handling4.5. Asynchronous Commands4.5.1. Job Status4.5.2. ExampleChapter 5. Working With Usage Data5.1. Usage Record Format5.1.1. Virtual Machine Usage Record Format5.1.2. Network Usage Record Format5.1.3. IP Address Usage Record Format5.1.4. Disk Volume Usage Record Format5.1.5. Template, ISO, and Snapshot Usage Record Format5.1.6. Load Balancer Policy or Port Forwarding Rule Usage Record Format5.1.7. Network Offering Usage Record Format5.1.8. VPN User Usage Record Format5.2. Usage Types5.3. Example response from listUsageRecords5.4. Dates in the Usage RecordAppendix A. Event TypesAppendix B. AlertsAppendix C. Time ZonesAppendix D. Revision HistoryCloudStack API Developer's GuideApache CloudStack 4.0.0-incubatingCloudStack API Developer's Guide +CloudStack API Developer's GuideDocBook XSL Stylesheets with Apache FOPCloudStack API Developer's GuideTable of ContentsChapter 1. Concepts1.1. What Is CloudStack?1.2. What Can CloudStack Do?1.3. Deployment Architecture Overview1.3.1. Management Server Overview1.3.2. Cloud Infrastructure Overview1.3.3. Networking OverviewChapter 2. Introduction for Developers2.1. Roles2.2. API Reference Documentation2.3. Getting StartedChapter 3. What's New in the API?3.1. What's New in the API for 4.03.1.1. Changed API Commands in 4.0.0-incubating3.1.2. Added API Commands in 4.0.0-incubating3.2. What's New in the API for 3.03.2.1. Enabling Port 80963.2.2. Stopped VM3.2.3. Change to Behavior of List Commands3.2.4. Removed API commands3.2.5. Added API commands in 3.03.2.5.1. Added in 3.0.23.2.5.2. Added in 3.0.13.2.5.3. Added in 3.0.03.2.6. Added CloudStack Error CodesChapter 4. Calling the CloudStack API4.1. Making API Requests4.2. Enabling API Call Expiration4.3. Signing API Requests4.4. Responses4.4.1. Response Formats: XML and JSON4.4.2. Maximum Result Pages Returned4.4.3. Error Handling4.5. Asynchronous Commands4.5.1. Job Status4.5.2. ExampleChapter 5. Working With Usage Data5.1. Usage Record Format5.1.1. Virtual Machine Usage Record Format5.1.2. Network Usage Record Format5.1.3. IP Address Usage Record Format5.1.4. Disk Volume Usage Record Format5.1.5. Template, ISO, and Snapshot Usage Record Format5.1.6. Load Balancer Policy or Port Forwarding Rule Usage Record Format5.1.7. Network Offering Usage Record Format5.1.8. VPN User Usage Record Format5.2. Usage Types5.3. Example response from listUsageRecords5.4. Dates in the Usage RecordAppendix A. Event TypesAppendix B. AlertsAppendix C. Time ZonesAppendix D. Revision HistoryCloudStack API Developer's GuideApache CloudStack 4.0.0-incubatingCloudStack API Developer's Guide - Apache CloudStackApache CloudStack 4.0.0-incubating CloudStack API Developer's GuideAuthorApache CloudStack + Apache CloudStackApache CloudStack 4.0.0-incubating CloudStack API Developer's GuideAuthorApache CloudStack 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 @@ -14,15 +14,15 @@ Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. How to integrate with CloudStack using the CloudStack API. - CloudStack API Developer's Guide1. Concepts   1.1. What Is CloudStack? 1.2. What Can CloudStack Do? 1.3. Deployment Architecture Overview 1.3.1. Management Server Overview 1.3.2. Cloud Infrastructure Overview 1.3.3. Networking Overview 2. Introduction for Developers   2.1. Roles 2.2. API Reference Documentation 2.3. Getting Started 3. What's New in the API?   3.1. What's New in the API for 4.0 3.1.1. Changed API Commands in 4.0.0-incubating 3.1.2. Added API Commands in 4.0.0-incubating 3.2. What's New in the API for 3.0 3.2.1. Enabling Port 8096 3.2.2. Stopped VM 3.2.3. Change to Behavior of List Commands 3.2.4. Removed API commands 3.2.5. Added API commands in 3.0 3.2.6. Added CloudStack Error Codes 4. Calling the CloudStack API   4.1. Making API Requests 4.2. Enabling API Call Expiration 4.3. Signing API Requests 4.4. Responses 4.4.1. Response Formats: XML and JSON 4.4.2. Maximum Result Pages Returned 4.4.3. Error Handling 4.5. Asynchronous Commands 4.5.1. Job Status 4.5.2. Example 5. Working With Usage Data   5.1. Usage Record Format 5.1.1. Virtual Machine Usage Record Format 5.1.2. Network Usage Record Format 5.1.3. IP Address Usage Record Format 5.1.4. Disk Volume Usage Record Format 5.1.5. Template, ISO, and Snapshot Usage Record Format 5.1.6. Load Balancer Policy or Port Forwarding Rule Usage Record Format 5.1.7. Network Offering Usage Record Format 5.1.8. VPN User Usage Record Format 5.2. Usage Types 5.3. Example response from listUsageRecords 5.4. Dates in the Usage Record A. Event Types   B. Alerts   C. Time Zones   D. Revision History   Chapter 1.Chapter 1. ConceptsConceptsWhat Is CloudStack?1.1. What Is CloudStack? + CloudStack API Developer's Guide1. Concepts   1.1. What Is CloudStack? 1.2. What Can CloudStack Do? 1.3. Deployment Architecture Overview 1.3.1. Management Server Overview 1.3.2. Cloud Infrastructure Overview 1.3.3. Networking Overview 2. Introduction for Developers   2.1. Roles 2.2. API Reference Documentation 2.3. Getting Started 3. What's New in the API?   3.1. What's New in the API for 4.0 3.1.1. Changed API Commands in 4.0.0-incubating 3.1.2. Added API Commands in 4.0.0-incubating 3.2. What's New in the API for 3.0 3.2.1. Enabling Port 8096 3.2.2. Stopped VM 3.2.3. Change to Behavior of List Commands 3.2.4. Removed API commands 3.2.5. Added API commands in 3.0 3.2.6. Added CloudStack Error Codes 4. Calling the CloudStack API   4.1. Making API Requests 4.2. Enabling API Call Expiration 4.3. Signing API Requests 4.4. Responses 4.4.1. Response Formats: XML and JSON 4.4.2. Maximum Result Pages Returned 4.4.3. Error Handling 4.5. Asynchronous Commands 4.5.1. Job Status 4.5.2. Example 5. Working With Usage Data   5.1. Usage Record Format 5.1.1. Virtual Machine Usage Record Format 5.1.2. Network Usage Record Format 5.1.3. IP Address Usage Record Format 5.1.4. Disk Volume Usage Record Format 5.1.5. Template, ISO, and Snapshot Usage Record Format 5.1.6. Load Balancer Policy or Port Forwarding Rule Usage Record Format 5.1.7. Network Offering Usage Record Format 5.1.8. VPN User Usage Record Format 5.2. Usage Types 5.3. Example response from listUsageRecords 5.4. Dates in the Usage Record A. Event Types   B. Alerts   C. Time Zones   D. Revision History   Chapter 1.Chapter 1. ConceptsConceptsWhat Is CloudStack?1.1. What Is CloudStack? CloudStack is an open source software platform that pools computing resources to build public, private, and hybrid Infrastructure as a Service (IaaS) clouds. CloudStack manages the network, storage, and compute nodes that make up a cloud infrastructure. Use CloudStack to deploy, manage, and configure cloud computing environments. Typical users are service providers and enterprises. With CloudStack, you can: - + Set up an on-demand, elastic cloud computing service. Service providers can sell self service virtual machine instances, storage volumes, and networking configurations over the Internet. - + Set up an on-premise private cloud for use by employees. Rather than managing virtual machines in the same way as physical machines, with CloudStack an enterprise can offer self-service virtual machines to users without involving IT departments. - What Can CloudStack Do?1.2. What Can CloudStack Do? + What Can CloudStack Do?1.2. What Can CloudStack Do? Multiple Hypervisor Support CloudStack works with a variety of hypervisors, and a single cloud deployment can contain multiple hypervisor implementations. The current release of CloudStack supports pre-packaged enterprise solutions like Citrix XenServer and VMware vSphere, as well as KVM or Xen running on Ubuntu or CentOS. @@ -54,7 +54,7 @@ A CloudStack installation consists of two parts: the Management Server and the cloud infrastructure that it manages. When you set up and manage a CloudStack cloud, you provision resources such as hosts, storage devices, and IP addresses into the Management Server, and the Management Server manages those resources. The minimum production installation consists of one machine running the CloudStack Management Server and another machine to act as the cloud infrastructure (in this case, a very simple infrastructure consisting of one host running hypervisor software). In its smallest deployment, a single machine can act as both the Management Server and the hypervisor host (using the KVM hypervisor). - + A more full-featured installation consists of a highly-available multi-node Management Server installation and up to tens of thousands of hosts using any of several advanced networking setups. For information about deployment options, see Choosing a Deployment Architecture. Management Server Overview1.3.1. Management Server Overview The Management Server is the CloudStack software that manages cloud resources. By interacting with the Management Server through its UI or API, you can configure and manage your cloud infrastructure. @@ -64,53 +64,53 @@ The machine must meet the system requirements described in System Requirements. The Management Server: - + Provides the web user interface for the administrator and a reference user interface for end users. - + Provides the APIs for CloudStack. - + Manages the assignment of guest VMs to particular hosts. - + Manages the assignment of public and private IP addresses to particular accounts. - + Manages the allocation of storage to guests as virtual disks. - + Manages snapshots, templates, and ISO images, possibly replicating them across data centers. - + Provides a single point of configuration for the cloud. Cloud Infrastructure Overview1.3.2. Cloud Infrastructure Overview The Management Server manages one or more zones (typically, datacenters) containing host computers where guest virtual machines will run. The cloud infrastructure is organized as follows: - + Zone: Typically, a zone is equivalent to a single datacenter. A zone consists of one or more pods and secondary storage. - + Pod: A pod is usually one rack of hardware that includes a layer-2 switch and one or more clusters. - + Cluster: A cluster consists of one or more hosts and primary storage. - + Host: A single compute node within a cluster. The hosts are where the actual cloud services run in the form of guest virtual machines. - + Primary storage is associated with a cluster, and it stores the disk volumes for all the VMs running on hosts in that cluster. - + Secondary storage is associated with a zone, and it stores templates, ISO images, and disk volume snapshots. - + More Information For more information, see documentation on cloud infrastructure concepts. Networking Overview1.3.3. Networking Overview CloudStack offers two types of networking scenario: - + Basic. For AWS-style networking. Provides a single network where guest isolation can be provided through layer-3 means such as security groups (IP address source filtering). - + Advanced. For more sophisticated network topologies. This network model provides the most flexibility in defining guest networks. For more details, see Network Setup. Chapter 2.Chapter 2. Introduction for DevelopersIntroduction for DevelopersRoles2.1. Roles The CloudPlatform API supports three access roles: - 1. + 1. Root Admin. Access to all features of the cloud, including both virtual and physical resource management. - 2. + 2. Domain Admin. Access to only the virtual resources of the clouds that belong to the administrator’s domain. - 3. + 3. User. Access to only the features that allow management of the user’s virtual instances, storage, and network. API Reference Documentation2.2. API Reference Documentation 2.2 API Reference: @@ -122,19 +122,19 @@ http://download.cloud.com/releases/3.0.0/api_3.0.0/TOC_Root_Admin.html/ Getting Started2.3. Getting Started To get started using the CloudStack API, you should have the following: - + URL of the CloudStack server you wish to integrate with. - + Both the API Key and Secret Key for an account. This should have been generated by the administrator of the cloud instance and given to you. - + Familiarity with HTTP GET/POST and query strings. - + Knowledge of either XML or JSON. - + Knowledge of a programming language that can generate HTTP requests; for example, Java or PHP. Chapter 3.Chapter 3. What's New in the API?What's New in the API? The following describes any new major features of each CloudStack version as it applies to API usage. - What's New in the API for 4.03.1. What's New in the API for 4.0Changed API Commands in 4.0.0-incubating3.1.1. Changed API Commands in 4.0.0-incubating + What's New in the API for 4.03.1. What's New in the API for 4.0Changed API Commands in 4.0.0-incubating3.1.1. Changed API Commands in 4.0.0-incubating API Commands @@ -220,7 +220,7 @@ New response parameter: tags(*) - Note + Note Many other commands also have the new tags(*) parameter in addition to other changes; those commands are listed separately. @@ -574,110 +574,110 @@ New response parameters: id, endip, gateway, netmask, networkid, podid, startip, vlan, zoneid - Added API Commands in 4.0.0-incubating3.1.2. Added API Commands in 4.0.0-incubating + Added API Commands in 4.0.0-incubating3.1.2. Added API Commands in 4.0.0-incubating createCounter (Adds metric counter) - + deleteCounter (Deletes a counter) - + listCounters (List the counters) - + createCondition (Creates a condition) - + deleteCondition (Removes a condition) - + listConditions (List Conditions for the specific user) - + createTags. Add tags to one or more resources. Example: -command=createTags +command=createTags &resourceIds=1,10,12 &resourceType=userVm &tags[0].key=region &tags[0].value=canada &tags[1].key=city &tags[1].value=Toronto - + deleteTags. Remove tags from one or more resources. Example: -command=deleteTags +command=deleteTags &resourceIds=1,12 &resourceType=Snapshot &tags[0].key=city - + listTags (Show currently defined resource tags) - + createVPC (Creates a VPC) - + listVPCs (Lists VPCs) - + deleteVPC (Deletes a VPC) - + updateVPC (Updates a VPC) - + restartVPC (Restarts a VPC) - + createVPCOffering (Creates VPC offering) - + updateVPCOffering (Updates VPC offering) - + deleteVPCOffering (Deletes VPC offering) - + listVPCOfferings (Lists VPC offerings) - + createPrivateGateway (Creates a private gateway) - + listPrivateGateways (List private gateways) - + deletePrivateGateway (Deletes a Private gateway) - + createNetworkACL (Creates a ACL rule the given network (the network has to belong to VPC)) - + deleteNetworkACL (Deletes a Network ACL) - + listNetworkACLs (Lists all network ACLs) - + createStaticRoute (Creates a static route) - + deleteStaticRoute (Deletes a static route) - + listStaticRoutes (Lists all static routes) - + createVpnCustomerGateway (Creates site to site vpn customer gateway) - + createVpnGateway (Creates site to site vpn local gateway) - + createVpnConnection (Create site to site vpn connection) - + deleteVpnCustomerGateway (Delete site to site vpn customer gateway) - + deleteVpnGateway (Delete site to site vpn gateway) - + deleteVpnConnection (Delete site to site vpn connection) - + updateVpnCustomerGateway (Update site to site vpn customer gateway) - + resetVpnConnection (Reset site to site vpn connection) - + listVpnCustomerGateways (Lists site to site vpn customer gateways) - + listVpnGateways (Lists site 2 site vpn gateways) - + listVpnConnections (Lists site to site vpn connection gateways) - + enableCiscoNexusVSM (Enables Nexus 1000v dvSwitch in CloudStack.) - + disableCiscoNexusVSM (Disables Nexus 1000v dvSwitch in CloudStack.) - + deleteCiscoNexusVSM (Deletes Nexus 1000v dvSwitch in CloudStack.) - + listCiscoNexusVSMs (Lists the control VLAN ID, packet VLAN ID, and data VLAN ID, as well as the IP address of the Nexus 1000v dvSwitch.) What's New in the API for 3.03.2. What's New in the API for 3.0Enabling Port 80963.2.1. Enabling Port 8096 Port 8096, which allows API calls without authentication, is closed and disabled by default on any fresh 3.0.1 installations. You can enable 8096 (or another port) for this purpose as follows: - 1. + 1. Ensure that the first Management Server is installed and running. - 2. + 2. Set the global configuration parameter integration.api.port to the desired port. - 3. + 3. Restart the Management Server. - 4. + 4. On the Management Server host machine, create an iptables rule allowing access to that port. Stopped VM3.2.2. Stopped VM CloudStack now supports creating a VM without starting it. You can determine whether the VM needs to be started as part of the VM deployment. A VM can now be deployed in two ways: create and start a VM (the default method); or create a VM and leave it in the stopped state. @@ -685,9 +685,9 @@ A new request parameter, startVM, is introduced in the deployVm API to support the stopped VM feature. The possible values are: - + true - The VM starts as a part of the VM deployment. - + false - The VM is left in the stopped state at the end of the VM deployment. The default value is true. @@ -697,11 +697,11 @@ When no parameters are passed in to the call, the caller sees only resources owned by the caller (even when the caller is the administrator). Previously, the administrator saw everyone else's resources by default. When accountName and domainId are passed in: - + The caller sees the resources dedicated to the account specified. - + If the call is executed by a regular user, the user is authorized to specify only the user's own account and domainId. - + If the caller is a domain administrator, CloudStack performs an authorization check to see whether the caller is permitted to view resources for the given account and domainId. When projectId is passed in, only resources belonging to that project are listed. @@ -713,7 +713,7 @@ To see all Project resources the caller is authorized to see, use the parameter projectId=-1. There is one API command that doesn't fall under the rules above completely: the listTemplates command. This command has its own flags defining the list rules: - + listTemplates Flag @@ -779,19 +779,19 @@ The CloudStack UI on a general view will display all resources that the logged-in user is authorized to see, except for project resources. To see the project resources, select the project view. - Removed API commands3.2.4. Removed API commands + Removed API commands3.2.4. Removed API commands createConfiguration (Adds configuration value) - + configureSimulator (Configures simulator) - Added API commands in 3.03.2.5. Added API commands in 3.03.2.5.1. Added in 3.0.2 + Added API commands in 3.03.2.5. Added API commands in 3.03.2.5.1. Added in 3.0.2 changeServiceForSystemVm Changes the service offering for a system VM (console proxy or secondary storage). The system VM must be in a "Stopped" state for this command to take effect. - 3.2.5.2. Added in 3.0.1 + 3.2.5.2. Added in 3.0.1 changeServiceForSystemVm Changes the service offering for a system VM (console proxy or secondary storage). The system VM must be in a "Stopped" state for this command to take effect. - 3.2.5.3. Added in 3.0.0 + 3.2.5.3. Added in 3.0.0 assignVirtualMachine (Move a user VM to another user under same domain.) @@ -1055,7 +1055,7 @@ Added CloudStack Error Codes3.2.6. Added CloudStack Error Codes You can now find the CloudStack-specific error code in the exception response for each type of exception. The following list of error codes is added to the new class named CSExceptionErrorCode. These codes are applicable in CloudStack 3.0.3 and later versions. - + 4250 : "com.cloud.utils.exception.CloudRuntimeException" @@ -1296,18 +1296,18 @@ Chapter 4.Chapter 4. Calling the CloudStack APICalling the CloudStack APIMaking API Requests4.1. Making API Requests All CloudStack API requests are submitted in the form of a HTTP GET/POST with an associated command and any parameters. A request is composed of the following whether in HTTP or HTTPS: - + CloudStack API URL: This is the web services API entry point(for example, http://www.cloud.com:8080/client/api) - + Command: The web services command you wish to execute, such as start a virtual machine or create a disk volume - + Parameters: Any additional required or optional parameters for the command A sample API GET request looks like the following: - http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D + http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D Or in a more readable format: - + 1. http://localhost:8080/client/api 2. ?command=deployVirtualMachine 3. &serviceOfferingId=1 @@ -1330,29 +1330,29 @@ You can set an expiry timestamp on API calls to prevent replay attacks over non-secure channels, such as HTTP. The server tracks the expiry timestamp you have specified and rejects all the subsequent API requests that come in after this validity period. To enable this feature, add the following parameters to the API request: - + signatureVersion=3: If the signatureVersion parameter is missing or is not equal to 3, the expires parameter is ignored in the API request. - + expires=YYYY-MM-DDThh:mm:ssZ: Specifies the date and time at which the signature included in the request is expired. The timestamp is expressed in the YYYY-MM-DDThh:mm:ssZ format, as specified in the ISO 8601 standard. For example: - expires=2011-10-10T12:00:00+0530 + expires=2011-10-10T12:00:00+0530 A sample API request with expiration is given below: - http://<IPAddress>:8080/client/api?command=listZones&signatureVersion=3&expires=2011-10-10T12:00:00+0530&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3DSigning API Requests4.3. Signing API Requests + http://<IPAddress>:8080/client/api?command=listZones&signatureVersion=3&expires=2011-10-10T12:00:00+0530&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3DSigning API Requests4.3. Signing API Requests Whether you access the CloudStack API with HTTP or HTTPS, it must still be signed so that CloudStack can verify the caller has been authenticated and authorized to execute the command. Make sure that you have both the API Key and Secret Key provided by the CloudStack administrator for your account before proceeding with the signing process. To show how to sign a request, we will re-use the previous example. - http://http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D + http://http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D Breaking this down, we have several distinct parts to this URL. - + Base URL: This is the base URL to the CloudStack Management Server. - http://localhost:8080 + http://localhost:8080 API Path: This is the path to the API Servlet that processes the incoming requests. - /client/api? + /client/api? Command String: This part of the query string comprises of the command, its parameters, and the API Key that identifies the account. - Note + Note As with all query string parameters of field-value pairs, the "field" component is case insensitive while all "value" values are case sensitive. - command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ + command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ Signature: This is the hashed signature of the Base URL that is generated using a combination of the user’s Secret Key and the HMAC SHA-1 hashing algorithm. &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D @@ -1360,21 +1360,21 @@ Every API request has the format Base URL+API Path+Command String+Signature. To generate the signature. - 1. + 1. For each field-value pair (as separated by a '&') in the Command String, URL encode each value so that it can be safely sent via HTTP GET. - Note + Note Make sure all spaces are encoded as "%20" rather than "+". - 2. + 2. Lower case the entire Command String and sort it alphabetically via the field for each field-value pair. The result of this step would look like the following. - apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=43. + apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=43. Take the sorted Command String and run it through the HMAC SHA-1 hashing algorithm (most programming languages offer a utility method to do this) with the user’s Secret Key. Base64 encode the resulting byte array in UTF-8 so that it can be safely transmitted via HTTP. The final string produced after Base64 encoding should be "Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D". By reconstructing the final URL in the format Base URL+API Path+Command String+Signature, the final URL should look like: - http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3DResponses4.4. ResponsesResponse Formats: XML and JSON4.4.1. Response Formats: XML and JSON + http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3DResponses4.4. ResponsesResponse Formats: XML and JSON4.4.1. Response Formats: XML and JSON CloudStack supports two formats as the response to an API call. The default response is XML. If you would like the response to be in JSON, add &response=json to the Command String. Sample XML Response: - + <listipaddressesresponse> <allocatedipaddress> <ipaddress>192.168.10.141</ipaddress> @@ -1386,7 +1386,7 @@ </listipaddressesresponse> Sample JSON Response: - + { "listipaddressesresponse" : { "allocatedipaddress" : [ @@ -1406,9 +1406,9 @@ The default page size limit can be different for each cloud. It is set in the global configuration parameter default.page.size. If your cloud has many users with lots of VMs, you might need to increase the value of this parameter. At the same time, be careful not to set it so high that your site can be taken down by an enormous return from an API call. For more information about how to set global configuration parameters, see "Describe Your Deployment" in the Installation Guide. To decrease the page size limit for an individual API command, override the global setting with the page and pagesize parameters, which are available in any list* command (listCapabilities, listDiskOfferings, etc.). - + Both parameters must be specified together. - + The value of the pagesize parameter must be smaller than the value of default.page.size. That is, you can not increase the number of possible items in a result page, only decrease it. For syntax information on the list* commands, see the API Reference. @@ -1418,39 +1418,39 @@ An HTTP error code of 401 is always returned if API request was rejected due to bad signatures, missing API Keys, or the user simply did not have the permissions to execute the command. Asynchronous Commands4.5. Asynchronous Commands Asynchronous commands were introduced in CloudStack 2.x. Commands are designated as asynchronous when they can potentially take a long period of time to complete such as creating a snapshot or disk volume. They differ from synchronous commands by the following: - + They are identified in the API Reference by an (A). - + They will immediately return a job ID to refer to the job that will be responsible in processing the command. - + If executed as a "create" resource command, it will return the resource ID as well as the job ID. You can periodically check the status of the job by making a simple API call to the command, queryAsyncJobResult and passing in the job ID. Job Status4.5.1. Job Status The key to using an asynchronous command is the job ID that is returned immediately once the command has been executed. With the job ID, you can periodically check the job status by making calls to queryAsyncJobResult command. The command will return three possible job status integer values: - + 0 - Job is still in progress. Continue to periodically poll for any status changes. - + 1 - Job has successfully completed. The job will return any successful response values associated with command that was originally executed. - + 2 - Job has failed to complete. Please check the "jobresultcode" tag for failure reason code and "jobresult" for the failure reason. Example4.5.2. Example The following shows an example of using an asynchronous command. Assume the API command: - command=deployVirtualMachine&zoneId=1&serviceOfferingId=1&diskOfferingId=1&templateId=1 + command=deployVirtualMachine&zoneId=1&serviceOfferingId=1&diskOfferingId=1&templateId=1 CloudStack will immediately return a job ID and any other additional data. - + <deployvirtualmachineresponse> <jobid>1</jobid> <id>100</id> </deployvirtualmachineresponse> Using the job ID, you can periodically poll for the results by using the queryAsyncJobResult command. - command=queryAsyncJobResult&jobId=1 + command=queryAsyncJobResult&jobId=1 Three possible results could come from this query. Job is still pending: - + <queryasyncjobresult> <jobid>1</jobid> <jobstatus>0</jobstatus> @@ -1458,7 +1458,7 @@ </queryasyncjobresult> Job has succeeded: - + <queryasyncjobresultresponse cloud-stack-version="3.0.1.6"> <jobid>1</jobid> <jobstatus>1</jobstatus> @@ -1510,7 +1510,7 @@ </queryasyncjobresultresponse> Job has failed: - + <queryasyncjobresult> <jobid>1</jobid> <jobstatus>2</jobstatus> @@ -1527,215 +1527,215 @@ The Usage Server runs at least once per day. It can be configured to run multiple times per day. Its behavior is controlled by configuration settings as described in the CloudStack Administration Guide. Usage Record Format5.1. Usage Record FormatVirtual Machine Usage Record Format5.1.1. Virtual Machine Usage Record Format For running and allocated virtual machine usage, the following fields exist in a usage record: - + account – name of the account - + accountid – ID of the account - + domainid – ID of the domain in which this account resides - + zoneid – Zone where the usage occurred - + description – A string describing what the usage record is tracking - + usage – String representation of the usage, including the units of usage (e.g. 'Hrs' for VM running time) - + usagetype – A number representing the usage type (see Usage Types) - + rawusage – A number representing the actual usage in hours - + virtualMachineId – The ID of the virtual machine - + name – The name of the virtual machine - + offeringid – The ID of the service offering - + templateid – The ID of the template or the ID of the parent template. The parent template value is present when the current template was created from a volume. - + usageid – Virtual machine - + type – Hypervisor - + startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record Network Usage Record Format5.1.2. Network Usage Record Format For network usage (bytes sent/received), the following fields exist in a usage record. - + account – name of the account - + accountid – ID of the account - + domainid – ID of the domain in which this account resides - + zoneid – Zone where the usage occurred - + description – A string describing what the usage record is tracking - + usagetype – A number representing the usage type (see Usage Types) - + rawusage – A number representing the actual usage in hours - + usageid – Device ID (virtual router ID or external device ID) - + type – Device type (domain router, external load balancer, etc.) - + startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record IP Address Usage Record Format5.1.3. IP Address Usage Record Format For IP address usage the following fields exist in a usage record. - + account - name of the account - + accountid - ID of the account - + domainid - ID of the domain in which this account resides - + zoneid - Zone where the usage occurred - + description - A string describing what the usage record is tracking - + usage - String representation of the usage, including the units of usage - + usagetype - A number representing the usage type (see Usage Types) - + rawusage - A number representing the actual usage in hours - + usageid - IP address ID - + startdate, enddate - The range of time for which the usage is aggregated; see Dates in the Usage Record - + issourcenat - Whether source NAT is enabled for the IP address - + iselastic - True if the IP address is elastic. Disk Volume Usage Record Format5.1.4. Disk Volume Usage Record Format For disk volumes, the following fields exist in a usage record. - + account – name of the account - + accountid – ID of the account - + domainid – ID of the domain in which this account resides - + zoneid – Zone where the usage occurred - + description – A string describing what the usage record is tracking - + usage – String representation of the usage, including the units of usage (e.g. 'Hrs' for hours) - + usagetype – A number representing the usage type (see Usage Types) - + rawusage – A number representing the actual usage in hours - + usageid – The volume ID - + offeringid – The ID of the disk offering - + type – Hypervisor - + templateid – ROOT template ID - + size – The amount of storage allocated - + startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record - Template, ISO, and Snapshot Usage Record Format5.1.5. Template, ISO, and Snapshot Usage Record Format + Template, ISO, and Snapshot Usage Record Format5.1.5. Template, ISO, and Snapshot Usage Record Format account – name of the account - + accountid – ID of the account - + domainid – ID of the domain in which this account resides - + zoneid – Zone where the usage occurred - + description – A string describing what the usage record is tracking - + usage – String representation of the usage, including the units of usage (e.g. 'Hrs' for hours) - + usagetype – A number representing the usage type (see Usage Types) - + rawusage – A number representing the actual usage in hours - + usageid – The ID of the the template, ISO, or snapshot - + offeringid – The ID of the disk offering - + templateid – – Included only for templates (usage type 7). Source template ID. - + size – Size of the template, ISO, or snapshot - + startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record - Load Balancer Policy or Port Forwarding Rule Usage Record Format5.1.6. Load Balancer Policy or Port Forwarding Rule Usage Record Format + Load Balancer Policy or Port Forwarding Rule Usage Record Format5.1.6. Load Balancer Policy or Port Forwarding Rule Usage Record Format account - name of the account - + accountid - ID of the account - + domainid - ID of the domain in which this account resides - + zoneid - Zone where the usage occurred - + description - A string describing what the usage record is tracking - + usage - String representation of the usage, including the units of usage (e.g. 'Hrs' for hours) - + usagetype - A number representing the usage type (see Usage Types) - + rawusage - A number representing the actual usage in hours - + usageid - ID of the load balancer policy or port forwarding rule - + usagetype - A number representing the usage type (see Usage Types) - + startdate, enddate - The range of time for which the usage is aggregated; see Dates in the Usage Record - Network Offering Usage Record Format5.1.7. Network Offering Usage Record Format + Network Offering Usage Record Format5.1.7. Network Offering Usage Record Format account – name of the account - + accountid – ID of the account - + domainid – ID of the domain in which this account resides - + zoneid – Zone where the usage occurred - + description – A string describing what the usage record is tracking - + usage – String representation of the usage, including the units of usage (e.g. 'Hrs' for hours) - + usagetype – A number representing the usage type (see Usage Types) - + rawusage – A number representing the actual usage in hours - + usageid – ID of the network offering - + usagetype – A number representing the usage type (see Usage Types) - + offeringid – Network offering ID - + virtualMachineId – The ID of the virtual machine - + virtualMachineId – The ID of the virtual machine - + startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record - VPN User Usage Record Format5.1.8. VPN User Usage Record Format + VPN User Usage Record Format5.1.8. VPN User Usage Record Format account – name of the account - + accountid – ID of the account - + domainid – ID of the domain in which this account resides - + zoneid – Zone where the usage occurred - + description – A string describing what the usage record is tracking - + usage – String representation of the usage, including the units of usage (e.g. 'Hrs' for hours) - + usagetype – A number representing the usage type (see Usage Types) - + rawusage – A number representing the actual usage in hours - + usageid – VPN user ID - + usagetype – A number representing the usage type (see Usage Types) - + startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record Usage Types5.2. Usage Types The following table shows all usage types. - + Type ID Type Name @@ -1893,7 +1893,7 @@ Example response from listUsageRecords5.3. Example response from listUsageRecords All CloudStack API requests are submitted in the form of a HTTP GET/POST with an associated command and any parameters. A request is composed of the following whether in HTTP or HTTPS: - + <listusagerecordsresponse> <count>1816</count> <usagerecord> @@ -1925,7 +1925,7 @@ For network usage, the start date and end date again define the range in which the number of bytes transferred was calculated. If a user downloads 10 MB and uploads 1 MB in one day, there will be two records, one showing the 10 megabytes received and one showing the 1 megabyte sent. There is one case where the start date and end date do not correspond to midnight and 11:59:59pm when daily aggregation is used. This occurs only for network usage records. When the usage server has more than one day's worth of unprocessed data, the old data will be included in the aggregation period. The start date in the usage record will show the date and time of the earliest event. For other types of usage, such as IP addresses and VMs, the old unprocessed data is not included in daily aggregation. - Appendix A. Event TypesAppendix A. Event Types + Appendix A. Event TypesAppendix A. Event Types VM.CREATE @@ -2370,9 +2370,9 @@ Appendix B. AlertsAppendix B. Alerts The following is the list of alert type numbers. The current alerts can be found by calling listAlerts. - MEMORY = 0CPU = 1STORAGE =2STORAGE_ALLOCATED = 3PUBLIC_IP = 4PRIVATE_IP = 5HOST = 6USERVM = 7DOMAIN_ROUTER = 8CONSOLE_PROXY = 9ROUTING = 10// lost connection to default route (to the gateway)STORAGE_MISC = 11 // lost connection to default route (to the gateway)USAGE_SERVER = 12 // lost connection to default route (to the gateway)MANAGMENT_NODE = 13 // lost connection to default route (to the gateway)DOMAIN_ROUTER_MIGRATE = 14CONSOLE_PROXY_MIGRATE = 15USERVM_MIGRATE = 16VLAN = 17SSVM = 18USAGE_SERVER_RESULT = 19STORAGE_DELETE = 20;UPDATE_RESOURCE_COUNT = 21; //Generated when we fail to update the resource countUSAGE_SANITY_RESULT = 22;DIRECT_ATTACHED_PUBLIC_IP = 23;LOCAL_STORAGE = 24;RESOURCE_LIMIT_EXCEEDED = 25; //Generated when the resource limit exceeds the limit. Currently used for recurring snapshots onlyAppendix C. Time ZonesAppendix C. Time Zones + MEMORY = 0CPU = 1STORAGE =2STORAGE_ALLOCATED = 3PUBLIC_IP = 4PRIVATE_IP = 5HOST = 6USERVM = 7DOMAIN_ROUTER = 8CONSOLE_PROXY = 9ROUTING = 10// lost connection to default route (to the gateway)STORAGE_MISC = 11 // lost connection to default route (to the gateway)USAGE_SERVER = 12 // lost connection to default route (to the gateway)MANAGMENT_NODE = 13 // lost connection to default route (to the gateway)DOMAIN_ROUTER_MIGRATE = 14CONSOLE_PROXY_MIGRATE = 15USERVM_MIGRATE = 16VLAN = 17SSVM = 18USAGE_SERVER_RESULT = 19STORAGE_DELETE = 20;UPDATE_RESOURCE_COUNT = 21; //Generated when we fail to update the resource countUSAGE_SANITY_RESULT = 22;DIRECT_ATTACHED_PUBLIC_IP = 23;LOCAL_STORAGE = 24;RESOURCE_LIMIT_EXCEEDED = 25; //Generated when the resource limit exceeds the limit. Currently used for recurring snapshots onlyAppendix C. Time ZonesAppendix C. Time Zones The following time zone identifiers are accepted by CloudStack. There are several places that have a time zone as a required or optional parameter. These include scheduling recurring snapshots, creating a user, and specifying the usage time zone in the Configuration table. - + Etc/GMT+12 @@ -2613,7 +2613,7 @@ Appendix D. Revision HistoryAppendix D. Revision History Revision 0-0Tue May 29 2012Jessica Tomechak - Initial creation of book by publican + Initial creation of book by publican diff --git a/docs/tmp/en-US/xml/Admin_Guide.fo b/docs/tmp/en-US/xml/Admin_Guide.fo index c959329b712..583fedfa683 100644 --- a/docs/tmp/en-US/xml/Admin_Guide.fo +++ b/docs/tmp/en-US/xml/Admin_Guide.fo @@ -1,8 +1,8 @@ -CloudStack Administrator's GuideDocBook XSL Stylesheets with Apache FOPCloudStack Administrator's GuideTable of ContentsChapter 1. Concepts1.1. What Is CloudStack?1.2. What Can CloudStack Do?1.3. Deployment Architecture Overview1.3.1. Management Server Overview1.3.2. Cloud Infrastructure Overview1.3.3. Networking OverviewChapter 2. Cloud Infrastructure Concepts2.1. About Zones2.2. About Pods2.3. About Clusters2.4. About Hosts2.5. About Primary Storage2.6. About Secondary Storage2.7. About Physical Networks2.7.1. Configurable Characteristics of Physical Networks2.7.2. Basic Zone Network Traffic Types2.7.3. Basic Zone Guest IP Addresses2.7.4. Advanced Zone Network Traffic Types2.7.5. Advanced Zone Guest IP Addresses2.7.6. Advanced Zone Public IP Addresses2.7.7. System Reserved IP AddressesChapter 3. Accounts3.1. Accounts, Users, and Domains3.2. Using an LDAP Server for User Authentication3.2.1. Example LDAP Configuration Commands3.2.2. Search Base3.2.3. Query Filter3.2.4. Search User Bind DN3.2.5. SSL Keystore Path and PasswordChapter 4. User Services Overview4.1. Service Offerings, Disk Offerings, Network Offerings, and TemplatesChapter 5. User Interface5.1. Log In to the UI5.1.1. End User's UI Overview5.1.2. Root Administrator's UI Overview5.1.3. Logging In as the Root Administrator5.1.4. Changing the Root Password5.2. Using SSH Keys for Authentication5.2.1.  Creating an Instance Template that Supports SSH Keys5.2.2. Creating the SSH Keypair5.2.3. Creating an Instance5.2.4. Logging In Using the SSH KeypairChapter 6. Using Projects to Organize Users and Resources6.1. Overview of Projects6.2. Configuring Projects6.2.1. Setting Up Invitations6.2.2. Setting Resource Limits for Projects6.2.2.1. Setting Per-Project Resource Limits6.2.2.2. Setting the Global Project Resource Limits6.2.3. Setting Project Creator Permissions6.3. Creating a New Project6.4. Adding Members to a Project6.4.1. Sending Project Membership Invitations6.4.2. Adding Project Members From the UI6.5. Accepting a Membership Invitation6.6. Suspending or Deleting a Project6.7. Using the Project ViewChapter 7. Steps to Provisioning Your Cloud Infrastructure7.1. Overview of Provisioning Steps7.2. Adding a Zone7.2.1. Basic Zone Configuration7.2.2. Advanced Zone Configuration7.3. Adding a Pod7.4. Adding a Cluster7.4.1. Add Cluster: KVM or XenServer7.4.2. Add Cluster: vSphere7.5. Adding a Host7.5.1. Adding a Host (XenServer or KVM)7.5.1.1. Requirements for XenServer and KVM Hosts7.5.1.1.1. XenServer Host Additional Requirements7.5.1.1.2. KVM Host Additional Requirements7.5.1.2. Adding a XenServer or KVM Host7.5.2. Adding a Host (vSphere)7.6. Add Primary Storage7.6.1. System Requirements for Primary Storage7.6.2. Adding Primary Stroage7.7. Add Secondary Storage7.7.1. System Requirements for Secondary Storage7.7.2. Adding Secondary Storage7.8. Initialize and TestChapter 8. Service Offerings8.1. Compute and Disk Service Offerings8.1.1. Creating a New Compute Offering8.1.2. Creating a New Disk Offering8.1.3. Modifying or Deleting a Service Offering8.2. System Service OfferingsChapter 9. Setting Up Networking for Users9.1. Overview of Setting Up Networking for Users9.2. About Virtual Networks9.2.1. Isolated Networks9.2.2. Shared Networks9.2.3. Runtime Allocation of Virtual Network Resources9.3. Network Service Providers9.4. Network OfferingsChapter 10. Working With Virtual Machines10.1. About Working with Virtual Machines10.2. Best Practices for Virtual Machines10.3. VM Lifecycle10.4. Creating VMs10.5. Accessing VMs10.6. Stopping and Starting VMs10.7. Changing the VM Name, OS, or Group10.8. Changing the Service Offering for a VM10.9. Moving VMs Between Hosts (Manual Live Migration)10.10. Deleting VMs10.11. Working with ISOs10.11.1. Adding an ISO10.11.2. Attaching an ISO to a VMChapter 11. Working With Hosts11.1. Adding Hosts11.2. Scheduled Maintenance and Maintenance Mode for Hosts11.3. Disabling and Enabling Zones, Pods, and Clusters11.4. Removing Hosts11.4.1. Removing XenServer and KVM Hosts11.4.2. Removing vSphere Hosts11.5. Re-Installing Hosts11.6. Maintaining Hypervisors on Hosts11.7. Changing Host Password11.8. Host Allocation11.9. VLAN ProvisioningChapter 12. Working with Templates12.1. Creating Templates: Overview12.2. Requirements for Templates12.3. Best Practices for Templates12.4. The Default Template12.5. Private and Public Templates12.6. Creating a Template from an Existing Virtual Machine12.7. Creating a Template from a Snapshot12.8. Uploading Templates12.9. Exporting Templates12.10. Creating a Windows Template12.10.1. System Preparation for Windows Server 2008 R212.10.2. Sysprep for Windows Server 2003 R212.11. Importing Amazon Machine Images12.12. Converting a Hyper-V VM to a Template12.13. Adding Password Management to Your Templates12.13.1. Linux OS Installation12.13.2. Windows OS Installation12.14. Deleting TemplatesChapter 13. Working With Storage13.1. Storage Overview13.2. Primary Storage13.2.1. Best Practices for Primary Storage13.2.2. Runtime Behavior of Primary Storage13.2.3. Hypervisor Support for Primary Storage13.2.4. Storage Tags13.2.5. Maintenance Mode for Primary Storage13.3. Secondary Storage13.4. Using Swift for Secondary Storage13.5. Working with SnapshotsChapter 14. Working with Usage14.1. Configuring the Usage Server14.2. Setting Usage Limits14.3. Globally Configured Limits14.4. Default Account Resource Limits14.5. Per-Domain LimitsChapter 15. Managing Networks and Traffic15.1. Guest Traffic15.2. Networking in a Pod15.3. Networking in a Zone15.4. Basic Zone Physical Network Configuration15.5. Advanced Zone Physical Network Configuration15.5.1. Configure Guest Traffic in an Advanced Zone15.5.2. Configure Public Traffic in an Advanced Zone15.6. Using Multiple Guest Networks15.6.1. Adding an Additional Guest Network15.6.2. Changing the Network Offering on a Guest Network15.7. Security Groups15.7.1. About Security Groups15.7.2. Adding a Security Group15.7.3. Enabling Security Groups15.7.4. Adding Ingress and Egress Rules to a Security Group15.8. External Firewalls and Load Balancers15.9. Load Balancer Rules15.10. Guest IP Ranges15.11. Acquiring a New IP Address15.12. Releasing an IP Address15.13. Static NAT15.14. IP Forwarding and Firewalling15.15. IP Load Balancing15.16. DNS and DHCP15.17. VPN15.17.1. Configuring VPN15.17.2. Using VPN with Windows15.17.3. Using VPN with Mac OS X15.17.4. Setting Up a Site-to-Site VPN Connection15.17.4.1. Creating and Updating a VPN Customer Gateway15.17.4.2. Creating a VPN gateway for the VPC15.17.4.3. Creating a VPN Connection15.17.4.4. Restarting and Removing a VPN Connection15.18. About Inter-VLAN Routing15.19. Configuring a Virtual Private Cloud15.19.1. About Virtual Private Clouds15.19.2. Adding a Virtual Private Cloud15.19.3. Adding Tiers15.19.4. Configuring Access Control List15.19.5. Adding a Private Gateway to a VPC15.19.6. Deploying VMs to the Tier15.19.7. Acquiring a New IP Address for a VPC15.19.8. Releasing an IP Address Alloted to a VPC15.19.9. Enabling or Disabling Static NAT on a VPC15.19.10. Adding Load Balancing Rules on a VPC15.19.11. Adding a Port Forwarding Rule on a VPC15.19.12. Removing Tiers15.19.13. Editing, Restarting, and Removing a Virtual Private CloudChapter 16. Working with System Virtual Machines16.1. The System VM Template16.2. Multiple System VM Support for VMware16.3. Console Proxy16.4. Virtual Router16.5. Secondary Storage VMChapter 17. System Reliability and High Availability17.1. HA for Management Server17.2. HA-Enabled Virtual Machines17.3. HA for Hosts17.4. Primary Storage Outage and Data Loss17.5. Secondary Storage Outage and Data LossChapter 18. Managing the Cloud18.1. Using Tags to Organize Resources in the Cloud18.2. Changing the Database Configuration18.3. Administrator Alerts18.4. Customizing the Network Domain Name18.5. Stopping and Restarting the Management ServerChapter 19. Setting Global Configuration ParametersChapter 20. CloudStack API20.1. Provisioning and Authentication API20.2. Allocators20.3. User Data and Meta DataChapter 21. Tuning21.1. Performance Monitoring21.2. Increase Management Server Maximum Memory21.3. Set Database Buffer Pool Size21.4. Set and Monitor Total VM Limits per Host21.5. Configure XenServer dom0 MemoryChapter 22. Troubleshooting22.1. Events22.1.1. Event Logs22.1.2. Standard Events22.1.3. Long Running Job Events22.1.4. Event Log Queries22.2. Working with Server Logs22.3. Data Loss on Exported Primary Storage22.4. Recovering a Lost Virtual Router22.5. Maintenance mode not working on vCenter22.6. Unable to deploy VMs from uploaded vSphere template22.7. Unable to power on virtual machine on VMware22.8. Load balancer rules fail after changing network offeringAppendix A. Time ZonesAppendix B. Event TypesAppendix C. AlertsAppendix D. Revision HistoryCloudStack Administrator's GuideApache CloudStack 4.0.0-incubatingCloudStack Administrator's Guide +CloudStack Administrator's GuideDocBook XSL Stylesheets with Apache FOPCloudStack Administrator's GuideTable of ContentsChapter 1. Concepts1.1. What Is CloudStack?1.2. What Can CloudStack Do?1.3. Deployment Architecture Overview1.3.1. Management Server Overview1.3.2. Cloud Infrastructure Overview1.3.3. Networking OverviewChapter 2. Cloud Infrastructure Concepts2.1. About Zones2.2. About Pods2.3. About Clusters2.4. About Hosts2.5. About Primary Storage2.6. About Secondary Storage2.7. About Physical Networks2.7.1. Configurable Characteristics of Physical Networks2.7.2. Basic Zone Network Traffic Types2.7.3. Basic Zone Guest IP Addresses2.7.4. Advanced Zone Network Traffic Types2.7.5. Advanced Zone Guest IP Addresses2.7.6. Advanced Zone Public IP Addresses2.7.7. System Reserved IP AddressesChapter 3. Accounts3.1. Accounts, Users, and Domains3.2. Using an LDAP Server for User Authentication3.2.1. Example LDAP Configuration Commands3.2.2. Search Base3.2.3. Query Filter3.2.4. Search User Bind DN3.2.5. SSL Keystore Path and PasswordChapter 4. User Services Overview4.1. Service Offerings, Disk Offerings, Network Offerings, and TemplatesChapter 5. User Interface5.1. Log In to the UI5.1.1. End User's UI Overview5.1.2. Root Administrator's UI Overview5.1.3. Logging In as the Root Administrator5.1.4. Changing the Root Password5.2. Using SSH Keys for Authentication5.2.1.  Creating an Instance Template that Supports SSH Keys5.2.2. Creating the SSH Keypair5.2.3. Creating an Instance5.2.4. Logging In Using the SSH KeypairChapter 6. Using Projects to Organize Users and Resources6.1. Overview of Projects6.2. Configuring Projects6.2.1. Setting Up Invitations6.2.2. Setting Resource Limits for Projects6.2.2.1. Setting Per-Project Resource Limits6.2.2.2. Setting the Global Project Resource Limits6.2.3. Setting Project Creator Permissions6.3. Creating a New Project6.4. Adding Members to a Project6.4.1. Sending Project Membership Invitations6.4.2. Adding Project Members From the UI6.5. Accepting a Membership Invitation6.6. Suspending or Deleting a Project6.7. Using the Project ViewChapter 7. Steps to Provisioning Your Cloud Infrastructure7.1. Overview of Provisioning Steps7.2. Adding a Zone7.2.1. Basic Zone Configuration7.2.2. Advanced Zone Configuration7.3. Adding a Pod7.4. Adding a Cluster7.4.1. Add Cluster: KVM or XenServer7.4.2. Add Cluster: vSphere7.5. Adding a Host7.5.1. Adding a Host (XenServer or KVM)7.5.1.1. Requirements for XenServer and KVM Hosts7.5.1.1.1. XenServer Host Additional Requirements7.5.1.1.2. KVM Host Additional Requirements7.5.1.2. Adding a XenServer or KVM Host7.5.2. Adding a Host (vSphere)7.6. Add Primary Storage7.6.1. System Requirements for Primary Storage7.6.2. Adding Primary Stroage7.7. Add Secondary Storage7.7.1. System Requirements for Secondary Storage7.7.2. Adding Secondary Storage7.8. Initialize and TestChapter 8. Service Offerings8.1. Compute and Disk Service Offerings8.1.1. Creating a New Compute Offering8.1.2. Creating a New Disk Offering8.1.3. Modifying or Deleting a Service Offering8.2. System Service OfferingsChapter 9. Setting Up Networking for Users9.1. Overview of Setting Up Networking for Users9.2. About Virtual Networks9.2.1. Isolated Networks9.2.2. Shared Networks9.2.3. Runtime Allocation of Virtual Network Resources9.3. Network Service Providers9.4. Network OfferingsChapter 10. Working With Virtual Machines10.1. About Working with Virtual Machines10.2. Best Practices for Virtual Machines10.3. VM Lifecycle10.4. Creating VMs10.5. Accessing VMs10.6. Stopping and Starting VMs10.7. Changing the VM Name, OS, or Group10.8. Changing the Service Offering for a VM10.9. Moving VMs Between Hosts (Manual Live Migration)10.10. Deleting VMs10.11. Working with ISOs10.11.1. Adding an ISO10.11.2. Attaching an ISO to a VMChapter 11. Working With Hosts11.1. Adding Hosts11.2. Scheduled Maintenance and Maintenance Mode for Hosts11.3. Disabling and Enabling Zones, Pods, and Clusters11.4. Removing Hosts11.4.1. Removing XenServer and KVM Hosts11.4.2. Removing vSphere Hosts11.5. Re-Installing Hosts11.6. Maintaining Hypervisors on Hosts11.7. Changing Host Password11.8. Host Allocation11.9. VLAN ProvisioningChapter 12. Working with Templates12.1. Creating Templates: Overview12.2. Requirements for Templates12.3. Best Practices for Templates12.4. The Default Template12.5. Private and Public Templates12.6. Creating a Template from an Existing Virtual Machine12.7. Creating a Template from a Snapshot12.8. Uploading Templates12.9. Exporting Templates12.10. Creating a Windows Template12.10.1. System Preparation for Windows Server 2008 R212.10.2. Sysprep for Windows Server 2003 R212.11. Importing Amazon Machine Images12.12. Converting a Hyper-V VM to a Template12.13. Adding Password Management to Your Templates12.13.1. Linux OS Installation12.13.2. Windows OS Installation12.14. Deleting TemplatesChapter 13. Working With Storage13.1. Storage Overview13.2. Primary Storage13.2.1. Best Practices for Primary Storage13.2.2. Runtime Behavior of Primary Storage13.2.3. Hypervisor Support for Primary Storage13.2.4. Storage Tags13.2.5. Maintenance Mode for Primary Storage13.3. Secondary Storage13.4. Using Swift for Secondary Storage13.5. Working with SnapshotsChapter 14. Working with Usage14.1. Configuring the Usage Server14.2. Setting Usage Limits14.3. Globally Configured Limits14.4. Default Account Resource Limits14.5. Per-Domain LimitsChapter 15. Managing Networks and Traffic15.1. Guest Traffic15.2. Networking in a Pod15.3. Networking in a Zone15.4. Basic Zone Physical Network Configuration15.5. Advanced Zone Physical Network Configuration15.5.1. Configure Guest Traffic in an Advanced Zone15.5.2. Configure Public Traffic in an Advanced Zone15.6. Using Multiple Guest Networks15.6.1. Adding an Additional Guest Network15.6.2. Changing the Network Offering on a Guest Network15.7. Security Groups15.7.1. About Security Groups15.7.2. Adding a Security Group15.7.3. Enabling Security Groups15.7.4. Adding Ingress and Egress Rules to a Security Group15.8. External Firewalls and Load Balancers15.9. Load Balancer Rules15.10. Guest IP Ranges15.11. Acquiring a New IP Address15.12. Releasing an IP Address15.13. Static NAT15.14. IP Forwarding and Firewalling15.15. IP Load Balancing15.16. DNS and DHCP15.17. VPN15.17.1. Configuring VPN15.17.2. Using VPN with Windows15.17.3. Using VPN with Mac OS X15.17.4. Setting Up a Site-to-Site VPN Connection15.17.4.1. Creating and Updating a VPN Customer Gateway15.17.4.2. Creating a VPN gateway for the VPC15.17.4.3. Creating a VPN Connection15.17.4.4. Restarting and Removing a VPN Connection15.18. About Inter-VLAN Routing15.19. Configuring a Virtual Private Cloud15.19.1. About Virtual Private Clouds15.19.2. Adding a Virtual Private Cloud15.19.3. Adding Tiers15.19.4. Configuring Access Control List15.19.5. Adding a Private Gateway to a VPC15.19.6. Deploying VMs to the Tier15.19.7. Acquiring a New IP Address for a VPC15.19.8. Releasing an IP Address Alloted to a VPC15.19.9. Enabling or Disabling Static NAT on a VPC15.19.10. Adding Load Balancing Rules on a VPC15.19.11. Adding a Port Forwarding Rule on a VPC15.19.12. Removing Tiers15.19.13. Editing, Restarting, and Removing a Virtual Private CloudChapter 16. Working with System Virtual Machines16.1. The System VM Template16.2. Multiple System VM Support for VMware16.3. Console Proxy16.4. Virtual Router16.5. Secondary Storage VMChapter 17. System Reliability and High Availability17.1. HA for Management Server17.2. HA-Enabled Virtual Machines17.3. HA for Hosts17.4. Primary Storage Outage and Data Loss17.5. Secondary Storage Outage and Data LossChapter 18. Managing the Cloud18.1. Using Tags to Organize Resources in the Cloud18.2. Changing the Database Configuration18.3. Administrator Alerts18.4. Customizing the Network Domain Name18.5. Stopping and Restarting the Management ServerChapter 19. Setting Global Configuration ParametersChapter 20. CloudStack API20.1. Provisioning and Authentication API20.2. Allocators20.3. User Data and Meta DataChapter 21. Tuning21.1. Performance Monitoring21.2. Increase Management Server Maximum Memory21.3. Set Database Buffer Pool Size21.4. Set and Monitor Total VM Limits per Host21.5. Configure XenServer dom0 MemoryChapter 22. Troubleshooting22.1. Events22.1.1. Event Logs22.1.2. Standard Events22.1.3. Long Running Job Events22.1.4. Event Log Queries22.2. Working with Server Logs22.3. Data Loss on Exported Primary Storage22.4. Recovering a Lost Virtual Router22.5. Maintenance mode not working on vCenter22.6. Unable to deploy VMs from uploaded vSphere template22.7. Unable to power on virtual machine on VMware22.8. Load balancer rules fail after changing network offeringAppendix A. Time ZonesAppendix B. Event TypesAppendix C. AlertsAppendix D. Revision HistoryCloudStack Administrator's GuideApache CloudStack 4.0.0-incubatingCloudStack Administrator's Guide - Apache CloudStackApache CloudStack 4.0.0-incubating CloudStack Administrator's GuideAuthorApache CloudStack + Apache CloudStackApache CloudStack 4.0.0-incubating CloudStack Administrator's GuideAuthorApache CloudStack 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 @@ -14,15 +14,15 @@ Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. Administration Guide for CloudStack. - CloudStack Administrator's Guide1. Concepts   1.1. What Is CloudStack? 1.2. What Can CloudStack Do? 1.3. Deployment Architecture Overview 1.3.1. Management Server Overview 1.3.2. Cloud Infrastructure Overview 1.3.3. Networking Overview 2. Cloud Infrastructure Concepts   2.1. About Zones 2.2. About Pods 2.3. About Clusters 2.4. About Hosts 2.5. About Primary Storage 2.6. About Secondary Storage 2.7. About Physical Networks 2.7.1. Configurable Characteristics of Physical Networks 2.7.2. Basic Zone Network Traffic Types 2.7.3. Basic Zone Guest IP Addresses 2.7.4. Advanced Zone Network Traffic Types 2.7.5. Advanced Zone Guest IP Addresses 2.7.6. Advanced Zone Public IP Addresses 2.7.7. System Reserved IP Addresses 3. Accounts   3.1. Accounts, Users, and Domains 3.2. Using an LDAP Server for User Authentication 3.2.1. Example LDAP Configuration Commands 3.2.2. Search Base 3.2.3. Query Filter 3.2.4. Search User Bind DN 3.2.5. SSL Keystore Path and Password 4. User Services Overview   4.1. Service Offerings, Disk Offerings, Network Offerings, and Templates 5. User Interface   5.1. Log In to the UI 5.1.1. End User's UI Overview 5.1.2. Root Administrator's UI Overview 5.1.3. Logging In as the Root Administrator 5.1.4. Changing the Root Password 5.2. Using SSH Keys for Authentication 5.2.1. Creating an Instance Template that Supports SSH Keys 5.2.2. Creating the SSH Keypair 5.2.3. Creating an Instance 5.2.4. Logging In Using the SSH Keypair 6. Using Projects to Organize Users and Resources   6.1. Overview of Projects 6.2. Configuring Projects 6.2.1. Setting Up Invitations 6.2.2. Setting Resource Limits for Projects 6.2.3. Setting Project Creator Permissions 6.3. Creating a New Project 6.4. Adding Members to a Project 6.4.1. Sending Project Membership Invitations 6.4.2. Adding Project Members From the UI 6.5. Accepting a Membership Invitation 6.6. Suspending or Deleting a Project 6.7. Using the Project View 7. Steps to Provisioning Your Cloud Infrastructure   7.1. Overview of Provisioning Steps 7.2. Adding a Zone 7.2.1. Basic Zone Configuration 7.2.2. Advanced Zone Configuration 7.3. Adding a Pod 7.4. Adding a Cluster 7.4.1. Add Cluster: KVM or XenServer 7.4.2. Add Cluster: vSphere 7.5. Adding a Host 7.5.1. Adding a Host (XenServer or KVM) 7.5.2. Adding a Host (vSphere) 7.6. Add Primary Storage 7.6.1. System Requirements for Primary Storage 7.6.2. Adding Primary Stroage 7.7. Add Secondary Storage 7.7.1. System Requirements for Secondary Storage 7.7.2. Adding Secondary Storage 7.8. Initialize and Test 8. Service Offerings   8.1. Compute and Disk Service Offerings 8.1.1. Creating a New Compute Offering 8.1.2. Creating a New Disk Offering 8.1.3. Modifying or Deleting a Service Offering 8.2. System Service Offerings 9. Setting Up Networking for Users   9.1. Overview of Setting Up Networking for Users 9.2. About Virtual Networks 9.2.1. Isolated Networks 9.2.2. Shared Networks 9.2.3. Runtime Allocation of Virtual Network Resources 9.3. Network Service Providers 9.4. Network Offerings 10. Working With Virtual Machines   10.1. About Working with Virtual Machines 10.2. Best Practices for Virtual Machines 10.3. VM Lifecycle 10.4. Creating VMs 10.5. Accessing VMs 10.6. Stopping and Starting VMs 10.7. Changing the VM Name, OS, or Group 10.8. Changing the Service Offering for a VM 10.9. Moving VMs Between Hosts (Manual Live Migration) 10.10. Deleting VMs 10.11. Working with ISOs 10.11.1. Adding an ISO 10.11.2. Attaching an ISO to a VM 11. Working With Hosts   11.1. Adding Hosts 11.2. Scheduled Maintenance and Maintenance Mode for Hosts 11.3. Disabling and Enabling Zones, Pods, and Clusters 11.4. Removing Hosts 11.4.1. Removing XenServer and KVM Hosts 11.4.2. Removing vSphere Hosts 11.5. Re-Installing Hosts 11.6. Maintaining Hypervisors on Hosts 11.7. Changing Host Password 11.8. Host Allocation 11.9. VLAN Provisioning 12. Working with Templates   12.1. Creating Templates: Overview 12.2. Requirements for Templates 12.3. Best Practices for Templates 12.4. The Default Template 12.5. Private and Public Templates 12.6. Creating a Template from an Existing Virtual Machine 12.7. Creating a Template from a Snapshot 12.8. Uploading Templates 12.9. Exporting Templates 12.10. Creating a Windows Template 12.10.1. System Preparation for Windows Server 2008 R2 12.10.2. Sysprep for Windows Server 2003 R2 12.11. Importing Amazon Machine Images 12.12. Converting a Hyper-V VM to a Template 12.13. Adding Password Management to Your Templates 12.13.1. Linux OS Installation 12.13.2. Windows OS Installation 12.14. Deleting Templates 13. Working With Storage   13.1. Storage Overview 13.2. Primary Storage 13.2.1. Best Practices for Primary Storage 13.2.2. Runtime Behavior of Primary Storage 13.2.3. Hypervisor Support for Primary Storage 13.2.4. Storage Tags 13.2.5. Maintenance Mode for Primary Storage 13.3. Secondary Storage 13.4. Using Swift for Secondary Storage 13.5. Working with Snapshots 14. Working with Usage   14.1. Configuring the Usage Server 14.2. Setting Usage Limits 14.3. Globally Configured Limits 14.4. Default Account Resource Limits 14.5. Per-Domain Limits 15. Managing Networks and Traffic   15.1. Guest Traffic 15.2. Networking in a Pod 15.3. Networking in a Zone 15.4. Basic Zone Physical Network Configuration 15.5. Advanced Zone Physical Network Configuration 15.5.1. Configure Guest Traffic in an Advanced Zone 15.5.2. Configure Public Traffic in an Advanced Zone 15.6. Using Multiple Guest Networks 15.6.1. Adding an Additional Guest Network 15.6.2. Changing the Network Offering on a Guest Network 15.7. Security Groups 15.7.1. About Security Groups 15.7.2. Adding a Security Group 15.7.3. Enabling Security Groups 15.7.4. Adding Ingress and Egress Rules to a Security Group 15.8. External Firewalls and Load Balancers 15.9. Load Balancer Rules 15.10. Guest IP Ranges 15.11. Acquiring a New IP Address 15.12. Releasing an IP Address 15.13. Static NAT 15.14. IP Forwarding and Firewalling 15.15. IP Load Balancing 15.16. DNS and DHCP 15.17. VPN 15.17.1. Configuring VPN 15.17.2. Using VPN with Windows 15.17.3. Using VPN with Mac OS X 15.17.4. Setting Up a Site-to-Site VPN Connection 15.18. About Inter-VLAN Routing 15.19. Configuring a Virtual Private Cloud 15.19.1. About Virtual Private Clouds 15.19.2. Adding a Virtual Private Cloud 15.19.3. Adding Tiers 15.19.4. Configuring Access Control List 15.19.5. Adding a Private Gateway to a VPC 15.19.6. Deploying VMs to the Tier 15.19.7. Acquiring a New IP Address for a VPC 15.19.8. Releasing an IP Address Alloted to a VPC 15.19.9. Enabling or Disabling Static NAT on a VPC 15.19.10. Adding Load Balancing Rules on a VPC 15.19.11. Adding a Port Forwarding Rule on a VPC 15.19.12. Removing Tiers 15.19.13. Editing, Restarting, and Removing a Virtual Private Cloud 16. Working with System Virtual Machines   16.1. The System VM Template 16.2. Multiple System VM Support for VMware 16.3. Console Proxy 16.4. Virtual Router 16.5. Secondary Storage VM 17. System Reliability and High Availability   17.1. HA for Management Server 17.2. HA-Enabled Virtual Machines 17.3. HA for Hosts 17.4. Primary Storage Outage and Data Loss 17.5. Secondary Storage Outage and Data Loss 18. Managing the Cloud   18.1. Using Tags to Organize Resources in the Cloud 18.2. Changing the Database Configuration 18.3. Administrator Alerts 18.4. Customizing the Network Domain Name 18.5. Stopping and Restarting the Management Server 19. Setting Global Configuration Parameters   20. CloudStack API   20.1. Provisioning and Authentication API 20.2. Allocators 20.3. User Data and Meta Data 21. Tuning   21.1. Performance Monitoring 21.2. Increase Management Server Maximum Memory 21.3. Set Database Buffer Pool Size 21.4. Set and Monitor Total VM Limits per Host 21.5. Configure XenServer dom0 Memory 22. Troubleshooting   22.1. Events 22.1.1. Event Logs 22.1.2. Standard Events 22.1.3. Long Running Job Events 22.1.4. Event Log Queries 22.2. Working with Server Logs 22.3. Data Loss on Exported Primary Storage 22.4. Recovering a Lost Virtual Router 22.5. Maintenance mode not working on vCenter 22.6. Unable to deploy VMs from uploaded vSphere template 22.7. Unable to power on virtual machine on VMware 22.8. Load balancer rules fail after changing network offering A. Time Zones   B. Event Types   C. Alerts   D. Revision History   Chapter 1.Chapter 1. ConceptsConceptsWhat Is CloudStack?1.1. What Is CloudStack? + CloudStack Administrator's Guide1. Concepts   1.1. What Is CloudStack? 1.2. What Can CloudStack Do? 1.3. Deployment Architecture Overview 1.3.1. Management Server Overview 1.3.2. Cloud Infrastructure Overview 1.3.3. Networking Overview 2. Cloud Infrastructure Concepts   2.1. About Zones 2.2. About Pods 2.3. About Clusters 2.4. About Hosts 2.5. About Primary Storage 2.6. About Secondary Storage 2.7. About Physical Networks 2.7.1. Configurable Characteristics of Physical Networks 2.7.2. Basic Zone Network Traffic Types 2.7.3. Basic Zone Guest IP Addresses 2.7.4. Advanced Zone Network Traffic Types 2.7.5. Advanced Zone Guest IP Addresses 2.7.6. Advanced Zone Public IP Addresses 2.7.7. System Reserved IP Addresses 3. Accounts   3.1. Accounts, Users, and Domains 3.2. Using an LDAP Server for User Authentication 3.2.1. Example LDAP Configuration Commands 3.2.2. Search Base 3.2.3. Query Filter 3.2.4. Search User Bind DN 3.2.5. SSL Keystore Path and Password 4. User Services Overview   4.1. Service Offerings, Disk Offerings, Network Offerings, and Templates 5. User Interface   5.1. Log In to the UI 5.1.1. End User's UI Overview 5.1.2. Root Administrator's UI Overview 5.1.3. Logging In as the Root Administrator 5.1.4. Changing the Root Password 5.2. Using SSH Keys for Authentication 5.2.1. Creating an Instance Template that Supports SSH Keys 5.2.2. Creating the SSH Keypair 5.2.3. Creating an Instance 5.2.4. Logging In Using the SSH Keypair 6. Using Projects to Organize Users and Resources   6.1. Overview of Projects 6.2. Configuring Projects 6.2.1. Setting Up Invitations 6.2.2. Setting Resource Limits for Projects 6.2.3. Setting Project Creator Permissions 6.3. Creating a New Project 6.4. Adding Members to a Project 6.4.1. Sending Project Membership Invitations 6.4.2. Adding Project Members From the UI 6.5. Accepting a Membership Invitation 6.6. Suspending or Deleting a Project 6.7. Using the Project View 7. Steps to Provisioning Your Cloud Infrastructure   7.1. Overview of Provisioning Steps 7.2. Adding a Zone 7.2.1. Basic Zone Configuration 7.2.2. Advanced Zone Configuration 7.3. Adding a Pod 7.4. Adding a Cluster 7.4.1. Add Cluster: KVM or XenServer 7.4.2. Add Cluster: vSphere 7.5. Adding a Host 7.5.1. Adding a Host (XenServer or KVM) 7.5.2. Adding a Host (vSphere) 7.6. Add Primary Storage 7.6.1. System Requirements for Primary Storage 7.6.2. Adding Primary Stroage 7.7. Add Secondary Storage 7.7.1. System Requirements for Secondary Storage 7.7.2. Adding Secondary Storage 7.8. Initialize and Test 8. Service Offerings   8.1. Compute and Disk Service Offerings 8.1.1. Creating a New Compute Offering 8.1.2. Creating a New Disk Offering 8.1.3. Modifying or Deleting a Service Offering 8.2. System Service Offerings 9. Setting Up Networking for Users   9.1. Overview of Setting Up Networking for Users 9.2. About Virtual Networks 9.2.1. Isolated Networks 9.2.2. Shared Networks 9.2.3. Runtime Allocation of Virtual Network Resources 9.3. Network Service Providers 9.4. Network Offerings 10. Working With Virtual Machines   10.1. About Working with Virtual Machines 10.2. Best Practices for Virtual Machines 10.3. VM Lifecycle 10.4. Creating VMs 10.5. Accessing VMs 10.6. Stopping and Starting VMs 10.7. Changing the VM Name, OS, or Group 10.8. Changing the Service Offering for a VM 10.9. Moving VMs Between Hosts (Manual Live Migration) 10.10. Deleting VMs 10.11. Working with ISOs 10.11.1. Adding an ISO 10.11.2. Attaching an ISO to a VM 11. Working With Hosts   11.1. Adding Hosts 11.2. Scheduled Maintenance and Maintenance Mode for Hosts 11.3. Disabling and Enabling Zones, Pods, and Clusters 11.4. Removing Hosts 11.4.1. Removing XenServer and KVM Hosts 11.4.2. Removing vSphere Hosts 11.5. Re-Installing Hosts 11.6. Maintaining Hypervisors on Hosts 11.7. Changing Host Password 11.8. Host Allocation 11.9. VLAN Provisioning 12. Working with Templates   12.1. Creating Templates: Overview 12.2. Requirements for Templates 12.3. Best Practices for Templates 12.4. The Default Template 12.5. Private and Public Templates 12.6. Creating a Template from an Existing Virtual Machine 12.7. Creating a Template from a Snapshot 12.8. Uploading Templates 12.9. Exporting Templates 12.10. Creating a Windows Template 12.10.1. System Preparation for Windows Server 2008 R2 12.10.2. Sysprep for Windows Server 2003 R2 12.11. Importing Amazon Machine Images 12.12. Converting a Hyper-V VM to a Template 12.13. Adding Password Management to Your Templates 12.13.1. Linux OS Installation 12.13.2. Windows OS Installation 12.14. Deleting Templates 13. Working With Storage   13.1. Storage Overview 13.2. Primary Storage 13.2.1. Best Practices for Primary Storage 13.2.2. Runtime Behavior of Primary Storage 13.2.3. Hypervisor Support for Primary Storage 13.2.4. Storage Tags 13.2.5. Maintenance Mode for Primary Storage 13.3. Secondary Storage 13.4. Using Swift for Secondary Storage 13.5. Working with Snapshots 14. Working with Usage   14.1. Configuring the Usage Server 14.2. Setting Usage Limits 14.3. Globally Configured Limits 14.4. Default Account Resource Limits 14.5. Per-Domain Limits 15. Managing Networks and Traffic   15.1. Guest Traffic 15.2. Networking in a Pod 15.3. Networking in a Zone 15.4. Basic Zone Physical Network Configuration 15.5. Advanced Zone Physical Network Configuration 15.5.1. Configure Guest Traffic in an Advanced Zone 15.5.2. Configure Public Traffic in an Advanced Zone 15.6. Using Multiple Guest Networks 15.6.1. Adding an Additional Guest Network 15.6.2. Changing the Network Offering on a Guest Network 15.7. Security Groups 15.7.1. About Security Groups 15.7.2. Adding a Security Group 15.7.3. Enabling Security Groups 15.7.4. Adding Ingress and Egress Rules to a Security Group 15.8. External Firewalls and Load Balancers 15.9. Load Balancer Rules 15.10. Guest IP Ranges 15.11. Acquiring a New IP Address 15.12. Releasing an IP Address 15.13. Static NAT 15.14. IP Forwarding and Firewalling 15.15. IP Load Balancing 15.16. DNS and DHCP 15.17. VPN 15.17.1. Configuring VPN 15.17.2. Using VPN with Windows 15.17.3. Using VPN with Mac OS X 15.17.4. Setting Up a Site-to-Site VPN Connection 15.18. About Inter-VLAN Routing 15.19. Configuring a Virtual Private Cloud 15.19.1. About Virtual Private Clouds 15.19.2. Adding a Virtual Private Cloud 15.19.3. Adding Tiers 15.19.4. Configuring Access Control List 15.19.5. Adding a Private Gateway to a VPC 15.19.6. Deploying VMs to the Tier 15.19.7. Acquiring a New IP Address for a VPC 15.19.8. Releasing an IP Address Alloted to a VPC 15.19.9. Enabling or Disabling Static NAT on a VPC 15.19.10. Adding Load Balancing Rules on a VPC 15.19.11. Adding a Port Forwarding Rule on a VPC 15.19.12. Removing Tiers 15.19.13. Editing, Restarting, and Removing a Virtual Private Cloud 16. Working with System Virtual Machines   16.1. The System VM Template 16.2. Multiple System VM Support for VMware 16.3. Console Proxy 16.4. Virtual Router 16.5. Secondary Storage VM 17. System Reliability and High Availability   17.1. HA for Management Server 17.2. HA-Enabled Virtual Machines 17.3. HA for Hosts 17.4. Primary Storage Outage and Data Loss 17.5. Secondary Storage Outage and Data Loss 18. Managing the Cloud   18.1. Using Tags to Organize Resources in the Cloud 18.2. Changing the Database Configuration 18.3. Administrator Alerts 18.4. Customizing the Network Domain Name 18.5. Stopping and Restarting the Management Server 19. Setting Global Configuration Parameters   20. CloudStack API   20.1. Provisioning and Authentication API 20.2. Allocators 20.3. User Data and Meta Data 21. Tuning   21.1. Performance Monitoring 21.2. Increase Management Server Maximum Memory 21.3. Set Database Buffer Pool Size 21.4. Set and Monitor Total VM Limits per Host 21.5. Configure XenServer dom0 Memory 22. Troubleshooting   22.1. Events 22.1.1. Event Logs 22.1.2. Standard Events 22.1.3. Long Running Job Events 22.1.4. Event Log Queries 22.2. Working with Server Logs 22.3. Data Loss on Exported Primary Storage 22.4. Recovering a Lost Virtual Router 22.5. Maintenance mode not working on vCenter 22.6. Unable to deploy VMs from uploaded vSphere template 22.7. Unable to power on virtual machine on VMware 22.8. Load balancer rules fail after changing network offering A. Time Zones   B. Event Types   C. Alerts   D. Revision History   Chapter 1.Chapter 1. ConceptsConceptsWhat Is CloudStack?1.1. What Is CloudStack? CloudStack is an open source software platform that pools computing resources to build public, private, and hybrid Infrastructure as a Service (IaaS) clouds. CloudStack manages the network, storage, and compute nodes that make up a cloud infrastructure. Use CloudStack to deploy, manage, and configure cloud computing environments. Typical users are service providers and enterprises. With CloudStack, you can: - + Set up an on-demand, elastic cloud computing service. Service providers can sell self service virtual machine instances, storage volumes, and networking configurations over the Internet. - + Set up an on-premise private cloud for use by employees. Rather than managing virtual machines in the same way as physical machines, with CloudStack an enterprise can offer self-service virtual machines to users without involving IT departments. - What Can CloudStack Do?1.2. What Can CloudStack Do? + What Can CloudStack Do?1.2. What Can CloudStack Do? Multiple Hypervisor Support CloudStack works with a variety of hypervisors, and a single cloud deployment can contain multiple hypervisor implementations. The current release of CloudStack supports pre-packaged enterprise solutions like Citrix XenServer and VMware vSphere, as well as KVM or Xen running on Ubuntu or CentOS. @@ -54,7 +54,7 @@ A CloudStack installation consists of two parts: the Management Server and the cloud infrastructure that it manages. When you set up and manage a CloudStack cloud, you provision resources such as hosts, storage devices, and IP addresses into the Management Server, and the Management Server manages those resources. The minimum production installation consists of one machine running the CloudStack Management Server and another machine to act as the cloud infrastructure (in this case, a very simple infrastructure consisting of one host running hypervisor software). In its smallest deployment, a single machine can act as both the Management Server and the hypervisor host (using the KVM hypervisor). - + A more full-featured installation consists of a highly-available multi-node Management Server installation and up to tens of thousands of hosts using any of several advanced networking setups. For information about deployment options, see Choosing a Deployment Architecture. Management Server Overview1.3.1. Management Server Overview The Management Server is the CloudStack software that manages cloud resources. By interacting with the Management Server through its UI or API, you can configure and manage your cloud infrastructure. @@ -64,43 +64,43 @@ The machine must meet the system requirements described in System Requirements. The Management Server: - + Provides the web user interface for the administrator and a reference user interface for end users. - + Provides the APIs for CloudStack. - + Manages the assignment of guest VMs to particular hosts. - + Manages the assignment of public and private IP addresses to particular accounts. - + Manages the allocation of storage to guests as virtual disks. - + Manages snapshots, templates, and ISO images, possibly replicating them across data centers. - + Provides a single point of configuration for the cloud. Cloud Infrastructure Overview1.3.2. Cloud Infrastructure Overview The Management Server manages one or more zones (typically, datacenters) containing host computers where guest virtual machines will run. The cloud infrastructure is organized as follows: - + Zone: Typically, a zone is equivalent to a single datacenter. A zone consists of one or more pods and secondary storage. - + Pod: A pod is usually one rack of hardware that includes a layer-2 switch and one or more clusters. - + Cluster: A cluster consists of one or more hosts and primary storage. - + Host: A single compute node within a cluster. The hosts are where the actual cloud services run in the form of guest virtual machines. - + Primary storage is associated with a cluster, and it stores the disk volumes for all the VMs running on hosts in that cluster. - + Secondary storage is associated with a zone, and it stores templates, ISO images, and disk volume snapshots. - + More Information For more information, see documentation on cloud infrastructure concepts. Networking Overview1.3.3. Networking Overview CloudStack offers two types of networking scenario: - + Basic. For AWS-style networking. Provides a single network where guest isolation can be provided through layer-3 means such as security groups (IP address source filtering). - + Advanced. For more sophisticated network topologies. This network model provides the most flexibility in defining guest networks. For more details, see Network Setup. @@ -108,11 +108,11 @@ A zone is the largest organizational unit within a CloudStack deployment. A zone typically corresponds to a single datacenter, although it is permissible to have multiple zones in a datacenter. The benefit of organizing infrastructure into zones is to provide physical isolation and redundancy. For example, each zone can have its own power supply and network uplink, and the zones can be widely separated geographically (though this is not required). A zone consists of: - + One or more pods. Each pod contains one or more clusters of hosts and one or more primary storage servers. - + Secondary storage, which is shared by all the pods in the zone. - + Zones are visible to the end user. When a user starts a guest VM, the user must select a zone for their guest. Users might also be required to copy their private templates to additional zones to enable creation of guest VMs using their templates in those zones. Zones can be public or private. Public zones are visible to all users. This means that any user may create a guest in that zone. Private zones are reserved for a specific domain. Only users in that domain or its subdomains may create guests in that zone. @@ -120,15 +120,15 @@ Hosts in the same zone are directly accessible to each other without having to go through a firewall. Hosts in different zones can access each other through statically configured VPN tunnels. For each zone, the administrator must decide the following. - + How many pods to place in a zone. - + How many clusters to place in each pod. - + How many hosts to place in each cluster. - + How many primary storage servers to place in each cluster and total capacity for the storage servers. - + How much secondary storage to deploy in a zone. When you add a new zone, you will be prompted to configure the zone’s physical network and add the first pod, cluster, host, primary storage, and secondary storage. @@ -140,13 +140,13 @@ Pods are not visible to the end user. A pod consists of one or more clusters of hosts and one or more primary storage servers. - About Clusters2.3. About Clusters + About Clusters2.3. About Clusters A cluster provides a way to group hosts. To be precise, a cluster is a XenServer server pool, a set of KVM servers, , or a VMware cluster preconfigured in vCenter. The hosts in a cluster all have identical hardware, run the same hypervisor, are on the same subnet, and access the same shared primary storage. Virtual machine instances (VMs) can be live-migrated from one host to another within the same cluster, without interrupting service to the user. A cluster is the third-largest organizational unit within a CloudStack deployment. Clusters are contained within pods, and pods are contained within zones. Size of the cluster is limited by the underlying hypervisor, although the CloudStack recommends less in most cases; see Best Practices. A cluster consists of one or more hosts and one or more primary storage servers. - + CloudStack allows multiple clusters in a cloud deployment. Even when local storage is used exclusively, clusters are still required organizationally, even if there is just one host per cluster. @@ -158,13 +158,13 @@ The host is the smallest organizational unit within a CloudStack deployment. Hosts are contained within clusters, clusters are contained within pods, and pods are contained within zones. Hosts in a CloudStack deployment: - + Provide the CPU, memory, storage, and networking resources needed to host the virtual machines - + Interconnect using a high bandwidth TCP/IP network and connect to the Internet - + May reside in multiple data centers across different geographic locations - + May have different capacities (different CPU speeds, different amounts of RAM, etc.), although the hosts within a cluster must all be homogeneous Additional hosts can be added at any time to provide more capacity for guest VMs. @@ -174,31 +174,31 @@ Hosts are not visible to the end user. An end user cannot determine which host their guest has been assigned to. For a host to function in CloudStack, you must do the following: - + Install hypervisor software on the host - + Assign an IP address to the host - + Ensure the host is connected to the CloudStack Management Server About Primary Storage2.5. About Primary Storage Primary storage is associated with a cluster, and it stores the disk volumes for all the VMs running on hosts in that cluster. You can add multiple primary storage servers to a cluster. At least one is required. It is typically located close to the hosts for increased performance. CloudStack is designed to work with all standards-compliant iSCSI and NFS servers that are supported by the underlying hypervisor, including, for example: - + Dell EqualLogic™ for iSCSI - + Network Appliances filers for NFS and iSCSI - + Scale Computing for NFS If you intend to use only local disk for your installation, you can skip to Add Secondary Storage. About Secondary Storage2.6. About Secondary Storage Secondary storage is associated with a zone, and it stores the following: - + Templates — OS images that can be used to boot VMs and can include additional configuration information, such as installed applications - + ISO images — disc images containing data or bootable media for operating systems - + Disk volume snapshots — saved copies of VM data which can be used for data recovery or to create new templates The items in zone-based NFS secondary storage are available to all hosts in the zone. CloudStack manages the allocation of guest virtual disks to particular primary storage devices. @@ -208,45 +208,45 @@ Part of adding a zone is setting up the physical network. One or (in an advanced zone) more physical networks can be associated with each zone. The network corresponds to a NIC on the hypervisor host. Each physical network can carry one or more types of network traffic. The choices of traffic type for each network vary depending on whether you are creating a zone with basic networking or advanced networking. A physical network is the actual network hardware and wiring in a zone. A zone can have multiple physical networks. An administrator can: - + Add/Remove/Update physical networks in a zone - + Configure VLANs on the physical network - + Configure a name so the network can be recognized by hypervisors - + Configure the service providers (firewalls, load balancers, etc.) available on a physical network - + Configure the IP addresses trunked to a physical network - + Specify what type of traffic is carried on the physical network, as well as other properties like network speed Configurable Characteristics of Physical Networks2.7.1. Configurable Characteristics of Physical Networks CloudStack provides configuration settings you can use to set up a physical network in a zone, including: - + What type of network traffic it carries (guest, public, management, storage) - + VLANs - + Unique name that the hypervisor can use to find that particular network - + Enabled or disabled. When a network is first set up, it is disabled – not in use yet. The administrator sets the physical network to enabled, and it begins to be used. The administrator can later disable the network again, which prevents any new virtual networks from being created on that physical network; the existing network traffic continues even though the state is disabled. - + Speed - + Tags, so network offerings can be matched to physical networks - + Isolation method Basic Zone Network Traffic Types2.7.2. Basic Zone Network Traffic Types When basic networking is used, there can be only one physical network in the zone. That physical network carries the following traffic types: - + Guest. When end users run VMs, they generate guest traffic. The guest VMs communicate with each other over a network that can be referred to as the guest network. Each pod in a basic zone is a broadcast domain, and therefore each pod has a different IP range for the guest network. The administrator must configure the IP range for each pod. - + Management. When CloudStack’s internal resources communicate with each other, they generate management traffic. This includes communication between hosts, system VMs (VMs used by CloudStack to perform various tasks in the cloud), and any other component that communicates directly with the CloudStack Management Server. You must configure the IP range for the system VMs to use. - Note + Note We strongly recommend the use of separate NICs for management traffic and guest traffic. - + Public. Public traffic is generated when VMs in the cloud access the Internet. Publicly accessible IPs must be allocated for this purpose. End users can use the CloudStack UI to acquire these IPs to implement NAT between their guest network and the public network, as described in Acquiring a New IP Address. - + Storage. Traffic such as VM templates and snapshots, which is sent between the secondary storage VM and secondary storage servers. CloudStack uses a separate Network Interface Controller (NIC) named storage NIC for storage network traffic. Use of a storage NIC that always operates on a high bandwidth network allows fast template and snapshot copying. You must configure the IP range to use for the storage network. In a basic network, configuring the physical network is fairly straightforward. In most cases, you only need to configure one guest network to carry traffic that is generated by guest VMs. If you use a NetScaler load balancer and enable its elastic IP and elastic load balancing (EIP and ELB) features, you must also configure a network to carry public traffic. CloudStack takes care of presenting the necessary network configuration steps to you in the UI when you add a new zone. @@ -254,13 +254,13 @@ When basic networking is used, CloudPlatform will assign IP addresses in the CIDR of the pod to the guests in that pod. The administrator must add a Direct IP range on the pod for this purpose. These IPs are in the same VLAN as the hosts. Advanced Zone Network Traffic Types2.7.4. Advanced Zone Network Traffic Types When advanced networking is used, there can be multiple physical networks in the zone. Each physical network can carry one or more traffic types, and you need to let CloudStack know which type of network traffic you want each network to carry. The traffic types in an advanced zone are: - + Guest. When end users run VMs, they generate guest traffic. The guest VMs communicate with each other over a network that can be referred to as the guest network. This network can be isolated or shared. In an isolated guest network, the administrator needs to reserve VLAN ranges to provide isolation for each CloudStack account’s network (potentially a large number of VLANs). In a shared guest network, all guest VMs share a single network. - + Management. When CloudStack’s internal resources communicate with each other, they generate management traffic. This includes communication between hosts, system VMs (VMs used by CloudStack to perform various tasks in the cloud), and any other component that communicates directly with the CloudStack Management Server. You must configure the IP range for the system VMs to use. - + Public. Public traffic is generated when VMs in the cloud access the Internet. Publicly accessible IPs must be allocated for this purpose. End users can use the CloudStack UI to acquire these IPs to implement NAT between their guest network and the public network, as described in “Acquiring a New IP Address” in the Administration Guide. - + Storage. Traffic such as VM templates and snapshots, which is sent between the secondary storage VM and secondary storage servers. CloudStack uses a separate Network Interface Controller (NIC) named storage NIC for storage network traffic. Use of a storage NIC that always operates on a high bandwidth network allows fast template and snapshot copying. You must configure the IP range to use for the storage network. These traffic types can each be on a separate physical network, or they can be combined with certain restrictions. When you use the Add Zone wizard in the UI to create a new zone, you are guided into making only valid choices. @@ -290,9 +290,9 @@ When advanced networking is being used, the number of private IP addresses available in each pod varies depending on which hypervisor is running on the nodes in that pod. Citrix XenServer and KVM use link-local addresses, which in theory provide more than 65,000 private IP addresses within the address block. As the pod grows over time, this should be more than enough for any reasonable number of hosts as well as IP addresses for guest virtual routers. VMWare ESXi, by contrast uses any administrator-specified subnetting scheme, and the typical administrator provides only 255 IPs per pod. Since these are shared by physical machines, the guest virtual router, and other entities, it is possible to run out of private IPs when scaling up a pod whose nodes are running ESXi. To ensure adequate headroom to scale private IP space in an ESXi pod that uses advanced networking, use one or both of the following techniques: - + Specify a larger CIDR block for the subnet. A subnet mask with a /20 suffix will provide more than 4,000 IP addresses. - + Create multiple pods, each with its own subnet. For example, if you create 10 pods and each pod has 255 IPs, this will provide 2,550 IP addresses. Chapter 3.Chapter 3. AccountsAccountsAccounts, Users, and Domains3.1. Accounts, Users, and DomainsAccounts An account typically represents a customer of the service provider or a department in a large organization. Multiple users can exist in an account. @@ -316,21 +316,21 @@ You can use an external LDAP server such as Microsoft Active Directory or ApacheDS to authenticate CloudStack end-users. Just map CloudStack accounts to the corresponding LDAP accounts using a query filter. The query filter is written using the query syntax of the particular LDAP server, and can include special wildcard characters provided by CloudStack for matching common values such as the user’s email address and name. CloudStack will search the external LDAP directory tree starting at a specified base directory and return the distinguished name (DN) and password of the matching user. This information along with the given password is used to authenticate the user.. To set up LDAP authentication in CloudStack, call the CloudStack API command ldapConfig and provide the following: - + Hostname or IP address and listening port of the LDAP server - + Base directory and query filter - + Search user DN credentials, which give CloudStack permission to search on the LDAP server - + SSL keystore and password, if SSL is used Example LDAP Configuration Commands3.2.1. Example LDAP Configuration Commands To understand the examples in this section, you need to know the basic concepts behind calling the CloudStack API, which are explained in the Developer’s Guide. The following shows an example invocation of ldapConfig with an ApacheDS LDAP server - http://127.0.0.1:8080/client/api?command=ldapConfig&hostname=127.0.0.1&searchbase=ou%3Dtesting%2Co%3Dproject&queryfilter=%28%26%28uid%3D%25u%29%29&binddn=cn%3DJohn+Singh%2Cou%3Dtesting%2Co%project&bindpass=secret&port=10389&ssl=true&truststore=C%3A%2Fcompany%2Finfo%2Ftrusted.ks&truststorepass=secret&response=json&apiKey=YourAPIKey&signature=YourSignatureHash + http://127.0.0.1:8080/client/api?command=ldapConfig&hostname=127.0.0.1&searchbase=ou%3Dtesting%2Co%3Dproject&queryfilter=%28%26%28uid%3D%25u%29%29&binddn=cn%3DJohn+Singh%2Cou%3Dtesting%2Co%project&bindpass=secret&port=10389&ssl=true&truststore=C%3A%2Fcompany%2Finfo%2Ftrusted.ks&truststorepass=secret&response=json&apiKey=YourAPIKey&signature=YourSignatureHash The command must be URL-encoded. Here is the same example without the URL encoding: - http://127.0.0.1:8080/client/api?command=ldapConfig + http://127.0.0.1:8080/client/api?command=ldapConfig &hostname=127.0.0.1 &searchbase=ou=testing,o=project &queryfilter=(&(%uid=%u)) @@ -344,11 +344,11 @@ &apiKey=YourAPIKey&signature=YourSignatureHash The following shows a similar command for Active Directory. Here, the search base is the testing group within a company, and the users are matched up based on email address. - http://10.147.29.101:8080/client/api?command=ldapConfig&hostname=10.147.28.250&searchbase=OU%3Dtesting%2CDC%3Dcompany&queryfilter=%28%26%28mail%3D%25e%29%29 &binddn=CN%3DAdministrator%2COU%3Dtesting%2CDC%3Dcompany&bindpass=1111_aaaa&port=389&response=json&apiKey=YourAPIKey&signature=YourSignatureHash + http://10.147.29.101:8080/client/api?command=ldapConfig&hostname=10.147.28.250&searchbase=OU%3Dtesting%2CDC%3Dcompany&queryfilter=%28%26%28mail%3D%25e%29%29 &binddn=CN%3DAdministrator%2COU%3Dtesting%2CDC%3Dcompany&bindpass=1111_aaaa&port=389&response=json&apiKey=YourAPIKey&signature=YourSignatureHash The next few sections explain some of the concepts you will need to know when filling out the ldapConfig parameters. Search Base3.2.2. Search Base An LDAP query is relative to a given node of the LDAP directory tree, called the search base. The search base is the distinguished name (DN) of a level of the directory tree below which all users can be found. The users can be in the immediate base directory or in some subdirectory. The search base may be equivalent to the organization, group, or domain name. The syntax for writing a DN varies depending on which LDAP server you are using. A full discussion of distinguished names is outside the scope of our documentation. The following table shows some examples of search bases to find users in the testing department.. - + LDAP Server @@ -376,7 +376,7 @@ The query filter is used to find a mapped user in the external LDAP server. The query filter should uniquely map the CloudPlatform user to LDAP user for a meaningful authentication. For more information about query filter syntax, consult the documentation for your LDAP server. The CloudPlatform query filter wildcards are: - + Query Filter Wildcard @@ -412,13 +412,13 @@ The following examples assume you are using Active Directory, and refer to user attributes from the Active Directory schema. If the CloudPlatform user name is the same as the LDAP user ID: - (uid=%u) + (uid=%u) If the CloudPlatform user name is the LDAP display name: - (displayName=%u) + (displayName=%u) To find a user by email address: - (mail=%e)Search User Bind DN3.2.4. Search User Bind DN + (mail=%e)Search User Bind DN3.2.4. Search User Bind DN The bind DN is the user on the external LDAP server permitted to search the LDAP directory within the defined search base. When the DN is returned, the DN and passed password are used to authenticate the CloudStack user with an LDAP bind. A full discussion of bind DNs is outside the scope of our documentation. The following table shows some examples of bind DNs. - + LDAP Server @@ -448,19 +448,19 @@ In addition to the physical and logical infrastructure of your cloud, and the CloudStack software and servers, you also need a layer of user services so that people can actually make use of the cloud. This means not just a user UI, but a set of options and resources that users can choose from, such as templates for creating virtual machines, disk storage, and more. If you are running a commercial service, you will be keeping track of what services and resources users are consuming and charging them for that usage. Even if you do not charge anything for people to use your cloud – say, if the users are strictly internal to your organization, or just friends who are sharing your cloud – you can still keep track of what services they use and how much of them. Service Offerings, Disk Offerings, Network Offerings, and Templates4.1. Service Offerings, Disk Offerings, Network Offerings, and Templates A user creating a new instance can make a variety of choices about its characteristics and capabilities. CloudStack provides several ways to present users with choices when creating a new instance: - + Service Offerings, defined by the CloudStack administrator, provide a choice of CPU speed, number of CPUs, RAM size, tags on the root disk, and other choices. See Creating a New Compute Offering. - + Disk Offerings, defined by the CloudStack administrator, provide a choice of disk size for primary data storage. See Creating a New Disk Offering. - + Network Offerings, defined by the CloudStack administrator, describe the feature set that is available to end users from the virtual router or external networking devices on a given guest network. See Network Offerings. - + Templates, defined by the CloudStack administrator or by any CloudStack user, are the base OS images that the user can choose from when creating a new instance. For example, CloudStack includes CentOS as a template. See Working with Templates. In addition to these choices that are provided for users, there is another type of service offering which is available only to the CloudStack root administrator, and is used for configuring virtual infrastructure resources. For more information, see Upgrading a Virtual Router with System Service Offerings. Chapter 5.Chapter 5. User InterfaceUser InterfaceLog In to the UI5.1. Log In to the UI CloudStack provides a web-based UI that can be used by both administrators and end users. The appropriate version of the UI is displayed depending on the credentials used to log in. The UI is available in popular browsers including IE7, IE8, IE9, Firefox 3.5+, Firefox 4, Safari 4, and Safari 5. The URL is: (substitute your own management server IP address) - http://<management-server-ip-address>:8080/client + http://<management-server-ip-address>:8080/client On a fresh Management Server installation, a guided tour splash screen appears. On later visits, you’ll see a login screen where you specify the following to proceed to your Dashboard: Username The user ID of your account. The default username is admin. @@ -480,42 +480,42 @@ The CloudStack UI helps the CloudStack administrator provision, view, and manage the cloud infrastructure, domains, user accounts, projects, and configuration settings. The first time you start the UI after a fresh Management Server installation, you can choose to follow a guided tour to provision your cloud infrastructure. On subsequent logins, the dashboard of the logged-in user appears. The various links in this screen and the navigation bar on the left provide access to a variety of administrative functions. The root administrator can also use the UI to perform all the same tasks that are present in the end-user’s UI. Logging In as the Root Administrator5.1.3. Logging In as the Root Administrator After the Management Server software is installed and running, you can run the CloudStack user interface. This UI is there to help you provision, view, and manage your cloud infrastructure. - 1. + 1. Open your favorite Web browser and go to this URL. Substitute the IP address of your own Management Server: - http://<management-server-ip-address>:8080/client + http://<management-server-ip-address>:8080/client After logging into a fresh Management Server installation, a guided tour splash screen appears. On later visits, you’ll be taken directly into the Dashboard. - 2. + 2. If you see the first-time splash screen, choose one of the following. - + Continue with basic setup. Choose this if you're just trying CloudStack, and you want a guided walkthrough of the simplest possible configuration so that you can get started right away. We'll help you set up a cloud with the following features: a single machine that runs CloudStack software and uses NFS to provide storage; a single machine running VMs under the XenServer or KVM hypervisor; and a shared public network. The prompts in this guided tour should give you all the information you need, but if you want just a bit more detail, you can follow along in the Trial Installation Guide. - + I have used CloudStack before. Choose this if you have already gone through a design phase and planned a more sophisticated deployment, or you are ready to start scaling up a trial cloud that you set up earlier with the basic setup screens. In the Administrator UI, you can start using the more powerful features of CloudPlatform, such as advanced VLAN networking, high availability, additional network elements such as load balancers and firewalls, and support for multiple hypervisors including Citrix XenServer, KVM, and VMware vSphere. The root administrator Dashboard appears. - 3. + 3. You should set a new root administrator password. If you chose basic setup, you’ll be prompted to create a new password right away. If you chose experienced user, use the steps in Section 5.1.4, “Changing the Root Password”. - Warning + Warning You are logging in as the root administrator. This account manages the CloudStack deployment, including physical infrastructure. The root administrator can modify configuration settings to change basic functionality, create or delete user accounts, and take many actions that should be performed only by an authorized person. Please change the default password to a new, unique password. Changing the Root Password5.1.4. Changing the Root Password During installation and ongoing cloud administration, you will need to log in to the UI as the root administrator. The root administrator account manages the CloudStack deployment, including physical infrastructure. The root administrator can modify configuration settings to change basic functionality, create or delete user accounts, and take many actions that should be performed only by an authorized person. When first installing CloudStack, be sure to change the default password to a new, unique value. - 1. + 1. Open your favorite Web browser and go to this URL. Substitute the IP address of your own Management Server: - http://<management-server-ip-address>:8080/client2. + http://<management-server-ip-address>:8080/client2. Log in to the UI using the current root user ID and password. The default is admin, password. - 3. + 3. Click Accounts. - 4. + 4. Click the admin account name. - 5. + 5. Click View Users. - 6. + 6. Click the admin user name. - 7. + 7. Click the Change Password button. - 8. + 8. Type the new password, and click OK. Using SSH Keys for Authentication5.2. Using SSH Keys for Authentication In addition to the username and password authentication, CloudStack 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. @@ -523,31 +523,31 @@ 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. Creating an Instance Template that Supports SSH Keys5.2.1.  Creating an Instance Template that Supports SSH Keys Create a instance template that supports SSH Keys. - 1. + 1. Create a new instance by using the template provided by cloudstack. For more information on creating a new instance, see - 2. + 2. Download the cloudstack script from The SSH Key Gen Script11 http://sourceforge.net/projects/cloudstack/files/SSH%20Key%20Gen%20Script/to the instance you have created. - 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=iweb3. + 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=iweb3. Copy the file to /etc/init.d. - cp cloud-set-guest-sshkey.in /etc/init.d/4. + cp cloud-set-guest-sshkey.in /etc/init.d/4. Give the necessary permissions on the script: - chmod +x /etc/init.d/cloud-set-guest-sshkey.in5. + chmod +x /etc/init.d/cloud-set-guest-sshkey.in5. Run the script while starting up the operating system: - chkconfig --add cloud-set-guest-sshkey.in6. + chkconfig --add cloud-set-guest-sshkey.in6. Stop the instance. Creating the SSH Keypair5.2.2. Creating the SSH Keypair 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. 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: - Note + Note 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. - 1. + 1. Run the following curl command: - curl --globoff "http://localhost:8096/?command=createSSHKeyPair&name=keypair-doc&account=admin&domainid=5163440e-c44b-42b5-9109-ad75cae8e8a2" + curl --globoff "http://localhost:8096/?command=createSSHKeyPair&name=keypair-doc&account=admin&domainid=5163440e-c44b-42b5-9109-ad75cae8e8a2" The output is something similar to what is given below: - <?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----- + <?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 @@ -559,9 +559,9 @@ nVo8b2Gvyagqt/KEQo8wzH2THghZ1qQ1QRhIeJG2aissEacF6bGB2oZ7Igim5L14 4KR7OeEToyCLC2k+02UCQQCrniSnWKtDVoVqeK/zbB32JhW3Wullv5p5zUEcd KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 -----END RSA PRIVATE KEY----- -</privatekey></keypair></createsshkeypairresponse>2. +</privatekey></keypair></createsshkeypairresponse>2. Copy the key data into a file. The file looks like this: - -----BEGIN RSA PRIVATE KEY----- + -----BEGIN RSA PRIVATE KEY----- MIICXQIBAAKBgQCSydmnQ67jP6lNoXdX3noZjQdrMAWNQZ7y5SrEu4wDxplvhYci dXYBeZVwakDVsU2MLGl/K+wefwefwefwefwefJyKJaogMKn7BperPD6n1wIDAQAB AoGAdXaJ7uyZKeRDoy6wA0UmF0kSPbMZCR+UTIHNkS/E0/4U+6lhMokmFSHtu @@ -572,21 +572,21 @@ lYaocpk0yBqqOUSBawfIiDCuLXSdvBo1Xz5ICTM19vgvEp/+kMuECQBzm nVo8b2Gvyagqt/KEQo8wzH2THghZ1qQ1QRhIeJG2aissEacF6bGB2oZ7Igim5L14 4KR7OeEToyCLC2k+02UCQQCrniSnWKtDVoVqeK/zbB32JhW3Wullv5p5zUEcd KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 ------END RSA PRIVATE KEY-----3. +-----END RSA PRIVATE KEY-----3. Save the file. Creating an Instance5.2.3. Creating an Instance After you save the SSH keypair file, you must create an instance by using the template that you created at Section 5.2.1, “ Creating an Instance Template that Supports SSH Keys”. Ensure that you use the same SSH key name that you created at Section 5.2.2, “Creating the SSH Keypair”. - Note + Note You cannot create the instance by using the GUI at this time and associate the instance with the newly created SSH keypair. A sample curl command to create a new instance is: - curl --globoff http://localhost:<port numbet>/?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 + curl --globoff http://localhost:<port numbet>/?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 Substitute the template, service offering and security group IDs (if you are using the security group feature) that are in your cloud environment. Logging In Using the SSH Keypair5.2.4. Logging In Using the SSH Keypair To test your SSH key generation is successful, check whether you can log in to the cloud setup. For exaple, from a Linux OS, run: - ssh -i ~/.ssh/keypair-doc <ip address> + ssh -i ~/.ssh/keypair-doc <ip address> The -i parameter tells the ssh client to use a ssh key found at ~/.ssh/keypair-doc. Chapter 6.Chapter 6. Using Projects to Organize Users and ResourcesUsing Projects to Organize Users and ResourcesOverview of Projects6.1. Overview of Projects Projects are used to organize people and resources. CloudStack users within a single domain can group themselves into project teams so they can collaborate and share virtual resources such as VMs, snapshots, templates, data disks, and IP addresses. CloudStack tracks resource usage per project as well as per user, so the usage can be billed to either a user account or a project. For example, a private cloud within a software company might have all members of the QA department assigned to one project, so the company can track the resources used in testing while the project members can more easily isolate their efforts from other users of the same cloud @@ -600,18 +600,18 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 Before CloudPlatform users start using projects, the CloudPlatform administrator must set up various systems to support them, including membership invitations, limits on project resources, and controls on who can create projects. Setting Up Invitations6.2.1. Setting Up Invitations CloudStack can be set up either so that project administrators can add people directly to a project, or so that it is necessary to send an invitation which the recipient must accept. The invitation can be sent by email or through the user’s CloudStack account. If you want administrators to use invitations to add members to projects, turn on and set up the invitations feature in CloudStack. - + Log in as administrator to the CloudStack UI. - + In the left navigation, click Global Settings. - + In the search box, type project and click the search button. - + In the search box, type project and click the search button. - + In the search results, you will see a few other parameters you need to set to control how invitations behave. The table below shows global configuration parameters related to project invitations. Click the edit button to set each parameter - + Configuration Parameters @@ -683,38 +683,38 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 (Optional) User name required by the SMTP server for authentication. You must also set project.smtp.password and set project.smtp.useAuth to true.. - + Restart the Management Server - service cloud-management restartSetting Resource Limits for Projects6.2.2. Setting Resource Limits for Projects + service cloud-management restartSetting Resource Limits for Projects6.2.2. Setting Resource Limits for Projects The CloudStack administrator can set global default limits to control the amount of resources that can be owned by each project in the cloud. This serves to prevent uncontrolled usage of resources such as snapshots, IP addresses, and virtual machine instances. Domain administrators can override these resource limits for individual projects with their domains, as long as the new limits are below the global defaults set by the CloudStack root administrator. The root administrator can also set lower resource limits for any project in the cloud 6.2.2.1. Setting Per-Project Resource Limits The CloudStack root administrator or the domain administrator of the domain where the project resides can set new resource limits for an individual project. The project owner can set resource limits only if the owner is also a domain or root administrator. The new limits must be below the global default limits set by the CloudStack administrator (as described in Section 6.2.2, “Setting Resource Limits for Projects”). If the project already owns more of a given type of resource than the new maximum, the resources are not affected; however, the project can not add any new resources of that type until the total drops below the new limit. - 1. + 1. Log in as administrator to the CloudStack UI. - 2. + 2. In the left navigation, click Projects. - 3. + 3. In Select View, choose Projects. - 4. + 4. Click the name of the project you want to work with. - 5. + 5. Click the Resources tab. This tab lists the current maximum amount that the project is allowed to own for each type of resource. - 6. + 6. Type new values for one or more resources. - 7. + 7. Click Apply. - 6.2.2.2. Setting the Global Project Resource Limits1. + 6.2.2.2. Setting the Global Project Resource Limits1. Log in as administrator to the CloudStack UI. - 2. + 2. In the left navigation, click Global Settings. - 3. + 3. In the search box, type max.projects and click the search button. - 4. + 4. In the search results, you will see the parameters you can use to set per-project maximum resource amounts that apply to all projects in the cloud. No project can have more resources, but an individual project can have lower limits. Click the edit button to set each parameter. - + max.project.public.ips @@ -754,20 +754,20 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 Maximum number of data volumes that can be owned by any project in the cloud. See Working with Volumes. - 5. + 5. Restart the Management Server. - # service cloud-management restartSetting Project Creator Permissions6.2.3. Setting Project Creator Permissions + # service cloud-management restartSetting Project Creator Permissions6.2.3. Setting Project Creator Permissions You can configure CloudStack to allow any user to create a new project, or you can restrict that ability to just CloudStack administrators. - 1. + 1. Log in as administrator to the CloudStack UI. - 2. + 2. In the left navigation, click Global Settings. - 3. + 3. In the search box, type allow.user.create.projects. - 4. + 4. Click the edit button to set the parameter. - + allow.user.create.projects @@ -775,79 +775,79 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 Set to true to allow end users to create projects. Set to false if you want only the CloudStack root administrator and domain administrators to create projects. - 5. + 5. Restart the Management Server. - # service cloud-management restartCreating a New Project6.3. Creating a New Project + # service cloud-management restartCreating a New Project6.3. Creating a New Project CloudStack administrators and domain administrators can create projects. If the global configuration parameter allow.user.create.projects is set to true, end users can also create projects. - 1. + 1. Log in as administrator to the CloudStack UI. - 2. + 2. In the left navigation, click Projects. - 3. + 3. In Select view, click Projects. - 4. + 4. Click New Project. - 5. + 5. Give the project a name and description for display to users, then click Create Project. - 6. + 6. A screen appears where you can immediately add more members to the project. This is optional. Click Next when you are ready to move on. - 7. + 7. Click Save. Adding Members to a Project6.4. Adding Members to a Project New members can be added to a project by the project’s administrator, the domain administrator of the domain where the project resides or any parent domain, or the CloudStack root administrator. There are two ways to add members in CloudStack, but only one way is enabled at a time: - + If invitations have been enabled, you can send invitations to new members. - + If invitations are not enabled, you can add members directly through the UI. Sending Project Membership Invitations6.4.1. Sending Project Membership Invitations Use these steps to add a new member to a project if the invitations feature is enabled in the cloud as described in Section 6.2.1, “Setting Up Invitations”. If the invitations feature is not turned on, use the procedure in Adding Project Members From the UI. - 1. + 1. Log in to the CloudStack UI. - 2. + 2. In the left navigation, click Projects. - 3. + 3. In Select View, choose Projects. - 4. + 4. Click the name of the project you want to work with. - 5. + 5. Click the Invitations tab. - 6. + 6. In Add by, select one of the following: - a. + a. Account – The invitation will appear in the user’s Invitations tab in the Project View. See Using the Project View. - b. + b. Email – The invitation will be sent to the user’s email address. Each emailed invitation includes a unique code called a token which the recipient will provide back to CloudStack when accepting the invitation. Email invitations will work only if the global parameters related to the SMTP server have been set. See Section 6.2.1, “Setting Up Invitations”. - 7. + 7. Type the user name or email address of the new member you want to add, and click Invite. Type the CloudStack user name if you chose Account in the previous step. If you chose Email, type the email address. You can invite only people who have an account in this cloud within the same domain as the project. However, you can send the invitation to any email address. - 8. + 8. To view and manage the invitations you have sent, return to this tab. When an invitation is accepted, the new member will appear in the project’s Accounts tab. Adding Project Members From the UI6.4.2. Adding Project Members From the UI The steps below tell how to add a new member to a project if the invitations feature is not enabled in the cloud. If the invitations feature is enabled cloud,as described in Section 6.2.1, “Setting Up Invitations”, use the procedure in Section 6.4.1, “Sending Project Membership Invitations”. - 1. + 1. Log in to the CloudStack UI. - 2. + 2. In the left navigation, click Projects. - 3. + 3. In Select View, choose Projects. - 4. + 4. Click the name of the project you want to work with. - 5. + 5. Click the Accounts tab. The current members of the project are listed. - 6. + 6. Type the account name of the new member you want to add, and click Add Account. You can add only people who have an account in this cloud and within the same domain as the project. Accepting a Membership Invitation6.5. Accepting a Membership Invitation If you have received an invitation to join a CloudStack project, and you want to accept the invitation, follow these steps: - 1. + 1. Log in to the CloudStack UI. - 2. + 2. In the left navigation, click Projects. - 3. + 3. In Select View, choose Invitations. - 4. + 4. If you see the invitation listed onscreen, click the Accept button. Invitations listed on screen were sent to you using your CloudStack account name. - 5. + 5. If you received an email invitation, click the Enter Token button, and provide the project ID and unique ID code (token) from the email. Suspending or Deleting a Project6.6. Suspending or Deleting a Project When a project is suspended, it retains the resources it owns, but they can no longer be used. No new resources or members can be added to a suspended project. @@ -855,15 +855,15 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 When a project is deleted, its resources are destroyed, and member accounts are removed from the project. The project’s status is shown as Disabled pending final deletion. A project can be suspended or deleted by the project administrator, the domain administrator of the domain the project belongs to or of its parent domain, or the CloudStack root administrator. - 1. + 1. Log in to the CloudStack UI. - 2. + 2. In the left navigation, click Projects. - 3. + 3. In Select View, choose Projects. - 4. + 4. Click the name of the project. - 5. + 5. Click one of the buttons: To delete, use @@ -873,15 +873,15 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 Using the Project View6.7. Using the Project View If you are a member of a project, you can use CloudStack’s project view to see project members, resources consumed, and more. The project view shows only information related to one project. It is a useful way to filter out other information so you can concentrate on a project status and resources. - 1. + 1. Log in to the CloudStack UI. - 2. + 2. Click Project View. - 3. + 3. The project dashboard appears, showing the project’s VMs, volumes, users, events, network settings, and more. From the dashboard, you can: - + Click the Accounts tab to view and manage project members. If you are the project administrator, you can add new members, remove members, or change the role of a member from user to admin. Only one member at a time can have the admin role, so if you set another user’s role to admin, your role will change to regular user. - + (If invitations are enabled) Click the Invitations tab to view and manage invitations that have been sent to new project members but not yet accepted. Pending invitations will remain in this list until the new member accepts, the invitation timeout is reached, or you cancel the invitation. Chapter 7.Chapter 7. Steps to Provisioning Your Cloud InfrastructureSteps to Provisioning Your Cloud Infrastructure This section tells how to add zones, pods, clusters, hosts, storage, and networks to your cloud. If you are unfamiliar with these entities, please begin by looking through Chapter 2, Cloud Infrastructure Concepts. @@ -889,87 +889,87 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 After the Management Server is installed and running, you can add the compute resources for it to manage. For an overview of how a CloudStack cloud infrastructure is organized, see Section 1.3.2, “Cloud Infrastructure Overview”. To provision the cloud infrastructure, or to scale it up at any time, follow these procedures: - 1. + 1. Change the root password. See Section 5.1.4, “Changing the Root Password”. - 2. + 2. Add a zone. See Section 7.2, “Adding a Zone”. - 3. + 3. Add more pods (optional). See Section 7.3, “Adding a Pod”. - 4. + 4. Add more clusters (optional). See Section 7.4, “Adding a Cluster”. - 5. + 5. Add more hosts (optional). See Section 7.5, “Adding a Host”. - 6. + 6. Add primary storage. See Section 7.6, “Add Primary Storage”. - 7. + 7. Add secondary storage. See Section 7.7, “Add Secondary Storage”. - 8. + 8. Initialize and test the new cloud. See Section 7.8, “Initialize and Test”. When you have finished these steps, you will have a deployment with the following basic structure: - Adding a Zone7.2. Adding a Zone + Adding a Zone7.2. Adding a Zone These steps assume you have already logged in to the CloudStack UI. See Section 5.1, “Log In to the UI”. - 1. + 1. (Optional) If you are going to use Swift for cloud-wide secondary storage, you need to add it before you add zones. - a. + a. Log in to the CloudStack UI as administrator. - b. + b. If this is your first time visiting the UI, you will see the guided tour splash screen. Choose “Experienced user.” The Dashboard appears. - c. + c. In the left navigation bar, click Global Settings. - d. + d. In the search box, type swift.enable and click the search button. - e. + e. Click the edit button and set swift.enable to true. - f. + f. Restart the Management Server. - # service cloud-management restartg. + # service cloud-management restartg. Refresh the CloudStack UI browser tab and log back in. - 2. + 2. In the left navigation, choose Infrastructure. - 3. + 3. On Zones, click View More. - 4. + 4. (Optional) If you are using Swift storage, click Enable Swift. Provide the following: - + URL. The Swift URL. - + Account. The Swift account. - + Username. The Swift account’s username. - + Key. The Swift key. - 5. + 5. Click Add Zone. The zone creation wizard will appear. - 6. + 6. Choose one of the following network types: - + Basic. For AWS-style networking. Provides a single network where each VM instance is assigned an IP directly from the network. Guest isolation can be provided through layer-3 means such as security groups (IP address source filtering). - + Advanced. For more sophisticated network topologies. This network model provides the most flexibility in defining guest networks and providing custom network offerings such as firewall, VPN, or load balancer support. For more information about the network types, see Network Setup. - 7. + 7. The rest of the steps differ depending on whether you chose Basic or Advanced. Continue with the steps that apply to you: - + Section 7.2.1, “Basic Zone Configuration” - + Section 7.2.2, “Advanced Zone Configuration” - Basic Zone Configuration7.2.1. Basic Zone Configuration1. + Basic Zone Configuration7.2.1. Basic Zone Configuration1. After you select Basic in the Add Zone wizard and click Next, you will be asked to enter the following details. Then click Next. - + Name. A name for the zone. - + DNS 1 and 2. These are DNS servers for use by guest VMs in the zone. These DNS servers will be accessed via the public network you will add later. The public IP addresses for the zone must have a route to the DNS server named here. - + Internal DNS 1 and Internal DNS 2. These are DNS servers for use by system VMs in the zone (these are VMs used by CloudStack itself, such as virtual routers, console proxies, and Secondary Storage VMs.) These DNS servers will be accessed via the management traffic network interface of the System VMs. The private IP address you provide for the pods must have a route to the internal DNS server named here. - + Hypervisor. (Introduced in version 3.0.1) Choose the hypervisor for the first cluster in the zone. You can add clusters with different hypervisors later, after you finish adding the zone. - + Network Offering. Your choice here determines what network services will be available on the network for guest VMs. - + Network Offering @@ -1001,208 +1001,208 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 If you have installed a Citrix NetScaler appliance as part of your zone network, and you will be using its Elastic IP and Elastic Load Balancing features, choose this. With the EIP and ELB features, a basic zone with security groups enabled can offer 1:1 static NAT and load balancing. - + Network Domain. (Optional) If you want to assign a special domain name to the guest VM network, specify the DNS suffix. - + Public. A public zone is available to all users. A zone that is not public will be assigned to a particular domain. Only users in that domain will be allowed to create guest VMs in this zone. - 2. + 2. Choose which traffic types will be carried by the physical network. The traffic types are management, public, guest, and storage traffic. For more information about the types, roll over the icons to display their tool tips, or see Basic Zone Network Traffic Types. This screen starts out with some traffic types already assigned. To add more, drag and drop traffic types onto the network. You can also change the network name if desired. - 3. + 3. (Introduced in version 3.0.1) Assign a network traffic label to each traffic type on the physical network. These labels must match the labels you have already defined on the hypervisor host. To assign each label, click the Edit button under the traffic type icon. A popup dialog appears where you can type the label, then click OK. These traffic labels will be defined only for the hypervisor selected for the first cluster. For all other hypervisors, the labels can be configured after the zone is created. - 4. + 4. Click Next. - 5. + 5. (NetScaler only) If you chose the network offering for NetScaler, you have an additional screen to fill out. Provide the requested details to set up the NetScaler, then click Next. - + IP address. The NSIP (NetScaler IP) address of the NetScaler device. - + Username/Password. The authentication credentials to access the device. CloudStack uses these credentials to access the device. - + Type. NetScaler device type that is being added. It could be NetScaler VPX, NetScaler MPX, or NetScaler SDX. For a comparison of the types, see About Using a NetScaler Load Balancer. - + Public interface. Interface of NetScaler that is configured to be part of the public network. - + Private interface. Interface of NetScaler that is configured to be part of the private network. - + Number of retries. Number of times to attempt a command on the device before considering the operation failed. Default is 2. - + Capacity. Number of guest networks/accounts that will share this NetScaler device. - + Dedicated. When marked as dedicated, this device will be dedicated to a single account. When Dedicated is checked, the value in the Capacity field has no significance – implicitly, its value is 1. - 6. + 6. (NetScaler only) Configure the IP range for public traffic. The IPs in this range will be used for the static NAT capability which you enabled by selecting the network offering for NetScaler with EIP and ELB. Enter the following details, then click Add. If desired, you can repeat this step to add more IP ranges. When done, click Next. - + Gateway. The gateway in use for these IP addresses. - + Netmask. The netmask associated with this IP range. - + VLAN. The VLAN that will be used for public traffic. - + Start IP/End IP. A range of IP addresses that are assumed to be accessible from the Internet and will be allocated for access to guest VMs. - 7. + 7. In a new zone, CloudStack adds the first pod for you. You can always add more pods later. For an overview of what a pod is, see Section 2.2, “About Pods”. To configure the first pod, enter the following, then click Next: - + Pod Name. A name for the pod. - + Reserved system gateway. The gateway for the hosts in that pod. - + Reserved system netmask. The network prefix that defines the pod's subnet. Use CIDR notation. - + Start/End Reserved System IP. The IP range in the management network that CloudStack uses to manage various system VMs, such as Secondary Storage VMs, Console Proxy VMs, and DHCP. For more information, see System Reserved IP Addresses. - 8. + 8. Configure the network for guest traffic. Provide the following, then click Next: - + Guest gateway. The gateway that the guests should use. - + Guest netmask. The netmask in use on the subnet the guests will use. - + Guest start IP/End IP. Enter the first and last IP addresses that define a range that CloudStack can assign to guests. - + We strongly recommend the use of multiple NICs. If multiple NICs are used, they may be in a different subnet. - + If one NIC is used, these IPs should be in the same CIDR as the pod CIDR. - 9. + 9. In a new pod, CloudStack adds the first cluster for you. You can always add more clusters later. For an overview of what a cluster is, see About Clusters. To configure the first cluster, enter the following, then click Next: - + Hypervisor. (Version 3.0.0 only; in 3.0.1, this field is read only) Choose the type of hypervisor software that all hosts in this cluster will run. If you choose VMware, additional fields appear so you can give information about a vSphere cluster. For vSphere servers, we recommend creating the cluster of hosts in vCenter and then adding the entire cluster to CloudStack. See Add Cluster: vSphere. - + Cluster name. Enter a name for the cluster. This can be text of your choosing and is not used by CloudStack. - 10. + 10. In a new cluster, CloudStack adds the first host for you. You can always add more hosts later. For an overview of what a host is, see About Hosts. - Note + Note When you add a hypervisor host to CloudStack, the host must not have any VMs already running. Before you can configure the host, you need to install the hypervisor software on the host. You will need to know which version of the hypervisor software version is supported by CloudStack and what additional configuration is required to ensure the host will work with CloudStack. To find these installation details, see: - + Citrix XenServer Installation and Configuration - + VMware vSphere Installation and Configuration - + KVM vSphere Installation and Configuration To configure the first host, enter the following, then click Next: - + Host Name. The DNS name or IP address of the host. - + Username. The username is root. - + Password. This is the password for the user named above (from your XenServer or KVM install). - + Host Tags. (Optional) Any labels that you use to categorize hosts for ease of maintenance. For example, you can set this to the cloud's HA tag (set in the ha.tag global configuration parameter) if you want this host to be used only for VMs with the "high availability" feature enabled. For more information, see HA-Enabled Virtual Machines as well as HA for Hosts. - 11. + 11. In a new cluster, CloudPlatform adds the first primary storage server for you. You can always add more servers later. For an overview of what primary storage is, see About Primary Storage. To configure the first primary storage server, enter the following, then click Next: - + Name. The name of the storage device. - + Protocol. For XenServer, choose either NFS, iSCSI, or PreSetup. For KVM, choose NFS, SharedMountPoint,CLVM, or RBD. For vSphere choose either VMFS (iSCSI or FiberChannel) or NFS. The remaining fields in the screen vary depending on what you choose here. - Advanced Zone Configuration7.2.2. Advanced Zone Configuration1. + Advanced Zone Configuration7.2.2. Advanced Zone Configuration1. After you select Advanced in the Add Zone wizard and click Next, you will be asked to enter the following details. Then click Next. - + Name. A name for the zone. - + DNS 1 and 2. These are DNS servers for use by guest VMs in the zone. These DNS servers will be accessed via the public network you will add later. The public IP addresses for the zone must have a route to the DNS server named here. - + Internal DNS 1 and Internal DNS 2. These are DNS servers for use by system VMs in the zone(these are VMs used by CloudStack itself, such as virtual routers, console proxies,and Secondary Storage VMs.) These DNS servers will be accessed via the management traffic network interface of the System VMs. The private IP address you provide for the pods must have a route to the internal DNS server named here. - + Network Domain. (Optional) If you want to assign a special domain name to the guest VM network, specify the DNS suffix. - + Guest CIDR. This is the CIDR that describes the IP addresses in use in the guest virtual networks in this zone. For example, 10.1.1.0/24. As a matter of good practice you should set different CIDRs for different zones. This will make it easier to set up VPNs between networks in different zones. - + Hypervisor. (Introduced in version 3.0.1) Choose the hypervisor for the first cluster in the zone. You can add clusters with different hypervisors later, after you finish adding the zone. - + Public. A public zone is available to all users. A zone that is not public will be assigned to a particular domain. Only users in that domain will be allowed to create guest VMs in this zone. - 2. + 2. Choose which traffic types will be carried by the physical network. The traffic types are management, public, guest, and storage traffic. For more information about the types, roll over the icons to display their tool tips, or see Section 2.7.4, “Advanced Zone Network Traffic Types”. This screen starts out with one network already configured. If you have multiple physical networks, you need to add more. Drag and drop traffic types onto a greyed-out network and it will become active. You can move the traffic icons from one network to another; for example, if the default traffic types shown for Network 1 do not match your actual setup, you can move them down. You can also change the network names if desired. - 3. + 3. (Introduced in version 3.0.1) Assign a network traffic label to each traffic type on each physical network. These labels must match the labels you have already defined on the hypervisor host. To assign each label, click the Edit button under the traffic type icon within each physical network. A popup dialog appears where you can type the label, then click OK. These traffic labels will be defined only for the hypervisor selected for the first cluster. For all other hypervisors, the labels can be configured after the zone is created. - 4. + 4. Click Next. - 5. + 5. Configure the IP range for public Internet traffic. Enter the following details, then click Add. If desired, you can repeat this step to add more public Internet IP ranges. When done, click Next. - + Gateway. The gateway in use for these IP addresses. - + Netmask. The netmask associated with this IP range. - + VLAN. The VLAN that will be used for public traffic. - + Start IP/End IP. A range of IP addresses that are assumed to be accessible from the Internet and will be allocated for access to guest networks. - 6. + 6. In a new zone, CloudStack adds the first pod for you. You can always add more pods later. For an overview of what a pod is, see Section 2.2, “About Pods”. To configure the first pod, enter the following, then click Next: - + Pod Name. A name for the pod. - + Reserved system gateway. The gateway for the hosts in that pod. - + Reserved system netmask. The network prefix that defines the pod's subnet. Use CIDR notation. - + Start/End Reserved System IP. The IP range in the management network that CloudStack uses to manage various system VMs, such as Secondary Storage VMs, Console Proxy VMs, and DHCP. For more information, see Section 2.7.7, “System Reserved IP Addresses”. - 7. + 7. Specify a range of VLAN IDs to carry guest traffic for each physical network (see VLAN Allocation Example ), then click Next. - 8. + 8. In a new pod, CloudStack adds the first cluster for you. You can always add more clusters later. For an overview of what a cluster is, see Section 2.3, “About Clusters”. To configure the first cluster, enter the following, then click Next: - + Hypervisor. (Version 3.0.0 only; in 3.0.1, this field is read only) Choose the type of hypervisor software that all hosts in this cluster will run. If you choose VMware, additional fields appear so you can give information about a vSphere cluster. For vSphere servers, we recommend creating the cluster of hosts in vCenter and then adding the entire cluster to CloudStack. See Add Cluster: vSphere . - + Cluster name. Enter a name for the cluster. This can be text of your choosing and is not used by CloudStack. - 9. + 9. In a new cluster, CloudStack adds the first host for you. You can always add more hosts later. For an overview of what a host is, see Section 2.4, “About Hosts”. - Note + Note When you deploy CloudStack, the hypervisor host must not have any VMs already running. Before you can configure the host, you need to install the hypervisor software on the host. You will need to know which version of the hypervisor software version is supported by CloudStack and what additional configuration is required to ensure the host will work with CloudStack. To find these installation details, see: - + Citrix XenServer Installation for CloudStack - + VMware vSphere Installation and Configuration - + KVM Installation and Configuration To configure the first host, enter the following, then click Next: - + Host Name. The DNS name or IP address of the host. - + Username. Usually root. - + Password. This is the password for the user named above (from your XenServer or KVM install). - + Host Tags. (Optional) Any labels that you use to categorize hosts for ease of maintenance. For example, you can set to the cloud's HA tag (set in the ha.tag global configuration parameter) if you want this host to be used only for VMs with the "high availability" feature enabled. For more information, see HA-Enabled Virtual Machines as well as HA for Hosts, both in the Administration Guide. - 10. + 10. In a new cluster, CloudStack adds the first primary storage server for you. You can always add more servers later. For an overview of what primary storage is, see Section 2.5, “About Primary Storage”. To configure the first primary storage server, enter the following, then click Next: - + Name. The name of the storage device. - + Protocol. For XenServer, choose either NFS, iSCSI, or PreSetup. For KVM, choose NFS, SharedMountPoint, CLVM, and RBD. For vSphere choose either VMFS (iSCSI or FiberChannel) or NFS. The remaining fields in the screen vary depending on what you choose here. - + NFS - + Server. The IP address or DNS name of the storage device. - + Path. The exported path from the server. - + Tags (optional). The comma-separated list of tags for this storage device. It should be an equivalent set or superset of the tags on your disk offerings. @@ -1214,13 +1214,13 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 iSCSI - + Server. The IP address or DNS name of the storage device. - + Target IQN. The IQN of the target. For example, iqn.1986-03.com.sun:02:01ec9bb549-1271378984. - + Lun. The LUN number. For example, 3. - + Tags (optional). The comma-separated list of tags for this storage device. It should be an equivalent set or superset of the tags on your disk offerings. @@ -1232,11 +1232,11 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 preSetup - + Server. The IP address or DNS name of the storage device. - + SR Name-Label. Enter the name-label of the SR that has been set up outside CloudStack. - + Tags (optional). The comma-separated list of tags for this storage device. It should be an equivalent set or superset of the tags on your disk offerings. @@ -1248,9 +1248,9 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 SharedMountPoint - + Path. The path on each host that is where this primary storage is mounted. For example, "/mnt/primary". - + Tags (optional). The comma-separated list of tags for this storage device. It should be an equivalent set or superset of the tags on your disk offerings. @@ -1262,284 +1262,284 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 VMFS - + Server. The IP address or DNS name of the vCenter server. - + Path. A combination of the datacenter name and the datastore name. The format is "/" datacenter name "/" datastore name. For example, "/cloud.dc.VM/cluster1datastore". - + Tags (optional). The comma-separated list of tags for this storage device. It should be an equivalent set or superset of the tags on your disk offerings. The tag sets on primary storage across clusters in a Zone must be identical. For example, if cluster A provides primary storage that has tags T1 and T2, all other clusters in the Zone must also provide primary storage that has tags T1 and T2. - 11. + 11. In a new zone, CloudStack adds the first secondary storage server for you. For an overview of what secondary storage is, see Section 2.6, “About Secondary Storage”. Before you can fill out this screen, you need to prepare the secondary storage by setting up NFS shares and installing the latest CloudStack System VM template. See Adding Secondary Storage : - + NFS Server. The IP address of the server. - + Path. The exported path from the server. - 12. + 12. Click Launch. Adding a Pod7.3. Adding a Pod When you created a new zone, CloudStack adds the first pod for you. You can add more pods at any time using the procedure in this section. - 1. + 1. Log in to the CloudStack UI. See Section 5.1, “Log In to the UI”. - 2. + 2. In the left navigation, choose Infrastructure. In Zones, click View More, then click the zone to which you want to add a pod. - 3. + 3. Click the Compute and Storage tab. In the Pods node of the diagram, click View All. - 4. + 4. Click Add Pod. - 5. + 5. Enter the following details in the dialog. - + Name. The name of the pod. - + Gateway. The gateway for the hosts in that pod. - + Netmask. The network prefix that defines the pod's subnet. Use CIDR notation. - + Start/End Reserved System IP. The IP range in the management network that CloudStack uses to manage various system VMs, such as Secondary Storage VMs, Console Proxy VMs, and DHCP. For more information, see System Reserved IP Addresses. - 6. + 6. Click OK. Adding a Cluster7.4. Adding a Cluster You need to tell CloudStack about the hosts that it will manage. Hosts exist inside clusters, so before you begin adding hosts to the cloud, you must add at least one cluster. Add Cluster: KVM or XenServer7.4.1. Add Cluster: KVM or XenServer These steps assume you have already installed the hypervisor on the hosts and logged in to the CloudStack UI. - 1. + 1. In the left navigation, choose Infrastructure. In Zones, click View More, then click the zone in which you want to add the cluster. - 2. + 2. Click the Compute tab. - 3. + 3. In the Clusters node of the diagram, click View All. - 4. + 4. Click Add Cluster. - 5. + 5. Choose the hypervisor type for this cluster. - 6. + 6. Choose the pod in which you want to create the cluster. - 7. + 7. Enter a name for the cluster. This can be text of your choosing and is not used by CloudStack. - 8. + 8. Click OK. Add Cluster: vSphere7.4.2. Add Cluster: vSphere Host management for vSphere is done through a combination of vCenter and the CloudStack admin UI. CloudStack requires that all hosts be in a CloudStack cluster, but the cluster may consist of a single host. As an administrator you must decide if you would like to use clusters of one host or of multiple hosts. Clusters of multiple hosts allow for features like live migration. Clusters also require shared storage such as NFS or iSCSI. For vSphere servers, we recommend creating the cluster of hosts in vCenter and then adding the entire cluster to CloudStack. Follow these requirements: - + Do not put more than 8 hosts in a vSphere cluster - + Make sure the hypervisor hosts do not have any VMs already running before you add them to CloudStack. To add a vSphere cluster to CloudStack: - 1. + 1. Create the cluster of hosts in vCenter. Follow the vCenter instructions to do this. You will create a cluster that looks something like this in vCenter. - 2. + 2. Log in to the UI. - 3. + 3. In the left navigation, choose Infrastructure. In Zones, click View More, then click the zone in which you want to add the cluster. - 4. + 4. Click the Compute tab, and click View All on Pods. Choose the pod to which you want to add the cluster. - 5. + 5. Click View Clusters. - 6. + 6. Click Add Cluster. - 7. + 7. In Hypervisor, choose VMware. - 8. + 8. Provide the following information in the dialog. The fields below make reference to values from vCenter. - + Cluster Name. Enter the name of the cluster you created in vCenter. For example, "cloud.cluster.2.2.1" - + vCenter Host. Enter the hostname or IP address of the vCenter server. - + vCenter Username. Enter the username that CloudStack should use to connect to vCenter. This user must have all administrative privileges. - + vCenter Password. Enter the password for the user named above - + vCenter Datacenter. Enter the vCenter datacenter that the cluster is in. For example, "cloud.dc.VM". - + There might be a slight delay while the cluster is provisioned. It will automatically display in the UI - Adding a Host7.5. Adding a Host1. + Adding a Host7.5. Adding a Host1. Before adding a host to the CloudStack configuration, you must first install your chosen hypervisor on the host. CloudStack can manage hosts running VMs under a variety of hypervisors. The CloudStack Installation Guide provides instructions on how to install each supported hypervisor and configure it for use with CloudStack. See the appropriate section in the Installation Guide for information about which version of your chosen hypervisor is supported, as well as crucial additional steps to configure the hypervisor hosts for use with CloudStack. - Warning + Warning Be sure you have performed the additional CloudStack-specific configuration steps described in the hypervisor installation section for your particular hypervisor. - 2. + 2. Now add the hypervisor host to CloudStack. The technique to use varies depending on the hypervisor. - + Section 7.5.1, “Adding a Host (XenServer or KVM)” - + Section 7.5.2, “Adding a Host (vSphere)” Adding a Host (XenServer or KVM)7.5.1. Adding a Host (XenServer or KVM) XenServer and KVM hosts can be added to a cluster at any time. - 7.5.1.1. Requirements for XenServer and KVM HostsWarning + 7.5.1.1. Requirements for XenServer and KVM HostsWarning Make sure the hypervisor host does not have any VMs already running before you add it to CloudStack. Configuration requirements: - + Each cluster must contain only hosts with the identical hypervisor. - + For XenServer, do not put more than 8 hosts in a cluster. - + For KVM, do not put more than 16 hosts in a cluster. For hardware requirements, see the installation section for your hypervisor in the CloudStack Installation Guide. - 7.5.1.1.1. XenServer Host Additional Requirements + 7.5.1.1.1. XenServer Host Additional Requirements If network bonding is in use, the administrator must cable the new host identically to other hosts in the cluster. For all additional hosts to be added to the cluster, run the following command. This will cause the host to join the master in a XenServer pool. - # xe pool-join master-address=[master IP] master-username=root master-password=[your password]Note + # xe pool-join master-address=[master IP] master-username=root master-password=[your password]Note When copying and pasting a command, be sure the command has pasted as a single line before executing. Some document viewers may introduce unwanted line breaks in copied text. With all hosts added to the XenServer pool, run the cloud-setup-bond script. This script will complete the configuration and setup of the bonds on the new hosts in the cluster. - 1. + 1. Copy the script from the Management Server in /usr/lib64/cloud/common/scripts/vm/hypervisor/xenserver/cloud-setup-bonding.sh to the master host and ensure it is executable. - 2. + 2. Run the script: - # ./cloud-setup-bonding.sh7.5.1.1.2. KVM Host Additional Requirements + # ./cloud-setup-bonding.sh7.5.1.1.2. KVM Host Additional Requirements If shared mountpoint storage is in use, the administrator should ensure that the new host has all the same mountpoints (with storage mounted) as the other hosts in the cluster. - + Make sure the new host has the same network configuration (guest, private, and public network) as other hosts in the cluster. - 7.5.1.2. Adding a XenServer or KVM Host + 7.5.1.2. Adding a XenServer or KVM Host If you have not already done so, install the hypervisor software on the host. You will need to know which version of the hypervisor software version is supported by CloudStack and what additional configuration is required to ensure the host will work with CloudStack. To find these installation details, see the appropriate section for your hypervisor in the CloudStack Installation Guide. - + Log in to the CloudStack UI as administrator. - + In the left navigation, choose Infrastructure. In Zones, click View More, then click the zone in which you want to add the host. - + Click the Compute tab. In the Clusters node, click View All. - + Click the cluster where you want to add the host. - + Click View Hosts. - + Click Add Host. - + Provide the following information. - + Host Name. The DNS name or IP address of the host. - + Username. Usually root. - + Password. This is the password for the user from your XenServer or KVM install). - + Host Tags (Optional). Any labels that you use to categorize hosts for ease of maintenance. For example, you can set to the cloud's HA tag (set in the ha.tag global configuration parameter) if you want this host to be used only for VMs with the "high availability" feature enabled. For more information, see HA-Enabled Virtual Machines as well as HA for Hosts. There may be a slight delay while the host is provisioned. It should automatically display in the UI. - + Repeat for additional hosts. Adding a Host (vSphere)7.5.2. Adding a Host (vSphere) For vSphere servers, we recommend creating the cluster of hosts in vCenter and then adding the entire cluster to CloudStack. See Add Cluster: vSphere. Add Primary Storage7.6. Add Primary StorageSystem Requirements for Primary Storage7.6.1. System Requirements for Primary Storage Hardware requirements: - + Any standards-compliant iSCSI or NFS server that is supported by the underlying hypervisor. - + The storage server should be a machine with a large number of disks. The disks should ideally be managed by a hardware RAID controller. - + Minimum required capacity depends on your needs. When setting up primary storage, follow these restrictions: - + Primary storage cannot be added until a host has been added to the cluster. - + If you do not provision shared primary storage, you must set the global configuration parameter system.vm.local.storage.required to true, or else you will not be able to start VMs. Adding Primary Stroage7.6.2. Adding Primary Stroage When you create a new zone, the first primary storage is added as part of that procedure. You can add primary storage servers at any time, such as when adding a new cluster or adding more servers to an existing cluster. - Warning + Warning Be sure there is nothing stored on the server. Adding the server to CloudStack will destroy any existing data. - 1. + 1. Log in to the CloudStack UI (see Section 5.1, “Log In to the UI”). - 2. + 2. In the left navigation, choose Infrastructure. In Zones, click View More, then click the zone in which you want to add the primary storage. - 3. + 3. Click the Compute tab. - 4. + 4. In the Primary Storage node of the diagram, click View All. - 5. + 5. Click Add Primary Storage. - 6. + 6. Provide the following information in the dialog. The information required varies depending on your choice in Protocol. - + Pod. The pod for the storage device. - + Cluster. The cluster for the storage device. - + Name. The name of the storage device. - + Protocol. For XenServer, choose either NFS, iSCSI, or PreSetup. For KVM, choose NFS or SharedMountPoint. For vSphere choose either VMFS (iSCSI or FiberChannel) or NFS. - + Server (for NFS, iSCSI, or PreSetup). The IP address or DNS name of the storage device. - + Server (for VMFS). The IP address or DNS name of the vCenter server. - + Path (for NFS). In NFS this is the exported path from the server. - + Path (for VMFS). In vSphere this is a combination of the datacenter name and the datastore name. The format is "/" datacenter name "/" datastore name. For example, "/cloud.dc.VM/cluster1datastore". - + Path (for SharedMountPoint). With KVM this is the path on each host that is where this primary storage is mounted. For example, "/mnt/primary". - + SR Name-Label (for PreSetup). Enter the name-label of the SR that has been set up outside CloudStack. - + Target IQN (for iSCSI). In iSCSI this is the IQN of the target. For example, iqn.1986-03.com.sun:02:01ec9bb549-1271378984. - + Lun # (for iSCSI). In iSCSI this is the LUN number. For example, 3. - + Tags (optional). The comma-separated list of tags for this storage device. It should be an equivalent set or superset of the tags on your disk offerings.. The tag sets on primary storage across clusters in a Zone must be identical. For example, if cluster A provides primary storage that has tags T1 and T2, all other clusters in the Zone must also provide primary storage that has tags T1 and T2. - 7. + 7. Click OK. - Add Secondary Storage7.7. Add Secondary StorageSystem Requirements for Secondary Storage7.7.1. System Requirements for Secondary Storage + Add Secondary Storage7.7. Add Secondary StorageSystem Requirements for Secondary Storage7.7.1. System Requirements for Secondary Storage NFS storage appliance or Linux NFS server - + (Optional) OpenStack Object Storage (Swift) (see http://swift.openstack.org) - + 100GB minimum capacity - + A secondary storage device must be located in the same zone as the guest VMs it serves. - + Each Secondary Storage server must be available to all hosts in the zone. Adding Secondary Storage7.7.2. Adding Secondary Storage When you create a new zone, the first secondary storage is added as part of that procedure. You can add secondary storage servers at any time to add more servers to an existing zone. - Warning + Warning Be sure there is nothing stored on the server. Adding the server to CloudStack will destroy any existing data. - 1. + 1. If you are going to use Swift for cloud-wide secondary storage, you must add the Swift storage to CloudStack before you add the local zone secondary storage servers. See Section 7.2, “Adding a Zone”. - 2. + 2. To prepare for local zone secondary storage, you should have created and mounted an NFS share during Management Server installation. See Preparing NFS Shares in the Installation Guide. - 3. + 3. Make sure you prepared the system VM template during Management Server installation. See Prepare the System VM Template in the Installation Guide. - 4. + 4. Now that the secondary storage server for per-zone storage is prepared, add it to CloudStack. Secondary storage is added as part of the procedure for adding a new zone. See Section 7.2, “Adding a Zone”. Initialize and Test7.8. Initialize and Test After everything is configured, CloudStack will perform its initialization. This can take 30 minutes or more, depending on the speed of your network. When the initialization has completed successfully, the administrator's Dashboard should be displayed in the CloudStack UI. - 1. + 1. Verify that the system is ready. In the left navigation bar, select Templates. Click on the CentOS 5.5 (64bit) no Gui (KVM) template. Check to be sure that the status is "Download Complete." Do not proceed to the next step until this status is displayed. - 2. + 2. Go to the Instances tab, and filter by My Instances. - 3. + 3. Click Add Instance and follow the steps in the wizard. - a. + a. Choose the zone you just added. - b. + b. In the template selection, choose the template to use in the VM. If this is a fresh installation, likely only the provided CentOS template is available. - c. + c. Select a service offering. Be sure that the hardware you have allows starting the selected service offering. - d. + d. In data disk offering, if desired, add another data disk. This is a second volume that will be available to but not mounted in the guest. For example, in Linux on XenServer you will see /dev/xvdb in the guest after rebooting the VM. A reboot is not required if you have a PV-enabled OS kernel in use. - e. + e. In default network, choose the primary network for the guest. In a trial installation, you would have only one option here. - f. + f. Optionally give your VM a name and a group. Use any descriptive text you would like. - g. + g. Click Launch VM. Your VM will be created and started. It might take some time to download the template and complete the VM startup. You can watch the VM’s progress in the Instances screen. - 4. + 4. To use the VM, click the View Console button. @@ -1551,93 +1551,93 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 In this chapter we discuss compute, disk, and system service offerings. Network offerings are discussed in the section on setting up networking for users. Compute and Disk Service Offerings8.1. Compute and Disk Service Offerings A service offering is a set of virtual hardware features such as CPU core count and speed, memory, and disk size. The CloudStack administrator can set up various offerings, and then end users choose from the available offerings when they create a new VM. A service offering includes the following elements: - + CPU, memory, and network resource guarantees - + How resources are metered - + How the resource usage is charged - + How often the charges are generated For example, one service offering might allow users to create a virtual machine instance that is equivalent to a 1 GHz Intel® Core™ 2 CPU, with 1 GB memory at $0.20/hour, with network traffic metered at $0.10/GB. Based on the user’s selected offering, CloudStack emits usage records that can be integrated with billing systems. CloudStack separates service offerings into compute offerings and disk offerings. The computing service offering specifies: - + Guest CPU - + Guest RAM - + Guest Networking type (virtual or direct) - + Tags on the root disk The disk offering specifies: - + Disk size (optional). An offering without a disk size will allow users to pick their own - + Tags on the data disk Creating a New Compute Offering8.1.1. Creating a New Compute Offering To create a new compute offering: - 1. + 1. Log in with admin privileges to the CloudStack UI. - 2. + 2. In the left navigation bar, click Service Offerings. - 3. + 3. In Select Offering, choose Compute Offering. - 4. + 4. Click Add Compute Offering. - 5. + 5. In the dialog, make the following choices: - + Name: Any desired name for the service offering. - + Description: A short description of the offering that can be displayed to users - + Storage type: The type of disk that should be allocated. Local allocates from storage attached directly to the host where the system VM is running. Shared allocates from storage accessible via NFS. - + # of CPU cores: The number of cores which should be allocated to a system VM with this offering - + CPU (in MHz): The CPU speed of the cores that the system VM is allocated. For example, “2000” would provide for a 2 GHz clock. - + Memory (in MB): The amount of memory in megabytes that the system VM should be allocated. For example, “2048” would provide for a 2 GB RAM allocation. - + Network Rate: Allowed data transfer rate in MB per second. - + Offer HA: If yes, the administrator can choose to have the system VM be monitored and as highly available as possible. - + Storage Tags: The tags that should be associated with the primary storage used by the system VM. - + Host Tags: (Optional) Any tags that you use to organize your hosts - + CPU cap: Whether to limit the level of CPU usage even if spare capacity is available. - + Public: Indicate whether the service offering should be available all domains or only some domains. Choose Yes to make it available to all domains. Choose No to limit the scope to a subdomain; CloudStack will then prompt for the subdomain's name. - 6. + 6. Click Add. Creating a New Disk Offering8.1.2. Creating a New Disk Offering To create a system service offering: - 1. + 1. Log in with admin privileges to the CloudStack UI. - 2. + 2. In the left navigation bar, click Service Offerings. - 3. + 3. In Select Offering, choose Disk Offering. - 4. + 4. Click Add Disk Offering. - 5. + 5. In the dialog, make the following choices: - + Name. Any desired name for the system offering. - + Description. A short description of the offering that can be displayed to users - + Custom Disk Size. If checked, the user can set their own disk size. If not checked, the root administrator must define a value in Disk Size. - + Disk Size. Appears only if Custom Disk Size is not selected. Define the volume size in GB. - + (Optional)Storage Tags. The tags that should be associated with the primary storage for this disk. Tags are a comma separated list of attributes of the storage. For example "ssd,blue". Tags are also added on Primary Storage. CloudStack matches tags on a disk offering to tags on the storage. If a tag is present on a disk offering that tag (or tags) must also be present on Primary Storage for the volume to be provisioned. If no such primary storage exists, allocation from the disk offering will fail.. - + Public. Indicate whether the service offering should be available all domains or only some domains. Choose Yes to make it available to all domains. Choose No to limit the scope to a subdomain; CloudStack will then prompt for the subdomain's name. - 6. + 6. Click Add. Modifying or Deleting a Service Offering8.1.3. Modifying or Deleting a Service Offering Service offerings cannot be changed once created. This applies to both compute offerings and disk offerings. @@ -1649,41 +1649,41 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 When CloudStack creates a virtual router for a guest network, it uses default settings which are defined in the system service offering associated with the network offering. You can upgrade the capabilities of the virtual router by applying a new network offering that contains a different system service offering. All virtual routers in that network will begin using the settings from the new service offering. Chapter 9.Chapter 9. Setting Up Networking for UsersSetting Up Networking for UsersOverview of Setting Up Networking for Users9.1. Overview of Setting Up Networking for Users People using cloud infrastructure have a variety of needs and preferences when it comes to the networking services provided by the cloud. As a CloudStack administrator, you can do the following things to set up networking for your users: - + Set up physical networks in zones - + Set up several different providers for the same service on a single physical network (for example, both Cisco and Juniper firewalls) - + Bundle different types of network services into network offerings, so users can choose the desired network services for any given virtual machine - + Add new network offerings as time goes on so end users can upgrade to a better class of service on their network - + Provide more ways for a network to be accessed by a user, such as through a project of which the user is a member About Virtual Networks9.2. About Virtual Networks A virtual network is a logical construct that enables multi-tenancy on a single physical network. In CloudStack a virtual network can be shared or isolated. Isolated Networks9.2.1. Isolated Networks An isolated network can be accessed only by virtual machines of a single account. Isolated networks have the following properties. - + Resources such as VLAN are allocated and garbage collected dynamically - + There is one network offering for the entire network - + The network offering can be upgraded or downgraded but it is for the entire network Shared Networks9.2.2. Shared Networks A shared network can be accessed by virtual machines that belong to many different accounts. Network Isolation on shared networks is accomplished using techniques such as security groups (supported only in basic zones in CloudStack 3.0.3). - + Shared Networks are created by the administrator - + Shared Networks can be designated to a certain domain - + Shared Network resources such as VLAN and physical network that it maps to are designated by the administrator - + Shared Networks are isolated by security groups - + Public Network is a shared network that is not shown to the end users Runtime Allocation of Virtual Network Resources9.2.3. Runtime Allocation of Virtual Network Resources When you define a new virtual network, all your settings for that network are stored in CloudStack. The actual network resources are activated only when the first virtual machine starts in the network. When all virtual machines have left the virtual network, the network resources are garbage collected so they can be allocated again. This helps to conserve network resources.. - Network Service Providers9.3. Network Service ProvidersNote + Network Service Providers9.3. Network Service ProvidersNote For the most up-to-date list of supported network service providers, see the CloudPlatform UI or call listNetworkServiceProviders. A service provider (also called a network element) is hardware or virtual appliance that makes a network service possible; for example, a firewall appliance can be installed in the cloud to provide firewall service. On a single network, multiple providers can provide the same network service. For example, a firewall service may be provided by Cisco or Juniper devices in the same physical network. @@ -1693,35 +1693,35 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 If different providers are set up to provide the same service on the network, the administrator can create network offerings so users can specify which network service provider they prefer (along with the other choices offered in network offerings). Otherwise, CloudPlatform will choose which provider to use whenever the service is called for. Supported Network Service Providers CloudPlatform ships with an internal list of the supported service providers, and you can choose from this list when creating a network offering. - Network Offerings9.4. Network OfferingsNote + Network Offerings9.4. Network OfferingsNote For the most up-to-date list of supported network services, see the CloudPlatform UI or call listNetworkServices. A network offering is a named set of network services, such as: - + DHCP - + DNS - + Source NAT - + Static NAT - + Port Forwarding - + Load Balancing - + Firewall - + VPN - + Optional) Name one of several available providers to use for a given service, such as Juniper for the firewall - + (Optional) Network tag to specify which physical network to use When creating a new VM, the user chooses one of the available network offerings, and that determines which network services the VM can use. The CloudPlatform administrator can create any number of custom network offerings, in addition to the default network offerings provided by CloudPlatform. By creating multiple custom network offerings, you can set up your cloud to offer different classes of service on a single multi-tenant physical network. For example, while the underlying physical wiring may be the same for two tenants, tenant A may only need simple firewall protection for their website, while tenant B may be running a web server farm and require a scalable firewall solution, load balancing solution, and alternate networks for accessing the database backend. - Note + Note If you create load balancing rules while using a network service offering that includes an external load balancer device such as NetScaler, and later change the network service offering to one that uses the CloudPlatform virtual router, you must create a firewall rule on the virtual router for each of your existing load balancing rules so that they continue to function. When creating a new virtual network, the CloudPlatform administrator chooses which network offering to enable for that network. Each virtual network is associated with one network offering. A virtual network can be upgraded or downgraded by changing its associated network offering. If you do this, be sure to reprogram the physical network to match. @@ -1731,11 +1731,11 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 CloudStack provides administrators with complete control over the lifecycle of all guest VMs executing in the cloud. CloudStack provides several guest management operations for end users and administrators. VMs may be stopped, started, rebooted, and destroyed. Guest VMs have a name and group. VM names and groups are opaque to CloudStack and are available for end users to organize their VMs. Each VM can have three names for use in different contexts. Only two of these names can be controlled by the user: - + Instance name – a unique, immutable ID that is generated by CloudStack and can not be modified by the user. This name conforms to the requirements in IETF RFC 1123. - + Display name – the name displayed in the CloudStack web UI. Can be set by the user. Defaults to instance name. - + Name – host name that the DHCP server assigns to the VM. Can be set by the user. Defaults to instance name Guest VMs can be configured to be Highly Available (HA). An HA-enabled VM is monitored by the system. If the system detects that the VM is down, it will attempt to restart the VM, possibly on a different host. For more information, see HA-Enabled Virtual Machines on @@ -1749,7 +1749,7 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 The CloudStack administrator should monitor the total number of VM instances in each cluster, and disable allocation to the cluster if the total is approaching the maximum that the hypervisor can handle. Be sure to leave a safety margin to allow for the possibility of one or more hosts failing, which would increase the VM load on the other hosts as the VMs are automatically redeployed. Consult the documentation for your chosen hypervisor to find the maximum permitted number of VMs per host, then use CloudStack global configuration settings to set this as the default limit. Monitor the VM activity in each cluster at all times. Keep the total number of VMs below a safe level that allows for the occasional host failure. For example, if there are N hosts in the cluster, and you want to allow for one host in the cluster to be down at any given time, the total number of VM instances you can permit in the cluster is at most (N-1) * (per-host-limit). Once a cluster reaches this number of VMs, use the CloudStack UI to disable allocation of more VMs to the cluster. VM Lifecycle10.3. VM Lifecycle Virtual machines can be in the following states: - + Once a virtual machine is destroyed, it cannot be recovered. All the resources used by the virtual machine will be reclaimed by the system. This includes the virtual machine’s IP address. A stop will attempt to gracefully shut down the operating system, which typically involves terminating all the running applications. If the operation system cannot be stopped, it will be forcefully terminated. This has the same effect as pulling the power cord to a physical machine. @@ -1769,53 +1769,53 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 Virtual machines are usually created from a template. Users can also create blank virtual machines. A blank virtual machine is a virtual machine without an OS template. Users can attach an ISO file and install the OS from the CD/DVD-ROM. To create a VM from a template: - 1. + 1. Log in to the CloudStack UI as an administrator or user. - 2. + 2. In the left navigation bar, click Instances. - 3. + 3. Click Add Instance. - 4. + 4. Select a template, then follow the steps in the wizard. (For more information about how the templates came to be in this list, see Working with Templates. - 5. + 5. Be sure that the hardware you have allows starting the selected service offering. - 6. + 6. Click Submit and your VM will be created and started. - Note + Note For security reason, the internal name of the VM is visible only to the root admin. - Note + Note Starting with v3.0.3, you can create a VM without starting it. You can determine whether the VM needs to be started as part of the VM deployment. A new request parameter, startVM, is introduced in the deployVm API to support this feature. For more information, see the Developer's Guide To create a VM from an ISO: - Note + Note (XenServer) Windows VMs running on XenServer require PV drivers, which may be provided in the template or added after the VM is created. The PV drivers are necessary for essential management functions such as mounting additional volumes and ISO images, live migration, and graceful shutdown. - 1. + 1. Log in to the CloudStack UI as an administrator or user. - 2. + 2. In the left navigation bar, click Instances. - 3. + 3. Click Add Instance. - 4. + 4. Select ISO Boot, and follow the steps in the wizard. - 5. + 5. Click Submit and your VM will be created and started. Accessing VMs10.5. Accessing VMs Any user can access their own virtual machines. The administrator can access all VMs running in the cloud. To access a VM through the CloudStack UI: - 1. + 1. Log in to the CloudStack UI as a user or admin. - 2. + 2. Click Instances, then click the name of a running VM. - 3. + 3. Click the View Console button . To access a VM directly over the network: - 1. + 1. The VM must have some port open to incoming traffic. For example, in a basic zone, a new VM might be assigned to a security group which allows incoming traffic. This depends on what security group you picked when creating the VM. In other cases, you can open a port by setting up a port forwarding policy. See IP Forwarding and Firewalling. - 2. + 2. If a port is open but you can not access the VM using ssh, it’s possible that ssh is not already enabled on the VM. This will depend on whether ssh is enabled in the template you picked when creating the VM. Access the VM through the CloudStack UI and enable ssh on the machine using the commands for the VM’s operating system. - 3. + 3. If the network has an external firewall device, you will need to create a firewall rule to allow access. See IP Forwarding and Firewalling. Stopping and Starting VMs10.6. Stopping and Starting VMs Any user can access their own virtual machines. The administrator can access all VMs running in the cloud. @@ -1823,89 +1823,89 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 After a VM is created, you can modify the display name, operating system, and the group it belongs to. To access a VM through the CloudStack UI: - 1. + 1. Log in to the CloudStack UI as a user or admin. - 2. + 2. In the left navigation, click Instances. - 3. + 3. Select the VM that you want to modify. - 4. + 4. Click the Stop button to stop the VM - 5. + 5. Click Edit . - 6. + 6. Make the desired changes to the following: - 7. + 7. Display name: Enter a new display name if you want to change the name of the VM. - 8. + 8. OS Type: Select the desired operating system. - 9. + 9. Group: Enter the group name for the VM. - 10. + 10. Click Apply. Changing the Service Offering for a VM10.8. Changing the Service Offering for a VM To upgrade or downgrade the level of compute resources available to a virtual machine, you can change the VM's compute offering. - 1. + 1. Log in to the CloudStack UI as a user or admin. - 2. + 2. In the left navigation, click Instances. - 3. + 3. Choose the VM that you want to work with. - 4. + 4. Click the Stop button to stop the VM - 5. + 5. Click the Change Service button . The Change service dialog box is displayed. - 6. + 6. Select the offering you want. - 7. + 7. Click OK. Moving VMs Between Hosts (Manual Live Migration)10.9. Moving VMs Between Hosts (Manual Live Migration) The CloudPlatform administrator can move a running VM from one host to another without interrupting service to users or going into maintenance mode. This is called manual live migration, and can be done under the following conditions: - + The root administrator is logged in. Domain admins and users can not perform manual live migration of VMs. - + The VM is running. Stopped VMs can not be live migrated. - + The destination host must be in the same cluster as the original host. - + The VM must not be using local disk storage. - + The destination host must have enough available capacity. If not, the VM will remain in the "migrating" state until memory becomes available. To manually live migrate a virtual machine - 1. + 1. Log in to the CloudPlatform UI as a user or admin. - 2. + 2. In the left navigation, click Instances. - 3. + 3. Choose the VM that you want to migrate. - 4. + 4. Click the Migrate Instance button - 5. + 5. From the list of hosts, choose the one to which you want to move the VM. - 6. + 6. Click OK. Deleting VMs10.10. Deleting VMs Users can delete their own virtual machines. A running virtual machine will be abruptly stopped before it is deleted. Administrators can delete any virtual machines. To delete a virtual machine: - 1. + 1. Log in to the CloudStack UI as a user or admin. - 2. + 2. In the left navigation, click Instances. - 3. + 3. Choose the VM that you want to delete. - 4. + 4. Click the Destroy Instance button @@ -1919,37 +1919,37 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 ISO images may be stored in the system and made available with a privacy level similar to templates. ISO images are classified as either bootable or not bootable. A bootable ISO image is one that contains an OS image. CloudStack allows a user to boot a guest VM off of an ISO image. Users can also attach ISO images to guest VMs. For example, this enables installing PV drivers into Windows. ISO images are not hypervisor-specific. Adding an ISO10.11.1. Adding an ISO To make additional operating system or other software available for use with guest VMs, you can add an ISO. The ISO is typically thought of as an operating system image, but you can also add ISOs for other types of software, such as desktop applications that you want to be installed as part of a template. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation bar, click Templates. - 3. + 3. In Select View, choose ISOs. - 4. + 4. Click Add ISO. - 5. + 5. In the Add ISO screen, provide the following: - + Name: Short name for the ISO image. For example, CentOS 6.2 64-bit. - + Description: Display test for the ISO image. For example, CentOS 6.2 64-bit. - + URL: The URL that hosts the ISO image. The Management Server must be able to access this location via HTTP. If needed you can place the ISO image directly on the Management Server - + Zone: Choose the zone where you want the ISO to be available, or All Zones to make it available throughout CloudStack. - + Bootable: Whether or not a guest could boot off this ISO image. For example, a CentOS ISO is bootable, a Microsoft Office ISO is not bootable. - + OS Type: This helps CloudStack and the hypervisor perform certain operations and make assumptions that improve the performance of the guest. Select one of the following. - + If the operating system of your desired ISO image is listed, choose it. - + If the OS Type of the ISO is not listed or if the ISO is not bootable, choose Other. - + (XenServer only) If you want to boot from this ISO in PV mode, choose Other PV (32-bit) or Other PV (64-bit) - + (KVM only) If you choose an OS that is PV-enabled, the VMs created from this ISO will have a SCSI (virtio) root disk. If the OS is not PV-enabled, the VMs will have an IDE root disk. The PV-enabled types are: - + Fedora 13 @@ -2006,30 +2006,30 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 Red Hat Enterprise Linux 6 - Note + Note It is not recommended to choose an older version of the OS than the version in the image. For example, choosing CentOS 5.4 to support a CentOS 6.2 image will usually not work. In these cases, choose Other. - + Extractable: Choose Yes if the ISO should be available for extraction. - + Public: Choose Yes if this ISO should be available to other users. - + Featured: Choose Yes if you would like this ISO to be more prominent for users to select. The ISO will appear in the Featured ISOs list. Only an administrator can make an ISO Featured. - 6. + 6. Click OK. The Management Server will download the ISO. Depending on the size of the ISO, this may take a long time. The ISO status column will display Ready once it has been successfully downloaded into secondary storage. Clicking Refresh updates the download percentage. - 7. + 7. Important: Wait for the ISO to finish downloading. If you move on to the next task and try to use the ISO right away, it will appear to fail. The entire ISO must be available before CloudStack can work with it. - Attaching an ISO to a VM10.11.2. Attaching an ISO to a VM1. + Attaching an ISO to a VM10.11.2. Attaching an ISO to a VM1. In the left navigation, click Instances. - 2. + 2. Choose the virtual machine you want to work with. - 3. + 3. Click the Attach ISO button - 4. + 4. In the Attach ISO dialog box, select the desired ISO. - 5. + 5. Click OK Chapter 11.Chapter 11. Working With HostsWorking With HostsAdding Hosts11.1. Adding Hosts Additional hosts can be added at any time to provide more capacity for guest VMs. For requirements and instructions, see Section 7.5, “Adding a Host”. @@ -2039,38 +2039,38 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 You can enable or disable a zone, pod, or cluster without permanently removing it from the cloud. This is useful for maintenance or when there are problems that make a portion of the cloud infrastructure unreliable. No new allocations will be made to a disabled zone, pod, or cluster until its state is returned to Enabled. When a zone, pod, or cluster is first added to the cloud, it is Disabled by default. To disable and enable a zone, pod, or cluster: - 1. + 1. Log in to the CloudStack UI as administrator - 2. + 2. In the left navigation bar, click Infrastructure. - 3. + 3. In Zones, click View More. - 4. + 4. If you are disabling or enabling a zone, find the name of the zone in the list, and click the Enable/Disable button. - 5. + 5. If you are disabling or enabling a pod or cluster, click the name of the zone that contains the pod or cluster. - 6. + 6. Click the Compute tab. - 7. + 7. In the Pods or Clusters node of the diagram, click View All. - 8. + 8. Click the pod or cluster name in the list. - 9. + 9. Click the Enable/Disable button. Removing Hosts11.4. Removing Hosts Hosts can be removed from the cloud as needed. The procedure to remove a host depends on the hypervisor type. Removing XenServer and KVM Hosts11.4.1. Removing XenServer and KVM Hosts A node cannot be removed from a cluster until it has been placed in maintenance mode. This will ensure that all of the VMs on it have been migrated to other Hosts. To remove a Host from the cloud: - 1. + 1. Place the node in maintenance mode. See Section 11.2, “Scheduled Maintenance and Maintenance Mode for Hosts”. - 2. + 2. For KVM, stop the cloud-agent service. - 3. + 3. Use the UI option to remove the node. Then you may power down the Host, re-use its IP address, re-install it, etc @@ -2080,7 +2080,7 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 You can re-install a host after placing it in maintenance mode and then removing it. If a host is down and cannot be placed in maintenance mode, it should still be removed before the re-install. Maintaining Hypervisors on Hosts11.6. Maintaining Hypervisors on Hosts When running hypervisor software on hosts, be sure all the hotfixes provided by the hypervisor vendor are applied. Track the release of hypervisor patches through your hypervisor vendor’s support channel, and apply patches as soon as possible after they are released. CloudStack will not track or notify you of required hypervisor patches. It is essential that your hosts are completely up to date with the provided hypervisor patches. The hypervisor vendor is likely to refuse to support any system that is not up to date with patches. - Note + Note The lack of up-do-date hotfixes can lead to data corruption and lost VMs. (XenServer) For more information, see Highly Recommended Hotfixes for XenServer in the CloudStack Knowledge Base11 http://docs.cloudstack.org/Knowledge_Base/Possible_VM_corruption_if_XenServer_Hotfix_is_not_Applied/Highly_Recommended_Hotfixes_for_XenServer_5.6_SP2 @@ -2088,17 +2088,17 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 The password for a XenServer Node, KVM Node, or vSphere Node may be changed in the database. Note that all Nodes in a Cluster must have the same password. To change a Node's password: - 1. + 1. Identify all hosts in the cluster. - 2. + 2. Change the password on all hosts in the cluster. Now the password for the host and the password known to CloudStack will not match. Operations on the cluster will fail until the two passwords match. - 3. + 3. Get the list of host IDs for the host in the cluster where you are changing the password. You will need to access the database to determine these host IDs. For each hostname "h" (or vSphere cluster) that you are changing the password for, execute: - mysql> select id from cloud.host where name like '%h%';4. + mysql> select id from cloud.host where name like '%h%';4. This should return a single ID. Record the set of such IDs for these hosts. - 5. + 5. Update the passwords for the host in the database. In this example, we change the passwords for hosts with IDs 5, 10, and 12 to "password". - mysql> update cloud.host set password='password' where id=5 or id=10 or id=12;Host Allocation11.8. Host Allocation + mysql> update cloud.host set password='password' where id=5 or id=10 or id=12;Host Allocation11.8. Host Allocation The system automatically picks the most appropriate host to run each virtual machine. End users may specify the zone in which the virtual machine will be created. End users do not have control over which host will run the virtual machine instance. CloudStack administrators can specify that certain hosts should have a preference for particular types of guest instances. For example, an administrator could state that a host should have a preference to run Windows guests. The default host allocator will attempt to place guests of that OS type on such hosts first. If no such host is available, the allocator will place the instance wherever there is sufficient physical capacity. @@ -2120,19 +2120,19 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 CloudStack ships with a default template. In order to present more choices to users, CloudStack administrators and users can create templates and add them to CloudStack. Creating Templates: Overview12.1. Creating Templates: Overview CloudStack ships with a default template for the CentOS operating system. There are a variety of ways to add more templates. Administrators and end users can add templates. The typical sequence of events is: - 1. + 1. Launch a VM instance that has the operating system you want. Make any other desired configuration changes to the VM. - 2. + 2. Stop the VM. - 3. + 3. Convert the volume into a template. There are other ways to add templates to CloudStack. For example, you can take a snapshot of the VM's volume and create a template from the snapshot, or import a VHD from another system into CloudStack The various techniques for creating templates are described in the next few sections. - Requirements for Templates12.2. Requirements for Templates + Requirements for Templates12.2. Requirements for Templates For XenServer, install PV drivers / Xen tools on each template that you create. This will enable live migration and clean guest shutdown. - + For vSphere, install VMware Tools on each template that you create. This will enable console view to work properly. Best Practices for Templates12.3. Best Practices for Templates If you plan to use large templates (100 GB or larger), be sure you have a 10-gigabit network to support the large templates. A slower network can lead to timeouts and other errors when large templates are used. @@ -2144,7 +2144,7 @@ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3 A default template is provided for each of XenServer, KVM, and vSphere. The templates that are downloaded depend on the hypervisor type that is available in your cloud. Each template is approximately 2.5 GB physical size. The default template includes the standard iptables rules, which will block most access to the template excluding ssh. - # iptables --list + # iptables --list Chain INPUT (policy ACCEPT) target prot opt source destination RH-Firewall-1-INPUT all -- anywhere anywhere @@ -2176,93 +2176,93 @@ REJECT all -- anywhere anywhere reject-with icmp-host- When a user marks a template as “public,” the template becomes available to all users in all accounts in the user's domain, as well as users in any other domains that have access to the Zone where the template is stored. This depends on whether the Zone, in turn, was defined as private or public. A private Zone is assigned to a single domain, and a public Zone is accessible to any domain. If a public template is created in a private Zone, it is available only to users in the domain assigned to that Zone. If a public template is created in a public Zone, it is available to all users in all domains. Creating a Template from an Existing Virtual Machine12.6. Creating a Template from an Existing Virtual Machine Once you have at least one VM set up in the way you want, you can use it as the prototype for other VMs. - 1. + 1. Create and start a virtual machine using any of the techniques given in Section 10.4, “Creating VMs”. - 2. + 2. Make any desired configuration changes on the running VM, then click Stop. - 3. + 3. Wait for the VM to stop. When the status shows Stopped, go to the next step. - 4. + 4. Click Create Template and provide the following: - + Name and Display Text. These will be shown in the UI, so choose something descriptive. - + OS Type. This helps CloudStack and the hypervisor perform certain operations and make assumptions that improve the performance of the guest. Select one of the following. - + If the operating system of the stopped VM is listed, choose it. - + If the OS type of the stopped VM is not listed, choose Other. - + If you want to boot from this template in PV mode, choose Other PV (32-bit) or Other PV (64-bit). This choice is available only for XenServere: - Note + Note Note: Generally you should not choose an older version of the OS than the version in the image. For example, choosing CentOS 5.4 to support a CentOS 6.2 image will in general not work. In those cases you should choose Other. - + Public. Choose Yes to make this template accessible to all users of this CloudStack installation. The template will appear in the Community Templates list. See Section 12.5, “Private and Public Templates”. - + Password Enabled. Choose Yes if your template has the CloudStack password change script installed. See Adding Password Management to Your Templates. - 5. + 5. Click Add. The new template will be visible in the Templates section when the template creation process has been completed. The template is then available when creating a new VM Creating a Template from a Snapshot12.7. Creating a Template from a Snapshot If you do not want to stop the VM in order to use the Create Template menu item (as described in Section 12.6, “Creating a Template from an Existing Virtual Machine”), you can create a template directly from any snapshot through the CloudStack UI. - Uploading Templates12.8. Uploading TemplatesvSphere Templates and ISOs + Uploading Templates12.8. Uploading TemplatesvSphere Templates and ISOs If you are uploading a template that was created using vSphere Client, be sure the OVA file does not contain an ISO. If it does, the deployment of VMs from the template will fail. Templates are uploaded based on a URL. HTTP is the supported access protocol. Templates are frequently large files. You can optionally gzip them to decrease upload times. To upload a template: - 1. + 1. In the left navigation bar, click Templates. - 2. + 2. Click Create Template. - 3. + 3. Provide the following: - + Name and Display Text. These will be shown in the UI, so choose something descriptive. - + URL. The Management Server will download the file from the specified URL, such as http://my.web.server/filename.vhd.gz. - + Zone. Choose the zone where you want the template to be available, or All Zones to make it available throughout CloudStack. - + OS Type: This helps CloudStack and the hypervisor perform certain operations and make assumptions that improve the performance of the guest. Select one of the following: - + If the operating system of the stopped VM is listed, choose it. - + If the OS type of the stopped VM is not listed, choose Other. - Note + Note You should not choose an older version of the OS than the version in the image. For example, choosing CentOS 5.4 to support a CentOS 6.2 image will in general not work. In those cases you should choose Other. - + Hypervisor - + Format. The format of the template upload file, such as VHD or OVA. - + Password Enabled. Choose Yes if your template has the CloudStack password change script installed. See Adding Password Management to Your Templates - + Extractable. Choose Yes if the template is available for extraction. If this option is selected, end users can download a full image of a template. - + Public. Choose Yes to make this template accessible to all users of this CloudStack installation. The template will appear in the Community Templates list. See Section 12.5, “Private and Public Templates” - + Featured. Choose Yes if you would like this template to be more prominent for users to select. The template will appear in the Featured Templates list. Only an administrator can make a template Featured. Exporting Templates12.9. Exporting Templates End users and Administrators may export templates from the CloudStack. Navigate to the template in the UI and choose the Download function from the Actions menu. Creating a Windows Template12.10. Creating a Windows Template Windows templates must be prepared with Sysprep before they can be provisioned on multiple machines. Sysprep allows you to create a generic Windows template and avoid any possible SID conflicts. - Note + Note (XenServer) Windows VMs running on XenServer require PV drivers, which may be provided in the template or added after the VM is created. The PV drivers are necessary for essential management functions such as mounting additional volumes and ISO images, live migration, and graceful shutdown. An overview of the procedure is as follows: - 1. + 1. Upload your Windows ISO. For more information, see Section 10.11.1, “Adding an ISO” - 2. + 2. Create a VM Instance with this ISO. For more information, see Section 10.4, “Creating VMs” - 3. + 3. Follow the steps in Sysprep for Windows Server 2008 R2 (below) or Sysprep for Windows Server 2003 R2, depending on your version of Windows Server - 4. + 4. The preparation steps are complete. Now you can actually create the template as described in Creating the Windows Template. System Preparation for Windows Server 2008 R212.10.1. System Preparation for Windows Server 2008 R2 For Windows 2008 R2, you run Windows System Image Manager to create a custom sysprep response XML file. Windows System Image Manager is installed as part of the Windows Automated Installation Kit (AIK). Windows AIK can be downloaded from the Microsoft Download Center at the following location: @@ -2270,95 +2270,95 @@ REJECT all -- anywhere anywhere reject-with icmp-host- http://www.microsoft.com/en-us/download/details.aspx?id=9085Microsoft Download Center. Use the following steps to run sysprep for Windows 2008 R2: - Note + Note The steps outlined here are derived from the excellent guide by Charity Shelbourne, originally published at http://blogs.technet.com/askcore/archive/2008/10/31/automating-the-oobe-process-during-windows-server-2008-sysprep-mini-setup.aspxWindows Server 2008 Sysprep Mini-Setup - 1. + 1. Download and install the Windows AIK - Note + Note Windows AIK should not be installed on the Windows 2008 R2 VM you just created. Windows AIK should not be part of the template you create. It is only used to create the sysprep answer file. - 2. + 2. Copy the install.wim file in the \sources directory of the Windows 2008 R2 installation DVD to the hard disk. This is a very large file and may take a long time to copy. Windows AIK requires the WIM file to be writable. - 3. + 3. Start the Windows System Image Manager, which is part of the Windows AIK. - 4. + 4. In the Windows Image pane, right click “Select a Windows image or catalog file” to load the install.wim file you just copied. - 5. + 5. Select the Windows 2008 R2 Edition You may be prompted with a warning that the catalog file cannot be opened. Click Yes to create a new catalog file. - 6. + 6. In the Answer File pane, right click to create a new answer file. - 7. + 7. Generate the answer file from the Windows System Image Manager using the following steps: - a. + a. The first page you need to automate is the Language and Country or Region Selection page. To automate this, expand Components in your Windows Image pane, right-click and add the Microsoft-Windows-International-Core setting to Pass 7 oobeSystem. In your Answer File pane, configure the InputLocale, SystemLocale, UILanguage, and UserLocale with the appropriate settings for your language and country or region. Should you have a question about any of these settings, you can right-click on the specific setting and select Help. This will open the appropriate CHM help file with more information, including examples on the setting you are attempting to configure. - b. + b. You need to automate the Software License Terms Selection page, otherwise known as the End-User License Agreement (EULA). To do this, expand the Microsoft-Windows-Shell-Setup component. High-light the OOBE setting, and add the setting to the Pass 7 oobeSystem. In Settings, set HideEULAPage true. - c. + c. Make sure the license key is properly set. If you use MAK key, you can just enter the MAK key on the Windows 2008 R2 VM. You need not input the MAK into the Windows System Image Manager. If you use KMS host for activation you need not enter the Product Key. Details of Windows Volume Activation can be found at http://technet.microsoft.com/en-us/library/bb892849.aspx - d. + d. You need to automate is the Change Administrator Password page. Expand the Microsoft-Windows-Shell-Setup component (if it is not still expanded), expand UserAccounts, right-click on AdministratorPassword, and add the setting to the Pass 7 oobeSystem configuration pass of your answer file. Under Settings, specify a password next to Value. - + You may read the AIK documentation and set many more options that suit your deployment. The steps above are the minimum needed to make Windows unattended setup work. - 8. + 8. Save the answer file as unattend.xml. You can ignore the warning messages that appear in the validation window. - 9. + 9. Copy the unattend.xml file into the c:\windows\system32\sysprep directory of the Windows 2008 R2 Virtual Machine - 10. + 10. Once you place the unattend.xml file in c:\windows\system32\sysprep directory, you run the sysprep tool as follows: - cd c:\Windows\System32\sysprep + cd c:\Windows\System32\sysprep sysprep.exe /oobe /generalize /shutdown The Windows 2008 R2 VM will automatically shut down after sysprep is complete. Sysprep for Windows Server 2003 R212.10.2. Sysprep for Windows Server 2003 R2 Earlier versions of Windows have a different sysprep tool. Follow these steps for Windows Server 2003 R2. - 1. + 1. Extract the content of \support\tools\deploy.cab on the Windows installation CD into a directory called c:\sysprep on the Windows 2003 R2 VM. - 2. + 2. Run c:\sysprep\setupmgr.exe to create the sysprep.inf file. - a. + a. Select Create New to create a new Answer File. - b. + b. Enter “Sysprep setup” for the Type of Setup. - c. + c. Select the appropriate OS version and edition. - d. + d. On the License Agreement screen, select “Yes fully automate the installation”. - e. + e. Provide your name and organization. - f. + f. Leave display settings at default. - g. + g. Set the appropriate time zone. - h. + h. Provide your product key. - i. + i. Select an appropriate license mode for your deployment - j. + j. Select “Automatically generate computer name”. - k. + k. Type a default administrator password. If you enable the password reset feature, the users will not actually use this password. This password will be reset by the instance manager after the guest boots up. - l. + l. Leave Network Components at “Typical Settings”. - m. + m. Select the “WORKGROUP” option. - n. + n. Leave Telephony options at default. - o. + o. Select appropriate Regional Settings. - p. + p. Select appropriate language settings. - q. + q. Do not install printers. - r. + r. Do not specify “Run Once commands”. - s. + s. You need not specify an identification string. - t. + t. Save the Answer File as c:\sysprep\sysprep.inf. - 3. + 3. Run the following command to sysprep the image: - c:\sysprep\sysprep.exe -reseal -mini -activated + c:\sysprep\sysprep.exe -reseal -mini -activated After this step the machine will automatically shut down Importing Amazon Machine Images12.11. Importing Amazon Machine Images The following procedures describe how to import an Amazon Machine Image (AMI) into CloudStack when using the XenServer hypervisor. @@ -2366,22 +2366,22 @@ sysprep.exe /oobe /generalize /shutdown Assume you have an AMI file and this file is called CentOS_6.2_x64. Assume further that you are working on a CentOS host. If the AMI is a Fedora image, you need to be working on a Fedora host initially. You need to have a XenServer host with a file-based storage repository (either a local ext3 SR or an NFS SR) to convert to a VHD once the image file has been customized on the Centos/Fedora host. - Note + Note When copying and pasting a command, be sure the command has pasted as a single line before executing. Some document viewers may introduce unwanted line breaks in copied text. - 1. + 1. Set up loopback on image file: - # mkdir -p /mnt/loop/centos62 + # mkdir -p /mnt/loop/centos62 # mount -o loop CentOS_6.2_x64 /mnt/loop/centos54 -2. +2. Install the kernel-xen package into the image. This downloads the PV kernel and ramdisk to the image. - # yum -c /mnt/loop/centos54/etc/yum.conf --installroot=/mnt/loop/centos62/ -y install kernel-xen3. + # yum -c /mnt/loop/centos54/etc/yum.conf --installroot=/mnt/loop/centos62/ -y install kernel-xen3. Create a grub entry in /boot/grub/grub.conf. - # mkdir -p /mnt/loop/centos62/boot/grub + # mkdir -p /mnt/loop/centos62/boot/grub # touch /mnt/loop/centos62/boot/grub/grub.conf # echo "" > /mnt/loop/centos62/boot/grub/grub.conf -4. +4. Determine the name of the PV kernel that has been installed into the image. - # cd /mnt/loop/centos62 + # cd /mnt/loop/centos62 # ls lib/modules/ 2.6.16.33-xenU 2.6.16-xenU 2.6.18-164.15.1.el5xen 2.6.18-164.6.1.el5.centos.plus 2.6.18-xenU-ec2-v1.0 2.6.21.7-2.fc8xen 2.6.31-302-ec2 # ls boot/initrd* @@ -2390,125 +2390,125 @@ boot/initrd-2.6.18-164.6.1.el5.centos.plus.img boot/initrd-2.6.18-164.15.1.el5xe boot/vmlinuz-2.6.18-164.15.1.el5xen boot/vmlinuz-2.6.18-164.6.1.el5.centos.plus boot/vmlinuz-2.6.18-xenU-ec2-v1.0 boot/vmlinuz-2.6.21-2952.fc8xen Xen kernels/ramdisk always end with "xen". For the kernel version you choose, there has to be an entry for that version under lib/modules, there has to be an initrd and vmlinuz corresponding to that. Above, the only kernel that satisfies this condition is 2.6.18-164.15.1.el5xen. - 5. + 5. Based on your findings, create an entry in the grub.conf file. Below is an example entry. - default=0 + default=0 timeout=5 hiddenmenu title CentOS (2.6.18-164.15.1.el5xen) root (hd0,0) kernel /boot/vmlinuz-2.6.18-164.15.1.el5xen ro root=/dev/xvda initrd /boot/initrd-2.6.18-164.15.1.el5xen.img -6. +6. Edit etc/fstab, changing “sda1” to “xvda” and changing “sdb” to “xvdb”. - # cat etc/fstab + # cat etc/fstab /dev/xvda / ext3 defaults 1 1 /dev/xvdb /mnt ext3 defaults 0 0 none /dev/pts devpts gid=5,mode=620 0 0 none /proc proc defaults 0 0 none /sys sysfs defaults 0 0 -7. +7. Enable login via the console. The default console device in a XenServer system is xvc0. Ensure that etc/inittab and etc/securetty have the following lines respectively: - # grep xvc0 etc/inittab + # grep xvc0 etc/inittab co:2345:respawn:/sbin/agetty xvc0 9600 vt100-nav # grep xvc0 etc/securetty xvc0 -8. +8. Ensure the ramdisk supports PV disk and PV network. Customize this for the kernel version you have determined above. - # chroot /mnt/loop/centos54 + # chroot /mnt/loop/centos54 # cd /boot/ # mv initrd-2.6.18-164.15.1.el5xen.img initrd-2.6.18-164.15.1.el5xen.img.bak # mkinitrd -f /boot/initrd-2.6.18-164.15.1.el5xen.img --with=xennet --preload=xenblk --omit-scsi-modules 2.6.18-164.15.1.el5xen -9. +9. Change the password. - # passwd + # passwd Changing password for user root. New UNIX password: Retype new UNIX password: passwd: all authentication tokens updated successfully. -10. +10. Exit out of chroot. - # exit11. + # exit11. Check etc/ssh/sshd_config for lines allowing ssh login using a password. - # egrep "PermitRootLogin|PasswordAuthentication" /mnt/loop/centos54/etc/ssh/sshd_config + # egrep "PermitRootLogin|PasswordAuthentication" /mnt/loop/centos54/etc/ssh/sshd_config PermitRootLogin yes PasswordAuthentication yes -12. +12. If you need the template to be enabled to reset passwords from the CloudStack UI or API, install the password change script into the image at this point. See Section 12.13, “Adding Password Management to Your Templates”. - 13. + 13. Unmount and delete loopback mount. - # umount /mnt/loop/centos54 + # umount /mnt/loop/centos54 # losetup -d /dev/loop0 -14. +14. Copy the image file to your XenServer host's file-based storage repository. In the example below, the Xenserver is "xenhost". This XenServer has an NFS repository whose uuid is a9c5b8c8-536b-a193-a6dc-51af3e5ff799. - # scp CentOS_6.2_x64 xenhost:/var/run/sr-mount/a9c5b8c8-536b-a193-a6dc-51af3e5ff799/15. + # scp CentOS_6.2_x64 xenhost:/var/run/sr-mount/a9c5b8c8-536b-a193-a6dc-51af3e5ff799/15. Log in to the Xenserver and create a VDI the same size as the image. - [root@xenhost ~]# cd /var/run/sr-mount/a9c5b8c8-536b-a193-a6dc-51af3e5ff799 + [root@xenhost ~]# cd /var/run/sr-mount/a9c5b8c8-536b-a193-a6dc-51af3e5ff799 [root@xenhost a9c5b8c8-536b-a193-a6dc-51af3e5ff799]# ls -lh CentOS_6.2_x64 -rw-r--r-- 1 root root 10G Mar 16 16:49 CentOS_6.2_x64 [root@xenhost a9c5b8c8-536b-a193-a6dc-51af3e5ff799]# xe vdi-create virtual-size=10GiB sr-uuid=a9c5b8c8-536b-a193-a6dc-51af3e5ff799 type=user name-label="Centos 6.2 x86_64" cad7317c-258b-4ef7-b207-cdf0283a7923 -16. +16. Import the image file into the VDI. This may take 10–20 minutes. - [root@xenhost a9c5b8c8-536b-a193-a6dc-51af3e5ff799]# xe vdi-import filename=CentOS_6.2_x64 uuid=cad7317c-258b-4ef7-b207-cdf0283a792317. + [root@xenhost a9c5b8c8-536b-a193-a6dc-51af3e5ff799]# xe vdi-import filename=CentOS_6.2_x64 uuid=cad7317c-258b-4ef7-b207-cdf0283a792317. Locate a the VHD file. This is the file with the VDI’s UUID as its name. Compress it and upload it to your web server. - [root@xenhost a9c5b8c8-536b-a193-a6dc-51af3e5ff799]# bzip2 -c cad7317c-258b-4ef7-b207-cdf0283a7923.vhd > CentOS_6.2_x64.vhd.bz2 + [root@xenhost a9c5b8c8-536b-a193-a6dc-51af3e5ff799]# bzip2 -c cad7317c-258b-4ef7-b207-cdf0283a7923.vhd > CentOS_6.2_x64.vhd.bz2 [root@xenhost a9c5b8c8-536b-a193-a6dc-51af3e5ff799]# scp CentOS_6.2_x64.vhd.bz2 webserver:/var/www/html/templates/ Converting a Hyper-V VM to a Template12.12. Converting a Hyper-V VM to a Template To convert a Hyper-V VM to a XenServer-compatible CloudStack template, you will need a standalone XenServer host with an attached NFS VHD SR. Use whatever XenServer version you are using with CloudStack, but use XenCenter 5.6 FP1 or SP2 (it is backwards compatible to 5.6). Additionally, it may help to have an attached NFS ISO SR. For Linux VMs, you may need to do some preparation in Hyper-V before trying to get the VM to work in XenServer. Clone the VM and work on the clone if you still want to use the VM in Hyper-V. Uninstall Hyper-V Integration Components and check for any references to device names in /etc/fstab: - 1. + 1. From the linux_ic/drivers/dist directory, run make uninstall (where "linux_ic" is the path to the copied Hyper-V Integration Components files). - 2. + 2. Restore the original initrd from backup in /boot/ (the backup is named *.backup0). - 3. + 3. Remove the "hdX=noprobe" entries from /boot/grub/menu.lst. - 4. + 4. Check /etc/fstab for any partitions mounted by device name. Change those entries (if any) to mount by LABEL or UUID (get that information with the "blkid" command).. The next step is make sure the VM is not running in Hyper-V, then get the VHD into XenServer. There are two options for doing this. Option one: - 1. + 1. Import the VHD using XenCenter. In XenCenter, go to Tools>Virtual Appliance Tools>Disk Image Import. - 2. + 2. Choose the VHD, then click Next. - 3. + 3. Name the VM, choose the NFS VHD SR under Storage, enable "Run Operating System Fixups" and choose the NFS ISO SR. - 4. + 4. Click Next, then Finish. A VM should be created. Option two - 1. + 1. Run XenConvert, under From choose VHD, under To choose XenServer. Click Next. - 2. + 2. Choose the VHD, then click Next. - 3. + 3. Input the XenServer host info, then click Next. - 4. + 4. Name the VM, then click Next, then Convert. A VM should be created Once you have a VM created from the Hyper-V VHD, prepare it using the following steps: - 1. + 1. Boot the VM, uninstall Hyper-V Integration Services, and reboot. - 2. + 2. Install XenServer Tools, then reboot. - 3. + 3. Prepare the VM as desired. For example, run sysprep on Windows VMs. See Section 12.10, “Creating a Windows Template” Either option above will create a VM in HVM mode. This is fine for Windows VMs, but Linux VMs may not perform optimally. Converting a Linux VM to PV mode will require additional steps and will vary by distribution. - 1. + 1. Shut down the VM and copy the VHD from the NFS storage to a web server; for example, mount the NFS share on the web server and copy it, or from the XenServer host use sftp or scp to upload it to the web server. - 2. + 2. In CloudStack, create a new template using the following values: - + URL. Give the URL for the VHD - + OS Type. Use the appropriate OS. For PV mode on CentOS, choose Other PV (32-bit) or Other PV (64-bit). This choice is available only for XenServer. - + Hypervisor. XenServer - + Format. VHD The template will be created, and you can create instances from it. @@ -2522,23 +2522,23 @@ cad7317c-258b-4ef7-b207-cdf0283a7923 If the script is unable to contact the virtual router during instance boot it will not set the password but boot will continue normally. Linux OS Installation12.13.1. Linux OS Installation Use the following steps to begin the Linux OS installation: - 1. + 1. Download the script file cloud-set-guest-password: - + Linux: http://cloudstack.org/dl/cloud-set-guest-password - + Windows: http://sourceforge.net/projects/cloudstack/files/Password%20Management%20Scripts/CloudInstanceManager.msi/download - 2. + 2. Copy this file to /etc/init.d. On some Linux distributions, copy the file to /etc/rc.d/init.d. - 3. + 3. Run the following command to make the script executable: - chmod +x /etc/init.d/cloud-set-guest-password4. + chmod +x /etc/init.d/cloud-set-guest-password4. Depending on the Linux distribution, continue with the appropriate step. On Fedora, CentOS/RHEL, and Debian, run: - chkconfig --add cloud-set-guest-passwordWindows OS Installation12.13.2. Windows OS Installation + chkconfig --add cloud-set-guest-passwordWindows OS Installation12.13.2. Windows OS Installation Download the installer, CloudInstanceManager.msi, from Download page11 http://cloudstack.org/download.html and run the installer in the newly created Windows VM. Deleting Templates12.14. Deleting Templates Templates may be deleted. In general, when a template spans multiple Zones, only the copy that is selected for deletion will be deleted; the same template in other Zones will not be deleted. The provided CentOS template is an exception to this. If the provided CentOS template is deleted, it will be deleted from all Zones. @@ -2550,9 +2550,9 @@ cad7317c-258b-4ef7-b207-cdf0283a7923 There is no ephemeral storage in CloudStack. All volumes on all nodes are persistent. Primary Storage13.2. Primary Storage This section gives concepts and technical details about CloudPlatform primary storage. For information about how to install and configure primary storage through the CloudPlatform UI, see the Advanced Installation Guide. - Best Practices for Primary Storage13.2.1. Best Practices for Primary Storage + Best Practices for Primary Storage13.2.1. Best Practices for Primary Storage The speed of primary storage will impact guest performance. If possible, choose smaller, higher RPM drives for primary storage. - + Ensure that nothing is stored on the server. Adding the server to CloudPlatform will destroy any existing data Runtime Behavior of Primary Storage13.2.2. Runtime Behavior of Primary Storage Root volumes are created automatically when a virtual machine is created. Root volumes are deleted when the VM is destroyed. Data volumes can be created and dynamically attached to VMs. Data volumes are not deleted when VMs are destroyed. @@ -2562,7 +2562,7 @@ cad7317c-258b-4ef7-b207-cdf0283a7923 Administrators add primary storage to the system by creating a CloudStack storage pool. Each storage pool is associated with a cluster. Hypervisor Support for Primary Storage13.2.3. Hypervisor Support for Primary Storage The following table shows storage options and parameters for different hypervisors. - + VMware vSphere @@ -2713,25 +2713,25 @@ cad7317c-258b-4ef7-b207-cdf0283a7923 The Usage Server runs at least once per day. It can be configured to run multiple times per day. Configuring the Usage Server14.1. Configuring the Usage Server To configure the usage server: - 1. + 1. Be sure the Usage Server has been installed. This requires extra steps beyond just installing the CloudStack software. See Installing the Usage Server (Optional) in the Advanced Installation Guide. - 2. + 2. Log in to the CloudStack UI as administrator. - 3. + 3. Click Global Settings. - 4. + 4. In Search, type usage. Find the configuration parameter that controls the behavior you want to set. See the table below for a description of the available parameters. - 5. + 5. In Actions, click the Edit icon. - 6. + 6. Type the desired value and click the Save icon. - 7. + 7. Restart the Management Server (as usual with any global configuration change) and also the Usage Server: - # service cloud-management restart + # service cloud-management restart # service cloud-usage restart The following table shows the global configuration settings that control the behavior of the Usage Server. - + Parameter Name @@ -2756,7 +2756,7 @@ cad7317c-258b-4ef7-b207-cdf0283a7923 Time zone of usage records. Set this if the usage records and daily job execution are in different time zones. For example, with the following settings, the usage job will run at PST 00:15 and generate usage records for the 24 hours from 00:00:00 GMT to 23:59:59 GMT: -usage.stats.job.exec.time = 00:15 +usage.stats.job.exec.time = 00:15 usage.execution.timezone = PST usage.aggregation.timezone = GMT @@ -2819,17 +2819,17 @@ usage.aggregation.timezone = GMT For example, suppose that your server is in GMT, your user population is predominantly in the East Coast of the United States, and you would like to process usage records every night at 2 AM local (EST) time. Choose these settings: - + enable.usage.server = true - + usage.execution.timezone = America/New_York - + usage.stats.job.exec.time = 07:00. This will run the Usage job at 2:00 AM EST. Note that this will shift by an hour as the East Coast of the U.S. enters and exits Daylight Savings Time. - + usage.stats.job.aggregation.range = 1440 With this configuration, the Usage job will run every night at 2 AM EST and will process records for the previous day’s midnight-midnight as defined by the EST (America/New_York) time zone. - Note + Note Because the special value 1440 has been used for usage.stats.job.aggregation.range, the Usage Server will ignore the data between midnight and 2 AM. That data will be included in the next day's run Setting Usage Limits14.2. Setting Usage Limits CloudStack provides several administrator control points for capping resource usage by users. Some of these limits are global configuration parameters. Others are applied at the ROOT domain and may be overridden on a per-account basis. @@ -2847,7 +2847,7 @@ usage.aggregation.timezone = GMT In a zone, the guest virtual network has a 24 bit CIDR by default. This limits the guest virtual network to 254 running instances. It can be adjusted as needed, but this must be done before any instances are created in the zone. For example, 10.1.1.0/22 would provide for ~1000 addresses. The following table lists limits set in the Global Configuration: - + Parameter Name @@ -2957,26 +2957,26 @@ usage.aggregation.timezone = GMT You can limit resource use by accounts. The default limits are set using global configuration parameters, and they affect all accounts within a cloud. The relevant parameters are those beginning with max.account (max.account.snapshots, etc.).. To override a default limit for a particular account, set a per-account resource limit. - 1. + 1. Log in to the CloudStack UI. - 2. + 2. In the left navigation tree, click Accounts. - 3. + 3. Select the account you want to modify. The current limits are displayed. A value of -1 shows that there is no limit in place - 4. + 4. Click the Edit button Per-Domain Limits14.5. Per-Domain Limits CloudStack allows the configuration of limits on a domain basis. With a domain limit in place, all users still have their account limits. They are additionally limited, as a group, to not exceed the resource limits set on their domain. Domain limits aggregate the usage of all accounts in the domain as well as all accounts in all subdomains of that domain. Limits set at the root domain level apply to the sum of resource usage by the accounts in all domains and sub-domains below that root domain. To set a domain limit: - 1. + 1. Log in to the CloudStack UI. - 2. + 2. In the left navigation tree, click Domains. - 3. + 3. Select the domain you want to modify. The current domain limits are displayed. A value of -1 shows that there is no limit in place. - 4. + 4. Click the Edit button Chapter 15.Chapter 15. Managing Networks and TrafficManaging Networks and Traffic @@ -2985,7 +2985,7 @@ usage.aggregation.timezone = GMT A network can carry guest traffic only between VMs within one zone. Virtual machines in different zones cannot communicate with each other using their IP addresses; they must communicate with each other by routing through a public IP address. Figure 1 illustrates a typical guest traffic setup: - + The Management Server automatically creates a virtual router for each network. A virtual router is a special virtual machine that runs on the hosts. Each virtual router has three network interfaces. Its eth0 interface serves as the gateway for the guest traffic and has the IP address of 10.1.1.1. Its eth1 interface is used by the system to configure the virtual router. Its eth2 interface is assigned a public IP address for public traffic. The virtual router provides DHCP and will automatically assign an IP address for each guest VM within the IP range assigned for the network. The user can manually reconfigure guest VMs to assume different IP addresses. @@ -2993,19 +2993,19 @@ usage.aggregation.timezone = GMT Source NAT is automatically configured in the virtual router to forward outbound traffic for all guest VMs Networking in a Pod15.2. Networking in a Pod Figure 2 illustrates network setup within a single pod. The hosts are connected to a pod-level switch. At a minimum, the hosts should have one physical uplink to each switch. Bonded NICs are supported as well. The pod-level switch is a pair of redundant gigabit switches with 10 G uplinks. - + Servers are connected as follows: - + Storage devices are connected to only the network that carries management traffic. - + Hosts are connected to networks for both management traffic and public traffic. - + Hosts are also connected to one or more networks carrying guest traffic. We recommend the use of multiple physical Ethernet cards to implement each network interface as well as redundant switch fabric in order to maximize throughput and improve reliability. Networking in a Zone15.3. Networking in a Zone Figure 3 illustrates the network setup within a single zone. - + A firewall for management traffic operates in the NAT mode. The network typically is assigned IP addresses in the 192.168.0.0/16 Class B private address space. Each pod is assigned IP addresses in the 192.168.*.0/24 Class C private address space. Each zone has its own set of public IP addresses. Public IP addresses from different zones do not overlap. @@ -3015,29 +3015,29 @@ usage.aggregation.timezone = GMT Within a zone that uses advanced networking, you need to tell the Management Server how the physical network is set up to carry different kinds of traffic in isolation. Configure Guest Traffic in an Advanced Zone15.5.1. Configure Guest Traffic in an Advanced Zone These steps assume you have already logged in to the CloudStack UI. To configure the base guest network: - 1. + 1. In the left navigation, choose Infrastructure. On Zones, click View More, then click the zone to which you want to add a network. - 2. + 2. Click the Network tab. - 3. + 3. Click Add guest network. The Add guest network window is displayed: - 4. + 4. Provide the following information: - + Name. The name of the network. This will be user-visible - + Display Text: The description of the network. This will be user-visible - + Zone: The zone in which you are configuring the guest network. - + Network offering: If the administrator has configured multiple network offerings, select the one you want to use for this network - + Guest Gateway: The gateway that the guests should use - + Guest Netmask: The netmask in use on the subnet the guests will use - 5. + 5. Click OK. Configure Public Traffic in an Advanced Zone15.5.2. Configure Public Traffic in an Advanced Zone In a zone that uses advanced networking, you need to configure at least one range of IP addresses for Internet traffic. @@ -3049,49 +3049,49 @@ usage.aggregation.timezone = GMT Each VM has just one default network. The virtual router's DHCP reply will set the guest's default gateway as that for the default network. Multiple non-default networks may be added to a guest in addition to the single, required default network. The administrator can control which networks are available as the default network. Additional networks can either be available to all accounts or be assigned to a specific account. Networks that are available to all accounts are zone-wide. Any user with access to the zone can create a VM with access to that network. These zone-wide networks provide little or no isolation between guests.Networks that are assigned to a specific account provide strong isolation. - Adding an Additional Guest Network15.6.1. Adding an Additional Guest Network1. + Adding an Additional Guest Network15.6.1. Adding an Additional Guest Network1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. Click Add guest network. Provide the following information: - + Name: The name of the network. This will be user-visible. - + Display Text: The description of the network. This will be user-visible. - + Zone. The name of the zone this network applies to. Each zone is a broadcast domain, and therefore each zone has a different IP range for the guest network. The administrator must configure the IP range for each zone. - + Network offering: If the administrator has configured multiple network offerings, select the one you want to use for this network. - + Guest Gateway: The gateway that the guests should use. - + Guest Netmask: The netmask in use on the subnet the guests will use. - 4. + 4. Click Create. Changing the Network Offering on a Guest Network15.6.2. Changing the Network Offering on a Guest Network A user or administrator can change the network offering that is associated with an existing guest network. - + Log in to the CloudStack UI as an administrator or end user. - + If you are changing from a network offering that uses the CloudStack virtual router to one that uses external devices as network service providers, you must first stop all the VMs on the network. See Stopping and Starting VMs. Then return here and continue to the next step - + In the left navigation, choose Network - + Click the name of the network you want to modify . - + In Network Offering, choose the new network offering, then click Apply. - + A prompt appears asking whether you want to keep the existing CIDR. This is to let you know that if you change the network offering, the CIDR will be affected. Choose No to proceed with the change. - + Wait for the update to complete. Don’t try to restart VMs until after the network change is complete. - + If you stopped any VMs in step 2, restart them. Security Groups15.7. Security GroupsAbout Security Groups15.7.1. About Security Groups Security groups provide a way to isolate traffic to VMs. A security group is a group of VMs that filter their incoming and outgoing traffic according to a set of rules, called ingress and egress rules. These rules filter network traffic according to the IP address that is attempting to communicate with the VM. Security groups are particularly useful in zones that use basic networking, because there is a single guest network for all guest VMs. In CloudStack 3.0.3 - 3.0.5, security groups are supported only in zones that use basic networking. - Note + Note In a zone that uses advanced networking, you can instead define multiple guest networks to isolate traffic to VMs. @@ -3104,93 +3104,93 @@ usage.aggregation.timezone = GMT If no ingress rules are specified, then no traffic will be allowed in, except for responses to any traffic that has been allowed out through an egress rule. Adding a Security Group15.7.2. Adding a Security Group A user or administrator can define a new security group. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network - 3. + 3. In Select view, choose Security Groups. - 4. + 4. Click Add Security Group. - 5. + 5. Provide a name and description. - 6. + 6. Click OK. The new security group appears in the Security Groups Details tab. - 7. + 7. To make the security group useful, continue to Adding Ingress and Egress Rules to a Security Group. Enabling Security Groups15.7.3. Enabling Security Groups In order for security groups to function in a zone, the security groups feature must first be enabled for the zone. The administrator can do this when creating a new zone, by selecting a network offering that includes security groups. The procedure is described in Basic Zone Configuration in the Advanced Installation Guide. - Adding Ingress and Egress Rules to a Security Group15.7.4. Adding Ingress and Egress Rules to a Security Group1. + Adding Ingress and Egress Rules to a Security Group15.7.4. Adding Ingress and Egress Rules to a Security Group1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network - 3. + 3. In Select view, choose Security Groups, then click the security group you want . - 4. + 4. To add an ingress rule, click the Ingress Rules tab and fill out the following fields to specify what network traffic is allowed into VM instances in this security group. If no ingress rules are specified, then no traffic will be allowed in, except for responses to any traffic that has been allowed out through an egress rule. - + Add by CIDR/Account. Indicate whether the source of the traffic will be defined by IP address (CIDR) or an existing security group in a CloudStack account (Account). Choose Account if you want to allow incoming traffic from all VMs in another security group - + Protocol. The networking protocol that sources will use to send traffic to the security group. TCP and UDP are typically used for data exchange and end-user communications. ICMP is typically used to send error messages or network monitoring data. - + Start Port, End Port. (TCP, UDP only) A range of listening ports that are the destination for the incoming traffic. If you are opening a single port, use the same number in both fields. - + ICMP Type, ICMP Code. (ICMP only) The type of message and error code that will be accepted. - + CIDR. (Add by CIDR only) To accept only traffic from IP addresses within a particular address block, enter a CIDR or a comma-separated list of CIDRs. The CIDR is the base IP address of the incoming traffic. For example, 192.168.0.0/22. To allow all CIDRs, set to 0.0.0.0/0. - + Account, Security Group. (Add by Account only) To accept only traffic from another security group, enter the CloudStack account and name of a security group that has already been defined in that account. To allow traffic between VMs within the security group you are editing now, enter the same name you used in step 7. The following example allows inbound HTTP access from anywhere: - 5. + 5. To add an egress rule, click the Egress Rules tab and fill out the following fields to specify what type of traffic is allowed to be sent out of VM instances in this security group. If no egress rules are specified, then all traffic will be allowed out. Once egress rules are specified, the following types of traffic are allowed out: traffic specified in egress rules; queries to DNS and DHCP servers; and responses to any traffic that has been allowed in through an ingress rule - + Add by CIDR/Account. Indicate whether the destination of the traffic will be defined by IP address (CIDR) or an existing security group in a CloudStack account (Account). Choose Account if you want to allow outgoing traffic to all VMs in another security group. - + Protocol. The networking protocol that VMs will use to send outgoing traffic. TCP and UDP are typically used for data exchange and end-user communications. ICMP is typically used to send error messages or network monitoring data. - + Start Port, End Port. (TCP, UDP only) A range of listening ports that are the destination for the outgoing traffic. If you are opening a single port, use the same number in both fields. - + ICMP Type, ICMP Code. (ICMP only) The type of message and error code that will be sent - + CIDR. (Add by CIDR only) To send traffic only to IP addresses within a particular address block, enter a CIDR or a comma-separated list of CIDRs. The CIDR is the base IP address of the destination. For example, 192.168.0.0/22. To allow all CIDRs, set to 0.0.0.0/0. - + Account, Security Group. (Add by Account only) To allow traffic to be sent to another security group, enter the CloudStack account and name of a security group that has already been defined in that account. To allow traffic between VMs within the security group you are editing now, enter its name. - 6. + 6. Click Add. External Firewalls and Load Balancers15.8. External Firewalls and Load Balancers CloudStack is capable of replacing its Virtual Router with an external Juniper SRX device and an optional external NetScaler or F5 load balancer for gateway and load balancing services. In this case, the VMs use the SRX as their gateway. Load Balancer Rules15.9. Load Balancer Rules A CloudStack user or administrator may create load balancing rules that balance traffic received at a public IP to one or more VMs. A user creates a rule, specifies an algorithm, and assigns the rule to a set of VMs. - Note + Note If you create load balancing rules while using a network service offering that includes an external load balancer device such as NetScaler, and later change the network service offering to one that uses the CloudStack virtual router, you must create a firewall rule on the virtual router for each of your existing load balancing rules so that they continue to function. Guest IP Ranges15.10. Guest IP Ranges The IP ranges for guest network traffic are set on a per-account basis by the user. This allows the users to configure their network in a fashion that will enable VPN linking between their guest network and their clients. - Acquiring a New IP Address15.11. Acquiring a New IP Address1. + Acquiring a New IP Address15.11. Acquiring a New IP Address1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. Click the name of the network where you want to work with. - 4. + 4. Click View IP Addresses. - 5. + 5. Click Acquire New IP, and click Yes in the confirmation dialog. You are prompted for confirmation because, typically, IP addresses are a limited resource. Within a few moments, the new IP address should appear with the state Allocated. You can now use the IP address in port forwarding or static NAT rules. - Releasing an IP Address15.12. Releasing an IP Address1. + Releasing an IP Address15.12. Releasing an IP Address1. Log in to the CloudPlatform UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. Click the name of the network where you want to work with. - 4. + 4. Click View IP Addresses. - 5. + 5. Click the IP address you want to release. - 6. + 6. Click the Release IP button . @@ -3204,11 +3204,11 @@ usage.aggregation.timezone = GMT For the steps to implement these rules, see Firewall Rules and Port Forwarding. IP Load Balancing15.15. IP Load Balancing The user may choose to associate the same public IP for multiple guests. CloudStack implements a TCP-level load balancer with the following policies. - + Round-robin - + Least connection - + Source IP This is similar to port forwarding but the destination may be multiple IP addresses. @@ -3216,39 +3216,39 @@ usage.aggregation.timezone = GMT The Virtual Router provides DNS and DHCP services to the guests. It proxies DNS requests to the DNS server configured on the Availability Zone. VPN15.17. VPN CloudStack account owners can create virtual private networks (VPN) to access their virtual machines. If the guest network is instantiated from a network offering that offers the Remote Access VPN service, the virtual router (based on the System VM) is used to provide the service. CloudStack provides a L2TP-over-IPsec-based remote access VPN service to guest virtual networks. Since each network gets its own virtual router, VPNs are not shared across the networks. VPN clients native to Windows, Mac OS X and iOS can be used to connect to the guest networks. The account owner can create and manage users for their VPN. CloudStack does not use its account database for this purpose but uses a separate table. The VPN user database is shared across all the VPNs created by the account owner. All VPN users get access to all VPNs created by the account owner. - Note + Note Make sure that not all traffic goes through the VPN. That is, the route installed by the VPN should be only for the guest network and not for all traffic. - + Road Warrior / Remote Access. Users want to be able to connect securely from a home or office to a private network in the cloud. Typically, the IP address of the connecting client is dynamic and cannot be preconfigured on the VPN server. - + Site to Site. In this scenario, two private subnets are connected over the public Internet with a secure VPN tunnel. The cloud user’s subnet (for example, an office network) is connected through a gateway to the network in the cloud. The address of the user’s gateway must be preconfigured on the VPN server in the cloud. Note that although L2TP-over-IPsec can be used to set up Site-to-Site VPNs, this is not the primary intent of this feature. Configuring VPN15.17.1. Configuring VPN To set up VPN for the cloud: - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, click Global Settings. - 3. + 3. Set the following global configuration parameters. - + remote.access.vpn.client.ip.range – The range of IP addressess to be allocated to remote access VPN clients. The first IP in the range is used by the VPN server. - + remote.access.vpn.psk.length – Length of the IPSec key. - + remote.access.vpn.user.limit – Maximum number of VPN users per account. To enable VPN for a particular network: - 1. + 1. Log in as a user or administrator to the CloudStack UI. - 2. + 2. In the left navigation, click Network. - 3. + 3. Click the name of the network you want to work with. - 4. + 4. Click View IP Addresses. - 5. + 5. Click one of the displayed IP address names. - 6. + 6. Click the Enable VPN button . @@ -3256,29 +3256,29 @@ usage.aggregation.timezone = GMT The IPsec key is displayed in a popup window. Using VPN with Windows15.17.2. Using VPN with Windows The procedure to use VPN varies by Windows version. Generally, the user must edit the VPN properties and make sure that the default route is not the VPN. The following steps are for Windows L2TP clients on Windows Vista. The commands should be similar for other Windows versions. - 1. + 1. Log in to the CloudStack UI and click on the source NAT IP for the account. The VPN tab should display the IPsec preshared key. Make a note of this and the source NAT IP. The UI also lists one or more users and their passwords. Choose one of these users, or, if none exists, add a user and password. - 2. + 2. On the Windows box, go to Control Panel, then select Network and Sharing center. Click Setup a connection or network. - 3. + 3. In the next dialog, select No, create a new connection. - 4. + 4. In the next dialog, select Use my Internet Connection (VPN). - 5. + 5. In the next dialog, enter the source NAT IP from step 1 and give the connection a name. Check Don't connect now. - 6. + 6. In the next dialog, enter the user name and password selected in step 1. - 7. + 7. Click Create. - 8. + 8. Go back to the Control Panel and click Network Connections to see the new connection. The connection is not active yet. - 9. + 9. Right-click the new connection and select Properties. In the Properties dialog, select the Networking tab. - 10. + 10. In Type of VPN, choose L2TP IPsec VPN, then click IPsec settings. Select Use preshared key. Enter the preshared key from Step 1. - 11. + 11. The connection is ready for activation. Go back to Control Panel -> Network Connections and double-click the created connection. - 12. + 12. Enter the user name and password from Step 1. Using VPN with Mac OS X15.17.3. Using VPN with Mac OS X In Mac OS X, in Network Preferences - Advanced, make sure Send all traffic over VPN connection is not checked. @@ -3286,221 +3286,221 @@ usage.aggregation.timezone = GMT A Site-to-Site VPN connection helps you establish a secure connection from an enterprise datacenter to the cloud infrastructure. This allows users to access the guest VMs by establishing a VPN connection to the virtual router of the account from a device in the datacenter of the enterprise. Having this facility eliminates the need to establish VPN connections to individual VMs. The supported endpoints on the remote datacenters are: - + Cisco ISR with IOS 12.4 or later - + Juniper J-Series routers with JunOS 9.5 or later - Note + Note In addition to the specific Cisco and Juniper devices listed above, the expectation is that any Cisco or Juniper device running on the supported operating systems are able to establish VPN connections. To set up a Site-to-Site VPN connection, perform the following: - 1. + 1. Create a Virtual Private Cloud (VPC). See Section 15.19, “Configuring a Virtual Private Cloud”. - 2. + 2. Create a VPN Customer Gateway. - 3. + 3. Create a VPN gateway for the VPC that you created. - 4. + 4. Create VPN connection from the VPC VPN gateway to the customer VPN gateway. - 15.17.4.1. Creating and Updating a VPN Customer GatewayNote + 15.17.4.1. Creating and Updating a VPN Customer GatewayNote A VPN customer gateway can be connected to only one VPN gateway at a time. To add a VPN Customer Gateway: - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPN Customer Gateway. - 4. + 4. Click Add site-to-site VPN. - + Provide the following information: - + Name: A unique name for the VPN customer gateway you create. - + Gateway: The IP address for the remote gateway. - + CIDR list: The guest CIDR list of the remote subnets. Enter a CIDR or a comma-separated list of CIDRs. Ensure that a guest CIDR list is not overlapped with the VPC’s CIDR, or another guest CIDR. The CIDR must be RFC1918-compliant. - + IPsec Preshared Key: Preshared keying is a method where the endpoints of the VPN share a secret key. This key value is used to authenticate the customer gateway and the VPC VPN gateway to each other. - Note + Note The IKE peers (VPN end points) authenticate each other by computing and sending a keyed hash of data that includes the Preshared key. If the receiving peer is able to create the same hash independently by using its Preshared key, it knows that both peers must share the same secret, thus authenticating the customer gateway. - + IKE Encryption: The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. Authentication is accomplished through the Preshared Keys. - Note + Note The phase-1 is the first phase in the IKE process. In this initial negotiation phase, the two VPN endpoints agree on the methods to be used to provide security for the underlying IP traffic. The phase-1 authenticates the two VPN gateways to each other, by confirming that the remote gateway has a matching Preshared Key. - + IKE Hash: The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5. - + IKE DH: A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The 1536-bit Diffie-Hellman group is used within IKE to establish session keys. The supported options are None, Group-5 (1536-bit) and Group-2 (1024-bit). - + ESP Encryption: Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. - Note + Note The phase-2 is the second phase in the IKE process. The purpose of IKE phase-2 is to negotiate IPSec security associations (SA) to set up the IPSec tunnel. In phase-2, new keying material is extracted from the Diffie-Hellman key exchange in phase-1, to provide session keys to use in protecting the VPN data flow. - + ESP Hash: Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5. - + Perfect Forward Secrecy: Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. This property enforces a new Diffie-Hellman key exchange. It provides the keying material that has greater key material life and thereby greater resistance to cryptographic attacks. The available options are None, Group-5 (1536-bit) and Group-2 (1024-bit). The security of the key exchanges increase as the DH groups grow larger, as does the time of the exchanges. - Note + Note When PFS is turned on, for every negotiation of a new phase-2 SA the two gateways must generate a new set of phase-1 keys. This adds an extra layer of protection that PFS adds, which ensures if the phase-2 SA’s have expired, the keys used for new phase-2 SA’s have not been generated from the current phase-1 keying material. - + IKE Lifetime (seconds): The phase-1 lifetime of the security association in seconds. Default is 86400 seconds (1 day). Whenever the time expires, a new phase-1 exchange is performed. - + ESP Lifetime (seconds): The phase-2 lifetime of the security association in seconds. Default is 3600 seconds (1 hour). Whenever the value is exceeded, a re-key is initiated to provide a new IPsec encryption and authentication session keys. - + Dead Peer Detection: A method to detect an unavailable Internet Key Exchange (IKE) peer. Select this option if you want the virtual router to query the liveliness of its IKE peer at regular intervals. It’s recommended to have the same configuration of DPD on both side of VPN connection. - 5. + 5. Click OK. Updating and Removing a VPN Customer Gateway You can update a customer gateway either with no VPN connection, or related VPN connection is in error state. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPN Customer Gateway. - 4. + 4. Select the VPN customer gateway you want to work with. - 5. + 5. To modify the required parameters, click the Edit VPN Customer Gateway button - 6. + 6. To remove the VPN customer gateway, click the Delete VPN Customer Gateway button - 7. + 7. Click OK. - 15.17.4.2. Creating a VPN gateway for the VPC1. + 15.17.4.2. Creating a VPN gateway for the VPC1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC to which you want to deploy the VMs. The VPC page is displayed where all the tiers you created are listed in a diagram. - 5. + 5. Click the Settings icon. The following options are displayed. - + IP Addresses - + Gateways - + Site-to-Site VPN - + Network ACLs - 6. + 6. Select Site-to-Site VPN. If you are creating the VPN gateway for the first time, selecting Site-to-Site VPN prompts you to create a VPN gateway. - 7. + 7. In the confirmation dialog, click Yes to confirm. Within a few moments, the VPN gateway is created. You will be prompted to view the details of the VPN gateway you have created. Click Yes to confirm. The following details are displayed in the VPN Gateway page: - + IP Address - + Account - + Domain - 15.17.4.3. Creating a VPN Connection1. + 15.17.4.3. Creating a VPN Connection1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you create for the account are listed in the page. - 4. + 4. Click the Configure button of the VPC to which you want to deploy the VMs. The VPC page is displayed where all the tiers you created are listed in a diagram. - 5. + 5. Click the Settings icon. The following options are displayed. - + IP Addresses - + Gateways - + Site-to-Site VPN - + Network ASLs - 6. + 6. Select Site-to-Site VPN. The Site-to-Site VPN page is displayed. - 7. + 7. From the Select View drop-down, ensure that VPN Connection is selected. - 8. + 8. Click Create VPN Connection. The Create VPN Connection dialog is displayed: - 9. + 9. Select the desired customer gateway, then click OK to confirm. Within a few moments, the VPN Connection is displayed. The following information on the VPN connection is displayed: - + IP Address - + Gateway - + State - + IPSec Preshared Key - + IKE Policy - + ESP Policy - 15.17.4.4. Restarting and Removing a VPN Connection1. + 15.17.4.4. Restarting and Removing a VPN Connection1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC to which you want to deploy the VMs. The VPC page is displayed where all the tiers you created are listed in a diagram. - 5. + 5. Click the Settings icon. The following options are displayed. - + IP Addresses - + Gateways - + Site-to-Site VPN - + Network ASLs - 6. + 6. Select Site-to-Site VPN. The Site-to-Site VPN page is displayed. - 7. + 7. From the Select View drop-down, ensure that VPN Connection is selected. All the VPN connections you created are displayed. - 8. + 8. Select the VPN connection you want to work with. The Details tab is displayed. - 9. + 9. To remove a VPN connection, click the Delete VPN connection button @@ -3512,35 +3512,35 @@ usage.aggregation.timezone = GMT This feature is supported on XenServer and VMware hypervisors. The major advantages are: - + The administrator can deploy a set of VLANs and allow users to deploy VMs on these VLANs. A guest VLAN is randomly alloted to an account from a pre-specified set of guest VLANs. All the VMs of a certain tier of an account reside on the guest VLAN allotted to that account. - Note + Note A VLAN allocated for an account cannot be shared between multiple accounts. - + The administrator can allow users create their own VPC and deploy the application. In this scenario, the VMs that belong to the account are deployed on the VLANs allotted to that account. - + Both administrators and users can create multiple VPCs. The guest network NIC is plugged to the VPC virtual router when the first VM is deployed in a tier. - + The administrator can create the following gateways to send to or receive traffic from the VMs: - + VPN Gateway: For more information, see Section 15.17.4.2, “Creating a VPN gateway for the VPC”. - + Public Gateway: The public gateway for a VPC is added to the virtual router when the virtual router is created for VPC. The public gateway is not exposed to the end users. You are not allowed to list it, nor allowed to create any static routes. - + Private Gateway: For more information, see Section 15.19.5, “Adding a Private Gateway to a VPC”. - + Both administrators and users can create various possible destinations-gateway combinations. However, only one gateway of each type can be used in a deployment. For example: - + VLANs and Public Gateway: For example, an application is deployed in the cloud, and the Web application VMs communicate with the Internet. - + VLANs, VPN Gateway, and Public Gateway: For example, an application is deployed in the cloud; the Web application VMs communicate with the Internet; and the database VMs communicate with the on-premise devices. - + The administrator can define Access Control List (ACL) on the virtual router to filter the traffic among the VLANs or between the Internet and a VLAN. You can define ACL based on CIDR, port range, protocol, type code (if ICMP protocol is selected) and Ingress/Egress type. The following figure shows the possible deployment scenarios of a Inter-VLAN setup: - + To set up a multi-tier Inter-VLAN deployment, see Section 15.19, “Configuring a Virtual Private Cloud”. Configuring a Virtual Private Cloud15.19. Configuring a Virtual Private CloudAbout Virtual Private Clouds15.19.1. About Virtual Private Clouds CloudStack Virtual Private Cloud is a private, isolated part of CloudStack. A VPC can have its own virtual network topology that resembles a traditional physical network. You can launch VMs in the virtual network that can have private addresses in the range of your choice, for example: 10.0.0.0/16. You can define network tiers within your VPC network range, which in turn enables you to group similar kinds of instances based on IP address range. @@ -3548,249 +3548,249 @@ usage.aggregation.timezone = GMT For example, if a VPC has the private range 10.0.0.0/16, its guest networks can have the network ranges 10.0.1.0/24, 10.0.2.0/24, 10.0.3.0/24, and so on. Major Components of a VPC: A VPC is comprised of the following network components: - + VPC: A VPC acts as a container for multiple isolated networks that can communicate with each other via its virtual router. - + Network Tiers: Each tier acts as an isolated network with its own VLANs and CIDR list, where you can place groups of resources, such as VMs. The tiers are segmented by means of VLANs. The NIC of each tier acts as its gateway. - + Virtual Router: A virtual router is automatically created and started when you create a VPC. The virtual router connect the tiers and direct traffic among the public gateway, the VPN gateways, and the NAT instances. For each tier, a corresponding NIC and IP exist in the virtual router. The virtual router provides DNS and DHCP services through its IP. - + Public Gateway: The traffic to and from the Internet routed to the VPC through the public gateway. In a VPC, the public gateway is not exposed to the end user; therefore, static routes are not support for the public gateway. - + Private Gateway: All the traffic to and from a private network routed to the VPC through the private gateway. For more information, see Section 15.19.5, “Adding a Private Gateway to a VPC”. - + VPN Gateway: The VPC side of a VPN connection. - + Site-to-Site VPN Connection: A hardware-based VPN connection between your VPC and your datacenter, home network, or co-location facility. For more information, see Section 15.17.4, “Setting Up a Site-to-Site VPN Connection”. - + Customer Gateway: The customer side of a VPN Connection. For more information, see Section 15.17.4.1, “Creating and Updating a VPN Customer Gateway”. - + NAT Instance: An instance that provides Port Address Translation for instances to access the Internet via the public gateway. For more information, see Section 15.19.9, “Enabling or Disabling Static NAT on a VPC”. Network Architecture in a VPC In a VPC, the following four basic options of network architectures are present: - + VPC with a public gateway only - + VPC with public and private gateways - + VPC with public and private gateways and site-to-site VPN access - + VPC with a private gateway only and site-to-site VPN access Connectivity Options for a VPC You can connect your VPC to: - + The Internet through the public gateway. - + The corporate datacenter by using a site-to-site VPN connection through the VPN gateway. - + Both the Internet and your corporate datacenter by using both the public gateway and a VPN gateway. VPC Network Considerations Consider the following before you create a VPC: - + A VPC, by default, is created in the enabled state. - + A VPC can be created in Advance zone only, and can't belong to more than one zone at a time. - + The default number of VPCs an account can create is 20. However, you can change it by using the max.account.vpcs global parameter, which controls the maximum number of VPCs an account is allowed to create. - + The default number of tiers an account can create within a VPC is 3. You can configure this number by using the vpc.max.networks parameter. - + Each tier should have an unique CIDR in the VPC. Ensure that the tier's CIDR should be within the VPC CIDR range. - + A tier belongs to only one VPC. - + All network tiers inside the VPC should belong to the same account. - + When a VPC is created, by default, a SourceNAT IP is allocated to it. The Source NAT IP is released only when the VPC is removed. - + A public IP can be used for only one purpose at a time. If the IP is a sourceNAT, it cannot be used for StaticNAT or port forwarding. - + The instances only have a private IP address that you provision. To communicate with the Internet, enable NAT to an instance that you launch in your VPC. - + Only new networks can be added to a VPC. The maximum number of networks per VPC is limited by the value you specify in the vpc.max.networks parameter. The default value is three. - + The load balancing service can be supported by only one tier inside the VPC. - + If an IP address is assigned to a tier: - + That IP can't be used by more than one tier at a time in the VPC. For example, if you have tiers A and B, and a public IP1, you can create a port forwarding rule by using the IP either for A or B, but not for both. - + That IP can't be used for StaticNAT, load balancing, or port forwarding rules for another guest network inside the VPC. - + Remote access VPN is not supported in VPC networks. Adding a Virtual Private Cloud15.19.2. Adding a Virtual Private Cloud When creating the VPC, you simply provide the zone and a set of IP addresses for the VPC network address space. You specify this set of addresses in the form of a Classless Inter-Domain Routing (CIDR) block. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. - 4. + 4. Click Add VPC. The Add VPC page is displayed as follows: - + Provide the following information: - + Name: A short name for the VPC that you are creating. - + Description: A brief description of the VPC. - + Zone: Choose the zone where you want the VPC to be available. - + Super CIDR for Guest Networks: Defines the CIDR range for all the tiers (guest networks) within a VPC. When you create a tier, ensure that its CIDR is within the Super CIDR value you enter. The CIDR must be RFC1918 compliant. - + DNS domain for Guest Networks: If you want to assign a special domain name, specify the DNS suffix. This parameter is applied to all the tiers within the VPC. That implies, all the tiers you create in the VPC belong to the same DNS domain. If the parameter is not specified, a DNS domain name is generated automatically. Adding Tiers15.19.3. Adding Tiers Tiers are distinct locations within a VPC that act as isolated networks, which do not have access to other tiers by default. Tiers are set up on different VLANs that can communicate with each other by using a virtual router. Tiers provide inexpensive, low latency network connectivity to other tiers within the VPC. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPC that you have created for the account is listed in the page. - Note + Note The end users can see their own VPCs, while root and domain admin can see any VPC they are authorized to see. - 4. + 4. Click the Configure button of the VPC for which you want to set up tiers. The Add new tier dialog is displayed, as follows: - + If you have already created tiers, the VPC diagram is displayed. Click Create Tier to add a new tier. - 5. + 5. Specify the following: All the fields are mandatory. - + Name: A unique name for the tier you create. - + Network Offering: The following default network offerings are listed: DefaultIsolatedNetworkOfferingForVpcNetworksNoLB, DefaultIsolatedNetworkOfferingForVpcNetworks In a VPC, only one tier can be created by using LB-enabled network offering. - + Gateway: The gateway for the tier you create. Ensure that the gateway is within the Super CIDR range that you specified while creating the VPC, and is not overlapped with the CIDR of any existing tier within the VPC. - + Netmask: The netmask for the tier you create. For example, if the VPC CIDR is 10.0.0.0/16 and the network tier CIDR is 10.0.1.0/24, the gateway of the tier is 10.0.1.1, and the netmask of the tier is 255.255.255.0. - 6. + 6. Click OK. - 7. + 7. Continue with configuring access control list for the tier. Configuring Access Control List15.19.4. Configuring Access Control List Define Network Access Control List (ACL) on the VPC virtual router to control incoming (ingress) and outgoing (egress) traffic between the VPC tiers, and the tiers and Internet. By default, all incoming and outgoing traffic to the guest networks is blocked. To open the ports, you must create a new network ACL. The network ACLs can be created for the tiers only if the NetworkACL service is supported. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Settings icon. The following options are displayed. - + IP Addresses - + Gateways - + Site-to-Site VPN - + Network ACLs - 5. + 5. Select Network ACLs. The Network ACLs page is displayed. - 6. + 6. Click Add Network ACLs. To add an ACL rule, fill in the following fields to specify what kind of network traffic is allowed in this tier. - + CIDR: The CIDR acts as the Source CIDR for the Ingress rules, and Destination CIDR for the Egress rules. To accept traffic only from or to the IP addresses within a particular address block, enter a CIDR or a comma-separated list of CIDRs. The CIDR is the base IP address of the incoming traffic. For example, 192.168.0.0/22. To allow all CIDRs, set to 0.0.0.0/0. - + Protocol: The networking protocol that sources use to send traffic to the tier. The TCP and UDP protocols are typically used for data exchange and end-user communications. The ICMP protocol is typically used to send error messages or network monitoring data. - + Start Port, End Port (TCP, UDP only): A range of listening ports that are the destination for the incoming traffic. If you are opening a single port, use the same number in both fields. - + Select Tier: Select the tier for which you want to add this ACL rule. - + ICMP Type, ICMP Code (ICMP only): The type of message and error code that will be sent. - + Traffic Type: Select the traffic type you want to apply. - + Egress: To add an egress rule, select Egress from the Traffic type drop-down box and click Add. This specifies what type of traffic is allowed to be sent out of VM instances in this tier. If no egress rules are specified, all traffic from the tier is allowed out at the VPC virtual router. Once egress rules are specified, only the traffic specified in egress rules and the responses to any traffic that has been allowed in through an ingress rule are allowed out. No egress rule is required for the VMs in a tier to communicate with each other. - + Ingress: To add an ingress rule, select Ingress from the Traffic type drop-down box and click Add. This specifies what network traffic is allowed into the VM instances in this tier. If no ingress rules are specified, then no traffic will be allowed in, except for responses to any traffic that has been allowed out through an egress rule. - Note + Note By default, all incoming and outgoing traffic to the guest networks is blocked. To open the ports, create a new network ACL. - 7. + 7. Click Add. The ACL rule is added. To view the list of ACL rules you have added, click the desired tier from the Network ACLs page, then select the Network ACL tab. - + You can edit the tags assigned to the ACL rules and delete the ACL rules you have created. Click the appropriate button in the Actions column. Adding a Private Gateway to a VPC15.19.5. Adding a Private Gateway to a VPC A private gateway can be added by the root admin only. The VPC private network has 1:1 relationship with the NIC of the physical network. No gateways with duplicated VLAN and IP are allowed in the same data center. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC to which you want to configure load balancing rules. The VPC page is displayed where all the tiers you created are listed in a diagram. - 5. + 5. Click the Settings icon. The following options are displayed. - + IP Addresses - + Private Gateways - + Site-to-Site VPN - + Network ACLs - 6. + 6. Select Private Gateways. The Gateways page is displayed. - 7. + 7. Click Add new gateway: - 8. + 8. Specify the following: - + Physical Network: The physical network you have created in the zone. - + IP Address: The IP address associated with the VPC gateway. - + Gateway: The gateway through which the traffic is routed to and from the VPC. - + Netmask: The netmask associated with the VPC gateway. - + VLAN: The VLAN associated with the VPC gateway. The new gateway appears in the list. You can repeat these steps to add more gateway for this VPC. - Deploying VMs to the Tier15.19.6. Deploying VMs to the Tier1. + Deploying VMs to the Tier15.19.6. Deploying VMs to the Tier1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC to which you want to deploy the VMs. The VPC page is displayed where all the tiers you created are listed. - 5. + 5. Click the Add VM button of the tier for which you want to add a VM. The Add Instance page is displayed. @@ -3798,71 +3798,71 @@ usage.aggregation.timezone = GMT Follow the on-screen instruction to add an instance. For information on adding an instance, see Adding Instances section in the Installation Guide. Acquiring a New IP Address for a VPC15.19.7. Acquiring a New IP Address for a VPC When you acquire an IP address, all IP addresses are allocated to VPC, not to the guest networks within the VPC. The IPs are associated to the guest network only when the first port-forwarding, load balancing, or Static NAT rule is created for the IP or the network. IP can't be associated to more than one network at a time. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC to which you want to deploy the VMs. The VPC page is displayed where all the tiers you created are listed in a diagram. - 5. + 5. Click the Settings icon. The following options are displayed. - + IP Addresses - + Gateways - + Site-to-Site VPN - + Network ACLs - 6. + 6. Select IP Addresses. The IP Addresses page is displayed. - 7. + 7. Click Acquire New IP, and click Yes in the confirmation dialog. You are prompted for confirmation because, typically, IP addresses are a limited resource. Within a few moments, the new IP address should appear with the state Allocated. You can now use the IP address in port forwarding, load balancing, and static NAT rules. Releasing an IP Address Alloted to a VPC15.19.8. Releasing an IP Address Alloted to a VPC The IP address is a limited resource. If you no longer need a particular IP, you can disassociate it from its VPC and return it to the pool of available addresses. An IP address can be released from its tier, only when all the networking ( port forwarding, load balancing, or StaticNAT ) rules are removed for this IP address. The released IP address will still belongs to the same VPC. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC whose IP you want to release. The VPC page is displayed where all the tiers you created are listed in a diagram. - 5. + 5. Click the Settings icon. The following options are displayed. - + IP Addresses - + Gateways - + Site-to-Site VPN - + Network ACLs - 6. + 6. Select IP Addresses. The IP Addresses page is displayed. - 7. + 7. Click the IP you want to release. - 8. + 8. In the Details tab, click the Release IP button Enabling or Disabling Static NAT on a VPC15.19.9. Enabling or Disabling Static NAT on a VPC @@ -3871,185 +3871,185 @@ usage.aggregation.timezone = GMT If port forwarding rules are already in effect for an IP address, you cannot enable static NAT to that IP. If a guest VM is part of more than one network, static NAT rules will function only if they are defined on the default network. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC to which you want to deploy the VMs. The VPC page is displayed where all the tiers you created are listed in a diagram. - 5. + 5. Click the Settings icon. The following options are displayed. - + IP Addresses - + Gateways - + Site-to-Site VPN - + Network ACLs - 6. + 6. Select IP Addresses. The IP Addresses page is displayed. - 7. + 7. Click the IP you want to work with. - 8. + 8. In the Details tab,click the Static NAT button. The button toggles between Enable and Disable, depending on whether static NAT is currently enabled for the IP address. - 9. + 9. If you are enabling static NAT, a dialog appears as follows: - 10. + 10. Select the tier and the destination VM, then click Apply. Adding Load Balancing Rules on a VPC15.19.10. Adding Load Balancing Rules on a VPC A CloudStack user or administrator may create load balancing rules that balance traffic received at a public IP to one or more VMs that belong to a network tier that provides load balancing service in a VPC. A user creates a rule, specifies an algorithm, and assigns the rule to a set of VMs within a VPC. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC to which you want to configure load balancing rules. The VPC page is displayed where all the tiers you created are listed in a diagram. - 5. + 5. Click the Settings icon. The following options are displayed. - + IP Addresses - + Gateways - + Site-to-Site VPN - + Network ACLs - 6. + 6. Select IP Addresses. The IP Addresses page is displayed. - 7. + 7. Click the IP address for which you want to create the rule, then click the Configuration tab. - 8. + 8. In the Load Balancing node of the diagram, click View All. - 9. + 9. Select the tier to which you want to apply the rule. - Note + Note In a VPC, the load balancing service is supported only on a single tier. - 10. + 10. Specify the following: - + Name: A name for the load balancer rule. - + Public Port: The port that receives the incoming traffic to be balanced. - + Private Port: The port that the VMs will use to receive the traffic. - + Algorithm. Choose the load balancing algorithm you want CloudStack to use. CloudStack supports the following well-known algorithms: - + Round-robin - + Least connections - + Source - + Stickiness. (Optional) Click Configure and choose the algorithm for the stickiness policy. See Sticky Session Policies for Load Balancer Rules. - + Add VMs: Click Add VMs, then select two or more VMs that will divide the load of incoming traffic, and click Apply. The new load balancing rule appears in the list. You can repeat these steps to add more load balancing rules for this IP address. - Adding a Port Forwarding Rule on a VPC15.19.11. Adding a Port Forwarding Rule on a VPC1. + Adding a Port Forwarding Rule on a VPC15.19.11. Adding a Port Forwarding Rule on a VPC1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC to which you want to deploy the VMs. The VPC page is displayed where all the tiers you created are listed in a diagram. - 5. + 5. Click the Settings icon. The following options are displayed. - + IP Addresses - + Gateways - + Site-to-Site VPN - + Network ACLs - 6. + 6. Choose an existing IP address or acquire a new IP address. Click the name of the IP address in the list. The IP Addresses page is displayed. - 7. + 7. Click the IP address for which you want to create the rule, then click the Configuration tab. - 8. + 8. In the Port Forwarding node of the diagram, click View All. - 9. + 9. Select the tier to which you want to apply the rule. - 10. + 10. Specify the following: - + Public Port: The port to which public traffic will be addressed on the IP address you acquired in the previous step. - + Private Port: The port on which the instance is listening for forwarded public traffic. - + Protocol: The communication protocol in use between the two ports. - + TCP - + UDP - + Add VM: Click Add VM. Select the name of the instance to which this rule applies, and click Apply. You can test the rule by opening an ssh session to the instance. Removing Tiers15.19.12. Removing Tiers You can remove a tier from a VPC. A removed tier cannot be revoked. When a tier is removed, only the resources of the tier are expunged. All the network rules (port forwarding, load balancing and staticNAT) and the IP addresses associated to the tier are removed. The IP address still be belonging to the same VPC. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPC that you have created for the account is listed in the page. - 4. + 4. Click the Configure button of the VPC for which you want to set up tiers. The Configure VPC page is displayed. Locate the tier you want to work with. - 5. + 5. Click the Remove VPC button: - + Wait for some time for the tier to be removed. - Editing, Restarting, and Removing a Virtual Private Cloud15.19.13. Editing, Restarting, and Removing a Virtual Private CloudNote + Editing, Restarting, and Removing a Virtual Private Cloud15.19.13. Editing, Restarting, and Removing a Virtual Private CloudNote Ensure that all the tiers are removed before you remove a VPC. - 1. + 1. Log in to the CloudStack UI as an administrator or end user. - 2. + 2. In the left navigation, choose Network. - 3. + 3. In the Select view, select VPC. All the VPCs that you have created for the account is listed in the page. - 4. + 4. Select the VPC you want to work with. - 5. + 5. To remove, click the Remove VPC button @@ -4062,19 +4062,19 @@ usage.aggregation.timezone = GMT CloudStack uses several types of system virtual machines to perform tasks in the cloud. In general CloudStack manages these system VMs and creates, starts, and stops them as needed based on scale and immediate needs. However, the administrator should be aware of them and their roles to assist in debugging issues. The System VM Template16.1. The System VM Template The System VMs come from a single template. The System VM has the following characteristics: - + Debian 6.0 ("Squeeze"), 2.6.32 kernel with the latest security patches from the Debian security APT repository - + Has a minimal set of packages installed thereby reducing the attack surface - + 32-bit for enhanced performance on Xen/VMWare - + pvops kernel with Xen PV drivers, KVM virtio drivers, and VMware tools for optimum performance on all hypervisors - + Xen tools inclusion allows performance monitoring - + Latest versions of HAProxy, iptables, IPsec, and Apache from debian repository ensures improved security and speed - + Latest version of JRE from Sun/Oracle ensures improved security and speed Multiple System VM Support for VMware16.2. Multiple System VM Support for VMware Every CloudStack zone has single System VM for template processing tasks such as downloading templates, uploading templates, and uploading ISOs. In a zone where VMware is being used, additional System VMs can be launched to process VMware-specific tasks such as taking snapshots and creating private templates. The CloudStack management server launches additional System VMs for VMware-specific tasks as the load increases. The management server monitors and weights all commands sent to these System VMs and performs dynamic load balancing and scaling-up of more System VMs. @@ -4082,7 +4082,7 @@ usage.aggregation.timezone = GMT The Console Proxy is a type of System Virtual Machine that has a role in presenting a console view via the web UI. It connects the user’s browser to the VNC port made available via the hypervisor for the console of the guest. Both the administrator and end user web UIs offer a console connection. Clicking on a console icon brings up a new window. The AJAX code downloaded into that window refers to the public IP address of a console proxy VM. There is exactly one public IP address allocated per console proxy VM. The AJAX application connects to this IP. The console proxy then proxies the connection to the VNC port for the requested VM on the Host hosting the guest. . - Note + Note The hypervisors will have many ports assigned to VNC usage so that multiple VNC sessions can occur simultaneously. There is never any traffic to the guest virtual IP, and there is no need to enable VNC within the guest. @@ -4134,42 +4134,42 @@ usage.aggregation.timezone = GMT You can work with tags through the UI or through the API commands createTags, deleteTags, and listTags. You can define multiple tags for each resource. There is no limit on the number of tags you can define. Each tag can be up to 255 characters long. Users can define tags on the resources they own, and administrators can define tags on any resources in the cloud. An optional input parameter, "tags," exists on many of the list* API commands. The following example shows how to use this new parameter to find all the volumes having tag region=canada OR tag city=Toronto: - command=listVolumes + command=listVolumes &listAll=true &tags[0].key=region &tags[0].value=canada &tags[1].key=city &tags[1].value=Toronto The following API commands have the "tags" input parameter: - + listVirtualMachines - + listVolumes - + listSnapshots - + listNetworks - + listTemplates - + listIsos - + listFirewallRules - + listPortForwardingRules - + listPublicIpAddresses - + listSecurityGroups - + listLoadBalancerRules - + listProjects - + listVPCs - + listNetworkACLs - + listStaticRoutes Changing the Database Configuration18.2. Changing the Database Configuration The CloudStack Management Server stores database configuration information (e.g., hostname, port, credentials) in the file /etc/cloud/management/db.properties. To effect a change, edit this file on each Management Server, then restart the Management Server. @@ -4179,33 +4179,33 @@ usage.aggregation.timezone = GMT Events track all of the user and administrator actions in the cloud. For example, every guest VM start creates an associated event. Events are stored in the Management Server’s database. Emails will be sent to administrators under the following circumstances: - + The Management Server cluster runs low on CPU, memory, or storage resources - + The Management Server loses heartbeat from a Host for more than 3 minutes - + The Host cluster runs low on CPU, memory, or storage resources Customizing the Network Domain Name18.4. Customizing the Network Domain Name The root administrator can optionally assign a custom DNS suffix at the level of a network, account, domain, zone, or entire CloudStack installation, and a domain administrator can do so within their own domain. To specify a custom domain name and put it into effect, follow these steps. - 1. + 1. Set the DNS suffix at the desired scope - + At the network level, the DNS suffix can be assigned through the UI when creating a new network, as described in Section 15.6.1, “Adding an Additional Guest Network” or with the updateNetwork command in the CloudStack API. - + At the account, domain, or zone level, the DNS suffix can be assigned with the appropriate CloudStack API commands: createAccount, editAccount, createDomain, editDomain, createZone, or editZone. - + At the global level, use the configuration parameter guest.domain.suffix. You can also use the CloudStack API command updateConfiguration. After modifying this global configuration, restart the Management Server to put the new setting into effect. - 2. + 2. To make the new DNS suffix take effect for an existing network, call the CloudStack API command updateNetwork. This step is not necessary when the DNS suffix was specified while creating a new network. The source of the network domain that is used depends on the following rules. - + For all networks, if a network domain is specified as part of a network's own configuration, that value is used. - + For an account-specific network, the network domain specified for the account is used. If none is specified, the system looks for a value in the domain, zone, and global configuration, in that order. - + For a domain-specific network, the network domain specified for the domain is used. If none is specified, the system looks for a value in the zone and global configuration, in that order. - + For a zone-specific network, the network domain specified for the zone is used. If none is specified, the system looks for a value in the global configuration. Stopping and Restarting the Management Server18.5. Stopping and Restarting the Management Server The root administrator will need to stop and restart the Management Server from time to time. @@ -4213,25 +4213,25 @@ usage.aggregation.timezone = GMT For example, after changing a global configuration parameter, a restart is required. If you have multiple Management Server nodes, restart all of them to put the new parameter value into effect consistently throughout the cloud. To stop the Management Server, issue the following command at the operating system prompt on the Management Server node: - # service cloud-management stop + # service cloud-management stop To start the Management Server: - # service cloud-management start + # service cloud-management start To stop the Management Server: - # service cloud-management stopChapter 19.Chapter 19. Setting Global Configuration ParametersSetting Global Configuration Parameters + # service cloud-management stopChapter 19.Chapter 19. Setting Global Configuration ParametersSetting Global Configuration Parameters CloudStack provides parameters that you can set to control many aspects of the cloud. When CloudStack is first installed, and periodically thereafter, you might need to modify these settings. - 1. + 1. Log in to the UI as administrator. - 2. + 2. In the left navigation bar, click Global Settings. - 3. + 3. In Select View, choose one of the following: - + Global Settings. This displays a list of the parameters with brief descriptions and current values. - + Hypervisor Capabilities. This displays a list of hypervisor versions with the maximum number of guests supported for each. - 4. + 4. Use the search box to narrow down the list to those you are interested in. - 5. + 5. Click the Edit icon to modify a value. If you are viewing Hypervisor Capabilities, you must click the name of the hypervisor first to display the editing screen. Chapter 20.Chapter 20. CloudStack APICloudStack API The CloudStack API is a low level API that has been used to implement the CloudStack web UIs. It is also a good basis for implementing other popular APIs such as EC2/S3 and emerging DMTF standards. @@ -4251,25 +4251,25 @@ usage.aggregation.timezone = GMT CloudStack provides API access to attach user data to a deployed VM. Deployed VMs also have access to instance metadata via the virtual router. User data can be accessed once the IP address of the virtual router is known. Once the IP address is known, use the following steps to access the user data: - 1. + 1. Run the following command to find the virtual router. - # cat /var/lib/dhclient/dhclient-eth0.leases | grep dhcp-server-identifier | tail -12. + # cat /var/lib/dhclient/dhclient-eth0.leases | grep dhcp-server-identifier | tail -12. Access user data by running the following command using the result of the above command - # curl http://10.1.1.1/latest/user-data + # curl http://10.1.1.1/latest/user-data Meta Data can be accessed similarly, using a URL of the form http://10.1.1.1/latest/meta-data/{metadata type}. (For backwards compatibility, the previous URL http://10.1.1.1/latest/{metadata type} is also supported.) For metadata type, use one of the following: - + service-offering. A description of the VMs service offering - + availability-zone. The Zone name - + local-ipv4. The guest IP of the VM - + local-hostname. The hostname of the VM - + public-ipv4. The first public IP for the router. (E.g. the first IP of eth2) - + public-hostname. This is the same as public-ipv4 - + instance-id. The instance name of the VM Chapter 21.Chapter 21. TuningTuning This section provides tips on how to improve the performance of your cloud. @@ -4277,25 +4277,25 @@ usage.aggregation.timezone = GMT Host and guest performance monitoring is available to end users and administrators. This allows the user to monitor their utilization of resources and determine when it is appropriate to choose a more powerful service offering or larger disk. Increase Management Server Maximum Memory21.2. Increase Management Server Maximum Memory If the Management Server is subject to high demand, the default maximum JVM memory allocation can be insufficient. To increase the memory: - 1. + 1. Edit the Tomcat configuration file: - /etc/cloud/management/tomcat6.conf2. + /etc/cloud/management/tomcat6.conf2. Change the command-line parameter -XmxNNNm to a higher value of N. For example, if the current value is -Xmx128m, change it to -Xmx1024m or higher. - 3. + 3. To put the new setting into effect, restart the Management Server. - # service cloud-management restart + # service cloud-management restart For more information about memory issues, see "FAQ: Memory" at Tomcat Wiki.11 http://wiki.apache.org/tomcat/FAQ/Memory Set Database Buffer Pool Size21.3. Set Database Buffer Pool Size It is important to provide enough memory space for the MySQL database to cache data and indexes: - 1. + 1. Edit the Tomcat configuration file: - /etc/my.cnf2. + /etc/my.cnf2. Insert the following line in the [mysqld] section, below the datadir line. Use a value that is appropriate for your situation. We recommend setting the buffer pool at 40% of RAM if MySQL is on the same server as the management server or 70% of RAM if MySQL has a dedicated server. The following example assumes a dedicated server with 1024M of RAM. - innodb_buffer_pool_size=700M3. + innodb_buffer_pool_size=700M3. Restart the MySQL service. - # service mysqld restart + # service mysqld restart For more information about the buffer pool, see "The InnoDB Buffer Pool" at MySQL Reference Manual22 http://dev.mysql.com/doc/refman/5.5/en/innodb-buffer-pool.html. Set and Monitor Total VM Limits per Host21.4. Set and Monitor Total VM Limits per Host The CloudStack administrator should monitor the total number of VM instances in each cluster, and disable allocation to the cluster if the total is approaching the maximum that the hypervisor can handle. Be sure to leave a safety margin to allow for the possibility of one or more hosts failing, which would increase the VM load on the other hosts as the VMs are automatically redeployed. Consult the documentation for your chosen hypervisor to find the maximum permitted number of VMs per host, then use CloudStack global configuration settings to set this as the default limit. Monitor the VM activity in each cluster at all times. Keep the total number of VMs below a safe level that allows for the occasional host failure. For example, if there are N hosts in the cluster, and you want to allow for one host in the cluster to be down at any given time, the total number of VM instances you can permit in the cluster is at most (N-1) * (per-host-limit). Once a cluster reaches this number of VMs, use the CloudStack UI to disable allocation of more VMs to the cluster. @@ -4305,59 +4305,59 @@ usage.aggregation.timezone = GMT There are two types of events logged in the CloudStack Event Log. Standard events log the success or failure of an event and can be used to identify jobs or processes that have failed. There are also long running job events. Events for asynchronous jobs log when a job is scheduled, when it starts, and when it completes. Other long running synchronous jobs log when a job starts, and when it completes. Long running synchronous and asynchronous event logs can be used to gain more information on the status of a pending job or can be used to identify a job that is hanging or has not started. The following sections provide more information on these events.. Standard Events22.1.2. Standard Events The events log records three types of standard events. - + INFO. This event is generated when an operation has been successfully performed. - + WARN. This event is generated in the following circumstances. - + When a network is disconnected while monitoring a template download. - + When a template download is abandoned. - + When an issue on the storage server causes the volumes to fail over to the mirror storage server. - + ERROR. This event is generated when an operation has not been successfully performed Long Running Job Events22.1.3. Long Running Job Events The events log records three types of standard events. - + INFO. This event is generated when an operation has been successfully performed. - + WARN. This event is generated in the following circumstances. - + When a network is disconnected while monitoring a template download. - + When a template download is abandoned. - + When an issue on the storage server causes the volumes to fail over to the mirror storage server. - + ERROR. This event is generated when an operation has not been successfully performed Event Log Queries22.1.4. Event Log Queries Database logs can be queried from the user interface. The list of events captured by the system includes: - + Virtual machine creation, deletion, and on-going management operations - + Virtual router creation, deletion, and on-going management operations - + Template creation and deletion - + Network/load balancer rules creation and deletion - + Storage volume creation and deletion - + User login and logout Working with Server Logs22.2. Working with Server Logs The CloudStack Management Server logs all web site, middle tier, and database activities for diagnostics purposes in /var/log/cloud/management/. The CloudStack logs a variety of error messages. We recommend this command to find the problematic output in the Management Server log:. - Note + Note When copying and pasting a command, be sure the command has pasted as a single line before executing. Some document viewers may introduce unwanted line breaks in copied text. - + grep -i -E 'exception|unable|fail|invalid|leak|warn|error' /var/log/cloud/management/management-server.log The CloudStack processes requests with a Job ID. If you find an error in the logs and you are interested in debugging the issue you can grep for this job ID in the management server log. For example, suppose that you find the following ERROR message: - + 2010-10-04 13:49:32,595 ERROR [cloud.vm.UserVmManagerImpl] (Job-Executor-11:job-1076) Unable to find any host for [User|i-8-42-VM-untagged] Note that the job ID is 1076. You can track back the events relating to job 1076 with the following grep: - + grep "job-1076)" management-server.log The CloudStack Agent Server logs its activities in /var/log/cloud/agent/. @@ -4367,7 +4367,7 @@ usage.aggregation.timezone = GMT It is possible that a client from outside the intended pool has mounted the storage. When this occurs, the LVM is wiped and all data in the volume is lost Solution When setting up LUN exports, restrict the range of IP addresses that are allowed access by specifying a subnet mask. For example: - echo “/export 192.168.1.0/24(rw,async,no_root_squash)” > /etc/exports + echo “/export 192.168.1.0/24(rw,async,no_root_squash)” > /etc/exports Adjust the above command to suit your deployment needs. More Information See the export procedure in the "Secondary Storage" section of the CloudStack Installation Guide @@ -4377,11 +4377,11 @@ usage.aggregation.timezone = GMT The Virtual router is lost or down. Solution If you are sure that a virtual router is down forever, or no longer functions as expected, destroy it. You must create one afresh while keeping the backup router up and running (it is assumed this is in a redundant router setup): - + Force stop the router. Use the stopRouter API with forced=true parameter to do so. - + Before you continue with destroying this router, ensure that the backup router is running. Otherwise the network connection will be lost. - + Destroy the router by using the destroyRouter API. Recreate the missing router by using the restartNetwork API with cleanup=false parameter. For more information about redundant router setup, see Creating a New Network Offering. @@ -4403,11 +4403,11 @@ usage.aggregation.timezone = GMT Remove the ISO and re-upload the template. Unable to power on virtual machine on VMware22.7. Unable to power on virtual machine on VMwareSymptom Virtual machine does not power on. You might see errors like: - + Unable to open Swap File - + Unable to access a file since it is locked - + Unable to access Virtual machine configuration Cause A known issue on VMware machines. ESX hosts lock certain critical virtual machine files and file systems to prevent concurrent changes. Sometimes the files are not unlocked when the virtual machine is powered off. When a virtual machine attempts to power on, it can not access these critical files, and the virtual machine is unable to power on. @@ -4423,7 +4423,7 @@ usage.aggregation.timezone = GMT Create a firewall rule on the virtual router for each of your existing load balancing rules so that they continue to function. Appendix A. Time ZonesAppendix A. Time Zones The following time zone identifiers are accepted by CloudStack. There are several places that have a time zone as a required or optional parameter. These include scheduling recurring snapshots, creating a user, and specifying the usage time zone in the Configuration table. - + Etc/GMT+12 @@ -4662,7 +4662,7 @@ usage.aggregation.timezone = GMT - Appendix B. Event TypesAppendix B. Event Types + Appendix B. Event TypesAppendix B. Event Types VM.CREATE @@ -5107,9 +5107,9 @@ usage.aggregation.timezone = GMT Appendix C. AlertsAppendix C. Alerts The following is the list of alert type numbers. The current alerts can be found by calling listAlerts. - MEMORY = 0CPU = 1STORAGE =2STORAGE_ALLOCATED = 3PUBLIC_IP = 4PRIVATE_IP = 5HOST = 6USERVM = 7DOMAIN_ROUTER = 8CONSOLE_PROXY = 9ROUTING = 10// lost connection to default route (to the gateway)STORAGE_MISC = 11 // lost connection to default route (to the gateway)USAGE_SERVER = 12 // lost connection to default route (to the gateway)MANAGMENT_NODE = 13 // lost connection to default route (to the gateway)DOMAIN_ROUTER_MIGRATE = 14CONSOLE_PROXY_MIGRATE = 15USERVM_MIGRATE = 16VLAN = 17SSVM = 18USAGE_SERVER_RESULT = 19STORAGE_DELETE = 20;UPDATE_RESOURCE_COUNT = 21; //Generated when we fail to update the resource countUSAGE_SANITY_RESULT = 22;DIRECT_ATTACHED_PUBLIC_IP = 23;LOCAL_STORAGE = 24;RESOURCE_LIMIT_EXCEEDED = 25; //Generated when the resource limit exceeds the limit. Currently used for recurring snapshots onlyAppendix D. Revision HistoryAppendix D. Revision History + MEMORY = 0CPU = 1STORAGE =2STORAGE_ALLOCATED = 3PUBLIC_IP = 4PRIVATE_IP = 5HOST = 6USERVM = 7DOMAIN_ROUTER = 8CONSOLE_PROXY = 9ROUTING = 10// lost connection to default route (to the gateway)STORAGE_MISC = 11 // lost connection to default route (to the gateway)USAGE_SERVER = 12 // lost connection to default route (to the gateway)MANAGMENT_NODE = 13 // lost connection to default route (to the gateway)DOMAIN_ROUTER_MIGRATE = 14CONSOLE_PROXY_MIGRATE = 15USERVM_MIGRATE = 16VLAN = 17SSVM = 18USAGE_SERVER_RESULT = 19STORAGE_DELETE = 20;UPDATE_RESOURCE_COUNT = 21; //Generated when we fail to update the resource countUSAGE_SANITY_RESULT = 22;DIRECT_ATTACHED_PUBLIC_IP = 23;LOCAL_STORAGE = 24;RESOURCE_LIMIT_EXCEEDED = 25; //Generated when the resource limit exceeds the limit. Currently used for recurring snapshots onlyAppendix D. Revision HistoryAppendix D. Revision History Revision 0-0Tue May 29 2012Jessica Tomechak - Initial creation of book by publican + Initial creation of book by publican diff --git a/docs/tmp/en-US/xml/Release_Notes.fo b/docs/tmp/en-US/xml/Release_Notes.fo index 50e6b6e9de2..2537279d2be 100644 --- a/docs/tmp/en-US/xml/Release_Notes.fo +++ b/docs/tmp/en-US/xml/Release_Notes.fo @@ -1,8 +1,8 @@ -Version 4.0.0-incubating Release Notes - Revised October 17, 2012 19:49 UTCDocBook XSL Stylesheets with Apache FOPVersion 4.0.0-incubating Release NotesTable of ContentsChapter 1. Submitting Feedback and Getting HelpChapter 2. Upgrade Instructions2.1. Upgrade from 3.0.2 to 4.0.0-incubating2.2. Upgrade from 2.2.14 to 4.0.0-incubatingChapter 3. Version 4.0.0-incubating3.1. What’s New in 4.0.0-incubating3.1.1. Inter-VLAN Routing3.1.2. Site-to-Site VPN3.1.3. Local Storage Support for Data Volumes3.1.4. Tags3.1.5. AWS API Changes for Tags3.1.6. Secure Console Access on XenServer3.1.7. Stopped VM3.1.8. Uploading an Existing Volume to a Virtual Machine3.1.9. Dedicated High-Availability Hosts3.1.10. Support for Amazon Web Services API3.1.11. The Nicira NVP Plugin3.1.12. Support for CAStor Cluster3.1.13. Clustered Logical Volume Manager Support for KVM3.1.14. Rados Block Device Support for KVM3.2. Issues Fixed in 4.0.0-incubating3.3. Known Issues in 4.0.0-incubatingChapter 4. API Changes from 3.0.2 to 4.0.0-incubating4.1. New API Commands in 4.0.0-incubating4.2. Changed API Commands in 4.0.0-incubatingVersion 4.0.0-incubating Release NotesApache CloudStack Version 4.0.0-incubating Release NotesRevised October 17, 2012 19:49 UTC +Version 4.0.0-incubating Release Notes - Revised October 17, 2012 19:49 UTCDocBook XSL Stylesheets with Apache FOPVersion 4.0.0-incubating Release NotesTable of ContentsChapter 1. Submitting Feedback and Getting HelpChapter 2. Upgrade Instructions2.1. Upgrade from 3.0.2 to 4.0.0-incubating2.2. Upgrade from 2.2.14 to 4.0.0-incubatingChapter 3. Version 4.0.0-incubating3.1. What’s New in 4.0.0-incubating3.1.1. Inter-VLAN Routing3.1.2. Site-to-Site VPN3.1.3. Local Storage Support for Data Volumes3.1.4. Tags3.1.5. AWS API Changes for Tags3.1.6. Secure Console Access on XenServer3.1.7. Stopped VM3.1.8. Uploading an Existing Volume to a Virtual Machine3.1.9. Dedicated High-Availability Hosts3.1.10. Support for Amazon Web Services API3.1.11. The Nicira NVP Plugin3.1.12. Support for CAStor Cluster3.1.13. Clustered Logical Volume Manager Support for KVM3.1.14. Rados Block Device Support for KVM3.2. Issues Fixed in 4.0.0-incubating3.3. Known Issues in 4.0.0-incubatingChapter 4. API Changes from 3.0.2 to 4.0.0-incubating4.1. New API Commands in 4.0.0-incubating4.2. Changed API Commands in 4.0.0-incubatingVersion 4.0.0-incubating Release NotesApache CloudStack Version 4.0.0-incubating Release NotesRevised October 17, 2012 19:49 UTC - Apache CloudStackApache CloudStack Version 4.0.0-incubating Release NotesRevised October 17, 2012 19:49 UTCAuthorApache CloudStack + Apache CloudStackApache CloudStack Version 4.0.0-incubating Release NotesRevised October 17, 2012 19:49 UTCAuthorApache CloudStack 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 @@ -14,7 +14,7 @@ Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. Release notes for the Apache CloudStack 4.0.0-incubating release. - Version 4.0.0-incubating Release Notes1. Submitting Feedback and Getting Help   2. Upgrade Instructions   2.1. Upgrade from 3.0.2 to 4.0.0-incubating 2.2. Upgrade from 2.2.14 to 4.0.0-incubating 3. Version 4.0.0-incubating   3.1. What’s New in 4.0.0-incubating 3.2. Issues Fixed in 4.0.0-incubating 3.3. Known Issues in 4.0.0-incubating 4. API Changes from 3.0.2 to 4.0.0-incubating   4.1. New API Commands in 4.0.0-incubating 4.2. Changed API Commands in 4.0.0-incubating Chapter 1.Chapter 1. Submitting Feedback and Getting HelpSubmitting Feedback and Getting Help + Version 4.0.0-incubating Release Notes1. Submitting Feedback and Getting Help   2. Upgrade Instructions   2.1. Upgrade from 3.0.2 to 4.0.0-incubating 2.2. Upgrade from 2.2.14 to 4.0.0-incubating 3. Version 4.0.0-incubating   3.1. What’s New in 4.0.0-incubating 3.2. Issues Fixed in 4.0.0-incubating 3.3. Known Issues in 4.0.0-incubating 4. API Changes from 3.0.2 to 4.0.0-incubating   4.1. New API Commands in 4.0.0-incubating 4.2. Changed API Commands in 4.0.0-incubating Chapter 1.Chapter 1. Submitting Feedback and Getting HelpSubmitting Feedback and Getting Help The Apache CloudStack project has mailing lists for users and developers. These are the official channels of communication for the project and are the best way to get answers about using and contributing to CloudStack. It's a good idea to subscribe to the cloudstack-users mailing list if you've deployed or are deploying CloudStack into production, and even for test deployments. The CloudStack developer's mailing list (cloudstack-dev) is for discussions about CloudStack development, and is the best list for discussing possible bugs in CloudStack. Anyone contributing to CloudStack should be on this mailing list. @@ -24,27 +24,27 @@ To posts to the lists, you'll need to be subscribed. See the CloudStack Web site22 http://incubator.apache.org/cloudstack/mailing-lists.html for instructions. Chapter 2.Chapter 2. Upgrade InstructionsUpgrade InstructionsUpgrade from 3.0.2 to 4.0.0-incubating2.1. Upgrade from 3.0.2 to 4.0.0-incubating Perform the following to upgrade from version 3.0.2 to version 4.0.0-incubating. Note that some of the steps here are only required if you're using a specific hypervisor. The steps that are hypervisor-specific are called out with a note. - 1. + 1. Ensure that you query your IP address usage records and process them or make a backup. During the upgrade you will lose the old IP address usage records. Starting in 3.0.2, the usage record format for IP addresses is the same as the rest of the usage types. Instead of a single record with the assignment and release dates, separate records are generated per aggregation period with start and end dates. After upgrading, any existing IP address usage records in the old format will no longer be available. - 2.Note + 2.Note The following upgrade instructions apply only if you're using VMware hosts. If you're not using VMware hosts, skip this step and move on to step 3: stopping all usage servers. In each zone that includes VMware hosts, you need to add a new system VM template. - a. + a. While running the existing 3.0.2 system, log in to the UI as root administrator. - b. + b. In the left navigation bar, click Templates. - c. + c. In Select view, click Templates. - d. + d. Click Register template. The Register template dialog box is displayed. - e. + e. In the Register template dialog box, specify the following values (do not change these): - + Field @@ -140,61 +140,61 @@ no - f. + f. Watch the screen to be sure that the template downloads successfully and enters the READY state. Do not proceed until this is successful. - 3. + 3. Stop all Usage Servers if running. Run this on all Usage Server hosts. - # service cloud-usage stop4. + # service cloud-usage stop4. Stop the Management Servers. Run this on all Management Server hosts. - # service cloud-management stop5. + # service cloud-management stop5. On the MySQL master, take a backup of the MySQL databases. We recommend performing this step even in test upgrades. If there is an issue, this will assist with debugging. In the following commands, it is assumed that you have set the root password on the database, which is a CloudStack recommended best practice. Substitute your own MySQL root password. - # mysqldump -u root -pmysql_password cloud > cloud-backup.dmp -# mysqldump -u root -pmysql_password cloud_usage > cloud-usage-backup.dmp6. + # mysqldump -u root -pmysql_password cloud > cloud-backup.dmp +# mysqldump -u root -pmysql_password cloud_usage > cloud-usage-backup.dmp6. Either build RPM/DEB packages as detailed in the Installation Guide, or use one of the community provided yum/apt repositories to gain access to the CloudStack binaries. - 7. + 7. After you have configured an appropriate yum or apt repository, you may execute the one of the following commands as appropriate for your environment in order to upgrade CloudStack: -# yum update cloud-* +# yum update cloud-* -# apt-get update +# apt-get update # apt-get upgrade cloud-* You will, of course, have to agree to the changes suggested by Yum or APT. - Note + Note If the upgrade output includes a message similar to the following, then some custom content was found in your old components.xml, and you need to merge the two files: - warning: /etc/cloud/management/components.xml created as /etc/cloud/management/components.xml.rpmnew + warning: /etc/cloud/management/components.xml created as /etc/cloud/management/components.xml.rpmnew Instructions follow in the next step. - 8. + 8. If you have made changes to your copy of /etc/cloud/management/components.xml the changes will be preserved in the upgrade. However, you need to do the following steps to place these changes in a new version of the file which is compatible with version 4.0.0-incubating. - a. + a. Make a backup copy of /etc/cloud/management/components.xml. For example: - # mv /etc/cloud/management/components.xml /etc/cloud/management/components.xml-backupb. + # mv /etc/cloud/management/components.xml /etc/cloud/management/components.xml-backupb. Copy /etc/cloud/management/components.xml.rpmnew to create a new /etc/cloud/management/components.xml: - # cp -ap /etc/cloud/management/components.xml.rpmnew /etc/cloud/management/components.xmlc. + # cp -ap /etc/cloud/management/components.xml.rpmnew /etc/cloud/management/components.xmlc. Merge your changes from the backup file into the new components.xml. - # vi /etc/cloud/management/components.xmlNote + # vi /etc/cloud/management/components.xmlNote If you have more than one management server node, repeat the upgrade steps on each node. - 9. + 9. Start the first Management Server. Do not start any other Management Server nodes yet. - # service cloud-management start + # service cloud-management start Wait until the databases are upgraded. Ensure that the database upgrade is complete. After confirmation, start the other Management Servers one at a time by running the same command on each node. - Note + Note Failing to restart the Management Server indicates a problem in the upgrade. Having the Management Server restarted without any issues indicates that the upgrade is successfully completed. - 10. + 10. Start all Usage Servers (if they were running on your previous version). Perform this on each Usage Server host. # service cloud-usage start - 11.Note + 11.Note Additional steps are required for each KVM host. These steps will not affect running guests in the cloud. These steps are required only for clouds using KVM as hosts and only on the KVM hosts. - a. + a. Configure a yum or apt respository containing the CloudStack packages as outlined in the Installation Guide. - b. + b. Stop the running agent. # service cloud-agent stop - c. + c. Update the agent software with one of the following command sets as appropriate for your environment. # yum update cloud-* @@ -202,32 +202,32 @@ # apt-get update # apt-get upgrade cloud-* - d. + d. Start the agent. - # service cloud-agent starte. + # service cloud-agent starte. Edit /etc/cloud/agent/agent.properties to change the resource parameter from "com.cloud.agent.resource.computing.LibvirtComputingResource" to "com.cloud.hypervisor.kvm.resource.LibvirtComputingResource". - f. + f. Start the cloud agent and cloud management services. - g. + g. When the Management Server is up and running, log in to the CloudStack UI and restart the virtual router for proper functioning of all the features. - 12. + 12. Log in to the CloudStack UI as administrator, and check the status of the hosts. All hosts should come to Up state (except those that you know to be offline). You may need to wait 20 or 30 minutes, depending on the number of hosts. - Note + Note Troubleshooting: If login fails, clear your browser cache and reload the page. Do not proceed to the next step until the hosts show in Up state. - 13. + 13. If you are upgrading from 3.0.2, perform the following: - a. + a. Ensure that the admin port is set to 8096 by using the "integration.api.port" global parameter. This port is used by the cloud-sysvmadm script at the end of the upgrade procedure. For information about how to set this parameter, see "Setting Global Configuration Parameters" in the Installation Guide. - b. + b. Restart the Management Server. - Note + Note If you don't want the admin port to remain open, you can set it to null after the upgrade is done and restart the management server. - 14. + 14. Run the cloud-sysvmadm script to stop, then start, all Secondary Storage VMs, Console Proxy VMs, and virtual routers. Run the script once on each management server. Substitute your own IP address of the MySQL instance, the MySQL user to connect as, and the password to use for that user. In addition to those parameters, provide the -c and -r arguments. For example: # nohup cloud-sysvmadm -d 192.168.1.5 -u cloud -p password -c -r > sysvm.log 2>&1 & @@ -235,11 +235,11 @@ # tail -f sysvm.log This might take up to an hour or more to run, depending on the number of accounts in the system. - 15. + 15. If needed, upgrade all Citrix XenServer hypervisor hosts in your cloud to a version supported by CloudStack 4.0.0-incubating. The supported versions are XenServer 5.6 SP2 and 6.0.2. Instructions for upgrade can be found in the CloudStack 4.0.0-incubating Installation Guide. - 16. + 16. Now apply the XenServer hotfix XS602E003 (and any other needed hotfixes) to XenServer v6.0.2 hypervisor hosts. - a. + a. Disconnect the XenServer cluster from CloudStack. In the left navigation bar of the CloudStack UI, select Infrastructure. Under Clusters, click View All. Select the XenServer cluster and click Actions - Unmanage. @@ -247,17 +247,17 @@ This may fail if there are hosts not in one of the states Up, Down, Disconnected, or Alert. You may need to fix that before unmanaging this cluster. Wait until the status of the cluster has reached Unmanaged. Use the CloudStack UI to check on the status. When the cluster is in the unmanaged state, there is no connection to the hosts in the cluster. - b. + b. To clean up the VLAN, log in to one XenServer host and run: /opt/xensource/bin/cloud-clean-vlan.sh - c. + c. Now prepare the upgrade by running the following on one XenServer host: /opt/xensource/bin/cloud-prepare-upgrade.sh If you see a message like "can't eject CD", log in to the VM and unmount the CD, then run this script again. - d. + d. Upload the hotfix to the XenServer hosts. Always start with the Xen pool master, then the slaves. Using your favorite file copy utility (e.g. WinSCP), copy the hotfixes to the host. Place them in a temporary folder such as /tmp. On the Xen pool master, upload the hotfix with this command: @@ -265,9 +265,9 @@ xe patch-upload file-name=XS602E003.xsupdate Make a note of the output from this command, which is a UUID for the hotfix file. You'll need it in another step later. - Note + Note (Optional) If you are applying other hotfixes as well, you can repeat the commands in this section with the appropriate hotfix number. For example, XS602E004.xsupdate. - e. + e. Manually live migrate all VMs on this host to another host. First, get a list of the VMs on this host: # xe vm-list @@ -275,17 +275,17 @@ Then use this command to migrate each VM. Replace the example host name and VM name with your own: # xe vm-migrate live=true host=host-name vm=VM-name - Troubleshooting + Troubleshooting If you see a message like "You attempted an operation on a VM which requires PV drivers to be installed but the drivers were not detected," run: /opt/xensource/bin/make_migratable.sh b6cf79c8-02ee-050b-922f-49583d9f1a14. - f. + f. Apply the hotfix. First, get the UUID of this host: - # xe host-list + # xe host-list Then use the following command to apply the hotfix. Replace the example host UUID with the current host ID, and replace the hotfix UUID with the output from the patch-upload command you ran on this machine earlier. You can also get the hotfix UUID by running xe patch-list. - xe patch-apply host-uuid=host-uuid uuid=hotfix-uuidg. + xe patch-apply host-uuid=host-uuid uuid=hotfix-uuidg. Copy the following files from the CloudStack Management Server to the host. - + Copy from here... @@ -317,55 +317,55 @@ /opt/xensource/bin/make_migratable.sh - h. + h. (Only for hotfixes XS602E005 and XS602E007) You need to apply a new Cloud Support Pack. - + Download the CSP software onto the XenServer host from one of the following links: For hotfix XS602E005: http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E005/56710/xe-phase-2/xenserver-cloud-supp.tgz For hotfix XS602E007: http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E007/57824/xe-phase-2/xenserver-cloud-supp.tgz - + Extract the file: - # tar xf xenserver-cloud-supp.tgz + # tar xf xenserver-cloud-supp.tgz Run the following script: - # xe-install-supplemental-pack xenserver-cloud-supp.iso + # xe-install-supplemental-pack xenserver-cloud-supp.iso If the XenServer host is part of a zone that uses basic networking, disable Open vSwitch (OVS): - # xe-switch-network-backend bridgei. + # xe-switch-network-backend bridgei. Reboot this XenServer host. - j. + j. Run the following: - /opt/xensource/bin/setupxenserver.shNote + /opt/xensource/bin/setupxenserver.shNote If the message "mv: cannot stat `/etc/cron.daily/logrotate': No such file or directory" appears, you can safely ignore it. - k. + k. Run the following: - for pbd in `xe pbd-list currently-attached=false| grep ^uuid | awk '{print $NF}'`; do xe pbd-plug uuid=$pbd ;l. + for pbd in `xe pbd-list currently-attached=false| grep ^uuid | awk '{print $NF}'`; do xe pbd-plug uuid=$pbd ;l. On each slave host in the Xen pool, repeat these steps, starting from "manually live migrate VMs." - Troubleshooting Tip + Troubleshooting Tip If passwords which you know to be valid appear not to work after upgrade, or other UI issues are seen, try clearing your browser cache and reloading the UI page. - Upgrade from 2.2.14 to 4.0.0-incubating2.2. Upgrade from 2.2.14 to 4.0.0-incubating1. + Upgrade from 2.2.14 to 4.0.0-incubating2.2. Upgrade from 2.2.14 to 4.0.0-incubating1. Ensure that you query your IPaddress usage records and process them; for example, issue invoices for any usage that you have not yet billed users for. Starting in 3.0.2, the usage record format for IP addresses is the same as the rest of the usage types. Instead of a single record with the assignment and release dates, separate records are generated per aggregation period with start and end dates. After upgrading to 4.0.0-incubating, any existing IP address usage records in the old format will no longer be available. - 2. + 2. If you are using version 2.2.0 - 2.2.13, first upgrade to 2.2.14 by using the instructions in the 2.2.14 Release Notes. - KVM Hosts + KVM Hosts If KVM hypervisor is used in your cloud, be sure you completed the step to insert a valid username and password into the host_details table on each KVM node as described in the 2.2.14 Release Notes. This step is critical, as the database will be encrypted after the upgrade to 4.0.0-incubating. - 3. + 3. While running the 2.2.14 system, log in to the UI as root administrator. - 4. + 4. Using the UI, add a new System VM template for each hypervisor type that is used in your cloud. In each zone, add a system VM template for each hypervisor used in that zone - a. + a. In the left navigation bar, click Templates. - b. + b. In Select view, click Templates. - c. + c. Click Register template. The Register template dialog box is displayed. - d. + d. In the Register template dialog box, specify the following values depending on the hypervisor type (do not change these): - + Hypervisor @@ -490,109 +490,109 @@ Featured: no - 5. + 5. Watch the screen to be sure that the template downloads successfully and enters the READY state. Do not proceed until this is successful - 6. + 6. WARNING: If you use more than one type of hypervisor in your cloud, be sure you have repeated these steps to download the system VM template for each hypervisor type. Otherwise, the upgrade will fail. - 7. + 7. Stop all Usage Servers if running. Run this on all Usage Server hosts. - # service cloud-usage stop8. + # service cloud-usage stop8. Stop the Management Servers. Run this on all Management Server hosts. - # service cloud-management stop9. + # service cloud-management stop9. On the MySQL master, take a backup of the MySQL databases. We recommend performing this step even in test upgrades. If there is an issue, this will assist with debugging. In the following commands, it is assumed that you have set the root password on the database, which is a CloudStack recommended best practice. Substitute your own MySQL root password. - # mysqldump -u root -pmysql_password cloud > cloud-backup.dmp -# mysqldump -u root -pmysql_password cloud_usage > cloud-usage-backup.dmp10. + # mysqldump -u root -pmysql_password cloud > cloud-backup.dmp +# mysqldump -u root -pmysql_password cloud_usage > cloud-usage-backup.dmp10. Either build RPM/DEB packages as detailed in the Installation Guide, or use one of the community provided yum/apt repositories to gain access to the CloudStack binaries. - 11. + 11. After you have configured an appropriate yum or apt repository, you may execute the one of the following commands as appropriate for your environment in order to upgrade CloudStack: -# yum update cloud-* +# yum update cloud-* -# apt-get update +# apt-get update # apt-get upgrade cloud-* You will, of course, have to agree to the changes suggested by Yum or APT. - 12. + 12. If you have made changes to your existing copy of the file components.xml in your previous-version CloudStack installation, the changes will be preserved in the upgrade. However, you need to do the following steps to place these changes in a new version of the file which is compatible with version 4.0.0-incubating. - Note + Note How will you know whether you need to do this? If the upgrade output in the previous step included a message like the following, then some custom content was found in your old components.xml, and you need to merge the two files: - warning: /etc/cloud/management/components.xml created as /etc/cloud/management/components.xml.rpmnewa. + warning: /etc/cloud/management/components.xml created as /etc/cloud/management/components.xml.rpmnewa. Make a backup copy of your /etc/cloud/management/components.xml file. For example: - # mv /etc/cloud/management/components.xml /etc/cloud/management/components.xml-backupb. + # mv /etc/cloud/management/components.xml /etc/cloud/management/components.xml-backupb. Copy /etc/cloud/management/components.xml.rpmnew to create a new /etc/cloud/management/components.xml: - # cp -ap /etc/cloud/management/components.xml.rpmnew /etc/cloud/management/components.xmlc. + # cp -ap /etc/cloud/management/components.xml.rpmnew /etc/cloud/management/components.xmlc. Merge your changes from the backup file into the new components.xml file. - # vi /etc/cloud/management/components.xml -13. + # vi /etc/cloud/management/components.xml +13. If you have made changes to your existing copy of the /etc/cloud/management/db.properties file in your previous-version CloudStack installation, the changes will be preserved in the upgrade. However, you need to do the following steps to place these changes in a new version of the file which is compatible with version 4.0.0-incubating. - a. + a. Make a backup copy of your file /etc/cloud/management/db.properties. For example: - # mv /etc/cloud/management/db.properties /etc/cloud/management/db.properties-backupb. + # mv /etc/cloud/management/db.properties /etc/cloud/management/db.properties-backupb. Copy /etc/cloud/management/db.properties.rpmnew to create a new /etc/cloud/management/db.properties: - # cp -ap /etc/cloud/management/db.properties.rpmnew etc/cloud/management/db.propertiesc. + # cp -ap /etc/cloud/management/db.properties.rpmnew etc/cloud/management/db.propertiesc. Merge your changes from the backup file into the new db.properties file. - # vi /etc/cloud/management/db.properties14. + # vi /etc/cloud/management/db.properties14. On the management server node, run the following command. It is recommended that you use the command-line flags to provide your own encryption keys. See Password and Key Encryption in the Installation Guide. - # cloud-setup-encryption -e encryption_type -m management_server_key -k database_key + # cloud-setup-encryption -e encryption_type -m management_server_key -k database_key When used without arguments, as in the following example, the default encryption type and keys will be used: - + (Optional) For encryption_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. - + (Optional) For management_server_key, substitute the default key that is used to encrypt confidential parameters in the properties file. Default: password. It is highly recommended that you replace this with a more secure value - + (Optional) For database_key, substitute the default key that is used to encrypt confidential parameters in the CloudStack database. Default: password. It is highly recommended that you replace this with a more secure value. - 15. + 15. Repeat steps 10 - 14 on every management server node. If you provided your own encryption key in step 14, use the same key on all other management servers. - 16. + 16. Start the first Management Server. Do not start any other Management Server nodes yet. - # service cloud-management start + # service cloud-management start Wait until the databases are upgraded. Ensure that the database upgrade is complete. You should see a message like "Complete! Done." After confirmation, start the other Management Servers one at a time by running the same command on each node. - 17. + 17. Start all Usage Servers (if they were running on your previous version). Perform this on each Usage Server host. - # service cloud-usage start18. + # service cloud-usage start18. (KVM only) Additional steps are required for each KVM host. These steps will not affect running guests in the cloud. These steps are required only for clouds using KVM as hosts and only on the KVM hosts. - a. + a. Configure your CloudStack package repositories as outlined in the Installation Guide - b. + b. Stop the running agent. - # service cloud-agent stopc. + # service cloud-agent stopc. Update the agent software with one of the following command sets as appropriate. - # yum update cloud-* + # yum update cloud-* # apt-get update # apt-get upgrade cloud-* -d. +d. Start the agent. - # service cloud-agent starte. + # service cloud-agent starte. Copy the contents of the agent.properties file to the new agent.properties file by using the following command - sed -i 's/com.cloud.agent.resource.computing.LibvirtComputingResource/com.cloud.hypervisor.kvm.resource.LibvirtComputingResource/g' /etc/cloud/agent/agent.propertiesf. + sed -i 's/com.cloud.agent.resource.computing.LibvirtComputingResource/com.cloud.hypervisor.kvm.resource.LibvirtComputingResource/g' /etc/cloud/agent/agent.propertiesf. Start the cloud agent and cloud management services. - g. + g. When the Management Server is up and running, log in to the CloudStack UI and restart the virtual router for proper functioning of all the features. - 19. + 19. Log in to the CloudStack UI as admin, and check the status of the hosts. All hosts should come to Up state (except those that you know to be offline). You may need to wait 20 or 30 minutes, depending on the number of hosts. Do not proceed to the next step until the hosts show in the Up state. If the hosts do not come to the Up state, contact support. - 20. + 20. Run the following script to stop, then start, all Secondary Storage VMs, Console Proxy VMs, and virtual routers. - a. + a. Run the command once on one management server. Substitute your own IP address of the MySQL instance, the MySQL user to connect as, and the password to use for that user. In addition to those parameters, provide the "-c" and "-r" arguments. For example: - # nohup cloud-sysvmadm -d 192.168.1.5 -u cloud -p password -c -r > sysvm.log 2>&1 & + # nohup cloud-sysvmadm -d 192.168.1.5 -u cloud -p password -c -r > sysvm.log 2>&1 & # tail -f sysvm.log This might take up to an hour or more to run, depending on the number of accounts in the system. - b. + b. After the script terminates, check the log to verify correct execution: - # tail -f sysvm.log + # tail -f sysvm.log The content should be like the following: - + Stopping and starting 1 secondary storage vm(s)... Done stopping and starting secondary storage vm(s) Stopping and starting 1 console proxy vm(s)... Done stopping and starting console proxy vm(s). Stopping and starting 4 running routing vm(s)... Done restarting router(s). -21. +21. If you would like additional confirmation that the new system VM templates were correctly applied when these system VMs were rebooted, SSH into the System VM and check the version. Use one of the following techniques, depending on the hypervisor. @@ -600,21 +600,21 @@ Done restarting router(s). SSH in by using the link local IP address of the system VM. For example, in the command below, substitute your own path to the private key used to log in to the system VM and your own link local IP. Run the following commands on the XenServer or KVM host on which the system VM is present: - # ssh -i private-key-path link-local-ip -p 3922 + # ssh -i private-key-path link-local-ip -p 3922 # cat /etc/cloudstack-release The output should be like the following: - Cloudstack Release 4.0.0-incubating Mon Oct 9 15:10:04 PST 2012ESXi + Cloudstack Release 4.0.0-incubating Mon Oct 9 15:10:04 PST 2012ESXi SSH in using the private IP address of the system VM. For example, in the command below, substitute your own path to the private key used to log in to the system VM and your own private IP. Run the following commands on the Management Server: - # ssh -i private-key-path private-ip -p 3922 + # ssh -i private-key-path private-ip -p 3922 # cat /etc/cloudstack-release The output should be like the following: - Cloudstack Release 4.0.0-incubating Mon Oct 9 15:10:04 PST 201222. + Cloudstack Release 4.0.0-incubating Mon Oct 9 15:10:04 PST 201222. If needed, upgrade all Citrix XenServer hypervisor hosts in your cloud to a version supported by CloudStack 4.0.0-incubating. The supported versions are XenServer 5.6 SP2 and 6.0.2. Instructions for upgrade can be found in the CloudStack 4.0.0-incubating Installation Guide. - 23. + 23. Apply the XenServer hotfix XS602E003 (and any other needed hotfixes) to XenServer v6.0.2 hypervisor hosts. - a. + a. Disconnect the XenServer cluster from CloudStack. In the left navigation bar of the CloudStack UI, select Infrastructure. Under Clusters, click View All. Select the XenServer cluster and click Actions - Unmanage. @@ -622,29 +622,29 @@ Done restarting router(s). This may fail if there are hosts not in one of the states Up, Down, Disconnected, or Alert. You may need to fix that before unmanaging this cluster. Wait until the status of the cluster has reached Unmanaged. Use the CloudStack UI to check on the status. When the cluster is in the unmanaged state, there is no connection to the hosts in the cluster. - b. + b. To clean up the VLAN, log in to one XenServer host and run: - /opt/xensource/bin/cloud-clean-vlan.shc. + /opt/xensource/bin/cloud-clean-vlan.shc. Prepare the upgrade by running the following on one XenServer host: - /opt/xensource/bin/cloud-prepare-upgrade.sh + /opt/xensource/bin/cloud-prepare-upgrade.sh If you see a message like "can't eject CD", log in to the VM and umount the CD, then run this script again. - d. + d. Upload the hotfix to the XenServer hosts. Always start with the Xen pool master, then the slaves. Using your favorite file copy utility (e.g. WinSCP), copy the hotfixes to the host. Place them in a temporary folder such as /root or /tmp. On the Xen pool master, upload the hotfix with this command: - xe patch-upload file-name=XS602E003.xsupdate + xe patch-upload file-name=XS602E003.xsupdate Make a note of the output from this command, which is a UUID for the hotfix file. You'll need it in another step later. - Note + Note (Optional) If you are applying other hotfixes as well, you can repeat the commands in this section with the appropriate hotfix number. For example, XS602E004.xsupdate. - e. + e. Manually live migrate all VMs on this host to another host. First, get a list of the VMs on this host: - # xe vm-list + # xe vm-list Then use this command to migrate each VM. Replace the example host name and VM name with your own: - # xe vm-migrate live=true host=host-name vm=VM-nameTroubleshooting + # xe vm-migrate live=true host=host-name vm=VM-nameTroubleshooting If you see a message like "You attempted an operation on a VM which requires PV drivers to be installed but the drivers were not detected," run: /opt/xensource/bin/make_migratable.sh b6cf79c8-02ee-050b-922f-49583d9f1a14. - f. + f. Apply the hotfix. First, get the UUID of this host: # xe host-list @@ -652,9 +652,9 @@ Done restarting router(s). Then use the following command to apply the hotfix. Replace the example host UUID with the current host ID, and replace the hotfix UUID with the output from the patch-upload command you ran on this machine earlier. You can also get the hotfix UUID by running xe patch-list. xe patch-apply host-uuid=host-uuid uuid=hotfix-uuid - g. + g. Copy the following files from the CloudStack Management Server to the host. - + Copy from here... @@ -686,39 +686,39 @@ Done restarting router(s). /opt/xensource/bin/make_migratable.sh - h. + h. (Only for hotfixes XS602E005 and XS602E007) You need to apply a new Cloud Support Pack. - + Download the CSP software onto the XenServer host from one of the following links: For hotfix XS602E005: http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E005/56710/xe-phase-2/xenserver-cloud-supp.tgz For hotfix XS602E007: http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E007/57824/xe-phase-2/xenserver-cloud-supp.tgz - + Extract the file: # tar xf xenserver-cloud-supp.tgz - + Run the following script: # xe-install-supplemental-pack xenserver-cloud-supp.iso - + If the XenServer host is part of a zone that uses basic networking, disable Open vSwitch (OVS): # xe-switch-network-backend bridge - i. + i. Reboot this XenServer host. - j. + j. Run the following: /opt/xensource/bin/setupxenserver.sh - Note + Note If the message "mv: cannot stat `/etc/cron.daily/logrotate': No such file or directory" appears, you can safely ignore it. - k. + k. Run the following: for pbd in `xe pbd-list currently-attached=false| grep ^uuid | awk '{print $NF}'`; do xe pbd-plug uuid=$pbd ; - l. + l. On each slave host in the Xen pool, repeat these steps, starting from "manually live migrate VMs." Chapter 3.Chapter 3. Version 4.0.0-incubatingVersion 4.0.0-incubatingWhat’s New in 4.0.0-incubating3.1. What’s New in 4.0.0-incubating Apache CloudStack 4.0.0-incubating includes the following new features: @@ -730,9 +730,9 @@ Done restarting router(s). A Site-to-Site VPN connection helps you establish a secure connection from an enterprise datacenter to the cloud infrastructure. This allows users to access the guest VMs by establishing a VPN connection to the virtual router of the account from a device in the datacenter of the enterprise. Having this facility eliminates the need to establish VPN connections to individual VMs. The supported endpoints on the remote datacenters are: - + Cisco ISR with IOS 12.4 or later - + Juniper J-Series routers with JunOS 9.5 or later Local Storage Support for Data Volumes3.1.3. Local Storage Support for Data Volumes You can now create data volumes on local storage. The data volume is placed on the same XenServer host as the VM instance that is attached to the data volume. These local data volumes can be attached to virtual machines, detached, re-attached, and deleted just as with the other types of data volume. In earlier releases of CloudStack, only the root disk could be placed in local storage. @@ -754,48 +754,48 @@ Done restarting router(s). You can work with tags through the UI or through the new API commands createTags, deleteTags, and listTags. You can define multiple tags for each resource. There is no limit on the number of tags you can define. Each tag can be up to 255 characters long. Users can define tags on the resources they own, and administrators can define tags on any resources in the cloud. A new optional input parameter, "tags," has been added to many of the list* API commands. The following example shows how to use this new parameter to find all the volumes having tag region=canada OR tag city=Toronto: - command=listVolumes + command=listVolumes &listAll=true &tags[0].key=region &tags[0].value=canada &tags[1].key=city &tags[1].value=Toronto The following API commands have the new "tags" input parameter: - + listVirtualMachines - + listVolumes - + listSnapshots - + listNetworks - + listTemplates - + listIsos - + listFirewallRules - + listPortForwardingRules - + listPublicIpAddresses - + listSecurityGroups - + listLoadBalancerRules - + listProjects - + listVPCs - + listNetworkACLs - + listStaticRoutes AWS API Changes for Tags3.1.5. AWS API Changes for Tags Some changes have been made to the Amazon Web Services API compatibility support in order to accommodate the new tagging feature. New APIs: - + New API @@ -834,7 +834,7 @@ Done restarting router(s). Changed APIs: - + Changed API @@ -893,21 +893,21 @@ Done restarting router(s). This release supports creating VMs without starting them on the backend. You can determine whether the VM needs to be started as part of the VM deployment. A VM can be deployed in two ways: create and start a VM (the default method); create a VM and leave it in the stopped state. A new request parameter, startVM, is introduced in the deployVm API to support the stopped VM feature. The possible values are: - + true - The VM starts as a part of the VM deployment - + false - The VM is left in stopped state at the end of the VM deployment Uploading an Existing Volume to a Virtual Machine3.1.8. Uploading an Existing Volume to a Virtual Machine Existing data can now be made accessible to a virtual machine. This is called uploading a volume to the VM. For example, this is useful to upload data from a local file system and attach it to a VM. Root administrators, domain administrators, and end users can all upload existing volumes to VMs. The upload is performed by using HTTP. The uploaded volume is placed in the zone's secondary storage. This functionality is supported for the following hypervisors: - + Hypervisor : Disk Image Format - + XenServer : VHD - + VMware : OVA - + KVM : QCOW2 Dedicated High-Availability Hosts3.1.9. Dedicated High-Availability Hosts One or more hosts can now be designated for use only by high-availability (HA) enabled VMs that are restarted due to a host failure. Setting up a pool of such dedicated HA hosts as the recovery destination for all HA-enabled VMs make it easier to determine which VMs are restarted as part of the high-availability function. You can designate a host as a dedicated-HA restart node only if the Dedicated HA Hosts feature is enabled by setting the appropriate global configuration parameter. @@ -931,7 +931,7 @@ Done restarting router(s). Create a disk offering for RBD so that you can ensure that StoragePoolAllocator chooses the RBD pool to deploy instances. Issues Fixed in 4.0.0-incubating3.2. Issues Fixed in 4.0.0-incubating Many bugs include a defect number that reflects the bug number that was held in the bug tracker run by Citrix (bugs.cloudstack.org). The Apache CloudStack project now uses Jira11 https://issues.apache.org/jira/browse/CLOUDSTACK to manage its bugs, so some of the bugs that are referenced here may not be available to view. However, we are still including them for completeness. - + Defect @@ -1974,7 +1974,7 @@ Done restarting router(s). Version 3.0.2 now accepts the valid public key. - Known Issues in 4.0.0-incubating3.3. Known Issues in 4.0.0-incubating + Known Issues in 4.0.0-incubating3.3. Known Issues in 4.0.0-incubating Issue ID @@ -2016,9 +2016,9 @@ Done restarting router(s). Deleting a project fails when executed by the regular user. This works as expected for root/domain admin. To workaround, perform either of the following: - + Use the account cleanup thread which will eventually complete the project deletion. - + Execute the call as the root/domain admin on behalf of the regular user. @@ -2381,37 +2381,37 @@ Done restarting router(s). To workaround this issue, follow the instructions given below: - 1. + 1. Revert to your 2.2.14 setup. - 2. + 2. Stop all the VMs with the isolated virtual networks in your cloud setup. - 3. + 3. Run following query to find if any networks still have the NICs allocated: - a. + a. Check if any virtual guest networks have the NICs allocated: - #SELECT DISTINCT op.id from `cloud`.`op_networks` op JOIN `cloud`.`networks` n on op.id=n.id WHERE nics_count != 0 AND guest_type = 'Virtual';b. + #SELECT DISTINCT op.id from `cloud`.`op_networks` op JOIN `cloud`.`networks` n on op.id=n.id WHERE nics_count != 0 AND guest_type = 'Virtual';b. If this returns any network IDs, then ensure the following: - i. + i. All the VMs are stopped. - ii. + ii. No new VM is started. - iii. + iii. Shutdown the Management Server. - c. + c. Remove the NICs count for the virtual network IDs returned in step (a), and set the NIC count to 0: - UPDATE `cloud`.`op_networks` SET nics_count = 0 WHERE id = enter id of virtual networkd. + UPDATE `cloud`.`op_networks` SET nics_count = 0 WHERE id = enter id of virtual networkd. Restart the Management Server, and wait for all the networks to shut down. - Note + Note Networks shutdown is determined by the network.gc.interval and network.gc.wait parameters. - 4. + 4. Ensure that all the networks are shut down and all the guest VNETs are free. - 5. + 5. Run the upgrade script. This allocates all your guest VNET ranges to the first physical network. - 6. + 6. By using the updatePhysicalNetwork API, reconfigure the VNET ranges for each physical network as desired. - 7. + 7. Start all the VMs. @@ -2428,7 +2428,7 @@ Done restarting router(s). To work with the LDAP user, the MD5 hash should be disabled in the login process by commenting the following variable in sharedFunctions.js file available at /usr/share/cloud/management/webapps/client/scripts, and restart the cloud-management service. -var md5HashedLogin = false; +var md5HashedLogin = false; However, if md5HashedLogin is set to false, the end user can login with the LDAP credentials but not with the CloudStack user credentials. @@ -2505,98 +2505,98 @@ Done restarting router(s). The minimum limit is not honored when there is not enough capacity to deploy all the VMs and the ec2-run-instances command with the -n >n1 -n2> option is used to deploy multiple VMs. - Chapter 4.Chapter 4. API Changes from 3.0.2 to 4.0.0-incubatingAPI Changes from 3.0.2 to 4.0.0-incubatingNew API Commands in 4.0.0-incubating4.1. New API Commands in 4.0.0-incubating + Chapter 4.Chapter 4. API Changes from 3.0.2 to 4.0.0-incubatingAPI Changes from 3.0.2 to 4.0.0-incubatingNew API Commands in 4.0.0-incubating4.1. New API Commands in 4.0.0-incubating createCounter (Adds metric counter) - + deleteCounter (Deletes a counter) - + listCounters (List the counters) - + createCondition (Creates a condition) - + deleteCondition (Removes a condition) - + listConditions (List Conditions for the specific user) - + createTags. Add tags to one or more resources. Example: -command=createTags +command=createTags &resourceIds=1,10,12 &resourceType=userVm &tags[0].key=region &tags[0].value=canada &tags[1].key=city &tags[1].value=Toronto - + deleteTags. Remove tags from one or more resources. Example: -command=deleteTags +command=deleteTags &resourceIds=1,12 &resourceType=Snapshot &tags[0].key=city - + listTags (Show currently defined resource tags) - + createVPC (Creates a VPC) - + listVPCs (Lists VPCs) - + deleteVPC (Deletes a VPC) - + updateVPC (Updates a VPC) - + restartVPC (Restarts a VPC) - + createVPCOffering (Creates VPC offering) - + updateVPCOffering (Updates VPC offering) - + deleteVPCOffering (Deletes VPC offering) - + listVPCOfferings (Lists VPC offerings) - + createPrivateGateway (Creates a private gateway) - + listPrivateGateways (List private gateways) - + deletePrivateGateway (Deletes a Private gateway) - + createNetworkACL (Creates a ACL rule the given network (the network has to belong to VPC)) - + deleteNetworkACL (Deletes a Network ACL) - + listNetworkACLs (Lists all network ACLs) - + createStaticRoute (Creates a static route) - + deleteStaticRoute (Deletes a static route) - + listStaticRoutes (Lists all static routes) - + createVpnCustomerGateway (Creates site to site vpn customer gateway) - + createVpnGateway (Creates site to site vpn local gateway) - + createVpnConnection (Create site to site vpn connection) - + deleteVpnCustomerGateway (Delete site to site vpn customer gateway) - + deleteVpnGateway (Delete site to site vpn gateway) - + deleteVpnConnection (Delete site to site vpn connection) - + updateVpnCustomerGateway (Update site to site vpn customer gateway) - + resetVpnConnection (Reset site to site vpn connection) - + listVpnCustomerGateways (Lists site to site vpn customer gateways) - + listVpnGateways (Lists site 2 site vpn gateways) - + listVpnConnections (Lists site to site vpn connection gateways) - + markDefaultZoneForAccount (Marks a default zone for the current account) - + uploadVolume (Uploads a data disk) - Changed API Commands in 4.0.0-incubating4.2. Changed API Commands in 4.0.0-incubating + Changed API Commands in 4.0.0-incubating4.2. Changed API Commands in 4.0.0-incubating API Commands @@ -2682,7 +2682,7 @@ Done restarting router(s). New response parameter: tags(*) - Note + Note Many other commands also have the new tags(*) parameter in addition to other changes; those commands are listed separately. @@ -3052,11 +3052,11 @@ Done restarting router(s). The following request parameters are added: - + vsmipaddress (optional) - + vsmpassword (optional) - + vsmusername (optional) diff --git a/docs/tmp/en-US/xml/management-server-install-db-external.xml b/docs/tmp/en-US/xml/management-server-install-db-external.xml index 31b8debea55..dab75868737 100644 --- a/docs/tmp/en-US/xml/management-server-install-db-external.xml +++ b/docs/tmp/en-US/xml/management-server-install-db-external.xml @@ -53,7 +53,7 @@ - On Ubuntu, you can also create a file /etc/mysql/conf.d/cloudstack.cnf and add these directives there. Don't forget to add [mysqld] on the first line of the file. + On Ubuntu, you can also create /etc/mysql/conf.d/cloudstack.cnf file and add these directives there. Don't forget to add [mysqld] on the first line of the file. @@ -136,6 +136,7 @@ bind-address = 0.0.0.0 Return to the root shell on your first Management Server. + @@ -146,35 +147,40 @@ bind-address = 0.0.0.0 In dbpassword, specify the password to be assigned to the cloud user. You can choose to provide no password. + In deploy-as, specify the username and password of the user deploying the database. In the following command, it is assumed the root user is deploying the database and creating the cloud user. + - (Optional) For encryption_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. See About Password and Key Encryption. + (Optional) For encryption_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. See . + (Optional) For management_server_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; properties file. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. + - (Optional) For database_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; database. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. + (Optional) For database_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; database. Default: password. It is highly recommended that you replace this with a more secure value. See . + cloud-setup-databases cloud:<dbpassword>@<ip address mysql server> \ - --deploy-as=root:<password> \ - -e <encryption_type> \ - -m <management_server_key> \ - -k <database_key> +--deploy-as=root:<password> \ +-e <encryption_type> \ +-m <management_server_key> \ +-k <database_key> When this script is finished, you should see a message like “Successfully initialized the database.” diff --git a/docs/tmp/en-US/xml/management-server-install-db-local.xml b/docs/tmp/en-US/xml/management-server-install-db-local.xml index 4dae0690e7c..b5d520dd73d 100644 --- a/docs/tmp/en-US/xml/management-server-install-db-local.xml +++ b/docs/tmp/en-US/xml/management-server-install-db-local.xml @@ -101,35 +101,40 @@ binlog-format = 'ROW' In dbpassword, specify the password to be assigned to the "cloud" user. You can choose to provide no password although that is not recommended. + In deploy-as, specify the username and password of the user deploying the database. In the following command, it is assumed the root user is deploying the database and creating the "cloud" user. + - (Optional) For encryption_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. See About Password and Key Encryption. + (Optional) For encryption_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. See . + - (Optional) For management_server_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; properties file. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. + (Optional) For management_server_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; properties file. Default: password. It is highly recommended that you replace this with a more secure value. See . + - (Optional) For database_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; database. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. + (Optional) For database_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; database. Default: password. It is highly recommended that you replace this with a more secure value. See . + cloud-setup-databases cloud:<dbpassword>@localhost \ - --deploy-as=root:<password> \ - -e <encryption_type> \ - -m <management_server_key> \ - -k <database_key> +--deploy-as=root:<password> \ +-e <encryption_type> \ +-m <management_server_key> \ +-k <database_key> When this script is finished, you should see a message like “Successfully initialized the database.” @@ -145,6 +150,7 @@ binlog-format = 'ROW' This type of single-machine setup is recommended only for a trial installation. + diff --git a/docs/tmp/en-US/xml/management-server-install-flow.xml b/docs/tmp/en-US/xml/management-server-install-flow.xml index dc46997e3cc..8f24f54d40c 100644 --- a/docs/tmp/en-US/xml/management-server-install-flow.xml +++ b/docs/tmp/en-US/xml/management-server-install-flow.xml @@ -25,6 +25,7 @@ + diff --git a/docs/tmp/en-US/xml/prepare-system-vm-template.xml b/docs/tmp/en-US/xml/prepare-system-vm-template.xml index 7e5e0899c2c..ea10f8f0780 100644 --- a/docs/tmp/en-US/xml/prepare-system-vm-template.xml +++ b/docs/tmp/en-US/xml/prepare-system-vm-template.xml @@ -22,7 +22,7 @@ under the License. --> Prepare the System VM Template - Secondary storage must be seeded with a template that is used for &PRODUCT; system VMs. + Secondary storage must be seeded with a template that is used for &PRODUCT; system VMs. Citrix provides you with the necessary binary package of the system VM. @@ -39,7 +39,7 @@ If your secondary storage mount point is not named /mnt/secondary, substitute your own mount point name. - If you set the &PRODUCT; database encryption type to "web" when you set up the database, you must now add the parameter -s <management-server-secret-key>. See About Password and Key Encryption. + If you set the &PRODUCT; database encryption type to "web" when you set up the database, you must now add the parameter -s <management-server-secret-key>. See . This process will require approximately 5 GB of free space on the local file system and up to 30 minutes each time it runs. @@ -75,8 +75,14 @@ - If you are using a separate NFS server, perform this step. If you are using the Management Server as the NFS server, you MUST NOT perform this step. + If you are using a separate NFS server, perform this step. + + + Do not perform this step if you are using the Management Server as the NFS server. + + + When the script has finished, unmount secondary storage and remove the created directory. diff --git a/docs/tmp/en-US/xml_tmp/management-server-install-db-external.xml b/docs/tmp/en-US/xml_tmp/management-server-install-db-external.xml index a749dc76c0d..3bba45f3ee1 100644 --- a/docs/tmp/en-US/xml_tmp/management-server-install-db-external.xml +++ b/docs/tmp/en-US/xml_tmp/management-server-install-db-external.xml @@ -21,95 +21,120 @@ specific language governing permissions and limitations under the License. --> -
      - Install the Database on a Separate Node - This section describes how to install MySQL on a standalone machine, separate from the Management Server. - This technique is intended for a deployment that includes several Management Server nodes. - If you have a single-node Management Server deployment, you will typically use the same node for MySQL. - See . - - - The management server doesn't require a specific distribution for the MySQL node. - You can use a distribution or Operating System of your choice. - Using the same distribution as the management server is recommended, but not required. - See . - - - - - Install MySQL from the package repository from your distribution: - On RHEL or CentOS: - yum install mysql-server - On Ubuntu: - apt-get install mysql-server - - Edit the MySQL configuration (/etc/my.cnf or /etc/mysql/my.cnf, depending on your OS) - and insert the following lines in the [mysqld] section. You can put these lines below the datadir - line. The max_connections parameter should be set to 350 multiplied by the number of Management - Servers you are deploying. This example assumes two Management Servers. - - On Ubuntu, you can also create a file /etc/mysql/conf.d/cloudstack.cnf and add - these directives there. Don't forget to add [mysqld] on the first line of the - file. - - innodb_rollback_on_timeout=1 + Install the Database on a Separate Node + This section describes how to install MySQL on a standalone machine, separate from the + Management Server. This technique is intended for a deployment that includes several Management + Server nodes. If you have a single-node Management Server deployment, you will typically use the + same node for MySQL. See . + + The management server doesn't require a specific distribution for the MySQL node. You can + use a distribution or Operating System of your choice. Using the same distribution as the + management server is recommended, but not required. See . + + + + Install MySQL from the package repository from your distribution: + On RHEL or CentOS: + yum install mysql-server + On Ubuntu: + apt-get install mysql-server + + + Edit the MySQL configuration (/etc/my.cnf or /etc/mysql/my.cnf, depending on your OS) + and insert the following lines in the [mysqld] section. You can put these lines below the + datadir line. The max_connections parameter should be set to 350 multiplied by the number of + Management Servers you are deploying. This example assumes two Management Servers. + + On Ubuntu, you can also create /etc/mysql/conf.d/cloudstack.cnf file and add these + directives there. Don't forget to add [mysqld] on the first line of the file. + + innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=700 log-bin=mysql-bin binlog-format = 'ROW' -bind-address = 0.0.0.0 +bind-address = 0.0.0.0 + + + Start or restart MySQL to put the new configuration into effect. + On RHEL/CentOS, MySQL doesn't automatically start after installation. Start it + manually. + service mysqld start + On Ubuntu, restart MySQL. + service mysqld restart + + + (CentOS and RHEL only; not required on Ubuntu) + + On RHEL and CentOS, MySQL does not set a root password by default. It is very strongly + recommended that you set a root password as a security precaution. + + Run the following command to secure your installation. You can answer "Y" to all + questions except "Disallow root login remotely?". Remote root login is required to set up + the databases. + mysql_secure_installation + + + If a firewall is present on the system, open TCP port 3306 so external MySQL connections + can be established. + On Ubuntu, UFW is the default firewall. Open the port with this command: + ufw allow mysql + On RHEL/CentOS: + + + Edit the /etc/sysconfig/iptables file and add the following line at the beginning of + the INPUT chain. + -A INPUT -p tcp --dport 3306 -j ACCEPT - Start or restart MySQL to put the new configuration into effect. - On RHEL/CentOS, - MySQL doesn't automatically start after installation. Start it manually. - service mysqld start - On Ubuntu, restart MySQL. - service mysqld restart + Now reload the iptables rules. + service iptables restart + + + + + Return to the root shell on your first Management Server. + + + Set up the database. The following command creates the cloud user on the + database. + + + In dbpassword, specify the password to be assigned to the cloud user. You can choose + to provide no password. - (CentOS and RHEL only; not required on Ubuntu) - - On RHEL and CentOS, MySQL does not set a root password by default. It is very - strongly recommended that you set a root password as a security precaution. - - Run the following command to secure your installation. You can answer "Y" to all - questions except "Disallow root login remotely?". Remote root login is required to - set up the databases. - mysql_secure_installation + In deploy-as, specify the username and password of the user deploying the database. + In the following command, it is assumed the root user is deploying the database and + creating the cloud user. - If a firewall is present on the system, open TCP port 3306 so external MySQL connections can be established. - On Ubuntu, UFW is the default firewall. Open the port with this command: - ufw allow mysql - On RHEL/CentOS: - - - Edit the /etc/sysconfig/iptables file and add the following line at the beginning of the INPUT chain. - -A INPUT -p tcp --dport 3306 -j ACCEPT - - - Now reload the iptables rules. - service iptables restart - - - - Return to the root shell on your first Management Server. - Set up the database. The following command creates the cloud user on the database. - - In dbpassword, specify the password to be assigned to the cloud user. You can choose to provide no password. - In deploy-as, specify the username and password of the user deploying the database. In the following command, it is assumed the root user is deploying the database and creating the cloud user. - (Optional) For encryption_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. See About Password and Key Encryption. - (Optional) For management_server_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; properties file. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. - (Optional) For database_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; database. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. - - cloud-setup-databases cloud:<dbpassword>@<ip address mysql server> \ - --deploy-as=root:<password> \ - -e <encryption_type> \ - -m <management_server_key> \ - -k <database_key> - When this script is finished, you should see a message like “Successfully initialized the database.” + (Optional) For encryption_type, use file or web to indicate the technique used to + pass in the database encryption password. Default: file. See . - + + (Optional) For management_server_key, substitute the default key that is used to + encrypt confidential parameters in the &PRODUCT; properties file. Default: password. It + is highly recommended that you replace this with a more secure value. See About Password + and Key Encryption. + + + (Optional) For database_key, substitute the default key that is used to encrypt + confidential parameters in the &PRODUCT; database. Default: password. It is highly + recommended that you replace this with a more secure value. See . + + + cloud-setup-databases cloud:<dbpassword>@<ip address mysql server> \ +--deploy-as=root:<password> \ +-e <encryption_type> \ +-m <management_server_key> \ +-k <database_key> + When this script is finished, you should see a message like “Successfully initialized + the database.” + +
      diff --git a/docs/tmp/en-US/xml_tmp/management-server-install-db-local.xml b/docs/tmp/en-US/xml_tmp/management-server-install-db-local.xml index 9880c54571b..3e09c554df0 100644 --- a/docs/tmp/en-US/xml_tmp/management-server-install-db-local.xml +++ b/docs/tmp/en-US/xml_tmp/management-server-install-db-local.xml @@ -1,5 +1,5 @@ - %BOOK_ENTITIES; ]> @@ -21,69 +21,105 @@ specific language governing permissions and limitations under the License. --> -
      - Install the Database on the Management Server Node - This section describes how to install MySQL on the same machine with the Management Server. This technique is intended for a simple deployment that has a single Management Server node. If you have a multi-node Management Server deployment, you will typically use a separate node for MySQL. See . - - - Install MySQL from the package repository from your distribution: - On RHEL or CentOS: - yum install mysql-server - On Ubuntu: - apt-get install mysql-server - - - Edit the MySQL configuration (/etc/my.cnf or /etc/mysql/my.cnf, depending on your OS) and insert the following lines in the [mysqld] section. You can put these lines below the datadir line. The max_connections parameter should be set to 350 multiplied by the number of Management Servers you are deploying. This example assumes one Management Server. - - On Ubuntu, you can also create a file /etc/mysql/conf.d/cloudstack.cnf and add these directives there. Don't forget to add [mysqld] on the first line of the file. - - innodb_rollback_on_timeout=1 + Install the Database on the Management Server Node + This section describes how to install MySQL on the same machine with the Management Server. + This technique is intended for a simple deployment that has a single Management Server node. If + you have a multi-node Management Server deployment, you will typically use a separate node for + MySQL. See . + + + Install MySQL from the package repository from your distribution: + On RHEL or CentOS: + yum install mysql-server + On Ubuntu: + apt-get install mysql-server + + + Edit the MySQL configuration (/etc/my.cnf or /etc/mysql/my.cnf, depending on your OS) + and insert the following lines in the [mysqld] section. You can put these lines below the + datadir line. The max_connections parameter should be set to 350 multiplied by the number of + Management Servers you are deploying. This example assumes one Management Server. + + On Ubuntu, you can also create a file /etc/mysql/conf.d/cloudstack.cnf and add these + directives there. Don't forget to add [mysqld] on the first line of the file. + + innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=350 log-bin=mysql-bin binlog-format = 'ROW' + + + Start or restart MySQL to put the new configuration into effect. + On RHEL/CentOS, MySQL doesn't automatically start after installation. Start it + manually. + service mysqld start + On Ubuntu, restart MySQL. + service mysqld restart + + + (CentOS and RHEL only; not required on Ubuntu) + + On RHEL and CentOS, MySQL does not set a root password by default. It is very strongly + recommended that you set a root password as a security precaution. + + Run the following command to secure your installation. You can answer "Y" to all + questions. + mysql_secure_installation + + + Set up the database. The following command creates the "cloud" user on the + database. + + + In dbpassword, specify the password to be assigned to the "cloud" user. You can + choose to provide no password although that is not recommended. - Start or restart MySQL to put the new configuration into effect. - On RHEL/CentOS, - MySQL doesn't automatically start after installation. Start it manually. - service mysqld start - On Ubuntu, restart MySQL. - service mysqld restart + In deploy-as, specify the username and password of the user deploying the database. + In the following command, it is assumed the root user is deploying the database and + creating the "cloud" user. - (CentOS and RHEL only; not required on Ubuntu) - - On RHEL and CentOS, MySQL does not set a root password by default. It is very - strongly recommended that you set a root password as a security precaution. - - Run the following command to secure your installation. You can answer "Y" to all - questions. - mysql_secure_installation + (Optional) For encryption_type, use file or web to indicate the technique used to + pass in the database encryption password. Default: file. See . - Set up the database. The following command creates the "cloud" user on the database. - - In dbpassword, specify the password to be assigned to the "cloud" user. You can choose to provide no password although that is not recommended. - In deploy-as, specify the username and password of the user deploying the database. In the following command, it is assumed the root user is deploying the database and creating the "cloud" user. - (Optional) For encryption_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. See About Password and Key Encryption. - (Optional) For management_server_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; properties file. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. - (Optional) For database_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; database. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. - - cloud-setup-databases cloud:<dbpassword>@localhost \ - --deploy-as=root:<password> \ - -e <encryption_type> \ - -m <management_server_key> \ - -k <database_key> - When this script is finished, you should see a message like “Successfully initialized the database.” + + (Optional) For management_server_key, substitute the default key that is used to + encrypt confidential parameters in the &PRODUCT; properties file. Default: password. It + is highly recommended that you replace this with a more secure value. See . - If you are running the KVM hypervisor on the same machine with the Management Server, edit /etc/sudoers and add the following line: - Defaults:cloud !requiretty - This type of single-machine setup is recommended only for a trial installation. + + (Optional) For database_key, substitute the default key that is used to encrypt + confidential parameters in the &PRODUCT; database. Default: password. It is highly + recommended that you replace this with a more secure value. See . - Now that the database is set up, you can finish configuring the OS for the Management Server. This command will set up iptables, sudoers, and start the Management Server. - # cloud-setup-management - You should see the message “&PRODUCT; Management Server setup is done.” - - + + cloud-setup-databases cloud:<dbpassword>@localhost \ +--deploy-as=root:<password> \ +-e <encryption_type> \ +-m <management_server_key> \ +-k <database_key> + When this script is finished, you should see a message like “Successfully initialized + the database.” + + + If you are running the KVM hypervisor on the same machine with the Management Server, + edit /etc/sudoers and add the following line: + Defaults:cloud !requiretty + + This type of single-machine setup is recommended only for a trial installation. + + + + Now that the database is set up, you can finish configuring the OS for the Management + Server. This command will set up iptables, sudoers, and start the Management Server. + # cloud-setup-management + You should see the message “&PRODUCT; Management Server setup is done.” + +
      diff --git a/docs/tmp/en-US/xml_tmp/management-server-install-flow.xml b/docs/tmp/en-US/xml_tmp/management-server-install-flow.xml index 33bcac9c85b..cf14857364f 100644 --- a/docs/tmp/en-US/xml_tmp/management-server-install-flow.xml +++ b/docs/tmp/en-US/xml_tmp/management-server-install-flow.xml @@ -28,6 +28,7 @@ + diff --git a/docs/tmp/en-US/xml_tmp/prepare-system-vm-template.xml b/docs/tmp/en-US/xml_tmp/prepare-system-vm-template.xml index 5ed78f7d5a3..22674d47952 100644 --- a/docs/tmp/en-US/xml_tmp/prepare-system-vm-template.xml +++ b/docs/tmp/en-US/xml_tmp/prepare-system-vm-template.xml @@ -23,8 +23,8 @@ -->
      Prepare the System VM Template - Secondary storage must be seeded with a template that is used for &PRODUCT; system - VMs. + Secondary storage must be seeded with a template that is used for &PRODUCT; system VMs. + Citrix provides you with the necessary binary package of the system VM. When copying and pasting a command, be sure the command has pasted as a single line before executing. Some document viewers may introduce unwanted line breaks in copied text. @@ -37,8 +37,8 @@ If your secondary storage mount point is not named /mnt/secondary, substitute your own mount point name. If you set the &PRODUCT; database encryption type to "web" when you set up the database, - you must now add the parameter -s <management-server-secret-key>. See About Password - and Key Encryption. + you must now add the parameter -s <management-server-secret-key>. See . This process will require approximately 5 GB of free space on the local file system and up to 30 minutes each time it runs. @@ -57,8 +57,11 @@ - If you are using a separate NFS server, perform this step. If you are using the - Management Server as the NFS server, you MUST NOT perform this step. + If you are using a separate NFS server, perform this step. + + Do not perform this step if you are using the Management Server as the NFS + server. + When the script has finished, unmount secondary storage and remove the created directory. # umount /mnt/secondary