Getting Started with NYMMS

This tutorial will walk you through installing and configuring NYMMS. If you’d quickly like to start a NYMMS system to play with yourself, please see the Demo AMI documentation.

This tutorial assumes basic understanding of Amazon Web Services. You will either need to understand how to launch an instance with an instance profile with the appropriate permissions (see below) or you will need the Access Key ID and Secret Access Key for a user with the appropriate permissions.

Installing NYMMS

On Ubuntu

I maintain a set of packages for installing NYMMS on your Ubuntu Precise system. In order to install these you first need to add my PPA & key to your sources. You can find the directions to do so here.

Once you’ve done that, you can use apt to download the packages:

apt-get install python-nymms
apt-get install nymms-common
apt-get install nymms-reactor nymms-probe nymms-scheduler

The first package is the python code that makes up NYMMS. The second package is some common configuration used by Ubuntu for running the NYMMS daemons. The last three packages are mainly startup scripts for starting NYMMS via Ubuntu’s Upstart system.

Once those packages are installed you only need to provide NYMMS with the correct AWS permissions in order to access the various services it makes use of. See Permissions below.

Note

If you decide to provide the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables for a user, you can store them in /etc/default/nymms-common. Be sure to restart each of the daemons after doing so.

These packages will include a basic config as well as a few example nodes, monitors and handlers to give an example of how the system runs. You can control the stopping/starting of all the daemons with various upstart commands - there is one upstart script per daemon. For example to restart all three daemons you would call:

restart nymms-reactor
restart nymms-probe
restart nymms-scheduler

Using PIP

Since NYMMS is written in python I’ve also published it to PyPI. You can install it with pip by running:

pip install nymms

Warning

The python library does not come with startup scripts, though it does install the three daemon scripts in system directories. You should work on your own startup scripts for the OS you are using.

Installing From Source

You can also install from the latest source repo:

git clone https://github.com/cloudtools/nymms.git
cd nymms
python setup.py install

Warning

The python library does not come with startup scripts, though it does install the three daemon scripts in system directories. You should work on your own startup scripts for the OS you are using.

Using Virtual Environments

Another common way to install NYMMS is to use a virtualenv which provides isolated environments. This is also useful if you want to play with NYMMS but do not want to (or do not have the permissions to) install it as root. First install the virtualenv Python package:

pip install virtualenv

Next you’ll need to create a virtual environment to work in with the newly installed virtualenv command and specifying a directory where you want the virtualenv to be created:

mkdir ~/.virtualenvs
virtualenv ~/.virtualenvs/nymms

Now you need to activate the virtual environment:

source ~/.virtualenvs/nymms/bin/activate

Now you can use either the instructions in Using PIP or Installing From Source above.

When you are finished using NYMMS you can deactivate your virtual environment with:

deactivate

Note

The deactivate command just unloads the virtualenv from that session. The virtualenv still exists in the location you created it and can be re-activated by running the activate command once more.

Permissions

NYMMS makes use of many of the Amazon Web Services. In order for the daemons to use these services they have to be given access to them. Since NYMMS is written in python, we make heavy use of the boto library. Because of that we fall back on boto’s way of dealing with credentials.

If you are running NYMMS on an EC2 instance the preferred way to provide access is to use an instance profile. If that is not possible (you do not run on EC2, or you don’t understand how to setup the instance profile, etc) then the next best way of providing the credentials is by createing an IAM user with only the permissions necessary to run NYMMS. You would then need to get that user’s Access Key ID & Secret Key and provide them as the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Whichever method you choose, you’ll need to provide the following permission document (for either the user, or the role):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "ses:GetSendQuota",
        "ses:SendEmail"
      ],
      "Sid": "NymmsSESAccess",
      "Resource": [
        "*"
      ],
      "Effect": "Allow"
    },
    {
      "Action": [
        "sns:ConfirmSubscription",
        "sns:CreateTopic",
        "sns:DeleteTopic",
        "sns:GetTopicAttributes",
        "sns:ListSubscriptions",
        "sns:ListSubscriptionsByTopic",
        "sns:ListTopics",
        "sns:Publish",
        "sns:SetTopicAttributes",
        "sns:Subscribe",
        "sns:Unsubscribe"
      ],
      "Sid": "NymmsSNSAccess",
      "Resource": [
        "*"
      ],
      "Effect": "Allow"
    },
    {
      "Action": [
        "sqs:ChangeMessageVisibility",
        "sqs:CreateQueue",
        "sqs:DeleteMessage",
        "sqs:DeleteQueue",
        "sqs:GetQueueAttributes",
        "sqs:GetQueueUrl",
        "sqs:ListQueues",
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:SetQueueAttributes"
      ],
      "Sid": "NymmsSQSAccess",
      "Resource": [
        "*",
      ],
      "Effect": "Allow"
    },
    {
      "Action": [
        "sdb:*"
      ],
      "Sid": "NymmsSDBAccess",
      "Resource": [
        "*"
      ],
      "Effect": "Allow"
    }
  ]
}

Note

If you want to provide even tighter permissions, you can limit the SNS, SDB and SQS stanzas to specific resources. You should provide the ARNs for each of the resources necessary.

Configuration

Please see the configuration page for information on how to configure NYMMS. Usually the configuration files are located in /etc/nymms/config but that is not a requirement and all of the daemons accept the --config argument to point them at a new config file.