Help

How Scout Works

• How does the Scout Client execute plugins?
• Scout retrieves plugins via HTTP. What happens if the resource is no longer available?
• What happens if a new version of a plugin is released?
• How does Scout approach security?
• Is Scout open source?

Using Cron

• How do I setup Scout to run using cron?
• How do I setup Scout to run using the system-wide crontab file?
• How do I setup Scout to run using my current user's crontab file?
• Scout doesn't run in cron. I'm seeing a "Permission denied" error.
• Scout doesn't run in cron. I'm seeing a "ruby: command not found" error.
• How do I setup my crontab in Solaris to run every X minutes?
• I'm still having problems running Scout through cron.

Using Launchd

• How do I setup Scout to run using launchd?
• Scout doesn't run in launchd. I'm not seeing any errors.

Installing the Client

• I'm stuck. How do I get help?

Inserting Report Data Into Scout

• Can I associate report data with an arbitrary time?
• Scout isn't graphing fields it should be (or vice versa). Does report data need to fit a certain format?

How does the Scout Client execute plugins?

The Scout Client retrieves the plugin plan at an interval you define via Cron (or some other method to schedule a regularly occurring job). The plugin plan includes the plugin code plus any plugin-specific options you've set. The client then executes the code, with the provided options, and reports back the results to Scout.

Plugins are not manually installed on the client. You configure all plugins in the Scout web interface. Once the Scout Client is installed, you're done!

Scout retrieves plugins via HTTP. What happens if the resource is no longer available?

Scout caches the plugin code upon installation, so you'll be able to execute the plugin code whether or not the resource still exists.

What happens if a new version of a plugin is released?

By default, Scout only executes the plugin code available at the time the plugin was installed on a client. If a new version of a plugin is released, the plugin won't be updated with the new code. You can override this and have the client automatically grab the latest version of the plugin by checking the "Automatically Update" setting in the plugin settings. You can also do a one-time update of the plugin by clicking the "Update Code" button in the plugins settings.

How does Scout approach security?

To answer that, let’s look at the architecture of Scout first:

• You install the tiny Scout client (which is a Ruby gem) on your server.
• The client connects over https (always) through a 256-bit secure, encrypted connection (the same encryption your bank uses).
• Scout never logs in to any of your servers.
• All communication is initiated by the client.
• The client downloads a pre-loaded plugin plan, consisting only of plugins of your choosing, so it cannot run plugins you didn’t explicitly authorize.
• The server also uses that same secure encryption for all communication. Individual accounts are protected.
• Client keys (uniquely generated) can be revoked at any time, disabling the client.

The security measures needed for Scout are the same as for any other software. In fact, in some ways, it’s easier to be more secure – the plugins are relatively few lines of code and easy to review. For a more closed environment, you can create a copy of the plugin code and host it on one of your own servers (a plugin is plain text).

Is Scout open source?

The Scout client is completely open source. The gem is a normal Ruby gem, open for development, and distributed under the MIT and/or Ruby License (whichever you prefer). The Scout Plugins people write are also completely open, in fact, they are surrounded and fostered by a community that encourages branching, fixes, and general open-ness.

The Server, where you aggregate your data, do reporting, and in general, collect information about your account is not open-source. We maintain the server, and keep all your data safe and sound.

How do I setup Scout to run using cron?

You need to configure Scout to run automatically after it is installed. Cron is the easiest way to have Scout run at a scheduled interval on a Linux, Solaris or BSD system.

Cron jobs are configured using the crontab file (also called the cron table). Each user can have their own crontab file, and there is also a system-wide crontab file located here:

If you have root access, find out: "How do I setup Scout to run using the system-wide crontab file?"

If you do not have root access, find out "How do I setup Scout to run using my current user's crontab file?"

How do I setup Scout to run using the system-wide crontab file?

As the root user (or using sudo), open the crontab file for editing:

We will need to add a line to the bottom of the file with our cron job.

To run the Scout client every 15 minutes, we'll use the following format:

For example:

The above cron job runs every 15 minutes as the deploy user.

Save the file, and it will automatically run every 15 minutes.

If you are on Solaris, find out: How do I setup my crontab in Solaris to run every X minutes?

How do I setup Scout to run using my current user's crontab file?

We will need to use the crontab command to edit our current user's crontab.

Run the crontab edit command:

If you do not have any jobs already setup, you should see a blank file. If you get an error, see this Unix Crontab Reference for more help.

To run the Scout client every 15 minutes, we'll use the following format:

For example:

The above cron job runs every 15 minutes as the current user.

Save the file, and it will automatically run every 15 minutes.

Scout doesn't run in cron. I'm seeing a "Permission denied" error.

Scout probably doesn't have access to the data file it needs to store information locally. You may be scheduling the job to run as a different user than the one you installed Scout with, and that user may not be able to write to the data file.

You can get around this by specifying a path to a data file (doesn't matter if it exists yet) that the user in the cron job has access to using the "-d option":

Scout doesn't run in cron. I'm seeing a "ruby: command not found" error.

Scout can't find the Ruby executer. Your cron path may not contain the full path to Ruby. Be sure to update your PATH in /etc/crontab if you have installed Ruby in an alternate location. For example, if Ruby is installed in "/usr/local/bin", your PATH line my look like:

How do I setup my crontab in Solaris to run every X minutes?

Solaris uses a different format for specifying the interval. To run Scout every 10 minutes, use the following format:

For example:

I'm still having problems running Scout through cron.

Here are a few tips for debugging Scout in the crontab file. We can tell Scout to log to a log file:

Using the -v option tells it to be verbose. Using the -l debug option tells it to use the debugging log level. Note that this will also run every minute (using the * * * * * interval).

For more help on cron and the crontab file, see this Unix Crontab Reference.

How do I setup Scout to run using launchd?

Scout can be configured to run at a scheduled interval using launchd, or as it sometimes called, launchctl or LaunchDaemon. Launchd can be used by Mac OS X systems to run Scout regularly.

To create a LaunchDaemon, simply create a file, named com.scoutapp.ScoutClient.plist with the following properties:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>Label</key>
        <string>com.scoutapp.ScoutClient</string>
        <key>ProgramArguments</key>
        <array>
                <string>[PATH TO RUBY]</string>
                <string>[PATH TO SCOUT]</string>
                <string>[CLIENT KEY]</string>
                <string>-d [DATA FILE]</string>
        </array>
        <key>StartInterval</key>
        <integer>[INTERVAL IN SECONDS]</integer>
</dict>
</plist>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>Label</key>
        <string>com.scoutapp.ScoutClient</string>
        <key>ProgramArguments</key>
        <array>
                <string>/usr/local/bin/ruby</string>
                <string>/usr/local/bin/scout</string>
                <string>8c6dc00d-af3a-4606-a384-85f276ecbbb5</string>
                <string>-d /tmp/scout_data.yml</string>
        </array>
        <key>StartInterval</key>
        <integer>900</integer>
</dict>
</plist>

Scout doesn't run in launchd. I'm not seeing any errors.

In order to view errors produced by launchd, you'll need to visit the Console, or tail the /var/log/system.log file. Launchd logs messages and problems running the Scout Client there.

I'm stuck. How do I get help?

Contact us at support@highgroove.com. We usually respond in a couple of hours. Please provide your operating system, account name, and any error messages you received.

Can I associate report data with an arbitrary time?

Yes. If you're working with a Scout::Plugin, return the field {:scout_time => INSERT TIME} along with your existing report data. For example:

class TimeExample < Scout::Plugin
  def run
    data = { :scout_time => "12/23/1980 12:00 PM",
             :users_count => 132 }

    {:report => data} 
end

The time must be in UTC. We use Ruby's Time#parse method to parse scout_time.

Scout isn't graphing fields it should be (or vice versa). Does report data need to fit a certain format?

If a field has a nil value, it won't be graphed. Instead, return zero.