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)
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:
RedHat Enterprise Linux
And on the following kinds of cloud:
Amazon Web Services (AWS)
Rackspace Cloud Servers
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
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.
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
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:
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.
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
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:
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.
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
/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
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, ...)