Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: e7d547bc8c
Fetching contributors…

Cannot retrieve contributors at this time

274 lines (198 sloc) 9.862 kb

PREREQUISITES

RightLink is a Ruby application that runs as a daemon. It depends on the following system components/packages, which must be installed before you can proceed with RightLink installation.

  • Ruby >= 1.8.7 p334 or better – older versions have GC issues!

  • RubyGems >= 1.3.7

  • C/C++ toolchain (needed to install various gems)

Several auxiliary packages are recommended in order to obtain full RightLink functionality at runtime:

  • git and Subversion clients (facilitates Chef recipe development)

  • curl (for download of RightScript attachments)

  • dig, sed and perl (used by some cloud-specific config logic)

Supported Configurations

RightLink is regularly tested on the following Linux distributions:

  • CentOS - 5.4, 5.6

  • Ubuntu - 8.04, 10.04, 10.10, 11.04

It has been known to work on the following with little or no modification:

  • Debian

  • RedHat Enterprise Linux

  • SuSE Linux

And on the following kinds of cloud:

  • Amazon Web Services (AWS)

  • Rackspace Cloud Servers

  • Eucalyptus

  • CloudStack

Although RightLink is Windows-compatible and is regularly released for Windows variants, installation and configuration are not yet covered in this document. For information on the RightLink Windows MSI, see the documentation page on our support wiki

CentOS Systems

Install the C toolchain and related libraries, plus some additional libs required for RightLink,

yum install -y gcc-c++ patch readline readline-devel zlib zlib-devel libyaml-devel libffi-devel openssl-devel make bzip2 iconv-devel libarchive-devel

CentOS does not have a suitable prepackaged Ruby. To run RightLink, you can install RVM and use it to satisfy the Ruby dependency.

Ubuntu Systems

Install the C toolchain and related libraries, plus some additional libs required for RightLink.

apt-get update
# may need libreadline5 (not 6), on older systems. Ditto with libreadline5-dev
apt-get install -y build-essential gcc g++ bison openssl libreadline6 zlib1g vim autoconf libxml2 libffi
apt-get install -y libssl-dev libarchive-dev libreadline-dev zlib1g-dev libyaml-dev libffi-dev libxml2-dev
apt-get install -y git-core perl sed curl dnsutils

System Ruby (Optional)

On Ubuntu, you have the choice of using RVM (see instructions below) or installing a system Ruby interpreter. RVM is recommended, but it is possible to run against the system Ruby interpreter provided it's recent enough.

On Ubuntu < 10.04.3, it is necessary to fetch the newer packages from an Ubuntu mirror. You can download them from EasyNews (as in the example below), or get them from a mirror close to you

apt-get install -y ruby1.8 ">=1.8.7"
apt-get install -y ruby1.8-dev g++ libreadline-ruby1.8 rubygems1.8 irb1.8 rdoc1.8

wget http://mirrors.easynews.com/linux/ubuntu//pool/universe/libg/libgems-ruby/rubygems1.8_1.3.7-2_all.deb
dpkg -i rubygems1.8_1.3.7-2.deb
apt-get -f install

All Linux Systems

Ruby Version Manager (RVM) is a set of shell scripts that allows you to build and install multiple Ruby interpreters side by side.

NOTE - If you create init scripts for RightLink, they should source rvm.sh and “rvm use” the appropriate Ruby before invoking any RightLink commands.

bash < <(curl -sk https://rvm.beginrescueend.com/install/rvm)
source /etc/profile.d/rvm.sh

rvm install ruby-1.8.7-p352

rvm use ruby-1.8.7-p352

PRE-INSTALL CUSTOMIZATIOn

Feature Control Customization

Before installing RightLink (either as a package or from sources), you can selectively disable certain features that may not be compatible with your deployment environment.

Feature control is accomplished by creating a special YAML file prior to installing the package or running any RightLink init script or program logic. The YAML file contains some boolean flags that affect the behavior of the init scripts and the agent at runtime.

The following features can all be disabled:

* Managed login (aka Server Login Control)
* Frozen OS package repositories
* Automatic MOTD update on state transitions

To disable one or more of these features, create the following file:

/etc/rightscale.d/right_link/features.yml

And populate the file thusly, supplying true/false for each feature as appropriate.

motd:
  update: false
package_repositories:
  freeze: false
managed_login:
  enable: false

All features are assumed to be enabled by default unless this file exists and the associated feature is marked as disabled. Therefore, you can omit sections for features that should remain enabled.

INSTALLATION

One-Time Setup

If you are packaging RightLink, run these commands as a post-install step for your package. If you are bundling a cloud image, run these commands before bundling.

Fetch RightLink Source

mkdir -p /opt/rightscale
cd /opt/rightscale
git clone git://github.com/rightscale/right_link.git

  Clone the RightLink source repository from GitHub. By cloning it into /opt/rightscale, you will be able to run RightLink directly out of the source repository with no intermediate packaging or install steps.

Run Setup Script

cd right_link
bin/setup.sh

The source distribution contains setup.sh, which installs some necessary RubyGems and also copies some RightLink command-line tools into suitable system directories so they can be invoked by users and scripts.

On Unix systems, CLI tools are created in /usr/bin. By convention, they begin with the prefix “rs_” e.g. rs_tag or rs_run_recipe.

INTEGRATING WITH THE SYSTEM

Multi-Cloud Support

export RS_CLOUD=ec2 # or another cloud type, see below...
mkdir -p /etc/rightscale.d
echo "$RS_CLOUD" > /etc/rightscale.d/cloud

RightLink supports many virtualization engines, cloud APIs and other facets of cloud technology. Due to lack of standardization, there is no reliable way for RightLink to auto-detect the cloud type in which it is running.

We have taken the pragmatic approach and require the user to give RightLink a hint about its runtime environment. RightLink must know its cloud type in order to retrieve launch settings and runtime metadata that are crucial to successful operation.

In the commands below, we refer to an environment variable RS_CLOUD. You should set RS_CLOUD to the cloud type under which RightLink is running, before running any of the commands below. RS_CLOUD is your “hint” to RightLink.

RightLink knows about the following values of RS_CLOUD:

  • ec2

  • rackspace

  • eucalyptus

  • cloudstack

  • openstack

On-Boot Commands

Under Linux these are accomplished with init scripts, optionally using monit for robustness. Under Windows, a system service spawns the agent process and monitors its health.

CAUTION: if your instance is attached to the RightScale dashboard, running the commands below will cause it to begin running boot scripts! This is not harmful, but if your intent is to bundle a “pristine” image, you probably want to put the following commands into an init script and test by bundling and relaunching.

#The commands below use relative paths for readability
cd /opt/rightscale

 

# Fetch metadata from cloud and make it available in the shell environment
bin/cloud --name $RS_CLOUD --action bootstrap > /dev/null
. /var/spool/cloud/user-data.sh

 

Determine Boot State

# TODO - check_for_rightscale

# TODO - rightboot init script (detect reboot & tweak state)

# TODO - check_boot_state, update_boot_state 

Run Fix-It Tasks

# TODO - UNDOCUMENTED - bin/system --action ssh
# TODO - UNDOCUMENTED - bin/system --action hostname
# TODO - UNDOCUMENTED - bin/system --action proxy

Configure RightLink Agent

 

bin/enroll --root-dir /opt/rightscale/right_link --url $RS_RN_URL --host $RS_RN_HOST --id $RS_RN_ID --token $RS_RN_AUTH
bin/deploy

 

Launch RightLink Agent

# Start the RightLink agent
bin/rnac --start instance

# Start the agent watchdog process
bin/rchk --start

At this point, your instance should be booting and sending audit entries back to the RightScale dashboard. Navigate to this server and verify that it's booting cleanly.

On-Shutdown Commands

When the system is terminating, you should allow RightLink to run its decommission scripts.

#The commands below use relative paths for readability
cd /opt/rightscale

 

bin/rnac --decommission

Filesystem Locations

Linux Systems

/etc/rightscale.d               | Static configuration, incl. "hints" for init scripts
/etc/rightscale.d/right_link    | Static files that customize RightLink behavior
/var/spool/cloud                | Cloud-provided metadata & user-data
/var/lib/rightscale/right_agent | Persistent config files generated at startup
/var/lib/rightscale/right_link  | Persistent RightLink agent state
/var/run                        | Transient agent state, e.g. pid files
/var/cache                      | Cookbooks, attachments, temp files
/usr/bin                        | Public CLI: rs_tag, rs_debug, ...
/opt/rightscale/bin             | Private CLI: rnac, rad, cook, ...
/opt/rightscale/sandbox         | Private sandbox (Ruby, RubyGems, monit, ...)
/opt/rightscale/right_link      | Application logic & support files

Windows Systems

Data files – paths are relative to %COMMON_APPDATA%RightScale

rightscale.d            | Static "hints" for system services
spool\cloud             | Cloud-provided metadata & user-data (.sh, .rb, raw formats)
RightAgent              | Persistent config files generated at startup
right_link              | Persistent RightLink agent state
cache                   | Cookbooks, attachments, temp files

Program logic – paths are relative to %ProgramFiles(x86)%

RightScale\RightLink    | Application logic & support files
RightScale\sandbox      | Private sandbox (Ruby, RubyGems, monit, ...)
Jump to Line
Something went wrong with that request. Please try again.