Fixed formatting by Will stevens
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/commit/68c20df4 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/tree/68c20df4 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/diff/68c20df4 Branch: refs/heads/4.4 Commit: 68c20df481a0bc13e1794a4a897686977139a17c Parents: 72a3a7c Author: Will Stevens <wstev...@cloudops.com> Authored: Tue May 20 12:33:17 2014 -0400 Committer: Sebastien Goasguen <run...@gmail.com> Committed: Wed May 21 08:25:06 2014 +0200 ---------------------------------------------------------------------- source/accounts.rst | 76 +- source/administration.rst | 18 +- source/api.rst | 34 +- source/events.rst | 189 ++-- source/hosts.rst | 245 ++--- source/index.rst | 34 + source/management.rst | 381 ++++---- source/networking.rst | 232 ++--- .../networking/global_server_load_balancing.rst | 20 +- source/networking/portable_ips.rst | 4 +- source/networking/security_groups.rst | 3 +- source/projects.rst | 261 ++---- source/reliability.rst | 65 +- source/service_offerings.rst | 311 ++----- source/storage.rst | 326 +++---- source/systemvm.rst | 381 +++----- source/templates.rst | 908 +++++++------------ source/troubleshooting.rst | 231 ++--- source/tuning.rst | 39 +- source/ui.rst | 76 +- source/usage.rst | 734 +++++---------- source/virtual_machines.rst | 781 ++++++---------- 22 files changed, 1942 insertions(+), 3407 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/accounts.rst ---------------------------------------------------------------------- diff --git a/source/accounts.rst b/source/accounts.rst index 5367743..e5d4b6d 100644 --- a/source/accounts.rst +++ b/source/accounts.rst @@ -27,6 +27,7 @@ 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 ~~~~~~~ @@ -40,6 +41,7 @@ For each account created, the Cloud installation creates three different types of user accounts: root administrator, domain administrator, and user. + Users ~~~~~ @@ -59,6 +61,7 @@ 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 ~~~~~~~~~~~~~~~~~~~~~ @@ -66,6 +69,7 @@ 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 ~~~~~~~~~~~~~~~~~~ @@ -73,6 +77,7 @@ Root administrators have complete access to the system, including managing templates, service offerings, customer care administrators, and domains + Resource Ownership ~~~~~~~~~~~~~~~~~~ @@ -86,6 +91,7 @@ account by using the assignVirtualMachine API. A domain or sub-domain administrator can do the same for VMs within the domain from one account to any other account in the domain or any of its sub-domains. + Dedicating Resources to Accounts and Domains -------------------------------------------- @@ -99,26 +105,21 @@ that domain. There are several types of dedication available: -- - - Explicit dedication. A zone, pod, cluster, or host is dedicated to an +- Explicit dedication. A zone, pod, cluster, or host is dedicated to an account or domain by the root administrator during initial deployment and configuration. -- - - Strict implicit dedication. A host will not be shared across multiple +- Strict implicit dedication. A host will not be shared across multiple accounts. For example, strict implicit dedication is useful for deployment of certain types of applications, such as desktops, where no host can be shared between different accounts without violating the desktop software's terms of license. -- - - Preferred implicit dedication. The VM will be deployed in dedicated +- Preferred implicit dedication. The VM will be deployed in dedicated infrastructure if possible. Otherwise, the VM can be deployed in shared infrastructure. + How to Dedicate a Zone, Cluster, Pod, or Host to an Account or Domain ---------------------------------------------------------------------- @@ -138,6 +139,7 @@ permissible to allow some use of shared resources when dedicated resources are not available. Whenever a user creates a VM based on this service offering, it is allocated on one of the dedicated hosts. + How to Use Dedicated Hosts ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -148,6 +150,7 @@ end user can choose to place it on dedicated infrastructure. This operation will succeed only if some infrastructure has already been assigned as dedicated to the user's account or domain. + Behavior of Dedicated Hosts, Clusters, Pods, and Zones ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -178,6 +181,7 @@ VMs of a specific account (the default system account). However, a host with system VMs or virtual routers can be used for preferred implicit dedication. + Using an LDAP Server for User Authentication -------------------------------------------- @@ -195,22 +199,15 @@ 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 +- 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 user DN credentials, which give CloudStack permission to search on the LDAP server -- +- SSL keystore and password, if SSL is used - SSL keystore and password, if SSL is used Example LDAP Configuration Commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -224,25 +221,25 @@ LDAP server .. code:: bash - 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: .. code:: bash - - http://127.0.0.1:8080/client/api?command=ldapConfig - &hostname=127.0.0.1 - &searchbase=ou=testing,o=project - &queryfilter=(&(%uid=%u)) - &binddn=cn=John+Singh,ou=testing,o=project - &bindpass=secret - &port=10389 - &ssl=true - &truststore=C:/company/info/trusted.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=testing,o=project + &queryfilter=(&(%uid=%u)) + &binddn=cn=John+Singh,ou=testing,o=project + &bindpass=secret + &port=10389 + &ssl=true + &truststore=C:/company/info/trusted.ks + &truststorepass=secret + &response=json + &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 @@ -250,11 +247,12 @@ matched up based on email address. .. code:: bash - 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 Base ~~~~~~~~~~~ @@ -275,6 +273,7 @@ ApacheDS OU=testing, O=project Active Directory OU=testing, DC=company ================ ======================= + Query Filter ~~~~~~~~~~~~ @@ -300,19 +299,20 @@ If the CloudStack user name is the same as the LDAP user ID: .. code:: bash - (uid=%u) + (uid=%u) If the CloudStack user name is the LDAP display name: .. code:: bash - (displayName=%u) + (displayName=%u) To find a user by email address: .. code:: bash - (mail=%e) + (mail=%e) + Search User Bind DN ~~~~~~~~~~~~~~~~~~~ http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/administration.rst ---------------------------------------------------------------------- diff --git a/source/administration.rst b/source/administration.rst index 7c81173..4baa17f 100644 --- a/source/administration.rst +++ b/source/administration.rst @@ -14,7 +14,6 @@ under the License. - User Services ============= @@ -30,6 +29,7 @@ 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 Templates ------------------------------------------------------------------- @@ -37,28 +37,20 @@ 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 +- 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 +- Disk Offerings, defined by the CloudStack administrator, provide a choice of disk size and IOPS (Quality of Service) for primary data storage. See Creating a New Disk Offering. -- - - Network Offerings, defined by the CloudStack administrator, describe +- 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 +- 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. http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/api.rst ---------------------------------------------------------------------- diff --git a/source/api.rst b/source/api.rst index e8875fc..654c063 100644 --- a/source/api.rst +++ b/source/api.rst @@ -31,6 +31,7 @@ The API has a REST-like query basis and returns results in XML or JSON. See `the Developerâs Guide <https://cwiki.apache.org/confluence/display/CLOUDSTACK/Development+101>`_ and `the API Reference <http://cloudstack.apache.org/docs/api/>`_. + Provisioning and Authentication API ----------------------------------- @@ -44,6 +45,7 @@ authentication is done locally. However, external authentication is possible as well. For example, see Using an LDAP Server for User Authentication. + User Data and Meta Data ----------------------- @@ -59,47 +61,33 @@ the user data: .. code:: bash - # cat /var/lib/dhclient/dhclient-eth0.leases | grep dhcp-server-identifier | tail -1 + # cat /var/lib/dhclient/dhclient-eth0.leases | grep dhcp-server-identifier | tail -1 #. Access user data by running the following command using the result of the above command .. code:: bash - # 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 +- service-offering. A description of the VMs service offering -- +- availability-zone. The Zone name - local-ipv4. The guest IP of the VM +- local-ipv4. The guest IP of the VM -- +- local-hostname. The hostname of the VM - local-hostname. The hostname of the VM - -- - - public-ipv4. The first public IP for the router. (E.g. the first IP +- 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 - -- +- public-hostname. This is the same as public-ipv4 - instance-id. The instance name of the VM +- instance-id. The instance name of the VM http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/events.rst ---------------------------------------------------------------------- diff --git a/source/events.rst b/source/events.rst index d18d66a..cbba93b 100644 --- a/source/events.rst +++ b/source/events.rst @@ -25,6 +25,7 @@ and make the right business decision. In CloudStack an event could be a state change of virtual or physical resources, an action performed by an user (action events), or policy based events (alerts). + Event Logs ---------- @@ -39,6 +40,7 @@ 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.. + Notification ------------ @@ -64,32 +66,28 @@ machine on the event bus. All the CloudStack events (alerts, action events, usage events) and the additional category of resource state change events, are published on to the events bus. + Use Cases ~~~~~~~~~ The following are some of the use cases: -- - - Usage or Billing Engines: A third-party cloud usage solution can +- Usage or Billing Engines: A third-party cloud usage solution can implement a plug-in that can connects to CloudStack to subscribe to CloudStack events and generate usage data. The usage data is consumed by their usage software. -- - - AMQP plug-in can place all the events on the a message queue, then a +- AMQP plug-in can place all the events on the a message queue, then a AMQP message broker can provide topic-based notification to the subscribers. -- - - Publish and Subscribe notification service can be implemented as a +- Publish and Subscribe notification service can be implemented as a pluggable service in CloudStack that can provide rich set of APIs for event notification, such as topics-based subscription and notification. Additionally, the pluggable service can deal with multi-tenancy, authentication, and authorization issues. + Configuration ~~~~~~~~~~~~~ @@ -97,157 +95,107 @@ As a CloudStack administrator, perform the following one-time configuration to enable event notification framework. At run time no changes can control the behaviour. -#. - - Open ``'componentContext.xml``. - -#. - - Define a bean named ``eventNotificationBus`` as follows: - - - - - name : Specify a name for the bean. +#. Open ``'componentContext.xml``. - - +#. Define a bean named ``eventNotificationBus`` as follows: - server : The name or the IP address of the RabbitMQ AMQP server. + - name : Specify a name for the bean. - - + - server : The name or the IP address of the RabbitMQ AMQP server. - port : The port on which RabbitMQ server is running. + - port : The port on which RabbitMQ server is running. - - - - username : The username associated with the account to access the + - username : The username associated with the account to access the RabbitMQ server. - - - - password : The password associated with the username of the + - password : The password associated with the username of the account to access the RabbitMQ server. - - - - exchange : The exchange name on the RabbitMQ server where + - exchange : The exchange name on the RabbitMQ server where CloudStack events are published. A sample bean is given below: .. code:: bash - <bean id="eventNotificationBus" class="org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus"> - <property name="name" value="eventNotificationBus"/> - <property name="server" value="127.0.0.1"/> - <property name="port" value="5672"/> - <property name="username" value="guest"/> - <property name="password" value="guest"/> - <property name="exchange" value="cloudstack-events"/> - </bean> + <bean id="eventNotificationBus" class="org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus"> + <property name="name" value="eventNotificationBus"/> + <property name="server" value="127.0.0.1"/> + <property name="port" value="5672"/> + <property name="username" value="guest"/> + <property name="password" value="guest"/> + <property name="exchange" value="cloudstack-events"/> + </bean> The ``eventNotificationBus`` bean represents the ``org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus`` class. -#. +#. Restart the Management Server. - Restart the Management Server. Standard Events --------------- The events log records three types of standard events. -- - - INFO. This event is generated when an operation has been successfully +- INFO. This event is generated when an operation has been successfully performed. -- - - WARN. This event is generated in the following circumstances. - - - +- WARN. This event is generated in the following circumstances. - When a network is disconnected while monitoring a template + - When a network is disconnected while monitoring a template download. - - + - When a template download is abandoned. - When a template download is abandoned. - - - - - When an issue on the storage server causes the volumes to fail + - 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 +- ERROR. This event is generated when an operation has not been successfully performed + Long Running Job Events ----------------------- The events log records three types of standard events. -- - - INFO. This event is generated when an operation has been successfully +- INFO. This event is generated when an operation has been successfully performed. -- +- WARN. This event is generated in the following circumstances. - WARN. This event is generated in the following circumstances. - - - - - When a network is disconnected while monitoring a template + - When a network is disconnected while monitoring a template download. - - - - When a template download is abandoned. + - When a template download is abandoned. - - - - When an issue on the storage server causes the volumes to fail + - 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 +- ERROR. This event is generated when an operation has not been successfully performed + 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 +- Virtual machine creation, deletion, and on-going management operations -- - - Virtual router creation, deletion, and on-going management operations - -- +- Virtual router creation, deletion, and on-going management operations - Template creation and deletion +- Template creation and deletion -- +- Network/load balancer rules creation and deletion - Network/load balancer rules creation and deletion +- Storage volume creation and deletion -- +- User login and logout - Storage volume creation and deletion - -- - - User login and logout Deleting and Archiving Events and Alerts ---------------------------------------- @@ -269,61 +217,44 @@ deleted. In order to support the delete or archive alerts, the following global parameters have been added: -- - - **alert.purge.delay**: The alerts older than specified number of days +- **alert.purge.delay**: The alerts older than specified number of days are purged. Set the value to 0 to never purge alerts automatically. -- - - **alert.purge.interval**: The interval in seconds to wait before +- **alert.purge.interval**: The interval in seconds to wait before running the alert purge thread. The default is 86400 seconds (one day). -.. note:: Archived alerts or events cannot be viewed in the UI or by using the - API. They are maintained in the database for auditing or compliance - purposes. +.. note:: + Archived alerts or events cannot be viewed in the UI or by using the + API. They are maintained in the database for auditing or compliance + purposes. + Permissions ~~~~~~~~~~~ Consider the following: -- - - The root admin can delete or archive one or multiple alerts or +- The root admin can delete or archive one or multiple alerts or events. -- - - The domain admin or end user can delete or archive one or multiple +- The domain admin or end user can delete or archive one or multiple events. + Procedure ~~~~~~~~~ -#. - - Log in as administrator to the CloudStack UI. +#. Log in as administrator to the CloudStack UI. -#. +#. In the left navigation, click Events. - In the left navigation, click Events. +#. Perform either of the following: -#. - - Perform either of the following: - - - - - To archive events, click Archive Events, and specify event type + - To archive events, click Archive Events, and specify event type and date. - - - - To archive events, click Delete Events, and specify event type and + - To archive events, click Delete Events, and specify event type and date. -#. - - Click OK. +#. Click OK. http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/hosts.rst ---------------------------------------------------------------------- diff --git a/source/hosts.rst b/source/hosts.rst index 9fcf260..755a891 100644 --- a/source/hosts.rst +++ b/source/hosts.rst @@ -24,6 +24,7 @@ Additional hosts can be added at any time to provide more capacity for guest VMs. For requirements and instructions, see `âAdding a Hostâ <http://docs.cloudstack.apache.org/projects/cloudstack-installation/en/latest/configuration.html#adding-a-host>`_. + Scheduled Maintenance and Maintenance Mode for Hosts ---------------------------------------------------- @@ -33,6 +34,7 @@ the guest VMs already running on the host are seamlessly migrated to another host not in maintenance mode. This migration uses live migration technology and does not interrupt the execution of the guest. + vCenter and Maintenance Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -40,9 +42,7 @@ To enter maintenance mode on a vCenter host, both vCenter and CloudStack must be used in concert. CloudStack and vCenter have separate maintenance modes that work closely together. -#. - - Place the host into CloudStack's "scheduled maintenance" mode. This +#. Place the host into CloudStack's "scheduled maintenance" mode. This does not invoke the vCenter maintenance mode, but only causes VMs to be migrated off the host @@ -54,35 +54,26 @@ maintenance modes that work closely together. disruption to the guests. After this migration is completed, the host will enter the Ready for Maintenance mode. -#. - - Wait for the "Ready for Maintenance" indicator to appear in the UI. - -#. +#. Wait for the "Ready for Maintenance" indicator to appear in the UI. - Now use vCenter to perform whatever actions are necessary to maintain +#. Now use vCenter to perform whatever actions are necessary to maintain the host. During this time, the host cannot be the target of new VM allocations. -#. - - When the maintenance tasks are complete, take the host out of +#. When the maintenance tasks are complete, take the host out of maintenance mode as follows: - #. - - First use vCenter to exit the vCenter maintenance mode. + #. First use vCenter to exit the vCenter maintenance mode. This makes the host ready for CloudStack to reactivate it. - #. - - Then use CloudStack's administrator UI to cancel the CloudStack + #. Then use CloudStack's administrator UI to cancel the CloudStack maintenance mode When the host comes back online, the VMs that were migrated off of it may be migrated back to it manually and new VMs can be added. + XenServer and Maintenance Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -95,46 +86,31 @@ Mode, you cannot create or start any VMs on it. **To place a server in Maintenance Mode:** -#. - - In the Resources pane, select the server, then do one of the +#. In the Resources pane, select the server, then do one of the following: - - - - Right-click, then click Enter Maintenance Mode on the shortcut + - Right-click, then click Enter Maintenance Mode on the shortcut menu. - - - - On the Server menu, click Enter Maintenance Mode. - -#. + - On the Server menu, click Enter Maintenance Mode. - Click Enter Maintenance Mode. +#. Click Enter Maintenance Mode. The server's status in the Resources pane shows when all running VMs have been successfully migrated off the server. **To take a server out of Maintenance Mode:** -#. - - In the Resources pane, select the server, then do one of the +#. In the Resources pane, select the server, then do one of the following: - - - - Right-click, then click Exit Maintenance Mode on the shortcut + - Right-click, then click Exit Maintenance Mode on the shortcut menu. - - + - On the Server menu, click Exit Maintenance Mode. - On the Server menu, click Exit Maintenance Mode. +#. Click Exit Maintenance Mode. -#. - - Click Exit Maintenance Mode. Disabling and Enabling Zones, Pods, and Clusters ------------------------------------------------ @@ -148,43 +124,26 @@ first added to the cloud, it is Disabled by default. To disable and enable a zone, pod, or cluster: -#. - - Log in to the CloudStack UI as administrator - -#. - - In the left navigation bar, click Infrastructure. +#. Log in to the CloudStack UI as administrator -#. +#. In the left navigation bar, click Infrastructure. - In Zones, click View More. +#. In Zones, click View More. -#. - - If you are disabling or enabling a zone, find the name of the zone in +#. If you are disabling or enabling a zone, find the name of the zone in the list, and click the Enable/Disable button. |enable-disable.png| -#. - - If you are disabling or enabling a pod or cluster, click the name of +#. If you are disabling or enabling a pod or cluster, click the name of the zone that contains the pod or cluster. -#. - - Click the Compute tab. - -#. - - In the Pods or Clusters node of the diagram, click View All. +#. Click the Compute tab. -#. +#. In the Pods or Clusters node of the diagram, click View All. - Click the pod or cluster name in the list. +#. Click the pod or cluster name in the list. -#. +#. Click the Enable/Disable button. |enable-disable.png| - Click the Enable/Disable button. |enable-disable.png| Removing Hosts -------------- @@ -192,6 +151,7 @@ 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 Hosts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -199,24 +159,19 @@ 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: -#. - - Place the node in maintenance mode. +#. Place the node in maintenance mode. See `âScheduled Maintenance and Maintenance Mode for Hostsâ <#scheduled-maintenance-and-maintenance-mode-for-hosts>`_. -#. - - For KVM, stop the cloud-agent service. - -#. +#. For KVM, stop the cloud-agent service. - Use the UI option to remove the node. +#. Use the UI option to remove the node. Then you may power down the Host, re-use its IP address, re-install it, etc + Removing vSphere Hosts ~~~~~~~~~~~~~~~~~~~~~~ @@ -227,6 +182,7 @@ CloudStack to remove the host. CloudStack will not direct commands to a host that has been removed using CloudStack. However, the host may still exist in the vCenter cluster. + Re-Installing Hosts ------------------- @@ -234,6 +190,7 @@ 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 Hosts -------------------------------- @@ -249,7 +206,10 @@ any system that is not up to date with patches. .. 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 Base <http://docs.cloudstack.org/Knowledge_Base/Possible_VM_corruption_if_XenServer_Hotfix_is_not_Applied/Highly_Recommended_Hotfixes_for_XenServer_5.6_SP2>`_. +(XenServer) For more information, see +`Highly Recommended Hotfixes for XenServer in the CloudStack Knowledge Base +<http://docs.cloudstack.org/Knowledge_Base/Possible_VM_corruption_if_XenServer_Hotfix_is_not_Applied/Highly_Recommended_Hotfixes_for_XenServer_5.6_SP2>`_. + Changing Host Password ---------------------- @@ -260,19 +220,13 @@ same password. To change a Node's password: -#. - - Identify all hosts in the cluster. +#. Identify all hosts in the cluster. -#. - - Change the password on all hosts in the cluster. Now the password for +#. 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. -#. - - Get the list of host IDs for the host in the cluster where you are +#. 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: @@ -281,14 +235,10 @@ To change a Node's password: mysql> select id from cloud.host where name like '%h%'; -#. - - This should return a single ID. Record the set of such IDs for these +#. This should return a single ID. Record the set of such IDs for these hosts. -#. - - Update the passwords for the host in the database. In this example, +#. 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". @@ -296,6 +246,7 @@ To change a Node's password: mysql> update cloud.host set password='password' where id=5 or id=10 or id=12; + Over-Provisioning and Service Offering Limits --------------------------------------------- @@ -350,21 +301,19 @@ configured for that cluster. It is up to the administrator to be sure the host is actually suitable for the level of over-provisioning which has been set. + Limitations on Over-Provisioning in XenServer and KVM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- - - In XenServer, due to a constraint of this hypervisor, you can not use +- In XenServer, due to a constraint of this hypervisor, you can not use an over-provisioning factor greater than 4. -- - - The KVM hypervisor can not manage memory allocation to VMs +- The KVM hypervisor can not manage memory allocation to VMs dynamically. CloudStack sets the minimum and maximum amount of memory that a VM can use. The hypervisor adjusts the memory within the set limits based on the memory contention. + Requirements for Over-Provisioning ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -373,6 +322,7 @@ function properly. The feature is dependent on the OS type, hypervisor capabilities, and certain scripts. It is the administrator's responsibility to ensure that these requirements are met. + Balloon Driver ^^^^^^^^^^^^^^ @@ -380,12 +330,14 @@ All VMs should have a balloon driver installed in them. The hypervisor communicates with the balloon driver to free up and make the memory available to a VM. + XenServer ''''''''' The balloon driver can be found as a part of xen pv or PVHVM drivers. The xen pvhvm drivers are included in upstream linux kernels 2.6.36+. + VMware '''''' @@ -393,6 +345,7 @@ The balloon driver can be found as a part of the VMware tools. All the VMs that are deployed in a over-provisioned cluster should have the VMware tools installed. + KVM ''' @@ -401,22 +354,26 @@ installed in all Linux kernel versions 2.6.25 and greater. The administrator must set CONFIG\_VIRTIO\_BALLOON=y in the virtio configuration. + Hypervisor capabilities ^^^^^^^^^^^^^^^^^^^^^^^ The hypervisor must be capable of using the memory ballooning. + XenServer ''''''''' The DMC (Dynamic Memory Control) capability of the hypervisor should be enabled. Only XenServer Advanced and above versions have this feature. + VMware, KVM ''''''''''' Memory ballooning is supported by default. + Setting Over-Provisioning Ratios ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -434,35 +391,31 @@ based on the new over-provisioning ratios, to ensure that CloudStack is correctly tracking the amount of free capacity. .. note:: - It is safer not to deploy additional new VMs while the capacity recalculation is underway, in case the new values for available capacity are not high enough to accommodate the new VMs. Just wait for the new used/available values to become available, to be sure there is room for all the new VMs you want. + It is safer not to deploy additional new VMs while the capacity + recalculation is underway, in case the new values for available + capacity are not high enough to accommodate the new VMs. Just wait + for the new used/available values to become available, to be sure + there is room for all the new VMs you want. To change the over-provisioning ratios for an existing cluster: -#. - - Log in as administrator to the CloudStack UI. - -#. - - In the left navigation bar, click Infrastructure. - -#. - - Under Clusters, click View All. +#. Log in as administrator to the CloudStack UI. -#. +#. In the left navigation bar, click Infrastructure. - Select the cluster you want to work with, and click the Edit button. +#. Under Clusters, click View All. -#. +#. Select the cluster you want to work with, and click the Edit button. - Fill in your desired over-provisioning multipliers in the fields CPU +#. Fill in your desired over-provisioning multipliers in the fields CPU overcommit ratio and RAM overcommit ratio. The value which is intially shown in these fields is the default value inherited from the global configuration settings. .. note:: - In XenServer, due to a constraint of this hypervisor, you can not use an over-provisioning factor greater than 4. + In XenServer, due to a constraint of this hypervisor, you can not + use an over-provisioning factor greater than 4. + Service Offering Limits and Over-Provisioning ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -484,6 +437,7 @@ offering. For example, a guest created from a 2 GHz service offering will receive twice the CPU allocation as a guest created from a 1 GHz service offering. CloudStack does not perform memory over-provisioning. + VLAN Provisioning ----------------- @@ -513,6 +467,7 @@ if you run out of VLANs. Another advantage is that you can use the same set of IPs for different customers, each one with their own routers and the guest networks on different physical NICs. + VLAN Allocation Example ~~~~~~~~~~~~~~~~~~~~~~~ @@ -530,6 +485,7 @@ less than 500 Management traffic. Reserved for administrative greater than 1000 Reserved for future use ================= ============================= ==================================================================================================== + Adding Non Contiguous VLAN Ranges ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -539,47 +495,30 @@ VLAN range or add multiple non contiguous VLAN ranges while creating a zone. You can also use the UpdatephysicalNetwork API to extend the VLAN range. -#. - - Log in to the CloudStack UI as an administrator or end user. +#. Log in to the CloudStack UI as an administrator or end user. -#. +#. Ensure that the VLAN range does not already exist. - Ensure that the VLAN range does not already exist. +#. In the left navigation, choose Infrastructure. -#. - - In the left navigation, choose Infrastructure. - -#. - - On Zones, click View More, then click the zone to which you want to +#. On Zones, click View More, then click the zone to which you want to work with. -#. - - Click Physical Network. +#. Click Physical Network. -#. +#. In the Guest node of the diagram, click Configure. - In the Guest node of the diagram, click Configure. - -#. - - Click Edit |edit-icon.png|. +#. Click Edit |edit-icon.png|. The VLAN Ranges field now is editable. -#. - - Specify the start and end of the VLAN range in comma-separated list. +#. Specify the start and end of the VLAN range in comma-separated list. Specify all the VLANs you want to use, VLANs not specified will be removed if you are adding new ranges to the existing list. -#. +#. Click Apply. - Click Apply. Assigning VLANs to Isolated Networks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -602,36 +541,28 @@ view what VLAN is assigned to a network. To enable you to assign VLANs to Isolated networks, -#. - - Create a network offering by specifying the following: - - - +#. Create a network offering by specifying the following: - **Guest Type**: Select Isolated. + - **Guest Type**: Select Isolated. - - - - **Specify VLAN**: Select the option. + - **Specify VLAN**: Select the option. For more information, see the CloudStack Installation Guide. -#. - - Using this network offering, create a network. +#. Using this network offering, create a network. You can create a VPC tier or an Isolated network. -#. - - Specify the VLAN when you create the network. +#. Specify the VLAN when you create the network. When VLAN is specified, a CIDR and gateway are assigned to this network and the state is changed to Setup. In this state, the network will not be garbage collected. .. note:: - You cannot change a VLAN once it's assigned to the network. The VLAN remains with the network for its entire life cycle. + You cannot change a VLAN once it's assigned to the network. The VLAN + remains with the network for its entire life cycle. + .. |enable-disable.png| image:: _static/images/enable-disable.png :alt: button to enable or disable zone, pod, or cluster. http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/index.rst ---------------------------------------------------------------------- diff --git a/source/index.rst b/source/index.rst index cc25dd4..5ab217f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -18,9 +18,28 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. + Welcome to CloudStack Administration Documentation ================================================== +.. figure:: /_static/images/acslogo.png + :align: center + +.. warning:: + We are in the process of changing documentation format as well as hosting mechanism. + Please be patient with us as we migrate our entire documentation to this new setup. + +This guide is aimed at Administrators of a CloudStack based Cloud, +for Release Notes, Installation and General introduction to CloudStack +see the following guides: + +- `Documentation Start <http://docs.cloudstack.apache.org>`_ + +- `Installation Guide <http://docs.cloudstack.apache.org/projects/cloudstack-installation>`_ + +- `Release Notes <http://docs.cloudstack.apache.org/projects/cloudstack-release-notes>`_ + + User Interface -------------- @@ -29,6 +48,7 @@ User Interface ui + Managing Accounts, Users and Domains ------------------------------------ @@ -37,6 +57,7 @@ Managing Accounts, Users and Domains accounts + Using Projects to Organize User Resources ------------------------------------------ .. toctree:: @@ -44,6 +65,7 @@ Using Projects to Organize User Resources projects + Service Offerings ----------------- @@ -52,6 +74,7 @@ Service Offerings service_offerings + Setting up Networking for Users ------------------------------- @@ -60,6 +83,7 @@ Setting up Networking for Users networking + Working with Virtual Machines ----------------------------- @@ -68,6 +92,7 @@ Working with Virtual Machines virtual_machines + Working with Templates ---------------------- @@ -76,6 +101,7 @@ Working with Templates templates + Working with Hosts ------------------ @@ -84,6 +110,7 @@ Working with Hosts hosts + Working with Storage -------------------- @@ -92,6 +119,7 @@ Working with Storage storage + Working with System Virtual Machines ------------------------------------ @@ -100,6 +128,7 @@ Working with System Virtual Machines systemvm + Working with Usage ------------------ @@ -108,6 +137,7 @@ Working with Usage usage + Managing Networks and Traffic ----------------------------- @@ -116,6 +146,7 @@ Managing Networks and Traffic networking_and_traffic + Managing the Cloud ------------------ @@ -124,6 +155,7 @@ Managing the Cloud management + System Reliability and Availability ----------------------------------- @@ -132,6 +164,7 @@ System Reliability and Availability reliability + Tuning ------ @@ -140,6 +173,7 @@ Tuning tuning + Events and Troubleshooting -------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/management.rst ---------------------------------------------------------------------- diff --git a/source/management.rst b/source/management.rst index a5f7266..a52b40f 100644 --- a/source/management.rst +++ b/source/management.rst @@ -45,74 +45,44 @@ find all the volumes having tag region=canada OR tag city=Toronto: .. code:: bash - command=listVolumes - &listAll=true - &tags[0].key=region - &tags[0].value=canada - &tags[1].key=city - &tags[1].value=Toronto + 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 - listVirtualMachines +- listVolumes -- +- listSnapshots - listVolumes +- listNetworks -- +- listTemplates - listSnapshots +- listIsos -- +- listFirewallRules - listNetworks +- listPortForwardingRules -- +- listPublicIpAddresses - listTemplates +- listSecurityGroups -- +- listLoadBalancerRules - listIsos +- listProjects -- +- listVPCs - listFirewallRules +- listNetworkACLs -- - - listPortForwardingRules - -- - - listPublicIpAddresses - -- - - listSecurityGroups - -- - - listLoadBalancerRules - -- - - listProjects - -- - - listVPCs - -- - - listNetworkACLs - -- - - listStaticRoutes +- listStaticRoutes Reporting CPU Sockets @@ -153,9 +123,7 @@ CloudStack. If so, you'll need to change the password in MySQL, and then add the encrypted password to ``/etc/cloudstack/management/db.properties``. -#. - - Before changing the password, you'll need to stop CloudStack's +#. Before changing the password, you'll need to stop CloudStack's management server and the usage engine if you've deployed that component. @@ -164,9 +132,7 @@ add the encrypted password to # service cloudstack-management stop # service cloudstack-usage stop -#. - - Next, you'll update the password for the CloudStack user on the MySQL +#. Next, you'll update the password for the CloudStack user on the MySQL server. .. code:: bash @@ -181,9 +147,7 @@ add the encrypted password to flush privileges; quit; -#. - - The next step is to encrypt the password and copy the encrypted +#. The next step is to encrypt the password and copy the encrypted password to CloudStack's database configuration (``/etc/cloudstack/management/db.properties``). @@ -191,6 +155,7 @@ add the encrypted password to # java -classpath /usr/share/cloudstack-common/lib/jasypt-1.9.0.jar \ org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI encrypt.sh \ input="newpassword123" password="`cat /etc/cloudstack/management/key`" \ verbose=false + File encryption type -------------------- @@ -198,9 +163,7 @@ File encryption type web encryption type then you'll use password="management\_server\_secret\_key" -#. - - Now, you'll update ``/etc/cloudstack/management/db.properties`` with +#. Now, you'll update ``/etc/cloudstack/management/db.properties`` with the new ciphertext. Open ``/etc/cloudstack/management/db.properties`` in a text editor, and update these parameters: @@ -209,9 +172,7 @@ File encryption type db.cloud.password=ENC(encrypted_password_from_above) db.usage.password=ENC(encrypted_password_from_above) -#. - - After copying the new password over, you can now start CloudStack +#. After copying the new password over, you can now start CloudStack (and the usage engine, if necessary). .. code:: bash @@ -219,6 +180,7 @@ File encryption type # service cloudstack-management start # service cloud-usage start + Administrator Alerts -------------------- @@ -233,19 +195,14 @@ 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 +- The Management Server cluster runs low on CPU, memory, or storage resources -- - - The Management Server loses heartbeat from a Host for more than 3 +- The Management Server loses heartbeat from a Host for more than 3 minutes -- +- The Host cluster runs low on CPU, memory, or storage resources - The Host cluster runs low on CPU, memory, or storage resources Sending Alerts to External SNMP and Syslog Managers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -261,117 +218,118 @@ The alerts which can be sent are: The following is the list of alert type numbers. The current alerts can be found by calling listAlerts. -:: - - MEMORY = 0 // Available Memory below configured threshold - -:: - - CPU = 1 // Unallocated CPU below configured threshold - -:: - - STORAGE =2 // Available Storage below configured threshold - -:: - - STORAGE_ALLOCATED = 3 // Remaining unallocated Storage is below configured threshold - -:: - - PUBLIC_IP = 4 // Number of unallocated virtual network public IPs is below configured threshold - -:: - - PRIVATE_IP = 5 // Number of unallocated private IPs is below configured threshold - -:: - - SECONDARY_STORAGE = 6 // Available Secondary Storage in availability zone is below configured threshold - -:: - - HOST = 7 // Host related alerts like host disconnected - -:: - - USERVM = 8 // User VM stopped unexpectedly - -:: - - DOMAIN_ROUTER = 9 // Domain Router VM stopped unexpectedly - -:: - - CONSOLE_PROXY = 10 // Console Proxy VM stopped unexpectedly - -:: - - ROUTING = 11 // Lost connection to default route (to the gateway) - -:: - - STORAGE_MISC = 12 // Storage issue in system VMs - -:: - - USAGE_SERVER = 13 // No usage server process running +:: + + MEMORY = 0 // Available Memory below configured threshold -:: +:: + + CPU = 1 // Unallocated CPU below configured threshold - MANAGMENT_NODE = 14 // Management network CIDR is not configured originally +:: + + STORAGE =2 // Available Storage below configured threshold -:: +:: + + STORAGE_ALLOCATED = 3 // Remaining unallocated Storage is below configured threshold - DOMAIN_ROUTER_MIGRATE = 15 // Domain Router VM Migration was unsuccessful +:: + + PUBLIC_IP = 4 // Number of unallocated virtual network public IPs is below configured threshold -:: +:: + + PRIVATE_IP = 5 // Number of unallocated private IPs is below configured threshold - CONSOLE_PROXY_MIGRATE = 16 // Console Proxy VM Migration was unsuccessful +:: + + SECONDARY_STORAGE = 6 // Available Secondary Storage in availability zone is below configured threshold -:: +:: + + HOST = 7 // Host related alerts like host disconnected - USERVM_MIGRATE = 17 // User VM Migration was unsuccessful +:: + + USERVM = 8 // User VM stopped unexpectedly -:: +:: + + DOMAIN_ROUTER = 9 // Domain Router VM stopped unexpectedly - VLAN = 18 // Number of unallocated VLANs is below configured threshold in availability zone +:: + + CONSOLE_PROXY = 10 // Console Proxy VM stopped unexpectedly -:: +:: + + ROUTING = 11 // Lost connection to default route (to the gateway) - SSVM = 19 // SSVM stopped unexpectedly +:: + + STORAGE_MISC = 12 // Storage issue in system VMs -:: +:: + + USAGE_SERVER = 13 // No usage server process running - USAGE_SERVER_RESULT = 20 // Usage job failed +:: + + MANAGMENT_NODE = 14 // Management network CIDR is not configured originally -:: +:: + + DOMAIN_ROUTER_MIGRATE = 15 // Domain Router VM Migration was unsuccessful - STORAGE_DELETE = 21 // Failed to delete storage pool +:: + + CONSOLE_PROXY_MIGRATE = 16 // Console Proxy VM Migration was unsuccessful -:: +:: + + USERVM_MIGRATE = 17 // User VM Migration was unsuccessful - UPDATE_RESOURCE_COUNT = 22 // Failed to update the resource count +:: + + VLAN = 18 // Number of unallocated VLANs is below configured threshold in availability zone -:: +:: + + SSVM = 19 // SSVM stopped unexpectedly - USAGE_SANITY_RESULT = 23 // Usage Sanity Check failed +:: + + USAGE_SERVER_RESULT = 20 // Usage job failed -:: +:: + + STORAGE_DELETE = 21 // Failed to delete storage pool - DIRECT_ATTACHED_PUBLIC_IP = 24 // Number of unallocated shared network IPs is low in availability zone +:: + + UPDATE_RESOURCE_COUNT = 22 // Failed to update the resource count -:: +:: + + USAGE_SANITY_RESULT = 23 // Usage Sanity Check failed - LOCAL_STORAGE = 25 // Remaining unallocated Local Storage is below configured threshold +:: + + DIRECT_ATTACHED_PUBLIC_IP = 24 // Number of unallocated shared network IPs is low in availability zone -:: +:: + + LOCAL_STORAGE = 25 // Remaining unallocated Local Storage is below configured threshold - RESOURCE_LIMIT_EXCEEDED = 26 //Generated when the resource limit exceeds the limit. Currently used for recurring snapshots only +:: + + RESOURCE_LIMIT_EXCEEDED = 26 //Generated when the resource limit exceeds the limit. Currently used for recurring snapshots only You can also display the most up to date list by calling the API command ``listAlerts``. + SNMP Alert Details ^^^^^^^^^^^^^^^^^^ @@ -380,6 +338,7 @@ The supported protocol is SNMP version 2. Each SNMP trap contains the following information: message, podId, dataCenterId, clusterId, and generationTime. + Syslog Alert Details ^^^^^^^^^^^^^^^^^^^^ @@ -390,13 +349,13 @@ value, it will not be included. .. code:: bash - Date severity_level Management_Server_IP_Address/Name alertType:: value dataCenterId:: value podId:: value clusterId:: value message:: value + Date severity_level Management_Server_IP_Address/Name alertType:: value dataCenterId:: value podId:: value clusterId:: value message:: value For example: .. code:: bash - Mar 4 10:13:47 WARN localhost alertType:: managementNode message:: Management server node 127.0.0.1 is up + Mar 4 10:13:47 WARN localhost alertType:: managementNode message:: Management server node 127.0.0.1 is up Configuring SNMP and Syslog Managers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -404,30 +363,26 @@ Configuring SNMP and Syslog Managers To configure one or more SNMP managers or Syslog managers to receive alerts from CloudStack: -#. - - For an SNMP manager, install the CloudStack MIB file on your SNMP +#. For an SNMP manager, install the CloudStack MIB file on your SNMP manager system. This maps the SNMP OIDs to trap types that can be more easily read by users. The file must be publicly available. For more information on how to install this file, consult the documentation provided with the SNMP manager. -#. - - Edit the file /etc/cloudstack/management/log4j-cloud.xml. +#. Edit the file /etc/cloudstack/management/log4j-cloud.xml. .. code:: bash - # vi /etc/cloudstack/management/log4j-cloud.xml + # vi /etc/cloudstack/management/log4j-cloud.xml -#. - - Add an entry using the syntax shown below. Follow the appropriate +#. Add an entry using the syntax shown below. Follow the appropriate example depending on whether you are adding an SNMP manager or a Syslog manager. To specify multiple external managers, separate the IP addresses and other configuration values with commas (,). - .. note:: The recommended maximum number of SNMP or Syslog managers is 20 for each. + .. note:: + The recommended maximum number of SNMP or Syslog managers is 20 + for each. The following example shows how to configure two SNMP managers at IP addresses 10.1.1.1 and 10.1.1.2. Substitute your own IP addresses, @@ -436,16 +391,16 @@ alerts from CloudStack: .. code:: bash - <appender name="SNMP" class="org.apache.cloudstack.alert.snmp.SnmpTrapAppender"> - <param name="Threshold" value="WARN"/> <!-- Do not edit. The alert feature assumes WARN. --> - <param name="SnmpManagerIpAddresses" value="10.1.1.1,10.1.1.2"/> - <param name="SnmpManagerPorts" value="162,162"/> - <param name="SnmpManagerCommunities" value="public,public"/> - <layout class="org.apache.cloudstack.alert.snmp.SnmpEnhancedPatternLayout"> <!-- Do not edit --> - <param name="PairDelimeter" value="//"/> - <param name="KeyValueDelimeter" value="::"/> - </layout> - </appender> + <appender name="SNMP" class="org.apache.cloudstack.alert.snmp.SnmpTrapAppender"> + <param name="Threshold" value="WARN"/> <!-- Do not edit. The alert feature assumes WARN. --> + <param name="SnmpManagerIpAddresses" value="10.1.1.1,10.1.1.2"/> + <param name="SnmpManagerPorts" value="162,162"/> + <param name="SnmpManagerCommunities" value="public,public"/> + <layout class="org.apache.cloudstack.alert.snmp.SnmpEnhancedPatternLayout"> <!-- Do not edit --> + <param name="PairDelimeter" value="//"/> + <param name="KeyValueDelimeter" value="::"/> + </layout> + </appender> The following example shows how to configure two Syslog managers at IP addresses 10.1.1.1 and 10.1.1.2. Substitute your own IP addresses. @@ -454,23 +409,19 @@ alerts from CloudStack: .. code:: bash - <appender name="ALERTSYSLOG"> - <param name="Threshold" value="WARN"/> - <param name="SyslogHosts" value="10.1.1.1,10.1.1.2"/> - <param name="Facility" value="LOCAL6"/> - <layout> - <param name="ConversionPattern" value=""/> - </layout> - </appender> - -#. + <appender name="ALERTSYSLOG"> + <param name="Threshold" value="WARN"/> + <param name="SyslogHosts" value="10.1.1.1,10.1.1.2"/> + <param name="Facility" value="LOCAL6"/> + <layout> + <param name="ConversionPattern" value=""/> + </layout> + </appender> - If your cloud has multiple Management Server nodes, repeat these +#. If your cloud has multiple Management Server nodes, repeat these steps to edit log4j-cloud.xml on every instance. -#. - - If you have made these changes while the Management Server is +#. If you have made these changes while the Management Server is running, wait a few minutes for the change to take effect. **Troubleshooting:** If no alerts appear at the configured SNMP or @@ -479,6 +430,7 @@ there is an error in the syntax of the <appender> entry in log4j-cloud.xml. Check to be sure that the format and settings are correct. + Deleting an SNMP or Syslog Manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -486,6 +438,7 @@ To remove an external SNMP manager or Syslog manager so that it no longer receives alerts from CloudStack, remove the corresponding entry from the file ``/etc/cloudstack/management/log4j-cloud.xml``. + Customizing the Network Domain Name ----------------------------------- @@ -495,63 +448,47 @@ 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. -#. - - Set the DNS suffix at the desired scope +#. Set the DNS suffix at the desired scope - - - - At the network level, the DNS suffix can be assigned through the + - At the network level, the DNS suffix can be assigned through the UI when creating a new network, as described in - `âAdding an Additional Guest Networkâ <networking2#adding-an-additional-guest-network>`_ or with the + `âAdding an Additional Guest Networkâ + <networking2#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 + - 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 + - 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. -#. - - To make the new DNS suffix take effect for an existing network, call +#. 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 +- 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 +- 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 +- 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 +- 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 Server --------------------------------------------------- @@ -568,11 +505,11 @@ operating system prompt on the Management Server node: .. code:: bash - # service cloudstack-management stop + # service cloudstack-management stop To start the Management Server: .. code:: bash - # service cloudstack-management start + # service cloudstack-management start http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/networking.rst ---------------------------------------------------------------------- diff --git a/source/networking.rst b/source/networking.rst index df65cd2..6568703 100644 --- a/source/networking.rst +++ b/source/networking.rst @@ -25,31 +25,22 @@ 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 physical networks in zones - -- - - Set up several different providers for the same service on a single +- 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 +- 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 +- 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 +- 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 Networks --------------------------- @@ -57,27 +48,24 @@ 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 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 +- Resources such as VLAN are allocated and garbage collected dynamically -- - - There is one network offering for the entire network +- There is one network offering for the entire network -- - - The network offering can be upgraded or downgraded but it is for the +- The network offering can be upgraded or downgraded but it is for the entire network -For more information, see `âConfigure Guest Traffic in an Advanced Zoneâ <networking2.html#configure-guest-traffic-in-an-advanced-zone>`_. +For more information, see `âConfigure Guest Traffic in an Advanced Zoneâ +<networking2.html#configure-guest-traffic-in-an-advanced-zone>`_. + Shared Networks ~~~~~~~~~~~~~~~ @@ -87,32 +75,21 @@ different accounts. Network Isolation on shared networks is accomplished by using techniques such as security groups, which is supported only in Basic zones in CloudStack 3.0.3 and later versions. -- - - Shared Networks are created by the administrator - -- - - Shared Networks can be designated to a certain domain +- 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 +- Shared Network resources such as VLAN and physical network that it maps to are designated by the administrator -- +- Shared Networks can be isolated by security groups - Shared Networks can be isolated by security groups +- Public Network is a shared network that is not shown to the end users -- - - Public Network is a shared network that is not shown to the end users - -- - - Source NAT per zone is not supported in Shared Network when the +- Source NAT per zone is not supported in Shared Network when the service provider is virtual router. However, Source NAT per account - is supported. For information, see `âConfiguring a Shared Guest Networkâ <networking2.html#configuring-a-shared-guest-network>`_. + is supported. For information, see `âConfiguring a Shared Guest + Networkâ <networking2.html#configuring-a-shared-guest-network>`_. Runtime Allocation of Virtual Network Resources @@ -125,11 +102,13 @@ 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 Providers ------------------------- .. note:: - For the most up-to-date list of supported network service providers, see the CloudStack UI or call `listNetworkServiceProviders`. + For the most up-to-date list of supported network service providers, + see the CloudStack 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 @@ -176,54 +155,36 @@ offering. | Port Forwarding | Yes | No | Yes | No | No | +----------------------+-----------+------------+----------+-------------+-------------+ + Network Offerings ----------------- .. note:: - For the most up-to-date list of supported network services, see the CloudStack UI or call listNetworkServices. + For the most up-to-date list of supported network services, see the + CloudStack UI or call listNetworkServices. A network offering is a named set of network services, such as: -- - - DHCP - -- - - DNS - -- - - Source NAT - -- - - Static NAT - -- - - Port Forwarding +- DHCP -- +- DNS - Load Balancing +- Source NAT -- +- Static NAT - Firewall +- Port Forwarding -- +- Load Balancing - VPN +- Firewall -- +- VPN - (Optional) Name one of several available providers to use for a given +- (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 +- (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. @@ -240,7 +201,12 @@ balancing solution, and alternate networks for accessing the database backend. .. 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. + 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. When creating a new virtual network, the CloudStack administrator chooses which network offering to enable for that network. Each virtual @@ -252,80 +218,55 @@ CloudStack also has internal network offerings for use by CloudStack system VMs. These network offerings are not visible to users but can be modified by administrators. + Creating a New Network Offering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To create a network offering: -#. - - Log in with admin privileges to the CloudStack UI. - -#. - - In the left navigation bar, click Service Offerings. - -#. - - In Select Offering, choose Network Offering. +#. Log in with admin privileges to the CloudStack UI. -#. +#. In the left navigation bar, click Service Offerings. - Click Add Network Offering. +#. In Select Offering, choose Network Offering. -#. +#. Click Add Network Offering. - In the dialog, make the following choices: +#. In the dialog, make the following choices: - - + - **Name**. Any desired name for the network offering. - **Name**. Any desired name for the network offering. - - - - - **Description**. A short description of the offering that can be + - **Description**. A short description of the offering that can be displayed to users. - - - - **Network Rate**. Allowed data transfer rate in MB per second. - - - + - **Network Rate**. Allowed data transfer rate in MB per second. - **Guest Type**. Choose whether the guest network is isolated or + - **Guest Type**. Choose whether the guest network is isolated or shared. For a description of this term, see `âAbout Virtual Networksâ <#about-virtual-networks>`_. - - - - **Persistent**. Indicate whether the guest network is persistent + - **Persistent**. Indicate whether the guest network is persistent or not. The network that you can provision without having to deploy a VM on it is termed persistent network. For more information, see `âPersistent Networksâ <networking2.html#persistent-networks>`_. - - - - **Specify VLAN**. (Isolated guest networks only) Indicate whether + - **Specify VLAN**. (Isolated guest networks only) Indicate whether a VLAN could be specified when this offering is used. If you select this option and later use this network offering while creating a VPC tier or an isolated network, you will be able to specify a VLAN ID for the network you create. - - - - **VPC**. This option indicate whether the guest network is Virtual + - **VPC**. This option indicate whether the guest network is Virtual Private Cloud-enabled. A Virtual Private Cloud (VPC) is a private, isolated part of CloudStack. A VPC can have its own virtual network topology that resembles a traditional physical network. For more information on VPCs, see `âAbout Virtual Private Cloudsâ <networking2.html#about-virtual-private-clouds>`_. - - - - **Supported Services**. Select one or more of the possible network + - **Supported Services**. Select one or more of the possible network services. For some services, you must also choose the service provider; for example, if you select Load Balancer, you can choose the CloudStack virtual router or any other load balancers that @@ -365,9 +306,7 @@ To create a network offering: =================== ============================================================================ ============= ============= - - - - **System Offering**. If the service provider for any of the + - **System Offering**. If the service provider for any of the services selected in Supported Services is a virtual router, the System Offering field appears. Choose the system service offering that you want virtual routers to use in this network. For example, @@ -377,11 +316,10 @@ To create a network offering: system service offering and any custom system service offerings that have been defined by the CloudStack root administrator. - For more information, see `âSystem Service Offeringsâ <service_offerings.html#system-service-offerings>`_. + For more information, see `âSystem Service Offeringsâ + <service_offerings.html#system-service-offerings>`_. - - - - **LB Isolation**: Specify what type of load balancer isolation you + - **LB Isolation**: Specify what type of load balancer isolation you want for the network: Shared or Dedicated. **Dedicated**: If you select dedicated LB isolation, a dedicated @@ -400,9 +338,7 @@ To create a network offering: its maximum capacity, the device will not be allocated to a new account. - - - - **Mode**: You can select either Inline mode or Side by Side mode: + - **Mode**: You can select either Inline mode or Side by Side mode: **Inline mode**: Supported only for Juniper SRX firewall and BigF5 load balancer devices. In inline mode, a firewall device is placed @@ -417,29 +353,20 @@ To create a network offering: to the load balancer public IP is not routed through the firewall, and therefore, is exposed to the public network. - - - - **Associate Public IP**: Select this option if you want to assign + - **Associate Public IP**: Select this option if you want to assign a public IP address to the VMs deployed in the guest network. This option is available only if - - - - Guest network is shared. - - - + - Guest network is shared. - StaticNAT is enabled. + - StaticNAT is enabled. - - + - Elastic IP is enabled. - Elastic IP is enabled. + For information on Elastic IP, see `âAbout Elastic IPâ + <networking2.html#about-elastic-ip>`_. - For information on Elastic IP, see `âAbout Elastic IPâ <networking2.html#about-elastic-ip>`_. - - - - - **Redundant router capability**: Available only when Virtual + - **Redundant router capability**: Available only when Virtual Router is selected as the Source NAT provider. Select this option if you want to use two virtual routers in the network for uninterrupted connection: one operating as the master virtual @@ -450,9 +377,7 @@ To create a network offering: CloudStack deploys the routers on different hosts to ensure reliability if one host is down. - - - - **Conserve mode**: Indicate whether to use conserve mode. In this + - **Conserve mode**: Indicate whether to use conserve mode. In this mode, network resources are allocated only when the first virtual machine starts in the network. When conservative mode is off, the public IP can only be used for a single service. For example, a @@ -462,15 +387,14 @@ To create a network offering: the same public IP. .. note:: - If StaticNAT is enabled, irrespective of the status of the conserve mode, no port forwarding or load balancing rule can be created for the IP. However, you can add the firewall rules by using the createFirewallRule command. + If StaticNAT is enabled, irrespective of the status of the + conserve mode, no port forwarding or load balancing rule can be + created for the IP. However, you can add the firewall rules by + using the createFirewallRule command. - - + - **Tags**: Network tag to specify which physical network to use. - **Tags**: Network tag to specify which physical network to use. - - - - - **Default egress policy**: Configure the default policy for + - **Default egress policy**: Configure the default policy for firewall egress rules. Options are Allow and Deny. Default is Allow if no egress policy is specified, which indicates that all the egress traffic is accepted when a guest network is created @@ -480,7 +404,5 @@ To create a network offering: this case, when you configure an egress rules for an isolated guest network, rules are added to allow the specified traffic. -#. - - Click Add. +#. Click Add. http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/networking/global_server_load_balancing.rst ---------------------------------------------------------------------- diff --git a/source/networking/global_server_load_balancing.rst b/source/networking/global_server_load_balancing.rst index 3d88f4d..e25ea45 100644 --- a/source/networking/global_server_load_balancing.rst +++ b/source/networking/global_server_load_balancing.rst @@ -193,14 +193,14 @@ above, the administrator of xyztelco is the one who sets up GSLB: tenant's cloud that make use of the GSLB service. #. On the NetScaler side, configure GSLB as given in `Configuring Global - Server Load Balancing - (GSLB) <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-con.html>`_: + Server Load Balancing (GSLB) + <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-con.html>`_: #. Configuring a standard load balancing setup. #. Configure Authoritative DNS, as explained in `Configuring an - Authoritative DNS - Service <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-adns-svc-tsk.html>`_. + Authoritative DNS Service + <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-adns-svc-tsk.html>`_. #. Configure a GSLB site with site name formed from the domain name details. @@ -211,18 +211,18 @@ above, the administrator of xyztelco is the one who sets up GSLB: As per the example given above, the site names are A.xyztelco.com and B.xyztelco.com. - For more information, see `Configuring a Basic GSLB - Site <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-basic-site-tsk.html>`_. + For more information, see `Configuring a Basic GSLB Site + <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-basic-site-tsk.html>`_. #. Configure a GSLB virtual server. - For more information, see `Configuring a GSLB Virtual - Server <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-vsvr-tsk.html>`_. + For more information, see `Configuring a GSLB Virtual Server + <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-vsvr-tsk.html>`_. #. Configure a GSLB service for each virtual server. - For more information, see `Configuring a GSLB - Service <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-svc-tsk.html>`_. + For more information, see `Configuring a GSLB Service + <http://support.citrix.com/proddocs/topic/netscaler-traffic-management-10-map/ns-gslb-config-svc-tsk.html>`_. #. Bind the GSLB services to the GSLB virtual server. http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/networking/portable_ips.rst ---------------------------------------------------------------------- diff --git a/source/networking/portable_ips.rst b/source/networking/portable_ips.rst index 7daed13..55b3cd2 100644 --- a/source/networking/portable_ips.rst +++ b/source/networking/portable_ips.rst @@ -120,7 +120,7 @@ API: .. code:: bash - http://localhost:8096/client/api?command=enableStaticNat&response=json&ipaddressid=a4bc37b2-4b4e-461d-9a62-b66414618e36&virtualmachineid=a242c476-ef37-441e-9c7b-b303e2a9cb4f&networkid=6e7cd8d1-d1ba-4c35-bdaf-333354cbd49810 + http://localhost:8096/client/api?command=enableStaticNat&response=json&ipaddressid=a4bc37b2-4b4e-461d-9a62-b66414618e36&virtualmachineid=a242c476-ef37-441e-9c7b-b303e2a9cb4f&networkid=6e7cd8d1-d1ba-4c35-bdaf-333354cbd49810 Replace the UUID with appropriate UUID. For example, if you want to transfer a portable IP to network X and VM Y in a network, execute the @@ -128,4 +128,4 @@ following: .. code:: bash - http://localhost:8096/client/api?command=enableStaticNat&response=json&ipaddressid=a4bc37b2-4b4e-461d-9a62-b66414618e36&virtualmachineid=Y&networkid=X + http://localhost:8096/client/api?command=enableStaticNat&response=json&ipaddressid=a4bc37b2-4b4e-461d-9a62-b66414618e36&virtualmachineid=Y&networkid=X http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/networking/security_groups.rst ---------------------------------------------------------------------- diff --git a/source/networking/security_groups.rst b/source/networking/security_groups.rst index 9ff2841..8ef58b8 100644 --- a/source/networking/security_groups.rst +++ b/source/networking/security_groups.rst @@ -30,7 +30,8 @@ guest network for all guest VMs. In advanced zones, security groups are supported only on the KVM hypervisor. .. note:: - In a zone that uses advanced networking, you can instead define multiple guest networks to isolate traffic to VMs. + In a zone that uses advanced networking, you can instead define + multiple guest networks to isolate traffic to VMs. Each CloudStack account comes with a default security group that denies all inbound traffic and allows all outbound traffic. The default