Atom feed of this document
 
 
 

 Chapter 2. Install and Configure

These instructions tell you how to install and configure:

  • raxmon, which is the Cloud Monitoring command-line interface (CLI)

  • The Cloud Monitoring Agent

 2.1. Install and Configure raxmon

You need to use the Cloud Monitoring command-line interface (CLI), raxmon, for some preliminary agent configuration. raxmon is also helpful if you use the tutorial in Chapter 3, Create Your First Monitor. raxmon runs on your local workstation (not the servers you plan to monitor).

[Note]Note

The $ symbol represents a command line prompt, you should not be typing it.

 2.1.1. Requirements

Before you install raxmon, meet these requirements on your local workstation:

  • Install Python 2.5, 2.6, or 2.7 on your local workstation.

  • Make sure you install raxmon on your local workstation (not the server you plan to monitor). This allows you to install raxmon once to monitor many remote servers.

 2.1.2. Install raxmon

Follow these steps to install raxmon on your local workstation if you don't already have a version installed.

Upgrade raxmon if you have an earlier version installed. Version 0.4.6 or higher is required. See Section 2.1.3, “Upgrade Raxmon” for details.

 

To install raxmon:

  1. Log into a bash shell on your local workstation.

    If you don't use a virtual environment, log into a shell as the user who has write permissions to /usr/local/bin on your local machine.

  2. Install pip.

    To install the rackspace-monitoring-cli package, you need the python pip command.  If you don’t already have access to that tool, enter these commands:

    $ sudo yum install -y python-setuptools  
    $ sudo easy_install pip  
  3. Install raxmon.

    Enter this command to install raxmon:

    $ sudo pip install rackspace-monitoring-cli  

 2.1.3. Upgrade Raxmon

Upgrade raxmon on your local workstation if you have an earlier version installed. Version 0.4.6 or higher is required.

 

To upgrade to a new version of raxmon:

  1. Remove raxmon.

    Remove the previous version of raxmon before running the upgrade:

    $ sudo pip uninstall rackspace-monitoring-cli  
  2. Upgrade to the latest version.

    Enter this command:

    $ sudo pip install --upgrade rackspace-monitoring-cli  

 2.1.4. Configure raxmon

Configure raxmon with your credentials and URLs for Cloud Monitoring and Rackspace Cloud Identity Service.

 

To configure raxmon:

Although you can specify your Rackspace credentials and URLs as command-line options, it saves time to add them to the raxmon configuration file.

  1. Locate your API key.

    Follow these instructions to find your API key if you do not already have it: Section 1.5.2, “Obtaining an API Key”.

  2. Edit the .raxrc file.

    Use vi or your favorite text editor to edit the .raxrc file in your home directory. You need to supply both your Rackspace username and API key.

    $  vi ~/.raxrc  

    Be sure to specify the correct identity endpoint for your account location. See Section 1.5.1, “Identity Endpoints” for details. Here is an example of the .raxrc file with the Rackspace credentials and URLs:

    [credentials]
    username=MyRackspaceAcct
    api_key=0000000000000000000
    
    [api]
    url=https://monitoring.api.rackspacecloud.com/v1.0
    
    [auth_api]
    url=https://identity.api.rackspacecloud.com/v2.0
    
    [ssl]
    verify=true

 2.2. Install and Configure the Monitoring Agent

Use of the agent is optional. If you choose to use the agent, you must install it on each server that you want to monitor.

Package Manager installation is supported for these environments:

  • Ubuntu or Debian

  • Red Hat, Fedora, or Centos

For more information about the agent, see Section 1.2, “How the Monitoring Agent Works”. For information about the agent endpoints, including attributes and code samples, see Agents in the Rackspace Cloud Monitoring Developer Guide.

For information about installing the agent from source, see https://github.com/racker/virgo.

 2.2.1. Install on Ubuntu or Debian

This section tells you how to install the agent on a server running Ubuntu or Debian.

These steps have been tested on Ubuntu Lucid 10.04, but should work on most recent versions of Ubuntu or Debian.

 

To install the agent on the Ubuntu environment:

  1. Add the repository for the agent.

    Create a text file named rackspace-monitoring-agent.list in the /etc/apt/sources.list.d directory.

    Add the following content to the rackspace-monitoring-agent.list file:

    deb <repo-name> cloudmonitoring main

    where repo-name is one of the following available packages:

    • http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-10.04-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-11.04-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-11.10-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-12.04-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-12.10-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-13.04-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/debian-squeeze-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/debian-wheezy-x86_64

    For example, to install Ubuntu, version 10.04, your file would contain this content:

    deb http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-10.04-x86_64 cloudmonitoring main
  2. Add a signing key for the apt repository.

    $ curl https://monitoring.api.rackspacecloud.com/pki/agent/linux.asc | sudo apt-key add -
  3. Update your apt-get program to recognize the new repository.

    $ sudo apt-get update
  4. Install the agent.

    $ sudo apt-get install rackspace-monitoring-agent

 2.2.2. Install on Red Hat/Fedora/Centos

This section tells you how to install the agent on a server running a Red Hat, Fedora or Centos environment.

 

To install the agent on Red Hat, Fedora, or Centos:

  1. Enable the signing key.

    $ curl https://monitoring.api.rackspacecloud.com/pki/agent/<signing-key> > /tmp/signing-key.asc 
    $ sudo rpm --import /tmp/signing-key.asc 

    where <signing-key> is the correct signing key for your operating system:

    Operating System Signing Key
    redhat-5-x86_64 redhat-5.asc
    redhat-6-x86_64 linux.asc
    fedora-16-x86_6 linux.asc
    fedora-17-x86_64 linux.asc
    fedora-18-x86_64 linux.asc
    fedora-19-x86_64 linux.asc
    centos-5-x86_64 centos-5.asc
    centos-6-x86_64 linux.asc

    For example, on Redhat version 5, you enter:

    $ curl https://monitoring.api.rackspacecloud.com/pki/agent/redhat-5.asc > /tmp/signing-key.asc 
    $ sudo rpm --import /tmp/signing-key.asc 
  2. Set up the yum repository.

    Create a text file named rackspace-cloud-monitoring.repo in the /etc/yum.repos.d directory.

    Add the following content to the rackspace-cloud-monitoring file:

    [rackspace]
    name=Rackspace Monitoring
    baseurl=<repo-name>
    enabled=1

    where <repo-name> is one of the following available packages:

    • http://stable.packages.cloudmonitoring.rackspace.com/redhat-5-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/redhat-6-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/fedora-16-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/fedora-17-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/fedora-18-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/fedora-19-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/centos-5-x86_64

    • http://stable.packages.cloudmonitoring.rackspace.com/centos-6-x86_64

    For example, to install Redhat, version 6, your file would contain this content:

    [rackspace]
    name=Rackspace Monitoring
    baseurl=http://stable.packages.cloudmonitoring.rackspace.com/redhat-6-x86_64/
    enabled=1
  3. Install the agent packages.

    $ sudo yum update
    $ sudo yum install rackspace-monitoring-agent

 2.2.3. Set Up the Agent

The agent Setup program provides the easiest way to get started with the agent. Setup takes care of these configuration tasks for you:

  • Configures an agent token that the agent uses to authenticate with Cloud Monitoring.

  • Creates an agent configuration file for you.

  • Verifies connectivity to the Rackspace datacenters.

  • Associates the agent with a monitoring entity.

You can also manually edit the agent configuration file. See Section 2.3, “Manual Agent Configuration” for details.

 

To run the agent Setup program:

  1. Before you start, make sure you have your Rackspace username and API key. If not, see: Section 1.5.2, “Obtaining an API Key”.

  2. Log in as the root user on the server where you installed the agent package.

  3. Enter this command to run Setup:

    $ sudo rackspace-monitoring-agent --setup

    A list of Setup Settings appears, which includes the agent ID. The agent ID matches the hostname of the server.

  4. Respond to the prompts and supply your Rackspace username and API key.

  5. Specify an agent token to use when authenticating the agent with Cloud Monitoring. You have these options:

    • Select an existing agent token from the list — Setup lists the tokens that have been created under your account. You can use the same token for multiple agents, or select the option to create a new one for use on this server.

    • Create a New Token — Setup creates a token and uses it to authenticate the agent with the Cloud Monitoring endpoints.

    You should see the message: Agent successfully connected!

  6. Associate the agent with the monitoring entity for this server. You have these options:

    1. <hostname> — Setup creates an entity for the server where you installed the agent. Select this option unless you have other requirements.

    2. Create a new entity for this server — Select this option to create a new entity with an alternate label.

    3. Do not associate the agent with an entity— Select this option to associate the agent with an entity at a later time.

    Make note of the entity ID, which you'll use when you create checks to monitor the health of your server. See Section 2.2.5, “First Steps with the Agent”.

You're now ready to run the agent.

 2.2.4. Run the Agent

After you perform the configuration and set-up tasks, you're ready to start the agent.

 

To start the agent:

  • Enter this command:

    $ sudo service rackspace-monitoring-agent start 

The rackspace-monitoring-agent command lets you manage the agent. Enter the following command to see the available options:

$ rackspace-monitoring-agent --help 

 2.2.5. First Steps with the Agent

After you start the agent, you can schedule some agent checks.

 

To create an entity and agent checks:

  1. Install raxmon on your local workstation.

    If you have not installed raxmon yet, do that now. See Section 2.1, “Install and Configure raxmon” .

    If you prefer to use the API, instead of the raxmon CLI, see Entities and Checks in the Rackspace Cloud Monitoring Developer Guide.

  2. Create some Monitoring checks.

    Now you can create some monitoring checks for the agent to run.

    $ raxmon-checks-create --entity-id=<entityId> --type=agent.memory --period=30 --label=mem 
    $ raxmon-checks-create --entity-id=<entityId> --type=agent.cpu --period=30 --label=cpu  
    $ raxmon-checks-create --entity-id=<entityId> --type=agent.filesystem --period=30 --label=root --details="target=/"

    Where <entityId> is the ID for the entity you associated with the agent.

    These commands create three monitoring checks. The --type values of agent.memory, agent.cpu, and agent.filesystem are agent check types, which means the checks will run local to the system being monitored.

 2.3. Manual Agent Configuration

[Note]Note

Using the Setup program is the preferred way to set up the agent. This section is provided as an alternate method of setting up the agent. If you used the Setup program to complete the agent configuration, skip this section.

 

To manually set up the agent:

  1. Install raxmon.

    If you have not installed raxmon yet, do that now. See Section 2.1, “Install and Configure raxmon” .

    If you prefer to use the API, instead of the raxmon CLI, see Entities and Agent Tokens in the Rackspace Cloud Monitoring Developer Guide.

  2. Create an entity in the Monitoring service:

    $ raxmon-entities-create --label=<entityLabel>   

    Where <entityLabel> is a name for the new entity. This entity represents the server where you're installing the agent. Suppose the server is named employee-news, you might use that hostname as the <entityLabel>.

    This command returns an entity ID for the new entity. For example, ent12345. You need to supply this entity ID for <entityId> in the next several steps.

  3. Assign an ID to your agent.

    You need to assign an ID to your agent and associate it with the server entity you just created. Cloud Monitoring uses this ID for two-way communication between the agent and the Cloud Monitoring endpoint.

    $ raxmon-entities-update --id=<entityId> --agent-id=<agentId>

    Where:

    <entityId>

    is the entity ID returned in the previous step.

    <agentId>

    is the ID, or name, you want to assign to the agent installed on the server. For the ID value, use any label that makes sense for the system that you plan to monitor. For example, you can use the server hostname, although the ID does not need to match or contain any part of the entity label or the entityId.

  4. Create an agent token.

    The agent uses an agent token to authenticate with the Cloud Monitoring endpoint. The token ensures that no one masquerades as your server. Enter this command to create the token:

    $ raxmon-agent-tokens-create --label="<agent-token-label>"   

    where <agent-token-label> is a name for your agent token. You can use any name you like.

  5. List the tokens.

    Enter this command to see a list of tokens, including the one you just created.

    $ raxmon-agent-tokens-list

    Make a note of the agent token value to use in the next few steps.

  6. Log in as the root user on the server where you installed the agent.

  7. Use vi or your favorite text editor to edit the file or create it if it does not exist.

    $ sudo vi /etc/rackspace-monitoring-agent.cfg  
  8. Add this content to the rackspace-monitoring-agent.cfg file:

    monitoring_id <agentId>
    monitoring_token <agentToken>
    

    Where:

    <agentId>

    is the agent ID you assigned to the agent in Step 3.

    <agentToken>

    is the token value returned for your agent token by the raxmon-agent-tokens-list command.

You're now ready to start the agent. See Section 2.2.4, “Run the Agent”.

 2.4. Uninstalling the Agent

Use the standard method for your operating system to uninstall the agent.

On Debian/Ubuntu systems, run:

$ sudo apt-get remove rackspace-monitoring-agent

On CentOS/Red Hat/Fedora, run:

$ sudo rpm -e rackspace-monitoring-agent