diff --git a/docs/en-US/Book_Info_Admin.xml b/docs/en-US/Book_Info_Admin.xml new file mode 100644 index 00000000000..6bf89b328c8 --- /dev/null +++ b/docs/en-US/Book_Info_Admin.xml @@ -0,0 +1,46 @@ + + +%BOOK_ENTITIES; +]> + + + + + Apache CloudStack 4.0 + Administrator's Guide + Revised September 11, 2012 01:32 am Pacific + + + + + If you have already installed &PRODUCT; or you want to learn more about the ongoing + operation and maintenance of a &PRODUCT;-powered cloud, read this documentation. It + will help you start using, configuring, and managing the ongoing operation of your cloud. + + + + + + + + + + + diff --git a/docs/en-US/add-members-to-projects.xml b/docs/en-US/add-members-to-projects.xml index a51726e14fc..39c3edfb2c3 100644 --- a/docs/en-US/add-members-to-projects.xml +++ b/docs/en-US/add-members-to-projects.xml @@ -29,5 +29,7 @@ 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. + + diff --git a/docs/en-US/cloudstack_admin.ent b/docs/en-US/cloudstack_admin.ent index abb18851bcf..c52e1056321 100644 --- a/docs/en-US/cloudstack_admin.ent +++ b/docs/en-US/cloudstack_admin.ent @@ -1,22 +1,4 @@ - - - + - + diff --git a/docs/en-US/compute-disk-service-offerings.xml b/docs/en-US/compute-disk-service-offerings.xml index 2469dfe3a15..1fd2a91a38b 100644 --- a/docs/en-US/compute-disk-service-offerings.xml +++ b/docs/en-US/compute-disk-service-offerings.xml @@ -5,33 +5,32 @@ ]> -
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 CloudPlatform 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: + A service offering is a set of virtual hardware features such as CPU core count and speed, memory, and disk size. The &PRODUCT; 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, CloudPlatform emits usage records that can be integrated with billing systems. CloudPlatform separates service offerings into compute offerings and disk offerings. The computing service offering specifies: + 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, &PRODUCT; emits usage records that can be integrated with billing systems. &PRODUCT; separates service offerings into compute offerings and disk offerings. The computing service offering specifies: Guest CPU Guest RAM @@ -43,4 +42,9 @@ Disk size (optional). An offering without a disk size will allow users to pick their own Tags on the data disk + + +
+ + diff --git a/docs/en-US/configuring-projects.xml b/docs/en-US/configuring-projects.xml index e18843d15d6..db0a8b143c0 100644 --- a/docs/en-US/configuring-projects.xml +++ b/docs/en-US/configuring-projects.xml @@ -1,29 +1,15 @@ - %BOOK_ENTITIES; ]> - - -
Configuring Projects - Before &PRODUCT; users start using projects, the &PRODUCT; administrator must set up various systems to support them, including membership invitations, limits on project resources, and controls on who can create projects + 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. + + +
diff --git a/docs/en-US/creating-compute-offerings.xml b/docs/en-US/creating-compute-offerings.xml index 56679a422f4..31f974196fb 100644 --- a/docs/en-US/creating-compute-offerings.xml +++ b/docs/en-US/creating-compute-offerings.xml @@ -5,23 +5,22 @@ ]> - + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +-->
Creating a New Compute Offering To create a new compute offering: @@ -32,19 +31,36 @@ Click Add Compute Offering. 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; &PRODUCT; will then prompt for the subdomain's name. + 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; &PRODUCT; + will then prompt for the subdomain's name. Click Add. + +
diff --git a/docs/en-US/projects-overview.xml b/docs/en-US/projects-overview.xml new file mode 100644 index 00000000000..4f9a833b5ed --- /dev/null +++ b/docs/en-US/projects-overview.xml @@ -0,0 +1,31 @@ + + +%BOOK_ENTITIES; +]> + + +
+ Overview of Projects + Projects are used to organize people and resources. &PRODUCT; 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. &PRODUCT; 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 + You can configure &PRODUCT; to allow any user to create a new project, or you can restrict that ability to just &PRODUCT; administrators. Once you have created a project, you become that project’s administrator, and you can add others within your domain to the project. &PRODUCT; can be set up either so that you can add people directly to a project, or so that you have to send an invitation which the recipient must accept. Project members can view and manage all virtual resources created by anyone in the project (for example, share VMs). A user can be a member of any number of projects and can switch views in the &PRODUCT; UI to show only project-related information, such as project VMs, fellow project members, project-related alerts, and so on. + The project administrator can pass on the role to another project member. The project administrator can also add more members, remove members from the project, set new resource limits (as long as they are below the global defaults set by the &PRODUCT; administrator), and delete the project. When the administrator removes a member from the project, resources created by that user, such as VM instances, remain with the project. This brings us to the subject of resource ownership and which resources can be used by a project. + Resources created within a project are owned by the project, not by any particular &PRODUCT; account, and they can be used only within the project. A user who belongs to one or more projects can still create resources outside of those projects, and those resources belong to the user’s account; they will not be counted against the project’s usage or resource limits. You can create project-level networks to isolate traffic within the project and provide network services such as port forwarding, load balancing, VPN, and static NAT. A project can also make use of certain types of resources from outside the project, if those resources are shared. For example, a shared network or public template is available to any project in the domain. A project can get access to a private template if the template’s owner will grant permission. A project can use any service offering or disk offering available in its domain; however, you can not create private service and disk offerings at the project level.. +
+ diff --git a/docs/en-US/projects.xml b/docs/en-US/projects.xml index 0390f528f3f..39ce96bd3bc 100644 --- a/docs/en-US/projects.xml +++ b/docs/en-US/projects.xml @@ -5,27 +5,31 @@ ]> -
- Projects - Projects are used to organize people and resources. &PRODUCT; 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. &PRODUCT; 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 - You can configure &PRODUCT; to allow any user to create a new project, or you can restrict that ability to just &PRODUCT; administrators. Once you have created a project, you become that project’s administrator, and you can add others within your domain to the project. &PRODUCT; can be set up either so that you can add people directly to a project, or so that you have to send an invitation which the recipient must accept. Project members can view and manage all virtual resources created by anyone in the project (for example, share VMs). A user can be a member of any number of projects and can switch views in the &PRODUCT; UI to show only project-related information, such as project VMs, fellow project members, project-related alerts, and so on. - The project administrator can pass on the role to another project member. The project administrator can also add more members, remove members from the project, set new resource limits (as long as they are below the global defaults set by the &PRODUCT; administrator), and delete the project. When the administrator removes a member from the project, resources created by that user, such as VM instances, remain with the project. This brings us to the subject of resource ownership and which resources can be used by a project. - Resources created within a project are owned by the project, not by any particular &PRODUCT; account, and they can be used only within the project. A user who belongs to one or more projects can still create resources outside of those projects, and those resources belong to the user’s account; they will not be counted against the project’s usage or resource limits. You can create project-level networks to isolate traffic within the project and provide network services such as port forwarding, load balancing, VPN, and static NAT. A project can also make use of certain types of resources from outside the project, if those resources are shared. For example, a shared network or public template is available to any project in the domain. A project can get access to a private template if the template’s owner will grant permission. A project can use any service offering or disk offering available in its domain; however, you can not create private service and disk offerings at the project level.. -
+ + Using Projects to Organize Users and Resources + + + + + + + + + diff --git a/docs/en-US/provisioning-steps.xml b/docs/en-US/provisioning-steps.xml index 3febc814035..98717435c62 100644 --- a/docs/en-US/provisioning-steps.xml +++ b/docs/en-US/provisioning-steps.xml @@ -26,7 +26,6 @@ Steps 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 . - diff --git a/docs/en-US/set-global-project-resource-limits.xml b/docs/en-US/set-global-project-resource-limits.xml new file mode 100644 index 00000000000..e2b08cc807f --- /dev/null +++ b/docs/en-US/set-global-project-resource-limits.xml @@ -0,0 +1,28 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ Setting the Global Project Resource Limits + TODO +
diff --git a/docs/en-US/set-per-project-resource-limits.xml b/docs/en-US/set-per-project-resource-limits.xml new file mode 100644 index 00000000000..682b92ccf98 --- /dev/null +++ b/docs/en-US/set-per-project-resource-limits.xml @@ -0,0 +1,28 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ Setting Per-Project Resource Limits + TODO +
diff --git a/docs/en-US/set-resource-limits-for-projects.xml b/docs/en-US/set-resource-limits-for-projects.xml index 2c331acde51..52083d297c3 100644 --- a/docs/en-US/set-resource-limits-for-projects.xml +++ b/docs/en-US/set-resource-limits-for-projects.xml @@ -24,5 +24,7 @@
Setting Resource Limits for Projects - The &PRODUCT; 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 &PRODUCT; root administrator. The root administrator can also set lower resource limits for any project in the cloud + The &PRODUCT; 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 &PRODUCT; root administrator. The root administrator can also set lower resource limits for any project in the cloud. + +
diff --git a/docs/en-US/suspend-project.xml b/docs/en-US/suspend-project.xml index bfaa12a03d9..b4f821b2c26 100644 --- a/docs/en-US/suspend-project.xml +++ b/docs/en-US/suspend-project.xml @@ -32,17 +32,21 @@ In the left navigation, click Projects. In Select View, choose Projects. Click the name of the project. - Click one of the buttons: + Click one of the buttons:To delete, use - deletebutton.png: Removes a member - - + + deletebutton.png: Removes a project + + + To suspend, use - deletebutton.png: Removes a member + + deletebutton.png: suspends a project + diff --git a/docs/en-US/system-service-offerings.xml b/docs/en-US/system-service-offerings.xml index 75aa128d4c8..c41aa2e293b 100644 --- a/docs/en-US/system-service-offerings.xml +++ b/docs/en-US/system-service-offerings.xml @@ -26,4 +26,4 @@ System Service Offerings System service offerings provide a choice of CPU speed, number of CPUs, tags, and RAM size, just as other service offerings do. But rather than being used for virtual machine instances and exposed to users, system service offerings are used to change the default properties of virtual routers, console proxies, and other system VMs. System service offerings are visible only to the &PRODUCT; root administrator. &PRODUCT; provides default system service offerings. The &PRODUCT; root administrator can create additional custom system service offerings. When &PRODUCT; 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. - + diff --git a/docs/en-US/ui.xml b/docs/en-US/ui.xml index 4f7f327d700..94ea4eaf95c 100644 --- a/docs/en-US/ui.xml +++ b/docs/en-US/ui.xml @@ -5,24 +5,25 @@ ]> - User Interface - + User Interface + + diff --git a/docs/en-US/user-services-overview.xml b/docs/en-US/user-services-overview.xml index f9e38c09209..95761217fbf 100644 --- a/docs/en-US/user-services-overview.xml +++ b/docs/en-US/user-services-overview.xml @@ -5,94 +5,35 @@ ]> -
- User Services Overview - In addition to the physical and logical infrastructure of your cloud, and the &PRODUCT; 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 Templates - A user creating a new instance can make a variety of choices about its characteristics and capabilities. &PRODUCT; provides several ways to present users with choices when creating a new instance: - - Service Offerings, defined by the &PRODUCT; 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 &PRODUCT; administrator, provide a choice of disk size for primary data storage. See Creating a New Disk Offering. - Network Offerings, defined by the &PRODUCT; 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 &PRODUCT; administrator or by any &PRODUCT; user, are the base OS images that the user can choose from when creating a new instance. For example, &PRODUCT; 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 &PRODUCT; root administrator, and is used for configuring virtual infrastructure resources. For more information, see Upgrading a Virtual Router with System Service Offerings. -
-
- Accounts, Users, and Domains - An account typically represents a customer of the service provider or a department in a large organization. Multiple users can exist in an account. 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. - Accounts are grouped by domains. Domains usually contain 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. - 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. Root administrators have complete access to the system, including managing templates, service offerings, customer care administrators, and domains. 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. -
-
- Using an LDAP Server for User Authentication - You can use an external LDAP server such as Microsoft Active Directory or ApacheDS to authenticate &PRODUCT; end-users. Just map &PRODUCT; 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 &PRODUCT; for matching common values such as the user’s email address and name. &PRODUCT; 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 &PRODUCT;, call the &PRODUCT; 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 &PRODUCT; permission to search on the LDAP server - SSL keystore and password, if SSL is used - -
- Example LDAP Configuration Commands - To understand the examples in this section, you need to know the basic concepts behind calling the &PRODUCT; 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 - - 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 -&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 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 - The next few sections explain some of the concepts you will need to know when filling out the ldapConfig parameters. -
-
- Search Base - Coming soon: TODO -
-
- Query Filter - Coming soon: TODO -
-
- Search User Bind DN - Coming soon: TODO -
-
- SSL Keystore Path and Password - Coming soon: TODO -
-
-
+ + User Services Overview + In addition to the physical and logical infrastructure of your cloud, and the &PRODUCT; 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 Templates + A user creating a new instance can make a variety of choices about its characteristics and capabilities. &PRODUCT; provides several ways to present users with choices when creating a new instance: + + Service Offerings, defined by the &PRODUCT; 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 &PRODUCT; administrator, provide a choice of disk size for primary data storage. See Creating a New Disk Offering. + Network Offerings, defined by the &PRODUCT; 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 &PRODUCT; administrator or by any &PRODUCT; user, are the base OS images that the user can choose from when creating a new instance. For example, &PRODUCT; 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 &PRODUCT; root administrator, and is used for configuring virtual infrastructure resources. For more information, see Upgrading a Virtual Router with System Service Offerings. +
+ \ No newline at end of file diff --git a/docs/publican-adminguide.cfg b/docs/publican-adminguide.cfg index a5997823ad4..c8a109fbf8e 100644 --- a/docs/publican-adminguide.cfg +++ b/docs/publican-adminguide.cfg @@ -24,6 +24,7 @@ docname: cloudstack_admin brand: cloudstack chunk_first: 1 chunk_section_depth: 1 +condition: admin