New tutorials and troubleshooters.

Author: Paul Cornell

doc_source/_sample-prereqs.txt

@@ -8,10 +8,10 @@
    either express or implied. See the License for the specific language governing permissions and
    limitations under the License.
 
-This sample assumes you already have the |AC9IDE| for your |envfirst| open in your web browser, and that you're using an |envfirstec2| that is connected to an |EC2| instance running Amazon Linux. 
-If you're using a different operating system or using an |envfirstssh|, you might need to adapt this sample's instructions to correctly 
-install and configure this sample's required tools. To create 
-an |env|, see :ref:`Creating an Environment <create-environment>`.
+Before you use this sample, be sure to meet the following requirements.
 
-When you're using this sample, be sure you're signed in to AWS with the AWS account ID and name and password of the 
-user you created or identified in :doc:`Team Setup <setup>`.
+* **You must have an existing AWS Cloud9 development environment.** This sample assumes you already have an |envfirstec2| that is connected to an |EC2| instance running Amazon Linux. 
+  If you have a different type of |env| or 
+  operating system, you might need to adapt this sample's instructions to set up related tools. See :ref:`Creating an Environment <create-environment>` for details.
+* **You have the AWS Cloud IDE for the existing environment already open.** When you open an |env|, |AC9| opens the |IDE| for that |env| in your web browser. 
+  See :ref:`Opening an Environment <open-environment>` for details.

doc_source/app-preview.rst

@@ -34,9 +34,14 @@ Run an Application
 ==================
 
 Before you can preview your application from within the |IDE|, it must be running in the |envfirst| using 
-HTTP over port :code:`8080`, :code:`8081`, or :code:`8082` with the IP of :code:`127.0.0.1` or :code:`localhost`.
+HTTP over port :code:`8080`, :code:`8081`, or :code:`8082` with the IP of :code:`127.0.0.1`, :code:`localhost`, or :code:`0.0.0.0`.
 
-.. note:: You don't have to run using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082` with the IP of :code:`127.0.0.1` or :code:`localhost`. However, you won't be able to preview your running application from within the |IDE|.
+.. note:: You don't have to run using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082` with the IP of :code:`127.0.0.1`, :code:`localhost`, or :code:`0.0.0.0`. However, you won't be able to preview your running application from within the |IDE|.
+
+   If you run with the IP of :code:`0.0.0.0`, anyone can potentially access your running application. For approaches to address this issue, see the following: 
+
+   * :ref:`app-preview-share-security-group` in *Share a Running Application over the Internet*
+   * :ref:`app-preview-share-subnet` in *Share a Running Application over the Internet*
 
 To write the code to run your application on a specific port and IP, see your application's documentation.
 
@@ -105,7 +110,7 @@ Then follow the instructions in the next procedure to preview it. On the applica
 Preview a Running Application
 =============================
 
-With your application already running using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082` with the IP of :code:`127.0.0.1` or :code:`localhost` in the |env|, 
+With your application already running using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082` with the IP of :code:`127.0.0.1`, :code:`localhost`, or :code:`0.0.0.0` in the |env|, 
 and with the corresponding application code file open and active in the |AC9IDE|, choose one of the following on the menu bar:
 
 * :guilabel:`Preview, Preview Running Application`
@@ -116,6 +121,10 @@ This opens an application preview tab within the |env|, and then displays the ap
 To enable others to preview the running application outside of the |IDE|, see :ref:`app-preview-share`. 
 
 .. note:: If the application is not already running, you will see an error on the application preview tab. Run or restart the application, and then choose the menu bar command again.
+
+   If your application cannot run on any of the preceding ports or IPs, or if your application must run on more than one of these ports at the same time (for example, your application must 
+   run on ports :code:`8080` and :code:`3000` at the same time), the application preview tab might display an error or might be blank. This is because the application preview tab 
+   within the |env| works only with the preceding ports and IPs, and it works with only a single port at a time.
 
    We don't recommend sharing the URL in the application preview tab with others. (The URL displays using the format 
    :code:`https://ENVIRONMENT_ID.vfs.cloud9.REGION_ID.amazonaws.com/`.) This URL works only when the |IDE| for the |env| is open and the application is running in the same web browser.    
@@ -228,8 +237,15 @@ Step 2: Set Up the Security Group for the Instance
 In this step, you use the |EC2| console to set up the |EC2| security group for the instance that is connected to the |env|, to allow incoming HTTP requests over port 8080, 8081, or 8082.
 
 .. note:: You don't have to run using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082`. If you are running on a different protocol or port, substitute it throughout this step. 
-   You won't be able to preview your running application from within the |IDE| until you switch back to running using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082` 
-   using IP :code:`127.0.0.1` or :code:`localhost`.
+   You won't be able to preview your running application from within the |IDE| until you switch back to running using HTTP over one of the ports and IPs as described in :ref:`app-preview-preview-app`.
+
+   For an additional layer of security, you can also set up a network access control list (ACL) for a subnet in a virtual private cloud (VPC) that the instance can use. 
+   For more information about security groups and network ACLs, see the following:
+   
+   * :ref:`app-preview-share-subnet`
+   * :VPC-ug:`Security <VPC_Security>` in the |VPC-ug|
+   * :VPC-ug:`Security Groups for Your VPC <VPC_SecurityGroups>` in the |VPC-ug|
+   * :VPC-ug:`Network ACLs <VPC_ACLs>` in the |VPC-ug|
 
 #. In the |IDE| for the |env|, on the menu bar, choose your user icon, and then choose :guilabel:`Manage EC2 Instance`. Then skip ahead to step 3 in this procedure.
 #. If choosing :guilabel:`Manage EC2 Instance` or other steps in this procedure display errors, we recommend you sign in to the |EC2| console using credentials for an |IAM| administrator user in your AWS account, and then 
@@ -244,7 +260,7 @@ In this step, you use the |EC2| console to set up the |EC2| security group for t
 
 #. In the :guilabel:`Description` tab for the instance, choose the security group link next to :guilabel:`Security groups`. 
 #. With the security group displayed, look on the :guilabel:`Inbound` tab. If a rule already exists where :guilabel:`Type` is set to :guilabel:`Custom TCP Rule` and :guilabel:`Port Range` is set to 
-   :guilabel:`8080`, :guilabel:`8081`, or :guilabel:`8082`, choose :guilabel:`Cancel`, and skip ahread to :ref:`app-preview-share-subnet`. Otherwise, choose :guilabel:`Edit`.
+   :guilabel:`8080`, :guilabel:`8081`, or :guilabel:`8082`, choose :guilabel:`Cancel`, and skip ahead to :ref:`app-preview-share-subnet`. Otherwise, choose :guilabel:`Edit`.
 #. In the :guilabel:`Edit inbound rules` dialog box, choose :guilabel:`Add Rule`.
 #. For :guilabel:`Type`, choose :guilabel:`Custom TCP Rule`.
 #. For :guilabel:`Port Range`, type :code:`8080`, :code:`8081`, or :code:`8082`. 
@@ -263,8 +279,14 @@ Step 3: Set Up the Subnet for the Instance
 In this step, you use the consoles for |EC2| and |VPClong| (|VPC|) to set up the subnet for the |EC2| instance that is connected to the |env|, to also allow incoming HTTP requests over port 8080, 8081, or 8082.
 
 .. note:: You don't have to run using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082`. If you are running on a different protocol or port, substitute it throughout this step. 
-   You won't be able to preview your running application from within the |IDE| until you switch back to running using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082` 
-   using IP :code:`127.0.0.1` or :code:`localhost`.
+   You won't be able to preview your running application from within the |IDE| until you switch back to running using HTTP over the ports and IPs as described in :ref:`app-preview-preview-app`.
+
+   This step describes how to set up a network ACL for a subnet in an |VPC| that the instance can use. This step is not required. However, it adds an additional layer of security when compared to just using 
+   security groups. For more information 
+   about network ACLs, see the following:
+   
+   * :VPC-ug:`Security <VPC_Security>` in the |VPC-ug|
+   * :VPC-ug:`Network ACLs <VPC_ACLs>` in the |VPC-ug|
 
 #. With the |EC2| console already open from the previous step, in the service navigation pane, expand :guilabel:`Instances` if it is not already expanded, 
    and then choose :guilabel:`Instances`.
@@ -292,10 +314,9 @@ In this step, you use the consoles for |EC2| and |VPClong| (|VPC|) to set up the
 Step 4: Change the Running Application IP
 -----------------------------------------
 
-In your code, switch from using IP :code:`127.0.0.1` or :code:`localhost` to using IP :code:`0.0.0.0`. To use this new IP, stop the application if is already running, and then run the application again.
+In your code, switch from using IP :code:`127.0.0.1`, :code:`localhost`, or :code:`0.0.0.0` to using the IP address or addresses you specified in the previous steps in this section. To use these new IPs, stop the application if is already running, and then run the application again.
 
-.. note:: You won't be able to preview your running application from within the |IDE| until you switch back to using IP :code:`127.0.0.1` or :code:`localhost` 
-   running HTTP over port :code:`8080`, :code:`8081`, or :code:`8082`.
+.. note:: You won't be able to preview your running application from within the |IDE| until you switch back to running using HTTP over one of the ports and IPs as described in :ref:`app-preview-preview-app`.
 
 .. _app-preview-share-url:
 
@@ -310,8 +331,8 @@ not the default for that protocol (for example, :code:`http://192.0.2.0:8080/ind
    :ec2-user-guide:`Associating an Elastic IP Address with a Running Instance <elastic-ip-addresses-eip.html#using-instance-addressing-eips-associating>` in the |EC2-ug|. Note also that 
    allocating an Elastic IP address might result in charges to your AWS account. For more information, see `Amazon EC2 Pricing <https://aws.amazon.com/ec2/pricing/>`_.
 
-   You don't have to run using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082`. However, you won't be able to preview your running application from within the |IDE| until you switch back to running using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082` 
-   using IP :code:`127.0.0.1` or :code:`localhost`.
+   You don't have to run using HTTP over port :code:`8080`, :code:`8081`, or :code:`8082`. However, you won't be able to preview your running application from within the |IDE| 
+   until you switch back to running using HTTP over one of the ports and IPs as described in :ref:`app-preview-preview-app`.
 
    If users make requests to the preceding URL, and those requests originate from a virtual private network (VPN) that blocks traffic over the requested protocol or 
    port, those requests might fail. Those users must use a different network that allows traffic over the requested protocol and port. For more information, see your network administrator.

doc_source/auth-and-access-control.rst

@@ -68,7 +68,7 @@ to sign in to secure AWS webpages like the |AC9| console, |console|,
 AWS Discussion Forums, and |SUPlong| Support Center.
 
 In addition to a user name and password, you can also generate access keys for each user. You can use these keys when you access AWS services
-programmatically, either through one of the several AWS SDKs or by using the |clilong| (|cli|). The AWS SDKs and the |cli| use these access keys to
+programmatically, either through one of the several AWS SDKs or by using the |clilong| (|cli|) or the aws-shell. The AWS SDKs, the |cli|, and the aws-shell use these access keys to
 cryptographically sign your request. If you don't use these tools, you must sign the request yourself. |AC9| supports Signature Version 4, a protocol
 for authenticating inbound API requests. For more information about authenticating requests, see :AWS-gr:`Signature Version 4 Signing Process <signature-version-4>` in the |AWS-gr|.
 

doc_source/change-environment.rst

@@ -20,6 +20,10 @@ Changing Environment Settings in |AC9long|
 
 You can change the preferences or settings for an |envfirst|.
 
+* :ref:`change-environment-single`
+* :ref:`change-environment-description`
+* :ref:`change-environment-description-code`
+
 .. _change-environment-single:
 
 Change |envtitle| Preferences
@@ -34,8 +38,8 @@ Change |envtitle| Preferences
 
 .. _change-environment-description:
 
-Change |envtitle| Settings
-==========================
+Change |envtitle| Settings with the Console
+===========================================
 
 #. Open the |AC9| console, if it isn't already open, at |AC9Console_link|.
 #. In the top navigation bar, choose the AWS Region where the |env| is located.
@@ -81,3 +85,42 @@ Change |envtitle| Settings
        :ref:`share-environment-delete-member`.
 
 .. include:: _find-environment.txt
+
+.. _change-environment-description-code:
+
+Change |envtitle| Settings with Code
+====================================
+
+To use code to change the settings of an |env| in |AC9|, call the |AC9| update |env| operation, as follows.
+
+.. list-table::
+   :widths: 1 1
+   :header-rows: 0
+
+   * - |cli|
+     - :AC9-cli:`update-environment <update-environment>`
+   * - |sdk-cpp|
+     - :sdk-cpp-ref:`UpdateEnvironmentRequest <LATEST/class_aws_1_1_cloud9_1_1_model_1_1_update_environment_request>`, 
+       :sdk-cpp-ref:`UpdateEnvironmentResult <LATEST/class_aws_1_1_cloud9_1_1_model_1_1_update_environment_result>`
+   * - |sdk-go|
+     - :sdk-for-go-api-ref:`UpdateEnvironment <service/cloud9/#Cloud9.UpdateEnvironment>`, 
+       :sdk-for-go-api-ref:`UpdateEnvironmentRequest <service/cloud9/#Cloud9.UpdateEnvironmentRequest>`, 
+       :sdk-for-go-api-ref:`UpdateEnvironmentWithContext <service/cloud9/#Cloud9.UpdateEnvironmentWithContext>`
+   * - |sdk-java|
+     - :sdk-java-api:`UpdateEnvironmentRequest <com/amazonaws/services/cloud9/model/UpdateEnvironmentRequest>`, 
+       :sdk-java-api:`UpdateEnvironmentResult <com/amazonaws/services/cloud9/model/UpdateEnvironmentResult>`
+   * - |sdk-js|
+     - :sdk-for-javascript-api-ref:`updateEnvironment <AWS/Cloud9.html#updateEnvironment-property>`
+   * - |sdk-net|
+     - :sdk-net-api-v3:`UpdateEnvironmentRequest <items/Cloud9/TUpdateEnvironmentRequest>`, 
+       :sdk-net-api-v3:`UpdateEnvironmentResponse <items/Cloud9/TUpdateEnvironmentResponse>`
+   * - |sdk-php|
+     - :sdk-for-php-api-ref:`updateEnvironment <api-cloud9-2017-09-23.html#updateenvironment>`
+   * - |sdk-python|
+     - :sdk-for-python-api-ref:`update_environment <services/cloud9.html#Cloud9.Client.update_environment>`
+   * - |sdk-ruby|
+     - :sdk-for-ruby-api-ref:`update_environment <Aws/Cloud9/Client.html#update_environment-instance_method>`
+   * - |TWPlong|
+     - :TWP-ref:`Update-C9Environment <items/Update-C9Environment>`
+   * - |AC9| API
+     - :AC9-api:`UpdateEnvironment <API_UpdateEnvironment>`