PHP App Server (v13.5 LTS) - Runbook

Update Application Code

Application code is typically downloaded at boot time when an application server is launched. However, you can manually update the application code on a running server by executing an operational script. For example, you may want to retrieve the latest version of your application from a different branch in your software repository.

• To update the application code on a server run the app::do_update_code operational script.

Stop the Application (Stop Apache)

Warning! If you stop the application from running, a client will see receive a '503' error message in the browser if the request is routed to the application server. Therefore, before you perform this action you may want to remove the application server from the load balancing pool/service.

• To stop the application from running on the server, run the web_apache::do_stop operational script.

Start the Application (Start Apache)

If you stopped the application, you can start it again by running the following script.

• To start the application on the server, run the web_apache::do_start operational script.

Restart the Application (Restart Apache)

To restart the application on the server, run the or web_apache::do_restart operational script.

Connect or Disconnect from the Load Balancing Servers/Service

This ServerTemplate supports several load balancing options:

• HAProxy - Use RightScale's Load Balancer with HAProxy (v13.5 LTS) ServerTemplate to launch dedicated load balancing servers that use HAProxy for load balancing across servers in any cloud. 
• Elastic Load Balancing (ELB) - Load balancing service provided by Amazon. Use an ELB to load balance across servers in the same AWS cloud/region. For example, an ELB in 'us-east' can load balance across EC2 instances in the same region.
• Cloud Load Balancers (CLB) - Load balancing service provided by Rackspace. Use a CLB to load balance across servers in the Rackspace cloud. 

Define values for the required inputs depending on the chosen load balancing option. See the tables below for details.

HAProxy

Define the following inputs at the deployment level.

ELB

Define the following inputs at the deployment level.

CLB

Warning! When using Rackspace CLB, you must wait until after launching your first application server before setting up your load balancer via the Rackspace API or control panel. This is because you cannot create a new CLB without at least one running cloud server or external node associated. Also, you must create the CLB in the same datacenter as your running servers; Rackspace randomly assigns you to one of their datacenters (e.g. ORD, DFW, etc.). For example, you cannot use a CLB created in ORD to load balance across servers in DSW. If you want to change the datacenter that you were assigned to, you must contact Rackspace.

To configure application servers to work with Rackspace CLB, set the below input values at the deployment level. Since you will configure these inputs before setting up your new Cloud Load Balancer on Rackspace, carefully note each entry so that your Rackspace configuration, upon setup, will match these values exactly.

Define the following inputs at the deployment level.

Once the inputs are set, run one of the following scripts to add/remove an application server to/from the load balancing servers/service. 

• Run the lb::do_detach_request operational script if you no longer want an application server to receive new requests from the load balancer.
• Run the lb::do_attach_request operational script if you want an application server to start receiving requests from the load balancer.

Handle Attach or Detach

Warning! DO NOT RUN the following operational scripts because they are designed to be run as a remote recipe by a load balancer server and not as a manual operational script on an application server.

• lb::handle_attach
• lb::handle_detach

Enable or Disable Maintenance Mode

If you are performing upgrades to your application servers, you may want to inform your users by putting up a temporary maintenance window. Use the scripts below to turn on and off a basic Apache maintenance window. The default maintenance page is shown below however you can create your own custom maintenance page, if desired.

• Run the web_apache::do_enable_maintenance_mode operational script to make the maintenance window visible. 
• Run the web_apache::do_disable_maintenance_mode operational script to hide the maintenance window.

When you enable the maintenance mode, the contents of the maintenance tarball is unpacked and saved into a new directory. The content for the maintenance page is retrieved from the 'web_apache' cookbook (rightscale_cookbooks/cookbooks/web_apache/files/default/maintenance.tar.gz), and saved to a newly created maintenance directory (/home/webapps/system).

Note: By default, the application root directory (/home/webapps) defined by the Project App root input is different than the maintenance directory (/home/webapps/system) used by Apache.

Customize the Maintenance Page

Follow the steps below to replace the default maintenance page with your own custom message.

1. Create a custom HTML maintenance page and name it accordingly. (e.g. custom_maintenance.html) along with any required images, css files, etc. Note: The webpage will be renamed 'maintenance.html' when it is saved locally on the instance because Apache will look for a file called 'maintenance.html' in the directory.
2. Create a tarball that includes all the required custom content (e.g. maintenance.tar.gz).  
3. Override the default maintenance tarball in the 'web_apache' cookbook with your own custom message.

Apache will look for the maintenance page in the location specified by the default attribute file in the 'web_apache' cookbook: /home/webapps/system/maintenance.html 
Note: The location is defined in the following attribute file: rightscale_cookbooks/cookbooks/web_apache/attributes/default.rb

Enable, Disable, or Update Reconverge List

Typically, an application server has a script (e.g app::do_loadbalancers_allow) listed in the 'Reconvergence List' input that tries to attach itself to the specified load balancer servers or service based on its tags. By default, all scripts listed in the Recovergence List input are run every 15 minutes unless otherwise specified in the 'Interval in Minutes to Run Reconverge List' input. 

Note: This functionality only applies to Chef recipes. RightScripts are not supported in the Recoverge List.

1. Go to the current server's Inputs tab and add any recipes that you want to periodically be executed on the server to the 'Reconverge List' input. 

2. Go to the Scripts tab and run the appropriate operational script.
   • Run the sys::do_reconverge_list_enable operational script to enable reconverge functionality or update the current reconverge list. 
   • Run the sys::do_reconverge_list_disable operational script to disable reconverge functionality.

Add or Remove a Firewall Rule

When iptables is enabled, which is the default behavior in all Linux-based v13 ServerTemplates, TCP ports 22, 80, and 443 are configured to be open to any IP address in order to enable minimum functionality and access. If you want to add or remove a firewall rule on a running (operational) server by opening or closing a port, you can set the following inputs accordingly and run the sys_firewall::setup_rule operational script.

If you want the firewall rules to be set at boot time, you can either add the Chef recipe to the end of the boot script list or update the sys_firewall::default recipe to change the list of default firewall permissions by explicitly opening up additional ports. However, you should only consider overriding the default recipe if you want to change the default behavior for all of your servers that use that cookbook.

Note: If the cloud provider supports security groups, you must also open or close the appropriate ports in the security group resource.

1. Go to the current server's Inputs tab and set the following inputs accordingly.
    

2. Run the sys_firewall::setup_rule operational script to add the firewall permission to the running server(s).

List Current Firewall Rules

For troubleshooting and security purposes, you may want to list a server's current firewall rules to make sure that a server has the expected IP/port permissions. This script is especially useful if you want to check the firewall rules across all servers in a deployment to validate that all of them have the same iptables rules. 

1. Go to the running server's Scripts tab and run the sys_firewall::do_list_rules operational script.
2. Go to the server's Audit Entries tab to view the output. The output will look similar to the following example.

22:25:03: ==================== do_list_rules : Firewall rules Begin ==================
Chain INPUT (policy ACCEPT)
target     prot opt source               destination         
FWR        all  --  0.0.0.0/0            0.0.0.0/0           

Chain FORWARD (policy ACCEPT)
target     prot opt source               destination         

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination         

Chain FWR (1 references)
target     prot opt source               destination         
ACCEPT     all  --  0.0.0.0/0            0.0.0.0/0           
ACCEPT     all  --  0.0.0.0/0            0.0.0.0/0           state RELATED,ESTABLISHED 
ACCEPT     icmp --  0.0.0.0/0            0.0.0.0/0           
ACCEPT     tcp  --  0.0.0.0/0            0.0.0.0/0           tcp dpt:22 
ACCEPT     tcp  --  0.0.0.0/0            0.0.0.0/0           tcp dpt:443 
ACCEPT     tcp  --  10.123.456.22        0.0.0.0/0           tcp dpt:8000 
ACCEPT     tcp  --  0.0.0.0/0            0.0.0.0/0           tcp dpt:80 
REJECT     tcp  --  0.0.0.0/0            0.0.0.0/0           tcp flags:0x16/0x02 reject-with icmp-port-unreachable 
REJECT     udp  --  0.0.0.0/0            0.0.0.0/0           reject-with icmp-port-unreachable 
==================== do_list_rules : Firewall rules End ====================

If you want to perform the same action via SSH, follow the steps below.

1. SSH into the running server. (Requires 'server_login' user role privileges.)
2. Switch to the 'root' user.

Note: When using newer images (>5.8/13.4), ensure that you have the 'server_superuser' permission to the Rightscale account where the server is running in order to gain root privileges using the sudo command (Settings > Account Settings > Users).

# sudo -i

3. Type the following Unix command.

# /sbin/iptables -L

Enable or Disable Iptables

Iptables is typically enabled by default ('Firewall' = enabled). However, you can use the following script to enable or disable Iptables on an instance.

Warning! You should only perform this action if you fully understand its implications. For example, if the cloud provider does not support cloud-level firewall services such as security groups, you could permanently lock yourself out of the instance if you disable Iptables.

To enable Iptables, follow the steps below.

1. Set the 'Firewall' input to 'enabled'.
2. Run the sys_firewall::default (boot script).

To disable Iptables, follow the steps below.

1. Set the 'Firewall' input to 'disabled'.
2. Run the sys_firewall::default (boot script).

Enable or Disable System Security Updates

Typically, ServerTemplates are configured with frozen software repositories that are locked down to a specific date to ensure that the same versions of software and packages are installed on a server at launch time. You also have the option to configure the server so that you can easily apply security patches from one of the related system software repositories as they become available. (Currently, only the Epel and Ubuntu Precise (v12.04) repositories are checked for security updates.) System security updates are disabled by default at the ServerTemplate level, as defined by the 'Enable security updates' input. As a best practice, you should determine whether or not you want to reserve the ability to apply security updates as an operational script before you launch the server. Changing this setting after a server is operational is not recommended.

To enable security updates, follow the steps below.

Warning! Once security updates are enabled, they cannot be disabled.

1. Set 'Enable security updates' input to 'enable' at the deployment level, or at the (next) server level if you do not want this change to be applied to all future servers launched in the deployment.
2. Launch or relaunch the server, if possible. Otherwise, you must update the input setting under the current server's Inputs tab and run the rightscale::setup_security_updates boot script.

Apply System Security Updates

If the server is enabled for system security updates (Enable security updates = enable), a server tag will be added to the server when a security update becomes available ('rs_monitoring:security_updates_available=true'). By default, a triggered alert sends an email notification to the account owner as a reminder that a security update is available on a particular server. If a security update is available, follow the steps below to download and apply the security update.

1. Check to make sure that a security update is available. All effected servers will have the following server tag: rs_monitoring:security_updates_available=true 
2. Run the rightscale::do_security_updates operational script. You can either apply the update on a per server basis under the "current" server's Scripts tab. However, if you want to apply the update to some or all servers in a deployment, run the script at the deployment level instead (under the deployment's Scripts tab).
3. A reboot may be required to apply the security update. If you see the following reboot tag on the server ('rs_monitoring:reboot_required=true'), you must manually reboot the server at your convenience (View Server > More Actions > Reboot) to complete the security update.